was-teaching-server 0.9.1

package/dist/lib/backends.d.ts

@@ -0,0 +1,142 @@
+/**
+ * Collection backend selection helpers (spec "Backends" / "Collection Backend
+ * Selected"). A Collection carries an optional `backend` object whose `id` MUST
+ * name one of the Space's backends-available; this module centralizes the three
+ * operations that need that list: enumerating the available backends, validating
+ * (and default-filling) a client-supplied `backend` on create/update, and
+ * resolving a stored `{ id }` to its full descriptor for `GET .../backend`.
+ *
+ * This reference server ships a single server-configured backend (the active
+ * `StorageBackend`, registered as `default`), so the available list has one
+ * entry; the indirection leaves room for multiple registered backends later.
+ */
+import type { BackendDescriptor, BackendRegistration, CollectionDescription, StorageBackend, StoredBackendRecord } from '../types.js';
+/** The conventional id of the server-assigned default backend (spec). */
+export declare const DEFAULT_BACKEND_ID = "default";
+/**
+ * Validates a client-supplied Collection `backend` value and returns the
+ * normalized `{ id }` to persist. An absent value defaults to the server's
+ * default backend. A present-but-malformed value (not an object, or no string
+ * `id`) is `invalid-request-body` (400); a well-formed value whose `id` is not
+ * in the Space's backends-available (the server `default` plus its registered
+ * `external` backends) is `unsupported-backend` (409). A registered `external`
+ * backend is now selectable here -- routing its data plane to the resolved
+ * adapter is the resolver's job (lib/backendRegistry.ts).
+ *
+ * @param options {object}
+ * @param options.storage {StorageBackend}   the request's storage backend
+ * @param options.spaceId {string}   the Space whose backends-available is checked
+ * @param [options.backend] {unknown}   the request body's `backend` value
+ * @param [options.requestName] {string}   request name for the 400 error title
+ * @returns {Promise<{ id: string }>}   the normalized backend reference to store
+ */
+export declare function assertSupportedBackend({ storage, spaceId, backend, requestName }: {
+    storage: StorageBackend;
+    spaceId: string;
+    backend?: unknown;
+    requestName?: string;
+}): Promise<{
+    id: string;
+}>;
+/**
+ * Resolves a Collection's selected backend to its full descriptor, for the
+ * `GET .../backend` ("Collection Backend Selected") response, consulting the
+ * Space's backends-available (server `default` plus registered `external`
+ * records). A stored description without a `backend` (created before the property
+ * existed) defaults to the server's default backend.
+ *
+ * @param options {object}
+ * @param options.storage {StorageBackend}   the request's storage backend
+ * @param options.spaceId {string}   the Space whose backends-available is checked
+ * @param options.collectionDescription {CollectionDescription}
+ * @returns {Promise<BackendDescriptor>}
+ */
+export declare function resolveBackendDescriptor({ storage, spaceId, collectionDescription }: {
+    storage: StorageBackend;
+    spaceId: string;
+    collectionDescription: CollectionDescription;
+}): Promise<BackendDescriptor>;
+/**
+ * Projects a full (secret-bearing) `StoredBackendRecord` down to the sanitized
+ * `BackendDescriptor` that every client-facing read path returns: the public
+ * descriptor fields plus a `connection` reduced to its public subset (no
+ * `authorizationCode` / `refreshToken` / etc.). The single projection shared by
+ * `FileSystemBackend.listBackends` and the register (`POST`/`PUT`) responses, so
+ * the secret material has exactly one place it could leak -- and does not.
+ * @param record {StoredBackendRecord}
+ * @returns {BackendDescriptor}
+ */
+export declare function sanitizeBackendRecord(record: StoredBackendRecord): BackendDescriptor;
+/**
+ * The backends advertised at `GET /space/:spaceId/backends`: the server's
+ * `default` backend first, followed by the Space's sanitized registered
+ * `external` backends. Also the single source of a Space's selectable backends
+ * for `assertSupportedBackend` / `resolveBackendDescriptor`.
+ * @param options {object}
+ * @param options.storage {StorageBackend}
+ * @param options.spaceId {string}
+ * @returns {Promise<BackendDescriptor[]>}
+ */
+export declare function listRegisteredBackends({ storage, spaceId }: {
+    storage: StorageBackend;
+    spaceId: string;
+}): Promise<BackendDescriptor[]>;
+/**
+ * Validates a backend-registration request body and returns the typed
+ * `BackendRegistration`. Enforces: an object body; a string `id`; a non-empty
+ * string `provider`; `managedBy` absent or `'external'` (a client may not
+ * register a `server` backend); and a `connection` object with a string `kind`.
+ * Throws `InvalidRequestBodyError` (400) with the offending `#/...` pointer.
+ * Does not check `id` URL-safety -- callers run `assertValidBackendId`.
+ * @param body {unknown}   the parsed request body
+ * @param options {object}
+ * @param [options.requestName] {string}   request name for the 400 error title
+ * @returns {BackendRegistration}
+ */
+export declare function parseBackendRegistration(body: unknown, { requestName }?: {
+    requestName?: string;
+}): BackendRegistration;
+/**
+ * Enforces the optional server-wide registration allowlist (config
+ * `WAS_ENABLED_BACKENDS`): the set of backend `provider` names a client may
+ * register. An `undefined` allowlist is **permissive** -- any provider passes,
+ * preserving the prior behavior where any provider could be registered. When the
+ * allowlist is configured, a `provider` outside it is rejected with
+ * `unsupported-backend` (409) pointing at `#/provider`. This is the fail-fast
+ * registration gate; the resolver's data-plane factory check
+ * (lib/backendRegistry.ts) remains the backstop for a provider with no live
+ * adapter.
+ * @param options {object}
+ * @param options.provider {string}   the registration's `provider`
+ * @param [options.enabledProviders] {string[]}   the configured allowlist, or
+ *   `undefined` for permissive
+ * @returns {void}
+ */
+export declare function assertProviderAllowed({ provider, enabledProviders }: {
+    provider: string;
+    enabledProviders?: string[];
+}): void;
+/**
+ * Asserts a registered-backend id is a single URL-safe path segment (it becomes
+ * both a URL segment and a `.backend.<id>.json` filename). A backend id is a
+ * body field, so a failure is `invalid-request-body` (400) pointing at `#/id`
+ * rather than a URL-param id error.
+ * @param id {string}
+ * @param options {object}
+ * @param [options.requestName] {string}   request name for the 400 error title
+ * @returns {void}
+ */
+export declare function assertValidBackendId(id: string, { requestName }?: {
+    requestName?: string;
+}): void;
+/**
+ * Assembles the full `StoredBackendRecord` to persist from a validated
+ * `BackendRegistration`: the descriptor fields, `managedBy: 'external'`, default
+ * `storageMode` / `features`, and the full (secret-bearing) connection stamped
+ * with `status: 'registered'` and the registration timestamp. The record is
+ * inert until the live provider adapter (future work) connects it.
+ * @param registration {BackendRegistration}
+ * @returns {StoredBackendRecord}
+ */
+export declare function buildBackendRecord(registration: BackendRegistration): StoredBackendRecord;
+//# sourceMappingURL=backends.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"backends.d.ts","sourceRoot":"","sources":["../../src/lib/backends.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EACV,iBAAiB,EAEjB,mBAAmB,EACnB,qBAAqB,EACrB,cAAc,EACd,mBAAmB,EACpB,MAAM,aAAa,CAAA;AAIpB,yEAAyE;AACzE,eAAO,MAAM,kBAAkB,YAAY,CAAA;AAgB3C;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,sBAAsB,CAAC,EAC3C,OAAO,EACP,OAAO,EACP,OAAO,EACP,WAAW,EACZ,EAAE;IACD,OAAO,EAAE,cAAc,CAAA;IACvB,OAAO,EAAE,MAAM,CAAA;IACf,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB,GAAG,OAAO,CAAC;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC,CAqB1B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,wBAAwB,CAAC,EAC7C,OAAO,EACP,OAAO,EACP,qBAAqB,EACtB,EAAE;IACD,OAAO,EAAE,cAAc,CAAA;IACvB,OAAO,EAAE,MAAM,CAAA;IACf,qBAAqB,EAAE,qBAAqB,CAAA;CAC7C,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAO7B;AAWD;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,mBAAmB,GAC1B,iBAAiB,CA2BnB;AAED;;;;;;;;;GASG;AACH,wBAAsB,sBAAsB,CAAC,EAC3C,OAAO,EACP,OAAO,EACR,EAAE;IACD,OAAO,EAAE,cAAc,CAAA;IACvB,OAAO,EAAE,MAAM,CAAA;CAChB,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAE/B;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,OAAO,EACb,EAAE,WAAW,EAAE,GAAE;IAAE,WAAW,CAAC,EAAE,MAAM,CAAA;CAAO,GAC7C,mBAAmB,CA2DrB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,qBAAqB,CAAC,EACpC,QAAQ,EACR,gBAAgB,EACjB,EAAE;IACD,QAAQ,EAAE,MAAM,CAAA;IAChB,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAA;CAC5B,GAAG,IAAI,CAWP;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAClC,EAAE,EAAE,MAAM,EACV,EAAE,WAAW,EAAE,GAAE;IAAE,WAAW,CAAC,EAAE,MAAM,CAAA;CAAO,GAC7C,IAAI,CAQN;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAChC,YAAY,EAAE,mBAAmB,GAChC,mBAAmB,CAerB"}

package/dist/lib/backends.js

@@ -0,0 +1,272 @@
+import { InvalidRequestBodyError, UnsupportedBackendError } from '../errors.js';
+import { isUrlSafeSegment } from './validateId.js';
+/** The conventional id of the server-assigned default backend (spec). */
+export const DEFAULT_BACKEND_ID = 'default';
+// `listRegisteredBackends` (defined below, with the registration helpers) is the
+// single source of a Space's selectable backends -- the server `default` plus
+// its registered `external` records -- used by both the selection-validation
+// (`assertSupportedBackend`) and descriptor-resolution (`resolveBackendDescriptor`)
+// paths below.
+/** The public (secret-free) subset of a connection a sanitized read may carry. */
+const PUBLIC_CONNECTION_FIELDS = [
+    'account',
+    'scope',
+    'connectedAt',
+    'rootFolderName'
+];
+/**
+ * Validates a client-supplied Collection `backend` value and returns the
+ * normalized `{ id }` to persist. An absent value defaults to the server's
+ * default backend. A present-but-malformed value (not an object, or no string
+ * `id`) is `invalid-request-body` (400); a well-formed value whose `id` is not
+ * in the Space's backends-available (the server `default` plus its registered
+ * `external` backends) is `unsupported-backend` (409). A registered `external`
+ * backend is now selectable here -- routing its data plane to the resolved
+ * adapter is the resolver's job (lib/backendRegistry.ts).
+ *
+ * @param options {object}
+ * @param options.storage {StorageBackend}   the request's storage backend
+ * @param options.spaceId {string}   the Space whose backends-available is checked
+ * @param [options.backend] {unknown}   the request body's `backend` value
+ * @param [options.requestName] {string}   request name for the 400 error title
+ * @returns {Promise<{ id: string }>}   the normalized backend reference to store
+ */
+export async function assertSupportedBackend({ storage, spaceId, backend, requestName }) {
+    if (backend === undefined) {
+        return { id: DEFAULT_BACKEND_ID };
+    }
+    if (typeof backend !== 'object' ||
+        backend === null ||
+        typeof backend.id !== 'string') {
+        throw new InvalidRequestBodyError({
+            requestName,
+            detail: 'Collection "backend" must be an object with a string "id".',
+            pointer: '#/backend'
+        });
+    }
+    const { id } = backend;
+    const available = await listRegisteredBackends({ storage, spaceId });
+    if (!available.some(entry => entry.id === id)) {
+        throw new UnsupportedBackendError({ backendId: id });
+    }
+    return { id };
+}
+/**
+ * Resolves a Collection's selected backend to its full descriptor, for the
+ * `GET .../backend` ("Collection Backend Selected") response, consulting the
+ * Space's backends-available (server `default` plus registered `external`
+ * records). A stored description without a `backend` (created before the property
+ * existed) defaults to the server's default backend.
+ *
+ * @param options {object}
+ * @param options.storage {StorageBackend}   the request's storage backend
+ * @param options.spaceId {string}   the Space whose backends-available is checked
+ * @param options.collectionDescription {CollectionDescription}
+ * @returns {Promise<BackendDescriptor>}
+ */
+export async function resolveBackendDescriptor({ storage, spaceId, collectionDescription }) {
+    const id = collectionDescription.backend?.id ?? DEFAULT_BACKEND_ID;
+    const available = await listRegisteredBackends({ storage, spaceId });
+    const descriptor = available.find(entry => entry.id === id);
+    // A stored backend id should always resolve (it was validated on write); fall
+    // back to the default descriptor defensively rather than returning undefined.
+    return descriptor ?? storage.describe();
+}
+// --- External backend registration (spec "Backends") ---
+//
+// A registered `external` backend is both listed (below) and now *selectable* as
+// a Collection's `backend` (`assertSupportedBackend` / `resolveBackendDescriptor`
+// above consult `listRegisteredBackends`). Routing the selected Collection's data
+// plane to the live provider adapter is the resolver's job
+// (lib/backendRegistry.ts); a selected backend with no registered provider
+// adapter fails closed there.
+/**
+ * Projects a full (secret-bearing) `StoredBackendRecord` down to the sanitized
+ * `BackendDescriptor` that every client-facing read path returns: the public
+ * descriptor fields plus a `connection` reduced to its public subset (no
+ * `authorizationCode` / `refreshToken` / etc.). The single projection shared by
+ * `FileSystemBackend.listBackends` and the register (`POST`/`PUT`) responses, so
+ * the secret material has exactly one place it could leak -- and does not.
+ * @param record {StoredBackendRecord}
+ * @returns {BackendDescriptor}
+ */
+export function sanitizeBackendRecord(record) {
+    const { connection } = record;
+    const publicConnection = {
+        kind: connection.kind,
+        status: connection.status ?? 'registered'
+    };
+    for (const field of PUBLIC_CONNECTION_FIELDS) {
+        const value = connection[field];
+        if (typeof value === 'string') {
+            publicConnection[field] = value;
+        }
+    }
+    return {
+        id: record.id,
+        ...(record.name !== undefined && { name: record.name }),
+        managedBy: record.managedBy,
+        ...(record.storageMode !== undefined && {
+            storageMode: record.storageMode
+        }),
+        ...(record.persistence !== undefined && {
+            persistence: record.persistence
+        }),
+        ...(record.features !== undefined && { features: record.features }),
+        provider: record.provider,
+        connection: publicConnection
+    };
+}
+/**
+ * The backends advertised at `GET /space/:spaceId/backends`: the server's
+ * `default` backend first, followed by the Space's sanitized registered
+ * `external` backends. Also the single source of a Space's selectable backends
+ * for `assertSupportedBackend` / `resolveBackendDescriptor`.
+ * @param options {object}
+ * @param options.storage {StorageBackend}
+ * @param options.spaceId {string}
+ * @returns {Promise<BackendDescriptor[]>}
+ */
+export async function listRegisteredBackends({ storage, spaceId }) {
+    return [storage.describe(), ...(await storage.listBackends({ spaceId }))];
+}
+/**
+ * Validates a backend-registration request body and returns the typed
+ * `BackendRegistration`. Enforces: an object body; a string `id`; a non-empty
+ * string `provider`; `managedBy` absent or `'external'` (a client may not
+ * register a `server` backend); and a `connection` object with a string `kind`.
+ * Throws `InvalidRequestBodyError` (400) with the offending `#/...` pointer.
+ * Does not check `id` URL-safety -- callers run `assertValidBackendId`.
+ * @param body {unknown}   the parsed request body
+ * @param options {object}
+ * @param [options.requestName] {string}   request name for the 400 error title
+ * @returns {BackendRegistration}
+ */
+export function parseBackendRegistration(body, { requestName } = {}) {
+    if (typeof body !== 'object' || body === null) {
+        throw new InvalidRequestBodyError({
+            requestName,
+            detail: 'Backend registration body must be a JSON object.',
+            pointer: '#'
+        });
+    }
+    const candidate = body;
+    if (typeof candidate.id !== 'string') {
+        throw new InvalidRequestBodyError({
+            requestName,
+            detail: 'Backend registration requires a string "id".',
+            pointer: '#/id'
+        });
+    }
+    if (typeof candidate.provider !== 'string' ||
+        candidate.provider.length === 0) {
+        throw new InvalidRequestBodyError({
+            requestName,
+            detail: 'Backend registration requires a non-empty string "provider".',
+            pointer: '#/provider'
+        });
+    }
+    if (candidate.managedBy !== undefined && candidate.managedBy !== 'external') {
+        throw new InvalidRequestBodyError({
+            requestName,
+            detail: 'Backend "managedBy" must be "external"; server backends are not client-registered.',
+            pointer: '#/managedBy'
+        });
+    }
+    const connection = candidate.connection;
+    if (typeof connection !== 'object' ||
+        connection === null ||
+        typeof connection.kind !== 'string') {
+        throw new InvalidRequestBodyError({
+            requestName,
+            detail: 'Backend "connection" must be an object with a string "kind".',
+            pointer: '#/connection'
+        });
+    }
+    return {
+        id: candidate.id,
+        ...(typeof candidate.name === 'string' && { name: candidate.name }),
+        managedBy: 'external',
+        provider: candidate.provider,
+        ...(Array.isArray(candidate.storageMode) && {
+            storageMode: candidate.storageMode
+        }),
+        ...(Array.isArray(candidate.features) && {
+            features: candidate.features
+        }),
+        connection: connection
+    };
+}
+/**
+ * Enforces the optional server-wide registration allowlist (config
+ * `WAS_ENABLED_BACKENDS`): the set of backend `provider` names a client may
+ * register. An `undefined` allowlist is **permissive** -- any provider passes,
+ * preserving the prior behavior where any provider could be registered. When the
+ * allowlist is configured, a `provider` outside it is rejected with
+ * `unsupported-backend` (409) pointing at `#/provider`. This is the fail-fast
+ * registration gate; the resolver's data-plane factory check
+ * (lib/backendRegistry.ts) remains the backstop for a provider with no live
+ * adapter.
+ * @param options {object}
+ * @param options.provider {string}   the registration's `provider`
+ * @param [options.enabledProviders] {string[]}   the configured allowlist, or
+ *   `undefined` for permissive
+ * @returns {void}
+ */
+export function assertProviderAllowed({ provider, enabledProviders }) {
+    if (enabledProviders === undefined) {
+        return;
+    }
+    if (!enabledProviders.includes(provider)) {
+        throw new UnsupportedBackendError({
+            backendId: provider,
+            detail: `Backend provider '${provider}' is not enabled on this server.`,
+            pointer: '#/provider'
+        });
+    }
+}
+/**
+ * Asserts a registered-backend id is a single URL-safe path segment (it becomes
+ * both a URL segment and a `.backend.<id>.json` filename). A backend id is a
+ * body field, so a failure is `invalid-request-body` (400) pointing at `#/id`
+ * rather than a URL-param id error.
+ * @param id {string}
+ * @param options {object}
+ * @param [options.requestName] {string}   request name for the 400 error title
+ * @returns {void}
+ */
+export function assertValidBackendId(id, { requestName } = {}) {
+    if (!isUrlSafeSegment(id)) {
+        throw new InvalidRequestBodyError({
+            requestName,
+            detail: 'Backend "id" must be a single, URL-safe path segment.',
+            pointer: '#/id'
+        });
+    }
+}
+/**
+ * Assembles the full `StoredBackendRecord` to persist from a validated
+ * `BackendRegistration`: the descriptor fields, `managedBy: 'external'`, default
+ * `storageMode` / `features`, and the full (secret-bearing) connection stamped
+ * with `status: 'registered'` and the registration timestamp. The record is
+ * inert until the live provider adapter (future work) connects it.
+ * @param registration {BackendRegistration}
+ * @returns {StoredBackendRecord}
+ */
+export function buildBackendRecord(registration) {
+    const { id, name, provider, storageMode, features, connection } = registration;
+    return {
+        id,
+        ...(name !== undefined && { name }),
+        managedBy: 'external',
+        provider,
+        storageMode: storageMode ?? ['document', 'blob'],
+        features: features ?? [],
+        connection: {
+            ...connection,
+            status: 'registered',
+            connectedAt: new Date().toISOString()
+        }
+    };
+}
+//# sourceMappingURL=backends.js.map

package/dist/lib/backends.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backends.js","sourceRoot":"","sources":["../../src/lib/backends.ts"],"names":[],"mappings":"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"}

package/dist/lib/blindedIndex.d.ts

@@ -0,0 +1,156 @@
+/**
+ * A validated blinded-index query: the HMAC key id naming which blinded index
+ * to search, and exactly one of `equals` / `has`. All names and values are
+ * opaque blinded (base64url) strings.
+ */
+export interface BlindedIndexQuery {
+    index: string;
+    equals?: Array<Record<string, string>>;
+    has?: string[];
+}
+/**
+ * A page of matching documents: the stored JSON bodies verbatim (EDV encrypted
+ * documents pass through untouched), in ascending `resourceId` order.
+ * `cursor` is present if and only if a further page may follow (`hasMore`);
+ * echo it back in the next query body to resume.
+ */
+export interface BlindedIndexQueryPage {
+    documents: unknown[];
+    hasMore: boolean;
+    cursor?: string;
+}
+/**
+ * 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 declare function parseBlindedIndexQueryBody({ body, requestName }: {
+    body: {
+        index?: unknown;
+        equals?: unknown;
+        has?: unknown;
+        count?: unknown;
+        limit?: unknown;
+        cursor?: unknown;
+    };
+    requestName?: string;
+}): {
+    query: BlindedIndexQuery;
+    count: boolean;
+    limit?: number;
+    cursor?: string;
+};
+/**
+ * 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 declare function matchesBlindedIndexQuery({ document, query }: {
+    document: unknown;
+    query: BlindedIndexQuery;
+}): boolean;
+/**
+ * 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 declare function runBlindedIndexQuery({ candidates, query, count, limit, cursor }: {
+    candidates: Array<{
+        resourceId: string;
+        document: unknown;
+    }>;
+    query: BlindedIndexQuery;
+    count?: boolean;
+    limit?: number;
+    cursor?: string;
+}): {
+    count: number;
+} | BlindedIndexQueryPage;
+/**
+ * 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 declare function collectUniqueBlindedTerms({ document }: {
+    document: unknown;
+}): Array<{
+    hmacId: string;
+    name: string;
+    value: string;
+}>;
+/**
+ * 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 declare function assertNoUniqueBlindedConflict({ document, candidates }: {
+    document: unknown;
+    candidates: Array<{
+        resourceId: string;
+        document: unknown;
+    }>;
+}): void;
+//# sourceMappingURL=blindedIndex.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"blindedIndex.d.ts","sourceRoot":"","sources":["../../src/lib/blindedIndex.ts"],"names":[],"mappings":"AAgCA;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;IACtC,GAAG,CAAC,EAAE,MAAM,EAAE,CAAA;CACf;AAED;;;;;GAKG;AACH,MAAM,WAAW,qBAAqB;IACpC,SAAS,EAAE,OAAO,EAAE,CAAA;IACpB,OAAO,EAAE,OAAO,CAAA;IAChB,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAQD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,0BAA0B,CAAC,EACzC,IAAI,EACJ,WAAW,EACZ,EAAE;IACD,IAAI,EAAE;QACJ,KAAK,CAAC,EAAE,OAAO,CAAA;QACf,MAAM,CAAC,EAAE,OAAO,CAAA;QAChB,GAAG,CAAC,EAAE,OAAO,CAAA;QACb,KAAK,CAAC,EAAE,OAAO,CAAA;QACf,KAAK,CAAC,EAAE,OAAO,CAAA;QACf,MAAM,CAAC,EAAE,OAAO,CAAA;KACjB,CAAA;IACD,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB,GAAG;IACF,KAAK,EAAE,iBAAiB,CAAA;IACxB,KAAK,EAAE,OAAO,CAAA;IACd,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB,CAyFA;AAmDD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,wBAAwB,CAAC,EACvC,QAAQ,EACR,KAAK,EACN,EAAE;IACD,QAAQ,EAAE,OAAO,CAAA;IACjB,KAAK,EAAE,iBAAiB,CAAA;CACzB,GAAG,OAAO,CA2BV;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,oBAAoB,CAAC,EACnC,UAAU,EACV,KAAK,EACL,KAAK,EACL,KAAK,EACL,MAAM,EACP,EAAE;IACD,UAAU,EAAE,KAAK,CAAC;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,OAAO,CAAA;KAAE,CAAC,CAAA;IAC5D,KAAK,EAAE,iBAAiB,CAAA;IACxB,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG,qBAAqB,CA0C5C;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,yBAAyB,CAAC,EACxC,QAAQ,EACT,EAAE;IACD,QAAQ,EAAE,OAAO,CAAA;CAClB,GAAG,KAAK,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAqCzD;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,6BAA6B,CAAC,EAC5C,QAAQ,EACR,UAAU,EACX,EAAE;IACD,QAAQ,EAAE,OAAO,CAAA;IACjB,UAAU,EAAE,KAAK,CAAC;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,OAAO,CAAA;KAAE,CAAC,CAAA;CAC7D,GAAG,IAAI,CAkBP"}