@interop/wallet-core 0.74.0 → 0.76.0

package/dist/clientAnnex/spaceCapability.js

@@ -1,4 +1,5 @@
-import { rootCapabilityId, spacePath, toUrl } from '@interop/was-client/paths';
+import { rootCapabilityId, spaceMeta, spacePath, toUrl } from '@interop/was-client/paths';
+import { KEYRING_COLLECTION, KEYRING_RESOURCE } from '../space/collections.js';
 /**
  * The single-verb Space capability's lifetime: ten minutes, long enough for
  * the request it is minted for and twice `@interop/zcap`'s 300-second clock
@@ -81,10 +82,83 @@ function assertParentAllows({ parent, verb }) {
         `${actions.join(', ')} and not ${verb}; refusing to mint a child that ` +
         'verifies nowhere.');
 }
+/**
+ * Refuses a Resource path segment that is empty or contains `/`. The server
+ * matches a Resource target as three URL-safe segments exactly, so a segment
+ * carrying a `/` would name something else and an empty one names nothing.
+ *
+ * @param options {object}
+ * @param options.label {string}   `collectionId` or `resourceId`, for the
+ *   message
+ * @param options.value {string}
+ * @returns {void}
+ */
+function assertResourceSegment({ label, value }) {
+    if (value.length === 0 || value.includes('/')) {
+        throw new Error(`single-verb Space capability: the resource's "${label}" ` +
+            `("${value}") must be non-empty and contain no "/"; refusing to ` +
+            'mint a child that verifies nowhere.');
+    }
+}
+/**
+ * The stored parent's target, narrowed to what the child's verb (and, on a
+ * `GET`, an optional `resource`) addresses. A `DELETE` names the Space
+ * container, which is the parent's target unchanged; `DELETE` admits no
+ * `resource` narrowing. A bare `GET` names the Space Metadata object one
+ * segment beneath it, since that is where a Space Description is served and
+ * what a storage server's probe predicate keys on. A `GET` given `resource`
+ * names that one Resource beneath the Space instead. All three are taken
+ * from the parent's own bytes rather than rebuilt from a server URL and a
+ * Space id, because this module holds neither and a rebuilt target would
+ * miss a sub-path deployment's prefix.
+ *
+ * Every case requires the parent to target a container URL in canonical
+ * form, carrying its trailing slash, and a parent that does not is refused
+ * here rather than minted from. A storage server's admission predicate
+ * matches the canonical form by exact bytes, so a child built on any other
+ * form of the same Space verifies nowhere: appending onto a sibling path
+ * names nothing, and copying that target verbatim names one no predicate
+ * admits. That refusal comes back as a masked 404, which is indistinguishable
+ * from a Space that is simply gone -- the same failure the expiry and
+ * action-set checks above exist to keep off the wire.
+ *
+ * @param options {object}
+ * @param options.parentTarget {string}
+ * @param options.verb {SpaceCapabilityVerb}
+ * @param [options.resource] {object}   a single Resource beneath the Space,
+ *   admitted only for `GET`
+ * @param options.resource.collectionId {string}
+ * @param options.resource.resourceId {string}
+ * @returns {string}
+ */
+function childTarget({ parentTarget, verb, resource }) {
+    if (resource !== undefined && verb === 'DELETE') {
+        throw new Error('single-verb Space capability: a DELETE child admits no `resource`; ' +
+            'a Resource is not a target the DELETE shape addresses.');
+    }
+    if (!parentTarget.endsWith('/')) {
+        throw new Error('single-verb Space capability: the parent capability targets ' +
+            `"${parentTarget}", which is not a container URL in canonical form; ` +
+            'refusing to mint a child that verifies nowhere.');
+    }
+    if (resource !== undefined) {
+        assertResourceSegment({
+            label: 'collectionId',
+            value: resource.collectionId
+        });
+        assertResourceSegment({ label: 'resourceId', value: resource.resourceId });
+        return `${parentTarget}${resource.collectionId}/${resource.resourceId}`;
+    }
+    return verb === 'GET' ? `${parentTarget}meta` : parentTarget;
+}
 /**
  * Mints a single-verb child of a STORED parent capability -- the three-link
  * shape, used on an unlock Space whose management zcap the account already
- * holds. The child's `invocationTarget` is the parent's unchanged.
+ * holds. The child's `invocationTarget` is {@link childTarget}'s: the
+ * parent's unchanged for the deletion child, the Space Metadata object
+ * beneath it for a bare `GET`, or one Resource beneath the Space for a `GET`
+ * given `resource` -- e.g. a transient session reading an unlock Space's
+ * keyring record under the stored management zcap.
  *
  * @param options {object}
  * @param options.zcapClient {ZcapClient}   the delegating signer (the ladder
@@ -93,13 +167,17 @@ function assertParentAllows({ parent, verb }) {
  * @param options.parent {IZcap}   the stored parent capability
  * @param options.verb {SpaceCapabilityVerb}   the child's one allowed action
  * @param options.controller {string}   the delegatee DID
+ * @param [options.resource] {object}   a single Resource beneath the Space,
+ *   admitted only for `GET`
+ * @param options.resource.collectionId {string}
+ * @param options.resource.resourceId {string}
  * @param [options.ttlMs] {number}   the child's requested lifetime
  * @param [options.now] {number}   the clock the child is minted against
  *   (epoch milliseconds); a caller holding server-relative time passes it
  *   so the proof's `created` and the child's `expires` come off one clock
  * @returns {Promise<IZcap>}
  */
-export async function mintSpaceVerbCapability({ zcapClient, parent, verb, controller, ttlMs = DELETION_ZCAP_TTL_MS, now = Date.now() }) {
+export async function mintSpaceVerbCapability({ zcapClient, parent, verb, controller, resource, ttlMs = DELETION_ZCAP_TTL_MS, now = Date.now() }) {
     const invocationTarget = parent
         .invocationTarget;
     if (invocationTarget === undefined) {
@@ -109,19 +187,43 @@ export async function mintSpaceVerbCapability({ zcapClient, parent, verb, contro
     assertParentAllows({ parent, verb });
     return (await zcapClient.delegate({
         capability: parent,
-        invocationTarget,
+        invocationTarget: childTarget({
+            parentTarget: invocationTarget,
+            verb,
+            resource
+        }),
         controller,
         allowedActions: [verb],
         expires: childExpires({ ttlMs, parent, now }),
         now
     }));
 }
+/**
+ * The target a single-verb Space capability names, by verb. `DELETE`
+ * addresses the Space container itself, which in canonical form carries a
+ * trailing slash; `GET` addresses the Space Metadata object at the Space's
+ * `meta` sub-resource, where the Space Description is served.
+ *
+ * @param options {object}
+ * @param options.storageServerUrl {string}
+ * @param options.spaceId {string}
+ * @param options.verb {SpaceCapabilityVerb}
+ * @returns {string}
+ */
+export function spaceVerbTarget({ storageServerUrl, spaceId, verb }) {
+    const path = verb === 'GET' ? spaceMeta(spaceId) : spacePath(spaceId);
+    return toUrl({ serverUrl: storageServerUrl, path });
+}
 /**
  * Mints a single-verb child of a Space's SYNTHESIZED ROOT -- the two-link
  * shape, used on the account Space and an auxiliary annex Space, where the
- * session holds no stored parent. The child's `invocationTarget` is the bare
- * Space URL, with no trailing slash, so the deletion child covers the Space
- * itself rather than its items subtree.
+ * session holds no stored parent. The chain roots in the Space's own root
+ * capability, and the child's `invocationTarget` is
+ * {@link spaceVerbTarget}'s: the canonical Space URL for the deletion child,
+ * the Space Metadata object for the probe child. The probe therefore narrows
+ * its root's target rather than restating it, and neither child can be read
+ * as the broad subtree grant the Space URL would otherwise be, because its
+ * action set is one verb.
  *
  * @param options {object}
  * @param options.zcapClient {ZcapClient}   the delegating signer
@@ -142,11 +244,47 @@ export async function mintSpaceRootVerbCapability({ zcapClient, storageServerUrl
     });
     return (await zcapClient.delegate({
         capability: rootCapabilityId(spaceUrl),
-        invocationTarget: spaceUrl,
+        invocationTarget: spaceVerbTarget({ storageServerUrl, spaceId, verb }),
         controller,
         allowedActions: [verb],
         expires: childExpires({ ttlMs, now }),
         now
     }));
 }
+/**
+ * Mints the GET-only child that reads an unlock Space's keyring record, over
+ * the stored management zcap the account holds for that Space -- what a
+ * wallet does when it reads a SIBLING unlock credential's record, having no
+ * root invocation over the Space.
+ *
+ * It exists so the capability's target and the URL `getUnlockKeyring`
+ * addresses come from the same two constants, `KEYRING_COLLECTION.id` and
+ * `KEYRING_RESOURCE`. The child then matches the request by construction,
+ * rather than by a caller restating the record's placement beside the read
+ * and having to agree with it. Both wallets run this read.
+ *
+ * @param options {object}
+ * @param options.zcapClient {ZcapClient}   the delegating signer
+ * @param options.parent {IZcap}   the stored management zcap for the unlock
+ *   Space
+ * @param options.controller {string}   the delegatee DID
+ * @param [options.ttlMs] {number}   the child's requested lifetime
+ * @param [options.now] {number}   the clock the child is minted against
+ *   (epoch milliseconds)
+ * @returns {Promise<IZcap>}
+ */
+export async function mintUnlockKeyringReadCapability({ zcapClient, parent, controller, ttlMs = DELETION_ZCAP_TTL_MS, now = Date.now() }) {
+    return mintSpaceVerbCapability({
+        zcapClient,
+        parent,
+        verb: 'GET',
+        controller,
+        resource: {
+            collectionId: KEYRING_COLLECTION.id,
+            resourceId: KEYRING_RESOURCE
+        },
+        ttlMs,
+        now
+    });
+}
 //# sourceMappingURL=spaceCapability.js.map

package/dist/clientAnnex/spaceCapability.js.map

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

package/dist/keyring/fetch.d.ts

@@ -10,6 +10,7 @@
  * wrap around this rather than living inside it, because those are per-app
  * storage concerns with per-app durability rules.
  */
+import type { ServiceDescription } from '@interop/was-client';
 import type { UnlockKdf } from './kdf.js';
 import type { KeyringRecordContents } from './record.js';
 /**
@@ -27,12 +28,16 @@ import type { KeyringRecordContents } from './record.js';
  *   (`KEYRING_KDF` for a passphrase) and a method that omits it fails to
  *   compile instead of silently reading the passphrase-salted unlock Space.
  * @param options.storageServerUrl {string}   the WAS server origin
+ * @param [options.serviceDescription] {ServiceDescription}   the server's
+ *   service description a client the caller already holds discovered
+ *   (`(await was.service()).description`), so this one skips discovery
  * @returns {Promise<(KeyringRecordContents & { unlockSpaceId: string }) | null>}
  */
-export declare function fetchKeyringRecord({ secret, kdf, storageServerUrl }: {
+export declare function fetchKeyringRecord({ secret, kdf, storageServerUrl, serviceDescription }: {
     secret: string | Uint8Array;
     kdf: UnlockKdf;
     storageServerUrl: string;
+    serviceDescription?: ServiceDescription;
 }): Promise<(KeyringRecordContents & {
     unlockSpaceId: string;
 }) | null>;

package/dist/keyring/fetch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fetch.d.ts","sourceRoot":"","sources":["../../src/keyring/fetch.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAA;AAIzC,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAA;AAExD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,kBAAkB,CAAC,EACvC,MAAM,EACN,GAAG,EACH,gBAAgB,EACjB,EAAE;IACD,MAAM,EAAE,MAAM,GAAG,UAAU,CAAA;IAC3B,GAAG,EAAE,SAAS,CAAA;IACd,gBAAgB,EAAE,MAAM,CAAA;CACzB,GAAG,OAAO,CAAC,CAAC,qBAAqB,GAAG;IAAE,aAAa,EAAE,MAAM,CAAA;CAAE,CAAC,GAAG,IAAI,CAAC,CAoBtE"}
+{"version":3,"file":"fetch.d.ts","sourceRoot":"","sources":["../../src/keyring/fetch.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAA;AAC7D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAA;AAIzC,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAA;AAExD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,kBAAkB,CAAC,EACvC,MAAM,EACN,GAAG,EACH,gBAAgB,EAChB,kBAAkB,EACnB,EAAE;IACD,MAAM,EAAE,MAAM,GAAG,UAAU,CAAA;IAC3B,GAAG,EAAE,SAAS,CAAA;IACd,gBAAgB,EAAE,MAAM,CAAA;IACxB,kBAAkB,CAAC,EAAE,kBAAkB,CAAA;CACxC,GAAG,OAAO,CAAC,CAAC,qBAAqB,GAAG;IAAE,aAAa,EAAE,MAAM,CAAA;CAAE,CAAC,GAAG,IAAI,CAAC,CAqBtE"}

package/dist/keyring/fetch.js

@@ -16,13 +16,17 @@ import { unwrapKeyringRecord } from './record.js';
  *   (`KEYRING_KDF` for a passphrase) and a method that omits it fails to
  *   compile instead of silently reading the passphrase-salted unlock Space.
  * @param options.storageServerUrl {string}   the WAS server origin
+ * @param [options.serviceDescription] {ServiceDescription}   the server's
+ *   service description a client the caller already holds discovered
+ *   (`(await was.service()).description`), so this one skips discovery
  * @returns {Promise<(KeyringRecordContents & { unlockSpaceId: string }) | null>}
  */
-export async function fetchKeyringRecord({ secret, kdf, storageServerUrl }) {
+export async function fetchKeyringRecord({ secret, kdf, storageServerUrl, serviceDescription }) {
     const unlock = await deriveUnlockIdentity({ secret, kdf });
     const record = await getUnlockKeyring({
         storageServerUrl,
         zcapClient: unlock.zcapClient,
+        serviceDescription,
         spaceId: unlock.spaceId
     });
     if (record === null) {

package/dist/keyring/fetch.js.map

@@ -1 +1 @@
-{"version":3,"file":"fetch.js","sourceRoot":"","sources":["../../src/keyring/fetch.ts"],"names":[],"mappings":"AAaA,OAAO,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAA;AAC/C,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAA;AACnD,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAA;AAGjD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,EACvC,MAAM,EACN,GAAG,EACH,gBAAgB,EAKjB;IACC,MAAM,MAAM,GAAG,MAAM,oBAAoB,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,CAAA;IAC1D,MAAM,MAAM,GAAG,MAAM,gBAAgB,CAAC;QACpC,gBAAgB;QAChB,UAAU,EAAE,MAAM,CAAC,UAAU;QAC7B,OAAO,EAAE,MAAM,CAAC,OAAO;KACxB,CAAC,CAAA;IACF,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;QACpB,OAAO,IAAI,CAAA;IACb,CAAC;IACD,MAAM,QAAQ,GAAG,MAAM,mBAAmB,CAAC;QACzC,MAAM;QACN,eAAe,EAAE,MAAM,CAAC,eAAe;QACvC,WAAW,EAAE,MAAM,CAAC,WAAW;QAC/B,qEAAqE;QACrE,uEAAuE;QACvE,iEAAiE;QACjE,oBAAoB,EAAE,MAAM,CAAC,YAAY,CAAC,YAAY;KACvD,CAAC,CAAA;IACF,OAAO,EAAE,GAAG,QAAQ,EAAE,aAAa,EAAE,MAAM,CAAC,OAAO,EAAE,CAAA;AACvD,CAAC"}
+{"version":3,"file":"fetch.js","sourceRoot":"","sources":["../../src/keyring/fetch.ts"],"names":[],"mappings":"AAcA,OAAO,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAA;AAC/C,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAA;AACnD,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAA;AAGjD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,EACvC,MAAM,EACN,GAAG,EACH,gBAAgB,EAChB,kBAAkB,EAMnB;IACC,MAAM,MAAM,GAAG,MAAM,oBAAoB,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,CAAA;IAC1D,MAAM,MAAM,GAAG,MAAM,gBAAgB,CAAC;QACpC,gBAAgB;QAChB,UAAU,EAAE,MAAM,CAAC,UAAU;QAC7B,kBAAkB;QAClB,OAAO,EAAE,MAAM,CAAC,OAAO;KACxB,CAAC,CAAA;IACF,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;QACpB,OAAO,IAAI,CAAA;IACb,CAAC;IACD,MAAM,QAAQ,GAAG,MAAM,mBAAmB,CAAC;QACzC,MAAM;QACN,eAAe,EAAE,MAAM,CAAC,eAAe;QACvC,WAAW,EAAE,MAAM,CAAC,WAAW;QAC/B,qEAAqE;QACrE,uEAAuE;QACvE,iEAAiE;QACjE,oBAAoB,EAAE,MAAM,CAAC,YAAY,CAAC,YAAY;KACvD,CAAC,CAAA;IACF,OAAO,EAAE,GAAG,QAAQ,EAAE,aAAa,EAAE,MAAM,CAAC,OAAO,EAAE,CAAA;AACvD,CAAC"}

package/dist/keyring/unlockSpace.d.ts

@@ -1,3 +1,27 @@
+/*!
+ * Copyright (c) 2026 Interop Alliance. All rights reserved.
+ */
+/**
+ * The unlock Space: a minimal second Space, controlled by an unlock identity
+ * and separate from the wallet data Space, holding the one keyring record.
+ * These are standalone functions rather than methods on a wallet's remote-store
+ * class (that store is bound to the data identity): each builds its own
+ * `WasClient` over the caller's `zcapClient`. By default that is the unlock
+ * agent's, whose invocation signer is the unlock root key (root invocation,
+ * no capability attached -- the same invocation shape the data Space uses).
+ * Each read/write/delete also takes an optional `capability`: an enrolled
+ * client's `zcapClient` then invokes the management zcap the unlock identity
+ * delegated at bind time, which is how a ceremony reaches an unlock Space
+ * without holding its secret (the revocation cascade's re-mint reading and
+ * re-PUTting a recovery code's standing record, or a lost unlock method's
+ * Space being retired).
+ *
+ * The one resource is a plaintext JSON document (its keyring payload is
+ * already ciphertext), so no encryption provider is wired in and every
+ * read/write handle is built by {@link plaintextCollection} -- load-bearing
+ * here for the absent Space a fresh unlock secret's keyring lookup meets.
+ */
+import { type ServiceDescription } from '@interop/was-client';
 import type { IZcap } from '@interop/data-integrity-core';
 import type { ZcapClient } from '@interop/ezcap';
 /**
@@ -15,14 +39,18 @@ export declare const UNLOCK_SPACE_NAME = "Freewallet Keyring";
  * @param options {object}
  * @param options.storageServerUrl {string}
  * @param options.zcapClient {ZcapClient}
+ * @param [options.serviceDescription] {ServiceDescription}   the server's
+ *   service description a client the caller already holds discovered
+ *   (`(await was.service()).description`), so this one skips discovery
  * @param options.spaceId {string}   the unlock Space id
  * @param options.controller {string}   the unlock did:key
  * @param [options.name] {string}   the Space Description name
  * @returns {Promise<void>}
  */
-export declare function ensureUnlockSpace({ storageServerUrl, zcapClient, spaceId, controller, name }: {
+export declare function ensureUnlockSpace({ storageServerUrl, zcapClient, serviceDescription, spaceId, controller, name }: {
     storageServerUrl: string;
     zcapClient: ZcapClient;
+    serviceDescription?: ServiceDescription;
     spaceId: string;
     controller: string;
     name?: string;
@@ -43,14 +71,18 @@ export declare function ensureUnlockSpace({ storageServerUrl, zcapClient, spaceI
  * @param options {object}
  * @param options.storageServerUrl {string}
  * @param options.zcapClient {ZcapClient}
+ * @param [options.serviceDescription] {ServiceDescription}   the server's
+ *   service description a client the caller already holds discovered
+ *   (`(await was.service()).description`), so this one skips discovery
  * @param options.spaceId {string}   the unlock Space id
  * @param [options.capability] {IZcap}   the delegated management zcap;
  *   absent, the read is a root invocation
  * @returns {Promise<unknown | null>}
  */
-export declare function getUnlockKeyring({ storageServerUrl, zcapClient, spaceId, capability }: {
+export declare function getUnlockKeyring({ storageServerUrl, zcapClient, serviceDescription, spaceId, capability }: {
     storageServerUrl: string;
     zcapClient: ZcapClient;
+    serviceDescription?: ServiceDescription;
     spaceId: string;
     capability?: IZcap;
 }): Promise<unknown | null>;
@@ -68,15 +100,19 @@ export declare function getUnlockKeyring({ storageServerUrl, zcapClient, spaceId
  * @param options {object}
  * @param options.storageServerUrl {string}
  * @param options.zcapClient {ZcapClient}
+ * @param [options.serviceDescription] {ServiceDescription}   the server's
+ *   service description a client the caller already holds discovered
+ *   (`(await was.service()).description`), so this one skips discovery
  * @param options.spaceId {string}   the unlock Space id
  * @param options.record {object}   the keyring record
  * @param [options.capability] {IZcap}   the delegated management zcap;
  *   absent, the write is a root invocation
  * @returns {Promise<void>}
  */
-export declare function putUnlockKeyring({ storageServerUrl, zcapClient, spaceId, record, capability }: {
+export declare function putUnlockKeyring({ storageServerUrl, zcapClient, serviceDescription, spaceId, record, capability }: {
     storageServerUrl: string;
     zcapClient: ZcapClient;
+    serviceDescription?: ServiceDescription;
     spaceId: string;
     record: object;
     capability?: IZcap;
@@ -99,6 +135,9 @@ export declare function putUnlockKeyring({ storageServerUrl, zcapClient, spaceId
  * @param options {object}
  * @param options.storageServerUrl {string}
  * @param options.zcapClient {ZcapClient}
+ * @param [options.serviceDescription] {ServiceDescription}   the server's
+ *   service description a client the caller already holds discovered
+ *   (`(await was.service()).description`), so this one skips discovery
  * @param options.spaceId {string}   the unlock Space id
  * @param [options.capability] {IZcap}   the delegated management zcap;
  *   absent, the delete is a root invocation
@@ -106,9 +145,10 @@ export declare function putUnlockKeyring({ storageServerUrl, zcapClient, spaceId
  *   when the server answered 404 (absent, or unauthorized under a
  *   capability); every other error propagates unchanged
  */
-export declare function deleteUnlockSpace({ storageServerUrl, zcapClient, spaceId, capability }: {
+export declare function deleteUnlockSpace({ storageServerUrl, zcapClient, serviceDescription, spaceId, capability }: {
     storageServerUrl: string;
     zcapClient: ZcapClient;
+    serviceDescription?: ServiceDescription;
     spaceId: string;
     capability?: IZcap;
 }): Promise<{

package/dist/keyring/unlockSpace.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"unlockSpace.d.ts","sourceRoot":"","sources":["../../src/keyring/unlockSpace.ts"],"names":[],"mappings":"AAwBA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,8BAA8B,CAAA;AACzD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AAIhD;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,uBAAuB,CAAA;AA6IrD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,iBAAiB,CAAC,EACtC,gBAAgB,EAChB,UAAU,EACV,OAAO,EACP,UAAU,EACV,IAAwB,EACzB,EAAE;IACD,gBAAgB,EAAE,MAAM,CAAA;IACxB,UAAU,EAAE,UAAU,CAAA;IACtB,OAAO,EAAE,MAAM,CAAA;IACf,UAAU,EAAE,MAAM,CAAA;IAClB,IAAI,CAAC,EAAE,MAAM,CAAA;CACd,GAAG,OAAO,CAAC,IAAI,CAAC,CAUhB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,gBAAgB,CAAC,EACrC,gBAAgB,EAChB,UAAU,EACV,OAAO,EACP,UAAU,EACX,EAAE;IACD,gBAAgB,EAAE,MAAM,CAAA;IACxB,UAAU,EAAE,UAAU,CAAA;IACtB,OAAO,EAAE,MAAM,CAAA;IACf,UAAU,CAAC,EAAE,KAAK,CAAA;CACnB,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAS1B;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,gBAAgB,CAAC,EACrC,gBAAgB,EAChB,UAAU,EACV,OAAO,EACP,MAAM,EACN,UAAU,EACX,EAAE;IACD,gBAAgB,EAAE,MAAM,CAAA;IACxB,UAAU,EAAE,UAAU,CAAA;IACtB,OAAO,EAAE,MAAM,CAAA;IACf,MAAM,EAAE,MAAM,CAAA;IACd,UAAU,CAAC,EAAE,KAAK,CAAA;CACnB,GAAG,OAAO,CAAC,IAAI,CAAC,CAUhB;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAsB,iBAAiB,CAAC,EACtC,gBAAgB,EAChB,UAAU,EACV,OAAO,EACP,UAAU,EACX,EAAE;IACD,gBAAgB,EAAE,MAAM,CAAA;IACxB,UAAU,EAAE,UAAU,CAAA;IACtB,OAAO,EAAE,MAAM,CAAA;IACf,UAAU,CAAC,EAAE,KAAK,CAAA;CACnB,GAAG,OAAO,CAAC;IAAE,OAAO,EAAE,SAAS,GAAG,WAAW,CAAA;CAAE,CAAC,CAGhD"}
+{"version":3,"file":"unlockSpace.d.ts","sourceRoot":"","sources":["../../src/keyring/unlockSpace.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,EAAa,KAAK,kBAAkB,EAAE,MAAM,qBAAqB,CAAA;AACxE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,8BAA8B,CAAA;AACzD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AAIhD;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,uBAAuB,CAAA;AAwIrD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,iBAAiB,CAAC,EACtC,gBAAgB,EAChB,UAAU,EACV,kBAAkB,EAClB,OAAO,EACP,UAAU,EACV,IAAwB,EACzB,EAAE;IACD,gBAAgB,EAAE,MAAM,CAAA;IACxB,UAAU,EAAE,UAAU,CAAA;IACtB,kBAAkB,CAAC,EAAE,kBAAkB,CAAA;IACvC,OAAO,EAAE,MAAM,CAAA;IACf,UAAU,EAAE,MAAM,CAAA;IAClB,IAAI,CAAC,EAAE,MAAM,CAAA;CACd,GAAG,OAAO,CAAC,IAAI,CAAC,CAahB;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,gBAAgB,CAAC,EACrC,gBAAgB,EAChB,UAAU,EACV,kBAAkB,EAClB,OAAO,EACP,UAAU,EACX,EAAE;IACD,gBAAgB,EAAE,MAAM,CAAA;IACxB,UAAU,EAAE,UAAU,CAAA;IACtB,kBAAkB,CAAC,EAAE,kBAAkB,CAAA;IACvC,OAAO,EAAE,MAAM,CAAA;IACf,UAAU,CAAC,EAAE,KAAK,CAAA;CACnB,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAY1B;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,gBAAgB,CAAC,EACrC,gBAAgB,EAChB,UAAU,EACV,kBAAkB,EAClB,OAAO,EACP,MAAM,EACN,UAAU,EACX,EAAE;IACD,gBAAgB,EAAE,MAAM,CAAA;IACxB,UAAU,EAAE,UAAU,CAAA;IACtB,kBAAkB,CAAC,EAAE,kBAAkB,CAAA;IACvC,OAAO,EAAE,MAAM,CAAA;IACf,MAAM,EAAE,MAAM,CAAA;IACd,UAAU,CAAC,EAAE,KAAK,CAAA;CACnB,GAAG,OAAO,CAAC,IAAI,CAAC,CAahB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAsB,iBAAiB,CAAC,EACtC,gBAAgB,EAChB,UAAU,EACV,kBAAkB,EAClB,OAAO,EACP,UAAU,EACX,EAAE;IACD,gBAAgB,EAAE,MAAM,CAAA;IACxB,UAAU,EAAE,UAAU,CAAA;IACtB,kBAAkB,CAAC,EAAE,kBAAkB,CAAA;IACvC,OAAO,EAAE,MAAM,CAAA;IACf,UAAU,CAAC,EAAE,KAAK,CAAA;CACnB,GAAG,OAAO,CAAC;IAAE,OAAO,EAAE,SAAS,GAAG,WAAW,CAAA;CAAE,CAAC,CAOhD"}

package/dist/keyring/unlockSpace.js

@@ -32,17 +32,22 @@ import { plaintextCollection } from '../space/plaintextCollection.js';
 export const UNLOCK_SPACE_NAME = 'Freewallet Keyring';
 /**
  * The bare WAS client for an unlock Space (see the module doc for why it wires
- * in no encryption provider).
+ * in no encryption provider). Each exported function builds one and hands it
+ * to the helpers it composes, so a call discovers the service at most once.
  *
  * @param options {object}
  * @param options.storageServerUrl {string}
  * @param options.zcapClient {ZcapClient}   built on the unlock agent's signer
+ * @param [options.serviceDescription] {ServiceDescription}   the server's
+ *   service description a client the caller already holds discovered
+ *   (`(await was.service()).description`), so this one skips discovery
  * @returns {WasClient}
  */
-function unlockSpaceClient({ storageServerUrl, zcapClient }) {
+function unlockSpaceClient({ storageServerUrl, zcapClient, serviceDescription }) {
     return new WasClient({
         serverUrl: storageServerUrl,
-        zcapClient
+        zcapClient,
+        serviceDescription
     });
 }
 /**
@@ -52,15 +57,13 @@ function unlockSpaceClient({ storageServerUrl, zcapClient }) {
  * unreadable.
  *
  * @param options {object}
- * @param options.storageServerUrl {string}
- * @param options.zcapClient {ZcapClient}
+ * @param options.was {WasClient}   the unlock Space client
  * @param options.spaceId {string}
  * @param options.collectionId {string}
  * @param options.name {string}
  * @returns {Promise<void>}
  */
-async function ensurePlaintextCollection({ storageServerUrl, zcapClient, spaceId, collectionId, name }) {
-    const was = unlockSpaceClient({ storageServerUrl, zcapClient });
+async function ensurePlaintextCollection({ was, spaceId, collectionId, name }) {
     await was
         .space(spaceId)
         .collection(collectionId)
@@ -74,8 +77,7 @@ async function ensurePlaintextCollection({ storageServerUrl, zcapClient, spaceId
  * The explicit `plaintext` override is load-bearing (see the module doc).
  *
  * @param options {object}
- * @param options.storageServerUrl {string}
- * @param options.zcapClient {ZcapClient}
+ * @param options.was {WasClient}   the unlock Space client
  * @param options.spaceId {string}
  * @param options.collectionId {string}
  * @param options.resourceId {string}
@@ -83,8 +85,7 @@ async function ensurePlaintextCollection({ storageServerUrl, zcapClient, spaceId
  *   rides; absent, the request invokes the root capability
  * @returns {Promise<unknown | null>}
  */
-async function getPlaintextRecord({ storageServerUrl, zcapClient, spaceId, collectionId, resourceId, capability }) {
-    const was = unlockSpaceClient({ storageServerUrl, zcapClient });
+async function getPlaintextRecord({ was, spaceId, collectionId, resourceId, capability }) {
     const result = await plaintextCollection({
         was,
         spaceId,
@@ -100,8 +101,7 @@ async function getPlaintextRecord({ storageServerUrl, zcapClient, spaceId, colle
  * Serialized to bytes with an explicit `application/json` content-type.
  *
  * @param options {object}
- * @param options.storageServerUrl {string}
- * @param options.zcapClient {ZcapClient}
+ * @param options.was {WasClient}   the unlock Space client
  * @param options.spaceId {string}
  * @param options.collectionId {string}
  * @param options.resourceId {string}
@@ -110,8 +110,7 @@ async function getPlaintextRecord({ storageServerUrl, zcapClient, spaceId, colle
  *   rides; absent, the request invokes the root capability
  * @returns {Promise<void>}
  */
-async function putPlaintextRecord({ storageServerUrl, zcapClient, spaceId, collectionId, resourceId, record, capability }) {
-    const was = unlockSpaceClient({ storageServerUrl, zcapClient });
+async function putPlaintextRecord({ was, spaceId, collectionId, resourceId, record, capability }) {
     const body = new TextEncoder().encode(JSON.stringify(record));
     await plaintextCollection({ was, spaceId, collectionId, capability })
         .resource(resourceId)
@@ -126,17 +125,23 @@ async function putPlaintextRecord({ storageServerUrl, zcapClient, spaceId, colle
  * @param options {object}
  * @param options.storageServerUrl {string}
  * @param options.zcapClient {ZcapClient}
+ * @param [options.serviceDescription] {ServiceDescription}   the server's
+ *   service description a client the caller already holds discovered
+ *   (`(await was.service()).description`), so this one skips discovery
  * @param options.spaceId {string}   the unlock Space id
  * @param options.controller {string}   the unlock did:key
  * @param [options.name] {string}   the Space Description name
  * @returns {Promise<void>}
  */
-export async function ensureUnlockSpace({ storageServerUrl, zcapClient, spaceId, controller, name = UNLOCK_SPACE_NAME }) {
-    const was = unlockSpaceClient({ storageServerUrl, zcapClient });
-    await was.space(spaceId).configure({ name, controller });
-    await ensurePlaintextCollection({
+export async function ensureUnlockSpace({ storageServerUrl, zcapClient, serviceDescription, spaceId, controller, name = UNLOCK_SPACE_NAME }) {
+    const was = unlockSpaceClient({
         storageServerUrl,
         zcapClient,
+        serviceDescription
+    });
+    await was.space(spaceId).configure({ name, controller });
+    await ensurePlaintextCollection({
+        was,
         spaceId,
         collectionId: KEYRING_COLLECTION.id,
         name: KEYRING_COLLECTION.name
@@ -158,15 +163,21 @@ export async function ensureUnlockSpace({ storageServerUrl, zcapClient, spaceId,
  * @param options {object}
  * @param options.storageServerUrl {string}
  * @param options.zcapClient {ZcapClient}
+ * @param [options.serviceDescription] {ServiceDescription}   the server's
+ *   service description a client the caller already holds discovered
+ *   (`(await was.service()).description`), so this one skips discovery
  * @param options.spaceId {string}   the unlock Space id
  * @param [options.capability] {IZcap}   the delegated management zcap;
  *   absent, the read is a root invocation
  * @returns {Promise<unknown | null>}
  */
-export async function getUnlockKeyring({ storageServerUrl, zcapClient, spaceId, capability }) {
+export async function getUnlockKeyring({ storageServerUrl, zcapClient, serviceDescription, spaceId, capability }) {
     return getPlaintextRecord({
-        storageServerUrl,
-        zcapClient,
+        was: unlockSpaceClient({
+            storageServerUrl,
+            zcapClient,
+            serviceDescription
+        }),
         spaceId,
         collectionId: KEYRING_COLLECTION.id,
         resourceId: KEYRING_RESOURCE,
@@ -187,16 +198,22 @@ export async function getUnlockKeyring({ storageServerUrl, zcapClient, spaceId,
  * @param options {object}
  * @param options.storageServerUrl {string}
  * @param options.zcapClient {ZcapClient}
+ * @param [options.serviceDescription] {ServiceDescription}   the server's
+ *   service description a client the caller already holds discovered
+ *   (`(await was.service()).description`), so this one skips discovery
  * @param options.spaceId {string}   the unlock Space id
  * @param options.record {object}   the keyring record
  * @param [options.capability] {IZcap}   the delegated management zcap;
  *   absent, the write is a root invocation
  * @returns {Promise<void>}
  */
-export async function putUnlockKeyring({ storageServerUrl, zcapClient, spaceId, record, capability }) {
+export async function putUnlockKeyring({ storageServerUrl, zcapClient, serviceDescription, spaceId, record, capability }) {
     await putPlaintextRecord({
-        storageServerUrl,
-        zcapClient,
+        was: unlockSpaceClient({
+            storageServerUrl,
+            zcapClient,
+            serviceDescription
+        }),
         spaceId,
         collectionId: KEYRING_COLLECTION.id,
         resourceId: KEYRING_RESOURCE,
@@ -222,6 +239,9 @@ export async function putUnlockKeyring({ storageServerUrl, zcapClient, spaceId,
  * @param options {object}
  * @param options.storageServerUrl {string}
  * @param options.zcapClient {ZcapClient}
+ * @param [options.serviceDescription] {ServiceDescription}   the server's
+ *   service description a client the caller already holds discovered
+ *   (`(await was.service()).description`), so this one skips discovery
  * @param options.spaceId {string}   the unlock Space id
  * @param [options.capability] {IZcap}   the delegated management zcap;
  *   absent, the delete is a root invocation
@@ -229,8 +249,12 @@ export async function putUnlockKeyring({ storageServerUrl, zcapClient, spaceId,
  *   when the server answered 404 (absent, or unauthorized under a
  *   capability); every other error propagates unchanged
  */
-export async function deleteUnlockSpace({ storageServerUrl, zcapClient, spaceId, capability }) {
-    const was = unlockSpaceClient({ storageServerUrl, zcapClient });
+export async function deleteUnlockSpace({ storageServerUrl, zcapClient, serviceDescription, spaceId, capability }) {
+    const was = unlockSpaceClient({
+        storageServerUrl,
+        zcapClient,
+        serviceDescription
+    });
     return was.space(spaceId, { capability }).deleteWithOutcome();
 }
 //# sourceMappingURL=unlockSpace.js.map

package/dist/keyring/unlockSpace.js.map

@@ -1 +1 @@
-{"version":3,"file":"unlockSpace.js","sourceRoot":"","sources":["../../src/keyring/unlockSpace.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"unlockSpace.js","sourceRoot":"","sources":["../../src/keyring/unlockSpace.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,EAAE,SAAS,EAA2B,MAAM,qBAAqB,CAAA;AAGxE,OAAO,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAA;AAC9E,OAAO,EAAE,mBAAmB,EAAE,MAAM,iCAAiC,CAAA;AAErE;;;;GAIG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,oBAAoB,CAAA;AAErD;;;;;;;;;;;;GAYG;AACH,SAAS,iBAAiB,CAAC,EACzB,gBAAgB,EAChB,UAAU,EACV,kBAAkB,EAKnB;IACC,OAAO,IAAI,SAAS,CAAC;QACnB,SAAS,EAAE,gBAAgB;QAC3B,UAAU;QACV,kBAAkB;KACnB,CAAC,CAAA;AACJ,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,KAAK,UAAU,yBAAyB,CAAC,EACvC,GAAG,EACH,OAAO,EACP,YAAY,EACZ,IAAI,EAML;IACC,MAAM,GAAG;SACN,KAAK,CAAC,OAAO,CAAC;SACd,UAAU,CAAC,YAAY,CAAC;SACxB,SAAS,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAA;AACrC,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,KAAK,UAAU,kBAAkB,CAAC,EAChC,GAAG,EACH,OAAO,EACP,YAAY,EACZ,UAAU,EACV,UAAU,EAOX;IACC,MAAM,MAAM,GAAG,MAAM,mBAAmB,CAAC;QACvC,GAAG;QACH,OAAO;QACP,YAAY;QACZ,UAAU;KACX,CAAC;SACC,QAAQ,CAAC,UAAU,CAAC;SACpB,GAAG,EAAE,CAAA;IACR,OAAO,MAAM,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAA;AACxC,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,KAAK,UAAU,kBAAkB,CAAC,EAChC,GAAG,EACH,OAAO,EACP,YAAY,EACZ,UAAU,EACV,MAAM,EACN,UAAU,EAQX;IACC,MAAM,IAAI,GAAG,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAA;IAC7D,MAAM,mBAAmB,CAAC,EAAE,GAAG,EAAE,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,CAAC;SAClE,QAAQ,CAAC,UAAU,CAAC;SACpB,GAAG,CAAC,IAAI,EAAE,EAAE,WAAW,EAAE,kBAAkB,EAAE,CAAC,CAAA;AACnD,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,EACtC,gBAAgB,EAChB,UAAU,EACV,kBAAkB,EAClB,OAAO,EACP,UAAU,EACV,IAAI,GAAG,iBAAiB,EAQzB;IACC,MAAM,GAAG,GAAG,iBAAiB,CAAC;QAC5B,gBAAgB;QAChB,UAAU;QACV,kBAAkB;KACnB,CAAC,CAAA;IACF,MAAM,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC,CAAA;IACxD,MAAM,yBAAyB,CAAC;QAC9B,GAAG;QACH,OAAO;QACP,YAAY,EAAE,kBAAkB,CAAC,EAAE;QACnC,IAAI,EAAE,kBAAkB,CAAC,IAAI;KAC9B,CAAC,CAAA;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,EACrC,gBAAgB,EAChB,UAAU,EACV,kBAAkB,EAClB,OAAO,EACP,UAAU,EAOX;IACC,OAAO,kBAAkB,CAAC;QACxB,GAAG,EAAE,iBAAiB,CAAC;YACrB,gBAAgB;YAChB,UAAU;YACV,kBAAkB;SACnB,CAAC;QACF,OAAO;QACP,YAAY,EAAE,kBAAkB,CAAC,EAAE;QACnC,UAAU,EAAE,gBAAgB;QAC5B,UAAU;KACX,CAAC,CAAA;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,EACrC,gBAAgB,EAChB,UAAU,EACV,kBAAkB,EAClB,OAAO,EACP,MAAM,EACN,UAAU,EAQX;IACC,MAAM,kBAAkB,CAAC;QACvB,GAAG,EAAE,iBAAiB,CAAC;YACrB,gBAAgB;YAChB,UAAU;YACV,kBAAkB;SACnB,CAAC;QACF,OAAO;QACP,YAAY,EAAE,kBAAkB,CAAC,EAAE;QACnC,UAAU,EAAE,gBAAgB;QAC5B,MAAM;QACN,UAAU;KACX,CAAC,CAAA;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,EACtC,gBAAgB,EAChB,UAAU,EACV,kBAAkB,EAClB,OAAO,EACP,UAAU,EAOX;IACC,MAAM,GAAG,GAAG,iBAAiB,CAAC;QAC5B,gBAAgB;QAChB,UAAU;QACV,kBAAkB;KACnB,CAAC,CAAA;IACF,OAAO,GAAG,CAAC,KAAK,CAAC,OAAO,EAAE,EAAE,UAAU,EAAE,CAAC,CAAC,iBAAiB,EAAE,CAAA;AAC/D,CAAC"}

package/dist/keys/collectionLogStore.d.ts

@@ -27,7 +27,7 @@
  */
 import type { DIDLog } from '@interop/did-method-webvh';
 import type { ZcapClient } from '@interop/ezcap';
-import { type Collection, type IZcap } from '@interop/was-client';
+import { type Collection, type IZcap, type ServiceDescription } from '@interop/was-client';
 import type { ResourceLogPinStore, ResourceLogSigner } from '@interop/vh-resource-log';
 import type { WebvhResourceLogController } from '../resourceLog/index.js';
 import { type SealableEncryptionDescriptorStore } from './rosterLogStore.js';
@@ -156,9 +156,12 @@ export declare function collectionDescriptorStores({ collectionFor, resolveContr
  * @param [options.capability] {IZcap}   an invocation capability every
  *   request rides (a transient visit's generation delegation); absent,
  *   requests invoke the root capability
+ * @param [options.serviceDescription] {ServiceDescription}   the server's
+ *   service description a client the caller already holds discovered
+ *   (`(await was.service()).description`), so this one skips discovery
  * @returns {CollectionStoreFor}
  */
-export declare function accountCollectionStores({ storageServerUrl, zcapClient, spaceId, did, pinStore, signer, log, capability }: {
+export declare function accountCollectionStores({ storageServerUrl, zcapClient, spaceId, did, pinStore, signer, log, capability, serviceDescription }: {
     storageServerUrl: string;
     zcapClient: ZcapClient;
     spaceId: string;
@@ -167,5 +170,6 @@ export declare function accountCollectionStores({ storageServerUrl, zcapClient,
     signer: ResourceLogSigner;
     log?: DIDLog;
     capability?: IZcap;
+    serviceDescription?: ServiceDescription;
 }): CollectionStoreFor;
 //# sourceMappingURL=collectionLogStore.d.ts.map