QuantLayer Identity — Security Design

Design document, published from the repository at docs/security/IDENTITY_SECURITY.md.

Audience: security reviewers, auditors and engineers operating the identity service. Scope: @quantlayer-protocol/identity, @quantlayer-protocol/evm (ownership proofs), @quantlayer-protocol/crypto-classical, and their composition in IdentityService. Decisions: ADR-0009, ADR-0010.

1. Security goals

IDGoal
G1No private key is ever accepted, stored, logged or serialized by QuantLayer backends.
G2Every identity mutation is authorised by a current controller of that identity.
G3A signed authorization is valid for exactly one operation, on one subject, at one service, once, for a short time.
G4Identifiers cannot be squatted and are verifiable from their inception.
G5Key compromise is containable: rotation, revocation and recovery work without the compromised key.
G6Signatures are unambiguous: no malleability, no algorithm confusion, fail-closed on unknown algorithms.
G7Historic signatures remain verifiable after rotation, and stop verifying after revocation.

2. Trust boundaries and assets

  • Client / wallet — holds private keys; signs statements. Untrusted input source.
  • IdentityService — trusted application logic; holds no secrets.
  • Repository / ChallengeStore — trusted for integrity and atomicity (see §8).
  • Operator — may activate/suspend/reinstate identities; must be authorised at the API layer (e.g. @quantlayer-protocol/authorization). Cannot change keys or accounts.

Assets: identity state (public keys, account links, recovery policy), challenge nonces, audit evidence (ownership signatures).

3. Key custody (G1)

  • All key inputs are typed as public keys (PublicKey, NewKeyInput.publicKey) and validated for exact length per algorithm (e.g. Ed25519 32 B, ES256K 33 B compressed, ML-DSA-65 1952 B, ML-KEM-768 1184 B).
  • @quantlayer-protocol/crypto-classical exposes verification, recovery and hashing only — there is no signing function to misuse. SignatureProvider (signing) is implemented by client wallets, HSMs or KMS behind the port.
  • The integration suite serializes the full identity state and asserts that no private-key bytes appear in it.

4. Authorization protocol (G2, G3)

client                                   IdentityService
  │ issueChallenge(action, subject) ───────►│ nonce ← CSPRNG(32 B), ttl ≤ 15 min
  │◄──────── {id, nonce, action, subject,   │ store (unconsumed)
  │           audience, issuedAt, expiresAt}│
  │ statement = {…challenge, payload}       │
  │ signature = Sign(statement)             │
  │ request(challengeId, params, sig) ─────►│ 1 scope: audience, action, subject match
  │                                         │ 2 expiry: now < expiresAt
  │                                         │ 3 rebuild statement from params (shared builders)
  │                                         │ 4 verify controller sig (+ PoP, + wallet sig)
  │                                         │ 5 consume(challenge) atomically, else REPLAY_DETECTED
  │                                         │ 6 apply domain rules
  │                                         │ 7 persist with expected revision

Domain separation (layered).

LayerQuantLayer keysWallets
Protocol & purposeQUANTLAYER-SIG-V1:identity-authorization\n prefixEIP-712 domain name="QuantLayer Identity", version="1"
Chain—chainId from the CAIP-10 account (blocks cross-chain replay)
Serviceaudienceaudience
Operationaction, subjectaction, subject
Parameterscanonical payloadpayloadHash = keccak256(canonical(payload))

Statements are QuantLayer canonical JSON (RFC 8785 profile), so client and server produce identical bytes; payloads come from the shared authorizationPayloads builders.

Nonce and replay protection. 32-byte CSPRNG nonces; challenges are bound to action, subject and audience; ChallengeStore.consume is an atomic compare-and-set, so concurrent submissions of one challenge yield exactly one success (tested). Signature failures do not consume the challenge; once signatures verify, the challenge is consumed before domain rules run, so any replay deterministically fails with REPLAY_DETECTED.

Expiry. Challenges live at most 15 minutes (default 5). Expired challenges fail with EXPIRED before any signature work.

5. Proof of possession

Every new signing key (creation, registration, rotation, recovery) must sign the same statement. This prevents registering someone else's public key (key substitution / "unknown key-share") and proves the client controls it. KEM and key-agreement keys cannot sign; they require controller authorization only.

6. Identifiers (G4)

did:quantlayer = first 160 bits of SHA-256 over a domain-separated canonical inception (initial key, algorithm, server nonce). Squatting requires the key; collisions require ~2⁸⁰ work. Anyone can recompute the DID from the inception.

7. Signature robustness (G6, G7)

  • Ed25519: RFC 8032 strict decoding (ZIP-215 disabled) → one valid encoding.
  • ECDSA (ES256K, EIP-712): low-S required (EIP-2); 65-byte r‖s‖v with v ∈ {27,28,0,1}; recovered address compared to the CAIP-10 address.
  • Exact signature and key lengths; malformed inputs verify as false.
  • Algorithm confusion: a key's algorithm is stored with each version and used for verification; credential verification also checks the claimed algorithm.
  • Unknown algorithms throw UNSUPPORTED_ALGORITHM (never "valid").
  • Key versions: active → signs and verifies; retired → verifies only; revoked or expired → nothing. Credentials name the exact keyId@version that signed.

8. Port contracts that are security-critical

PortRequirementFailure if violated
ChallengeStore.consumeAtomic, exactly-onceReplay of authorizations
IdentityRepository.register/updateAtomic account uniqueness; optimistic concurrency on revisionAccount hijack across identities; lost updates
RandomSourceCSPRNG, full lengthPredictable nonces → pre-computed signatures
SignatureVerifierReturn false on invalid, throw on unsupportedForged authorizations
AccountOwnershipVerifierBind chainId and full statementCross-chain or cross-operation replay

The in-memory implementations in @quantlayer-protocol/identity/testing are the executable specification of these contracts.

9. Account association

  • CAIP-10 ids; eip155 addresses normalised to lowercase so the uniqueness index is unambiguous; EIP-55 checksums validated on mixed-case input.
  • Linking requires both a controller authorization and a signature from the account over the same statement. The signature and nonce are stored as audit evidence.
  • Contract wallets: optional EIP-1271 checker (requires an RPC adapter outside the domain).

10. Recovery (G5)

  • m-of-n guardians (identities or accounts), 1 ≤ m ≤ n ≤ 10; an identity and its own linked accounts cannot be guardians.
  • Time-lock (delayMs, ≤30 days) between threshold and completion lets the legitimate owner cancel; request expiry (≤90 days) bounds stale requests.
  • Policy changes after the first wait out the current delay, so a thief holding a key cannot instantly replace guardians.
  • Completion revokes every authentication key version and unlinks every account, then installs the guardians' chosen key (with proof of possession).
  • Guardian approvals are signed statements with their own single-use challenges.

11. Residual risks and operational guidance

RiskStatus / mitigation
Attacker with a controller key cancels a legitimate recoveryInherent to owner-cancellable recovery. Mitigate with short-lived/hardware keys and monitoring of RecoveryCancelled events.
Attacker with a controller key revokes all keys (denial of service)Recoverable through guardians; configure a recovery policy at onboarding.
delayMs = 0 permittedAllowed for testing; production should enforce ≥ 24 h at the API layer.
Guardian collusion (≥ m guardians)Inherent to social recovery; choose independent guardians.
Post-quantum verification not yet available in TypeScriptPQ keys can be registered (lengths enforced); PQ signatures fail closed until the quantlayer-pqc WASM verifier is wired in.
Duplicate JSON keys in transportStatements are rebuilt server-side from typed parameters; transport JSON is never signed directly.
Clock skewServer clock is authoritative for issuance and expiry; clients never supply times.
Operator abuse (suspension)Operators cannot alter keys or accounts; status changes emit events for audit.

12. Test evidence

  • Spec vectors: RFC 8032 (Ed25519), FIPS 180 (SHA-256), Keccak-256, EIP-55, EIP-712 (domain separator, struct hash, digest, signer recovery).
  • Exhaustive state-transition tests for identity, account-link, recovery and key lifecycles (every valid and invalid pair).
  • Service tests: replay, concurrent replay, expiry, wrong action/subject/audience, forged signatures, missing/invalid proof of possession, non-controller wallets.
  • Integration (SDK) with real Ed25519, ES256K and EIP-712 wallet signatures: full lifecycle, cross-chain replay, rotation continuity, revocation effect, guardian recovery and absence of private keys in stored state.