- Status: Accepted
- Date: 2026-11-13
Context
QuantLayer needs a production-oriented identity layer: identifiers, wallet association, versioned classical and post-quantum public keys, rotation, revocation, recovery and status management, with no private keys server-side and strong replay protection.
Decision
- Identifier —
did:quantlayer.did:quantlayer:<base32(SHA-256("QUANTLAYER-DID-V1\n" ‖ canonical(inception))[0..20])>where inception = initial public key, algorithm and the creation challenge nonce. Self-certifying: it cannot be claimed without the key and is re-derivable by anyone. - Keys. Each verification method is a key ring (
@quantlayer-protocol/crypto): versions are appended on rotation, never deleted. Retired versions verify historic signatures; revoked versions verify nothing. Rotation may change algorithm (crypto agility, e.g. Ed25519 → ML-DSA-65) but not purposes. Exact public-key lengths are enforced for every algorithm. - Controllers. An identity is controlled by its active authentication keys and its actively linked accounts (wallets).
- Authorization statements. Every state change is authorised by a signed
statement
{audience, action, subject, nonce, issuedAt, expiresAt, payload}bound to a single-use, ≤15-minute server challenge.- QuantLayer keys sign
"QUANTLAYER-SIG-V1:identity-authorization\n" ‖ canonical(statement). - Wallets sign EIP-712
IdentityAuthorizationwith domain{name: "QuantLayer Identity", version: "1", chainId}andpayloadHash = keccak256(canonical(payload)). - Payloads are built by shared functions (
authorizationPayloads) used by clients and the service alike.
- QuantLayer keys sign
- Order of checks: challenge scope → expiry → all signatures (controller,
proof of possession, wallet) → atomic nonce consumption → domain rules →
optimistic persistence. Bad signatures never burn a challenge; a replay
always yields
REPLAY_DETECTED. - Proof of possession is required for every new signing key (creation, registration, rotation, recovery). KEM/key-agreement keys cannot sign and are authorised by a controller only.
- Accounts are CAIP-10 ids, unique across identities (repository-enforced), linked only with a signature from the account over the same statement.
- Recovery is m-of-n guardians (identities or accounts) with a time-lock and request expiry; the first policy applies immediately, later changes wait out the current delay; completion revokes all authentication keys and unlinks all accounts, then installs the new key.
- Status.
pending → active ⇄ suspended → deactivated; suspend/reinstate are operator actions (authorised at the API layer), deactivation is a controller action. Key revocation remains possible while suspended.
Consequences
- The domain remains pure;
IdentityServicecomposes it with ports (IdentityRepository,ChallengeStore,SignatureVerifier,AccountOwnershipVerifier,HashFunction,RandomSource). - Production adapters must honour the port contracts, demonstrated by the
in-memory references in
@quantlayer-protocol/identity/testing: atomic challenge consumption and atomic account uniqueness. - The identity wire format moved to
quantlayer.identityv2 with a v1 migration. - See
docs/security/IDENTITY_SECURITY.mdfor the threat analysis.