@interop/wallet-core 0.65.0 → 0.67.0

package/dist/keys/userKeyRosterCascade.d.ts

@@ -36,6 +36,20 @@
  * epoch names a non-current key generation -- so a mid-cascade crash strands
  * nothing permanently and a naive full re-run finishes it (the login-time
  * completion sweep is the standing backstop).
+ *
+ * The tail has two entry points over the same preamble and fan-out.
+ * `rotateRosterToDocumentAndCascade` is the document-converging one above,
+ * for a ceremony whose document edit has already landed.
+ * `retireRosterRecipientAndCascade` is the recipient-naming one: for a
+ * ceremony that must rotate BEFORE its own document edit -- the two forget
+ * ceremonies, where the forgetting client can sign nothing after its removal
+ * entry -- the document still lists the retiring recipient, so convergence
+ * would retire nothing, and the caller names the roster kid to retire
+ * instead. That entry point reads the fresh key back through a key the
+ * caller names (the standing credential's, whose wrap survives the rotation)
+ * and runs no seal backstop: with the document edit still ahead, there is no
+ * removal to seal against, and on the last-client transition the rotation
+ * itself is the one ladder-signed append its anchor licenses.
  */
 import type { DIDDoc, DIDLog } from '@interop/did-method-webvh';
 import type { IKeyAgreementKey } from '@interop/data-integrity-core';
@@ -68,8 +82,11 @@ export interface CascadeCollections {
     isEncrypted?: (collectionId: string) => Promise<boolean>;
 }
 /**
- * What the shared tail reports: whether the roster actually rotated on this
- * run (a re-run of an already-complete ceremony reports `false`), the roster's
+ * What the shared tail reports: whether the roster rotated on this run -- a
+ * re-run of an already-complete ceremony reports `false`; the
+ * document-converging entry point reads it off the adopting read, so a
+ * caller holding no cached key sees `true` on its first read either way,
+ * while the recipient-retiring one reports whether THIS call appended -- the roster's
  * seal-backstop report (present when the roster store is sealable and the
  * roster stage ran), the per-collection fan-out result, and the rotated key
  * with the roster descriptor it was read from.
@@ -81,6 +98,41 @@ export interface RosterCascadeResult {
     userKey?: UserKey;
     rosterDescriptor?: CollectionEncryption;
 }
+/**
+ * The post-edit anchoring guarantee, shared by both entry points: the roster
+ * appends -- and the seal backstop's removal detection -- must run under a
+ * controller view that includes the log the ceremony is anchoring at, or the
+ * rotation anchors before it (a revocation's rotation leaves the log
+ * unsealed with the seal blind to the removal; the last-client transition's
+ * ladder-signed rotation lands before its reinstall version and the
+ * ceremony-tail license refuses it). Rather than leaving that to the
+ * injected store's own controller wiring, the view built from the ceremony's
+ * log is set as the store's minimum controller version; a fresher resolved
+ * view still wins. A store that is not log-governed has no controller view
+ * to anchor and is left alone. Exported for the one caller that reads the
+ * roster before its anchoring entry exists (the last-client transition's
+ * pre-pair probe, anchored at the pre-transition head it verified).
+ *
+ * @param options {object}
+ * @param options.rosterStore {EncryptionDescriptorStore}
+ * @param options.did {string}
+ * @param options.log {DIDLog}
+ */
+export declare function anchorRosterStoreAt({ rosterStore, did, log }: {
+    rosterStore: EncryptionDescriptorStore;
+    did: string;
+    log: DIDLog;
+}): void;
+/**
+ * Persists a rotated key: called with `{ userKey, latestEpochId, descriptor }`
+ * after the roster read and BEFORE the fan-out. The key and the epoch pin
+ * must persist atomically.
+ */
+export type UserKeyAdoptedHook = (adopted: {
+    userKey: UserKey;
+    latestEpochId: string;
+    descriptor: CollectionEncryption;
+}) => Promise<void>;
 /**
  * Runs the roster rotation (with its seal backstop) and the collection
  * fan-out over the document a ceremony's own edit just published. See the
@@ -98,9 +150,8 @@ export interface RosterCascadeResult {
  *   (identity) key-agreement key -- its roster entry
  * @param [options.pinnedEpochId] {string}   the locally pinned latest-seen
  *   roster epoch
- * @param [options.onUserKeyAdopted] {Function}   persists a rotated key:
- *   called with `{ userKey, latestEpochId, descriptor }` after the roster read
- *   and BEFORE the fan-out. The key and the epoch pin must persist atomically
+ * @param [options.onUserKeyAdopted] {UserKeyAdoptedHook}   persists a
+ *   rotated key
  * @param options.collections {CascadeCollections}   the fan-out's work
  * @returns {Promise<RosterCascadeResult>}
  */
@@ -112,11 +163,60 @@ export declare function rotateRosterToDocumentAndCascade({ rosterStore, did, doc
     userKey?: UserKey;
     clientKeyAgreementKey: IKeyAgreementKey;
     pinnedEpochId?: string | null;
-    onUserKeyAdopted?: (adopted: {
-        userKey: UserKey;
-        latestEpochId: string;
-        descriptor: CollectionEncryption;
-    }) => Promise<void>;
+    onUserKeyAdopted?: UserKeyAdoptedHook;
+    collections: CascadeCollections;
+}): Promise<RosterCascadeResult>;
+/**
+ * The recipient-naming entry point: retires ONE named roster recipient and
+ * runs the collection fan-out, for a ceremony that rotates BEFORE its own
+ * document edit (see the module doc). The document handed in still keys the
+ * retiring recipient, so the rotation names its kid explicitly; the fresh key
+ * is read back through `readBackKeyAgreementKey`, a recipient whose wrap
+ * survives the rotation (the standing credential's, on both forgets). No
+ * seal backstop runs here.
+ *
+ * Every stage detects its own completion from durable state: a recipient the
+ * current epoch no longer wraps to skips the append (so a re-run of a
+ * torn-after-rotation ceremony attempts no second append at the same anchor,
+ * which on a ladder-signed roster the one-shot license would refuse), the
+ * read-back adopts whatever the roster now delivers, and the fan-out is
+ * staleness-driven. An account with no roster yet reports `rotated: false`
+ * with an empty fan-out and no key.
+ *
+ * @param options {object}
+ * @param options.rosterStore {EncryptionDescriptorStore}   the
+ *   `key-map/user-key.jsonl` roster store
+ * @param options.did {string}   the account's did:webvh
+ * @param options.doc {DIDDoc}   the document the rotation's recipients are
+ *   resolved from -- the one `log` resolves to
+ * @param options.log {DIDLog}   the log the rotation anchors at, which the
+ *   minimum controller version is built from: the pre-edit head for a plain
+ *   forget, the post-reinstall head for the last-client transition
+ * @param options.retireRecipientId {string}   the roster kid to retire
+ * @param [options.userKey] {UserKey}   this client's cached user key
+ * @param options.readBackKeyAgreementKey {IKeyAgreementKey}   the recipient
+ *   whose wrap survives the rotation, reading the fresh key back and
+ *   unwrapping the generations for the fan-out
+ * @param [options.pinnedEpochId] {string}   the locally pinned latest-seen
+ *   roster epoch
+ * @param [options.onUserKeyAdopted] {UserKeyAdoptedHook}   persists a
+ *   rotated key
+ * @param options.collections {CascadeCollections}   the fan-out's work
+ * @returns {Promise<RosterCascadeResult>}   `rotated` says whether THIS run
+ *   retired the recipient's wrap; `rosterSeal` is never present
+ * @throws {UserKeyRosterIntegrityError}   the roster's `currentEpoch` names
+ *   no epoch in its own list
+ */
+export declare function retireRosterRecipientAndCascade({ rosterStore, did, doc, log, retireRecipientId, userKey, readBackKeyAgreementKey, pinnedEpochId, onUserKeyAdopted, collections }: {
+    rosterStore: EncryptionDescriptorStore;
+    did: string;
+    doc: DIDDoc;
+    log: DIDLog;
+    retireRecipientId: string;
+    userKey?: UserKey;
+    readBackKeyAgreementKey: IKeyAgreementKey;
+    pinnedEpochId?: string | null;
+    onUserKeyAdopted?: UserKeyAdoptedHook;
     collections: CascadeCollections;
 }): Promise<RosterCascadeResult>;
 //# sourceMappingURL=userKeyRosterCascade.d.ts.map

package/dist/keys/userKeyRosterCascade.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"userKeyRosterCascade.d.ts","sourceRoot":"","sources":["../../src/keys/userKeyRosterCascade.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,2BAA2B,CAAA;AAC/D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAA;AACpE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAA;AAC/D,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,yBAAyB,CAAA;AAExE,OAAO,EAEL,KAAK,oBAAoB,EAC1B,MAAM,qBAAqB,CAAA;AAM5B,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAE3C;;;;;;;GAOG;AACH,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,QAAQ,GAAG,MAAM,GAAG,QAAQ,CAAA;IACrC,KAAK,CAAC,EAAE,OAAO,CAAA;CAChB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IACjC,aAAa,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,CAAA;IACnD,QAAQ,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,yBAAyB,CAAA;IAC7D,WAAW,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;CACzD;AAED;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,OAAO,CAAA;IAChB,UAAU,CAAC,EAAE,gBAAgB,CAAA;IAC7B,WAAW,EAAE,oBAAoB,CAAA;IACjC,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,gBAAgB,CAAC,EAAE,oBAAoB,CAAA;CACxC;AAqBD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,gCAAgC,CAAC,EACrD,WAAW,EACX,GAAG,EACH,GAAG,EACH,GAAG,EACH,OAAO,EACP,qBAAqB,EACrB,aAAa,EACb,gBAAgB,EAChB,WAAW,EACZ,EAAE;IACD,WAAW,EAAE,yBAAyB,CAAA;IACtC,GAAG,EAAE,MAAM,CAAA;IACX,GAAG,EAAE,MAAM,CAAA;IACX,GAAG,EAAE,MAAM,CAAA;IACX,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,qBAAqB,EAAE,gBAAgB,CAAA;IACvC,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC7B,gBAAgB,CAAC,EAAE,CAAC,OAAO,EAAE;QAC3B,OAAO,EAAE,OAAO,CAAA;QAChB,aAAa,EAAE,MAAM,CAAA;QACrB,UAAU,EAAE,oBAAoB,CAAA;KACjC,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IACnB,WAAW,EAAE,kBAAkB,CAAA;CAChC,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAsF/B"}
+{"version":3,"file":"userKeyRosterCascade.d.ts","sourceRoot":"","sources":["../../src/keys/userKeyRosterCascade.ts"],"names":[],"mappings":"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"}

package/dist/keys/userKeyRosterCascade.js

@@ -1,7 +1,7 @@
 import { webvhResourceLogController } from '../resourceLog/index.js';
 import { cascadeCollectionsToUserKey } from './userKeyCascade.js';
 import { isSealableDescriptorStore } from './rosterLogStore.js';
-import { convergeUserKeyRosterToDocument, readUserKeyRoster } from './userKeyRoster.js';
+import { convergeUserKeyRosterToDocument, readUserKeyRoster, rosterWrapsRecipient, rotateUserKeyRoster } from './userKeyRoster.js';
 /**
  * Resolves the collection ids the fan-out covers, whether they are a fixed set
  * or a listing the app performs.
@@ -16,6 +16,94 @@ async function collectionIdsOf({ collections }) {
         ? await collectionIds()
         : collectionIds;
 }
+/**
+ * The post-edit anchoring guarantee, shared by both entry points: the roster
+ * appends -- and the seal backstop's removal detection -- must run under a
+ * controller view that includes the log the ceremony is anchoring at, or the
+ * rotation anchors before it (a revocation's rotation leaves the log
+ * unsealed with the seal blind to the removal; the last-client transition's
+ * ladder-signed rotation lands before its reinstall version and the
+ * ceremony-tail license refuses it). Rather than leaving that to the
+ * injected store's own controller wiring, the view built from the ceremony's
+ * log is set as the store's minimum controller version; a fresher resolved
+ * view still wins. A store that is not log-governed has no controller view
+ * to anchor and is left alone. Exported for the one caller that reads the
+ * roster before its anchoring entry exists (the last-client transition's
+ * pre-pair probe, anchored at the pre-transition head it verified).
+ *
+ * @param options {object}
+ * @param options.rosterStore {EncryptionDescriptorStore}
+ * @param options.did {string}
+ * @param options.log {DIDLog}
+ */
+export function anchorRosterStoreAt({ rosterStore, did, log }) {
+    if (isSealableDescriptorStore(rosterStore)) {
+        rosterStore.setMinimumControllerVersion({
+            controller: webvhResourceLogController({ did, log })
+        });
+    }
+}
+/**
+ * The adopting read after a rotation: the roster read on the threaded
+ * descriptor (the continuity and possession checks still run on it), then
+ * the caller's `onUserKeyAdopted` when the key rotated on this run.
+ *
+ * @param options {object}
+ * @param options.rosterStore {EncryptionDescriptorStore}
+ * @param options.descriptor {CollectionEncryption}   the rotation's own
+ *   verified result, so one run acquires the roster once for both halves
+ * @param [options.userKey] {UserKey}
+ * @param options.readBackKeyAgreementKey {IKeyAgreementKey}
+ * @param [options.pinnedEpochId] {string}
+ * @param [options.onUserKeyAdopted] {Function}
+ * @returns {Promise<object>}
+ */
+async function adoptRotatedUserKey({ rosterStore, descriptor, userKey, readBackKeyAgreementKey, pinnedEpochId, onUserKeyAdopted }) {
+    const read = await readUserKeyRoster({
+        store: rosterStore,
+        descriptor,
+        ...(userKey ? { userKey } : {}),
+        clientKeyAgreementKey: readBackKeyAgreementKey,
+        pinnedEpochId
+    });
+    if (read.rotated) {
+        await onUserKeyAdopted?.({
+            userKey: read.userKey,
+            latestEpochId: read.latestEpochId,
+            descriptor: read.descriptor
+        });
+    }
+    return {
+        rotated: read.rotated,
+        userKey: read.userKey,
+        descriptor: read.descriptor
+    };
+}
+/**
+ * The collection fan-out, in parallel -- run even when the roster was found
+ * already rotated (a re-run after a crash), because the staleness rule finds
+ * exactly the stranded collections.
+ *
+ * @param options {object}
+ * @param options.collections {CascadeCollections}
+ * @param options.rosterDescriptor {CollectionEncryption}
+ * @param options.clientKeyAgreementKey {IKeyAgreementKey}   the key that
+ *   unwraps the roster's generations for the per-collection re-epoch
+ * @param options.userKey {UserKey}
+ * @returns {Promise<UserKeyCascadeResult>}
+ */
+async function fanOutToCollections({ collections, rosterDescriptor, clientKeyAgreementKey, userKey }) {
+    return cascadeCollectionsToUserKey({
+        collectionIds: await collectionIdsOf({ collections }),
+        storeFor: collections.storeFor,
+        ...(collections.isEncrypted
+            ? { isEncrypted: collections.isEncrypted }
+            : {}),
+        rosterDescriptor,
+        clientKeyAgreementKey,
+        userKey
+    });
+}
 /**
  * Runs the roster rotation (with its seal backstop) and the collection
  * fan-out over the document a ceremony's own edit just published. See the
@@ -33,25 +121,13 @@ async function collectionIdsOf({ collections }) {
  *   (identity) key-agreement key -- its roster entry
  * @param [options.pinnedEpochId] {string}   the locally pinned latest-seen
  *   roster epoch
- * @param [options.onUserKeyAdopted] {Function}   persists a rotated key:
- *   called with `{ userKey, latestEpochId, descriptor }` after the roster read
- *   and BEFORE the fan-out. The key and the epoch pin must persist atomically
+ * @param [options.onUserKeyAdopted] {UserKeyAdoptedHook}   persists a
+ *   rotated key
  * @param options.collections {CascadeCollections}   the fan-out's work
  * @returns {Promise<RosterCascadeResult>}
  */
 export async function rotateRosterToDocumentAndCascade({ rosterStore, did, doc, log, userKey, clientKeyAgreementKey, pinnedEpochId, onUserKeyAdopted, collections }) {
-    // The post-edit anchoring guarantee: the roster appends -- and the seal
-    // backstop's removal detection -- must run under a controller view that
-    // includes the edit the ceremony just published, or the rotation anchors
-    // pre-edit and the log stays unsealed with the seal blind to the removal.
-    // Rather than leaving that to the injected store's own controller wiring,
-    // the view built from the edit's post-edit log is set as the store's minimum
-    // controller version; a fresher resolved view still wins.
-    if (isSealableDescriptorStore(rosterStore)) {
-        rosterStore.setMinimumControllerVersion({
-            controller: webvhResourceLogController({ did, log })
-        });
-    }
+    anchorRosterStoreAt({ rosterStore, did, log });
     // The roster rotation, recipients resolved from that same document.
     // Whether there IS a roster is settled BY the convergence call itself: a
     // `null` descriptor back means the account has no `key-map/user-key.jsonl`
@@ -70,23 +146,14 @@ export async function rotateRosterToDocumentAndCascade({ rosterStore, did, doc,
     if (converged.descriptor === null) {
         return { rotated: false, collections: { outcomes: {}, failed: [] } };
     }
-    // The rotation's own verified result is threaded into the adopting read, so
-    // one run acquires the roster once for both halves of the stage (the
-    // continuity and possession checks still run on the threaded descriptor).
-    const read = await readUserKeyRoster({
-        store: rosterStore,
+    const read = await adoptRotatedUserKey({
+        rosterStore,
         descriptor: converged.descriptor,
-        ...(userKey ? { userKey } : {}),
-        clientKeyAgreementKey,
-        pinnedEpochId
+        userKey,
+        readBackKeyAgreementKey: clientKeyAgreementKey,
+        pinnedEpochId,
+        onUserKeyAdopted
     });
-    if (read.rotated) {
-        await onUserKeyAdopted?.({
-            userKey: read.userKey,
-            latestEpochId: read.latestEpochId,
-            descriptor: read.descriptor
-        });
-    }
     // The seal backstop: an ordinary rotation is the sealing append by
     // construction, but a rotation that no-op'd (the removed party held no
     // current-epoch wrap -- an orphan entry, or any re-run) appended nothing,
@@ -102,15 +169,8 @@ export async function rotateRosterToDocumentAndCascade({ rosterStore, did, doc,
             rosterSeal = { outcome: 'failed', error: err };
         }
     }
-    // The collection fan-out, in parallel -- run even when this call found the
-    // roster already rotated (a re-run after a crash), because the staleness
-    // rule finds exactly the stranded collections.
-    const cascade = await cascadeCollectionsToUserKey({
-        collectionIds: await collectionIdsOf({ collections }),
-        storeFor: collections.storeFor,
-        ...(collections.isEncrypted
-            ? { isEncrypted: collections.isEncrypted }
-            : {}),
+    const cascade = await fanOutToCollections({
+        collections,
         rosterDescriptor: read.descriptor,
         clientKeyAgreementKey,
         userKey: read.userKey
@@ -123,4 +183,88 @@ export async function rotateRosterToDocumentAndCascade({ rosterStore, did, doc,
         rosterDescriptor: read.descriptor
     };
 }
+/**
+ * The recipient-naming entry point: retires ONE named roster recipient and
+ * runs the collection fan-out, for a ceremony that rotates BEFORE its own
+ * document edit (see the module doc). The document handed in still keys the
+ * retiring recipient, so the rotation names its kid explicitly; the fresh key
+ * is read back through `readBackKeyAgreementKey`, a recipient whose wrap
+ * survives the rotation (the standing credential's, on both forgets). No
+ * seal backstop runs here.
+ *
+ * Every stage detects its own completion from durable state: a recipient the
+ * current epoch no longer wraps to skips the append (so a re-run of a
+ * torn-after-rotation ceremony attempts no second append at the same anchor,
+ * which on a ladder-signed roster the one-shot license would refuse), the
+ * read-back adopts whatever the roster now delivers, and the fan-out is
+ * staleness-driven. An account with no roster yet reports `rotated: false`
+ * with an empty fan-out and no key.
+ *
+ * @param options {object}
+ * @param options.rosterStore {EncryptionDescriptorStore}   the
+ *   `key-map/user-key.jsonl` roster store
+ * @param options.did {string}   the account's did:webvh
+ * @param options.doc {DIDDoc}   the document the rotation's recipients are
+ *   resolved from -- the one `log` resolves to
+ * @param options.log {DIDLog}   the log the rotation anchors at, which the
+ *   minimum controller version is built from: the pre-edit head for a plain
+ *   forget, the post-reinstall head for the last-client transition
+ * @param options.retireRecipientId {string}   the roster kid to retire
+ * @param [options.userKey] {UserKey}   this client's cached user key
+ * @param options.readBackKeyAgreementKey {IKeyAgreementKey}   the recipient
+ *   whose wrap survives the rotation, reading the fresh key back and
+ *   unwrapping the generations for the fan-out
+ * @param [options.pinnedEpochId] {string}   the locally pinned latest-seen
+ *   roster epoch
+ * @param [options.onUserKeyAdopted] {UserKeyAdoptedHook}   persists a
+ *   rotated key
+ * @param options.collections {CascadeCollections}   the fan-out's work
+ * @returns {Promise<RosterCascadeResult>}   `rotated` says whether THIS run
+ *   retired the recipient's wrap; `rosterSeal` is never present
+ * @throws {UserKeyRosterIntegrityError}   the roster's `currentEpoch` names
+ *   no epoch in its own list
+ */
+export async function retireRosterRecipientAndCascade({ rosterStore, did, doc, log, retireRecipientId, userKey, readBackKeyAgreementKey, pinnedEpochId, onUserKeyAdopted, collections }) {
+    anchorRosterStoreAt({ rosterStore, did, log });
+    const current = await rosterStore.read();
+    if (current === null) {
+        return { rotated: false, collections: { outcomes: {}, failed: [] } };
+    }
+    let descriptor = current.descriptor;
+    let rotated = false;
+    if (rosterWrapsRecipient({ descriptor, recipientId: retireRecipientId })) {
+        // Seeded from the read above, so the roster is acquired once: the
+        // rotation's verified head, its license check, and its minimum-controller
+        // anchoring all run over that one read.
+        descriptor = await rotateUserKeyRoster({
+            store: rosterStore,
+            document: doc,
+            retireRecipientId,
+            current
+        });
+        rotated = true;
+    }
+    // The fresh key comes back through the surviving recipient's wrap -- the
+    // retired one is gone from the current epoch.
+    const read = await adoptRotatedUserKey({
+        rosterStore,
+        descriptor,
+        userKey,
+        readBackKeyAgreementKey,
+        pinnedEpochId,
+        onUserKeyAdopted
+    });
+    const cascade = await fanOutToCollections({
+        collections,
+        rosterDescriptor: read.descriptor,
+        clientKeyAgreementKey: readBackKeyAgreementKey,
+        userKey: read.userKey
+    });
+    return {
+        rotated,
+        collections: cascade,
+        userKey: read.userKey,
+        rosterDescriptor: read.descriptor
+    };
+}
 //# sourceMappingURL=userKeyRosterCascade.js.map

package/dist/keys/userKeyRosterCascade.js.map

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