/** * Internal opaque-key registry (P4 impl detail; NOT a re-declared contract shape). * * The frozen §4.4 `AeadKey` is a nominal phantom type (`{ readonly __aeadKey: unique symbol }`). * At runtime we return an opaque, frozen handle and keep the real key material in a module-private * WeakMap — the handle itself exposes NO bytes (supports INV5: no secret sitting on a passed object). * `aadLabel` binds the direction/purpose into every frame's AEAD `aad = aadLabel‖seq`. */ import type { AeadAlg, AeadKey } from 'relay-contracts' import { AEAD_KEY_BYTES } from 'relay-contracts' import { E2EError } from './errors.js' export interface AeadKeyMaterial { readonly raw: Uint8Array readonly alg: AeadAlg readonly aadLabel: string } const REGISTRY = new WeakMap() /** Wrap 32 raw key bytes + alg + aad label into the frozen opaque `AeadKey`. */ export function wrapAeadKey(raw: Uint8Array, alg: AeadAlg, aadLabel: string): AeadKey { if (raw.length !== AEAD_KEY_BYTES) { throw new E2EError('E2E_KEY_LENGTH', `AEAD key must be ${AEAD_KEY_BYTES} bytes; got ${raw.length}`) } const handle = Object.freeze({}) REGISTRY.set(handle, { raw: raw.slice(), alg, aadLabel }) return handle as unknown as AeadKey } /** Recover the key material for a handle previously produced by {@link wrapAeadKey}. */ export function unwrapAeadKey(key: AeadKey): AeadKeyMaterial { const material = REGISTRY.get(key as unknown as object) if (!material) { throw new E2EError('E2E_BAD_KEY_HANDLE', 'value is not a relay-e2e AeadKey handle') } return material }