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
| ID | Goal |
|---|---|
| G1 | No private key is ever accepted, stored, logged or serialized by QuantLayer backends. |
| G2 | Every identity mutation is authorised by a current controller of that identity. |
| G3 | A signed authorization is valid for exactly one operation, on one subject, at one service, once, for a short time. |
| G4 | Identifiers cannot be squatted and are verifiable from their inception. |
| G5 | Key compromise is containable: rotation, revocation and recovery work without the compromised key. |
| G6 | Signatures are unambiguous: no malleability, no algorithm confusion, fail-closed on unknown algorithms. |
| G7 | Historic 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-classicalexposes 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 revisionDomain separation (layered).
| Layer | QuantLayer keys | Wallets |
|---|---|---|
| Protocol & purpose | QUANTLAYER-SIG-V1:identity-authorization\n prefix | EIP-712 domain name="QuantLayer Identity", version="1" |
| Chain | — | chainId from the CAIP-10 account (blocks cross-chain replay) |
| Service | audience | audience |
| Operation | action, subject | action, subject |
| Parameters | canonical payload | payloadHash = 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‖vwith 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@versionthat signed.
8. Port contracts that are security-critical
| Port | Requirement | Failure if violated |
|---|---|---|
ChallengeStore.consume | Atomic, exactly-once | Replay of authorizations |
IdentityRepository.register/update | Atomic account uniqueness; optimistic concurrency on revision | Account hijack across identities; lost updates |
RandomSource | CSPRNG, full length | Predictable nonces → pre-computed signatures |
SignatureVerifier | Return false on invalid, throw on unsupported | Forged authorizations |
AccountOwnershipVerifier | Bind chainId and full statement | Cross-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;
eip155addresses 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
| Risk | Status / mitigation |
|---|---|
| Attacker with a controller key cancels a legitimate recovery | Inherent 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 permitted | Allowed 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 TypeScript | PQ keys can be registered (lengths enforced); PQ signatures fail closed until the quantlayer-pqc WASM verifier is wired in. |
| Duplicate JSON keys in transport | Statements are rebuilt server-side from typed parameters; transport JSON is never signed directly. |
| Clock skew | Server 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.