0010. QuantLayer Identity protocol

Design document, published from the repository at docs/adr/0010-identity-protocol.md.

  • 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

  1. 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.
  2. 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.
  3. Controllers. An identity is controlled by its active authentication keys and its actively linked accounts (wallets).
  4. 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 IdentityAuthorization with domain {name: "QuantLayer Identity", version: "1", chainId} and payloadHash = keccak256(canonical(payload)).
    • Payloads are built by shared functions (authorizationPayloads) used by clients and the service alike.
  5. 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.
  6. 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.
  7. Accounts are CAIP-10 ids, unique across identities (repository-enforced), linked only with a signature from the account over the same statement.
  8. 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.
  9. 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; IdentityService composes 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.identity v2 with a v1 migration.
  • See docs/security/IDENTITY_SECURITY.md for the threat analysis.