was-teaching-server 0.9.1

package/dist/lib/blindedIndex.js

@@ -0,0 +1,338 @@
+/**
+ * Blinded-index query evaluation -- the `blinded-index` profile of the reserved
+ * Collection `POST .../query` endpoint (the `blinded-index-query` backend
+ * feature). An EDV-encrypted Resource stored in a Collection carries an
+ * `indexed` array of HMAC-blinded attribute entries (produced client-side by
+ * `@interop/edv-client`'s IndexHelper); this module evaluates EDV queries
+ * (`equals` / `has`) against those entries, and enforces the write-time EDV
+ * unique-attribute invariant (`unique: true` claims;
+ * `assertNoUniqueBlindedConflict`). Everything here is opaque
+ * base64url string matching: the server never sees plaintext attribute names
+ * or values and performs no cryptography, so it is agnostic to the client's
+ * attribute-blinding version.
+ *
+ * Both storage backends answer the profile through `runBlindedIndexQuery` so
+ * their matching, ordering, and pagination semantics cannot drift (the same
+ * pattern as `preconditions.ts` for conditional writes). Matching semantics
+ * follow the EDV reference servers (`@interop/edv-server`,
+ * `bedrock-edv-storage`): `equals` is an OR across array elements of an AND
+ * within each element's `{name: value}` pairs, scoped to the queried index's
+ * entries; `has` requires every named attribute be present (value
+ * irrelevant). Pagination replaces EDV's `limit`+`hasMore`-only story with
+ * WAS's opaque cursor convention (`lib/cursor.ts`), closing the known EDV
+ * protocol gap: `cursor` names the keyset position (ascending `resourceId`)
+ * to resume from.
+ */
+import { decodeCursor, encodeCursor } from './cursor.js';
+import { clampPageSize, DEFAULT_PAGE_SIZE } from './pagination.js';
+import { InvalidRequestBodyError, UniqueAttributeConflictError } from '../errors.js';
+/**
+ * Validates and normalizes the `blinded-index` profile's query body fields
+ * (everything besides `profile`), throwing `invalid-request-body` (400) on a
+ * malformed query. Mirrors the EDV query schema (`{index, equals | has,
+ * count, limit}`, with `equals` and `has` mutually exclusive and exactly one
+ * required) plus the WAS `cursor`. `limit` is coerced leniently like the
+ * `changes` profile (a non-numeric or `< 1` value falls back to the default;
+ * the backend clamps an oversized one), and the opaque `cursor` is validated
+ * by the backend's cursor decode (`invalid-cursor` 400).
+ *
+ * @param options {object}
+ * @param options.body {object}   the parsed query POST body
+ * @param [options.requestName] {string}
+ * @returns {{ query: BlindedIndexQuery, count: boolean, limit?: number, cursor?: string }}
+ */
+export function parseBlindedIndexQueryBody({ body, requestName }) {
+    const { index, equals, has, count, limit, cursor } = body;
+    if (typeof index !== 'string' || index.length === 0) {
+        throw new InvalidRequestBodyError({
+            requestName,
+            detail: 'A blinded-index query requires a non-empty string "index".',
+            pointer: '#/index'
+        });
+    }
+    // Exactly one of `equals` / `has` (the EDV client never sends both; the
+    // reference server schema requires at least one).
+    if ((equals === undefined) === (has === undefined)) {
+        throw new InvalidRequestBodyError({
+            requestName,
+            detail: 'A blinded-index query requires exactly one of "equals" or "has".'
+        });
+    }
+    const query = { index };
+    if (equals !== undefined) {
+        if (!Array.isArray(equals) || equals.length === 0) {
+            throw new InvalidRequestBodyError({
+                requestName,
+                detail: '"equals" must be a non-empty array of objects.',
+                pointer: '#/equals'
+            });
+        }
+        for (const element of equals) {
+            if (typeof element !== 'object' ||
+                element === null ||
+                Array.isArray(element) ||
+                Object.values(element).some(value => typeof value !== 'string')) {
+                throw new InvalidRequestBodyError({
+                    requestName,
+                    detail: '"equals" elements must be objects mapping blinded attribute names to blinded string values.',
+                    pointer: '#/equals'
+                });
+            }
+        }
+        query.equals = equals;
+    }
+    if (has !== undefined) {
+        if (!Array.isArray(has) ||
+            has.length === 0 ||
+            has.some(name => typeof name !== 'string')) {
+            throw new InvalidRequestBodyError({
+                requestName,
+                detail: '"has" must be a non-empty array of blinded attribute names.',
+                pointer: '#/has'
+            });
+        }
+        query.has = has;
+    }
+    if (count !== undefined && typeof count !== 'boolean') {
+        throw new InvalidRequestBodyError({
+            requestName,
+            detail: '"count" must be a boolean.',
+            pointer: '#/count'
+        });
+    }
+    if (cursor !== undefined && typeof cursor !== 'string') {
+        throw new InvalidRequestBodyError({
+            requestName,
+            detail: '"cursor" must be a string.',
+            pointer: '#/cursor'
+        });
+    }
+    // Lenient `limit` coercion, same as the `changes` profile: a non-numeric or
+    // `< 1` value is ignored so the backend applies its own default/clamp.
+    const parsedLimit = Number(limit);
+    const resolvedLimit = Number.isFinite(parsedLimit) && parsedLimit >= 1 ? parsedLimit : undefined;
+    return {
+        query,
+        count: count === true,
+        ...(resolvedLimit !== undefined && { limit: resolvedLimit }),
+        ...(cursor !== undefined && { cursor })
+    };
+}
+/**
+ * Collects the `{name: value}` attribute pairs of a document's `indexed`
+ * entries into flat `name:value` terms. `scopedTo` limits collection to the
+ * entries of one HMAC key id (the `equals` scope); without it, attributes of
+ * every entry are collected (the `has` scope, matching the reference servers'
+ * Mongo-parity semantics where `has` names may come from any entry).
+ * Malformed entries and attributes are skipped, never thrown on.
+ *
+ * @param options {object}
+ * @param options.indexed {unknown[]}   the document's `indexed` array
+ * @param [options.scopedTo] {string}   collect only entries with this hmac id
+ * @returns {{ names: Set<string>, terms: Set<string> }}
+ */
+function collectIndexedAttributes({ indexed, scopedTo }) {
+    const names = new Set();
+    const terms = new Set();
+    for (const entry of indexed) {
+        if (typeof entry !== 'object' || entry === null) {
+            continue;
+        }
+        const { hmac, attributes } = entry;
+        if (scopedTo !== undefined && hmac?.id !== scopedTo) {
+            continue;
+        }
+        if (!Array.isArray(attributes)) {
+            continue;
+        }
+        for (const attribute of attributes) {
+            if (typeof attribute?.name !== 'string') {
+                continue;
+            }
+            names.add(attribute.name);
+            if (typeof attribute.value === 'string') {
+                terms.add(`${attribute.name}:${attribute.value}`);
+            }
+        }
+    }
+    return { names, terms };
+}
+/**
+ * True when a stored JSON document matches a blinded-index query. The document
+ * must carry an `indexed` entry for the queried `index` (HMAC key id); then
+ * `equals` matches when SOME array element has ALL its `{name: value}` pairs
+ * present among that index's blinded attributes (an empty element matches
+ * nothing -- the reference servers' Mongo `$all: []` parity, which the EDV
+ * client emits when querying a never-indexed attribute), and `has` matches
+ * when ALL named attributes are present (from any indexed entry). Purely
+ * structural string matching -- no decoding, no crypto.
+ *
+ * @param options {object}
+ * @param options.document {unknown}   the stored (parsed) resource JSON
+ * @param options.query {BlindedIndexQuery}
+ * @returns {boolean}
+ */
+export function matchesBlindedIndexQuery({ document, query }) {
+    if (typeof document !== 'object' || document === null) {
+        return false;
+    }
+    const { indexed } = document;
+    if (!Array.isArray(indexed)) {
+        return false;
+    }
+    // The document must be indexed under the queried HMAC key at all.
+    const scoped = collectIndexedAttributes({ indexed, scopedTo: query.index });
+    if (scoped.names.size === 0) {
+        return false;
+    }
+    if (query.equals !== undefined) {
+        return query.equals.some(element => {
+            const pairs = Object.entries(element);
+            return (pairs.length > 0 &&
+                pairs.every(([name, value]) => scoped.terms.has(`${name}:${value}`)));
+        });
+    }
+    // `has`: every named attribute present, from any indexed entry.
+    const all = collectIndexedAttributes({ indexed });
+    return (query.has ?? []).every(name => all.names.has(name));
+}
+/**
+ * Evaluates a blinded-index query over a Collection's candidate documents and
+ * shapes the result: a bare `{count}` for a count query, else a page of
+ * matching documents in ascending `resourceId` (code-unit) order with the
+ * standard opaque-cursor pagination (`limit` clamped to `[1, MAX_PAGE_SIZE]`,
+ * default `DEFAULT_PAGE_SIZE`; `cursor` resumes strictly after its anchor id,
+ * so paging stays correct if the anchor was deleted between pages). A
+ * malformed `cursor` rejects with `invalid-cursor` (400).
+ *
+ * Backends call this with every live JSON document of the Collection -- an
+ * O(n) full scan, deliberate for these teaching backends (an indexed backend
+ * would answer from flattened `hmacId:name:value` attribute tokens, the
+ * bedrock-edv-storage strategy).
+ *
+ * @param options {object}
+ * @param options.candidates {Array<{resourceId: string, document: unknown}>}
+ * @param options.query {BlindedIndexQuery}
+ * @param [options.count] {boolean}   return only the match count
+ * @param [options.limit] {number}   requested page size
+ * @param [options.cursor] {string}   opaque cursor from a prior page
+ * @returns {{ count: number } | BlindedIndexQueryPage}
+ */
+export function runBlindedIndexQuery({ candidates, query, count, limit, cursor }) {
+    const matches = candidates
+        .filter(candidate => matchesBlindedIndexQuery({ document: candidate.document, query }))
+        // Ascending `resourceId` in code-unit order -- the SAME ordering the
+        // cursor seek (`resourceId > after`) uses, so the keyset is stable.
+        .sort((left, right) => left.resourceId < right.resourceId
+        ? -1
+        : left.resourceId > right.resourceId
+            ? 1
+            : 0);
+    if (count === true) {
+        return { count: matches.length };
+    }
+    // Seek strictly past the cursor's anchor id.
+    let startIndex = 0;
+    if (cursor !== undefined) {
+        const { after } = decodeCursor(cursor);
+        const found = matches.findIndex(({ resourceId }) => resourceId > after);
+        startIndex = found === -1 ? matches.length : found;
+    }
+    const pageSize = limit === undefined ? DEFAULT_PAGE_SIZE : clampPageSize(limit);
+    // Take `pageSize + 1` to detect a further page without a second pass.
+    const window = matches.slice(startIndex, startIndex + pageSize + 1);
+    const hasMore = window.length > pageSize;
+    const page = hasMore ? window.slice(0, pageSize) : window;
+    return {
+        documents: page.map(({ document }) => document),
+        hasMore,
+        ...(hasMore && {
+            cursor: encodeCursor(page[page.length - 1].resourceId)
+        })
+    };
+}
+/**
+ * Collects a document's `unique: true` blinded attributes as
+ * `(hmac id, name, value)` triples -- the claims the EDV unique-attribute
+ * invariant protects. Malformed entries and attributes are skipped, never
+ * thrown on; an attribute counts only when `unique` is exactly `true` and
+ * both `name` and `value` are strings.
+ *
+ * @param options {object}
+ * @param options.document {unknown}   the (parsed) document JSON
+ * @returns {Array<{ hmacId: string, name: string, value: string }>}
+ */
+export function collectUniqueBlindedTerms({ document }) {
+    if (typeof document !== 'object' || document === null) {
+        return [];
+    }
+    const { indexed } = document;
+    if (!Array.isArray(indexed)) {
+        return [];
+    }
+    const terms = [];
+    for (const entry of indexed) {
+        if (typeof entry !== 'object' || entry === null) {
+            continue;
+        }
+        const { hmac, attributes } = entry;
+        if (typeof hmac?.id !== 'string' || !Array.isArray(attributes)) {
+            continue;
+        }
+        for (const attribute of attributes) {
+            if (attribute?.unique === true &&
+                typeof attribute.name === 'string' &&
+                typeof attribute.value === 'string') {
+                terms.push({
+                    hmacId: hmac.id,
+                    name: attribute.name,
+                    value: attribute.value
+                });
+            }
+        }
+    }
+    return terms;
+}
+/**
+ * Enforces the EDV unique-attribute invariant on a write: a `unique: true`
+ * blinded `(hmac id, name, value)` triple may be claimed by at most one live
+ * document per Collection. Following the reference servers
+ * (`@interop/edv-server`, bedrock-edv-storage's unique index over
+ * `uniqueAttributes`), a conflict requires the attribute be marked
+ * `unique: true` on BOTH sides -- an existing document carrying the same
+ * triple without `unique` does not conflict -- and the triple is keyed on the
+ * full `(hmac id, name, value)`, so the same blinded pair under a different
+ * HMAC key is no conflict. `candidates` MUST already exclude the document
+ * being written (its own resource id), so an update keeping its own unique
+ * attribute never self-conflicts. Throws `UniqueAttributeConflictError`
+ * (409) on a conflict; a document with no unique attributes never throws.
+ *
+ * The caller is responsible for making the check-and-write atomic (the
+ * filesystem backend serializes unique-carrying writes per Collection; the
+ * Postgres backend takes a per-Collection advisory lock in the write
+ * transaction).
+ *
+ * @param options {object}
+ * @param options.document {unknown}   the incoming (parsed) document JSON
+ * @param options.candidates {Array<{resourceId: string, document: unknown}>}
+ *   the Collection's other live JSON documents
+ * @returns {void}
+ */
+export function assertNoUniqueBlindedConflict({ document, candidates }) {
+    const incoming = collectUniqueBlindedTerms({ document });
+    if (incoming.length === 0) {
+        return;
+    }
+    // Key the triples unambiguously (hmac ids may themselves contain any
+    // delimiter, so a joined string could collide across segment boundaries).
+    const claimed = new Set(incoming.map(term => JSON.stringify([term.hmacId, term.name, term.value])));
+    for (const candidate of candidates) {
+        const held = collectUniqueBlindedTerms({ document: candidate.document });
+        for (const term of held) {
+            if (claimed.has(JSON.stringify([term.hmacId, term.name, term.value]))) {
+                throw new UniqueAttributeConflictError();
+            }
+        }
+    }
+}
+//# sourceMappingURL=blindedIndex.js.map

package/dist/lib/blindedIndex.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"blindedIndex.js","sourceRoot":"","sources":["../../src/lib/blindedIndex.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AACxD,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAA;AAClE,OAAO,EACL,uBAAuB,EACvB,4BAA4B,EAC7B,MAAM,cAAc,CAAA;AA+BrB;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,0BAA0B,CAAC,EACzC,IAAI,EACJ,WAAW,EAWZ;IAMC,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI,CAAA;IAEzD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACpD,MAAM,IAAI,uBAAuB,CAAC;YAChC,WAAW;YACX,MAAM,EAAE,4DAA4D;YACpE,OAAO,EAAE,SAAS;SACnB,CAAC,CAAA;IACJ,CAAC;IAED,wEAAwE;IACxE,kDAAkD;IAClD,IAAI,CAAC,MAAM,KAAK,SAAS,CAAC,KAAK,CAAC,GAAG,KAAK,SAAS,CAAC,EAAE,CAAC;QACnD,MAAM,IAAI,uBAAuB,CAAC;YAChC,WAAW;YACX,MAAM,EAAE,kEAAkE;SAC3E,CAAC,CAAA;IACJ,CAAC;IAED,MAAM,KAAK,GAAsB,EAAE,KAAK,EAAE,CAAA;IAC1C,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAClD,MAAM,IAAI,uBAAuB,CAAC;gBAChC,WAAW;gBACX,MAAM,EAAE,gDAAgD;gBACxD,OAAO,EAAE,UAAU;aACpB,CAAC,CAAA;QACJ,CAAC;QACD,KAAK,MAAM,OAAO,IAAI,MAAM,EAAE,CAAC;YAC7B,IACE,OAAO,OAAO,KAAK,QAAQ;gBAC3B,OAAO,KAAK,IAAI;gBAChB,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC;gBACtB,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,OAAO,KAAK,KAAK,QAAQ,CAAC,EAC/D,CAAC;gBACD,MAAM,IAAI,uBAAuB,CAAC;oBAChC,WAAW;oBACX,MAAM,EACJ,6FAA6F;oBAC/F,OAAO,EAAE,UAAU;iBACpB,CAAC,CAAA;YACJ,CAAC;QACH,CAAC;QACD,KAAK,CAAC,MAAM,GAAG,MAAuC,CAAA;IACxD,CAAC;IACD,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;QACtB,IACE,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC;YACnB,GAAG,CAAC,MAAM,KAAK,CAAC;YAChB,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,IAAI,KAAK,QAAQ,CAAC,EAC1C,CAAC;YACD,MAAM,IAAI,uBAAuB,CAAC;gBAChC,WAAW;gBACX,MAAM,EAAE,6DAA6D;gBACrE,OAAO,EAAE,OAAO;aACjB,CAAC,CAAA;QACJ,CAAC;QACD,KAAK,CAAC,GAAG,GAAG,GAAe,CAAA;IAC7B,CAAC;IAED,IAAI,KAAK,KAAK,SAAS,IAAI,OAAO,KAAK,KAAK,SAAS,EAAE,CAAC;QACtD,MAAM,IAAI,uBAAuB,CAAC;YAChC,WAAW;YACX,MAAM,EAAE,4BAA4B;YACpC,OAAO,EAAE,SAAS;SACnB,CAAC,CAAA;IACJ,CAAC;IAED,IAAI,MAAM,KAAK,SAAS,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;QACvD,MAAM,IAAI,uBAAuB,CAAC;YAChC,WAAW;YACX,MAAM,EAAE,4BAA4B;YACpC,OAAO,EAAE,UAAU;SACpB,CAAC,CAAA;IACJ,CAAC;IAED,4EAA4E;IAC5E,uEAAuE;IACvE,MAAM,WAAW,GAAG,MAAM,CAAC,KAAK,CAAC,CAAA;IACjC,MAAM,aAAa,GACjB,MAAM,CAAC,QAAQ,CAAC,WAAW,CAAC,IAAI,WAAW,IAAI,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,SAAS,CAAA;IAE5E,OAAO;QACL,KAAK;QACL,KAAK,EAAE,KAAK,KAAK,IAAI;QACrB,GAAG,CAAC,aAAa,KAAK,SAAS,IAAI,EAAE,KAAK,EAAE,aAAa,EAAE,CAAC;QAC5D,GAAG,CAAC,MAAM,KAAK,SAAS,IAAI,EAAE,MAAM,EAAE,CAAC;KACxC,CAAA;AACH,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,SAAS,wBAAwB,CAAC,EAChC,OAAO,EACP,QAAQ,EAIT;IACC,MAAM,KAAK,GAAG,IAAI,GAAG,EAAU,CAAA;IAC/B,MAAM,KAAK,GAAG,IAAI,GAAG,EAAU,CAAA;IAC/B,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;YAChD,SAAQ;QACV,CAAC;QACD,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,GAAG,KAG5B,CAAA;QACD,IAAI,QAAQ,KAAK,SAAS,IAAI,IAAI,EAAE,EAAE,KAAK,QAAQ,EAAE,CAAC;YACpD,SAAQ;QACV,CAAC;QACD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,CAAC;YAC/B,SAAQ;QACV,CAAC;QACD,KAAK,MAAM,SAAS,IAAI,UAAgC,EAAE,CAAC;YACzD,IAAI,OAAO,SAAS,EAAE,IAAI,KAAK,QAAQ,EAAE,CAAC;gBACxC,SAAQ;YACV,CAAC;YACD,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,CAAC,CAAA;YACzB,IAAI,OAAO,SAAS,CAAC,KAAK,KAAK,QAAQ,EAAE,CAAC;gBACxC,KAAK,CAAC,GAAG,CAAC,GAAG,SAAS,CAAC,IAAI,IAAI,SAAS,CAAC,KAAK,EAAE,CAAC,CAAA;YACnD,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,CAAA;AACzB,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,wBAAwB,CAAC,EACvC,QAAQ,EACR,KAAK,EAIN;IACC,IAAI,OAAO,QAAQ,KAAK,QAAQ,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;QACtD,OAAO,KAAK,CAAA;IACd,CAAC;IACD,MAAM,EAAE,OAAO,EAAE,GAAG,QAAiC,CAAA;IACrD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QAC5B,OAAO,KAAK,CAAA;IACd,CAAC;IAED,kEAAkE;IAClE,MAAM,MAAM,GAAG,wBAAwB,CAAC,EAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC,CAAA;IAC3E,IAAI,MAAM,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;QAC5B,OAAO,KAAK,CAAA;IACd,CAAC;IAED,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;QAC/B,OAAO,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE;YACjC,MAAM,KAAK,GAAG,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,CAAA;YACrC,OAAO,CACL,KAAK,CAAC,MAAM,GAAG,CAAC;gBAChB,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,IAAI,IAAI,KAAK,EAAE,CAAC,CAAC,CACrE,CAAA;QACH,CAAC,CAAC,CAAA;IACJ,CAAC;IACD,gEAAgE;IAChE,MAAM,GAAG,GAAG,wBAAwB,CAAC,EAAE,OAAO,EAAE,CAAC,CAAA;IACjD,OAAO,CAAC,KAAK,CAAC,GAAG,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAA;AAC7D,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,oBAAoB,CAAC,EACnC,UAAU,EACV,KAAK,EACL,KAAK,EACL,KAAK,EACL,MAAM,EAOP;IACC,MAAM,OAAO,GAAG,UAAU;SACvB,MAAM,CAAC,SAAS,CAAC,EAAE,CAClB,wBAAwB,CAAC,EAAE,QAAQ,EAAE,SAAS,CAAC,QAAQ,EAAE,KAAK,EAAE,CAAC,CAClE;QACD,qEAAqE;QACrE,oEAAoE;SACnE,IAAI,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CACpB,IAAI,CAAC,UAAU,GAAG,KAAK,CAAC,UAAU;QAChC,CAAC,CAAC,CAAC,CAAC;QACJ,CAAC,CAAC,IAAI,CAAC,UAAU,GAAG,KAAK,CAAC,UAAU;YAClC,CAAC,CAAC,CAAC;YACH,CAAC,CAAC,CAAC,CACR,CAAA;IAEH,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QACnB,OAAO,EAAE,KAAK,EAAE,OAAO,CAAC,MAAM,EAAE,CAAA;IAClC,CAAC;IAED,6CAA6C;IAC7C,IAAI,UAAU,GAAG,CAAC,CAAA;IAClB,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,MAAM,EAAE,KAAK,EAAE,GAAG,YAAY,CAAC,MAAM,CAAC,CAAA;QACtC,MAAM,KAAK,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC,EAAE,UAAU,EAAE,EAAE,EAAE,CAAC,UAAU,GAAG,KAAK,CAAC,CAAA;QACvE,UAAU,GAAG,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAA;IACpD,CAAC;IAED,MAAM,QAAQ,GACZ,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC,aAAa,CAAC,KAAK,CAAC,CAAA;IAEhE,sEAAsE;IACtE,MAAM,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,UAAU,EAAE,UAAU,GAAG,QAAQ,GAAG,CAAC,CAAC,CAAA;IACnE,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,GAAG,QAAQ,CAAA;IACxC,MAAM,IAAI,GAAG,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,MAAM,CAAA;IAEzD,OAAO;QACL,SAAS,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC,QAAQ,CAAC;QAC/C,OAAO;QACP,GAAG,CAAC,OAAO,IAAI;YACb,MAAM,EAAE,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAE,CAAC,UAAU,CAAC;SACxD,CAAC;KACH,CAAA;AACH,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,yBAAyB,CAAC,EACxC,QAAQ,EAGT;IACC,IAAI,OAAO,QAAQ,KAAK,QAAQ,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;QACtD,OAAO,EAAE,CAAA;IACX,CAAC;IACD,MAAM,EAAE,OAAO,EAAE,GAAG,QAAiC,CAAA;IACrD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QAC5B,OAAO,EAAE,CAAA;IACX,CAAC;IACD,MAAM,KAAK,GAA2D,EAAE,CAAA;IACxE,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;YAChD,SAAQ;QACV,CAAC;QACD,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,GAAG,KAG5B,CAAA;QACD,IAAI,OAAO,IAAI,EAAE,EAAE,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,CAAC;YAC/D,SAAQ;QACV,CAAC;QACD,KAAK,MAAM,SAAS,IAAI,UAEvB,EAAE,CAAC;YACF,IACE,SAAS,EAAE,MAAM,KAAK,IAAI;gBAC1B,OAAO,SAAS,CAAC,IAAI,KAAK,QAAQ;gBAClC,OAAO,SAAS,CAAC,KAAK,KAAK,QAAQ,EACnC,CAAC;gBACD,KAAK,CAAC,IAAI,CAAC;oBACT,MAAM,EAAE,IAAI,CAAC,EAAE;oBACf,IAAI,EAAE,SAAS,CAAC,IAAI;oBACpB,KAAK,EAAE,SAAS,CAAC,KAAK;iBACvB,CAAC,CAAA;YACJ,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAA;AACd,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,UAAU,6BAA6B,CAAC,EAC5C,QAAQ,EACR,UAAU,EAIX;IACC,MAAM,QAAQ,GAAG,yBAAyB,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAA;IACxD,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1B,OAAM;IACR,CAAC;IACD,qEAAqE;IACrE,0EAA0E;IAC1E,MAAM,OAAO,GAAG,IAAI,GAAG,CACrB,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAC3E,CAAA;IACD,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;QACnC,MAAM,IAAI,GAAG,yBAAyB,CAAC,EAAE,QAAQ,EAAE,SAAS,CAAC,QAAQ,EAAE,CAAC,CAAA;QACxE,KAAK,MAAM,IAAI,IAAI,IAAI,EAAE,CAAC;YACxB,IAAI,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;gBACtE,MAAM,IAAI,4BAA4B,EAAE,CAAA;YAC1C,CAAC;QACH,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/lib/collectionDescription.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Backend-agnostic normalization of a Collection Description about to be
+ * persisted (the `key-epochs` / conditional-Collection-write feature). Both
+ * storage backends run the same rule through {@link normalizeDescriptionWrite}
+ * so their stored bodies and version arithmetic cannot drift; only the storage
+ * of the resolved version differs downstream (a `_version` member in the
+ * filesystem description file vs the Postgres `description_version` column).
+ */
+import type { CollectionDescription } from '../types.js';
+/**
+ * Splits an incoming Collection Description into the body to persist and the
+ * description version to stamp. The two version-bearing members a wire or
+ * archived description may carry are stripped from the body: `_version` (the
+ * archive interchange token embedded by `exportSpace`) and
+ * `descriptionVersion` (the out-of-band `ETag` validator that
+ * `getCollectionDescription` attaches, which a caller may have spread back
+ * in). The version to stamp resolves with the precedence: the explicit
+ * `descriptionVersion` argument (the write path's monotonic bump), else the
+ * archived `_version` (the import path), else 1 (a first write).
+ *
+ * @param options {object}
+ * @param options.collectionDescription {CollectionDescription}
+ * @param [options.descriptionVersion] {number}   the explicit version to stamp
+ * @returns {{ body: CollectionDescription, version: number }}
+ */
+export declare function normalizeDescriptionWrite({ collectionDescription, descriptionVersion }: {
+    collectionDescription: CollectionDescription;
+    descriptionVersion?: number;
+}): {
+    body: CollectionDescription;
+    version: number;
+};
+//# sourceMappingURL=collectionDescription.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"collectionDescription.d.ts","sourceRoot":"","sources":["../../src/lib/collectionDescription.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAA;AAExD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,yBAAyB,CAAC,EACxC,qBAAqB,EACrB,kBAAkB,EACnB,EAAE;IACD,qBAAqB,EAAE,qBAAqB,CAAA;IAC5C,kBAAkB,CAAC,EAAE,MAAM,CAAA;CAC5B,GAAG;IAAE,IAAI,EAAE,qBAAqB,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAUnD"}

package/dist/lib/collectionDescription.js

@@ -0,0 +1,21 @@
+/**
+ * Splits an incoming Collection Description into the body to persist and the
+ * description version to stamp. The two version-bearing members a wire or
+ * archived description may carry are stripped from the body: `_version` (the
+ * archive interchange token embedded by `exportSpace`) and
+ * `descriptionVersion` (the out-of-band `ETag` validator that
+ * `getCollectionDescription` attaches, which a caller may have spread back
+ * in). The version to stamp resolves with the precedence: the explicit
+ * `descriptionVersion` argument (the write path's monotonic bump), else the
+ * archived `_version` (the import path), else 1 (a first write).
+ *
+ * @param options {object}
+ * @param options.collectionDescription {CollectionDescription}
+ * @param [options.descriptionVersion] {number}   the explicit version to stamp
+ * @returns {{ body: CollectionDescription, version: number }}
+ */
+export function normalizeDescriptionWrite({ collectionDescription, descriptionVersion }) {
+    const { _version: incomingVersion, descriptionVersion: _staleVersion, ...body } = collectionDescription;
+    return { body, version: descriptionVersion ?? incomingVersion ?? 1 };
+}
+//# sourceMappingURL=collectionDescription.js.map

package/dist/lib/collectionDescription.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"collectionDescription.js","sourceRoot":"","sources":["../../src/lib/collectionDescription.ts"],"names":[],"mappings":"AAUA;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,yBAAyB,CAAC,EACxC,qBAAqB,EACrB,kBAAkB,EAInB;IACC,MAAM,EACJ,QAAQ,EAAE,eAAe,EACzB,kBAAkB,EAAE,aAAa,EACjC,GAAG,IAAI,EACR,GAAG,qBAGH,CAAA;IACD,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,kBAAkB,IAAI,eAAe,IAAI,CAAC,EAAE,CAAA;AACtE,CAAC"}

package/dist/lib/cursor.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Encodes a keyset position into an opaque cursor token.
+ * @param after {string} - `resourceId` of the last item already returned
+ * @returns {string} - base64url-encoded cursor
+ */
+export declare function encodeCursor(after: string): string;
+/**
+ * Decodes an opaque cursor token back into its keyset position. Throws
+ * `InvalidCursorError` (400 `invalid-cursor`) when the token is not valid
+ * base64url, is not JSON, or does not carry a string `after` -- i.e. a cursor
+ * the server cannot honor (malformed, tampered with, or from another context).
+ * @param cursor {string}   the cursor query parameter
+ * @returns {{ after: string }}
+ */
+export declare function decodeCursor(cursor: string): {
+    after: string;
+};
+//# sourceMappingURL=cursor.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cursor.d.ts","sourceRoot":"","sources":["../../src/lib/cursor.ts"],"names":[],"mappings":"AAcA;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAElD;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CAoB9D"}

package/dist/lib/cursor.js

@@ -0,0 +1,50 @@
+/**
+ * Opaque pagination cursor codec for the List Collection operation (spec
+ * "Pagination"). A cursor names the position to resume an ordered keyset scan
+ * from -- here, the `resourceId` of the last item already returned. It is
+ * OPAQUE to clients: the server encodes and decodes it, and the client only ever
+ * echoes back the `cursor` baked into a prior page's `next` URL.
+ *
+ * The encoding is `base64url(JSON.stringify({ after }))`. It is deliberately not
+ * a signed or encrypted token -- it leaks nothing a caller authorized to list
+ * the Collection cannot already see (a `resourceId`), and a tampered cursor is
+ * rejected as `invalid-cursor` rather than trusted.
+ */
+import { InvalidCursorError } from '../errors.js';
+/**
+ * Encodes a keyset position into an opaque cursor token.
+ * @param after {string} - `resourceId` of the last item already returned
+ * @returns {string} - base64url-encoded cursor
+ */
+export function encodeCursor(after) {
+    return Buffer.from(JSON.stringify({ after }), 'utf8').toString('base64url');
+}
+/**
+ * Decodes an opaque cursor token back into its keyset position. Throws
+ * `InvalidCursorError` (400 `invalid-cursor`) when the token is not valid
+ * base64url, is not JSON, or does not carry a string `after` -- i.e. a cursor
+ * the server cannot honor (malformed, tampered with, or from another context).
+ * @param cursor {string}   the cursor query parameter
+ * @returns {{ after: string }}
+ */
+export function decodeCursor(cursor) {
+    // base64url charset only (no `+`, `/`, or `=` padding); `Buffer` decoding is
+    // lenient and would silently drop stray characters, so reject them up front.
+    if (!/^[A-Za-z0-9_-]+$/.test(cursor)) {
+        throw new InvalidCursorError();
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(Buffer.from(cursor, 'base64url').toString('utf8'));
+    }
+    catch (err) {
+        throw new InvalidCursorError({ cause: err });
+    }
+    if (typeof parsed !== 'object' ||
+        parsed === null ||
+        typeof parsed.after !== 'string') {
+        throw new InvalidCursorError();
+    }
+    return { after: parsed.after };
+}
+//# sourceMappingURL=cursor.js.map

package/dist/lib/cursor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cursor.js","sourceRoot":"","sources":["../../src/lib/cursor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAA;AAEjD;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,KAAa;IACxC,OAAO,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAA;AAC7E,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAAC,MAAc;IACzC,6EAA6E;IAC7E,6EAA6E;IAC7E,IAAI,CAAC,kBAAkB,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;QACrC,MAAM,IAAI,kBAAkB,EAAE,CAAA;IAChC,CAAC;IACD,IAAI,MAAe,CAAA;IACnB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAA;IACxE,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,kBAAkB,CAAC,EAAE,KAAK,EAAE,GAAY,EAAE,CAAC,CAAA;IACvD,CAAC;IACD,IACE,OAAO,MAAM,KAAK,QAAQ;QAC1B,MAAM,KAAK,IAAI;QACf,OAAQ,MAA8B,CAAC,KAAK,KAAK,QAAQ,EACzD,CAAC;QACD,MAAM,IAAI,kBAAkB,EAAE,CAAA;IAChC,CAAC;IACD,OAAO,EAAE,KAAK,EAAG,MAA4B,CAAC,KAAK,EAAE,CAAA;AACvD,CAAC"}

package/dist/lib/edvEnvelope.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Structural validator for the `edv` encryption scheme's envelope profile (spec
+ * "Encryption Scheme Registry"). An `edv`-encrypted Resource is stored as an EDV
+ * **Encrypted Document** -- a JSON object whose `jwe` member is a JWE in JSON
+ * serialization (general or flattened, RFC7516). This checks only its *shape* so
+ * the server can fail closed on a non-envelope write into an encrypted
+ * Collection. The server MUST NOT attempt decryption and MUST NOT interpret the
+ * ciphertext or key values -- it validates that the document carries a
+ * plausible JWE, not that it decrypts.
+ */
+/**
+ * True if `entry` is a structurally valid JWE general-serialization
+ * `recipients` array entry: an object whose OPTIONAL `header` is an object and
+ * whose OPTIONAL `encrypted_key` is a string. Purely structural (values are
+ * never decoded); shared by {@link isValidEdvEnvelope} and the Collection
+ * key-epoch marker validator (`lib/encryption.ts`), which reuses the JWE
+ * recipients entry shape verbatim -- one wire vocabulary.
+ *
+ * @param entry {unknown}   one element of a `recipients` array
+ * @returns {boolean}
+ */
+export declare function isValidJweRecipientEntry(entry: unknown): boolean;
+/**
+ * True if `body` is a structurally valid JWE-JSON-serialization object: an
+ * object with a required non-empty string `ciphertext`; optional string
+ * `protected` / `iv` / `tag` / `encrypted_key`; an optional `recipients` array
+ * of `{ header?: object, encrypted_key?: string }`; and at least one key-delivery
+ * member present (`recipients` non-empty, top-level `encrypted_key`, or
+ * `protected` -- covering general, flattened, and direct JWE serializations).
+ * Purely structural: values are never decoded or decrypted.
+ *
+ * @param body {unknown}   the parsed request body to check
+ * @returns {boolean}
+ */
+export declare function isValidEdvEnvelope(body: unknown): boolean;
+/**
+ * True if `body` is a structurally valid EDV **Encrypted Document**: a JSON
+ * object whose `jwe` member is a valid JWE-JSON envelope ({@link
+ * isValidEdvEnvelope}). This is the actual stored representation the EDV codec
+ * produces -- `documentCipher.encrypt` nests the JWE under `jwe` alongside EDV
+ * bookkeeping members (`id`, `sequence`, `indexed`), which are opaque to the
+ * server and not checked. A bare JWE (top-level `ciphertext`, no `jwe`) or a
+ * plaintext object fails this check, so an enforcing server fails closed on a
+ * non-envelope write. Purely structural: values are never decoded or decrypted.
+ *
+ * @param body {unknown}   the parsed request body (or `custom` sub-value) to check
+ * @returns {boolean}
+ */
+export declare function isValidEdvDocument(body: unknown): boolean;
+//# sourceMappingURL=edvEnvelope.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"edvEnvelope.d.ts","sourceRoot":"","sources":["../../src/lib/edvEnvelope.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;;;;;;;;;GAUG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAoBhE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CA2CzD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAKzD"}

package/dist/lib/edvEnvelope.js

@@ -0,0 +1,106 @@
+/**
+ * Structural validator for the `edv` encryption scheme's envelope profile (spec
+ * "Encryption Scheme Registry"). An `edv`-encrypted Resource is stored as an EDV
+ * **Encrypted Document** -- a JSON object whose `jwe` member is a JWE in JSON
+ * serialization (general or flattened, RFC7516). This checks only its *shape* so
+ * the server can fail closed on a non-envelope write into an encrypted
+ * Collection. The server MUST NOT attempt decryption and MUST NOT interpret the
+ * ciphertext or key values -- it validates that the document carries a
+ * plausible JWE, not that it decrypts.
+ */
+/**
+ * True if `entry` is a structurally valid JWE general-serialization
+ * `recipients` array entry: an object whose OPTIONAL `header` is an object and
+ * whose OPTIONAL `encrypted_key` is a string. Purely structural (values are
+ * never decoded); shared by {@link isValidEdvEnvelope} and the Collection
+ * key-epoch marker validator (`lib/encryption.ts`), which reuses the JWE
+ * recipients entry shape verbatim -- one wire vocabulary.
+ *
+ * @param entry {unknown}   one element of a `recipients` array
+ * @returns {boolean}
+ */
+export function isValidJweRecipientEntry(entry) {
+    if (typeof entry !== 'object' || entry === null || Array.isArray(entry)) {
+        return false;
+    }
+    const recipient = entry;
+    if (recipient.header !== undefined &&
+        (typeof recipient.header !== 'object' ||
+            recipient.header === null ||
+            Array.isArray(recipient.header))) {
+        return false;
+    }
+    if (recipient.encrypted_key !== undefined &&
+        typeof recipient.encrypted_key !== 'string') {
+        return false;
+    }
+    return true;
+}
+/**
+ * True if `body` is a structurally valid JWE-JSON-serialization object: an
+ * object with a required non-empty string `ciphertext`; optional string
+ * `protected` / `iv` / `tag` / `encrypted_key`; an optional `recipients` array
+ * of `{ header?: object, encrypted_key?: string }`; and at least one key-delivery
+ * member present (`recipients` non-empty, top-level `encrypted_key`, or
+ * `protected` -- covering general, flattened, and direct JWE serializations).
+ * Purely structural: values are never decoded or decrypted.
+ *
+ * @param body {unknown}   the parsed request body to check
+ * @returns {boolean}
+ */
+export function isValidEdvEnvelope(body) {
+    if (typeof body !== 'object' || body === null || Array.isArray(body)) {
+        return false;
+    }
+    const envelope = body;
+    // Required: a non-empty string `ciphertext`.
+    if (typeof envelope.ciphertext !== 'string' ||
+        envelope.ciphertext.length === 0) {
+        return false;
+    }
+    // Optional string members.
+    for (const key of ['protected', 'iv', 'tag', 'encrypted_key']) {
+        if (envelope[key] !== undefined && typeof envelope[key] !== 'string') {
+            return false;
+        }
+    }
+    // Optional `recipients`: an array of `{ header?: object, encrypted_key?: string }`.
+    let hasRecipient = false;
+    if (envelope.recipients !== undefined) {
+        if (!Array.isArray(envelope.recipients)) {
+            return false;
+        }
+        for (const entry of envelope.recipients) {
+            if (!isValidJweRecipientEntry(entry)) {
+                return false;
+            }
+        }
+        hasRecipient = envelope.recipients.length > 0;
+    }
+    // anyOf: at least one key-delivery member -- a general-serialization
+    // `recipients` list, a flattened top-level `encrypted_key`, or a `protected`
+    // header (direct encryption, no per-recipient key).
+    return (hasRecipient ||
+        typeof envelope.encrypted_key === 'string' ||
+        typeof envelope.protected === 'string');
+}
+/**
+ * True if `body` is a structurally valid EDV **Encrypted Document**: a JSON
+ * object whose `jwe` member is a valid JWE-JSON envelope ({@link
+ * isValidEdvEnvelope}). This is the actual stored representation the EDV codec
+ * produces -- `documentCipher.encrypt` nests the JWE under `jwe` alongside EDV
+ * bookkeeping members (`id`, `sequence`, `indexed`), which are opaque to the
+ * server and not checked. A bare JWE (top-level `ciphertext`, no `jwe`) or a
+ * plaintext object fails this check, so an enforcing server fails closed on a
+ * non-envelope write. Purely structural: values are never decoded or decrypted.
+ *
+ * @param body {unknown}   the parsed request body (or `custom` sub-value) to check
+ * @returns {boolean}
+ */
+export function isValidEdvDocument(body) {
+    if (typeof body !== 'object' || body === null || Array.isArray(body)) {
+        return false;
+    }
+    return isValidEdvEnvelope(body.jwe);
+}
+//# sourceMappingURL=edvEnvelope.js.map