@interop/was-client 0.18.0 → 0.19.0

package/dist/sync/plaintextCipher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plaintextCipher.js","sourceRoot":"","sources":["../../src/sync/plaintextCipher.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;GAKG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AAGrC;;;;;;;;;;GAUG;AACH,MAAM,UAAU,wBAAwB,CAAC,EACvC,YAAY,EAGb;IACC,OAAO;QACL,KAAK,CAAC,OAAO,CAAC,EAAE,IAAI,EAAkB;YACpC,OAAO,EAAE,EAAE,EAAE,UAAU,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAA;QACjD,CAAC;QAED,KAAK,CAAC,aAAa;YACjB,MAAM,IAAI,KAAK,CACb,eAAe,YAAY,oCAAoC;gBAC7D,uCAAuC,CAC1C,CAAA;QACH,CAAC;QAED,KAAK,CAAC,OAAO,CAAC,EAAE,QAAQ,EAAsB;YAC5C,OAAO,QAAQ,CAAA;QACjB,CAAC;KACF,CAAA;AACH,CAAC"}

package/dist/sync/port.d.ts

@@ -0,0 +1,78 @@
+/*!
+ * Copyright (c) 2026 Interop Alliance. All rights reserved.
+ */
+/**
+ * `createWasSyncPort`: the {@link WasSyncPort} implementation over a signed
+ * {@link WasClient}, bound to one Space + Collection.
+ *
+ * Writes and single-resource reads ride the raw, signed `was.request()` escape
+ * hatch, which moves the stored body VERBATIM (bypassing the encryption codec).
+ * The change feed already ships opaque stored bodies -- plaintext for a
+ * plaintext collection, the EDV envelope for an encrypted one -- and push must
+ * write those same bytes back unchanged; running them through `resource.put()`
+ * would re-encrypt an already-encrypted envelope. Encrypt/decrypt therefore
+ * stays a read/write-time concern above the port, and the port itself is
+ * collection-agnostic and never touches keys.
+ *
+ * The pull path rides the client's `Collection.changes()` feed, bound to the
+ * same Space + Collection, which produces the byte-identical signed
+ * `POST /space/:s/:c/query` (profile `changes`) as a root invocation and, like
+ * the raw writes, ships the stored bodies verbatim without decrypting.
+ *
+ * Conditional writes ride the server's monotonic content `version` (`ETag`),
+ * enforced uniformly for plaintext and encrypted resources, so there is no
+ * plaintext-vs-encrypted fork. `putContent`/`deleteContent` return the server-
+ * acked `version` (parsed from the write's `ETag`, re-read only if the backend
+ * sent none), so a caller can record acked revisions immediately.
+ */
+import type { WasClient } from '../WasClient.js';
+import type { WasSyncPort } from './types.js';
+/**
+ * The request header the server reads a content write's key-epoch id from,
+ * stamping it onto the Resource's metadata (an absent header clears any prior
+ * stamp). HTTP header names are case-insensitive; the wire form is `WAS-Key-Epoch`.
+ */
+export declare const WAS_KEY_EPOCH_HEADER = "WAS-Key-Epoch";
+/**
+ * Extracts an HTTP status from a raw ky/ezcap error. `was.request()` rejects on
+ * any non-2xx with `err.status` set; this reads it defensively from either the
+ * flat `status` or the nested `response.status` shape.
+ *
+ * @param err {unknown}   the caught error
+ * @returns {number | undefined}
+ */
+export declare function errorStatus(err: unknown): number | undefined;
+/**
+ * Formats a numeric content `version` as the quoted strong `ETag` an
+ * update-if-unchanged write passes as its `ifMatch` precondition (e.g. `3` to
+ * `"3"`). Inverse of {@link parseEtag}.
+ *
+ * @param version {number}
+ * @returns {string}
+ */
+export declare function formatEtag(version: number): string;
+/**
+ * Parses a quoted strong `ETag` (`"3"`) into its numeric revision, or
+ * `undefined` when the header is absent or non-numeric (no such revision yet).
+ *
+ * @param etag {string | null}
+ * @returns {number | undefined}
+ */
+export declare function parseEtag(etag: string | null): number | undefined;
+/**
+ * Builds a {@link WasSyncPort} bound to one Space + Collection, backed by the
+ * caller's signed {@link WasClient}. Requests invoke the client's own root
+ * capability (no delegated `capability` is attached).
+ *
+ * @param options {object}
+ * @param options.was {WasClient}       the session client (holds the signer)
+ * @param options.spaceId {string}      the WAS Space id
+ * @param options.collectionId {string}   the WAS collection id
+ * @returns {WasSyncPort}
+ */
+export declare function createWasSyncPort({ was, spaceId, collectionId }: {
+    was: WasClient;
+    spaceId: string;
+    collectionId: string;
+}): WasSyncPort;
+//# sourceMappingURL=port.d.ts.map

package/dist/sync/port.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"port.d.ts","sourceRoot":"","sources":["../../src/sync/port.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAIhD,OAAO,KAAK,EAIV,WAAW,EAEZ,MAAM,YAAY,CAAA;AAEnB;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,kBAAkB,CAAA;AAWnD;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAK5D;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAElD;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,GAAG,SAAS,CAMjE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,EAChC,GAAG,EACH,OAAO,EACP,YAAY,EACb,EAAE;IACD,GAAG,EAAE,SAAS,CAAA;IACd,OAAO,EAAE,MAAM,CAAA;IACf,YAAY,EAAE,MAAM,CAAA;CACrB,GAAG,WAAW,CA0Jd"}

package/dist/sync/port.js

@@ -0,0 +1,204 @@
+import { writeHeaders } from '../internal/conditional.js';
+import { WasSyncConflictError, WasSyncNotFoundError } from '../errors.js';
+/**
+ * The request header the server reads a content write's key-epoch id from,
+ * stamping it onto the Resource's metadata (an absent header clears any prior
+ * stamp). HTTP header names are case-insensitive; the wire form is `WAS-Key-Epoch`.
+ */
+export const WAS_KEY_EPOCH_HEADER = 'WAS-Key-Epoch';
+/**
+ * The placeholder `updatedAt` for a 412-conflict re-read whose resource has no
+ * `/meta` document yet (its server-managed timestamp is unknown). An epoch-zero
+ * ISO string is a valid, sortable timestamp that sorts before every real one --
+ * unlike an empty string, which is not a parseable date. The change feed remains
+ * the authority on ordering, so this only feeds the one-off conflict entry.
+ */
+const UNKNOWN_UPDATED_AT = new Date(0).toISOString();
+/**
+ * Extracts an HTTP status from a raw ky/ezcap error. `was.request()` rejects on
+ * any non-2xx with `err.status` set; this reads it defensively from either the
+ * flat `status` or the nested `response.status` shape.
+ *
+ * @param err {unknown}   the caught error
+ * @returns {number | undefined}
+ */
+export function errorStatus(err) {
+    return (err.status ??
+        err.response?.status);
+}
+/**
+ * Formats a numeric content `version` as the quoted strong `ETag` an
+ * update-if-unchanged write passes as its `ifMatch` precondition (e.g. `3` to
+ * `"3"`). Inverse of {@link parseEtag}.
+ *
+ * @param version {number}
+ * @returns {string}
+ */
+export function formatEtag(version) {
+    return `"${version}"`;
+}
+/**
+ * Parses a quoted strong `ETag` (`"3"`) into its numeric revision, or
+ * `undefined` when the header is absent or non-numeric (no such revision yet).
+ *
+ * @param etag {string | null}
+ * @returns {number | undefined}
+ */
+export function parseEtag(etag) {
+    if (!etag) {
+        return undefined;
+    }
+    const revision = Number(etag.replace(/"/g, ''));
+    return Number.isFinite(revision) ? revision : undefined;
+}
+/**
+ * Builds a {@link WasSyncPort} bound to one Space + Collection, backed by the
+ * caller's signed {@link WasClient}. Requests invoke the client's own root
+ * capability (no delegated `capability` is attached).
+ *
+ * @param options {object}
+ * @param options.was {WasClient}       the session client (holds the signer)
+ * @param options.spaceId {string}      the WAS Space id
+ * @param options.collectionId {string}   the WAS collection id
+ * @returns {WasSyncPort}
+ */
+export function createWasSyncPort({ was, spaceId, collectionId }) {
+    const collectionPath = `/space/${spaceId}/${collectionId}`;
+    const resourcePath = (id) => `${collectionPath}/${encodeURIComponent(id)}`;
+    // Construction is I/O-free (the codec/feature probes are lazy thunks) and
+    // `changes()` never resolves the codec, so it ships the stored bodies
+    // verbatim -- what this codec-bypassing port requires.
+    const changesCollection = was.space(spaceId).collection(collectionId);
+    /** Re-reads a resource's raw content body + version (no decrypt, no `/meta`). */
+    const readContent = async (id) => {
+        let response;
+        try {
+            response = await was.request({ path: resourcePath(id), method: 'GET' });
+        }
+        catch (err) {
+            if (errorStatus(err) === 404) {
+                return null; // absent or tombstoned -- caller treats as deletion-wins
+            }
+            throw err;
+        }
+        return {
+            version: parseEtag(response.headers.get('etag')) ?? 0,
+            updatedAt: UNKNOWN_UPDATED_AT,
+            deleted: false,
+            data: response.data
+        };
+    };
+    /** Resolves the acked version from a write response, or via a content re-read. */
+    const ackedVersion = async (response, id) => {
+        const version = parseEtag(response.headers.get('etag'));
+        if (version !== undefined) {
+            return version;
+        }
+        return (await readContent(id))?.version ?? 0;
+    };
+    return {
+        async query({ checkpoint, limit }) {
+            const page = await changesCollection.changes({ checkpoint, limit });
+            return {
+                documents: page.documents,
+                checkpoint: page.checkpoint
+            };
+        },
+        async putContent({ id, data, ifMatch, ifNoneMatch, epoch }) {
+            try {
+                const response = await was.request({
+                    path: resourcePath(id),
+                    method: 'PUT',
+                    json: data,
+                    headers: writeHeaders({
+                        precondition: { ifMatch, ifNoneMatch },
+                        epoch
+                    })
+                });
+                return await ackedVersion(response, id);
+            }
+            catch (err) {
+                if (errorStatus(err) === 412) {
+                    throw new WasSyncConflictError();
+                }
+                throw err;
+            }
+        },
+        async deleteContent({ id, ifMatch }) {
+            try {
+                const response = await was.request({
+                    path: resourcePath(id),
+                    method: 'DELETE',
+                    headers: writeHeaders({ precondition: { ifMatch } })
+                });
+                return await ackedVersion(response, id);
+            }
+            catch (err) {
+                const status = errorStatus(err);
+                if (status === 404) {
+                    throw new WasSyncNotFoundError();
+                }
+                if (status === 412) {
+                    throw new WasSyncConflictError();
+                }
+                throw err;
+            }
+        },
+        async putMeta({ id, custom, ifMatch, ifNoneMatch }) {
+            try {
+                await was.request({
+                    path: `${resourcePath(id)}/meta`,
+                    method: 'PUT',
+                    json: { custom },
+                    headers: writeHeaders({ precondition: { ifMatch, ifNoneMatch } })
+                });
+            }
+            catch (err) {
+                if (errorStatus(err) === 412) {
+                    throw new WasSyncConflictError();
+                }
+                throw err;
+            }
+        },
+        async get({ id }) {
+            const master = await readContent(id);
+            if (master === null) {
+                return null;
+            }
+            // Metadata re-read (best-effort): the `/meta` body carries the server-
+            // managed `updatedAt`, the creator DID, the key-epoch id, and the user-
+            // writable `custom`, plus its own `metaVersion` ETag. A resource with no
+            // metadata yet 404s here; only a hard error propagates.
+            try {
+                const metaResponse = await was.request({
+                    path: `${resourcePath(id)}/meta`,
+                    method: 'GET'
+                });
+                const metaBody = metaResponse.data;
+                if (metaBody?.updatedAt) {
+                    master.updatedAt = metaBody.updatedAt;
+                }
+                if (metaBody?.createdBy !== undefined) {
+                    master.createdBy = metaBody.createdBy;
+                }
+                if (metaBody?.epoch !== undefined) {
+                    master.epoch = metaBody.epoch;
+                }
+                if (metaBody?.custom !== undefined) {
+                    master.custom = metaBody.custom;
+                }
+                const metaVersion = parseEtag(metaResponse.headers.get('etag'));
+                if (metaVersion !== undefined) {
+                    master.metaVersion = metaVersion;
+                }
+            }
+            catch (err) {
+                if (errorStatus(err) !== 404) {
+                    throw err;
+                }
+            }
+            return master;
+        }
+    };
+}
+//# sourceMappingURL=port.js.map

package/dist/sync/port.js.map

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

package/dist/sync/provisioning.d.ts

@@ -0,0 +1,41 @@
+/*!
+ * Copyright (c) 2026 Interop Alliance. All rights reserved.
+ */
+/**
+ * Idempotent Space + Collection provisioning for a synced collection. Re-running
+ * is safe: the server upserts the Space and allows a late encryption-marker
+ * declaration, so reconnecting an existing account is a no-op upgrade.
+ */
+import type { WasClient } from '../WasClient.js';
+/**
+ * Ensures the controller's Space exists and one synced collection is configured.
+ * An `'edv'` collection declares the encryption marker `{ scheme: 'edv' }` (so
+ * the server stores only ciphertext it can never decrypt); a `'plaintext'`
+ * collection is configured without one, with `force` so the marker-less upsert
+ * can create a fresh collection (running with the root capability, a 404 from
+ * the pre-merge describe really means absent). A public collection additionally
+ * gets a collection-level world-read grant (`setPublic`), which is what makes a
+ * resource URL in it resolve for anyone. Runs full-tier -- the client invokes
+ * its own root capability.
+ *
+ * @param options {object}
+ * @param options.was {WasClient}
+ * @param options.spaceId {string}
+ * @param options.controllerDid {string}   the Space controller (e.g. `did:key`)
+ * @param options.collectionId {string}    the WAS collection id
+ * @param [options.encryption] {'edv' | 'plaintext'}   defaults to `'edv'`
+ * @param [options.isPublic] {boolean}   grant collection-level world read
+ * @param [options.spaceName] {string}   the Space display name; defaults to
+ *   `'WAS Space'`
+ * @returns {Promise<void>}
+ */
+export declare function ensureSpaceAndCollection({ was, spaceId, controllerDid, collectionId, encryption, isPublic, spaceName }: {
+    was: WasClient;
+    spaceId: string;
+    controllerDid: string;
+    collectionId: string;
+    encryption?: 'edv' | 'plaintext';
+    isPublic?: boolean;
+    spaceName?: string;
+}): Promise<void>;
+//# sourceMappingURL=provisioning.d.ts.map

package/dist/sync/provisioning.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provisioning.d.ts","sourceRoot":"","sources":["../../src/sync/provisioning.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;GAIG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAEhD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,wBAAwB,CAAC,EAC7C,GAAG,EACH,OAAO,EACP,aAAa,EACb,YAAY,EACZ,UAAkB,EAClB,QAAgB,EAChB,SAAuB,EACxB,EAAE;IACD,GAAG,EAAE,SAAS,CAAA;IACd,OAAO,EAAE,MAAM,CAAA;IACf,aAAa,EAAE,MAAM,CAAA;IACrB,YAAY,EAAE,MAAM,CAAA;IACpB,UAAU,CAAC,EAAE,KAAK,GAAG,WAAW,CAAA;IAChC,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,GAAG,OAAO,CAAC,IAAI,CAAC,CA4BhB"}

package/dist/sync/provisioning.js

@@ -0,0 +1,44 @@
+/**
+ * Ensures the controller's Space exists and one synced collection is configured.
+ * An `'edv'` collection declares the encryption marker `{ scheme: 'edv' }` (so
+ * the server stores only ciphertext it can never decrypt); a `'plaintext'`
+ * collection is configured without one, with `force` so the marker-less upsert
+ * can create a fresh collection (running with the root capability, a 404 from
+ * the pre-merge describe really means absent). A public collection additionally
+ * gets a collection-level world-read grant (`setPublic`), which is what makes a
+ * resource URL in it resolve for anyone. Runs full-tier -- the client invokes
+ * its own root capability.
+ *
+ * @param options {object}
+ * @param options.was {WasClient}
+ * @param options.spaceId {string}
+ * @param options.controllerDid {string}   the Space controller (e.g. `did:key`)
+ * @param options.collectionId {string}    the WAS collection id
+ * @param [options.encryption] {'edv' | 'plaintext'}   defaults to `'edv'`
+ * @param [options.isPublic] {boolean}   grant collection-level world read
+ * @param [options.spaceName] {string}   the Space display name; defaults to
+ *   `'WAS Space'`
+ * @returns {Promise<void>}
+ */
+export async function ensureSpaceAndCollection({ was, spaceId, controllerDid, collectionId, encryption = 'edv', isPublic = false, spaceName = 'WAS Space' }) {
+    const space = was.space(spaceId);
+    try {
+        await space.configure({ name: spaceName, controller: controllerDid });
+    }
+    catch (err) {
+        throw new Error(`Failed to configure WAS space "${spaceId}" for "${controllerDid}".`, { cause: err });
+    }
+    try {
+        const collection = space.collection(collectionId);
+        await collection.configure(encryption === 'edv'
+            ? { name: collectionId, encryption: { scheme: 'edv' } }
+            : { name: collectionId, force: true });
+        if (isPublic) {
+            await collection.setPublic();
+        }
+    }
+    catch (err) {
+        throw new Error(`Failed to configure collection "${collectionId}" in space "${spaceId}".`, { cause: err });
+    }
+}
+//# sourceMappingURL=provisioning.js.map

package/dist/sync/provisioning.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provisioning.js","sourceRoot":"","sources":["../../src/sync/provisioning.ts"],"names":[],"mappings":"AAUA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,CAAC,KAAK,UAAU,wBAAwB,CAAC,EAC7C,GAAG,EACH,OAAO,EACP,aAAa,EACb,YAAY,EACZ,UAAU,GAAG,KAAK,EAClB,QAAQ,GAAG,KAAK,EAChB,SAAS,GAAG,WAAW,EASxB;IACC,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,CAAA;IAEhC,IAAI,CAAC;QACH,MAAM,KAAK,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,UAAU,EAAE,aAAa,EAAE,CAAC,CAAA;IACvE,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CACb,kCAAkC,OAAO,UAAU,aAAa,IAAI,EACpE,EAAE,KAAK,EAAE,GAAG,EAAE,CACf,CAAA;IACH,CAAC;IAED,IAAI,CAAC;QACH,MAAM,UAAU,GAAG,KAAK,CAAC,UAAU,CAAC,YAAY,CAAC,CAAA;QACjD,MAAM,UAAU,CAAC,SAAS,CACxB,UAAU,KAAK,KAAK;YAClB,CAAC,CAAC,EAAE,IAAI,EAAE,YAAY,EAAE,UAAU,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE;YACvD,CAAC,CAAC,EAAE,IAAI,EAAE,YAAY,EAAE,KAAK,EAAE,IAAI,EAAE,CACxC,CAAA;QACD,IAAI,QAAQ,EAAE,CAAC;YACb,MAAM,UAAU,CAAC,SAAS,EAAE,CAAA;QAC9B,CAAC;IACH,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CACb,mCAAmC,YAAY,eAAe,OAAO,IAAI,EACzE,EAAE,KAAK,EAAE,GAAG,EAAE,CACf,CAAA;IACH,CAAC;AACH,CAAC"}

package/dist/sync/types.d.ts

@@ -0,0 +1,166 @@
+/*!
+ * Copyright (c) 2026 Interop Alliance. All rights reserved.
+ */
+/**
+ * Wire and port types for cross-replica WAS synchronization.
+ *
+ * The change-feed wire model (`SyncCheckpoint`, `WireDoc`, and one page of the
+ * feed) is the shared WAS data model from `@interop/storage-core`, re-exported
+ * here under replication-facing names so a sync consumer imports one module.
+ * `WasSyncPort` and `MasterState` are the injectable access seam the change
+ * engine depends on, and `DocCipher` is the encrypt/decrypt seam a per-
+ * collection cipher implements.
+ */
+import type { ChangeDocument, ChangesCheckpoint, ChangesPage } from '@interop/storage-core';
+import type { Json } from '../types.js';
+export type { Json };
+/**
+ * The keyset position in the change feed: the `{ id, updatedAt }` of the last
+ * document a pull returned, passed back verbatim to resume strictly after it.
+ * `id` is the total-order tiebreaker within a single `updatedAt`. This is the
+ * shared `ChangesCheckpoint` from `@interop/storage-core` -- server time only,
+ * an opaque position token, never compared against a device clock.
+ */
+export type SyncCheckpoint = ChangesCheckpoint;
+/**
+ * One document as it travels on the `changes` feed wire: `id` is the WAS
+ * resource id, `version` the content revision (the push `If-Match` ETag), and
+ * the stored body is under `data`. A tombstone carries `_deleted: true` with no
+ * `data`. This is the shared `ChangeDocument` from `@interop/storage-core`; on
+ * an encrypted collection `data`/`custom` are the opaque stored envelope, moved
+ * verbatim (decrypt is a projection-time concern the engine's `DocCipher`
+ * handles, never the port).
+ */
+export type WireDoc = ChangeDocument;
+/**
+ * One page of the `changes` feed -- the return shape of {@link WasSyncPort.query}
+ * (the shared `ChangesPage`): the page's `documents` and its resume
+ * `checkpoint`, or `checkpoint: null` for an empty (no-change) page.
+ */
+export type SyncPage = ChangesPage;
+/**
+ * The current master state of a single resource, read back for the 412-conflict
+ * path ({@link WasSyncPort.get}). `deleted` distinguishes a tombstone from a
+ * live resource. `updatedAt`, `metaVersion`, `custom`, `createdBy`, and `epoch`
+ * are populated from the resource's `/meta` document when it exists; a resource
+ * with no metadata yet reports an epoch-zero `updatedAt` placeholder (a valid,
+ * sortable timestamp -- the change feed remains the authority on ordering).
+ */
+export interface MasterState {
+    version: number;
+    updatedAt: string;
+    deleted: boolean;
+    metaVersion?: number;
+    data?: Json;
+    custom?: Json;
+    createdBy?: string;
+    epoch?: string;
+}
+/**
+ * The injected WAS-access seam. `createWasSyncPort` implements this over
+ * `@interop/was-client`'s `was.request()` and the `Collection.changes()` feed;
+ * a change engine depends only on this interface. Every method moves the stored
+ * body verbatim -- no codec, no key handling.
+ *
+ * `putMeta` is optional: a replica that syncs only content (never the user-
+ * writable `/meta` `custom`) may omit it. All other methods are required.
+ */
+export interface WasSyncPort {
+    /**
+     * Pulls one page of the `changes` feed. Omit `checkpoint` for the first page.
+     * Returns the page's `documents` and its resume `checkpoint`, or
+     * `checkpoint: null` for an empty (no-change) page.
+     */
+    query(options: {
+        checkpoint?: SyncCheckpoint;
+        limit: number;
+    }): Promise<{
+        documents: WireDoc[];
+        checkpoint: SyncCheckpoint | null;
+    }>;
+    /**
+     * Conditionally writes the content body verbatim (`PUT /:id`). Pass
+     * `ifNoneMatch: true` for create-if-absent, or `ifMatch` (a quoted ETag over
+     * the content `version`) for update-if-unchanged. `epoch` stamps the opaque
+     * key-epoch id the body was encrypted under (absent clears any prior stamp).
+     * Returns the new server `version` (parsed from the write's `ETag`). Throws
+     * {@link WasSyncConflictError} on `412`.
+     */
+    putContent(options: {
+        id: string;
+        data: Json;
+        ifMatch?: string;
+        ifNoneMatch?: boolean;
+        epoch?: string;
+    }): Promise<number>;
+    /**
+     * Conditionally deletes a resource (writes a tombstone; `DELETE /:id`). Pass
+     * `ifMatch` (a quoted ETag over the content `version`) to delete only if
+     * unchanged. Returns the tombstone's new server `version`. Throws
+     * {@link WasSyncConflictError} on `412`, {@link WasSyncNotFoundError} on `404`
+     * (already gone -- a settled outcome for a delete).
+     */
+    deleteContent(options: {
+        id: string;
+        ifMatch?: string;
+    }): Promise<number>;
+    /**
+     * Conditionally writes the user-writable metadata `custom` (`PUT /:id/meta`).
+     * Optional -- present only on a port that syncs metadata. Throws
+     * {@link WasSyncConflictError} on `412`.
+     */
+    putMeta?(options: {
+        id: string;
+        custom: Json;
+        ifMatch?: string;
+        ifNoneMatch?: boolean;
+    }): Promise<void>;
+    /**
+     * Re-reads a single resource's current master state for the 412-conflict
+     * assembler. Returns `null` when the resource is genuinely absent OR a
+     * tombstone (the server's `GET` returns `404` for both -- indistinguishable,
+     * mapped to deletion-wins by the callers).
+     */
+    get(options: {
+        id: string;
+    }): Promise<MasterState | null>;
+}
+/**
+ * A per-collection document cipher: encrypts a JSON document into its stored
+ * body (minting the resource id) and decrypts a stored body back. Minting the
+ * id once, at write time, is what makes the same document converge on the same
+ * bytes -- and the same content-derived id -- on every replica.
+ *
+ * The members reconcile a plaintext (identity) cipher, a single-recipient EDV
+ * cipher, and a multi-recipient (key-epoch) EDV cipher:
+ *
+ * - `encrypt` may surface the `epoch` id a multi-recipient write encrypted
+ *   under (the marker's `currentEpoch`); absent on a single-key or plaintext
+ *   cipher.
+ * - `encryptUpdate` is optional -- present only for a mutable, random-id
+ *   collection that re-encrypts a head document in place under its existing id
+ *   (advancing the envelope `sequence`). A content-addressed cipher (plaintext
+ *   or `idDerivation: 'content'`) either omits it or throws: a changed document
+ *   is a different id, never an in-place update.
+ */
+export interface DocCipher {
+    encrypt(options: {
+        data: Json;
+    }): Promise<{
+        id: string;
+        envelope: Json;
+        epoch?: string;
+    }>;
+    encryptUpdate?(options: {
+        id: string;
+        data: Json;
+        current: Json;
+    }): Promise<{
+        id: string;
+        envelope: Json;
+    }>;
+    decrypt(options: {
+        envelope: Json;
+    }): Promise<Json>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/sync/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/sync/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;GASG;AACH,OAAO,KAAK,EACV,cAAc,EACd,iBAAiB,EACjB,WAAW,EACZ,MAAM,uBAAuB,CAAA;AAC9B,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,aAAa,CAAA;AAEvC,YAAY,EAAE,IAAI,EAAE,CAAA;AAEpB;;;;;;GAMG;AACH,MAAM,MAAM,cAAc,GAAG,iBAAiB,CAAA;AAE9C;;;;;;;;GAQG;AACH,MAAM,MAAM,OAAO,GAAG,cAAc,CAAA;AAEpC;;;;GAIG;AACH,MAAM,MAAM,QAAQ,GAAG,WAAW,CAAA;AAElC;;;;;;;GAOG;AACH,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAA;IACf,SAAS,EAAE,MAAM,CAAA;IACjB,OAAO,EAAE,OAAO,CAAA;IAChB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,IAAI,CAAC,EAAE,IAAI,CAAA;IACX,MAAM,CAAC,EAAE,IAAI,CAAA;IACb,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,WAAW;IAC1B;;;;OAIG;IACH,KAAK,CAAC,OAAO,EAAE;QAAE,UAAU,CAAC,EAAE,cAAc,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC;QACtE,SAAS,EAAE,OAAO,EAAE,CAAA;QACpB,UAAU,EAAE,cAAc,GAAG,IAAI,CAAA;KAClC,CAAC,CAAA;IAEF;;;;;;;OAOG;IACH,UAAU,CAAC,OAAO,EAAE;QAClB,EAAE,EAAE,MAAM,CAAA;QACV,IAAI,EAAE,IAAI,CAAA;QACV,OAAO,CAAC,EAAE,MAAM,CAAA;QAChB,WAAW,CAAC,EAAE,OAAO,CAAA;QACrB,KAAK,CAAC,EAAE,MAAM,CAAA;KACf,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IAEnB;;;;;;OAMG;IACH,aAAa,CAAC,OAAO,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IAEzE;;;;OAIG;IACH,OAAO,CAAC,CAAC,OAAO,EAAE;QAChB,EAAE,EAAE,MAAM,CAAA;QACV,MAAM,EAAE,IAAI,CAAA;QACZ,OAAO,CAAC,EAAE,MAAM,CAAA;QAChB,WAAW,CAAC,EAAE,OAAO,CAAA;KACtB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAEjB;;;;;OAKG;IACH,GAAG,CAAC,OAAO,EAAE;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAAA;CAC1D;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,SAAS;IACxB,OAAO,CAAC,OAAO,EAAE;QACf,IAAI,EAAE,IAAI,CAAA;KACX,GAAG,OAAO,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,IAAI,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IAC3D,aAAa,CAAC,CAAC,OAAO,EAAE;QACtB,EAAE,EAAE,MAAM,CAAA;QACV,IAAI,EAAE,IAAI,CAAA;QACV,OAAO,EAAE,IAAI,CAAA;KACd,GAAG,OAAO,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,IAAI,CAAA;KAAE,CAAC,CAAA;IAC3C,OAAO,CAAC,OAAO,EAAE;QAAE,QAAQ,EAAE,IAAI,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CACpD"}

package/dist/sync/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/sync/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/sync/types.ts"],"names":[],"mappings":""}

package/dist/types.d.ts

@@ -28,7 +28,7 @@ import type { BackendReference, CollectionEncryption } from '@interop/storage-co
  * The client-writable fields of a Collection Description -- the shape shared
  * by `Collection.configure` and `Collection.replaceDescription` and the single
  * place a new writable field is declared (the body/echo inclusion rule lives
- * in `Collection._writableFields`).
+ * in `Collection.#writableFields`).
  */
 export interface CollectionWritableFields {
     name?: string;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@interop/was-client",
   "description": "A developer-friendly client for Wallet Attached Storage (WAS) servers.",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "type": "module",
   "scripts": {
     "build": "pnpm run clear && tsc",
@@ -35,6 +35,12 @@
       "react-native": "./dist/edv/index.js",
       "import": "./dist/edv/index.js",
       "default": "./dist/edv/index.js"
+    },
+    "./sync": {
+      "types": "./dist/sync/index.d.ts",
+      "react-native": "./dist/sync/index.js",
+      "import": "./dist/sync/index.js",
+      "default": "./dist/sync/index.js"
     }
   },
   "module": "dist/index.js",
@@ -50,7 +56,9 @@
     "@interop/minimal-cipher": "^7.8.0",
     "@interop/storage-core": "^0.3.8",
     "@interop/x25519-key-agreement-key": "^5.2.1",
-    "@scure/base": "^2.2.0"
+    "@noble/hashes": "^2.2.0",
+    "@scure/base": "^2.2.0",
+    "json-canonicalize": "^2.0.0"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",