@coffre/core 0.0.0 → 0.1.0

package/src/identity/verifier.ts

@@ -0,0 +1,86 @@
+import { createRemoteJWKSet, jwtVerify, type JWTPayload } from 'jose';
+import type { AccessVerifierConfig, IdentityVerifier, Principal } from './types.ts';
+
+export type { AccessVerifierConfig };
+
+/**
+ * Signature algorithms we accept, as an explicit allowlist.
+ *
+ * Without this, the algorithm is taken from the attacker-controlled token
+ * header, which is how `alg: none` and RS256->HS256 confusion work. jose
+ * defaults to permitting whatever the key supports; we do not rely on that.
+ */
+const ALLOWED_ALGORITHMS = ['RS256', 'ES256'] as const;
+
+type AccessClaims = JWTPayload & {
+  email?: unknown;
+  common_name?: unknown;
+};
+
+function asNonEmptyString(value: unknown): string | null {
+  return typeof value === 'string' && value.length > 0 ? value : null;
+}
+
+/**
+ * Verifies Cloudflare Access JWTs.
+ *
+ * Signature and claim verification for the TanStack request boundary. The
+ * boundary also rejects `x-middleware-subrequest` before calling this verifier.
+ */
+export class AccessIdentityVerifier implements IdentityVerifier {
+  readonly #config: AccessVerifierConfig;
+  readonly #jwks: ReturnType<typeof createRemoteJWKSet>;
+
+  constructor(config: AccessVerifierConfig) {
+    this.#config = config;
+    // jose handles JWKS fetching, caching and rotation-driven refetch. Not
+    // something to hand-roll.
+    this.#jwks = createRemoteJWKSet(new URL(config.jwksUrl), {
+      cooldownDuration: 30_000,
+      cacheMaxAge: 600_000,
+    });
+  }
+
+  async verify(token: string): Promise<Principal> {
+    if (typeof token !== 'string' || token.length === 0) {
+      throw new Error('missing or empty Access token');
+    }
+
+    const { payload } = await jwtVerify<AccessClaims>(token, this.#jwks, {
+      issuer: this.#config.issuer,
+      audience: this.#config.audience,
+      algorithms: [...ALLOWED_ALGORITHMS],
+      clockTolerance: this.#config.clockToleranceSeconds ?? 0,
+    });
+
+    return toPrincipal(payload);
+  }
+}
+
+/**
+ * Derive the caller from verified claims.
+ *
+ * Order matters. A service token is identified by `common_name` and carries an
+ * empty `sub`; an identity token carries both `sub` and `email`. Anything else
+ * is rejected rather than being allowed through as an authenticated caller
+ * with no name -- an audit row with a null actor answers no question worth
+ * asking.
+ */
+export function toPrincipal(claims: AccessClaims): Principal {
+  const commonName = asNonEmptyString(claims.common_name);
+  if (commonName !== null) {
+    return { type: 'service', id: commonName, commonName };
+  }
+
+  const email = asNonEmptyString(claims.email);
+  const subject = asNonEmptyString(claims.sub);
+  if (email !== null && subject !== null) {
+    // People are stored by lowercased email; see principals_user_id_lowercase.
+    const id = email.toLowerCase();
+    return { type: 'user', id, email: id, subject };
+  }
+
+  throw new Error(
+    'token verified but carries no usable identity: expected common_name (service) or sub+email (user)',
+  );
+}

package/src/kek/aws-kms.ts

@@ -0,0 +1,279 @@
+import { checkContext, type SecretContext } from '../context.ts';
+import { signV4, type AwsCredentials } from './sigv4.ts';
+import { cancellable, checkOperation, delay, operationSignal } from './cancellation.ts';
+import {
+  DEK_BYTES,
+  KekBadClaimError,
+  KekCancelledError,
+  KekUnavailableError,
+  type KeyOperation,
+  type KekProvider,
+  type WrappedDek,
+} from './types.ts';
+
+export type AwsKmsOptions = {
+  /**
+   * The key's ARN, `arn:aws:kms:<region>:<account>:key/<id>`. Coffre calls
+   * KMS in that region, and records the ARN on every data key it wraps. Not
+   * an alias, which can come to name another key.
+   */
+  keyArn: string;
+  /**
+   * An access key allowed `kms:Encrypt` and `kms:Decrypt` on it, or a
+   * function that returns one, asked before each call so that it may refresh
+   * (an AWS SDK credential provider is one).
+   */
+  credentials: AwsCredentials | (() => Promise<AwsCredentials>);
+  /** For tests. */
+  fetch?: typeof fetch;
+};
+
+const KEY_ARN = /^arn:(aws|aws-cn|aws-us-gov):kms:([a-z0-9-]+):\d{12}:key\/[A-Za-z0-9-]{1,128}$/;
+
+const ATTEMPTS = 3;
+const TIMEOUT_MS = 5_000;
+/** Calls in flight at once. A Worker opens at most six connections anyway. */
+const CONCURRENCY = 8;
+/** What KMS says when the ciphertext does not open under this key and context: a bad claim, not an outage. */
+const NOT_THIS_KEY = new Set(['InvalidCiphertextException', 'IncorrectKeyException']);
+
+/** A KEK held in AWS KMS: it never leaves, and coffre asks KMS to wrap and unwrap each data key. */
+export function awsKms(options: AwsKmsOptions): KekProvider {
+  return new AwsKmsKekProvider(options);
+}
+
+/**
+ * KMS's JSON API, `Encrypt` and `Decrypt`, signed with SigV4 and no SDK, so
+ * it runs as is on Node and in a Worker. Each call sends the secret's UUIDs
+ * as the encryption context, which KMS binds to the ciphertext and CloudTrail
+ * logs with the call: every decrypt there names the secret it was for, in a
+ * log neither coffre nor whoever runs it can edit.
+ */
+export class AwsKmsKekProvider implements KekProvider {
+  readonly provider = 'aws-kms';
+  readonly keyId: string;
+  /** KMS keeps its own versions inside each ciphertext, and rotates the key material under the same ARN. */
+  readonly keyVersion = '1';
+
+  readonly #region: string;
+  readonly #url: URL;
+  readonly #credentials: () => Promise<AwsCredentials>;
+  readonly #fetch: typeof fetch;
+  readonly #slots = new Slots(CONCURRENCY);
+
+  constructor(options: AwsKmsOptions) {
+    const match = KEY_ARN.exec(options.keyArn);
+    if (match === null) {
+      throw new Error(
+        `the KMS key must be a key ARN, like arn:aws:kms:eu-west-3:123456789012:key/<id>, not an alias; got "${options.keyArn}"`,
+      );
+    }
+    const [, partition, region] = match as unknown as [string, string, string];
+    this.keyId = options.keyArn;
+    this.#region = region;
+    this.#url = new URL(`https://kms.${region}.amazonaws.com${partition === 'aws-cn' ? '.cn' : ''}/`);
+    const { credentials } = options;
+    this.#credentials = typeof credentials === 'function' ? credentials : async () => credentials;
+    // Called bare: a Worker's fetch refuses to run as a method of anything else.
+    this.#fetch = options.fetch ?? ((input, init) => fetch(input, init));
+  }
+
+  async wrap(dek: Buffer, ctx: SecretContext, operation?: KeyOperation): Promise<WrappedDek> {
+    if (dek.length !== DEK_BYTES) throw new Error(`DEK must be ${DEK_BYTES} bytes, got ${dek.length}`);
+    const { CiphertextBlob } = await this.#call('Encrypt', {
+      KeyId: this.keyId,
+      Plaintext: base64(dek),
+      EncryptionContext: encryptionContext(ctx),
+    }, operation);
+    return {
+      kekProvider: this.provider,
+      kekId: this.keyId,
+      kekVersion: this.keyVersion,
+      bytes: Buffer.from(CiphertextBlob, 'base64'),
+    };
+  }
+
+  async unwrap(wrapped: WrappedDek, ctx: SecretContext, operation?: KeyOperation): Promise<Buffer> {
+    if (wrapped.kekProvider !== this.provider || wrapped.kekId !== this.keyId) {
+      throw new KekBadClaimError(`wrapped DEK is for ${wrapped.kekProvider}:${wrapped.kekId}, not ${this.provider}:${this.keyId}`);
+    }
+    // KeyId makes KMS refuse a ciphertext made under any other key.
+    const { Plaintext, KeyId } = await this.#call('Decrypt', {
+      KeyId: this.keyId,
+      CiphertextBlob: base64(wrapped.bytes),
+      EncryptionContext: encryptionContext(ctx),
+    }, operation);
+    if (KeyId !== this.keyId) throw new KekUnavailableError(`KMS decrypted under ${KeyId}, not ${this.keyId}`, true);
+    const dek = Buffer.from(Plaintext, 'base64');
+    if (dek.length !== DEK_BYTES) {
+      dek.fill(0);
+      throw new KekUnavailableError('unwrapped DEK has the wrong length', true);
+    }
+    return dek;
+  }
+
+  /**
+   * One KMS call, tried up to three times while KMS throttles, fails on its
+   * side or does not answer. Every failure but a ciphertext that does not
+   * open is a `KekUnavailableError`, retried or not: a key KMS will not use
+   * or credentials it refuses say nothing about the claim either.
+   */
+  async #call(action: 'Encrypt' | 'Decrypt', request: object, operation?: KeyOperation): Promise<Record<string, string>> {
+    const body = JSON.stringify(request);
+    const signal = operationSignal(operation);
+    return this.#slots.run(async () => {
+      checkOperation(operation);
+      let credentials: AwsCredentials;
+      try {
+        credentials = await cancellable(this.#credentials(), signal);
+      } catch (error) {
+        if (error instanceof KekCancelledError) throw error;
+        throw new KekUnavailableError(`no AWS credentials for KMS: ${messageOf(error)}`);
+      }
+      let uncertain = false;
+      for (let attempt = 1; ; attempt++) {
+        checkOperation(operation, uncertain);
+        if (signal?.aborted) throw new KekCancelledError(uncertain);
+        const answer = await this.#send(action, body, credentials, signal, operation);
+        if ('data' in answer) return answer.data;
+        uncertain ||= answer.uncertain;
+        checkOperation(operation, uncertain);
+        if (signal?.aborted) throw new KekCancelledError(uncertain);
+        if (NOT_THIS_KEY.has(answer.type)) {
+          if (uncertain) throw new KekUnavailableError(`KMS ${action}: ${answer.type} after an unanswered request`, true);
+          throw new KekBadClaimError(`KMS ${action}: ${answer.type}`);
+        }
+        if (!answer.retry || attempt === ATTEMPTS) {
+          throw new KekUnavailableError(`KMS ${action} failed${attempt > 1 ? ` ${attempt} times` : ''}: ${answer.failure}`, uncertain);
+        }
+        try {
+          await delay(100 * 4 ** (attempt - 1) * (1 + Math.random()), signal);
+        } catch (error) {
+          if (error instanceof KekCancelledError) throw new KekCancelledError(uncertain);
+          throw error;
+        }
+      }
+    }, signal);
+  }
+
+  async #send(
+    action: string,
+    body: string,
+    credentials: AwsCredentials,
+    signal?: AbortSignal,
+    operation?: KeyOperation,
+  ): Promise<{ data: Record<string, string> } | { type: string; failure: string; retry: boolean; uncertain: boolean }> {
+    const headers = signV4({
+      method: 'POST',
+      url: this.#url,
+      headers: { 'content-type': 'application/x-amz-json-1.1', 'x-amz-target': `TrentService.${action}` },
+      body,
+      region: this.#region,
+      service: 'kms',
+      credentials,
+      date: new Date(),
+    });
+    let response: Response;
+    let text: string;
+    let sent = false;
+    try {
+      checkOperation(operation);
+      if (signal?.aborted) throw new KekCancelledError();
+      sent = true;
+      response = await this.#fetch(this.#url, {
+        method: 'POST', headers, body,
+        signal: AbortSignal.any([AbortSignal.timeout(TIMEOUT_MS), ...(signal === undefined ? [] : [signal])]),
+      });
+      text = await response.text();
+    } catch (error) {
+      return { type: 'network', failure: messageOf(error), retry: sent, uncertain: sent };
+    }
+    const parsed = parse(text);
+    if (response.ok) {
+      const complete =
+        parsed !== null && (action === 'Encrypt' ? typeof parsed.CiphertextBlob === 'string' : typeof parsed.Plaintext === 'string');
+      if (complete) return { data: parsed as Record<string, string> };
+      return { type: 'malformed', failure: `KMS answered ${response.status} without a result`, retry: true, uncertain: true };
+    }
+    // `__type` may carry a namespace (`com.amazonaws.kms#…`), the header a URL after `:`.
+    const raw = response.headers.get('x-amzn-errortype') ?? (typeof parsed?.__type === 'string' ? parsed.__type : '');
+    const type = raw.split(':')[0]!.split('#').pop() || `HTTP ${response.status}`;
+    const message = parsed?.message ?? parsed?.Message;
+    return {
+      type,
+      failure: `${type}${typeof message === 'string' ? `, ${message}` : ''}`,
+      uncertain: false,
+      retry: response.status >= 500 || response.status === 429 || type === 'ThrottlingException',
+    };
+  }
+}
+
+/**
+ * The secret's UUIDs, as KMS binds them to the ciphertext and CloudTrail
+ * shows them. Checked first, so a malformed one never reaches KMS.
+ */
+function encryptionContext(ctx: SecretContext): Record<string, string> {
+  checkContext(ctx);
+  return { 'coffre:project': ctx.projectId, 'coffre:environment': ctx.environmentId, 'coffre:secret': ctx.secretId };
+}
+
+/**
+ * Bytes as base64. Through `Buffer.from`, a view of the same memory, because
+ * Workers' types declare their own `Buffer` and a bare one loses its
+ * `toString(encoding)` to them.
+ */
+function base64(bytes: Uint8Array): string {
+  return Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength).toString('base64');
+}
+
+function parse(text: string): Record<string, unknown> | null {
+  try {
+    const value = JSON.parse(text) as unknown;
+    return typeof value === 'object' && value !== null ? (value as Record<string, unknown>) : null;
+  } catch {
+    return null;
+  }
+}
+
+function messageOf(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+/** At most `n` calls at once; the rest wait their turn. */
+class Slots {
+  #free: number;
+  readonly #waiting: { start: () => void; cancel: () => void }[] = [];
+
+  constructor(n: number) {
+    this.#free = n;
+  }
+
+  async run<T>(work: () => Promise<T>, signal?: AbortSignal): Promise<T> {
+    if (signal?.aborted) throw new KekCancelledError();
+    if (this.#free > 0) this.#free--;
+    else await new Promise<void>((resolve, reject) => {
+      const waiting = {
+        start: () => {
+          signal?.removeEventListener('abort', waiting.cancel);
+          resolve();
+        },
+        cancel: () => {
+          const index = this.#waiting.indexOf(waiting);
+          if (index >= 0) this.#waiting.splice(index, 1);
+          signal?.removeEventListener('abort', waiting.cancel);
+          reject(new KekCancelledError());
+        },
+      };
+      this.#waiting.push(waiting);
+      signal?.addEventListener('abort', waiting.cancel, { once: true });
+    });
+    try {
+      if (signal?.aborted) throw new KekCancelledError();
+      return await work();
+    } finally {
+      const next = this.#waiting.shift();
+      if (next) next.start();
+      else this.#free++;
+    }
+  }
+}

package/src/kek/cancellation.ts

@@ -0,0 +1,56 @@
+import { KekCancelledError, type KeyOperation } from './types.ts';
+
+export function checkOperation(operation?: KeyOperation, uncertain = false): void {
+  if (operation !== undefined && (operation.signal.aborted || Date.now() >= operation.deadline)) {
+    throw new KekCancelledError(uncertain);
+  }
+}
+
+const signals = new WeakMap<KeyOperation, AbortSignal>();
+
+/**
+ * Enforce the deadline even when the caller's signal has not fired yet: one
+ * signal for every call of an operation, so its deadline cancels them all at
+ * once. With a timer per call, one call's could fire first, free its slot,
+ * and start a key queued behind it whose own timer had not fired yet.
+ */
+export function operationSignal(operation?: KeyOperation): AbortSignal | undefined {
+  if (operation === undefined) return undefined;
+  checkOperation(operation);
+  let signal = signals.get(operation);
+  if (signal === undefined) {
+    signal = AbortSignal.any([operation.signal, AbortSignal.timeout(Math.max(0, operation.deadline - Date.now()))]);
+    signals.set(operation, signal);
+  }
+  return signal;
+}
+
+/** Credentials can finish later, but must never send a request after cancellation. */
+export function cancellable<T>(work: Promise<T>, signal?: AbortSignal): Promise<T> {
+  if (signal === undefined) return work;
+  return new Promise((resolve, reject) => {
+    const abort = () => {
+      signal.removeEventListener('abort', abort);
+      reject(new KekCancelledError());
+    };
+    if (signal.aborted) abort();
+    else signal.addEventListener('abort', abort, { once: true });
+    work.then(resolve, reject).finally(() => signal.removeEventListener('abort', abort));
+  });
+}
+
+export function delay(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const abort = () => {
+      clearTimeout(timer);
+      signal?.removeEventListener('abort', abort);
+      reject(new KekCancelledError());
+    };
+    const timer = setTimeout(() => {
+      signal?.removeEventListener('abort', abort);
+      resolve();
+    }, ms);
+    if (signal?.aborted) abort();
+    else signal?.addEventListener('abort', abort, { once: true });
+  });
+}

package/src/kek/index.ts

@@ -0,0 +1,6 @@
+export type { KekProvider, WrappedDek, KeyOperation } from './types.ts';
+export { DEK_BYTES, KekUnavailableError, KekCancelledError, KekBadClaimError } from './types.ts';
+export { LocalKekProvider, equalBytes } from './local.ts';
+export { KekRegistry } from './registry.ts';
+export { AwsKmsKekProvider, awsKms, type AwsKmsOptions } from './aws-kms.ts';
+export type { AwsCredentials } from './sigv4.ts';

package/src/kek/local.ts

@@ -0,0 +1,122 @@
+import { createCipheriv, createDecipheriv, randomBytes, timingSafeEqual } from 'node:crypto';
+import type { SecretContext } from '../context.ts';
+import { encodeAad } from '../context.ts';
+import { checkOperation } from './cancellation.ts';
+import { DEK_BYTES, KekBadClaimError, type KeyOperation, type KekProvider, type WrappedDek } from './types.ts';
+
+const IV_BYTES = 12;
+const TAG_BYTES = 16;
+const KEK_BYTES = 32;
+
+/**
+ * A KEK held in local process memory, loaded from configuration.
+ *
+ * This is the local-development implementation of `KekProvider`. It is a
+ * different implementation of the same interface, not a branch that skips
+ * wrapping: the envelope format, the context binding and the failure modes are
+ * identical to what a remote KMS-backed provider will produce.
+ */
+export class LocalKekProvider implements KekProvider {
+  readonly provider = 'local';
+  readonly keyId: string;
+  readonly keyVersion: string;
+
+  readonly #kek: Buffer;
+
+  constructor(kek: Buffer, keyId: string, keyVersion: string = '1') {
+    if (kek.length !== KEK_BYTES) {
+      throw new Error(`local KEK must be ${KEK_BYTES} bytes, got ${kek.length}`);
+    }
+    this.#kek = kek;
+    this.keyId = keyId;
+    this.keyVersion = keyVersion;
+  }
+
+  /** Build a provider from a base64-encoded 32-byte key, e.g. from an env var. */
+  static fromBase64(encoded: string, keyId: string, keyVersion = '1'): LocalKekProvider {
+    return new LocalKekProvider(Buffer.from(encoded, 'base64'), keyId, keyVersion);
+  }
+
+  /** Generate a fresh random KEK. Used by tests and by the dev seed script. */
+  static generate(keyId: string, keyVersion = '1'): LocalKekProvider {
+    return new LocalKekProvider(randomBytes(KEK_BYTES), keyId, keyVersion);
+  }
+
+  /**
+   * AAD for the wrap operation.
+   *
+   * Binds the wrapped DEK both to the secret it belongs to and to the KEK
+   * identity that produced it, so a wrapped DEK cannot be replayed against a
+   * row claiming a different KEK.
+   */
+  #wrapAad(ctx: SecretContext): Buffer {
+    return Buffer.concat([
+      encodeAad(ctx),
+      Buffer.from(`|${this.provider}|${this.keyId}|${this.keyVersion}`, 'utf8'),
+    ]);
+  }
+
+  async wrap(dek: Buffer, ctx: SecretContext, operation?: KeyOperation): Promise<WrappedDek> {
+    checkOperation(operation);
+    if (dek.length !== DEK_BYTES) {
+      throw new Error(`DEK must be ${DEK_BYTES} bytes, got ${dek.length}`);
+    }
+
+    const iv = randomBytes(IV_BYTES);
+    const cipher = createCipheriv('aes-256-gcm', this.#kek, iv);
+    cipher.setAAD(this.#wrapAad(ctx));
+
+    const body = Buffer.concat([cipher.update(dek), cipher.final()]);
+
+    return {
+      kekProvider: this.provider,
+      kekId: this.keyId,
+      kekVersion: this.keyVersion,
+      bytes: Buffer.concat([iv, cipher.getAuthTag(), body]),
+    };
+  }
+
+  async unwrap(wrapped: WrappedDek, ctx: SecretContext, operation?: KeyOperation): Promise<Buffer> {
+    checkOperation(operation);
+    if (wrapped.kekProvider !== this.provider || wrapped.kekId !== this.keyId) {
+      throw new KekBadClaimError(
+        `wrapped DEK is for ${wrapped.kekProvider}:${wrapped.kekId}, not ${this.provider}:${this.keyId}`,
+      );
+    }
+    if (wrapped.bytes.length !== IV_BYTES + TAG_BYTES + DEK_BYTES) {
+      throw new KekBadClaimError('wrapped DEK has the wrong length');
+    }
+
+    const iv = wrapped.bytes.subarray(0, IV_BYTES);
+    const tag = wrapped.bytes.subarray(IV_BYTES, IV_BYTES + TAG_BYTES);
+    const body = wrapped.bytes.subarray(IV_BYTES + TAG_BYTES);
+
+    const decipher = createDecipheriv('aes-256-gcm', this.#kek, iv);
+    decipher.setAAD(this.#wrapAad(ctx));
+    decipher.setAuthTag(tag);
+
+    // GCM raises on a tag mismatch, which is what a relocated or tampered
+    // wrapped DEK produces. The error is deliberately not specific.
+    let dek: Buffer;
+    const partial = decipher.update(body);
+    try {
+      dek = Buffer.concat([partial, decipher.final()]);
+    } catch {
+      throw new KekBadClaimError('wrapped DEK does not open under this context');
+    } finally {
+      partial.fill(0);
+    }
+
+    // Defensive: a 32-byte plaintext is the only shape we ever wrap.
+    if (dek.length !== DEK_BYTES) {
+      dek.fill(0);
+      throw new KekBadClaimError('unwrapped DEK has the wrong length');
+    }
+    return dek;
+  }
+}
+
+/** Constant-time buffer comparison, for tests and callers that need it. */
+export function equalBytes(a: Buffer, b: Buffer): boolean {
+  return a.length === b.length && timingSafeEqual(a, b);
+}

package/src/kek/registry.ts

@@ -0,0 +1,63 @@
+import type { SecretContext } from '../context.ts';
+import type { KekProvider, WrappedDek, KeyOperation } from './types.ts';
+
+function refOf(provider: string, keyId: string): string {
+  return `${provider}:${keyId}`;
+}
+
+/**
+ * A set of active KEKs, one of which is primary.
+ *
+ * New secret versions are always wrapped under the primary. Old versions keep
+ * unwrapping under whichever KEK produced them, looked up by the provider and
+ * key id stored on their own row. Key rotation and migrating from the local
+ * provider to a KMS-backed one are therefore the same operation: add a new KEK,
+ * make it primary, leave the old one readable until nothing references it.
+ */
+export class KekRegistry {
+  readonly #byRef = new Map<string, KekProvider>();
+  readonly #primary: KekProvider;
+
+  constructor(primary: KekProvider, additional: readonly KekProvider[] = []) {
+    this.#primary = primary;
+    for (const provider of [primary, ...additional]) {
+      const ref = refOf(provider.provider, provider.keyId);
+      if (this.#byRef.has(ref)) {
+        throw new Error(`duplicate KEK in registry: ${ref}`);
+      }
+      this.#byRef.set(ref, provider);
+    }
+  }
+
+  get primary(): KekProvider {
+    return this.#primary;
+  }
+
+  /** Every KEK, the primary first. */
+  get all(): KekProvider[] {
+    return [...this.#byRef.values()];
+  }
+
+  /** The KEK a wrapped key names, or undefined when none is configured. */
+  providerOf(wrapped: Pick<WrappedDek, 'kekProvider' | 'kekId'>): KekProvider | undefined {
+    return this.#byRef.get(refOf(wrapped.kekProvider, wrapped.kekId));
+  }
+
+  /** Wrap under the primary KEK. Used for every new secret version. */
+  wrap(dek: Buffer, ctx: SecretContext, operation?: KeyOperation): Promise<WrappedDek> {
+    return this.#primary.wrap(dek, ctx, operation);
+  }
+
+  /** Unwrap under whichever KEK the row says produced it. */
+  unwrap(wrapped: WrappedDek, ctx: SecretContext, operation?: KeyOperation): Promise<Buffer> {
+    const ref = refOf(wrapped.kekProvider, wrapped.kekId);
+    const provider = this.#byRef.get(ref);
+    if (!provider) {
+      // Operationally this means a KEK was removed from configuration while
+      // rows still reference it. Fail loudly rather than returning a decrypt
+      // error that looks like corruption.
+      throw new Error(`no KEK configured for ${ref}; cannot unwrap`);
+    }
+    return provider.unwrap(wrapped, ctx, operation);
+  }
+}

package/src/kek/sigv4.ts

@@ -0,0 +1,75 @@
+import { createHash, createHmac } from 'node:crypto';
+
+/** An AWS access key, with `sessionToken` when it is temporary (a role's). */
+export type AwsCredentials = { accessKeyId: string; secretAccessKey: string; sessionToken?: string };
+
+export type SigningInput = {
+  method: string;
+  url: URL;
+  /** The headers to send, but for `host`, `x-amz-date` and the session token, which signing adds. */
+  headers: Record<string, string>;
+  body: string;
+  region: string;
+  service: string;
+  credentials: AwsCredentials;
+  date: Date;
+};
+
+/**
+ * Every header a request signed with AWS Signature Version 4 sends: those
+ * given, `host`, `x-amz-date`, the session token if any, and
+ * `authorization`, which signs all of them and the body. The path is used as
+ * it is, which is right for the only one KMS has, `/`.
+ *
+ * https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv-create-signed-request.html
+ */
+export function signV4(input: SigningInput): Record<string, string> {
+  const stamp = input.date.toISOString().replace(/[-:]|\.\d{3}/g, ''); // 20260930T120000Z
+  const day = stamp.slice(0, 8);
+  const headers: Record<string, string> = { host: input.url.host, 'x-amz-date': stamp };
+  for (const [name, value] of Object.entries(input.headers)) headers[name.toLowerCase()] = value;
+  if (input.credentials.sessionToken) headers['x-amz-security-token'] = input.credentials.sessionToken;
+
+  const names = Object.keys(headers).sort();
+  const signed = names.join(';');
+  const request = [
+    input.method,
+    input.url.pathname,
+    canonicalQuery(input.url.searchParams),
+    ...names.map((name) => `${name}:${headers[name]!.trim().replace(/\s+/g, ' ')}`),
+    '',
+    signed,
+    sha256(input.body),
+  ].join('\n');
+  const scope = `${day}/${input.region}/${input.service}/aws4_request`;
+  const toSign = ['AWS4-HMAC-SHA256', stamp, scope, sha256(request)].join('\n');
+
+  let key = hmac(`AWS4${input.credentials.secretAccessKey}`, day);
+  for (const part of [input.region, input.service, 'aws4_request']) key = hmac(key, part);
+  const signature = createHmac('sha256', key).update(toSign, 'utf8').digest('hex');
+  return {
+    ...headers,
+    authorization: `AWS4-HMAC-SHA256 Credential=${input.credentials.accessKeyId}/${scope}, SignedHeaders=${signed}, Signature=${signature}`,
+  };
+}
+
+function canonicalQuery(params: URLSearchParams): string {
+  return [...params]
+    .map(([name, value]) => [encode(name), encode(value)])
+    .sort(([a, x], [b, y]) => (a! < b! ? -1 : a! > b! ? 1 : x! < y! ? -1 : x! > y! ? 1 : 0))
+    .map(([name, value]) => `${name}=${value}`)
+    .join('&');
+}
+
+/** RFC 3986: everything but letters, digits and `-._~` percent-encoded. */
+function encode(text: string): string {
+  return encodeURIComponent(text).replace(/[!'()*]/g, (char) => `%${char.charCodeAt(0).toString(16).toUpperCase()}`);
+}
+
+function sha256(text: string): string {
+  return createHash('sha256').update(text, 'utf8').digest('hex');
+}
+
+function hmac(key: string | Uint8Array, text: string) {
+  return createHmac('sha256', key).update(text, 'utf8').digest();
+}