was-teaching-server 0.9.1

package/dist/lib/edvEnvelope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"edvEnvelope.js","sourceRoot":"","sources":["../../src/lib/edvEnvelope.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;;;;;;;;;GAUG;AACH,MAAM,UAAU,wBAAwB,CAAC,KAAc;IACrD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACxE,OAAO,KAAK,CAAA;IACd,CAAC;IACD,MAAM,SAAS,GAAG,KAAgC,CAAA;IAClD,IACE,SAAS,CAAC,MAAM,KAAK,SAAS;QAC9B,CAAC,OAAO,SAAS,CAAC,MAAM,KAAK,QAAQ;YACnC,SAAS,CAAC,MAAM,KAAK,IAAI;YACzB,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,EAClC,CAAC;QACD,OAAO,KAAK,CAAA;IACd,CAAC;IACD,IACE,SAAS,CAAC,aAAa,KAAK,SAAS;QACrC,OAAO,SAAS,CAAC,aAAa,KAAK,QAAQ,EAC3C,CAAC;QACD,OAAO,KAAK,CAAA;IACd,CAAC;IACD,OAAO,IAAI,CAAA;AACb,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAAa;IAC9C,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QACrE,OAAO,KAAK,CAAA;IACd,CAAC;IACD,MAAM,QAAQ,GAAG,IAA+B,CAAA;IAEhD,6CAA6C;IAC7C,IACE,OAAO,QAAQ,CAAC,UAAU,KAAK,QAAQ;QACvC,QAAQ,CAAC,UAAU,CAAC,MAAM,KAAK,CAAC,EAChC,CAAC;QACD,OAAO,KAAK,CAAA;IACd,CAAC;IAED,2BAA2B;IAC3B,KAAK,MAAM,GAAG,IAAI,CAAC,WAAW,EAAE,IAAI,EAAE,KAAK,EAAE,eAAe,CAAU,EAAE,CAAC;QACvE,IAAI,QAAQ,CAAC,GAAG,CAAC,KAAK,SAAS,IAAI,OAAO,QAAQ,CAAC,GAAG,CAAC,KAAK,QAAQ,EAAE,CAAC;YACrE,OAAO,KAAK,CAAA;QACd,CAAC;IACH,CAAC;IAED,oFAAoF;IACpF,IAAI,YAAY,GAAG,KAAK,CAAA;IACxB,IAAI,QAAQ,CAAC,UAAU,KAAK,SAAS,EAAE,CAAC;QACtC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC;YACxC,OAAO,KAAK,CAAA;QACd,CAAC;QACD,KAAK,MAAM,KAAK,IAAI,QAAQ,CAAC,UAAU,EAAE,CAAC;YACxC,IAAI,CAAC,wBAAwB,CAAC,KAAK,CAAC,EAAE,CAAC;gBACrC,OAAO,KAAK,CAAA;YACd,CAAC;QACH,CAAC;QACD,YAAY,GAAG,QAAQ,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC,CAAA;IAC/C,CAAC;IAED,qEAAqE;IACrE,6EAA6E;IAC7E,oDAAoD;IACpD,OAAO,CACL,YAAY;QACZ,OAAO,QAAQ,CAAC,aAAa,KAAK,QAAQ;QAC1C,OAAO,QAAQ,CAAC,SAAS,KAAK,QAAQ,CACvC,CAAA;AACH,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAAa;IAC9C,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QACrE,OAAO,KAAK,CAAA;IACd,CAAC;IACD,OAAO,kBAAkB,CAAE,IAA0B,CAAC,GAAG,CAAC,CAAA;AAC5D,CAAC"}

package/dist/lib/encryption.d.ts

@@ -0,0 +1,192 @@
+/**
+ * Collection client-side encryption marker helpers (spec "Encrypted
+ * Collections"). A Collection MAY carry a non-secret `encryption` marker
+ * declaring that its Resources are client-encrypted and naming the scheme; any
+ * authorized reader discovers it by reading the Collection Description and then
+ * decrypts with its own keys. The server never decrypts: it validates only the
+ * marker's *shape* and enforces *set-once* immutability, storing the value
+ * opaquely. This mirrors the backend-selection helpers in lib/backends.ts
+ * (validate on write / preserve on read), kept separate because encryption is a
+ * per-Collection client concern, not a backend capability.
+ */
+import type { CollectionEncryption } from '../types.js';
+/**
+ * The encryption schemes this server recognizes and can enforce on write (spec
+ * "Encryption Scheme Registry"). Each entry pins the scheme token to its
+ * required stored-representation media type and the structural validator for its
+ * envelope profile. v1 has exactly one entry: `edv` (EDV-over-WAS), an EDV
+ * **Encrypted Document** (a JSON object whose `jwe` member is a JWE in JSON
+ * serialization) carried as `application/json` -- matching what the EDV codec
+ * actually stores and how a native EDV server serves an Encrypted Document.
+ * "Marked with a recognized scheme" structurally implies "non-conforming writes
+ * rejected here" -- the fail-closed guarantee: a plaintext object under
+ * `application/json` passes the media-type gate but fails the structural
+ * `jwe` gate, so it is still rejected. Extending the registry (a new scheme, or
+ * a new media type for an existing one) is the only place a scheme becomes
+ * acceptable.
+ */
+export declare const SUPPORTED_ENCRYPTION_SCHEMES: Record<string, {
+    mediaType: string;
+    validateEnvelope: (body: unknown) => boolean;
+}>;
+/**
+ * Validates a client-supplied Collection `encryption` marker and returns the
+ * normalized value to persist, or `undefined` when absent (plaintext). Two
+ * gates: (1) shape -- a present value must be an object with a non-empty string
+ * `scheme`, else `invalid-request-body` (400, pointer `#/encryption`); (2)
+ * fail-closed scheme gate -- the `scheme` MUST name one this server recognizes
+ * and can enforce on write (`SUPPORTED_ENCRYPTION_SCHEMES`), else
+ * `unsupported-encryption-scheme` (400, pointer `#/encryption/scheme`). Taking
+ * the spec's SHOULD path, the reference server refuses to store a marker it
+ * cannot back with write-time validation, rather than storing an unknown scheme
+ * opaquely. Unknown **extra fields** on an otherwise-recognized marker are still
+ * preserved (the whole object is returned, not reduced to `{ scheme }`) so
+ * future public-reference fields a newer client adds (e.g. recipient key
+ * references) survive an older server unchanged.
+ *
+ * @param options {object}
+ * @param [options.encryption] {unknown}   the request body's `encryption` value
+ * @param [options.requestName] {string}   request name for the 400 error title
+ * @returns {CollectionEncryption | undefined}   the marker to store, or undefined
+ */
+export declare function assertSupportedEncryption({ encryption, requestName }: {
+    encryption?: unknown;
+    requestName?: string;
+}): CollectionEncryption | undefined;
+/**
+ * Enforces the epoch-safety rails on an UPDATE, when the existing marker already
+ * carries `epochs` (spec "Encrypted Collections"; the `key-epochs` feature).
+ * Call only when an `incoming` marker was supplied and shape-validated. Rules
+ * (both `invalid-request-body`, 400):
+ * - **append-only**: every existing epoch id must still be present in
+ *   `incoming.epochs` -- dropping an epoch would strand every Resource stamped
+ *   with it (the removed reader could still hold that epoch's key, but no
+ *   remaining reader could find it).
+ * - **`currentEpoch` never moves backwards**: the incoming `currentEpoch` must
+ *   equal the existing one OR name an epoch id that was NOT in the existing
+ *   `epochs` list (a freshly appended epoch). This is the array-order-independent
+ *   formulation of "monotonic".
+ *
+ * Recipients WITHIN an existing epoch MAY change (adding a recipient wraps the
+ * epoch key to it; escrow adds entries to old epochs), so that is not
+ * restricted. A first declaration of `epochs` on a marker that had none is
+ * likewise unrestricted (there is nothing to append to yet).
+ *
+ * @param options {object}
+ * @param [options.existing] {CollectionEncryption}   the persisted marker
+ * @param options.incoming {CollectionEncryption}   the validated request marker
+ * @returns {void}
+ */
+export declare function assertEncryptionEpochsTransition({ existing, incoming }: {
+    existing?: CollectionEncryption;
+    incoming: CollectionEncryption;
+}): void;
+/**
+ * Enforces the full `encryption`-marker transition rails against a persisted
+ * marker in one call: set-once immutability
+ * ({@link assertEncryptionTransition}) plus the key-epoch rails
+ * ({@link assertEncryptionEpochsTransition}). Unlike those two -- which require
+ * a supplied `incoming` -- this also accepts an absent one: a write whose
+ * description would CLEAR an existing marker is rejected with
+ * `encryption-immutable` (409), on the same terms as changing it. The request
+ * layer uses this twice per Update Collection: once against its own
+ * (pre-lock) read for a clean early rejection, and again as the
+ * `writeCollection` `assertTransition` callback, re-evaluated inside the
+ * backend's lock/transaction against the freshly re-read description -- so a
+ * concurrent marker write cannot be silently clobbered and the epoch
+ * append-only rail holds unconditionally, not just under `If-Match`.
+ *
+ * @param options {object}
+ * @param [options.existing] {CollectionEncryption}   the persisted marker
+ * @param [options.incoming] {CollectionEncryption}   the marker about to be
+ *   persisted (absent when the write would drop the marker entirely)
+ * @returns {void}
+ */
+export declare function assertEncryptionMarkerTransition({ existing, incoming }: {
+    existing?: CollectionEncryption;
+    incoming?: CollectionEncryption;
+}): void;
+/**
+ * Enforces set-once immutability of a Collection's `encryption` marker on
+ * update. Call only when an `incoming` marker was supplied (and shape-validated)
+ * by the request. Declaring a marker on a Collection that lacks one is allowed
+ * (`absent -> present`: late declaration / migration of a pre-marker
+ * Collection); re-sending the same `scheme` is a no-op. Changing the `scheme` of
+ * an existing marker is rejected with `encryption-immutable` (409) -- it would
+ * corrupt the stored, client-encrypted Resources. (Clearing is not expressible:
+ * an absent body `encryption` leaves the existing marker untouched, and an
+ * explicit non-object is already a 400 in `assertSupportedEncryption`.) The
+ * `scheme` is the immutable identity; comparison deliberately ignores any
+ * future public-reference fields, whose evolution (e.g. adding a recipient) is a
+ * separate, allowed operation.
+ *
+ * @param options {object}
+ * @param [options.existing] {CollectionEncryption}   the persisted marker
+ * @param options.incoming {CollectionEncryption}   the validated request marker
+ * @returns {void}
+ */
+export declare function assertEncryptionTransition({ existing, incoming }: {
+    existing?: CollectionEncryption;
+    incoming: CollectionEncryption;
+}): void;
+/**
+ * Fail-closed structural validation of a Resource **content** write into an
+ * encrypted Collection (spec "Encryption Scheme Registry"). When the target
+ * Collection declares a recognized `encryption` scheme, a write MUST be a
+ * conforming envelope of that scheme -- two gates: (1) the request `Content-Type`
+ * MUST be the scheme's registered media type (so a binary/`octet-stream`,
+ * `multipart`, or plain `application/json` upload is rejected outright), and (2)
+ * the parsed body MUST satisfy the scheme's structural envelope profile. A
+ * failure of either is `encryption-scheme-mismatch` (422). No-op when the
+ * Collection has no marker (plaintext) or -- defensively -- an unrecognized
+ * scheme (which `assertSupportedEncryption` prevents from ever being stored), so
+ * plaintext Collections and API documents are unaffected. The server validates
+ * structure only; it never decrypts. Call this **after** capability verification
+ * and the 404-if-missing check, and before resolving the body stream, so a wrong
+ * content type is rejected without consuming the upload and a 422 is observable
+ * only to a caller already authorized to write the target.
+ *
+ * @param options {object}
+ * @param options.collectionDescription {{ encryption?: CollectionEncryption }}
+ *   the target Collection's stored description
+ * @param [options.contentType] {string}   the request `Content-Type` header
+ * @param options.body {unknown}   the parsed request body (an object for the
+ *   `application/<suffix>+json` media types the scheme registry uses)
+ * @returns {void}
+ */
+export declare function assertEncryptedWriteConforms({ collectionDescription, contentType, body }: {
+    collectionDescription: {
+        encryption?: CollectionEncryption;
+    };
+    contentType?: string;
+    body: unknown;
+}): void;
+/**
+ * Fail-closed structural validation of a Resource **metadata** write (`PUT
+ * /meta`) into an encrypted Collection (spec "Encrypted Collections"). When the
+ * target Collection declares a recognized `encryption` scheme, the user-writable
+ * `custom` object MUST be a conforming envelope of that scheme -- the same
+ * structural profile used for content -- so a plaintext `{ name, tags }` cannot
+ * be stored server-visibly. Unlike {@link assertEncryptedWriteConforms} there is
+ * **no media-type gate**: the metadata document itself stays `application/json`
+ * (its server-managed top-level fields are plaintext); only the `custom`
+ * sub-value is the envelope. A non-conforming `custom` is
+ * `encryption-scheme-mismatch` (422). No-op when the Collection has no marker
+ * (plaintext) or -- defensively -- an unrecognized scheme. The server validates
+ * structure only; it never decrypts. Call this **after** capability verification
+ * and the 404-if-missing check, before the write, so a 422 is observable only to
+ * a caller already authorized to write the target.
+ *
+ * @param options {object}
+ * @param options.collectionDescription {{ encryption?: CollectionEncryption }}
+ *   the target Collection's stored description
+ * @param options.custom {unknown}   the request body's `custom` value
+ * @returns {void}
+ */
+export declare function assertEncryptedMetaConforms({ collectionDescription, custom }: {
+    collectionDescription: {
+        encryption?: CollectionEncryption;
+    };
+    custom: unknown;
+}): void;
+//# sourceMappingURL=encryption.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"encryption.d.ts","sourceRoot":"","sources":["../../src/lib/encryption.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,EACV,oBAAoB,EAErB,MAAM,aAAa,CAAA;AASpB;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,4BAA4B,EAAE,MAAM,CAC/C,MAAM,EACN;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,gBAAgB,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,OAAO,CAAA;CAAE,CAMpE,CAAA;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,yBAAyB,CAAC,EACxC,UAAU,EACV,WAAW,EACZ,EAAE;IACD,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB,GAAG,oBAAoB,GAAG,SAAS,CAmCnC;AAiID;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,gCAAgC,CAAC,EAC/C,QAAQ,EACR,QAAQ,EACT,EAAE;IACD,QAAQ,CAAC,EAAE,oBAAoB,CAAA;IAC/B,QAAQ,EAAE,oBAAoB,CAAA;CAC/B,GAAG,IAAI,CA6BP;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,gCAAgC,CAAC,EAC/C,QAAQ,EACR,QAAQ,EACT,EAAE;IACD,QAAQ,CAAC,EAAE,oBAAoB,CAAA;IAC/B,QAAQ,CAAC,EAAE,oBAAoB,CAAA;CAChC,GAAG,IAAI,CAWP;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,0BAA0B,CAAC,EACzC,QAAQ,EACR,QAAQ,EACT,EAAE;IACD,QAAQ,CAAC,EAAE,oBAAoB,CAAA;IAC/B,QAAQ,EAAE,oBAAoB,CAAA;CAC/B,GAAG,IAAI,CAIP;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,4BAA4B,CAAC,EAC3C,qBAAqB,EACrB,WAAW,EACX,IAAI,EACL,EAAE;IACD,qBAAqB,EAAE;QAAE,UAAU,CAAC,EAAE,oBAAoB,CAAA;KAAE,CAAA;IAC5D,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,IAAI,EAAE,OAAO,CAAA;CACd,GAAG,IAAI,CAwBP;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,2BAA2B,CAAC,EAC1C,qBAAqB,EACrB,MAAM,EACP,EAAE;IACD,qBAAqB,EAAE;QAAE,UAAU,CAAC,EAAE,oBAAoB,CAAA;KAAE,CAAA;IAC5D,MAAM,EAAE,OAAO,CAAA;CAChB,GAAG,IAAI,CAcP"}

package/dist/lib/encryption.js

@@ -0,0 +1,383 @@
+import { InvalidRequestBodyError, EncryptionImmutableError, UnsupportedEncryptionSchemeError, EncryptionSchemeMismatchError } from '../errors.js';
+import { isValidEdvDocument } from './edvEnvelope.js';
+/**
+ * The encryption schemes this server recognizes and can enforce on write (spec
+ * "Encryption Scheme Registry"). Each entry pins the scheme token to its
+ * required stored-representation media type and the structural validator for its
+ * envelope profile. v1 has exactly one entry: `edv` (EDV-over-WAS), an EDV
+ * **Encrypted Document** (a JSON object whose `jwe` member is a JWE in JSON
+ * serialization) carried as `application/json` -- matching what the EDV codec
+ * actually stores and how a native EDV server serves an Encrypted Document.
+ * "Marked with a recognized scheme" structurally implies "non-conforming writes
+ * rejected here" -- the fail-closed guarantee: a plaintext object under
+ * `application/json` passes the media-type gate but fails the structural
+ * `jwe` gate, so it is still rejected. Extending the registry (a new scheme, or
+ * a new media type for an existing one) is the only place a scheme becomes
+ * acceptable.
+ */
+export const SUPPORTED_ENCRYPTION_SCHEMES = {
+    edv: {
+        mediaType: 'application/json',
+        validateEnvelope: isValidEdvDocument
+    }
+};
+/**
+ * Validates a client-supplied Collection `encryption` marker and returns the
+ * normalized value to persist, or `undefined` when absent (plaintext). Two
+ * gates: (1) shape -- a present value must be an object with a non-empty string
+ * `scheme`, else `invalid-request-body` (400, pointer `#/encryption`); (2)
+ * fail-closed scheme gate -- the `scheme` MUST name one this server recognizes
+ * and can enforce on write (`SUPPORTED_ENCRYPTION_SCHEMES`), else
+ * `unsupported-encryption-scheme` (400, pointer `#/encryption/scheme`). Taking
+ * the spec's SHOULD path, the reference server refuses to store a marker it
+ * cannot back with write-time validation, rather than storing an unknown scheme
+ * opaquely. Unknown **extra fields** on an otherwise-recognized marker are still
+ * preserved (the whole object is returned, not reduced to `{ scheme }`) so
+ * future public-reference fields a newer client adds (e.g. recipient key
+ * references) survive an older server unchanged.
+ *
+ * @param options {object}
+ * @param [options.encryption] {unknown}   the request body's `encryption` value
+ * @param [options.requestName] {string}   request name for the 400 error title
+ * @returns {CollectionEncryption | undefined}   the marker to store, or undefined
+ */
+export function assertSupportedEncryption({ encryption, requestName }) {
+    if (encryption === undefined) {
+        return undefined;
+    }
+    const scheme = encryption?.scheme;
+    if (typeof encryption !== 'object' ||
+        encryption === null ||
+        typeof scheme !== 'string' ||
+        scheme.length === 0) {
+        throw new InvalidRequestBodyError({
+            requestName,
+            detail: 'Collection "encryption" must be an object with a non-empty string "scheme".',
+            pointer: '#/encryption'
+        });
+    }
+    // Fail closed: only a recognized scheme (one the server validates on write) is
+    // accepted; an unknown scheme is rejected rather than stored opaquely.
+    if (!Object.hasOwn(SUPPORTED_ENCRYPTION_SCHEMES, scheme)) {
+        throw new UnsupportedEncryptionSchemeError({ scheme });
+    }
+    // Validate the OPTIONAL key-epoch fields (`epochs` / `currentEpoch`) when
+    // present: shape-only safety rails against client bugs (a dropped epoch, a
+    // dangling `currentEpoch`), never crypto verification -- the server holds no
+    // key. Absent fields are a plain single-key-set marker and pass unchanged.
+    assertValidEncryptionEpochs({
+        marker: encryption,
+        requestName
+    });
+    // Preserve the whole marker (only `scheme` is typed today; keep any extra
+    // forward-compat fields on a recognized scheme).
+    return encryption;
+}
+/**
+ * Validates the OPTIONAL key-epoch public-reference fields of a Collection
+ * `encryption` marker (spec "Encrypted Collections"; the `key-epochs` feature).
+ * Shape-only integrity checks that catch client bugs -- the server never
+ * interprets key material, so these are safety rails, not cryptographic
+ * verification. Rejects with `invalid-request-body` (400) and a precise
+ * `pointer`. Rules:
+ * - `epochs` and `currentEpoch` are all-or-nothing: either both absent (a plain
+ *   single-key-set marker) or both present.
+ * - `epochs`: a non-empty array; each entry an object with a non-empty string
+ *   `id` (ids unique across the array) and a non-empty `recipients` array.
+ * - each `recipients` entry carries the JWE recipients-entry members the
+ *   marker requires: a `header` object with non-empty string `kid` and `alg`,
+ *   plus a string `encrypted_key` (the wrapped epoch key).
+ * - `currentEpoch`: a non-empty string naming an `id` that exists in `epochs`.
+ *
+ * @param options {object}
+ * @param options.marker {CollectionEncryption}   the shape-validated marker
+ * @param [options.requestName] {string}   request name for the 400 error title
+ * @returns {void}
+ */
+function assertValidEncryptionEpochs({ marker, requestName }) {
+    const { epochs, currentEpoch } = marker;
+    // All-or-nothing: `epochs` and `currentEpoch` appear together or not at all.
+    if ((epochs === undefined) !== (currentEpoch === undefined)) {
+        throw new InvalidRequestBodyError({
+            requestName,
+            detail: 'Collection "encryption.epochs" and "encryption.currentEpoch" must both be present or both absent.',
+            pointer: '#/encryption/epochs'
+        });
+    }
+    if (epochs === undefined) {
+        return;
+    }
+    if (!Array.isArray(epochs) || epochs.length === 0) {
+        throw new InvalidRequestBodyError({
+            requestName,
+            detail: 'Collection "encryption.epochs" must be a non-empty array.',
+            pointer: '#/encryption/epochs'
+        });
+    }
+    const ids = new Set();
+    epochs.forEach((epoch, epochIndex) => {
+        const pointer = `#/encryption/epochs/${epochIndex}`;
+        if (typeof epoch !== 'object' || epoch === null || Array.isArray(epoch)) {
+            throw new InvalidRequestBodyError({
+                requestName,
+                detail: 'Each "encryption.epochs" entry must be an object.',
+                pointer
+            });
+        }
+        const { id, recipients } = epoch;
+        if (typeof id !== 'string' || id.length === 0) {
+            throw new InvalidRequestBodyError({
+                requestName,
+                detail: 'Each "encryption.epochs" entry must have a non-empty string "id".',
+                pointer: `${pointer}/id`
+            });
+        }
+        if (ids.has(id)) {
+            throw new InvalidRequestBodyError({
+                requestName,
+                detail: `Duplicate "encryption.epochs" id "${id}".`,
+                pointer: `${pointer}/id`
+            });
+        }
+        ids.add(id);
+        if (!Array.isArray(recipients) || recipients.length === 0) {
+            throw new InvalidRequestBodyError({
+                requestName,
+                detail: 'Each "encryption.epochs" entry must have a non-empty "recipients" array.',
+                pointer: `${pointer}/recipients`
+            });
+        }
+        recipients.forEach((recipient, recipientIndex) => {
+            const rPointer = `${pointer}/recipients/${recipientIndex}`;
+            // The JWE recipients-entry members the wrapped-epoch-key marker needs:
+            // `header.kid` / `header.alg` and the wrapped key `encrypted_key`. The
+            // member checks (optional chaining included) already reject every
+            // non-object or malformed entry, so no generic JWE-entry shape test runs
+            // first.
+            const header = recipient?.header;
+            if (typeof header?.kid !== 'string' ||
+                header.kid.length === 0 ||
+                typeof header.alg !== 'string' ||
+                header.alg.length === 0 ||
+                typeof recipient.encrypted_key !==
+                    'string') {
+                throw new InvalidRequestBodyError({
+                    requestName,
+                    detail: 'Each "recipients" entry must have a "header" object with non-empty string "kid" and "alg", plus a string "encrypted_key".',
+                    pointer: rPointer
+                });
+            }
+        });
+    });
+    if (typeof currentEpoch !== 'string' || currentEpoch.length === 0) {
+        throw new InvalidRequestBodyError({
+            requestName,
+            detail: 'Collection "encryption.currentEpoch" must be a non-empty string.',
+            pointer: '#/encryption/currentEpoch'
+        });
+    }
+    if (!ids.has(currentEpoch)) {
+        throw new InvalidRequestBodyError({
+            requestName,
+            detail: `Collection "encryption.currentEpoch" ("${currentEpoch}") does not name an epoch in "epochs".`,
+            pointer: '#/encryption/currentEpoch'
+        });
+    }
+}
+/**
+ * Enforces the epoch-safety rails on an UPDATE, when the existing marker already
+ * carries `epochs` (spec "Encrypted Collections"; the `key-epochs` feature).
+ * Call only when an `incoming` marker was supplied and shape-validated. Rules
+ * (both `invalid-request-body`, 400):
+ * - **append-only**: every existing epoch id must still be present in
+ *   `incoming.epochs` -- dropping an epoch would strand every Resource stamped
+ *   with it (the removed reader could still hold that epoch's key, but no
+ *   remaining reader could find it).
+ * - **`currentEpoch` never moves backwards**: the incoming `currentEpoch` must
+ *   equal the existing one OR name an epoch id that was NOT in the existing
+ *   `epochs` list (a freshly appended epoch). This is the array-order-independent
+ *   formulation of "monotonic".
+ *
+ * Recipients WITHIN an existing epoch MAY change (adding a recipient wraps the
+ * epoch key to it; escrow adds entries to old epochs), so that is not
+ * restricted. A first declaration of `epochs` on a marker that had none is
+ * likewise unrestricted (there is nothing to append to yet).
+ *
+ * @param options {object}
+ * @param [options.existing] {CollectionEncryption}   the persisted marker
+ * @param options.incoming {CollectionEncryption}   the validated request marker
+ * @returns {void}
+ */
+export function assertEncryptionEpochsTransition({ existing, incoming }) {
+    const existingEpochs = existing?.epochs;
+    if (existingEpochs === undefined || existingEpochs.length === 0) {
+        // No prior epochs: a first epoch declaration has nothing to append to.
+        return;
+    }
+    const incomingIds = new Set((incoming.epochs ?? []).map(epoch => epoch.id));
+    // Append-only: no existing epoch id may vanish.
+    for (const epoch of existingEpochs) {
+        if (!incomingIds.has(epoch.id)) {
+            throw new InvalidRequestBodyError({
+                detail: `Collection "encryption.epochs" is append-only: epoch "${epoch.id}" may not be removed.`,
+                pointer: '#/encryption/epochs'
+            });
+        }
+    }
+    // `currentEpoch` never moves backwards: keep it, or repoint it to a
+    // newly-appended epoch id (one that did not exist before).
+    const existingIds = new Set(existingEpochs.map(epoch => epoch.id));
+    const { currentEpoch } = incoming;
+    if (currentEpoch !== existing?.currentEpoch &&
+        existingIds.has(currentEpoch)) {
+        throw new InvalidRequestBodyError({
+            detail: `Collection "encryption.currentEpoch" may not move back to the existing epoch "${currentEpoch}"; repoint it only to a newly appended epoch.`,
+            pointer: '#/encryption/currentEpoch'
+        });
+    }
+}
+/**
+ * Enforces the full `encryption`-marker transition rails against a persisted
+ * marker in one call: set-once immutability
+ * ({@link assertEncryptionTransition}) plus the key-epoch rails
+ * ({@link assertEncryptionEpochsTransition}). Unlike those two -- which require
+ * a supplied `incoming` -- this also accepts an absent one: a write whose
+ * description would CLEAR an existing marker is rejected with
+ * `encryption-immutable` (409), on the same terms as changing it. The request
+ * layer uses this twice per Update Collection: once against its own
+ * (pre-lock) read for a clean early rejection, and again as the
+ * `writeCollection` `assertTransition` callback, re-evaluated inside the
+ * backend's lock/transaction against the freshly re-read description -- so a
+ * concurrent marker write cannot be silently clobbered and the epoch
+ * append-only rail holds unconditionally, not just under `If-Match`.
+ *
+ * @param options {object}
+ * @param [options.existing] {CollectionEncryption}   the persisted marker
+ * @param [options.incoming] {CollectionEncryption}   the marker about to be
+ *   persisted (absent when the write would drop the marker entirely)
+ * @returns {void}
+ */
+export function assertEncryptionMarkerTransition({ existing, incoming }) {
+    if (existing === undefined) {
+        // Nothing persisted yet: a first declaration (or a plaintext Collection
+        // staying plaintext) has no rails to check.
+        return;
+    }
+    if (incoming === undefined) {
+        throw new EncryptionImmutableError();
+    }
+    assertEncryptionTransition({ existing, incoming });
+    assertEncryptionEpochsTransition({ existing, incoming });
+}
+/**
+ * Enforces set-once immutability of a Collection's `encryption` marker on
+ * update. Call only when an `incoming` marker was supplied (and shape-validated)
+ * by the request. Declaring a marker on a Collection that lacks one is allowed
+ * (`absent -> present`: late declaration / migration of a pre-marker
+ * Collection); re-sending the same `scheme` is a no-op. Changing the `scheme` of
+ * an existing marker is rejected with `encryption-immutable` (409) -- it would
+ * corrupt the stored, client-encrypted Resources. (Clearing is not expressible:
+ * an absent body `encryption` leaves the existing marker untouched, and an
+ * explicit non-object is already a 400 in `assertSupportedEncryption`.) The
+ * `scheme` is the immutable identity; comparison deliberately ignores any
+ * future public-reference fields, whose evolution (e.g. adding a recipient) is a
+ * separate, allowed operation.
+ *
+ * @param options {object}
+ * @param [options.existing] {CollectionEncryption}   the persisted marker
+ * @param options.incoming {CollectionEncryption}   the validated request marker
+ * @returns {void}
+ */
+export function assertEncryptionTransition({ existing, incoming }) {
+    if (existing !== undefined && existing.scheme !== incoming.scheme) {
+        throw new EncryptionImmutableError();
+    }
+}
+/**
+ * Fail-closed structural validation of a Resource **content** write into an
+ * encrypted Collection (spec "Encryption Scheme Registry"). When the target
+ * Collection declares a recognized `encryption` scheme, a write MUST be a
+ * conforming envelope of that scheme -- two gates: (1) the request `Content-Type`
+ * MUST be the scheme's registered media type (so a binary/`octet-stream`,
+ * `multipart`, or plain `application/json` upload is rejected outright), and (2)
+ * the parsed body MUST satisfy the scheme's structural envelope profile. A
+ * failure of either is `encryption-scheme-mismatch` (422). No-op when the
+ * Collection has no marker (plaintext) or -- defensively -- an unrecognized
+ * scheme (which `assertSupportedEncryption` prevents from ever being stored), so
+ * plaintext Collections and API documents are unaffected. The server validates
+ * structure only; it never decrypts. Call this **after** capability verification
+ * and the 404-if-missing check, and before resolving the body stream, so a wrong
+ * content type is rejected without consuming the upload and a 422 is observable
+ * only to a caller already authorized to write the target.
+ *
+ * @param options {object}
+ * @param options.collectionDescription {{ encryption?: CollectionEncryption }}
+ *   the target Collection's stored description
+ * @param [options.contentType] {string}   the request `Content-Type` header
+ * @param options.body {unknown}   the parsed request body (an object for the
+ *   `application/<suffix>+json` media types the scheme registry uses)
+ * @returns {void}
+ */
+export function assertEncryptedWriteConforms({ collectionDescription, contentType, body }) {
+    const scheme = collectionDescription.encryption?.scheme;
+    if (scheme === undefined) {
+        return;
+    }
+    const profile = SUPPORTED_ENCRYPTION_SCHEMES[scheme];
+    if (!profile) {
+        return;
+    }
+    // Gate 1: the stored representation's media type. Compare the bare media type
+    // (parameters like `; charset=utf-8` stripped), case-insensitively.
+    const mediaType = (contentType ?? '').split(';')[0].trim().toLowerCase();
+    if (mediaType !== profile.mediaType) {
+        throw new EncryptionSchemeMismatchError({
+            detail: `A write into a Collection encrypted with the '${scheme}' scheme must use Content-Type '${profile.mediaType}'.`
+        });
+    }
+    // Gate 2: the envelope's structural profile (server validates shape, not
+    // contents -- it never decrypts).
+    if (!profile.validateEnvelope(body)) {
+        throw new EncryptionSchemeMismatchError({
+            detail: `Resource body is not a structurally valid '${scheme}' encryption envelope.`
+        });
+    }
+}
+/**
+ * Fail-closed structural validation of a Resource **metadata** write (`PUT
+ * /meta`) into an encrypted Collection (spec "Encrypted Collections"). When the
+ * target Collection declares a recognized `encryption` scheme, the user-writable
+ * `custom` object MUST be a conforming envelope of that scheme -- the same
+ * structural profile used for content -- so a plaintext `{ name, tags }` cannot
+ * be stored server-visibly. Unlike {@link assertEncryptedWriteConforms} there is
+ * **no media-type gate**: the metadata document itself stays `application/json`
+ * (its server-managed top-level fields are plaintext); only the `custom`
+ * sub-value is the envelope. A non-conforming `custom` is
+ * `encryption-scheme-mismatch` (422). No-op when the Collection has no marker
+ * (plaintext) or -- defensively -- an unrecognized scheme. The server validates
+ * structure only; it never decrypts. Call this **after** capability verification
+ * and the 404-if-missing check, before the write, so a 422 is observable only to
+ * a caller already authorized to write the target.
+ *
+ * @param options {object}
+ * @param options.collectionDescription {{ encryption?: CollectionEncryption }}
+ *   the target Collection's stored description
+ * @param options.custom {unknown}   the request body's `custom` value
+ * @returns {void}
+ */
+export function assertEncryptedMetaConforms({ collectionDescription, custom }) {
+    const scheme = collectionDescription.encryption?.scheme;
+    if (scheme === undefined) {
+        return;
+    }
+    const profile = SUPPORTED_ENCRYPTION_SCHEMES[scheme];
+    if (!profile) {
+        return;
+    }
+    if (!profile.validateEnvelope(custom)) {
+        throw new EncryptionSchemeMismatchError({
+            detail: `Resource metadata "custom" is not a structurally valid '${scheme}' encryption envelope.`
+        });
+    }
+}
+//# sourceMappingURL=encryption.js.map

package/dist/lib/encryption.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"encryption.js","sourceRoot":"","sources":["../../src/lib/encryption.ts"],"names":[],"mappings":"AAeA,OAAO,EACL,uBAAuB,EACvB,wBAAwB,EACxB,gCAAgC,EAChC,6BAA6B,EAC9B,MAAM,cAAc,CAAA;AACrB,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAA;AAErD;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAGrC;IACF,GAAG,EAAE;QACH,SAAS,EAAE,kBAAkB;QAC7B,gBAAgB,EAAE,kBAAkB;KACrC;CACF,CAAA;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,yBAAyB,CAAC,EACxC,UAAU,EACV,WAAW,EAIZ;IACC,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;QAC7B,OAAO,SAAS,CAAA;IAClB,CAAC;IACD,MAAM,MAAM,GAAI,UAAmC,EAAE,MAAM,CAAA;IAC3D,IACE,OAAO,UAAU,KAAK,QAAQ;QAC9B,UAAU,KAAK,IAAI;QACnB,OAAO,MAAM,KAAK,QAAQ;QAC1B,MAAM,CAAC,MAAM,KAAK,CAAC,EACnB,CAAC;QACD,MAAM,IAAI,uBAAuB,CAAC;YAChC,WAAW;YACX,MAAM,EACJ,6EAA6E;YAC/E,OAAO,EAAE,cAAc;SACxB,CAAC,CAAA;IACJ,CAAC;IACD,+EAA+E;IAC/E,uEAAuE;IACvE,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,4BAA4B,EAAE,MAAM,CAAC,EAAE,CAAC;QACzD,MAAM,IAAI,gCAAgC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAA;IACxD,CAAC;IACD,0EAA0E;IAC1E,2EAA2E;IAC3E,6EAA6E;IAC7E,2EAA2E;IAC3E,2BAA2B,CAAC;QAC1B,MAAM,EAAE,UAAkC;QAC1C,WAAW;KACZ,CAAC,CAAA;IAEF,0EAA0E;IAC1E,iDAAiD;IACjD,OAAO,UAAkC,CAAA;AAC3C,CAAC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,SAAS,2BAA2B,CAAC,EACnC,MAAM,EACN,WAAW,EAIZ;IACC,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,GAAG,MAAM,CAAA;IACvC,6EAA6E;IAC7E,IAAI,CAAC,MAAM,KAAK,SAAS,CAAC,KAAK,CAAC,YAAY,KAAK,SAAS,CAAC,EAAE,CAAC;QAC5D,MAAM,IAAI,uBAAuB,CAAC;YAChC,WAAW;YACX,MAAM,EACJ,mGAAmG;YACrG,OAAO,EAAE,qBAAqB;SAC/B,CAAC,CAAA;IACJ,CAAC;IACD,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,OAAM;IACR,CAAC;IACD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAClD,MAAM,IAAI,uBAAuB,CAAC;YAChC,WAAW;YACX,MAAM,EAAE,2DAA2D;YACnE,OAAO,EAAE,qBAAqB;SAC/B,CAAC,CAAA;IACJ,CAAC;IACD,MAAM,GAAG,GAAG,IAAI,GAAG,EAAU,CAAA;IAC7B,MAAM,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,UAAU,EAAE,EAAE;QACnC,MAAM,OAAO,GAAG,uBAAuB,UAAU,EAAE,CAAA;QACnD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;YACxE,MAAM,IAAI,uBAAuB,CAAC;gBAChC,WAAW;gBACX,MAAM,EAAE,mDAAmD;gBAC3D,OAAO;aACR,CAAC,CAAA;QACJ,CAAC;QACD,MAAM,EAAE,EAAE,EAAE,UAAU,EAAE,GAAG,KAAkC,CAAA;QAC7D,IAAI,OAAO,EAAE,KAAK,QAAQ,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC9C,MAAM,IAAI,uBAAuB,CAAC;gBAChC,WAAW;gBACX,MAAM,EACJ,mEAAmE;gBACrE,OAAO,EAAE,GAAG,OAAO,KAAK;aACzB,CAAC,CAAA;QACJ,CAAC;QACD,IAAI,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC;YAChB,MAAM,IAAI,uBAAuB,CAAC;gBAChC,WAAW;gBACX,MAAM,EAAE,qCAAqC,EAAE,IAAI;gBACnD,OAAO,EAAE,GAAG,OAAO,KAAK;aACzB,CAAC,CAAA;QACJ,CAAC;QACD,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,CAAA;QACX,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,UAAU,CAAC,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC1D,MAAM,IAAI,uBAAuB,CAAC;gBAChC,WAAW;gBACX,MAAM,EACJ,0EAA0E;gBAC5E,OAAO,EAAE,GAAG,OAAO,aAAa;aACjC,CAAC,CAAA;QACJ,CAAC;QACD,UAAU,CAAC,OAAO,CAAC,CAAC,SAAS,EAAE,cAAc,EAAE,EAAE;YAC/C,MAAM,QAAQ,GAAG,GAAG,OAAO,eAAe,cAAc,EAAE,CAAA;YAC1D,uEAAuE;YACvE,uEAAuE;YACvE,kEAAkE;YAClE,yEAAyE;YACzE,SAAS;YACT,MAAM,MAAM,GACV,SACD,EAAE,MAAM,CAAA;YACT,IACE,OAAO,MAAM,EAAE,GAAG,KAAK,QAAQ;gBAC/B,MAAM,CAAC,GAAG,CAAC,MAAM,KAAK,CAAC;gBACvB,OAAO,MAAM,CAAC,GAAG,KAAK,QAAQ;gBAC9B,MAAM,CAAC,GAAG,CAAC,MAAM,KAAK,CAAC;gBACvB,OAAQ,SAAyC,CAAC,aAAa;oBAC7D,QAAQ,EACV,CAAC;gBACD,MAAM,IAAI,uBAAuB,CAAC;oBAChC,WAAW;oBACX,MAAM,EACJ,2HAA2H;oBAC7H,OAAO,EAAE,QAAQ;iBAClB,CAAC,CAAA;YACJ,CAAC;QACH,CAAC,CAAC,CAAA;IACJ,CAAC,CAAC,CAAA;IACF,IAAI,OAAO,YAAY,KAAK,QAAQ,IAAI,YAAY,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAClE,MAAM,IAAI,uBAAuB,CAAC;YAChC,WAAW;YACX,MAAM,EACJ,kEAAkE;YACpE,OAAO,EAAE,2BAA2B;SACrC,CAAC,CAAA;IACJ,CAAC;IACD,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,YAAY,CAAC,EAAE,CAAC;QAC3B,MAAM,IAAI,uBAAuB,CAAC;YAChC,WAAW;YACX,MAAM,EAAE,0CAA0C,YAAY,wCAAwC;YACtG,OAAO,EAAE,2BAA2B;SACrC,CAAC,CAAA;IACJ,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,gCAAgC,CAAC,EAC/C,QAAQ,EACR,QAAQ,EAIT;IACC,MAAM,cAAc,GAAG,QAAQ,EAAE,MAAM,CAAA;IACvC,IAAI,cAAc,KAAK,SAAS,IAAI,cAAc,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAChE,uEAAuE;QACvE,OAAM;IACR,CAAC;IACD,MAAM,WAAW,GAAG,IAAI,GAAG,CAAC,CAAC,QAAQ,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAA;IAC3E,gDAAgD;IAChD,KAAK,MAAM,KAAK,IAAI,cAAc,EAAE,CAAC;QACnC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE,CAAC;YAC/B,MAAM,IAAI,uBAAuB,CAAC;gBAChC,MAAM,EAAE,yDAAyD,KAAK,CAAC,EAAE,uBAAuB;gBAChG,OAAO,EAAE,qBAAqB;aAC/B,CAAC,CAAA;QACJ,CAAC;IACH,CAAC;IACD,oEAAoE;IACpE,2DAA2D;IAC3D,MAAM,WAAW,GAAG,IAAI,GAAG,CAAC,cAAc,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAA;IAClE,MAAM,EAAE,YAAY,EAAE,GAAG,QAAQ,CAAA;IACjC,IACE,YAAY,KAAK,QAAQ,EAAE,YAAY;QACvC,WAAW,CAAC,GAAG,CAAC,YAAsB,CAAC,EACvC,CAAC;QACD,MAAM,IAAI,uBAAuB,CAAC;YAChC,MAAM,EAAE,iFAAiF,YAAY,+CAA+C;YACpJ,OAAO,EAAE,2BAA2B;SACrC,CAAC,CAAA;IACJ,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,gCAAgC,CAAC,EAC/C,QAAQ,EACR,QAAQ,EAIT;IACC,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC3B,wEAAwE;QACxE,4CAA4C;QAC5C,OAAM;IACR,CAAC;IACD,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC3B,MAAM,IAAI,wBAAwB,EAAE,CAAA;IACtC,CAAC;IACD,0BAA0B,CAAC,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC,CAAA;IAClD,gCAAgC,CAAC,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC,CAAA;AAC1D,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,0BAA0B,CAAC,EACzC,QAAQ,EACR,QAAQ,EAIT;IACC,IAAI,QAAQ,KAAK,SAAS,IAAI,QAAQ,CAAC,MAAM,KAAK,QAAQ,CAAC,MAAM,EAAE,CAAC;QAClE,MAAM,IAAI,wBAAwB,EAAE,CAAA;IACtC,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,UAAU,4BAA4B,CAAC,EAC3C,qBAAqB,EACrB,WAAW,EACX,IAAI,EAKL;IACC,MAAM,MAAM,GAAG,qBAAqB,CAAC,UAAU,EAAE,MAAM,CAAA;IACvD,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,OAAM;IACR,CAAC;IACD,MAAM,OAAO,GAAG,4BAA4B,CAAC,MAAM,CAAC,CAAA;IACpD,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,OAAM;IACR,CAAC;IACD,8EAA8E;IAC9E,oEAAoE;IACpE,MAAM,SAAS,GAAG,CAAC,WAAW,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAE,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAA;IACzE,IAAI,SAAS,KAAK,OAAO,CAAC,SAAS,EAAE,CAAC;QACpC,MAAM,IAAI,6BAA6B,CAAC;YACtC,MAAM,EAAE,iDAAiD,MAAM,mCAAmC,OAAO,CAAC,SAAS,IAAI;SACxH,CAAC,CAAA;IACJ,CAAC;IACD,yEAAyE;IACzE,kCAAkC;IAClC,IAAI,CAAC,OAAO,CAAC,gBAAgB,CAAC,IAAI,CAAC,EAAE,CAAC;QACpC,MAAM,IAAI,6BAA6B,CAAC;YACtC,MAAM,EAAE,8CAA8C,MAAM,wBAAwB;SACrF,CAAC,CAAA;IACJ,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,2BAA2B,CAAC,EAC1C,qBAAqB,EACrB,MAAM,EAIP;IACC,MAAM,MAAM,GAAG,qBAAqB,CAAC,UAAU,EAAE,MAAM,CAAA;IACvD,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,OAAM;IACR,CAAC;IACD,MAAM,OAAO,GAAG,4BAA4B,CAAC,MAAM,CAAC,CAAA;IACpD,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,OAAM;IACR,CAAC;IACD,IAAI,CAAC,OAAO,CAAC,gBAAgB,CAAC,MAAM,CAAC,EAAE,CAAC;QACtC,MAAM,IAAI,6BAA6B,CAAC;YACtC,MAAM,EAAE,2DAA2D,MAAM,wBAAwB;SAClG,CAAC,CAAA;IACJ,CAAC;AACH,CAAC"}

package/dist/lib/etag.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Helpers for the HTTP `ETag` strong validator that backs conditional writes
+ * (the `conditional-writes` feature). A Resource's monotonic `version` is
+ * formatted as a quoted strong validator on the wire, and incoming `If-Match` /
+ * `If-None-Match` request headers are normalized into write preconditions.
+ */
+/**
+ * Formats a Resource's monotonic `version` as a quoted strong `ETag` validator
+ * (e.g. version 3 to `"3"`). The quotes are part of the on-the-wire value, and
+ * `If-Match` comparison is exact-string (strong) comparison.
+ * @param version {number}
+ * @returns {string}
+ */
+export declare function formatEtag(version: number): string;
+/**
+ * Normalizes the `If-Match` / `If-None-Match` request headers into the write
+ * preconditions the storage layer evaluates. Only `If-None-Match: *`
+ * (create-if-absent) is supported; an `If-Match` value is passed through as the
+ * quoted ETag to match. A header that is absent (or, for an array-valued header,
+ * not a single string) contributes no precondition.
+ * @param headers {object}
+ * @param [headers.if-match] {string | string[]}
+ * @param [headers.if-none-match] {string | string[]}
+ * @returns {{ ifMatch?: string, ifNoneMatch?: boolean }}
+ */
+export declare function parseWritePreconditions(headers: {
+    'if-match'?: string | string[];
+    'if-none-match'?: string | string[];
+}): {
+    ifMatch?: string;
+    ifNoneMatch?: boolean;
+};
+//# sourceMappingURL=etag.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"etag.d.ts","sourceRoot":"","sources":["../../src/lib/etag.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAElD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE;IAC/C,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAA;IAC9B,eAAe,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAA;CACpC,GAAG;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,OAAO,CAAA;CAAE,CAO9C"}