was-teaching-server 0.9.1

package/dist/lib/keyEpoch.js

@@ -0,0 +1,75 @@
+/**
+ * Helpers for the client-declared key-epoch stamp on encrypted-Collection
+ * Resources (the `key-epochs` feature). A writer declares which epoch key
+ * encrypted a Resource's content so a reader can pick the right key BEFORE
+ * attempting decryption; the value is advisory metadata the server stores
+ * opaquely and never computes or verifies (a write may race a rotation).
+ *
+ * On a **content** write the epoch is declared via the `WAS-Key-Epoch` request
+ * header -- one mechanism that works uniformly for JSON, raw-stream binary, and
+ * multipart writes. It is deliberately NOT signature-covered (like `If-Match`):
+ * it is advisory client-declared metadata, not part of the capability
+ * invocation. A content write stores the header's value when present and CLEARS
+ * the stamp when absent -- the new ciphertext's epoch is unknown, and a stale
+ * stamp is worse than none (a reader falls back to `currentEpoch` and can try
+ * other epochs). A `PUT .../meta` may also declare `epoch` as a top-level member
+ * of the body (a sibling of `custom`), where omitting it PRESERVES the stored
+ * value -- see the `putMeta` handler.
+ *
+ * The only validation is that a present value is a non-empty string (400
+ * otherwise); the server never checks it against the Collection marker's epochs.
+ */
+import { InvalidRequestBodyError } from '../errors.js';
+/** The request header carrying the client-declared key-epoch on a content write. */
+export const KEY_EPOCH_HEADER = 'was-key-epoch';
+/**
+ * Parses the OPTIONAL `WAS-Key-Epoch` request header into the epoch stamp for a
+ * content write. Resolves `{ epoch: string }` for a non-empty single-valued
+ * header, `{ epoch: undefined }` when absent (the content write clears any
+ * stored stamp), and throws `invalid-request-body` (400) for an empty or
+ * array-valued header.
+ * @param options {object}
+ * @param options.headers {object}   the Fastify request headers
+ * @param [options.requestName] {string}   request name for the 400 error title
+ * @returns {{ epoch?: string }}
+ */
+export function parseKeyEpochHeader({ headers, requestName }) {
+    const value = headers[KEY_EPOCH_HEADER];
+    if (value === undefined) {
+        return {};
+    }
+    if (typeof value !== 'string' || value.length === 0) {
+        throw new InvalidRequestBodyError({
+            requestName,
+            detail: 'The "WAS-Key-Epoch" header must be a non-empty string.'
+        });
+    }
+    return { epoch: value };
+}
+/**
+ * Validates and extracts the OPTIONAL top-level `epoch` member of an Update
+ * Resource Metadata (`PUT .../meta`) body. Unlike a content write, a metadata
+ * write PRESERVES the stored epoch when the member is omitted (the stamp
+ * describes the content write, not the metadata write); a present value must be
+ * a non-empty string (400 otherwise). Returns `{ epoch: string }` when supplied,
+ * or `{}` when the member is absent (preserve).
+ * @param options {object}
+ * @param options.body {object}   the parsed request body (already known to be an object)
+ * @param [options.requestName] {string}   request name for the 400 error title
+ * @returns {{ epoch?: string }}
+ */
+export function parseMetaEpoch({ body, requestName }) {
+    if (!Object.hasOwn(body, 'epoch')) {
+        return {};
+    }
+    const value = body.epoch;
+    if (typeof value !== 'string' || value.length === 0) {
+        throw new InvalidRequestBodyError({
+            requestName,
+            detail: 'The "epoch" property must be a non-empty string.',
+            pointer: '/epoch'
+        });
+    }
+    return { epoch: value };
+}
+//# sourceMappingURL=keyEpoch.js.map

package/dist/lib/keyEpoch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keyEpoch.js","sourceRoot":"","sources":["../../src/lib/keyEpoch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAA;AAEtD,oFAAoF;AACpF,MAAM,CAAC,MAAM,gBAAgB,GAAG,eAAe,CAAA;AAE/C;;;;;;;;;;GAUG;AACH,MAAM,UAAU,mBAAmB,CAAC,EAClC,OAAO,EACP,WAAW,EAIZ;IACC,MAAM,KAAK,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAA;IACvC,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,OAAO,EAAE,CAAA;IACX,CAAC;IACD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACpD,MAAM,IAAI,uBAAuB,CAAC;YAChC,WAAW;YACX,MAAM,EAAE,wDAAwD;SACjE,CAAC,CAAA;IACJ,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,CAAA;AACzB,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,cAAc,CAAC,EAC7B,IAAI,EACJ,WAAW,EAIZ;IACC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,EAAE,CAAC;QAClC,OAAO,EAAE,CAAA;IACX,CAAC;IACD,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAA;IACxB,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACpD,MAAM,IAAI,uBAAuB,CAAC;YAChC,WAAW;YACX,MAAM,EAAE,kDAAkD;YAC1D,OAAO,EAAE,QAAQ;SAClB,CAAC,CAAA;IACJ,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,CAAA;AACzB,CAAC"}

package/dist/lib/keyedMutex.d.ts

@@ -0,0 +1,28 @@
+/**
+ * A keyed in-process mutex that serializes async functions per key, ported from
+ * the `@interop/edv-server` storage layer. The conditional-write path uses it to
+ * make a Resource's read-check-write atomic: two concurrent writers of the same
+ * Resource cannot both observe the same prior version and both succeed.
+ *
+ * This is a single-instance lock only. It does NOT coordinate writes across
+ * multiple server processes or a horizontally-scaled deployment -- that is out
+ * of scope for the reference server (see the spec's Conditional Requests note).
+ */
+/**
+ * Serializes async functions per key. `run` chains the given function onto the
+ * tail of the key's promise queue, so all functions for the same key execute
+ * strictly one at a time, in call order. Distinct keys run concurrently.
+ */
+export declare class KeyedMutex {
+    private readonly queues;
+    /**
+     * Runs `fn` once all previously-queued functions for `key` have settled,
+     * resolving (or rejecting) with `fn`'s result. The key's queue entry is
+     * cleaned up once it drains so the map does not grow without bound.
+     * @param key {string}   the serialization key (e.g. a per-Resource path)
+     * @param fn {() => Promise<T>}   the critical section to run under the lock
+     * @returns {Promise<T>}
+     */
+    run<T>(key: string, fn: () => Promise<T>): Promise<T>;
+}
+//# sourceMappingURL=keyedMutex.d.ts.map

package/dist/lib/keyedMutex.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keyedMutex.d.ts","sourceRoot":"","sources":["../../src/lib/keyedMutex.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;;;GAIG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAsC;IAE7D;;;;;;;OAOG;IACG,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;CAiB5D"}

package/dist/lib/keyedMutex.js

@@ -0,0 +1,45 @@
+/**
+ * A keyed in-process mutex that serializes async functions per key, ported from
+ * the `@interop/edv-server` storage layer. The conditional-write path uses it to
+ * make a Resource's read-check-write atomic: two concurrent writers of the same
+ * Resource cannot both observe the same prior version and both succeed.
+ *
+ * This is a single-instance lock only. It does NOT coordinate writes across
+ * multiple server processes or a horizontally-scaled deployment -- that is out
+ * of scope for the reference server (see the spec's Conditional Requests note).
+ */
+/**
+ * Serializes async functions per key. `run` chains the given function onto the
+ * tail of the key's promise queue, so all functions for the same key execute
+ * strictly one at a time, in call order. Distinct keys run concurrently.
+ */
+export class KeyedMutex {
+    queues = new Map();
+    /**
+     * Runs `fn` once all previously-queued functions for `key` have settled,
+     * resolving (or rejecting) with `fn`'s result. The key's queue entry is
+     * cleaned up once it drains so the map does not grow without bound.
+     * @param key {string}   the serialization key (e.g. a per-Resource path)
+     * @param fn {() => Promise<T>}   the critical section to run under the lock
+     * @returns {Promise<T>}
+     */
+    async run(key, fn) {
+        const previous = this.queues.get(key) ?? Promise.resolve();
+        const run = previous.then(fn, fn);
+        // Keep the chain alive even if `fn` rejects, so a failed critical section
+        // does not wedge the key's queue; track this swallowed-rejection tail so the
+        // queue entry can be reclaimed once it drains (unless a later call replaced
+        // it).
+        const tail = run.catch(() => { });
+        this.queues.set(key, tail);
+        try {
+            return await run;
+        }
+        finally {
+            if (this.queues.get(key) === tail) {
+                this.queues.delete(key);
+            }
+        }
+    }
+}
+//# sourceMappingURL=keyedMutex.js.map

package/dist/lib/keyedMutex.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keyedMutex.js","sourceRoot":"","sources":["../../src/lib/keyedMutex.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;;;GAIG;AACH,MAAM,OAAO,UAAU;IACJ,MAAM,GAAG,IAAI,GAAG,EAA4B,CAAA;IAE7D;;;;;;;OAOG;IACH,KAAK,CAAC,GAAG,CAAI,GAAW,EAAE,EAAoB;QAC5C,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,OAAO,CAAC,OAAO,EAAE,CAAA;QAC1D,MAAM,GAAG,GAAG,QAAQ,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,CAAC,CAAA;QACjC,0EAA0E;QAC1E,6EAA6E;QAC7E,4EAA4E;QAC5E,OAAO;QACP,MAAM,IAAI,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAA;QAChC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,CAAA;QAC1B,IAAI,CAAC;YACH,OAAO,MAAM,GAAG,CAAA;QAClB,CAAC;gBAAS,CAAC;YACT,IAAI,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,IAAI,EAAE,CAAC;gBAClC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;YACzB,CAAC;QACH,CAAC;IACH,CAAC;CACF"}

package/dist/lib/kmsModule.d.ts

@@ -0,0 +1,62 @@
+import type { IDID, KmsKeyDescription, KmsStoredKey } from '../types.js';
+/**
+ * Builds the public key-description projection of a stored key: the
+ * allowlisted public fields plus the live keystore `controller` (never any
+ * secret field), with the `publicAlias` / expanded `publicAliasTemplate`
+ * override applied to `id`. Applied identically at generate time and on every
+ * subsequent read, so descriptions are stable (the client caches them).
+ *
+ * @param options {object}
+ * @param options.key {KmsStoredKey}   the stored (secret-bearing) key
+ * @param options.controller {IDID}   the keystore's current controller
+ * @returns {KmsKeyDescription}
+ */
+export declare function describeKmsKey({ key, controller }: {
+    key: KmsStoredKey;
+    controller: IDID;
+}): KmsKeyDescription;
+/**
+ * Generates key material for a supported key type and assembles the stored
+ * key (full serialized form, secret material included) plus its public
+ * description. Field names are protocol-fixed: the asymmetric pairs carry
+ * `publicKeyMultibase` / `privateKeyMultibase`; the symmetric keys carry a
+ * base64url 256-bit `secret` (the webkms per-type key generators).
+ *
+ * @param options {object}
+ * @param options.keyId {string}   the full key URL (`<keystoreId>/keys/<localId>`)
+ * @param options.type {string}   the webkms key type
+ * @param options.controller {IDID}   the keystore's current controller (for
+ *   the returned description only -- never stored on the key)
+ * @param [options.maxCapabilityChainLength] {number}
+ * @param [options.publicAlias] {string}
+ * @param [options.publicAliasTemplate] {string}
+ * @returns {Promise<{ key: KmsStoredKey, keyDescription: KmsKeyDescription }>}
+ */
+export declare function generateKmsKey({ keyId, type, controller, maxCapabilityChainLength, publicAlias, publicAliasTemplate }: {
+    keyId: string;
+    type: string;
+    controller: IDID;
+    maxCapabilityChainLength?: number;
+    publicAlias?: string;
+    publicAliasTemplate?: string;
+}): Promise<{
+    key: KmsStoredKey;
+    keyDescription: KmsKeyDescription;
+}>;
+/**
+ * Runs a key operation envelope against a stored key, dispatching on
+ * `(key.type, operation.type)`. An operation this module does not serve for
+ * the key's type -- or does not recognize at all -- is a clean 400
+ * `UnsupportedKeyOperationError`.
+ *
+ * @param options {object}
+ * @param options.key {KmsStoredKey}   the stored (secret-bearing) key
+ * @param options.operation {Record<string, unknown>}   the validated envelope
+ * @returns {Promise<object>}   the operation's wire result (`signatureValue` /
+ *   `verified` / `secret` / `wrappedKey` / `unwrappedKey`)
+ */
+export declare function runKeyOperation({ key, operation }: {
+    key: KmsStoredKey;
+    operation: Record<string, unknown>;
+}): Promise<object>;
+//# sourceMappingURL=kmsModule.d.ts.map

package/dist/lib/kmsModule.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kmsModule.d.ts","sourceRoot":"","sources":["../../src/lib/kmsModule.ts"],"names":[],"mappings":"AA4BA,OAAO,KAAK,EAAE,IAAI,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAsExE;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,EAC7B,GAAG,EACH,UAAU,EACX,EAAE;IACD,GAAG,EAAE,YAAY,CAAA;IACjB,UAAU,EAAE,IAAI,CAAA;CACjB,GAAG,iBAAiB,CAmBpB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,cAAc,CAAC,EACnC,KAAK,EACL,IAAI,EACJ,UAAU,EACV,wBAAwB,EACxB,WAAW,EACX,mBAAmB,EACpB,EAAE;IACD,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;IACZ,UAAU,EAAE,IAAI,CAAA;IAChB,wBAAwB,CAAC,EAAE,MAAM,CAAA;IACjC,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,mBAAmB,CAAC,EAAE,MAAM,CAAA;CAC7B,GAAG,OAAO,CAAC;IAAE,GAAG,EAAE,YAAY,CAAC;IAAC,cAAc,EAAE,iBAAiB,CAAA;CAAE,CAAC,CAoCpE;AAgND;;;;;;;;;;;GAWG;AACH,wBAAsB,eAAe,CAAC,EACpC,GAAG,EACH,SAAS,EACV,EAAE;IACD,GAAG,EAAE,YAAY,CAAA;IACjB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACnC,GAAG,OAAO,CAAC,MAAM,CAAC,CAoBlB"}

package/dist/lib/kmsModule.js

@@ -0,0 +1,327 @@
+/**
+ * The single in-process WebKMS module this server hard-wires (`local-v1`),
+ * collecting the module's parts in one file: a pure-crypto core per key type,
+ * an operation dispatch table keyed by `(key type, operation type)`, and the
+ * generate/describe orchestration (record assembly, `publicAlias` /
+ * `publicAliasTemplate` expansion). The module never touches storage -- the
+ * request layer loads/inserts `KmsKeyRecord`s through the storage backend and
+ * hands this module the (secret-bearing) stored key.
+ *
+ * Custody draws the line on what is served (see the roadmap's wire contract):
+ * every operation here requires the custodial secret -- Ed25519 sign, X25519
+ * deriveSecret, HMAC sign/verify, AES-KW wrap/unwrap. Asymmetric verify needs
+ * only the public key and is deliberately not served (client-local instead);
+ * requesting it is a clean 400.
+ */
+import { createCipheriv, createDecipheriv, createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
+import { Ed25519VerificationKey } from '@interop/ed25519-verification-key';
+import { X25519KeyAgreementKey2020 } from '@interop/x25519-key-agreement-key';
+import { InvalidRequestBodyError, UnsupportedKeyOperationError } from '../errors.js';
+/** The JSON-LD context each supported key type's description carries. */
+const KEY_TYPE_CONTEXTS = {
+    Ed25519VerificationKey2020: 'https://w3id.org/security/suites/ed25519-2020/v1',
+    X25519KeyAgreementKey2020: 'https://w3id.org/security/suites/x25519-2020/v1',
+    Sha256HmacKey2019: 'https://w3id.org/security/suites/hmac-2019/v1',
+    AesKeyWrappingKey2019: 'https://w3id.org/security/suites/aes-2019/v1'
+};
+/**
+ * AES Key Wrap (RFC 3394) parameters: AES-256 in key-wrap mode with the RFC's
+ * default initial value. The IV is the integrity check -- `decipher.final()`
+ * throws when the unwrapped output would not reproduce it (i.e. the wrong KEK
+ * or corrupted ciphertext).
+ */
+const AES_KW_ALGORITHM = 'id-aes256-wrap';
+const AES_KW_DEFAULT_IV = Buffer.alloc(8, 0xa6);
+/** Decodes a base64url (no padding) operation field into bytes. */
+function decodeBase64url({ value, field, requestName }) {
+    if (typeof value !== 'string' || value.length === 0) {
+        throw new InvalidRequestBodyError({
+            requestName,
+            detail: `Operation "${field}" must be a non-empty base64url string.`,
+            pointer: `#/${field}`
+        });
+    }
+    return Buffer.from(value, 'base64url');
+}
+/**
+ * Expands a `publicAliasTemplate` against the key description, using the
+ * `url-template` package (RFC 6570): `{var}` substitutes the
+ * percent-encoded description field, `{+var}` substitutes it raw (a typical
+ * template is `{+controller}#{publicKeyMultibase}`). An unknown
+ * variable expands to the empty string, as in RFC 6570.
+ *
+ * @param options {object}
+ * @param options.template {string}
+ * @param options.description {KmsKeyDescription}   expansion variables
+ * @returns {string}
+ */
+function expandAliasTemplate({ template, description }) {
+    const variables = description;
+    return template.replace(/\{(\+?)([A-Za-z0-9_]+)\}/g, (_match, rawModifier, name) => {
+        const value = variables[name];
+        const expanded = typeof value === 'string' ? value : '';
+        return rawModifier === '+' ? expanded : encodeURIComponent(expanded);
+    });
+}
+/**
+ * Builds the public key-description projection of a stored key: the
+ * allowlisted public fields plus the live keystore `controller` (never any
+ * secret field), with the `publicAlias` / expanded `publicAliasTemplate`
+ * override applied to `id`. Applied identically at generate time and on every
+ * subsequent read, so descriptions are stable (the client caches them).
+ *
+ * @param options {object}
+ * @param options.key {KmsStoredKey}   the stored (secret-bearing) key
+ * @param options.controller {IDID}   the keystore's current controller
+ * @returns {KmsKeyDescription}
+ */
+export function describeKmsKey({ key, controller }) {
+    const description = {
+        '@context': key['@context'],
+        id: key.id,
+        type: key.type,
+        ...(key.publicKeyMultibase !== undefined && {
+            publicKeyMultibase: key.publicKeyMultibase
+        }),
+        controller
+    };
+    if (key.publicAlias !== undefined) {
+        description.id = key.publicAlias;
+    }
+    else if (key.publicAliasTemplate !== undefined) {
+        description.id = expandAliasTemplate({
+            template: key.publicAliasTemplate,
+            description
+        });
+    }
+    return description;
+}
+/**
+ * Generates key material for a supported key type and assembles the stored
+ * key (full serialized form, secret material included) plus its public
+ * description. Field names are protocol-fixed: the asymmetric pairs carry
+ * `publicKeyMultibase` / `privateKeyMultibase`; the symmetric keys carry a
+ * base64url 256-bit `secret` (the webkms per-type key generators).
+ *
+ * @param options {object}
+ * @param options.keyId {string}   the full key URL (`<keystoreId>/keys/<localId>`)
+ * @param options.type {string}   the webkms key type
+ * @param options.controller {IDID}   the keystore's current controller (for
+ *   the returned description only -- never stored on the key)
+ * @param [options.maxCapabilityChainLength] {number}
+ * @param [options.publicAlias] {string}
+ * @param [options.publicAliasTemplate] {string}
+ * @returns {Promise<{ key: KmsStoredKey, keyDescription: KmsKeyDescription }>}
+ */
+export async function generateKmsKey({ keyId, type, controller, maxCapabilityChainLength, publicAlias, publicAliasTemplate }) {
+    // `Object.hasOwn`, not `KEY_TYPE_CONTEXTS[type] === undefined`: `type` is
+    // client-supplied, so a prototype-chain name (`constructor`, `toString`,
+    // `hasOwnProperty`, ...) would otherwise resolve to an inherited `Object`
+    // member and slip past the fail-closed rejection into a stored key record.
+    if (!Object.hasOwn(KEY_TYPE_CONTEXTS, type)) {
+        throw new InvalidRequestBodyError({
+            requestName: 'Generate Key',
+            detail: `Unsupported key type "${type}".`,
+            pointer: '#/invocationTarget/type'
+        });
+    }
+    const context = KEY_TYPE_CONTEXTS[type];
+    const key = { '@context': context, id: keyId, type };
+    if (type === 'Ed25519VerificationKey2020') {
+        const keyPair = await Ed25519VerificationKey.generate();
+        key.publicKeyMultibase = keyPair.publicKeyMultibase;
+        key.privateKeyMultibase = keyPair.privateKeyMultibase;
+    }
+    else if (type === 'X25519KeyAgreementKey2020') {
+        const keyPair = await X25519KeyAgreementKey2020.generate();
+        key.publicKeyMultibase = keyPair.publicKeyMultibase;
+        key.privateKeyMultibase = keyPair.privateKeyMultibase;
+    }
+    else {
+        // Sha256HmacKey2019 / AesKeyWrappingKey2019: a 256-bit symmetric secret.
+        key.secret = randomBytes(32).toString('base64url');
+    }
+    if (maxCapabilityChainLength !== undefined) {
+        key.maxCapabilityChainLength = maxCapabilityChainLength;
+    }
+    if (publicAlias !== undefined) {
+        key.publicAlias = publicAlias;
+    }
+    if (publicAliasTemplate !== undefined) {
+        key.publicAliasTemplate = publicAliasTemplate;
+    }
+    return { key, keyDescription: describeKmsKey({ key, controller }) };
+}
+/**
+ * SignOperation on an Ed25519 key: signs the `verifyData` bytes with the
+ * custodial private key. The signature is not a secret, so serving it is the
+ * custody model WebKMS is built for.
+ */
+async function ed25519Sign({ key, operation }) {
+    const data = decodeBase64url({
+        value: operation.verifyData,
+        field: 'verifyData',
+        requestName: 'Sign Operation'
+    });
+    const keyPair = await Ed25519VerificationKey.from({ ...key });
+    const signature = await keyPair.signer().sign({ data });
+    return { signatureValue: Buffer.from(signature).toString('base64url') };
+}
+/**
+ * DeriveSecretOperation on an X25519 key: raw ECDH against the submitted peer
+ * public key -- no KDF is applied; the caller runs the shared secret through
+ * one. A peer whose `type` does not match the key's is a clean 400 (the client
+ * pre-checks, so only non-client callers hit this).
+ */
+async function x25519DeriveSecret({ key, operation }) {
+    const requestName = 'Derive Secret Operation';
+    const publicKey = operation.publicKey;
+    if (typeof publicKey !== 'object' || publicKey === null) {
+        throw new InvalidRequestBodyError({
+            requestName,
+            detail: 'Operation "publicKey" must be a public key object.',
+            pointer: '#/publicKey'
+        });
+    }
+    if (publicKey.type !== key.type) {
+        throw new InvalidRequestBodyError({
+            requestName,
+            detail: `The given public key type "${publicKey.type}" does not match the` +
+                ` key agreement key's type "${key.type}".`,
+            pointer: '#/publicKey/type'
+        });
+    }
+    const keyPair = await X25519KeyAgreementKey2020.from({ ...key });
+    let secret;
+    try {
+        secret = await keyPair.deriveSecret({ publicKey });
+    }
+    catch {
+        // A malformed / wrong-header `publicKeyMultibase` is a client error.
+        throw new InvalidRequestBodyError({
+            requestName,
+            detail: 'Operation "publicKey.publicKeyMultibase" is not a valid key.',
+            pointer: '#/publicKey/publicKeyMultibase'
+        });
+    }
+    return { secret: Buffer.from(secret).toString('base64url') };
+}
+/** Computes the HMAC-SHA-256 of `verifyData` under the key's secret. */
+function hmacDigest({ key, operation, requestName }) {
+    const data = decodeBase64url({
+        value: operation.verifyData,
+        field: 'verifyData',
+        requestName
+    });
+    const secret = Buffer.from(key.secret, 'base64url');
+    return createHmac('sha256', secret).update(data).digest();
+}
+/** SignOperation on an HMAC key. */
+async function hmacSign({ key, operation }) {
+    const digest = hmacDigest({ key, operation, requestName: 'Sign Operation' });
+    return { signatureValue: digest.toString('base64url') };
+}
+/**
+ * VerifyOperation on an HMAC key -- the one served verify (a client cannot
+ * check an HMAC without the symmetric secret). A wrong-*length*
+ * `signatureValue` is an ordinary `verified: false`, checked before
+ * `timingSafeEqual` (which throws on mismatched lengths).
+ */
+async function hmacVerify({ key, operation }) {
+    const requestName = 'Verify Operation';
+    const signature = decodeBase64url({
+        value: operation.signatureValue,
+        field: 'signatureValue',
+        requestName
+    });
+    const expected = hmacDigest({ key, operation, requestName });
+    const verified = signature.length === expected.length && timingSafeEqual(signature, expected);
+    return { verified };
+}
+/** WrapKeyOperation on an AES-KW key encryption key. */
+async function aesWrapKey({ key, operation }) {
+    const unwrapped = decodeBase64url({
+        value: operation.unwrappedKey,
+        field: 'unwrappedKey',
+        requestName: 'Wrap Key Operation'
+    });
+    const secret = Buffer.from(key.secret, 'base64url');
+    const cipher = createCipheriv(AES_KW_ALGORITHM, secret, AES_KW_DEFAULT_IV);
+    const wrapped = Buffer.concat([cipher.update(unwrapped), cipher.final()]);
+    return { wrappedKey: wrapped.toString('base64url') };
+}
+/**
+ * UnwrapKeyOperation on an AES-KW key encryption key. A failed unwrap -- the
+ * RFC 3394 integrity check rejecting the ciphertext (wrong KEK, corrupted
+ * `wrappedKey`) -- resolves `unwrappedKey: null` rather than erroring: that is
+ * the client's documented contract (`Kek.unwrapKey` resolves null when the key
+ * does not match).
+ */
+async function aesUnwrapKey({ key, operation }) {
+    const wrapped = decodeBase64url({
+        value: operation.wrappedKey,
+        field: 'wrappedKey',
+        requestName: 'Unwrap Key Operation'
+    });
+    const secret = Buffer.from(key.secret, 'base64url');
+    try {
+        const decipher = createDecipheriv(AES_KW_ALGORITHM, secret, AES_KW_DEFAULT_IV);
+        const unwrapped = Buffer.concat([
+            decipher.update(wrapped),
+            decipher.final()
+        ]);
+        return { unwrappedKey: unwrapped.toString('base64url') };
+    }
+    catch {
+        return { unwrappedKey: null };
+    }
+}
+/**
+ * The operation dispatch table: which operation envelope `type`s this module
+ * serves for each key type, and the pure-crypto implementation for each pair.
+ * Deliberate omissions (custody is the criterion): `VerifyOperation` on the
+ * asymmetric and key-agreement types (verify client-locally against the
+ * description's `publicKeyMultibase`), and every cross-type combination.
+ */
+const KEY_OPERATIONS = {
+    Ed25519VerificationKey2020: { SignOperation: ed25519Sign },
+    X25519KeyAgreementKey2020: { DeriveSecretOperation: x25519DeriveSecret },
+    Sha256HmacKey2019: { SignOperation: hmacSign, VerifyOperation: hmacVerify },
+    AesKeyWrappingKey2019: {
+        WrapKeyOperation: aesWrapKey,
+        UnwrapKeyOperation: aesUnwrapKey
+    }
+};
+/**
+ * Runs a key operation envelope against a stored key, dispatching on
+ * `(key.type, operation.type)`. An operation this module does not serve for
+ * the key's type -- or does not recognize at all -- is a clean 400
+ * `UnsupportedKeyOperationError`.
+ *
+ * @param options {object}
+ * @param options.key {KmsStoredKey}   the stored (secret-bearing) key
+ * @param options.operation {Record<string, unknown>}   the validated envelope
+ * @returns {Promise<object>}   the operation's wire result (`signatureValue` /
+ *   `verified` / `secret` / `wrappedKey` / `unwrappedKey`)
+ */
+export async function runKeyOperation({ key, operation }) {
+    const operationType = operation.type;
+    // `Object.hasOwn` at both levels: `key.type` and `operationType` are both
+    // client-influenced, so plain-object indexing could otherwise resolve an
+    // inherited `Object` member (`constructor`, `toString`, ...) to a truthy
+    // function and bypass this fail-closed gate.
+    const operations = Object.hasOwn(KEY_OPERATIONS, key.type)
+        ? KEY_OPERATIONS[key.type]
+        : undefined;
+    const runOperation = operations && Object.hasOwn(operations, operationType)
+        ? operations[operationType]
+        : undefined;
+    if (runOperation === undefined) {
+        throw new UnsupportedKeyOperationError({
+            operationType,
+            keyType: key.type
+        });
+    }
+    return await runOperation({ key, operation });
+}
+//# sourceMappingURL=kmsModule.js.map

package/dist/lib/kmsModule.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"kmsModule.js","sourceRoot":"","sources":["../../src/lib/kmsModule.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,EACL,cAAc,EACd,gBAAgB,EAChB,UAAU,EACV,WAAW,EACX,eAAe,EAChB,MAAM,aAAa,CAAA;AACpB,OAAO,EAAE,sBAAsB,EAAE,MAAM,mCAAmC,CAAA;AAC1E,OAAO,EAAE,yBAAyB,EAAE,MAAM,mCAAmC,CAAA;AAC7E,OAAO,EACL,uBAAuB,EACvB,4BAA4B,EAC7B,MAAM,cAAc,CAAA;AAGrB,yEAAyE;AACzE,MAAM,iBAAiB,GAA2B;IAChD,0BAA0B,EACxB,kDAAkD;IACpD,yBAAyB,EAAE,iDAAiD;IAC5E,iBAAiB,EAAE,+CAA+C;IAClE,qBAAqB,EAAE,8CAA8C;CACtE,CAAA;AAED;;;;;GAKG;AACH,MAAM,gBAAgB,GAAG,gBAAgB,CAAA;AACzC,MAAM,iBAAiB,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,CAAA;AAE/C,mEAAmE;AACnE,SAAS,eAAe,CAAC,EACvB,KAAK,EACL,KAAK,EACL,WAAW,EAKZ;IACC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACpD,MAAM,IAAI,uBAAuB,CAAC;YAChC,WAAW;YACX,MAAM,EAAE,cAAc,KAAK,yCAAyC;YACpE,OAAO,EAAE,KAAK,KAAK,EAAE;SACtB,CAAC,CAAA;IACJ,CAAC;IACD,OAAO,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE,WAAW,CAAC,CAAA;AACxC,CAAC;AAED;;;;;;;;;;;GAWG;AACH,SAAS,mBAAmB,CAAC,EAC3B,QAAQ,EACR,WAAW,EAIZ;IACC,MAAM,SAAS,GAAG,WAAiD,CAAA;IACnE,OAAO,QAAQ,CAAC,OAAO,CACrB,2BAA2B,EAC3B,CAAC,MAAM,EAAE,WAAmB,EAAE,IAAY,EAAE,EAAE;QAC5C,MAAM,KAAK,GAAG,SAAS,CAAC,IAAI,CAAC,CAAA;QAC7B,MAAM,QAAQ,GAAG,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAA;QACvD,OAAO,WAAW,KAAK,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,kBAAkB,CAAC,QAAQ,CAAC,CAAA;IACtE,CAAC,CACF,CAAA;AACH,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,cAAc,CAAC,EAC7B,GAAG,EACH,UAAU,EAIX;IACC,MAAM,WAAW,GAAsB;QACrC,UAAU,EAAE,GAAG,CAAC,UAAU,CAAC;QAC3B,EAAE,EAAE,GAAG,CAAC,EAAE;QACV,IAAI,EAAE,GAAG,CAAC,IAAI;QACd,GAAG,CAAC,GAAG,CAAC,kBAAkB,KAAK,SAAS,IAAI;YAC1C,kBAAkB,EAAE,GAAG,CAAC,kBAAkB;SAC3C,CAAC;QACF,UAAU;KACX,CAAA;IACD,IAAI,GAAG,CAAC,WAAW,KAAK,SAAS,EAAE,CAAC;QAClC,WAAW,CAAC,EAAE,GAAG,GAAG,CAAC,WAAW,CAAA;IAClC,CAAC;SAAM,IAAI,GAAG,CAAC,mBAAmB,KAAK,SAAS,EAAE,CAAC;QACjD,WAAW,CAAC,EAAE,GAAG,mBAAmB,CAAC;YACnC,QAAQ,EAAE,GAAG,CAAC,mBAAmB;YACjC,WAAW;SACZ,CAAC,CAAA;IACJ,CAAC;IACD,OAAO,WAAW,CAAA;AACpB,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,EACnC,KAAK,EACL,IAAI,EACJ,UAAU,EACV,wBAAwB,EACxB,WAAW,EACX,mBAAmB,EAQpB;IACC,0EAA0E;IAC1E,yEAAyE;IACzE,0EAA0E;IAC1E,2EAA2E;IAC3E,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,iBAAiB,EAAE,IAAI,CAAC,EAAE,CAAC;QAC5C,MAAM,IAAI,uBAAuB,CAAC;YAChC,WAAW,EAAE,cAAc;YAC3B,MAAM,EAAE,yBAAyB,IAAI,IAAI;YACzC,OAAO,EAAE,yBAAyB;SACnC,CAAC,CAAA;IACJ,CAAC;IACD,MAAM,OAAO,GAAG,iBAAiB,CAAC,IAAI,CAAE,CAAA;IACxC,MAAM,GAAG,GAAiB,EAAE,UAAU,EAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAA;IAClE,IAAI,IAAI,KAAK,4BAA4B,EAAE,CAAC;QAC1C,MAAM,OAAO,GAAG,MAAM,sBAAsB,CAAC,QAAQ,EAAE,CAAA;QACvD,GAAG,CAAC,kBAAkB,GAAG,OAAO,CAAC,kBAAkB,CAAA;QACnD,GAAG,CAAC,mBAAmB,GAAG,OAAO,CAAC,mBAAmB,CAAA;IACvD,CAAC;SAAM,IAAI,IAAI,KAAK,2BAA2B,EAAE,CAAC;QAChD,MAAM,OAAO,GAAG,MAAM,yBAAyB,CAAC,QAAQ,EAAE,CAAA;QAC1D,GAAG,CAAC,kBAAkB,GAAG,OAAO,CAAC,kBAAkB,CAAA;QACnD,GAAG,CAAC,mBAAmB,GAAG,OAAO,CAAC,mBAAmB,CAAA;IACvD,CAAC;SAAM,CAAC;QACN,yEAAyE;QACzE,GAAG,CAAC,MAAM,GAAG,WAAW,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAA;IACpD,CAAC;IACD,IAAI,wBAAwB,KAAK,SAAS,EAAE,CAAC;QAC3C,GAAG,CAAC,wBAAwB,GAAG,wBAAwB,CAAA;IACzD,CAAC;IACD,IAAI,WAAW,KAAK,SAAS,EAAE,CAAC;QAC9B,GAAG,CAAC,WAAW,GAAG,WAAW,CAAA;IAC/B,CAAC;IACD,IAAI,mBAAmB,KAAK,SAAS,EAAE,CAAC;QACtC,GAAG,CAAC,mBAAmB,GAAG,mBAAmB,CAAA;IAC/C,CAAC;IACD,OAAO,EAAE,GAAG,EAAE,cAAc,EAAE,cAAc,CAAC,EAAE,GAAG,EAAE,UAAU,EAAE,CAAC,EAAE,CAAA;AACrE,CAAC;AAED;;;;GAIG;AACH,KAAK,UAAU,WAAW,CAAC,EACzB,GAAG,EACH,SAAS,EAIV;IACC,MAAM,IAAI,GAAG,eAAe,CAAC;QAC3B,KAAK,EAAE,SAAS,CAAC,UAAU;QAC3B,KAAK,EAAE,YAAY;QACnB,WAAW,EAAE,gBAAgB;KAC9B,CAAC,CAAA;IACF,MAAM,OAAO,GAAG,MAAM,sBAAsB,CAAC,IAAI,CAAC,EAAE,GAAG,GAAG,EAAE,CAAC,CAAA;IAC7D,MAAM,SAAS,GAAG,MAAM,OAAO,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,CAAC,CAAA;IACvD,OAAO,EAAE,cAAc,EAAE,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAA;AACzE,CAAC;AAED;;;;;GAKG;AACH,KAAK,UAAU,kBAAkB,CAAC,EAChC,GAAG,EACH,SAAS,EAIV;IACC,MAAM,WAAW,GAAG,yBAAyB,CAAA;IAC7C,MAAM,SAAS,GAAG,SAAS,CAAC,SACgC,CAAA;IAC5D,IAAI,OAAO,SAAS,KAAK,QAAQ,IAAI,SAAS,KAAK,IAAI,EAAE,CAAC;QACxD,MAAM,IAAI,uBAAuB,CAAC;YAChC,WAAW;YACX,MAAM,EAAE,oDAAoD;YAC5D,OAAO,EAAE,aAAa;SACvB,CAAC,CAAA;IACJ,CAAC;IACD,IAAI,SAAS,CAAC,IAAI,KAAK,GAAG,CAAC,IAAI,EAAE,CAAC;QAChC,MAAM,IAAI,uBAAuB,CAAC;YAChC,WAAW;YACX,MAAM,EACJ,8BAA8B,SAAS,CAAC,IAAI,sBAAsB;gBAClE,8BAA8B,GAAG,CAAC,IAAI,IAAI;YAC5C,OAAO,EAAE,kBAAkB;SAC5B,CAAC,CAAA;IACJ,CAAC;IACD,MAAM,OAAO,GAAG,MAAM,yBAAyB,CAAC,IAAI,CAAC,EAAE,GAAG,GAAG,EAAE,CAAC,CAAA;IAChE,IAAI,MAAkB,CAAA;IACtB,IAAI,CAAC;QACH,MAAM,GAAG,MAAM,OAAO,CAAC,YAAY,CAAC,EAAE,SAAS,EAAE,CAAC,CAAA;IACpD,CAAC;IAAC,MAAM,CAAC;QACP,qEAAqE;QACrE,MAAM,IAAI,uBAAuB,CAAC;YAChC,WAAW;YACX,MAAM,EAAE,8DAA8D;YACtE,OAAO,EAAE,gCAAgC;SAC1C,CAAC,CAAA;IACJ,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAA;AAC9D,CAAC;AAED,wEAAwE;AACxE,SAAS,UAAU,CAAC,EAClB,GAAG,EACH,SAAS,EACT,WAAW,EAKZ;IACC,MAAM,IAAI,GAAG,eAAe,CAAC;QAC3B,KAAK,EAAE,SAAS,CAAC,UAAU;QAC3B,KAAK,EAAE,YAAY;QACnB,WAAW;KACZ,CAAC,CAAA;IACF,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,MAAgB,EAAE,WAAW,CAAC,CAAA;IAC7D,OAAO,UAAU,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,CAAA;AAC3D,CAAC;AAED,oCAAoC;AACpC,KAAK,UAAU,QAAQ,CAAC,EACtB,GAAG,EACH,SAAS,EAIV;IACC,MAAM,MAAM,GAAG,UAAU,CAAC,EAAE,GAAG,EAAE,SAAS,EAAE,WAAW,EAAE,gBAAgB,EAAE,CAAC,CAAA;IAC5E,OAAO,EAAE,cAAc,EAAE,MAAM,CAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAA;AACzD,CAAC;AAED;;;;;GAKG;AACH,KAAK,UAAU,UAAU,CAAC,EACxB,GAAG,EACH,SAAS,EAIV;IACC,MAAM,WAAW,GAAG,kBAAkB,CAAA;IACtC,MAAM,SAAS,GAAG,eAAe,CAAC;QAChC,KAAK,EAAE,SAAS,CAAC,cAAc;QAC/B,KAAK,EAAE,gBAAgB;QACvB,WAAW;KACZ,CAAC,CAAA;IACF,MAAM,QAAQ,GAAG,UAAU,CAAC,EAAE,GAAG,EAAE,SAAS,EAAE,WAAW,EAAE,CAAC,CAAA;IAC5D,MAAM,QAAQ,GACZ,SAAS,CAAC,MAAM,KAAK,QAAQ,CAAC,MAAM,IAAI,eAAe,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAA;IAC9E,OAAO,EAAE,QAAQ,EAAE,CAAA;AACrB,CAAC;AAED,wDAAwD;AACxD,KAAK,UAAU,UAAU,CAAC,EACxB,GAAG,EACH,SAAS,EAIV;IACC,MAAM,SAAS,GAAG,eAAe,CAAC;QAChC,KAAK,EAAE,SAAS,CAAC,YAAY;QAC7B,KAAK,EAAE,cAAc;QACrB,WAAW,EAAE,oBAAoB;KAClC,CAAC,CAAA;IACF,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,MAAgB,EAAE,WAAW,CAAC,CAAA;IAC7D,MAAM,MAAM,GAAG,cAAc,CAAC,gBAAgB,EAAE,MAAM,EAAE,iBAAiB,CAAC,CAAA;IAC1E,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAA;IACzE,OAAO,EAAE,UAAU,EAAE,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAA;AACtD,CAAC;AAED;;;;;;GAMG;AACH,KAAK,UAAU,YAAY,CAAC,EAC1B,GAAG,EACH,SAAS,EAIV;IACC,MAAM,OAAO,GAAG,eAAe,CAAC;QAC9B,KAAK,EAAE,SAAS,CAAC,UAAU;QAC3B,KAAK,EAAE,YAAY;QACnB,WAAW,EAAE,sBAAsB;KACpC,CAAC,CAAA;IACF,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,MAAgB,EAAE,WAAW,CAAC,CAAA;IAC7D,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,gBAAgB,CAC/B,gBAAgB,EAChB,MAAM,EACN,iBAAiB,CAClB,CAAA;QACD,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,CAAC;YAC9B,QAAQ,CAAC,MAAM,CAAC,OAAO,CAAC;YACxB,QAAQ,CAAC,KAAK,EAAE;SACjB,CAAC,CAAA;QACF,OAAO,EAAE,YAAY,EAAE,SAAS,CAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAA;IAC1D,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,YAAY,EAAE,IAAI,EAAE,CAAA;IAC/B,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,cAAc,GAShB;IACF,0BAA0B,EAAE,EAAE,aAAa,EAAE,WAAW,EAAE;IAC1D,yBAAyB,EAAE,EAAE,qBAAqB,EAAE,kBAAkB,EAAE;IACxE,iBAAiB,EAAE,EAAE,aAAa,EAAE,QAAQ,EAAE,eAAe,EAAE,UAAU,EAAE;IAC3E,qBAAqB,EAAE;QACrB,gBAAgB,EAAE,UAAU;QAC5B,kBAAkB,EAAE,YAAY;KACjC;CACF,CAAA;AAED;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,EACpC,GAAG,EACH,SAAS,EAIV;IACC,MAAM,aAAa,GAAG,SAAS,CAAC,IAAc,CAAA;IAC9C,0EAA0E;IAC1E,yEAAyE;IACzE,yEAAyE;IACzE,6CAA6C;IAC7C,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,CAAC,cAAc,EAAE,GAAG,CAAC,IAAI,CAAC;QACxD,CAAC,CAAC,cAAc,CAAC,GAAG,CAAC,IAAI,CAAC;QAC1B,CAAC,CAAC,SAAS,CAAA;IACb,MAAM,YAAY,GAChB,UAAU,IAAI,MAAM,CAAC,MAAM,CAAC,UAAU,EAAE,aAAa,CAAC;QACpD,CAAC,CAAC,UAAU,CAAC,aAAa,CAAC;QAC3B,CAAC,CAAC,SAAS,CAAA;IACf,IAAI,YAAY,KAAK,SAAS,EAAE,CAAC;QAC/B,MAAM,IAAI,4BAA4B,CAAC;YACrC,aAAa;YACb,OAAO,EAAE,GAAG,CAAC,IAAI;SAClB,CAAC,CAAA;IACJ,CAAC;IACD,OAAO,MAAM,YAAY,CAAC,EAAE,GAAG,EAAE,SAAS,EAAE,CAAC,CAAA;AAC/C,CAAC"}

package/dist/lib/kmsRecordCipher.d.ts

@@ -0,0 +1,82 @@
+import type { KmsKeyRecord, RecordKek, KmsRecordKekRegistry } from '../types.js';
+/**
+ * The plaintext allowlist: the `KmsStoredKey` fields that stay in the clear (and
+ * queryable) at rest. EVERY other field of `key` -- `privateKeyMultibase`,
+ * `secret`, and any secret-bearing field added later -- is swept into the
+ * envelope, so new secrets are protected by default unless explicitly added
+ * here. (Bedrock additionally lists `controller`; this server never stores
+ * `controller` on the key -- it is read from the live keystore config at
+ * description time -- so it is simply absent.)
+ */
+export declare const PLAINTEXT_KEY_FIELDS: ReadonlySet<string>;
+/**
+ * Derives a KEK's non-secret, stable id from its raw key bytes: a SHA-256 digest
+ * (one-way, so storing it per record leaks nothing about the key). Self-
+ * describing and deterministic, so a rotated-in KEK gets a stable id from its
+ * material alone -- the convention bedrock follows.
+ * @param key {Buffer}   the 32-byte AES-256 KEK
+ * @returns {string}   the derived `urn:kek:sha256:<hex>` id
+ */
+export declare function deriveKekId(key: Buffer): string;
+/**
+ * Parses a `secretKeyMultibase` (base58btc Multikey) AES-256 KEK into a
+ * `RecordKek` (its raw key plus a derived id). Throws a plain `Error` on a
+ * malformed value -- callers are config parsing (fails startup) and tests, not
+ * the request path. The error messages name `label` (the offending config
+ * variable, e.g. a `KMS_RECORD_KEKS entry N` position) but NEVER echo the secret
+ * value itself.
+ * @param secretKeyMultibase {string}   the multibase (`z...`) KEK value
+ * @param [label] {string}   the config source named in error messages
+ *   (defaults to `KMS_RECORD_KEK`)
+ * @returns {RecordKek}
+ */
+export declare function parseKekMultibase(secretKeyMultibase: string, label?: string): RecordKek;
+/**
+ * The KEK that wraps NEW records, or `undefined` when encryption is disabled
+ * (no registry, or `currentKekId: null`).
+ * @param [registry] {KmsRecordKekRegistry}
+ * @returns {RecordKek | undefined}
+ */
+export declare function currentRecordKek(registry?: KmsRecordKekRegistry): RecordKek | undefined;
+/**
+ * A KEK-lookup function over a registry, resolving a record's stored `kekId` to
+ * its `RecordKek` for decryption (`undefined` when the KEK is not registered, or
+ * there is no registry at all). The decrypt seam for the pass-through /
+ * rotation upgrade paths.
+ * @param [registry] {KmsRecordKekRegistry}
+ * @returns {(kekId: string) => RecordKek | undefined}
+ */
+export declare function recordKekLoader(registry?: KmsRecordKekRegistry): (kekId: string) => RecordKek | undefined;
+/**
+ * Encrypts the secret-bearing fields of a key record under a KEK, returning a
+ * record whose `key` carries the allowlisted plaintext fields plus an
+ * `encrypted` envelope in place of the secrets. Pure: the KEK is injected, no
+ * storage or env access. The record's non-`key` members (`keystoreId`,
+ * `localId`, `meta`) are unchanged.
+ * @param options {object}
+ * @param options.record {KmsKeyRecord}   the plaintext (secret-bearing) record
+ * @param options.kek {RecordKek}   the KEK to wrap the fresh CEK under
+ * @returns {KmsKeyRecord}   the at-rest record (secrets replaced by `encrypted`)
+ */
+export declare function encryptKeyRecord({ record, kek }: {
+    record: KmsKeyRecord;
+    kek: RecordKek;
+}): KmsKeyRecord;
+/**
+ * Decrypts a key record: pass-through when `key.encrypted` is absent (a
+ * plaintext record -- the default, and the pass-through upgrade path), else
+ * looks up the KEK by the record's stored `kekId`, unwraps the CEK, decrypts the
+ * secret subset, and splices the secret fields back onto the allowlisted ones
+ * (dropping the envelope). Pure: KEK(s) injected via `kekLoader`, no storage or
+ * env access. Throws a plain `Error` when the record's KEK is not registered or
+ * the ciphertext fails to authenticate; the request seam wraps that as a 500.
+ * @param options {object}
+ * @param options.record {KmsKeyRecord}   the at-rest (or plaintext) record
+ * @param options.kekLoader {(kekId: string) => RecordKek | undefined}   KEK lookup
+ * @returns {KmsKeyRecord}   the decrypted record (secrets restored on `key`)
+ */
+export declare function decryptKeyRecord({ record, kekLoader }: {
+    record: KmsKeyRecord;
+    kekLoader: (kekId: string) => RecordKek | undefined;
+}): KmsKeyRecord;
+//# sourceMappingURL=kmsRecordCipher.d.ts.map

package/dist/lib/kmsRecordCipher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kmsRecordCipher.d.ts","sourceRoot":"","sources":["../../src/lib/kmsRecordCipher.ts"],"names":[],"mappings":"AA2BA,OAAO,KAAK,EAEV,YAAY,EAEZ,SAAS,EACT,oBAAoB,EACrB,MAAM,aAAa,CAAA;AAEpB;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,EAAE,WAAW,CAAC,MAAM,CAQnD,CAAA;AAsBF;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE/C;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAC/B,kBAAkB,EAAE,MAAM,EAC1B,KAAK,SAAmB,GACvB,SAAS,CAoBX;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,CAAC,EAAE,oBAAoB,GAC9B,SAAS,GAAG,SAAS,CAKvB;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,CAAC,EAAE,oBAAoB,GAC9B,CAAC,KAAK,EAAE,MAAM,KAAK,SAAS,GAAG,SAAS,CAE1C;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,EAC/B,MAAM,EACN,GAAG,EACJ,EAAE;IACD,MAAM,EAAE,YAAY,CAAA;IACpB,GAAG,EAAE,SAAS,CAAA;CACf,GAAG,YAAY,CAmDf;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,EAC/B,MAAM,EACN,SAAS,EACV,EAAE;IACD,MAAM,EAAE,YAAY,CAAA;IACpB,SAAS,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,SAAS,GAAG,SAAS,CAAA;CACpD,GAAG,YAAY,CAkDf"}