mirror of
https://github.com/hanzoai/iam.git
synced 2026-11-19 18:37:16 +00:00
A deployment that names a registry, a chain, an RPC and a KMS-mounted controller key gets the account's DID written on chain when a wallet is linked: the document if the registry does not hold one, a service entry naming the issuer that asserts the identity and the subject at it, and the wallet as a verification method. A deployment that names none links wallets and mints the same `did` claim, because the claim is derived from the subject and owes the registry nothing. Anchoring publishes the fact; it does not create it. THE STORE IS THE SOURCE OF TRUTH, the registry is a projection. Every write happens after the link commits and outside its transaction, so a chain that is slow, forked or gone cannot fail a sign-in or leave a wallet half-linked. The cost is that a failed anchor is not retried: the document catches up the next time that person links a wallet. Convergence, if a deployment wants it, reconciles from the store — which holds every binding — rather than making a login wait on a block. Only a NEW binding is anchored, which is why verify now returns the wallet it bound rather than only the user. Signing in with a wallet already on file changes nothing, and asking "is there a row" afterwards cannot tell the two apart because the row is there either way; a flag would have answered, but the wallet also carries the CANONICAL address the verifier settled on instead of the spelling the client claimed. Four settings, all of them or none — a half-named registry is a mistake, not a choice, so it is refused rather than degrading into the off state with an operator left wondering why nothing is written. There is deliberately no default contract address: the one recorded for this contract in lux/standard holds no code on any live Lux chain and names an AMM router on another, so a default would have pointed every deployment at it. The key is a FILE, never an inline value, because the estate has one secret path — KMS -> KMSSecret -> Secret -> mounted material, the same path the registry signing key and provision's credentials already read. A key in the environment is a plaintext secret in a pod spec. Two things worth stating plainly rather than discovering in production. The contract splits its authority — createDIDFor is registrar-only while addVerificationMethod and addService are controller-only — so one key can do all three only by creating documents controlled by itself, and these documents are therefore not self-sovereign. Handing control to the person ends IAM's ability to keep the document in step, and no registrar override gets it back. And only EVM wallets become verification methods: the registry's struct types an account as an `address` plus a bytes32, which fits a secp256k1 account and nothing else. Other chains link normally, appear in the claim and count as a credential; packing a base58 address into an `address` field would be inventing an encoding no resolver reads. Selectors are derived from the canonical signature strings at init, never pasted. A four-byte constant is a value nobody can check by reading it, and a transposed digit still encodes, still sends, and reverts on chain as an unknown method — which looks exactly like a permissions failure. The registry is also asked once for its OWN method string and refuses to write if it disagrees with ours, because documents registered under a name no token's claim matches are worse than no documents. Co-authored-by: Hanzo Dev <[email protected]>
173 lines
6.5 KiB
Go
173 lines
6.5 KiB
Go
// Copyright 2026 Hanzo AI, Inc.
|
|
// SPDX-License-Identifier: MIT OR Apache-2.0
|
|
|
|
package did
|
|
|
|
import (
|
|
"math/big"
|
|
|
|
luxcrypto "github.com/luxfi/crypto"
|
|
"github.com/luxfi/crypto/common"
|
|
)
|
|
|
|
// Solidity call encoding for the four DIDRegistry methods this package uses.
|
|
//
|
|
// Hand-written, and small enough to read in one sitting, because the alternative
|
|
// is a generated binding — which would pull an EVM client library into a service
|
|
// whose job is issuing tokens. Four calls, three of which take one string and one
|
|
// struct, do not pay for that.
|
|
//
|
|
// SELECTORS ARE DERIVED, NEVER PASTED. Each is keccak256 of the canonical
|
|
// signature string below, computed at init. A pasted four-byte constant is a
|
|
// value nobody can check by reading it: transpose two hex digits and the call
|
|
// still encodes, still sends, and reverts on chain as an unknown method — which
|
|
// looks exactly like a permissions failure. The signature string is the thing a
|
|
// reader can compare against the .sol file.
|
|
|
|
// The canonical signatures, verbatim from contracts/identity/DIDRegistry.sol.
|
|
// A tuple argument is spelled by its component types in declaration order, which
|
|
// is what Solidity hashes: VerificationMethod is
|
|
// (bytes32 id, uint8 methodType, address controller, bytes publicKeyMultibase,
|
|
// bytes32 blockchainAccountId) and Service is
|
|
// (bytes32 id, uint8 serviceType, string endpoint, bytes data).
|
|
const (
|
|
sigCreateDIDFor = "createDIDFor(string,address)"
|
|
sigAddVerification = "addVerificationMethod(string,(bytes32,uint8,address,bytes,bytes32))"
|
|
sigAddService = "addService(string,(bytes32,uint8,string,bytes))"
|
|
sigDIDExists = "didExists(string)"
|
|
sigMethod = "method()"
|
|
wordLen = 32
|
|
verificationFieldCount = 5
|
|
serviceFieldCount = 4
|
|
)
|
|
|
|
// selector is the four-byte function selector of a canonical signature.
|
|
func selector(sig string) []byte { return luxcrypto.Keccak256([]byte(sig))[:4] }
|
|
|
|
// createDIDFor encodes createDIDFor(identifier, controller). The identifier is
|
|
// the method-specific-id — the registry concatenates "did:<method>:" onto it
|
|
// itself, so the FULL DID must not be passed here.
|
|
func createDIDFor(identifier string, controller common.Address) []byte {
|
|
out := selector(sigCreateDIDFor)
|
|
// Head: two words — the offset to the string tail, then the address.
|
|
out = append(out, word(big.NewInt(2*wordLen))...)
|
|
out = append(out, addressWord(controller)...)
|
|
return append(out, bytesTail([]byte(identifier))...)
|
|
}
|
|
|
|
// addVerificationMethod encodes addVerificationMethod(did, method). did is the
|
|
// FULL "did:lux:…" string, because the registry keys every document by
|
|
// keccak256 of it.
|
|
func addVerificationMethod(did string, m verification) []byte {
|
|
tuple := m.encode()
|
|
out := selector(sigAddVerification)
|
|
// Head: offset to the did string, then offset to the tuple. Both arguments
|
|
// are dynamic (the tuple contains `bytes`), so both are references.
|
|
out = append(out, word(big.NewInt(2*wordLen))...)
|
|
didTail := bytesTail([]byte(did))
|
|
out = append(out, word(big.NewInt(int64(2*wordLen+len(didTail))))...)
|
|
out = append(out, didTail...)
|
|
return append(out, tuple...)
|
|
}
|
|
|
|
// addService encodes addService(did, service).
|
|
func addService(did string, s service) []byte {
|
|
tuple := s.encode()
|
|
out := selector(sigAddService)
|
|
out = append(out, word(big.NewInt(2*wordLen))...)
|
|
didTail := bytesTail([]byte(did))
|
|
out = append(out, word(big.NewInt(int64(2*wordLen+len(didTail))))...)
|
|
out = append(out, didTail...)
|
|
return append(out, tuple...)
|
|
}
|
|
|
|
// didExists encodes the view call that reports whether a document is already
|
|
// registered. It is what keeps a re-link from re-creating a DID the registry
|
|
// would revert on.
|
|
func didExists(did string) []byte {
|
|
out := selector(sigDIDExists)
|
|
out = append(out, word(big.NewInt(wordLen))...)
|
|
return append(out, bytesTail([]byte(did))...)
|
|
}
|
|
|
|
// registryMethod encodes the view call returning the registry's OWN method
|
|
// string. See Registry.check for why it is asked.
|
|
func registryMethod() []byte { return selector(sigMethod) }
|
|
|
|
// verification is the VerificationMethod struct the registry stores.
|
|
type verification struct {
|
|
id [32]byte
|
|
methodType uint8
|
|
controller common.Address
|
|
publicKey []byte
|
|
accountHash [32]byte
|
|
}
|
|
|
|
// encode lays the struct out as a dynamic ABI tuple: four head words (the
|
|
// `bytes` field carries an offset instead of a value) followed by the bytes
|
|
// tail. Offsets inside a tuple are relative to the TUPLE's own start, not to
|
|
// the call data's.
|
|
func (v verification) encode() []byte {
|
|
out := make([]byte, 0, verificationFieldCount*wordLen+wordLen+len(v.publicKey))
|
|
out = append(out, v.id[:]...)
|
|
out = append(out, word(big.NewInt(int64(v.methodType)))...)
|
|
out = append(out, addressWord(v.controller)...)
|
|
out = append(out, word(big.NewInt(verificationFieldCount*wordLen))...)
|
|
out = append(out, v.accountHash[:]...)
|
|
return append(out, bytesTail(v.publicKey)...)
|
|
}
|
|
|
|
// service is the Service struct the registry stores.
|
|
type service struct {
|
|
id [32]byte
|
|
serviceType uint8
|
|
endpoint string
|
|
data []byte
|
|
}
|
|
|
|
// encode lays the struct out as a dynamic ABI tuple. Two of its four fields are
|
|
// dynamic, so the second offset depends on the first field's encoded length.
|
|
func (s service) encode() []byte {
|
|
endpoint := bytesTail([]byte(s.endpoint))
|
|
out := make([]byte, 0, serviceFieldCount*wordLen+len(endpoint)+wordLen+len(s.data))
|
|
out = append(out, s.id[:]...)
|
|
out = append(out, word(big.NewInt(int64(s.serviceType)))...)
|
|
out = append(out, word(big.NewInt(serviceFieldCount*wordLen))...)
|
|
out = append(out, word(big.NewInt(int64(serviceFieldCount*wordLen+len(endpoint))))...)
|
|
out = append(out, endpoint...)
|
|
return append(out, bytesTail(s.data)...)
|
|
}
|
|
|
|
// bytesTail encodes a dynamic `bytes`/`string` value: its length, then its
|
|
// content right-padded to a whole number of words.
|
|
func bytesTail(b []byte) []byte {
|
|
out := word(big.NewInt(int64(len(b))))
|
|
out = append(out, b...)
|
|
if pad := (wordLen - len(b)%wordLen) % wordLen; pad > 0 {
|
|
out = append(out, make([]byte, pad)...)
|
|
}
|
|
return out
|
|
}
|
|
|
|
// word left-pads an unsigned integer into one 32-byte ABI word.
|
|
func word(i *big.Int) []byte {
|
|
out := make([]byte, wordLen)
|
|
i.FillBytes(out)
|
|
return out
|
|
}
|
|
|
|
// addressWord left-pads a 20-byte address into one 32-byte ABI word.
|
|
func addressWord(a common.Address) []byte {
|
|
out := make([]byte, wordLen)
|
|
copy(out[wordLen-common.AddressLength:], a[:])
|
|
return out
|
|
}
|
|
|
|
// hash32 is keccak256 as a fixed array, the shape the registry's bytes32 ids
|
|
// take.
|
|
func hash32(s string) [32]byte {
|
|
var out [32]byte
|
|
copy(out[:], luxcrypto.Keccak256([]byte(s)))
|
|
return out
|
|
}
|