@interop/was-client 0.52.0 → 0.54.0

package/dist/sync/provisioning.js

@@ -3,6 +3,7 @@
 import { EDV_SCHEME_VERSION } from '../edv/constants.js';
 import { ValidationError, WasError } from '../errors.js';
 import { compareAndSwap } from '../internal/cas.js';
+import { isGovernedDescriptor } from '../internal/describe.js';
 /**
  * The Space display name applied at creation when the caller names none.
  */
@@ -32,10 +33,60 @@ function rethrowProvisioningFailure(err, context) {
     }
     throw new Error(context, { cause: err });
 }
+/**
+ * The read-then-guarded-create both ensures share: the value is read and, when
+ * present, kept as-is; when absent, `create` runs the `If-None-Match: *` write,
+ * and when that fails for ANY reason the value is re-read, and a value now
+ * present is adopted as the winner of a create race instead of failing. The race is detected by the re-read rather than by the
+ * failure's status because the server answers a lost race with whatever check
+ * the rival's description trips first: a 412 from the precondition, but also
+ * a 400 or 409 from the encryption-descriptor transition rules when the rival
+ * already installed key epochs. When nothing can be read back, the create's
+ * own failure is rethrown, so a genuine failure keeps its type.
+ *
+ * A `create` that resolves `undefined` (a server that answered the create with
+ * no body) also falls through to the re-read; that value being unreadable is
+ * the one case reported as its own error.
+ *
+ * @param options {object}
+ * @param options.read {function}   reads the value; `null` when absent
+ * @param options.create {function}   the guarded write; resolves the created
+ *   value, or `undefined` when the server echoed none
+ * @param options.unreadable {string}   the error message when a create
+ *   succeeded but the value cannot be read back
+ * @returns {Promise<{ value: T; created: boolean }>}   the value now present
+ *   and whether this call created it
+ */
+async function readOrCreate({ read, create, unreadable }) {
+    const current = await read();
+    if (current !== null) {
+        return { value: current, created: false };
+    }
+    let created = false;
+    let failure;
+    try {
+        const value = await create();
+        created = true;
+        if (value !== undefined) {
+            return { value, created };
+        }
+    }
+    catch (err) {
+        failure = err;
+    }
+    const latest = await read();
+    if (latest !== null) {
+        return { value: latest, created };
+    }
+    if (created) {
+        throw new ValidationError(unreadable);
+    }
+    throw failure;
+}
 /**
  * Ensures the controller's Space exists and one synced collection is
  * configured, without overwriting anything already there. The Space is
- * described first and configured only when absent -- an existing Space keeps
+ * described first and created only when absent -- an existing Space keeps
  * its name AND its controller, so `controllerDid` is used only at creation
  * (a joined client re-running this never rewrites the description). The
  * collection likewise: when absent, an `'edv'` collection is created with the
@@ -43,16 +94,29 @@ function rethrowProvisioningFailure(err, context) {
  * the server stores only ciphertext it can never decrypt and validates every
  * write against the declared envelope wire format -- the same version the
  * cipher binds into each envelope's AEAD-protected header, so descriptor and
- * envelopes cannot drift; a `'plaintext'` collection is created without one,
- * with `force` so the descriptor-less upsert can create a fresh collection
- * (running full-tier, a 404 from the pre-merge describe really means absent).
- * An existing collection that lacks a descriptor an `'edv'` spec calls for
+ * envelopes cannot drift; a `'plaintext'` or `'governed'` collection is created
+ * without one. Both creates are guarded (`If-None-Match: *`), so two clients
+ * booting at once cannot both create, and the loser adopts the winner's
+ * description instead of failing. Against a server that ignores the
+ * precondition the create is an unconditional upsert, and the loser of a race
+ * can overwrite the winner's display name; the server merges the rest of the
+ * winner's description forward.
+ *
+ * An existing collection that lacks the descriptor an `'edv'` spec calls for
  * gets the late in-place declaration (set-once on the server); one that
  * already carries a descriptor -- possibly with appended key epochs -- is
- * left untouched, epochs and display name included. A public collection gets
- * the collection-level world-read grant (`setPublic`, what makes a resource
- * URL in it resolve for anyone) only when its policy does not already say so.
- * Runs full-tier -- the client invokes its own root authority.
+ * left untouched, epochs and display name included. An existing `'governed'`
+ * collection is never written to: the server refuses to govern a Description
+ * that carries a client-written descriptor (`encryption-immutable`), and a
+ * governed Collection's served `encryption` is the derived member, which a
+ * Description PUT may not carry (`encryption-history-log-governed`). So an
+ * existing collection whose descriptor is client-written (no `history`
+ * member) cannot become governed, and a `'governed'` spec over it throws
+ * `ValidationError` here rather than letting the caller's log create fail
+ * with the server's 409. A public collection gets the collection-level
+ * world-read grant (`setPublic`, what makes a resource URL in it resolve for
+ * anyone) only when its policy does not already say so. Every request invokes
+ * the root capability, or `capability` when the caller holds a delegated one.
  *
  * @param options {object}
  * @param options.was {WasClient}
@@ -60,7 +124,14 @@ function rethrowProvisioningFailure(err, context) {
  * @param options.controllerDid {string}   the Space controller (e.g. `did:key`);
  *   used only when the Space does not exist yet
  * @param options.collectionId {string}    the WAS collection id
- * @param [options.encryption] {'edv' | 'plaintext'}   defaults to `'edv'`
+ * @param [options.encryption] {'edv' | 'plaintext' | 'governed'}   how the
+ *   collection's `encryption` member is settled; defaults to `'edv'`.
+ *   `'edv'` declares the descriptor here, `'plaintext'` declares none, and
+ *   `'governed'` leaves the member to the server, which derives it from the
+ *   collection's history log. Declaring that governance is the caller's next
+ *   step, through the log's guarded create --
+ *   `logGovernedDescriptorStore(...).create` or
+ *   `resourceLogStore({ collection }).create`
  * @param [options.isPublic] {boolean}   grant collection-level world read
  * @param [options.spaceName] {string}   the Space display name, applied only at
  *   Space creation; defaults to `'WAS Space'`
@@ -74,12 +145,16 @@ function rethrowProvisioningFailure(err, context) {
  *   be `spaceId` -- a description of some other Space throws
  *   `ValidationError`, since skipping the ensure would leave that Space
  *   unprovisioned
+ * @param [options.capability] {IZcap}   an invocation capability every
+ *   request rides (a delegated Space-subtree zcap, say); the root capability
+ *   is invoked otherwise. A capability scoped below the bare Space URL cannot
+ *   reach the Space half, so a caller holding one supplies `spaceDescription`
  * @returns {Promise<void>}
  */
-export async function ensureSpaceAndCollection({ was, spaceId, controllerDid, collectionId, encryption = 'edv', isPublic = false, spaceName = DEFAULT_SPACE_NAME, collectionName = collectionId, spaceDescription }) {
-    const space = was.space(spaceId);
+export async function ensureSpaceAndCollection({ was, spaceId, controllerDid, collectionId, encryption = 'edv', isPublic = false, spaceName = DEFAULT_SPACE_NAME, collectionName = collectionId, spaceDescription, capability }) {
+    const space = was.space(spaceId, { capability });
     if (spaceDescription === undefined) {
-        await ensureSpace({ was, spaceId, controllerDid, spaceName });
+        await ensureSpace({ was, spaceId, controllerDid, spaceName, capability });
     }
     else if (spaceDescription.id !== spaceId) {
         // Supplying a description skips the Space half entirely, so a caller
@@ -92,20 +167,25 @@ export async function ensureSpaceAndCollection({ was, spaceId, controllerDid, co
     }
     try {
         const collection = space.collection(collectionId);
-        const read = await collection.describeWithEtag();
-        const current = read?.description ?? null;
-        if (current === null) {
-            // The create deliberately does not thread the `null` just read into
-            // `configure`: neither endpoint honors a create-if-absent precondition
-            // yet, so the re-read inside `configure` is the narrowest window
-            // available against a rival create landing in between (it would lose
-            // its `backend` to a merge from a stale `null`). This branch runs once
-            // per collection, so the extra request is a cold-path cost only.
-            await collection.configure(encryption === 'edv'
+        // A `'governed'` or `'plaintext'` collection takes the descriptor-less
+        // create: a governed `encryption` member is the server's to derive.
+        const { value: read, created } = await readOrCreate({
+            read: () => collection.describeWithEtag(),
+            create: () => collection.replaceDescription(encryption === 'edv'
                 ? { name: collectionName, encryption: EDV_DESCRIPTOR }
-                : { name: collectionName, force: true });
+                : { name: collectionName }, { ifNoneMatch: true }),
+            unreadable: `Collection "${collectionId}" in space "${spaceId}" was ` +
+                'created but cannot be read back.'
+        });
+        const current = read.description;
+        if (encryption === 'governed' &&
+            current.encryption !== undefined &&
+            !isGovernedDescriptor(current.encryption)) {
+            throw new ValidationError(`Collection "${collectionId}" in space "${spaceId}" carries a ` +
+                'client-written encryption descriptor, so it cannot be governed by ' +
+                'a history log: the server keeps a declared descriptor immutable.');
         }
-        else if (encryption === 'edv' && current.encryption === undefined) {
+        if (!created && encryption === 'edv' && current.encryption === undefined) {
             // The late in-place declaration: adding a descriptor to a collection
             // that lacks one is allowed (set-once), while re-sending one over an
             // existing descriptor would drop its appended key epochs -- which is
@@ -144,7 +224,9 @@ export async function ensureSpaceAndCollection({ was, spaceId, controllerDid, co
                     : null
             });
         }
-        if (isPublic && !(await collection.isPublic())) {
+        // A collection this call just created has no policy document yet, so the
+        // read that would find it non-public is skipped.
+        if (isPublic && (created || !(await collection.isPublic()))) {
             await collection.setPublic();
         }
     }
@@ -157,11 +239,13 @@ export async function ensureSpaceAndCollection({ was, spaceId, controllerDid, co
  * there -- the Space half of {@link ensureSpaceAndCollection}, split out so a
  * caller provisioning SEVERAL collections into one Space pays for it once
  * rather than once per collection. An existing Space keeps its name AND its
- * controller, so `controllerDid` is used only at creation.
+ * controller, so `controllerDid` is used only at creation. The create is
+ * guarded (`If-None-Match: *`), so a Space created concurrently keeps its
+ * `type` array (accepted at creation only) and is adopted by the loser.
  *
- * Costs one `GET` on a settled Space, and one `GET` plus one `PUT` on a fresh
- * one: the description read here is threaded into `configure`, which therefore
- * does not re-read it.
+ * Costs one `GET` on a settled Space, and one `GET` plus one guarded `PUT`
+ * (`If-None-Match: *`) on a fresh one; a lost create race costs one more `GET`
+ * to adopt the winner.
  *
  * @param options {object}
  * @param options.was {WasClient}
@@ -170,25 +254,21 @@ export async function ensureSpaceAndCollection({ was, spaceId, controllerDid, co
  *   `did:key`); used only when the Space does not exist yet
  * @param [options.spaceName] {string}   the Space display name, applied only at
  *   Space creation; defaults to `'WAS Space'`
+ * @param [options.capability] {IZcap}   an invocation capability both
+ *   requests ride; the root capability is invoked otherwise
  * @returns {Promise<SpaceDescription>}   the Space's description, existing or
  *   just written -- pass it to {@link ensureSpaceAndCollection} as
  *   `spaceDescription` so each collection skips the Space ensure
  */
-export async function ensureSpace({ was, spaceId, controllerDid, spaceName = DEFAULT_SPACE_NAME }) {
-    const space = was.space(spaceId);
+export async function ensureSpace({ was, spaceId, controllerDid, spaceName = DEFAULT_SPACE_NAME, capability }) {
+    const space = was.space(spaceId, { capability });
     try {
-        const current = await space.describe();
-        if (current !== null) {
-            return current;
-        }
-        // The create does not thread the `null` just read into `configure` (same
-        // reasoning as the collection create in `ensureSpaceAndCollection`): a
-        // Space created concurrently in the window would lose its `type` array,
-        // which the server accepts at creation only. Once per Space, cold path.
-        return await space.configure({
-            name: spaceName,
-            controller: controllerDid
+        const { value } = await readOrCreate({
+            read: () => space.describe(),
+            create: async () => (await space.replaceDescription({ name: spaceName, controller: controllerDid }, { ifNoneMatch: true })).description,
+            unreadable: `Space "${spaceId}" was created but cannot be read back.`
         });
+        return value;
     }
     catch (err) {
         rethrowProvisioningFailure(err, `Failed to configure WAS space "${spaceId}" for "${controllerDid}".`);

package/dist/sync/provisioning.js.map

@@ -1 +1 @@
-{"version":3,"file":"provisioning.js","sourceRoot":"","sources":["../../src/sync/provisioning.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"provisioning.js","sourceRoot":"","sources":["../../src/sync/provisioning.ts"],"names":[],"mappings":"AA8BA,6EAA6E;AAC7E,iEAAiE;AACjE,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAA;AACxD,OAAO,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAA;AACxD,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AACnD,OAAO,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAA;AAE9D;;GAEG;AACH,MAAM,kBAAkB,GAAG,WAAW,CAAA;AAEtC;;;GAGG;AACH,MAAM,cAAc,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,kBAAkB,EAAW,CAAA;AAE9E;;;;;;;;;;;;;GAaG;AACH,SAAS,0BAA0B,CAAC,GAAY,EAAE,OAAe;IAC/D,IAAI,GAAG,YAAY,QAAQ,EAAE,CAAC;QAC5B,MAAM,GAAG,CAAA;IACX,CAAC;IACD,MAAM,IAAI,KAAK,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,CAAA;AAC1C,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,KAAK,UAAU,YAAY,CAAI,EAC7B,IAAI,EACJ,MAAM,EACN,UAAU,EAKX;IACC,MAAM,OAAO,GAAG,MAAM,IAAI,EAAE,CAAA;IAC5B,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;QACrB,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAA;IAC3C,CAAC;IACD,IAAI,OAAO,GAAG,KAAK,CAAA;IACnB,IAAI,OAAgB,CAAA;IACpB,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,MAAM,MAAM,EAAE,CAAA;QAC5B,OAAO,GAAG,IAAI,CAAA;QACd,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,CAAA;QAC3B,CAAC;IACH,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,GAAG,GAAG,CAAA;IACf,CAAC;IACD,MAAM,MAAM,GAAG,MAAM,IAAI,EAAE,CAAA;IAC3B,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;QACpB,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,CAAA;IACnC,CAAC;IACD,IAAI,OAAO,EAAE,CAAC;QACZ,MAAM,IAAI,eAAe,CAAC,UAAU,CAAC,CAAA;IACvC,CAAC;IACD,MAAM,OAAO,CAAA;AACf,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmEG;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,kBAAkB,EAC9B,cAAc,GAAG,YAAY,EAC7B,gBAAgB,EAChB,UAAU,EAYX;IACC,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,OAAO,EAAE,EAAE,UAAU,EAAE,CAAC,CAAA;IAEhD,IAAI,gBAAgB,KAAK,SAAS,EAAE,CAAC;QACnC,MAAM,WAAW,CAAC,EAAE,GAAG,EAAE,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,UAAU,EAAE,CAAC,CAAA;IAC3E,CAAC;SAAM,IAAI,gBAAgB,CAAC,EAAE,KAAK,OAAO,EAAE,CAAC;QAC3C,qEAAqE;QACrE,oEAAoE;QACpE,uEAAuE;QACvE,oEAAoE;QACpE,gCAAgC;QAChC,MAAM,IAAI,eAAe,CACvB,yBAAyB,gBAAgB,CAAC,EAAE,4BAA4B;YACtE,uBAAuB,OAAO,KAAK,CACtC,CAAA;IACH,CAAC;IAED,IAAI,CAAC;QACH,MAAM,UAAU,GAAG,KAAK,CAAC,UAAU,CAAC,YAAY,CAAC,CAAA;QACjD,uEAAuE;QACvE,oEAAoE;QACpE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,MAAM,YAAY,CAAC;YAClD,IAAI,EAAE,GAAG,EAAE,CAAC,UAAU,CAAC,gBAAgB,EAAE;YACzC,MAAM,EAAE,GAAG,EAAE,CACX,UAAU,CAAC,kBAAkB,CAC3B,UAAU,KAAK,KAAK;gBAClB,CAAC,CAAC,EAAE,IAAI,EAAE,cAAc,EAAE,UAAU,EAAE,cAAc,EAAE;gBACtD,CAAC,CAAC,EAAE,IAAI,EAAE,cAAc,EAAE,EAC5B,EAAE,WAAW,EAAE,IAAI,EAAE,CACtB;YACH,UAAU,EACR,eAAe,YAAY,eAAe,OAAO,QAAQ;gBACzD,kCAAkC;SACrC,CAAC,CAAA;QACF,MAAM,OAAO,GAAG,IAAI,CAAC,WAAW,CAAA;QAChC,IACE,UAAU,KAAK,UAAU;YACzB,OAAO,CAAC,UAAU,KAAK,SAAS;YAChC,CAAC,oBAAoB,CAAC,OAAO,CAAC,UAAU,CAAC,EACzC,CAAC;YACD,MAAM,IAAI,eAAe,CACvB,eAAe,YAAY,eAAe,OAAO,cAAc;gBAC7D,oEAAoE;gBACpE,kEAAkE,CACrE,CAAA;QACH,CAAC;QACD,IAAI,CAAC,OAAO,IAAI,UAAU,KAAK,KAAK,IAAI,OAAO,CAAC,UAAU,KAAK,SAAS,EAAE,CAAC;YACzE,qEAAqE;YACrE,qEAAqE;YACrE,qEAAqE;YACrE,oEAAoE;YACpE,oEAAoE;YACpE,qEAAqE;YACrE,6DAA6D;YAC7D,IAAI,QAAQ,GAAuB,IAAI,CAAA;YACvC,MAAM,cAAc,CAAwB;gBAC1C,KAAK,EAAE;oBACL,IAAI,EAAE,KAAK,IAAI,EAAE;wBACf,MAAM,MAAM,GACV,QAAQ,KAAK,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,UAAU,CAAC,gBAAgB,EAAE,CAAA;wBACpE,QAAQ,GAAG,IAAI,CAAA;wBACf,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;4BACpB,MAAM,IAAI,eAAe,CACvB,eAAe,YAAY,eAAe,OAAO,aAAa;gCAC5D,0CAA0C,CAC7C,CAAA;wBACH,CAAC;wBACD,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC,WAAW,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,CAAA;oBACzD,CAAC;oBACD,8DAA8D;oBAC9D,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE;wBACnC,MAAM,UAAU,CAAC,kBAAkB,CACjC;4BACE,IAAI,EAAE,IAAI,CAAC,IAAI;4BACf,OAAO,EAAE,IAAI,CAAC,OAAO;4BACrB,UAAU,EAAE,IAAI,CAAC,UAAU;yBAC5B,EACD,EAAE,OAAO,EAAE,CACZ,CAAA;oBACH,CAAC;iBACF;gBACD,SAAS,EAAE,wBAAwB;gBACnC,MAAM,EAAE,MAAM,CAAC,EAAE,CACf,MAAM,CAAC,UAAU,KAAK,SAAS;oBAC7B,CAAC,CAAC;wBACE,GAAG,MAAM;wBACT,IAAI,EAAE,MAAM,CAAC,IAAI,IAAI,cAAc;wBACnC,UAAU,EAAE,cAAc;qBAC3B;oBACH,CAAC,CAAC,IAAI;aACX,CAAC,CAAA;QACJ,CAAC;QACD,yEAAyE;QACzE,iDAAiD;QACjD,IAAI,QAAQ,IAAI,CAAC,OAAO,IAAI,CAAC,CAAC,MAAM,UAAU,CAAC,QAAQ,EAAE,CAAC,CAAC,EAAE,CAAC;YAC5D,MAAM,UAAU,CAAC,SAAS,EAAE,CAAA;QAC9B,CAAC;IACH,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,0BAA0B,CACxB,GAAG,EACH,mCAAmC,YAAY,eAAe,OAAO,IAAI,CAC1E,CAAA;IACH,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,EAChC,GAAG,EACH,OAAO,EACP,aAAa,EACb,SAAS,GAAG,kBAAkB,EAC9B,UAAU,EAOX;IACC,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,OAAO,EAAE,EAAE,UAAU,EAAE,CAAC,CAAA;IAChD,IAAI,CAAC;QACH,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,YAAY,CAAC;YACnC,IAAI,EAAE,GAAG,EAAE,CAAC,KAAK,CAAC,QAAQ,EAAE;YAC5B,MAAM,EAAE,KAAK,IAAI,EAAE,CACjB,CACE,MAAM,KAAK,CAAC,kBAAkB,CAC5B,EAAE,IAAI,EAAE,SAAS,EAAE,UAAU,EAAE,aAAa,EAAE,EAC9C,EAAE,WAAW,EAAE,IAAI,EAAE,CACtB,CACF,CAAC,WAAW;YACf,UAAU,EAAE,UAAU,OAAO,wCAAwC;SACtE,CAAC,CAAA;QACF,OAAO,KAAK,CAAA;IACd,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,0BAA0B,CACxB,GAAG,EACH,kCAAkC,OAAO,UAAU,aAAa,IAAI,CACrE,CAAA;IACH,CAAC;AACH,CAAC"}

package/dist/sync/types.d.ts

@@ -33,17 +33,25 @@ export type SyncCheckpoint = ChangesCheckpoint;
  * exactly as the server emits them, so a puller passes one back verbatim as a
  * conditional write's `ifMatch` without a {@link WasSyncPort.get} first. 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).
+ * `ChangeDocument` from `@interop/storage-core` with its two bodies typed as
+ * `Json`, the parsed JSON they always are on the wire (the shared type leaves
+ * them `unknown`); 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;
+export interface WireDoc extends Omit<ChangeDocument, 'data' | 'custom'> {
+    data?: Json;
+    custom?: Json;
+}
 /**
  * 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.
+ * WasSyncPort.query} (the shared `ChangesPage`, its documents typed as
+ * {@link WireDoc}): the page's `documents` and its resume `checkpoint`, or
+ * `checkpoint: null` for an empty (no-change) page.
  */
-export type SyncPage = ChangesPage;
+export interface SyncPage extends Omit<ChangesPage, 'documents'> {
+    documents: WireDoc[];
+}
 /**
  * The current master state of a single resource, read back for the 412-conflict
  * path ({@link WasSyncPort.get}). An absent or tombstoned resource surfaces as
@@ -87,10 +95,8 @@ export interface WriteAck {
  * 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.
+ * body verbatim -- no codec, no key handling. Every method is required,
+ * `putMeta` included: a replica that syncs content only simply never calls it.
  */
 export interface WasSyncPort {
     /**
@@ -135,14 +141,17 @@ export interface WasSyncPort {
     }): Promise<WriteAck | undefined>;
     /**
      * Conditionally writes the user-writable metadata `custom` (`PUT /:id/meta`).
-     * Optional -- present only on a port that syncs metadata. The write fully
+     * The write fully
      * replaces `custom`, so omitting it writes the CLEARED state (the server
      * clears every property the body leaves out) -- that is how a metadata clear
      * replicates. Returns the new metadata {@link WriteAck}, or `undefined` when
      * the response carried no `ETag`. Throws {@link WasSyncConflictError} on
-     * `412`.
+     * `412`, and {@link WasSyncNotFoundError} on `404` (the resource is gone: a
+     * delete race the caller corroborates). A port built with
+     * `mapAuthErrors: true` raises {@link WasSyncAuthError} with `status: 404`
+     * there instead, since the masked `404` is ambiguous.
      */
-    putMeta?(options: {
+    putMeta(options: {
         id: string;
         custom?: Json;
         ifMatch?: string;

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

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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@interop/was-client",
   "description": "A developer-friendly client for Wallet Attached Storage (WAS) servers.",
-  "version": "0.52.0",
+  "version": "0.54.0",
   "type": "module",
   "scripts": {
     "build": "pnpm run clear && tsc",
@@ -68,7 +68,7 @@
     "@interop/http-client": "^1.0.5",
     "@interop/minimal-cipher": "^7.10.0",
     "@interop/storage-core": "^0.11.0",
-    "@interop/vh-resource-log": "^0.4.1",
+    "@interop/vh-resource-log": "^0.5.0",
     "@interop/x25519-key-agreement-key": "^5.3.0",
     "@noble/hashes": "^2.3.0",
     "@scure/base": "^2.3.0",