@interop/was-react 0.4.0 → 0.5.0

package/dist/storage/sharedCollectionReader.d.ts

@@ -0,0 +1,95 @@
+import type { IKeyAgreementKey, IKeyResolver } from '@interop/data-integrity-core';
+import { type Json } from '../sync/index.js';
+import type { WasRemoteStore } from './wasRemoteStore.js';
+/**
+ * Default page size for the `changes`-feed walk. The server clamps its own
+ * maximum, and a page shorter than what was asked for is the feed's end-of-walk
+ * signal. Lower it on a collection of large envelopes to bound per-response
+ * size.
+ */
+export declare const SHARED_CHANGES_PAGE_SIZE = 100;
+/**
+ * One decrypted resource of a shared collection: the WAS resource id (the
+ * envelope id, opaque) and its decrypted payload.
+ */
+export interface SharedResource {
+    id: string;
+    data: Json;
+}
+/**
+ * Thrown when a shared collection cannot be opened for reading: it carries no
+ * multi-recipient key-epoch roster, or this app is not a recipient of any epoch
+ * on it (the wallet never shared it, or a later un-share rotated the epoch off
+ * this app's key).
+ */
+export declare class SharedCollectionUnavailableError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+export declare class SharedCollectionReader {
+    #private;
+    readonly collectionId: string;
+    private constructor();
+    /**
+     * Opens a reader over one shared collection: reads its `encryption` marker
+     * through the delegated zcap and builds the epoch-aware cipher from it.
+     *
+     * Throws {@link SharedCollectionUnavailableError} when the collection carries
+     * no marker or a marker with no key epochs (it is not multi-recipient, so this
+     * app cannot be a recipient of it), and likewise when the cipher cannot unwrap
+     * any epoch (this app is not, or is no longer, in the roster).
+     *
+     * @param options {object}
+     * @param options.remoteStore {WasRemoteStore}   the delegated remote store
+     * @param options.keyAgreementKey {IKeyAgreementKey}   this app's IDENTITY KAK
+     * @param options.keyResolver {IKeyResolver}   its one-key resolver
+     * @param options.collectionId {string}   the WAS collection id
+     * @param [options.pageSize] {number}   `changes`-feed page size (defaults to
+     *   {@link SHARED_CHANGES_PAGE_SIZE})
+     * @returns {Promise<SharedCollectionReader>}
+     */
+    static open({ remoteStore, keyAgreementKey, keyResolver, collectionId, pageSize }: {
+        remoteStore: WasRemoteStore;
+        keyAgreementKey: IKeyAgreementKey;
+        keyResolver: IKeyResolver;
+        collectionId: string;
+        pageSize?: number;
+    }): Promise<SharedCollectionReader>;
+    /**
+     * Lists the LIVE resources of the shared collection, decrypted. A body that is
+     * not an EDV envelope, or one sealed before the collection's first share (a
+     * single-recipient envelope this app is not a recipient of), is SKIPPED with a
+     * warning rather than failing the whole listing.
+     *
+     * Two paths, same result. The fast path pages the `changes` feed
+     * ({@link SharedCollectionReader.listViaChanges}), which returns whole pages of
+     * documents WITH their bodies -- and on an encrypted collection those bodies
+     * are exactly the opaque EDV envelopes wanted here, since the feed does not
+     * decrypt. That is one round trip per PAGE rather than the one per RESOURCE a
+     * listing plus a `get` each would cost, which on a wallet's
+     * `private-credentials` or `contacts` is the difference between a handful of
+     * requests and one per credential. It is also the same primitive replication
+     * pulls with.
+     *
+     * The slow path ({@link SharedCollectionReader.listViaResources}) is the
+     * fallback for a backend that does not advertise the `changes-query` feature
+     * (it answers 501, surfaced as `NotImplementedError`): list the resource
+     * summaries, then fetch each body. Taken only on that specific error, and
+     * warned about once per reader.
+     *
+     * @returns {Promise<SharedResource[]>}
+     */
+    list(): Promise<SharedResource[]>;
+    /**
+     * Reads and decrypts one resource of the shared collection by its WAS
+     * resource id. Returns `undefined` for a missing resource, a body that is not
+     * an EDV envelope, or a pre-share envelope this app cannot decrypt (each
+     * warned about, distinguishably).
+     *
+     * @param resourceId {string}   the WAS resource id
+     * @returns {Promise<Json | undefined>}
+     */
+    get(resourceId: string): Promise<Json | undefined>;
+}
+//# sourceMappingURL=sharedCollectionReader.d.ts.map

package/dist/storage/sharedCollectionReader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sharedCollectionReader.d.ts","sourceRoot":"","sources":["../../src/storage/sharedCollectionReader.ts"],"names":[],"mappings":"AAqCA,OAAO,KAAK,EACV,gBAAgB,EAChB,YAAY,EACb,MAAM,8BAA8B,CAAA;AAErC,OAAO,EAKL,KAAK,IAAI,EACV,MAAM,kBAAkB,CAAA;AACzB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AAEzD;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,MAAM,CAAA;AAU3C;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,IAAI,CAAA;CACX;AAED;;;;;GAKG;AACH,qBAAa,gCAAiC,SAAQ,KAAK;gBAC7C,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAI3D;AAED,qBAAa,sBAAsB;;IACjC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAe7B,OAAO;IAuBP;;;;;;;;;;;;;;;;;OAiBG;WACU,IAAI,CAAC,EAChB,WAAW,EACX,eAAe,EACf,WAAW,EACX,YAAY,EACZ,QAAmC,EACpC,EAAE;QACD,WAAW,EAAE,cAAc,CAAA;QAC3B,eAAe,EAAE,gBAAgB,CAAA;QACjC,WAAW,EAAE,YAAY,CAAA;QACzB,YAAY,EAAE,MAAM,CAAA;QACpB,QAAQ,CAAC,EAAE,MAAM,CAAA;KAClB,GAAG,OAAO,CAAC,sBAAsB,CAAC;IAkBnC;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACG,IAAI,IAAI,OAAO,CAAC,cAAc,EAAE,CAAC;IA4EvC;;;;;;;;OAQG;IACG,GAAG,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,GAAG,SAAS,CAAC;CAgGzD"}

package/dist/storage/sharedCollectionReader.js

@@ -0,0 +1,338 @@
+/*!
+ * Copyright (c) 2026 Interop Alliance. All rights reserved.
+ */
+/**
+ * SharedCollectionReader: a READ-ONLY view over one wallet-owned encrypted
+ * collection the wallet has shared with this app (the
+ * `urn:was:shared-collection` grant). It is the app-side other half of the
+ * wallet's share flow, and it is read-only BY CONSTRUCTION -- there is no write
+ * verb on this class, the collection is never replicated into RxDB, and the
+ * sync bootstrap never PUTs a description onto it.
+ *
+ * A share fuses two axes, and both are needed here:
+ *
+ * - **pull** -- the delegated `GET`/`HEAD` zcap on the collection, which is what
+ *   the server checks at request time;
+ * - **read** -- an entry in the collection's key-epoch roster, wrapped to this
+ *   app's IDENTITY key-agreement key (the X25519 twin of its did:key
+ *   controller, `IdentityAgents.keyAgreementKey`). That is the same key the
+ *   app's own collections are encrypted with: one rule for every roster entry,
+ *   whoever owns the collection.
+ *
+ * The stored resource body IS the EDV envelope the wallet's replication moved
+ * verbatim, so reads must be RAW: the handle is opened with the
+ * `encryption: 'plaintext'` override (the `WasClient`'s own encryption provider
+ * is a deliberate no-op keystore) and the envelope is decrypted locally with a
+ * cipher built from the collection's `encryption` marker.
+ *
+ * The honest ceiling, the same one the wallet's consent screen states:
+ *
+ * - access can be removed later, which stops FUTURE reads but cannot take back
+ *   what has already been read;
+ * - resources written BEFORE the collection's first share are single-recipient
+ *   envelopes sealed to the owner alone. They will not decrypt here. That is
+ *   expected, not corruption -- they are skipped with a warning.
+ */
+import { NotImplementedError } from '@interop/was-client';
+import { UnknownEpochError } from '@interop/was-client/edv';
+import { createDocCipher, errorMessage, isEncryptedEnvelope } from '../sync/index.js';
+/**
+ * Default page size for the `changes`-feed walk. The server clamps its own
+ * maximum, and a page shorter than what was asked for is the feed's end-of-walk
+ * signal. Lower it on a collection of large envelopes to bound per-response
+ * size.
+ */
+export const SHARED_CHANGES_PAGE_SIZE = 100;
+/**
+ * Thrown when a shared collection cannot be opened for reading: it carries no
+ * multi-recipient key-epoch roster, or this app is not a recipient of any epoch
+ * on it (the wallet never shared it, or a later un-share rotated the epoch off
+ * this app's key).
+ */
+export class SharedCollectionUnavailableError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = 'SharedCollectionUnavailableError';
+    }
+}
+export class SharedCollectionReader {
+    collectionId;
+    #remoteStore;
+    #keyAgreementKey;
+    #keyResolver;
+    #cipher;
+    // Whether an unknown-epoch marker refresh has already run for this reader. An
+    // epoch rotation emits no change-feed entry, so a stale marker is the
+    // expected failure mode; one refresh per reader is enough to recover, and the
+    // cap keeps a genuinely undecryptable envelope from looping.
+    #refreshed = false;
+    // Whether the one-time "reading this collection the slow way" warning has
+    // already been emitted for this reader.
+    #warnedSlowPath = false;
+    #pageSize;
+    constructor({ collectionId, remoteStore, keyAgreementKey, keyResolver, cipher, pageSize }) {
+        this.collectionId = collectionId;
+        this.#remoteStore = remoteStore;
+        this.#keyAgreementKey = keyAgreementKey;
+        this.#keyResolver = keyResolver;
+        this.#cipher = cipher;
+        this.#pageSize = pageSize;
+    }
+    /**
+     * Opens a reader over one shared collection: reads its `encryption` marker
+     * through the delegated zcap and builds the epoch-aware cipher from it.
+     *
+     * Throws {@link SharedCollectionUnavailableError} when the collection carries
+     * no marker or a marker with no key epochs (it is not multi-recipient, so this
+     * app cannot be a recipient of it), and likewise when the cipher cannot unwrap
+     * any epoch (this app is not, or is no longer, in the roster).
+     *
+     * @param options {object}
+     * @param options.remoteStore {WasRemoteStore}   the delegated remote store
+     * @param options.keyAgreementKey {IKeyAgreementKey}   this app's IDENTITY KAK
+     * @param options.keyResolver {IKeyResolver}   its one-key resolver
+     * @param options.collectionId {string}   the WAS collection id
+     * @param [options.pageSize] {number}   `changes`-feed page size (defaults to
+     *   {@link SHARED_CHANGES_PAGE_SIZE})
+     * @returns {Promise<SharedCollectionReader>}
+     */
+    static async open({ remoteStore, keyAgreementKey, keyResolver, collectionId, pageSize = SHARED_CHANGES_PAGE_SIZE }) {
+        const encryption = await remoteStore.readCollectionEncryption(collectionId);
+        const cipher = await buildSharedCipher({
+            collectionId,
+            keyAgreementKey,
+            keyResolver,
+            encryption
+        });
+        return new SharedCollectionReader({
+            collectionId,
+            remoteStore,
+            keyAgreementKey,
+            keyResolver,
+            cipher,
+            pageSize
+        });
+    }
+    /**
+     * Lists the LIVE resources of the shared collection, decrypted. A body that is
+     * not an EDV envelope, or one sealed before the collection's first share (a
+     * single-recipient envelope this app is not a recipient of), is SKIPPED with a
+     * warning rather than failing the whole listing.
+     *
+     * Two paths, same result. The fast path pages the `changes` feed
+     * ({@link SharedCollectionReader.listViaChanges}), which returns whole pages of
+     * documents WITH their bodies -- and on an encrypted collection those bodies
+     * are exactly the opaque EDV envelopes wanted here, since the feed does not
+     * decrypt. That is one round trip per PAGE rather than the one per RESOURCE a
+     * listing plus a `get` each would cost, which on a wallet's
+     * `private-credentials` or `contacts` is the difference between a handful of
+     * requests and one per credential. It is also the same primitive replication
+     * pulls with.
+     *
+     * The slow path ({@link SharedCollectionReader.listViaResources}) is the
+     * fallback for a backend that does not advertise the `changes-query` feature
+     * (it answers 501, surfaced as `NotImplementedError`): list the resource
+     * summaries, then fetch each body. Taken only on that specific error, and
+     * warned about once per reader.
+     *
+     * @returns {Promise<SharedResource[]>}
+     */
+    async list() {
+        const collection = this.#collectionHandle();
+        try {
+            return await this.#listViaChanges(collection);
+        }
+        catch (err) {
+            if (!(err instanceof NotImplementedError)) {
+                throw err;
+            }
+            if (!this.#warnedSlowPath) {
+                this.#warnedSlowPath = true;
+                console.warn(`Shared collection "${this.collectionId}" is being read the slow ` +
+                    `way (one request per resource): its backend does not support the ` +
+                    `"changes-query" feature the paged read path needs.`);
+            }
+            return await this.#listViaResources(collection);
+        }
+    }
+    /**
+     * The fast path: walk the `changes` feed page by page, resuming from each
+     * page's returned checkpoint, until a page comes back shorter than the
+     * requested limit (the feed's "you have caught up" signal). Tombstones
+     * (`_deleted`) are skipped, so the result is the LIVE set -- the same
+     * semantics the resource-listing path has. A resource that changes more than
+     * once within the walk appears under one id, so the last body seen wins.
+     */
+    async #listViaChanges(collection) {
+        const bodies = new Map();
+        let checkpoint;
+        for (;;) {
+            const page = await collection.changes({
+                ...(checkpoint && { checkpoint }),
+                limit: this.#pageSize
+            });
+            for (const document of page.documents) {
+                if (document._deleted) {
+                    bodies.delete(document.id);
+                    continue;
+                }
+                bodies.set(document.id, document.data);
+            }
+            if (page.documents.length < this.#pageSize || !page.checkpoint) {
+                break;
+            }
+            checkpoint = page.checkpoint;
+        }
+        const resources = [];
+        for (const [id, body] of bodies) {
+            const decrypted = await this.#decryptBody({ id, body: body ?? null });
+            if (decrypted !== undefined) {
+                resources.push({ id, data: decrypted });
+            }
+        }
+        return resources;
+    }
+    /**
+     * The slow path: one listing request for the resource summaries, then one
+     * request per resource for its body.
+     */
+    async #listViaResources(collection) {
+        const listing = await collection.list();
+        const items = listing?.items ?? [];
+        const resources = [];
+        for (const item of items) {
+            const body = (await collection.get(item.id));
+            const decrypted = await this.#decryptBody({ id: item.id, body });
+            if (decrypted !== undefined) {
+                resources.push({ id: item.id, data: decrypted });
+            }
+        }
+        return resources;
+    }
+    /**
+     * Reads and decrypts one resource of the shared collection by its WAS
+     * resource id. Returns `undefined` for a missing resource, a body that is not
+     * an EDV envelope, or a pre-share envelope this app cannot decrypt (each
+     * warned about, distinguishably).
+     *
+     * @param resourceId {string}   the WAS resource id
+     * @returns {Promise<Json | undefined>}
+     */
+    async get(resourceId) {
+        const body = (await this.#collectionHandle().get(resourceId));
+        return await this.#decryptBody({ id: resourceId, body });
+    }
+    /**
+     * The RAW collection handle: the delegated zcap plus the
+     * `encryption: 'plaintext'` override, so `get`/`list` return the stored EDV
+     * envelope verbatim instead of routing it through the client's (no-op)
+     * encryption provider.
+     */
+    #collectionHandle() {
+        const capability = this.#remoteStore.collectionCapability(this.collectionId);
+        if (!capability) {
+            throw new SharedCollectionUnavailableError(`No delegated capability covers the shared collection ` +
+                `"${this.collectionId}".`);
+        }
+        return this.#remoteStore.was
+            .space(this.#remoteStore.spaceId)
+            .collection(this.collectionId, { capability, encryption: 'plaintext' });
+    }
+    /**
+     * Decrypts one fetched body, tolerating the two expected non-results: a body
+     * that is not an EDV envelope at all, and a pre-share single-recipient
+     * envelope. An {@link UnknownEpochError} drives one marker re-read + cipher
+     * rebuild + retry (an epoch rotation emits no change-feed entry, so a stale
+     * marker is the expected failure mode).
+     */
+    async #decryptBody({ id, body }) {
+        if (body === null || body === undefined) {
+            return undefined;
+        }
+        if (!isEncryptedEnvelope(body)) {
+            console.warn(`Skipping resource "${id}" of shared collection ` +
+                `"${this.collectionId}": its body is not an EDV envelope.`);
+            return undefined;
+        }
+        try {
+            return await this.#cipher.decrypt({ envelope: body });
+        }
+        catch (err) {
+            if (err instanceof UnknownEpochError && !this.#refreshed) {
+                this.#refreshed = true;
+                await this.#rebuildCipher();
+                try {
+                    return await this.#cipher.decrypt({ envelope: body });
+                }
+                catch (retryErr) {
+                    return this.#skipUndecryptable({ id, err: retryErr });
+                }
+            }
+            return this.#skipUndecryptable({ id, err });
+        }
+    }
+    /**
+     * Re-reads the collection's `encryption` marker and rebuilds the cipher from
+     * it. Used once per reader on an unknown epoch.
+     */
+    async #rebuildCipher() {
+        const encryption = await this.#remoteStore.readCollectionEncryption(this.collectionId);
+        this.#cipher = await buildSharedCipher({
+            collectionId: this.collectionId,
+            keyAgreementKey: this.#keyAgreementKey,
+            keyResolver: this.#keyResolver,
+            encryption
+        });
+    }
+    /**
+     * Warns about, and skips, one envelope this app cannot decrypt. The
+     * overwhelmingly likely cause is a resource written BEFORE the collection's
+     * first share -- sealed to the owner's key alone, never re-encrypted -- which
+     * is expected rather than corruption, so it is called out by name.
+     */
+    #skipUndecryptable({ id, err }) {
+        console.warn(`Skipping resource "${id}" of shared collection ` +
+            `"${this.collectionId}": this app is not a recipient of its envelope ` +
+            `(expected for resources written before the collection was first ` +
+            `shared -- those are sealed to the owner alone and are never ` +
+            `re-encrypted). ${errorMessage(err)}`);
+        return undefined;
+    }
+}
+/**
+ * Builds the epoch-aware cipher for a shared collection, turning the two
+ * "cannot read this collection" outcomes into one descriptive error: no
+ * multi-recipient roster at all, and a roster this app is not in.
+ *
+ * Only the cipher's `decrypt` is ever exercised here -- the reader has no write
+ * path -- so the seam's write-side id model is irrelevant.
+ *
+ * @param options {object}
+ * @param options.collectionId {string}
+ * @param options.keyAgreementKey {IKeyAgreementKey}
+ * @param options.keyResolver {IKeyResolver}
+ * @param [options.encryption] {CollectionEncryption}
+ * @returns {Promise<DocCipher>}
+ */
+async function buildSharedCipher({ collectionId, keyAgreementKey, keyResolver, encryption }) {
+    if (!encryption?.epochs || encryption.epochs.length === 0) {
+        throw new SharedCollectionUnavailableError(`Shared collection "${collectionId}" carries no key-epoch roster, so it ` +
+            `is not multi-recipient and this app cannot be a recipient of it. The ` +
+            `wallet has not shared it with this app.`);
+    }
+    try {
+        return await createDocCipher({
+            keyAgreementKey,
+            keyResolver,
+            collectionId,
+            encryption
+        });
+    }
+    catch (err) {
+        throw new SharedCollectionUnavailableError(`Cannot read shared collection "${collectionId}": this app is not a ` +
+            `recipient of any of its key epochs. The wallet has not shared it ` +
+            `with this app, or access was removed (removing access rotates the ` +
+            `epoch off this app's key).`, { cause: err });
+    }
+}
+//# sourceMappingURL=sharedCollectionReader.js.map

package/dist/storage/sharedCollectionReader.js.map

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

package/dist/storage/wasSync.d.ts

@@ -10,18 +10,38 @@
  * controller, and the per-doc `onRemoteChange` patcher (typically wired to the
  * rehydrate mechanism over the app's store registry) rather than this module
  * reaching for app-side globals.
+ *
+ * SHARED collections are handled apart from all of that. They belong to the
+ * wallet, so they never enter replication, never get a local replica, and are
+ * excluded from the best-effort description PUTs (a read-only grant would draw
+ * nothing but a pointless 403). Instead one {@link SharedCollectionReader} is
+ * opened per configured shared collection the grant set actually covers; a
+ * shared collection with no covering grant, or one this app turns out not to be
+ * a recipient of, is skipped with a warning rather than failing the session.
  */
 import type { ZcapClient } from '@interop/ezcap';
 import type { RxChangeEvent } from 'rxdb/plugins/core';
 import type { CollectionEncryption } from '@interop/was-client';
+import type { IKeyAgreementKey, IKeyResolver } from '@interop/data-integrity-core';
 import type { SyncedDoc } from '../sync/index.js';
-import type { WasCollectionConfig } from '../config.js';
+import type { SharedCollectionConfig, WasCollectionConfig } from '../config.js';
 import type { ParsedGrants } from '../grants.js';
 import { WasRemoteStore } from './wasRemoteStore.js';
+import { SharedCollectionReader } from './sharedCollectionReader.js';
 import type { LocalStore } from './localStore.js';
 import type { SyncController } from './syncController.js';
 /**
- * Builds the remote store and starts background replication.
+ * What the sync bootstrap hands back: the delegated remote store, plus a
+ * read-only {@link SharedCollectionReader} per configured shared collection the
+ * grant set covers and this app is a recipient of, keyed by the config `key`.
+ */
+export interface WasSyncBootstrap {
+    remoteStore: WasRemoteStore;
+    sharedCollections: Record<string, SharedCollectionReader>;
+}
+/**
+ * Builds the remote store, opens the shared-collection readers, and starts
+ * background replication.
  *
  * @param options {object}
  * @param options.parsed {ParsedGrants}
@@ -32,21 +52,33 @@ import type { SyncController } from './syncController.js';
  * @param options.syncController {SyncController}   a fresh per-session controller
  * @param options.onRemoteChange {(collectionKey, event) => void}   per-doc
  *   reactive patcher for pulled/conflict-resolved remote changes
+ * @param [options.sharedCollections] {SharedCollectionConfig[]}   the shared
+ *   (read-only, wallet-owned) registry; never replicated, never written to
+ * @param [options.identityKeys] {object}   this app's IDENTITY key-agreement key
+ *   and its resolver, the recipient identity a wallet writes into a shared
+ *   collection's epoch roster. Required to open any shared-collection reader
+ * @param [options.identityKeys.keyAgreementKey] {IKeyAgreementKey}
+ * @param [options.identityKeys.keyResolver] {IKeyResolver}
  * @param [options.onAuthError] {() => void}   fired when replication hits a
  *   401/403 (expired/revoked access) -- wired to the reconnect banner
  * @param [options.onMarkersFetched] {(markers) => void | Promise<void>}   given
  *   the freshly fetched per-collection encryption markers (by WAS collection
  *   id), to refresh the offline marker cache
- * @returns {Promise<WasRemoteStore>}
+ * @returns {Promise<WasSyncBootstrap>}
  */
-export declare function startWasSync({ parsed, zcapClient, collections, localStore, syncController, onRemoteChange, onAuthError, onMarkersFetched }: {
+export declare function startWasSync({ parsed, zcapClient, collections, localStore, syncController, onRemoteChange, sharedCollections, identityKeys, onAuthError, onMarkersFetched }: {
     parsed: ParsedGrants;
     zcapClient: ZcapClient;
     collections: WasCollectionConfig[];
     localStore: LocalStore;
     syncController: SyncController;
     onRemoteChange: (collectionKey: string, event: RxChangeEvent<SyncedDoc>) => void;
+    sharedCollections?: SharedCollectionConfig[];
+    identityKeys?: {
+        keyAgreementKey: IKeyAgreementKey;
+        keyResolver: IKeyResolver;
+    };
     onAuthError?: () => void;
     onMarkersFetched?: (markers: Record<string, CollectionEncryption>) => void | Promise<void>;
-}): Promise<WasRemoteStore>;
+}): Promise<WasSyncBootstrap>;
 //# sourceMappingURL=wasSync.d.ts.map

package/dist/storage/wasSync.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"wasSync.d.ts","sourceRoot":"","sources":["../../src/storage/wasSync.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;GASG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AAChD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AACtD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAA;AAC/D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAA;AACjD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAA;AACvD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AAChD,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AACpD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AACjD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AAEzD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,YAAY,CAAC,EACjC,MAAM,EACN,UAAU,EACV,WAAW,EACX,UAAU,EACV,cAAc,EACd,cAAc,EACd,WAAW,EACX,gBAAgB,EACjB,EAAE;IACD,MAAM,EAAE,YAAY,CAAA;IACpB,UAAU,EAAE,UAAU,CAAA;IACtB,WAAW,EAAE,mBAAmB,EAAE,CAAA;IAClC,UAAU,EAAE,UAAU,CAAA;IACtB,cAAc,EAAE,cAAc,CAAA;IAC9B,cAAc,EAAE,CACd,aAAa,EAAE,MAAM,EACrB,KAAK,EAAE,aAAa,CAAC,SAAS,CAAC,KAC5B,IAAI,CAAA;IACT,WAAW,CAAC,EAAE,MAAM,IAAI,CAAA;IACxB,gBAAgB,CAAC,EAAE,CACjB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,KAC1C,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAC1B,GAAG,OAAO,CAAC,cAAc,CAAC,CAkE1B"}
+{"version":3,"file":"wasSync.d.ts","sourceRoot":"","sources":["../../src/storage/wasSync.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AAChD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AACtD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAA;AAC/D,OAAO,KAAK,EACV,gBAAgB,EAChB,YAAY,EACb,MAAM,8BAA8B,CAAA;AACrC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAA;AACjD,OAAO,KAAK,EAAE,sBAAsB,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAA;AAC/E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AAChD,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AACpD,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAA;AACpE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AACjD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AAEzD;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,WAAW,EAAE,cAAc,CAAA;IAC3B,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAAA;CAC1D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAsB,YAAY,CAAC,EACjC,MAAM,EACN,UAAU,EACV,WAAW,EACX,UAAU,EACV,cAAc,EACd,cAAc,EACd,iBAAsB,EACtB,YAAY,EACZ,WAAW,EACX,gBAAgB,EACjB,EAAE;IACD,MAAM,EAAE,YAAY,CAAA;IACpB,UAAU,EAAE,UAAU,CAAA;IACtB,WAAW,EAAE,mBAAmB,EAAE,CAAA;IAClC,UAAU,EAAE,UAAU,CAAA;IACtB,cAAc,EAAE,cAAc,CAAA;IAC9B,cAAc,EAAE,CACd,aAAa,EAAE,MAAM,EACrB,KAAK,EAAE,aAAa,CAAC,SAAS,CAAC,KAC5B,IAAI,CAAA;IACT,iBAAiB,CAAC,EAAE,sBAAsB,EAAE,CAAA;IAC5C,YAAY,CAAC,EAAE;QACb,eAAe,EAAE,gBAAgB,CAAA;QACjC,WAAW,EAAE,YAAY,CAAA;KAC1B,CAAA;IACD,WAAW,CAAC,EAAE,MAAM,IAAI,CAAA;IACxB,gBAAgB,CAAC,EAAE,CACjB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,KAC1C,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAC1B,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAqG5B"}

package/dist/storage/wasSync.js

@@ -1,6 +1,8 @@
 import { WasRemoteStore } from './wasRemoteStore.js';
+import { SharedCollectionReader } from './sharedCollectionReader.js';
 /**
- * Builds the remote store and starts background replication.
+ * Builds the remote store, opens the shared-collection readers, and starts
+ * background replication.
  *
  * @param options {object}
  * @param options.parsed {ParsedGrants}
@@ -11,14 +13,21 @@ import { WasRemoteStore } from './wasRemoteStore.js';
  * @param options.syncController {SyncController}   a fresh per-session controller
  * @param options.onRemoteChange {(collectionKey, event) => void}   per-doc
  *   reactive patcher for pulled/conflict-resolved remote changes
+ * @param [options.sharedCollections] {SharedCollectionConfig[]}   the shared
+ *   (read-only, wallet-owned) registry; never replicated, never written to
+ * @param [options.identityKeys] {object}   this app's IDENTITY key-agreement key
+ *   and its resolver, the recipient identity a wallet writes into a shared
+ *   collection's epoch roster. Required to open any shared-collection reader
+ * @param [options.identityKeys.keyAgreementKey] {IKeyAgreementKey}
+ * @param [options.identityKeys.keyResolver] {IKeyResolver}
  * @param [options.onAuthError] {() => void}   fired when replication hits a
  *   401/403 (expired/revoked access) -- wired to the reconnect banner
  * @param [options.onMarkersFetched] {(markers) => void | Promise<void>}   given
  *   the freshly fetched per-collection encryption markers (by WAS collection
  *   id), to refresh the offline marker cache
- * @returns {Promise<WasRemoteStore>}
+ * @returns {Promise<WasSyncBootstrap>}
  */
-export async function startWasSync({ parsed, zcapClient, collections, localStore, syncController, onRemoteChange, onAuthError, onMarkersFetched }) {
+export async function startWasSync({ parsed, zcapClient, collections, localStore, syncController, onRemoteChange, sharedCollections = [], identityKeys, onAuthError, onMarkersFetched }) {
     const remoteStore = WasRemoteStore.fromGrants({
         parsed,
         zcapClient,
@@ -30,7 +39,10 @@ export async function startWasSync({ parsed, zcapClient, collections, localStore
     // collections it does not apply to (reported ok + skipped): the encryption
     // marker skips public collections, the indexes declaration skips private
     // ones and public ones with no declared indexes.
-    await Promise.all(Object.keys(parsed.byCollectionId).map(async (collectionId) => {
+    const sharedIds = new Set(sharedCollections.map(entry => entry.id));
+    await Promise.all(Object.keys(parsed.byCollectionId)
+        .filter(collectionId => !sharedIds.has(collectionId))
+        .map(async (collectionId) => {
         const marker = await remoteStore.markCollectionEncrypted(collectionId);
         if (!marker.ok) {
             console.warn(`Encryption marker PUT not authorized for "${collectionId}" (status ${marker.status ?? 'n/a'}).`);
@@ -63,12 +75,40 @@ export async function startWasSync({ parsed, zcapClient, collections, localStore
     if (onMarkersFetched) {
         await onMarkersFetched(markers);
     }
+    // Shared collections stay entirely out of replication: one read-only reader
+    // each, opened over the delegated read zcap and the collection's epoch
+    // roster. Every failure mode here is a warn-and-skip -- an uncovered grant,
+    // a collection with no roster, an app that is not (or is no longer) a
+    // recipient -- so a removed share degrades one reader, never the session.
+    const sharedReaders = {};
+    for (const { key, id } of sharedCollections) {
+        if (!parsed.byCollectionId[id]) {
+            console.warn(`Skipping shared collection "${id}": no delegated capability covers it.`);
+            continue;
+        }
+        if (!identityKeys) {
+            console.warn(`Skipping shared collection "${id}": no identity key-agreement key was ` +
+                `supplied to decrypt it with.`);
+            continue;
+        }
+        try {
+            sharedReaders[key] = await SharedCollectionReader.open({
+                remoteStore,
+                keyAgreementKey: identityKeys.keyAgreementKey,
+                keyResolver: identityKeys.keyResolver,
+                collectionId: id
+            });
+        }
+        catch (err) {
+            console.warn(`Skipping shared collection "${id}":`, err);
+        }
+    }
     await syncController.start({
         remoteStore,
         localStore,
         onRemoteChange,
         ...(onAuthError && { onAuthError })
     });
-    return remoteStore;
+    return { remoteStore, sharedCollections: sharedReaders };
 }
 //# sourceMappingURL=wasSync.js.map

package/dist/storage/wasSync.js.map

@@ -1 +1 @@
-{"version":3,"file":"wasSync.js","sourceRoot":"","sources":["../../src/storage/wasSync.ts"],"names":[],"mappings":"AAmBA,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AAIpD;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,EACjC,MAAM,EACN,UAAU,EACV,WAAW,EACX,UAAU,EACV,cAAc,EACd,cAAc,EACd,WAAW,EACX,gBAAgB,EAejB;IACC,MAAM,WAAW,GAAG,cAAc,CAAC,UAAU,CAAC;QAC5C,MAAM;QACN,UAAU;QACV,WAAW;KACZ,CAAC,CAAA;IAEF,2EAA2E;IAC3E,2EAA2E;IAC3E,0EAA0E;IAC1E,2EAA2E;IAC3E,yEAAyE;IACzE,iDAAiD;IACjD,MAAM,OAAO,CAAC,GAAG,CACf,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC,GAAG,CAAC,KAAK,EAAC,YAAY,EAAC,EAAE;QAC1D,MAAM,MAAM,GAAG,MAAM,WAAW,CAAC,uBAAuB,CAAC,YAAY,CAAC,CAAA;QACtE,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;YACf,OAAO,CAAC,IAAI,CACV,6CAA6C,YAAY,aAAa,MAAM,CAAC,MAAM,IAAI,KAAK,IAAI,CACjG,CAAA;QACH,CAAC;QACD,MAAM,OAAO,GAAG,MAAM,WAAW,CAAC,wBAAwB,CAAC,YAAY,CAAC,CAAA;QACxE,IAAI,CAAC,OAAO,CAAC,EAAE,EAAE,CAAC;YAChB,OAAO,CAAC,IAAI,CACV,+CAA+C,YAAY,aAAa,OAAO,CAAC,MAAM,IAAI,KAAK,IAAI,CACpG,CAAA;QACH,CAAC;IACH,CAAC,CAAC,CACH,CAAA;IAED,0EAA0E;IAC1E,8EAA8E;IAC9E,2EAA2E;IAC3E,4EAA4E;IAC5E,+CAA+C;IAC/C,MAAM,UAAU,GAAG,WAAW;SAC3B,MAAM,CAAC,UAAU,CAAC,EAAE,CAAC,UAAU,CAAC,UAAU,KAAK,QAAQ,CAAC;SACxD,GAAG,CAAC,UAAU,CAAC,EAAE,CAAC,UAAU,CAAC,EAAE,CAAC;SAChC,MAAM,CAAC,EAAE,CAAC,EAAE,CAAC,MAAM,CAAC,cAAc,CAAC,EAAE,CAAC,KAAK,SAAS,CAAC,CAAA;IACxD,MAAM,OAAO,GAAyC,EAAE,CAAA;IACxD,MAAM,OAAO,CAAC,GAAG,CACf,UAAU,CAAC,GAAG,CAAC,KAAK,EAAC,YAAY,EAAC,EAAE;QAClC,MAAM,UAAU,GACd,MAAM,WAAW,CAAC,wBAAwB,CAAC,YAAY,CAAC,CAAA;QAC1D,IAAI,UAAU,EAAE,CAAC;YACf,OAAO,CAAC,YAAY,CAAC,GAAG,UAAU,CAAA;YAClC,MAAM,UAAU,CAAC,iBAAiB,CAAC,EAAE,YAAY,EAAE,UAAU,EAAE,CAAC,CAAA;QAClE,CAAC;IACH,CAAC,CAAC,CACH,CAAA;IACD,+EAA+E;IAC/E,8EAA8E;IAC9E,UAAU,CAAC,iBAAiB,CAAC,YAAY,CAAC,EAAE,CAC1C,WAAW,CAAC,wBAAwB,CAAC,YAAY,CAAC,CACnD,CAAA;IACD,IAAI,gBAAgB,EAAE,CAAC;QACrB,MAAM,gBAAgB,CAAC,OAAO,CAAC,CAAA;IACjC,CAAC;IAED,MAAM,cAAc,CAAC,KAAK,CAAC;QACzB,WAAW;QACX,UAAU;QACV,cAAc;QACd,GAAG,CAAC,WAAW,IAAI,EAAE,WAAW,EAAE,CAAC;KACpC,CAAC,CAAA;IACF,OAAO,WAAW,CAAA;AACpB,CAAC"}
+{"version":3,"file":"wasSync.js","sourceRoot":"","sources":["../../src/storage/wasSync.ts"],"names":[],"mappings":"AA+BA,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AACpD,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAA;AAcpE;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,EACjC,MAAM,EACN,UAAU,EACV,WAAW,EACX,UAAU,EACV,cAAc,EACd,cAAc,EACd,iBAAiB,GAAG,EAAE,EACtB,YAAY,EACZ,WAAW,EACX,gBAAgB,EAoBjB;IACC,MAAM,WAAW,GAAG,cAAc,CAAC,UAAU,CAAC;QAC5C,MAAM;QACN,UAAU;QACV,WAAW;KACZ,CAAC,CAAA;IAEF,2EAA2E;IAC3E,2EAA2E;IAC3E,0EAA0E;IAC1E,2EAA2E;IAC3E,yEAAyE;IACzE,iDAAiD;IACjD,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC,iBAAiB,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAA;IACnE,MAAM,OAAO,CAAC,GAAG,CACf,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,cAAc,CAAC;SAC/B,MAAM,CAAC,YAAY,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;SACpD,GAAG,CAAC,KAAK,EAAC,YAAY,EAAC,EAAE;QACxB,MAAM,MAAM,GAAG,MAAM,WAAW,CAAC,uBAAuB,CAAC,YAAY,CAAC,CAAA;QACtE,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;YACf,OAAO,CAAC,IAAI,CACV,6CAA6C,YAAY,aAAa,MAAM,CAAC,MAAM,IAAI,KAAK,IAAI,CACjG,CAAA;QACH,CAAC;QACD,MAAM,OAAO,GAAG,MAAM,WAAW,CAAC,wBAAwB,CAAC,YAAY,CAAC,CAAA;QACxE,IAAI,CAAC,OAAO,CAAC,EAAE,EAAE,CAAC;YAChB,OAAO,CAAC,IAAI,CACV,+CAA+C,YAAY,aAAa,OAAO,CAAC,MAAM,IAAI,KAAK,IAAI,CACpG,CAAA;QACH,CAAC;IACH,CAAC,CAAC,CACL,CAAA;IAED,0EAA0E;IAC1E,8EAA8E;IAC9E,2EAA2E;IAC3E,4EAA4E;IAC5E,+CAA+C;IAC/C,MAAM,UAAU,GAAG,WAAW;SAC3B,MAAM,CAAC,UAAU,CAAC,EAAE,CAAC,UAAU,CAAC,UAAU,KAAK,QAAQ,CAAC;SACxD,GAAG,CAAC,UAAU,CAAC,EAAE,CAAC,UAAU,CAAC,EAAE,CAAC;SAChC,MAAM,CAAC,EAAE,CAAC,EAAE,CAAC,MAAM,CAAC,cAAc,CAAC,EAAE,CAAC,KAAK,SAAS,CAAC,CAAA;IACxD,MAAM,OAAO,GAAyC,EAAE,CAAA;IACxD,MAAM,OAAO,CAAC,GAAG,CACf,UAAU,CAAC,GAAG,CAAC,KAAK,EAAC,YAAY,EAAC,EAAE;QAClC,MAAM,UAAU,GACd,MAAM,WAAW,CAAC,wBAAwB,CAAC,YAAY,CAAC,CAAA;QAC1D,IAAI,UAAU,EAAE,CAAC;YACf,OAAO,CAAC,YAAY,CAAC,GAAG,UAAU,CAAA;YAClC,MAAM,UAAU,CAAC,iBAAiB,CAAC,EAAE,YAAY,EAAE,UAAU,EAAE,CAAC,CAAA;QAClE,CAAC;IACH,CAAC,CAAC,CACH,CAAA;IACD,+EAA+E;IAC/E,8EAA8E;IAC9E,UAAU,CAAC,iBAAiB,CAAC,YAAY,CAAC,EAAE,CAC1C,WAAW,CAAC,wBAAwB,CAAC,YAAY,CAAC,CACnD,CAAA;IACD,IAAI,gBAAgB,EAAE,CAAC;QACrB,MAAM,gBAAgB,CAAC,OAAO,CAAC,CAAA;IACjC,CAAC;IAED,4EAA4E;IAC5E,uEAAuE;IACvE,4EAA4E;IAC5E,sEAAsE;IACtE,0EAA0E;IAC1E,MAAM,aAAa,GAA2C,EAAE,CAAA;IAChE,KAAK,MAAM,EAAE,GAAG,EAAE,EAAE,EAAE,IAAI,iBAAiB,EAAE,CAAC;QAC5C,IAAI,CAAC,MAAM,CAAC,cAAc,CAAC,EAAE,CAAC,EAAE,CAAC;YAC/B,OAAO,CAAC,IAAI,CACV,+BAA+B,EAAE,uCAAuC,CACzE,CAAA;YACD,SAAQ;QACV,CAAC;QACD,IAAI,CAAC,YAAY,EAAE,CAAC;YAClB,OAAO,CAAC,IAAI,CACV,+BAA+B,EAAE,uCAAuC;gBACtE,8BAA8B,CACjC,CAAA;YACD,SAAQ;QACV,CAAC;QACD,IAAI,CAAC;YACH,aAAa,CAAC,GAAG,CAAC,GAAG,MAAM,sBAAsB,CAAC,IAAI,CAAC;gBACrD,WAAW;gBACX,eAAe,EAAE,YAAY,CAAC,eAAe;gBAC7C,WAAW,EAAE,YAAY,CAAC,WAAW;gBACrC,YAAY,EAAE,EAAE;aACjB,CAAC,CAAA;QACJ,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,CAAC,IAAI,CAAC,+BAA+B,EAAE,IAAI,EAAE,GAAG,CAAC,CAAA;QAC1D,CAAC;IACH,CAAC;IAED,MAAM,cAAc,CAAC,KAAK,CAAC;QACzB,WAAW;QACX,UAAU;QACV,cAAc;QACd,GAAG,CAAC,WAAW,IAAI,EAAE,WAAW,EAAE,CAAC;KACpC,CAAC,CAAA;IACF,OAAO,EAAE,WAAW,EAAE,iBAAiB,EAAE,aAAa,EAAE,CAAA;AAC1D,CAAC"}

package/dist/sync/docCipher.d.ts

@@ -71,8 +71,9 @@ export declare function createPlaintextDocCodec({ collectionId }: {
     collectionId: string;
 }): DocCipher;
 /**
- * Builds a {@link DocCipher} for one collection from its derived key material
- * (the per-collection X25519 key agreement key). Keys are supplied directly (no
+ * Builds a {@link DocCipher} for one collection from the caller's derived key
+ * material (the app's identity X25519 key agreement key, the same one every
+ * other collection uses). Keys are supplied directly (no
  * keystore lookup). `idDerivation: 'random'` mints a stable random id updated in
  * place via `sequence` -- the mutable head-document model every entity here uses
  * (constant bump / toggle / re-categorize edits).