web-terminal/relay-e2e/src/aead-key.ts

/**
 * 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<object, AeadKeyMaterial>()

/** 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
}