@interop/was-client 0.27.2 → 0.28.0

package/dist/sync/provisioning.d.ts

@@ -2,36 +2,49 @@
  * 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-descriptor
- * declaration, so reconnecting an existing account is a no-op upgrade.
+ * Idempotent, non-clobbering Space + Collection provisioning for a synced
+ * collection. Everything is create-if-absent: an existing Space description,
+ * an existing encryption descriptor (which may carry a key-epoch roster other
+ * clients encrypt under), and an existing access policy are never overwritten,
+ * so ANY controller-tier client -- including one that joined a Space some
+ * other wallet provisioned -- can re-run it to heal a torn provisioning run.
+ * On a fully settled Space it issues only reads.
  */
 import type { WasClient } from '../WasClient.js';
 /**
  * Ensures the controller's Space exists and one synced collection is
- * configured. An `'edv'` collection declares the encryption descriptor `{
- * scheme: 'edv', version: EDV_SCHEME_VERSION }`, so 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 configured without one, with `force` so the
- * descriptor-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.
+ * configured, without overwriting anything already there. The Space is
+ * described first and configured 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
+ * encryption descriptor `{ scheme: 'edv', version: EDV_SCHEME_VERSION }`, so
+ * 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
+ * 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.
  *
  * @param options {object}
  * @param options.was {WasClient}
  * @param options.spaceId {string}
- * @param options.controllerDid {string}   the Space controller (e.g. `did:key`)
+ * @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.isPublic] {boolean}   grant collection-level world read
- * @param [options.spaceName] {string}   the Space display name; defaults to
- *   `'WAS Space'`
- * @param [options.collectionName] {string}   the collection display name;
- *   defaults to the collection id
+ * @param [options.spaceName] {string}   the Space display name, applied only at
+ *   Space creation; defaults to `'WAS Space'`
+ * @param [options.collectionName] {string}   the collection display name,
+ *   applied only at collection creation; defaults to the collection id
  * @returns {Promise<void>}
  */
 export declare function ensureSpaceAndCollection({ was, spaceId, controllerDid, collectionId, encryption, isPublic, spaceName, collectionName }: {

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

@@ -1 +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;AAKhD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAsB,wBAAwB,CAAC,EAC7C,GAAG,EACH,OAAO,EACP,aAAa,EACb,YAAY,EACZ,UAAkB,EAClB,QAAgB,EAChB,SAAuB,EACvB,cAA6B,EAC9B,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;IAClB,cAAc,CAAC,EAAE,MAAM,CAAA;CACxB,GAAG,OAAO,CAAC,IAAI,CAAC,CA+BhB"}
+{"version":3,"file":"provisioning.d.ts","sourceRoot":"","sources":["../../src/sync/provisioning.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAKhD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAsB,wBAAwB,CAAC,EAC7C,GAAG,EACH,OAAO,EACP,aAAa,EACb,YAAY,EACZ,UAAkB,EAClB,QAAgB,EAChB,SAAuB,EACvB,cAA6B,EAC9B,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;IAClB,cAAc,CAAC,EAAE,MAAM,CAAA;CACxB,GAAG,OAAO,CAAC,IAAI,CAAC,CA6ChB"}

package/dist/sync/provisioning.js

@@ -3,48 +3,72 @@
 import { EDV_SCHEME_VERSION } from '../edv/constants.js';
 /**
  * Ensures the controller's Space exists and one synced collection is
- * configured. An `'edv'` collection declares the encryption descriptor `{
- * scheme: 'edv', version: EDV_SCHEME_VERSION }`, so 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 configured without one, with `force` so the
- * descriptor-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.
+ * configured, without overwriting anything already there. The Space is
+ * described first and configured 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
+ * encryption descriptor `{ scheme: 'edv', version: EDV_SCHEME_VERSION }`, so
+ * 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
+ * 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.
  *
  * @param options {object}
  * @param options.was {WasClient}
  * @param options.spaceId {string}
- * @param options.controllerDid {string}   the Space controller (e.g. `did:key`)
+ * @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.isPublic] {boolean}   grant collection-level world read
- * @param [options.spaceName] {string}   the Space display name; defaults to
- *   `'WAS Space'`
- * @param [options.collectionName] {string}   the collection display name;
- *   defaults to the collection id
+ * @param [options.spaceName] {string}   the Space display name, applied only at
+ *   Space creation; defaults to `'WAS Space'`
+ * @param [options.collectionName] {string}   the collection display name,
+ *   applied only at collection creation; defaults to the collection id
  * @returns {Promise<void>}
  */
 export async function ensureSpaceAndCollection({ was, spaceId, controllerDid, collectionId, encryption = 'edv', isPublic = false, spaceName = 'WAS Space', collectionName = collectionId }) {
     const space = was.space(spaceId);
     try {
-        await space.configure({ name: spaceName, controller: controllerDid });
+        if ((await space.describe()) === null) {
+            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: collectionName,
+        const current = await collection.describe();
+        if (current === null) {
+            await collection.configure(encryption === 'edv'
+                ? {
+                    name: collectionName,
+                    encryption: { scheme: 'edv', version: EDV_SCHEME_VERSION }
+                }
+                : { name: collectionName, force: true });
+        }
+        else if (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
+            // exactly why an existing descriptor is never touched.
+            await collection.configure({
+                name: current.name ?? collectionName,
                 encryption: { scheme: 'edv', version: EDV_SCHEME_VERSION }
-            }
-            : { name: collectionName, force: true });
-        if (isPublic) {
+            });
+        }
+        if (isPublic && !(await collection.isPublic())) {
             await collection.setPublic();
         }
     }

package/dist/sync/provisioning.js.map

@@ -1 +1 @@
-{"version":3,"file":"provisioning.js","sourceRoot":"","sources":["../../src/sync/provisioning.ts"],"names":[],"mappings":"AASA,6EAA6E;AAC7E,iEAAiE;AACjE,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAA;AAExD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;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,EACvB,cAAc,GAAG,YAAY,EAU9B;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;gBACE,IAAI,EAAE,cAAc;gBACpB,UAAU,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,kBAAkB,EAAE;aAC3D;YACH,CAAC,CAAC,EAAE,IAAI,EAAE,cAAc,EAAE,KAAK,EAAE,IAAI,EAAE,CAC1C,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"}
+{"version":3,"file":"provisioning.js","sourceRoot":"","sources":["../../src/sync/provisioning.ts"],"names":[],"mappings":"AAaA,6EAA6E;AAC7E,iEAAiE;AACjE,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAA;AAExD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;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,EACvB,cAAc,GAAG,YAAY,EAU9B;IACC,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,CAAA;IAEhC,IAAI,CAAC;QACH,IAAI,CAAC,MAAM,KAAK,CAAC,QAAQ,EAAE,CAAC,KAAK,IAAI,EAAE,CAAC;YACtC,MAAM,KAAK,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,UAAU,EAAE,aAAa,EAAE,CAAC,CAAA;QACvE,CAAC;IACH,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,OAAO,GAAG,MAAM,UAAU,CAAC,QAAQ,EAAE,CAAA;QAC3C,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;YACrB,MAAM,UAAU,CAAC,SAAS,CACxB,UAAU,KAAK,KAAK;gBAClB,CAAC,CAAC;oBACE,IAAI,EAAE,cAAc;oBACpB,UAAU,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,kBAAkB,EAAE;iBAC3D;gBACH,CAAC,CAAC,EAAE,IAAI,EAAE,cAAc,EAAE,KAAK,EAAE,IAAI,EAAE,CAC1C,CAAA;QACH,CAAC;aAAM,IAAI,UAAU,KAAK,KAAK,IAAI,OAAO,CAAC,UAAU,KAAK,SAAS,EAAE,CAAC;YACpE,qEAAqE;YACrE,qEAAqE;YACrE,qEAAqE;YACrE,uDAAuD;YACvD,MAAM,UAAU,CAAC,SAAS,CAAC;gBACzB,IAAI,EAAE,OAAO,CAAC,IAAI,IAAI,cAAc;gBACpC,UAAU,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,kBAAkB,EAAE;aAC3D,CAAC,CAAA;QACJ,CAAC;QACD,IAAI,QAAQ,IAAI,CAAC,CAAC,MAAM,UAAU,CAAC,QAAQ,EAAE,CAAC,EAAE,CAAC;YAC/C,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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@interop/was-client",
   "description": "A developer-friendly client for Wallet Attached Storage (WAS) servers.",
-  "version": "0.27.2",
+  "version": "0.28.0",
   "type": "module",
   "scripts": {
     "build": "pnpm run clear && tsc",