@interop/was-client 0.22.0 → 0.24.0

package/dist/edv/recipients.d.ts

@@ -5,18 +5,18 @@
  * Recipient and key-epoch management for multi-recipient encrypted Collections:
  * initializing the first epoch, adding a reader (escrow -- history included),
  * and removing a reader (the full revoke-and-rotate procedure). Each operation
- * mutates a `CollectionEncryption` marker through the marker-store seam (see
- * `markerStore.ts`) -- the Collection Description's `encryption` member for the
- * `collection` sugar, or any explicit `store`, such as a marker hosted as a
- * plain JSON Resource -- and writes it back with a compare-and-swap
- * (`If-Match`), retrying on a concurrent change so two racing recipient edits
- * cannot clobber one another.
+ * mutates a `CollectionEncryption` descriptor through the descriptor-store seam
+ * (see `descriptorStore.ts`) -- the Collection Description's `encryption`
+ * member for the `collection` sugar, or any explicit `store`, such as a
+ * descriptor hosted as a plain JSON Resource -- and writes it back with a
+ * compare-and-swap (`If-Match`), retrying on a concurrent change so two racing
+ * recipient edits cannot clobber one another.
  *
  * The two axes stay separate and are both required to actually remove a reader:
  *
  * - **pull** -- the reader's server-side access. For a Collection this is the
  *   zcap the server checks at request time: revoking it stops the server
- *   serving that reader ciphertext. Immediate and total. A marker whose pull
+ *   serving that reader ciphertext. Immediate and total. A descriptor whose pull
  *   axis lives elsewhere (e.g. a DID document naming the readers) supplies a
  *   `pull` action instead of the default zcap revocation.
  * - **read** -- possession of an epoch key. Rotating the epoch means resources
@@ -33,7 +33,7 @@
 import type { IKeyAgreementKey } from '@interop/data-integrity-core';
 import type { Collection } from '../Collection.js';
 import type { Space } from '../Space.js';
-import type { MarkerStore } from './markerStore.js';
+import type { EncryptionDescriptorStore } from './descriptorStore.js';
 import type { CollectionEncryption, IDelegatedZcap } from '../types.js';
 import type { RecipientPublicKey } from './epochCrypto.js';
 export type { RecipientPublicKey } from './epochCrypto.js';
@@ -45,23 +45,24 @@ export interface OwnerKey {
     keyAgreementKey: IKeyAgreementKey;
 }
 /**
- * Initializes the first key epoch on a marker that has no epochs yet: mints a
- * fresh epoch key, wraps it to each initial recipient, and writes
- * `epochs: [epoch]` / `currentEpoch` back with a compare-and-swap. After this,
- * resources written by any recipient are encrypted under the epoch, and readers
- * unwrap it with their own key-agreement key.
+ * Initializes the first key epoch on a descriptor that has no epochs yet: mints
+ * a fresh epoch key, wraps it to each initial recipient, and writes `epochs:
+ * [epoch]` / `currentEpoch` back with a compare-and-swap. After this, resources
+ * written by any recipient are encrypted under the epoch, and readers unwrap it
+ * with their own key-agreement key.
  *
  * On the `collection` host the collection must already be declared encrypted
- * (its marker exists; this fills in the first epochs). On a store whose marker
- * host starts absent (e.g. `resourceMarkerStore`, whose roster resource does
- * not exist before the first init), the marker itself is created from scratch
- * with a create-if-absent guard (`If-None-Match: *`), so two racing first
- * inits cannot clobber one another.
+ * (its descriptor exists; this fills in the first epochs). On a store whose
+ * descriptor host starts absent (e.g. `resourceDescriptorStore`, whose roster
+ * resource does not exist before the first init), the descriptor itself is
+ * created from scratch with a create-if-absent guard (`If-None-Match: *`), so
+ * two racing first inits cannot clobber one another.
  *
  * @param options {object}
  * @param [options.collection] {Collection}   the (already encrypted) collection
- *   whose Description hosts the marker; exactly one of `collection` / `store`
- * @param [options.store] {MarkerStore}   an explicit marker store
+ *   whose Description hosts the descriptor; exactly one of `collection` /
+ *   `store`
+ * @param [options.store] {EncryptionDescriptorStore}   an explicit descriptor store
  * @param options.recipients {RecipientPublicKey[]}   the initial readers' public
  *   key-agreement keys (each `id` is the reader's `kid`)
  * @param [options.epoch] {{ epochId: string, secret: Uint8Array }}   a
@@ -69,11 +70,11 @@ export interface OwnerKey {
  *   whose epoch key already exists (e.g. a per-user key being enrolled into
  *   its wrap-set roster). The `epochId` must be the key's did:key and `secret`
  *   its raw 32-byte private key, exactly what {@link mintEpoch} returns.
- * @returns {Promise<CollectionEncryption>}   the new marker
+ * @returns {Promise<CollectionEncryption>}   the new descriptor
  */
 export declare function initRecipients({ collection, store, recipients, epoch: premintedEpoch }: {
     collection?: Collection;
-    store?: MarkerStore;
+    store?: EncryptionDescriptorStore;
     recipients: RecipientPublicKey[];
     epoch?: {
         epochId: string;
@@ -92,16 +93,16 @@ export declare function initRecipients({ collection, store, recipients, epoch: p
  *
  * @param options {object}
  * @param [options.collection] {Collection}   the collection whose Description
- *   hosts the marker; exactly one of `collection` / `store`
- * @param [options.store] {MarkerStore}   an explicit marker store
+ *   hosts the descriptor; exactly one of `collection` / `store`
+ * @param [options.store] {EncryptionDescriptorStore}   an explicit descriptor store
  * @param options.recipient {RecipientPublicKey}   the new reader's public KAK
  * @param options.owner {OwnerKey}   the caller's own key-agreement key, to
  *   unwrap each epoch key for re-wrapping to the new reader
- * @returns {Promise<CollectionEncryption>}   the new marker
+ * @returns {Promise<CollectionEncryption>}   the new descriptor
  */
 export declare function addRecipient({ collection, store, recipient, owner }: {
     collection?: Collection;
-    store?: MarkerStore;
+    store?: EncryptionDescriptorStore;
     recipient: RecipientPublicKey;
     owner: OwnerKey;
 }): Promise<CollectionEncryption>;
@@ -137,8 +138,8 @@ export declare function addRecipient({ collection, store, recipient, owner }: {
  *
  * @param options {object}
  * @param [options.collection] {Collection}   the collection whose Description
- *   hosts the marker; exactly one of `collection` / `store`
- * @param [options.store] {MarkerStore}   an explicit marker store
+ *   hosts the descriptor; exactly one of `collection` / `store`
+ * @param [options.store] {EncryptionDescriptorStore}   an explicit descriptor store
  * @param [options.space] {Space}   the collection's Space, for the default
  *   pull axis (zcap revocation); required together with `revoke` unless a
  *   custom `pull` is supplied
@@ -158,15 +159,76 @@ export declare function addRecipient({ collection, store, recipient, owner }: {
  *   self-describing `did:key`. May resolve `null` to signal drop-this-kid:
  *   the rotation then excludes that entry from the fresh epoch instead of
  *   throwing (subject to the no-recipients-remaining guard).
- * @returns {Promise<CollectionEncryption>}   the new marker
+ * @returns {Promise<CollectionEncryption>}   the new descriptor
  */
 export declare function removeRecipient({ collection, store, space, recipientId, revoke, pull, resolveRecipientKey }: {
     collection?: Collection;
-    store?: MarkerStore;
+    store?: EncryptionDescriptorStore;
     space?: Space;
     recipientId: string;
     revoke?: IDelegatedZcap | IDelegatedZcap[];
     pull?: () => Promise<void>;
     resolveRecipientKey?: (kid: string) => Promise<RecipientPublicKey | null>;
 }): Promise<CollectionEncryption>;
+/**
+ * Replaces one reader (or several) with another in ONE descriptor write -- the
+ * shape of a key rotation cascading over a collection (e.g. a per-user key
+ * replaced by its successor): the incoming recipient is escrowed into EVERY
+ * epoch (history included, {@link addRecipient}'s semantics) and the current
+ * epoch is rotated off the retiring recipient(s) ({@link removeRecipient}'s
+ * semantics), in a single compare-and-swap. Two requests total (the read and
+ * the CAS write) against the four a compose of addRecipient + removeRecipient
+ * would cost, and no intermediate state in which both keys are current.
+ *
+ * Idempotent to convergence like its two halves: an epoch already carrying the
+ * incoming recipient is left untouched; when additionally no retiring
+ * recipient remains in the current epoch, nothing is written at all -- a naive
+ * re-run after a crash appends zero redundant epochs. An escrow-only state
+ * (the incoming recipient missing from some epoch but no retiring recipient
+ * current) writes the escrow wraps without minting an epoch; the `epochsMac`
+ * is untouched then, since it binds the epoch configuration, not the
+ * recipient wraps.
+ *
+ * The pull-axis contract is {@link removeRecipient}'s verbatim: the default
+ * zcap revocation (`space` + `revoke`) or a caller-supplied `pull` action,
+ * run only after the rotation is durable. A caller whose pull axis has
+ * already run elsewhere (e.g. a DID-document edit under a current-key-set
+ * rule) passes a no-op `pull`.
+ *
+ * The rotation ceiling is unchanged: nothing is re-encrypted, so a retired
+ * key still opens every pre-rotation epoch it was a recipient of.
+ *
+ * @param options {object}
+ * @param [options.collection] {Collection}   the collection whose Description
+ *   hosts the descriptor; exactly one of `collection` / `store`
+ * @param [options.store] {EncryptionDescriptorStore}   an explicit descriptor store
+ * @param [options.space] {Space}   the default pull axis, with `revoke`
+ * @param options.retire {string | string[]}   the retiring recipient kid(s),
+ *   dropped from the fresh epoch's roster
+ * @param options.recipient {RecipientPublicKey}   the incoming reader's public
+ *   key-agreement key, escrowed into every epoch and wrapped into the fresh one
+ * @param options.owner {OwnerKey}   the caller's own key-agreement key,
+ *   unwrapping each epoch key for the escrow -- it must be a recipient of
+ *   every epoch (a retiring key that was escrowed everywhere qualifies)
+ * @param [options.revoke] {IDelegatedZcap | IDelegatedZcap[]}   the default
+ *   pull axis, with `space`
+ * @param [options.pull] {function}   a caller-supplied pull action; mutually
+ *   exclusive with `space` / `revoke`
+ * @param [options.resolveRecipientKey] {function}   resolves a remaining
+ *   recipient's kid for the fresh epoch, `null` to drop it -- the
+ *   {@link removeRecipient} contract (the incoming recipient never routes
+ *   through it)
+ * @returns {Promise<CollectionEncryption>}   the new descriptor
+ */
+export declare function replaceRecipient({ collection, store, space, retire, recipient, owner, revoke, pull, resolveRecipientKey }: {
+    collection?: Collection;
+    store?: EncryptionDescriptorStore;
+    space?: Space;
+    retire: string | string[];
+    recipient: RecipientPublicKey;
+    owner: OwnerKey;
+    revoke?: IDelegatedZcap | IDelegatedZcap[];
+    pull?: () => Promise<void>;
+    resolveRecipientKey?: (kid: string) => Promise<RecipientPublicKey | null>;
+}): Promise<CollectionEncryption>;
 //# sourceMappingURL=recipients.d.ts.map

package/dist/edv/recipients.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"recipients.d.ts","sourceRoot":"","sources":["../../src/edv/recipients.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAA;AACpE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAClD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAA;AAGxC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AACnD,OAAO,KAAK,EACV,oBAAoB,EAEpB,cAAc,EACf,MAAM,aAAa,CAAA;AAQpB,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAA;AAE1D,YAAY,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAA;AAE1D;;;GAGG;AACH,MAAM,WAAW,QAAQ;IACvB,eAAe,EAAE,gBAAgB,CAAA;CAClC;AAQD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAsB,cAAc,CAAC,EACnC,UAAU,EACV,KAAK,EACL,UAAU,EACV,KAAK,EAAE,cAAc,EACtB,EAAE;IACD,UAAU,CAAC,EAAE,UAAU,CAAA;IACvB,KAAK,CAAC,EAAE,WAAW,CAAA;IACnB,UAAU,EAAE,kBAAkB,EAAE,CAAA;IAChC,KAAK,CAAC,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,UAAU,CAAA;KAAE,CAAA;CAChD,GAAG,OAAO,CAAC,oBAAoB,CAAC,CA6ChC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,YAAY,CAAC,EACjC,UAAU,EACV,KAAK,EACL,SAAS,EACT,KAAK,EACN,EAAE;IACD,UAAU,CAAC,EAAE,UAAU,CAAA;IACvB,KAAK,CAAC,EAAE,WAAW,CAAA;IACnB,SAAS,EAAE,kBAAkB,CAAA;IAC7B,KAAK,EAAE,QAAQ,CAAA;CAChB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAuDhC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AACH,wBAAsB,eAAe,CAAC,EACpC,UAAU,EACV,KAAK,EACL,KAAK,EACL,WAAW,EACX,MAAM,EACN,IAAI,EACJ,mBAAgD,EACjD,EAAE;IACD,UAAU,CAAC,EAAE,UAAU,CAAA;IACvB,KAAK,CAAC,EAAE,WAAW,CAAA;IACnB,KAAK,CAAC,EAAE,KAAK,CAAA;IACb,WAAW,EAAE,MAAM,CAAA;IACnB,MAAM,CAAC,EAAE,cAAc,GAAG,cAAc,EAAE,CAAA;IAC1C,IAAI,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;IAC1B,mBAAmB,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CAAA;CAC1E,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAgGhC"}
+{"version":3,"file":"recipients.d.ts","sourceRoot":"","sources":["../../src/edv/recipients.ts"],"names":[],"mappings":"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"}