QuantLayer hybrid authorization engine

Design document, published from the repository at docs/authorization/AUTHORIZATION.md.

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/2 presentations);
  • 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)

FieldTypePurpose
version1Schema version
requestIdbytes32 hexUnique id (revocable)
subjectDIDWho authorizes
action, resourcestringWhat; matched against the policy's actions
parameterscanonical JSON object (≤ 4 KiB)Action arguments (hashed into the EIP-712 form)
domain.appDomainDNS nameApplication domain binding
domain.chainIddecimal stringChain id binding (EIP-155)
domain.contractlowercase addressContract address binding (the consumer / verifying contract)
noncebytes32 hexSingle-use per (subject, app domain, chain, contract)
issuedAt, expiresAtUnix secondsExpiry; the lifetime is bounded by the policy
policy.id, policy.versionstring, integerVerification policy (exact version)
modeclassical | post-quantum | hybrid | credential | zk-eligibilityMust equal the policy's mode
keys[]{role, keyId, version, algorithm}Key id, key version and algorithm identifier of each signer
hybridSchemeEd25519+ML-DSA-65 | ES256K+ML-DSA-65Hybrid 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;
  • mode and keys must be consistent, and every key must belong to subject;
  • expiresAt must be after issuedAt.

2. Canonical encodings

Both encodings are derived deterministically from the same request and cover every field.

EncodingDefinitionSigned 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 messageBoth 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.sol computes 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).

#ModeRequirement
1classicalOne signature by an allowed scheme (Ed25519, ES256K, ES256K-EIP712) with the active version of a subject key holding the policy's purpose
2post-quantumSame, with ML-DSA-44/65/87 or SLH-DSA-SHA2-128s/128f/256s
3hybridA hybrid signature: classical AND ML-DSA-65 over the same input; both keys active; scheme allowed
4credentialA 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
5zk-eligibilityA 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:

StepChecksReason codes
requeststrict schema; digestMALFORMED_REQUEST
evidenceshape and sizeMALFORMED_EVIDENCE
policyexists, not revoked, version ≥ minimum, not retired, mode matchesPOLICY_NOT_FOUND, POLICY_REVOKED, POLICY_VERSION_UNSUPPORTED, POLICY_RETIRED, MODE_MISMATCH
bindingchain, contract, app domain, actionCHAIN_NOT_ALLOWED, CONTRACT_NOT_ALLOWED, DOMAIN_NOT_ALLOWED, ACTION_NOT_ALLOWED
timelifetime, not before issuedAt − skew, not after expiresAtLIFETIME_TOO_LONG, NOT_YET_VALID, EXPIRED
revocationrequest id not revokedREQUEST_REVOKED
subjectidentity exists and is activeIDENTITY_NOT_FOUND, IDENTITY_NOT_ACTIVE
verificationper mode: key registry (version exists, not revoked or emergency-revoked, not expired, active, purpose, algorithm), then the signature, credential or proof checksKEY_*, ALGORITHM_*, EVIDENCE_MISSING, CLASSICAL_SIGNATURE_INVALID, PQC_SIGNATURE_INVALID, HYBRID_*, CREDENTIAL_*, PROOF_*, CAPABILITY_NOT_CONFIGURED
replayconsume the nonce, then the nullifierNONCE_REPLAYED, NULLIFIER_ALREADY_USED

The decision. It contains:

  • decision (allow/deny), the terminal reason (AUTHORIZED or the first failure), and the full trace (passed/failed/skipped for 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 becomes CAPABILITY_NOT_CONFIGURED. Neither can yield allow.
  • Replay prevention.
    • Nonces are consumed only after every other check passes, so a denied request doesn't burn its nonce. The atomic NonceStore.consume makes concurrent submissions resolve to exactly one allow.
    • 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.

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, mirroring QuantLayerRootRegistry); policy revocation and retirement.
    • Rotated (retired) keys can't authorize new requests.
  • Signatures. One SignatureVerifier is used, typically composeSignatureVerifiers(createClassicalSignatureVerifier(), pqcVerifier). The port now carries an optional FIPS context; classical verifiers return false for 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. verifyHybridSignature is byte-compatible with quantlayer_pqc::hybrid and 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 to authorizationDigest (checked on ethereumjs and in Foundry).
  • Every mode works on-chain, each with an explicit assurance:
ModeOn-chainAssurance
1 classicalauthorizeClassical: EIP-712 ECDSA by the subject's registered ES256K-EIP712 key (QuantLayerKeyRegistry: usable, purpose, not expired)Trustless
2 post-quantumauthorizePostQuantum: k-of-n attestation (attestPostQuantumAuthorization) that the engine verified the registered ML-DSA/SLH-DSA keyAttested
3 hybridauthorizeHybrid: classical half verified on-chain and post-quantum half attestedAttested
4 credentialauthorizeCredential: issuer and credential status checked on-chain; presentation attestedAttested
5 zk-eligibilityauthorizeWithProof: 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-eligibility the 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. parameters must 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.