Status: implemented (FEAT-08). Decision record: ADR-0015.
Code: packages/authorization (engine, browser-safe), packages/authorization-pqc (Rust adapters),
contracts/src/authorization (Solidity integration).
The engine decides whether a subject (a QuantLayer identity) may perform an action on a resource, in a given chain / contract / application domain, under one versioned verification policy. It integrates:
- QuantLayer Identity, the key registry (versioned key rings), the revocation system (key, request, credential status and root revocation), and policy revocation and versioning;
- credential verification (
quantlayer.credential/2presentations); - ZK proof verification (Noir/UltraHonk via
zk-engine); - classical signatures (Ed25519, ES256K, EIP-712 wallets);
- post-quantum signatures (ML-DSA, SLH-DSA via QuantLayer Quantum).
1. Authorization request (quantlayer.authorization-request v1)
| Field | Type | Purpose |
|---|---|---|
version | 1 | Schema version |
requestId | bytes32 hex | Unique id (revocable) |
subject | DID | Who authorizes |
action, resource | string | What; matched against the policy's actions |
parameters | canonical JSON object (≤ 4 KiB) | Action arguments (hashed into the EIP-712 form) |
domain.appDomain | DNS name | Application domain binding |
domain.chainId | decimal string | Chain id binding (EIP-155) |
domain.contract | lowercase address | Contract address binding (the consumer / verifying contract) |
nonce | bytes32 hex | Single-use per (subject, app domain, chain, contract) |
issuedAt, expiresAt | Unix seconds | Expiry; the lifetime is bounded by the policy |
policy.id, policy.version | string, integer | Verification policy (exact version) |
mode | classical | post-quantum | hybrid | credential | zk-eligibility | Must equal the policy's mode |
keys[] | {role, keyId, version, algorithm} | Key id, key version and algorithm identifier of each signer |
hybridScheme | Ed25519+ML-DSA-65 | ES256K+ML-DSA-65 | Hybrid mode only |
Parsing is strict:
- unknown fields are rejected, and so are values that aren't canonical JSON (non-safe-integer numbers, for example);
- hex must be lowercase;
modeandkeysmust be consistent, and every key must belong tosubject;expiresAtmust be afterissuedAt.
2. Canonical encodings
Both encodings are derived deterministically from the same request and cover every field.
| Encoding | Definition | Signed by |
|---|---|---|
| Canonical message | "QUANTLAYER-SIG-V1:authorization-request\n" ‖ canonicalJSON(request) (RFC 8785 profile) | Ed25519, ES256K, ML-DSA, SLH-DSA |
| Hybrid input | "QUANTLAYER-HYBRID-V1" ‖ 0x00 ‖ len ‖ scheme ‖ len ‖ "quantlayer.authorization/1" ‖ canonical message | Both halves of a hybrid signature (byte-compatible with quantlayer_pqc::hybrid) |
| EIP-712 digest (the request identity) | QuantLayerAuthorization(bytes32 requestId,string subject,string action,string resource,bytes32 parametersHash,string appDomain,bytes32 nonce,uint64 issuedAt,uint64 expiresAt,string policyId,uint32 policyVersion,uint8 mode,bytes32 keysHash) in domain {name:"QuantLayer Authorization", version:"1", chainId, verifyingContract: contract} | EVM wallets (ES256K-EIP712). Also the presentation nonce, the ZK proof nonce and the decision id |
- Digest inputs.
parametersHash= keccak256(canonical JSON of the parameters);keysHash= keccak256(canonical JSON of{keys, hybridScheme}). - Solidity agreement.
QuantLayerAuthorizationHash.solcomputes the same digest, and EVM tests check equality, including for Unicode parameters. - Wallet binding. For wallets, chain and contract binding is enforced twice: by the policy, and by the EIP-712 domain separator.
3. Verification policies (versioned)
A policy version is immutable. Changing a requirement means publishing
version n+1, and the registry's minimumVersion(id) rejects older versions.
Statuses: active, retired (no new requests) and revoked (emergency).
Every decision records the policy digest (keccak256 of its canonical JSON).
| # | Mode | Requirement |
|---|---|---|
| 1 | classical | One signature by an allowed scheme (Ed25519, ES256K, ES256K-EIP712) with the active version of a subject key holding the policy's purpose |
| 2 | post-quantum | Same, with ML-DSA-44/65/87 or SLH-DSA-SHA2-128s/128f/256s |
| 3 | hybrid | A hybrid signature: classical AND ML-DSA-65 over the same input; both keys active; scheme allowed |
| 4 | credential | A quantlayer.credential/2 presentation by the subject with audience = app domain and nonce = request digest; issuer, type and required claims per policy; status-list revocation honoured |
| 5 | zk-eligibility | A QuantLayer ZK proof of the configured circuit whose context = computeProofContext(chain, verifier, contract, keccak(appDomain), circuit, digest), whose scope is bound to keccak(action), with issuer, type and threshold ≥ minimum, a root valid in the root registry, a fresh now, and a nullifier used once |
Every policy also fixes:
- the allowed chain ids, contracts, app domains and actions (exact or
prefix.*); - the maximum lifetime and the clock skew;
- the required key purpose.
4. Decision engine
createAuthorizationEngine(deps).decide(request, evidence) never throws.
It runs these steps in a fixed order:
| Step | Checks | Reason codes |
|---|---|---|
request | strict schema; digest | MALFORMED_REQUEST |
evidence | shape and size | MALFORMED_EVIDENCE |
policy | exists, not revoked, version ≥ minimum, not retired, mode matches | POLICY_NOT_FOUND, POLICY_REVOKED, POLICY_VERSION_UNSUPPORTED, POLICY_RETIRED, MODE_MISMATCH |
binding | chain, contract, app domain, action | CHAIN_NOT_ALLOWED, CONTRACT_NOT_ALLOWED, DOMAIN_NOT_ALLOWED, ACTION_NOT_ALLOWED |
time | lifetime, not before issuedAt − skew, not after expiresAt | LIFETIME_TOO_LONG, NOT_YET_VALID, EXPIRED |
revocation | request id not revoked | REQUEST_REVOKED |
subject | identity exists and is active | IDENTITY_NOT_FOUND, IDENTITY_NOT_ACTIVE |
verification | per mode: key registry (version exists, not revoked or emergency-revoked, not expired, active, purpose, algorithm), then the signature, credential or proof checks | KEY_*, ALGORITHM_*, EVIDENCE_MISSING, CLASSICAL_SIGNATURE_INVALID, PQC_SIGNATURE_INVALID, HYBRID_*, CREDENTIAL_*, PROOF_*, CAPABILITY_NOT_CONFIGURED |
replay | consume the nonce, then the nullifier | NONCE_REPLAYED, NULLIFIER_ALREADY_USED |
The decision. It contains:
decision(allow/deny), the terminalreason(AUTHORIZEDor the first failure), and the fulltrace(passed/failed/skippedfor every step);- the request id and digest, subject, action and resource;
- the policy id, version, mode and digest;
- the public evidence used: key references and algorithms; credential issuer, type and claim names; ZK circuit, root and nullifier.
It never contains signatures, keys, presentations, claim values or witnesses.
- Determinism. Steps run in a fixed order and the clock comes from the dependencies. Identical inputs over identical state yield identical decisions; this is tested.
- Fail closed. Any thrown dependency (registry, identities, verifiers,
nonce store, proof backend) becomes
VERIFIER_UNAVAILABLE, and an unconfigured capability becomesCAPABILITY_NOT_CONFIGURED. Neither can yieldallow. - Replay prevention.
- Nonces are consumed only after every other check passes, so a denied
request doesn't burn its nonce. The atomic
NonceStore.consumemakes concurrent submissions resolve to exactly oneallow. - Credential and ZK evidence is bound to the request digest. A presentation or proof can't be moved to another request with the same nonce (front-running), or to another chain, contract or app.
- Nullifiers stop the same identity claiming twice per action, even with distinct requests.
- Nonces are consumed only after every other check passes, so a denied
request doesn't burn its nonce. The atomic
5. Integrations
- Key registry and revocation.
- Keys resolve through
IdentityProvider, from verification-method key rings with exact versions. - Revocation sources honoured: ring revocation;
RevocationRegistry(emergency key and request revocation); identity suspension; credential status lists (via the presentation verifier); root revocation (RootRegistry, mirroringQuantLayerRootRegistry); policy revocation and retirement. - Rotated (retired) keys can't authorize new requests.
- Keys resolve through
- Signatures. One
SignatureVerifieris used, typicallycomposeSignatureVerifiers(createClassicalSignatureVerifier(), pqcVerifier). The port now carries an optional FIPScontext; classical verifiers returnfalsefor a non-empty context rather than ignoring it. - Rust/PQC adapters (
@quantlayer-protocol/authorization-pqc):rustPqcVerifier(provider)verifies with libcrux (FEAT-07).createPqcRequestSigner(provider)produces post-quantum evidence from Rust custody.createHybridRequestSigner(provider, classicalSigner)produces the hybrid signature.- Signers refuse if the key version in the request isn't the active custody version.
- Hybrid in TypeScript.
verifyHybridSignatureis byte-compatible withquantlayer_pqc::hybridand is checked against the Rust interop vectors.
6. Solidity integration
The on-chain counterpart is QuantLayerAuthorizationManager, part of the protocol
layer documented in docs/contracts/ONCHAIN_PROTOCOL.md
(FEAT-09, ADR-0016). It replaces the FEAT-08 reference gate.
QuantLayerAuthorizationHash.sol: EIP-712 hashing identical toauthorizationDigest(checked on ethereumjs and in Foundry).- Every mode works on-chain, each with an explicit assurance:
| Mode | On-chain | Assurance |
|---|---|---|
| 1 classical | authorizeClassical: EIP-712 ECDSA by the subject's registered ES256K-EIP712 key (QuantLayerKeyRegistry: usable, purpose, not expired) | Trustless |
| 2 post-quantum | authorizePostQuantum: k-of-n attestation (attestPostQuantumAuthorization) that the engine verified the registered ML-DSA/SLH-DSA key | Attested |
| 3 hybrid | authorizeHybrid: classical half verified on-chain and post-quantum half attested | Attested |
| 4 credential | authorizeCredential: issuer and credential status checked on-chain; presentation attested | Attested |
| 5 zk-eligibility | authorizeWithProof: policy pins type/threshold; QuantLayerProofVerifier.verifyProof with ctx.nonce = digest (the manager is the consumer) | Trustless |
Native ML-DSA verification is not practical on the EVM (≥ 22.5M gas, see
PQC_FEASIBILITY.md), so attested modes are a
stated trust assumption, never presented as trustless. The manager also enforces
policy version ranges, app domain and action hashes, optional calling contract,
lifetime, clock skew and expiry, an active subject identity, and a single-use
nonce per subject in the shared QuantLayerNullifierRegistry.
7. Security notes and limitations
- Off-chain decisions don't change chain state. A contract must enforce
on-chain (gate) or verify a receipt (
confirmOnChainVerification). An API saying "allowed" proves nothing on-chain. - Nonce and nullifier atomicity. Nonce and nullifier consumption are two writes. If the nullifier write finds a duplicate, the nonce is already burnt, and the request fails closed. Production stores should commit both in one transaction.
- ZK-mode subject. In
zk-eligibilitythe subject DID must resolve and be active, but the proof doesn't link the identity to the DID; anonymity is by design. Combine it with a signature policy if you need both. - Post-quantum and hybrid on-chain. These policies are only as strong as the off-chain verifier's integrity. ES256K-EIP712 and on-chain classical authorizations are not quantum-safe.
- Parameters.
parametersmust be canonical JSON. Applications must give each parameter one meaning per action, because the engine doesn't interpret them. - Clocks. Decisions use the injected clock (milliseconds) and the policy skew. Requests use Unix seconds.