> ## Documentation Index > Fetch the complete documentation index at: https://docs.parmanasystems.com/llms.txt > Use this file to discover all available pages before exploring further. # Chapter 3: Cryptography > packages/crypto is where every signature Parmana produces or checks actually happens: ## What it is `packages/crypto` is where every signature Parmana produces or checks actually happens: signing an `ExecutionTrustRecord`, an `ExecutionAuthorization`, a `Receipt`, a `PolicyChangeApprovalRecord`, a caller-audit chain entry, and verifying every one of those independently. It provides a pluggable set of hash and signature algorithms, a deterministic serialization step every one of them depends on, and two key-custody models: local files on disk, and AWS KMS ("sign-without-release," the private key never leaves KMS). ## Why it was built The trust model in Chapter 1 is only as strong as the signatures backing it. Every artifact in the chain of custody claims to be "signed by Parmana," and that claim needs to be checkable by a third party who was never in the room, using nothing but the public key and the artifact itself. That requirement drives three design choices covered below: canonical serialization (so the same logical content always produces the same bytes to sign, regardless of how it was constructed in memory), a `Signer` abstraction separate from `KeyProvider` (so a key that can never be exported, like an AWS KMS key, is a first-class option, not a workaround), and hybrid signing (so a future break of one algorithm doesn't retroactively invalidate everything signed under it, as long as a second algorithm was also applied). ## How it works ### `CanonicalSerializer`: the thing every signature is actually computed over `packages/crypto/src/CanonicalSerializer.ts` is nineteen lines of `normalize()` plus a `serialize()` that runs `JSON.stringify` over the result. The normalization rule: objects have their keys recursively sorted lexicographically before serialization; arrays keep their original order (element order is meaningful, key order in an object is not); `Date` becomes its ISO string; everything else passes through unchanged. This single function is what makes two logically-identical objects with different key insertion order, or objects that came from different sources (a hand-typed JSON literal vs. a value round-tripped through a Postgres JSONB column, which does not guarantee to preserve key order) hash and sign identically. Every cryptographic operation in this codebase is required to go through it, `ArtifactSigner.sign()`, `TrustRecordHasher.hash()`, and every `*Crypto` class (`PolicyChangeCrypto`, `RefusalCrypto`, `VerificationCrypto`, `AuditEventCrypto`) all construct their own `CanonicalSerializer` instance rather than hashing raw `JSON.stringify` output directly. A real, recent incident makes the "array order still matters" half of that rule concrete: on 2026-09-16, a batch of policy approvals initially appeared to fail a content-hash check purely because a database round-trip had reordered object keys in the stored `proposedContent`, that turned out to be a red herring, since `CanonicalSerializer` normalizes object key order away. The real, separate finding underneath it was that the stored content was missing an entire field (`unboundSignalReasons`, and for two policies, `boundSignals`) relative to the current file, a genuine content difference no amount of key-order normalization could paper over. See `docs/CLAIMS.md` §2.26's "Legacy-policy backfill" entry for the full account , worth reading as a caution against assuming a hash mismatch has an obvious cause before actually diffing the two objects field by field. ### Hash and signature providers: pluggable, registered, resolved through `CryptoBootstrap` `packages/crypto/src/providers/hash/SHA256HashProvider.ts` implements `HashProvider`: one method, `hash(data: Uint8Array): Promise`, returning a hex digest via Node's `node:crypto` `createHash("sha256")`. Two more hash algorithms (`sha3-512`, `blake3`) are recognized by `Config.ts`'s validation but have no registered provider class yet, selecting either at the config layer would fail when `HashRegistry.get()` tries to resolve them; `sha256` is the only one with a real implementation. Signature providers implement `SignatureProvider` (`sign`/`verify`, plus a readonly `algorithm` field): `Ed25519SignatureProvider.ts` (46 lines, wraps `node:crypto`'s `sign`/`verify` with no options object, i.e. pure Ed25519, not Ed25519ph) and `Dilithium3SignatureProvider.ts` (53 lines, near-identical shape, using Node's native `"ml-dsa-65"` key type, this is the ML-DSA-65/FIPS 204 standard, and `ConfigValidation.ts` accepts the string `"ml-dsa-65"` as a config-time alias that resolves to the same internal `"dilithium3"` identifier, so an operator can write either name in `PRIMARY_SIGNATURE_PROVIDER`). ML-DSA-65 signatures are randomized , signing the same message twice with the same key produces two different, both valid, signatures, noted directly in that provider's own doc comment, worth knowing before assuming a signature mismatch across two runs means something is broken. `MlDsaSupport.ts` detects at runtime (cached after first call) whether the current Node/OpenSSL build actually supports `generateKeyPairSync("ml-dsa-65")`, this requires Node ≥24 with OpenSSL ≥3.5; tests that need it skip cleanly with `ML_DSA_65_SKIP_REASON` on older runtimes rather than failing. Two more algorithms (`ecdsa-p256`, `sphincs-plus`) are recognized by config validation with no registered provider at all. `CryptoBootstrap.create()` is the actual resolution point: it builds a `CryptoProvider` (hash + signature bundled) by registering the built-in providers into `HashRegistry`/ `SignatureRegistry` and selecting by whatever `loadConfig().crypto.hashProvider`/ `primarySignatureProvider` say. `createHybrid()` builds both primary and secondary providers at once, throwing if `CRYPTO_MODE=hybrid` but no `SECONDARY_SIGNATURE_PROVIDER` is set. `ProviderFactory` (`providers/ProviderFactory.ts`) is a three-line compatibility wrapper around `CryptoBootstrap.create()`, nothing more. ### `Signer` vs. `KeyProvider`: two abstractions for a real constraint `KeyProvider` (`KeyProvider.ts`) has a `getPrivateKey(keyId): Promise` method, it assumes the caller can obtain the raw private key material. That assumption is structurally false for AWS KMS, an HSM, or Vault Transit, where the entire point is that the private key never leaves the custody boundary. `Signer` (`Signer.ts`) exists for exactly that case: it drops `getPrivateKey` and adds `sign(keyId, data): Promise` instead, the backend signs on the caller's behalf and only ever returns a signature, never key material. Read operations (`getPublicKey`, `getMetadata`, `hasKey`, `listKeys`) are identical on both interfaces, since verification never needed private key material regardless of custody model. Two implementations exist for each side today. `FileKeyProvider` (`providers/key/FileKeyProvider.ts`, 192 lines) reads `.private.pem`/`.public.pem` from `PARMANA_KEY_DIR`, this is the only real `KeyProvider`, and `KeyBootstrap.create()` (Chapter 2) throws for any other `KEY_PROVIDER` value rather than silently falling back to it. `LocalFileSigner` wraps that same file-reading logic behind the `Signer` interface (so `local` custody works through either abstraction), and `KmsSigner` (`providers/signer/KmsSigner.ts`, 217 lines) is the real AWS KMS implementation, resolved only through `SignerBootstrap`, never through `KeyBootstrap`. ### `KmsSigner`: sign-without-release, against real AWS KMS `KmsSigner` supports exactly one key spec/algorithm pair , `ECC_NIST_EDWARDS25519`/`ED25519_SHA_512`, matching this codebase's `ed25519` default, noted in-source as deliberate: AWS KMS added Ed25519 support in November 2025, so adopting it needed no signature-algorithm migration. `sign()`/`getPublicKey()`/`getMetadata()`/`hasKey()` each call a real `KMSClient` command (`SignCommand`, `GetPublicKeyCommand`, `DescribeKeyCommand`); `listKeys()` is deliberately unimplemented, since enumerating every key in an account/region is a broader operation this codebase's routes don't need. Credentials are never a static access key/secret pair read from this codebase's own configuration. If `AWS_ROLE_ARN` is set, `KmsSigner` dynamically imports the optional `@vercel/oidc-aws-credentials-provider` peer dependency and exchanges Vercel's per-invocation OIDC token for short-lived STS credentials; otherwise it falls back to the AWS SDK's own default credential provider chain. **`resolveKmsKeyId()`** is a small, standalone, exported function (`KmsSigner.ts:46-56`) that matters more than its size suggests. Every real signing call site in this codebase passes a *logical* keyId, `"default"`, or a tenant-scoped `"tenant.acme"`, never a raw AWS identifier. AWS KMS's `KeyId` parameter requires a real key ID (UUID), a full ARN, or an alias name/ARN (which must carry the `alias/` prefix); a bare `"default"` matches none of those and AWS rejects it outright. `resolveKmsKeyId()` maps a bare logical keyId to `alias/` (mirroring `FileKeyProvider`'s own `.private.pem` filename convention), and passes an already-qualified alias, ARN, or raw UUID straight through unchanged. This was a real bug, found by code review before any production traffic hit it: the very first version of this class passed the logical keyId straight through, which meant `KmsSigner.sign("default", data)` would have called AWS with `{ KeyId: "default" }` and failed immediately on every real signing attempt. Because of this function, `alias/default` has to actually exist in AWS, it is not a naming convenience, it is the literal resolution target for the logical id every call site already uses. ### `SignerKeyProviderAdapter`: closing a real signing/verification divergence `providers/SignerKeyProviderAdapter.ts` is the fix for the most serious of the real incidents this migration produced, found against live production traffic on 2026-09-16 (see `docs/VERIFICATION-GAPS.md` G-48/G-49 and the KMS migration troubleshooting guide's item 7). The bug: `EnvelopeVerifier.resolveKey()` uses a `KeyProvider` to look up the public key for *every* authorization it verifies, including ones signed under the plain `"default"` keyId , not only tenant-scoped ones, contrary to an earlier assessment in this same codebase's own comments that this path was "currently inert." `createExecutionGateway.ts` unconditionally constructed a fresh `new FileKeyProvider()` for that lookup, regardless of `KEY_PROVIDER`. Once `KEY_PROVIDER=aws-kms` was set, every authorization was *signed* by the real KMS key (via `SignerBootstrap`) but *verified* against whatever stale local `default.public.pem` happened to still be materialized from a pre-migration `PARMANA_KEY_MATERIAL_JSON` entry. Signing and verification silently used two different keys, every real request's `signatureVerified` check (and everything that cascades from it: `businessTransactionHashMatches`, `nonceUnseen`) failed. `SignerKeyProviderAdapter` closes this by wrapping the *same* `Signer` instance `createGatewayPublicKey()` already uses, so signing and per-authorization verification now resolve through one identical source, KMS-backed or file-backed, whichever `KEY_PROVIDER` actually says. ### `HybridSignatureProvider`: two independent signatures, fail-closed on either `HybridSignatureProvider.ts` is not a `SignatureProvider` implementer, that interface signs with exactly one key and produces exactly one signature. Hybrid mode needs two of each. `sign()` produces a fixed `[primary, secondary]` pair of `SignatureEntry` values; `verify()` requires *exactly* two entries, one matching each configured algorithm, both independently verified, a missing, extra, duplicated, or mismatched-algorithm entry is rejected outright, never a partial pass. The stated purpose (its own doc comment) is "harvest now, decrypt/forge later" defense for the classical-to-post-quantum transition: if a future quantum computer ever breaks the classical primary algorithm, the post-quantum secondary signature alone still holds, and vice versa if a weakness is ever found in the newer PQ scheme instead. `HYBRID_SIGNATURE_REQUIRED=true` (Chapter 2) makes `VerificationCrypto` reject any record whose `signatures` array is absent or partial, rather than silently falling back to the legacy single-signature check, off by default so turning `CRYPTO_MODE=hybrid` on never retroactively invalidates records signed before that flag was set. ### A note on what `.env.example` gets wrong `.env.example`'s comment on `KEY_PROVIDER` states that only `local` has an implementing class and that setting it to anything else "does nothing." That was true when written and is no longer true: `SignerBootstrap.ts` implements `aws-kms` for real. Separately, a live `.env` in this repository was observed carrying `KMS_REGION` and `KMS_KEY_ALIAS` variables, neither name is read anywhere in `packages/*/src` (confirmed by a repo-wide grep returning zero matches). The variables `KmsSigner`/`assertKmsSigningKeyReachable` actually read are `AWS_REGION` and `AWS_ROLE_ARN`. If you are configuring KMS custody for a real deployment, set those two, not `KMS_REGION`/`KMS_KEY_ALIAS`, the latter pair currently does nothing at all. ## How it enables things, with a concrete example * `examples/tutorials/113-kms-key-id-resolution` exercises `resolveKmsKeyId()` directly against five real input shapes (bare logical id, tenant-scoped id, already-qualified alias, full ARN, raw UUID), no AWS credentials needed since it's a pure string-mapping function. * `examples/tutorials/114-signing-verification-key-agreement` exercises the `SignerKeyProviderAdapter` fix, proving signing and verification now resolve through the same key source. * `examples/tutorials/47-canonical-json` demonstrates `CanonicalSerializer`'s normalization behavior directly. * `packages/crypto/tests/unit/kms-signer.test.ts` and `signer-key-provider-adapter.test.ts` are the permanent, mocked-AWS-SDK regression coverage for both fixes above; the KMS migration's own troubleshooting guide notes a real, one-time end-to-end test was also run against actual AWS KMS before this coverage was trusted, then deleted once confirmed. ## How to validate this yourself * `packages/crypto/src/CanonicalSerializer.ts`, read the whole file, it's short and the normalization rule is the single most load-bearing piece of logic in this chapter. * `packages/crypto/src/CryptoBootstrap.ts`, `KeyBootstrap.ts`, `SignerBootstrap.ts`, the three composition roots (Chapter 2 also covers these from the config-and-startup angle). * `packages/crypto/src/Signer.ts`, `KeyProvider.ts`, the two interfaces, both with doc comments explaining exactly why they're separate. * `packages/crypto/src/providers/signer/KmsSigner.ts`, `providers/SignerKeyProviderAdapter.ts` , the real AWS KMS implementation and the incident it closes. * `docs/operations/2026-09-15-kms-migration-troubleshooting-guide.md`, the real incident timeline this chapter draws from; each entry names its symptom, root cause, and fix separately, and is worth reading end to end for the migration's own stated lesson: "a migration that changes *where* a system's trust boundary sits needs to be verified against the real target platform's actual runtime behavior, not just a mocked test double of it." * `docs/VERIFICATION-GAPS.md` G-48/G-49, the ledger entries for the `SignerKeyProviderAdapter` fix specifically. ## Integration requirements For local-file signing (the default): `PARMANA_KEY_DIR` pointing at a directory containing `default.private.pem`/`default.public.pem` (Ed25519 PEM pair), or `PARMANA_KEY_MATERIAL_JSON` set so the process materializes them itself at startup. For AWS KMS signing: `KEY_PROVIDER=aws-kms`, `AWS_REGION` set, an Ed25519 KMS key (`ECC_NIST_EDWARDS25519` key spec) with an alias matching your logical keyId (`alias/default` for the default signing key), and either `AWS_ROLE_ARN` (for Vercel OIDC federation) or a real AWS credential chain reachable in the runtime environment. `@vercel/oidc-aws-credentials-provider` is an optional peer dependency, only needed if `AWS_ROLE_ARN` is set. Note the Vercel-specific cold-start constraint from the troubleshooting guide's item 3: on Vercel specifically, KMS calls that need the OIDC token cannot run at module top level, they need a real in-flight HTTP request to read the token header from. A long-running process (`server.ts`) is not subject to this, since it calls `assertKmsSigningKeyReachable()` once at real process startup, not per-request. For hybrid mode: `CRYPTO_MODE=hybrid`, `SECONDARY_SIGNATURE_PROVIDER` set to a different algorithm than `PRIMARY_SIGNATURE_PROVIDER`, and a second key pair present at `/default-secondary.{private,public}.pem`.