@interop/wallet-core 0.101.1 → 0.104.0

package/dist/connections/upsert.js

@@ -1,12 +1,33 @@
 /*!
  * Copyright (c) 2026 Interop Alliance. All rights reserved.
  */
+/**
+ * A capability to record, read by the codec, or a `TypeError` naming the
+ * write when it lacks an id, a controller, or an invocation target.
+ *
+ * @param options {object}
+ * @param options.value {object}
+ * @param options.what {string}   the write's name, for the message
+ * @returns {ConnectionZcap}
+ */
+function requiredConnectionZcap({ value, what }) {
+    const zcap = parseConnectionZcap(value);
+    if (zcap === undefined) {
+        throw new TypeError(`A ${what} must carry a capability with an id, a controller, and an ` +
+            'invocation target.');
+    }
+    return zcap;
+}
 /**
  * The upsert helpers every flow writes a party's entry through:
  * `recordGrants` at consent, `removeGrants` at an unshare or a torn
  * consent's rollback, `retireConnection` when a relationship ends,
- * `unretireConnection` when one resumes without a consent, and
- * `setConnectionLabel` for the user's rename and the enrollment-time name.
+ * `unretireConnection` when one resumes without a consent,
+ * `setConnectionLabel` for the user's rename and the enrollment-time name,
+ * and the agent-connection helpers over `grantsReceived` and `outbox`:
+ * `recordReceivedGrants`, `recordRenewedGrants` (the renewal's one write),
+ * `settleOutboxItem`, `pruneSupersededGrants`, `dropReceivedGrant`,
+ * `clearReceivedGrants`, and `markDeclined`.
  *
  * Each runs `writeConnection`, the one bounded compare-and-swap loop at a
  * party's resource id, which the writer arm (`writers.ts`) runs too. It reads
@@ -22,15 +43,18 @@
  */
 import { NotSupportedError } from '@interop/was-client';
 import { errorNameOf } from '../errorName.js';
+import { isJsonObject } from '../jsonObject.js';
 import { normalizeDisplayName } from '../labelText.js';
+import { REVOCATION_CLOCK_SKEW_MS } from '../webvh/index.js';
 import { signingKeyMultibaseOfDid } from './didKey.js';
-import { CONNECTION_ENTRY_VERSION, GRANT_KINDS, isWritableConnectionEntry, newConnectionEntry, parseConnectionEntry, parseConnectionZcap } from './entry.js';
+import { CONNECTION_ENTRY_VERSION, GRANT_KINDS, RECEIVED_GRANT_KINDS, isWritableConnectionEntry, newConnectionEntry, parseConnectionEntry, parseConnectionZcap } from './entry.js';
 import { ConnectionKindMismatchError } from './errors.js';
-import { connectionGrants, isTargetInSpace } from './grants.js';
+import { allowsAction, connectionGrants, grantScopeKey, latestIndexPerScope, isTargetInSpace, liveInboxChannel, receivedGrantLapsed, receivedGrants } from './grants.js';
 import { claimedResourceId } from './read.js';
-import { connectionResourceId } from './resourceId.js';
+import { connectionResourceId, verifyConnectionSeedTag } from './resourceId.js';
 const PRECONDITION_FAILED_ERROR_NAME = 'PreconditionFailedError';
 const WRITE_ATTEMPTS = 3;
+const STRICT_ISO_8601 = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$/;
 /**
  * Whether a store write lost a race. Matched by name, since the store is an
  * injected seam that may raise from a second copy of was-client.
@@ -188,24 +212,19 @@ function assertKind({ entry, kind }) {
     }
 }
 /**
- * The capability of one grant to record, checked strictly: its known members
- * well-formed, its `controller` the party's DID, its `invocationTarget` under
- * this Space, its kind one this build writes. The target check is the same
- * one every reader applies, so a grant that is stored is a grant the
- * revocation index will see.
+ * A capability the wallet delegated, checked strictly: its known members
+ * well-formed, its `controller` the party's DID, its `invocationTarget`
+ * under this Space. The target check is the same one every reader applies,
+ * so a grant that is stored is a grant the revocation index will see.
  *
  * @param options {object}
  * @param options.did {string}
  * @param options.spaceUrl {string}
- * @param options.grant {object}
+ * @param options.zcap {object}
  * @returns {ConnectionZcap}
  */
-function checkedGrant({ did, spaceUrl, grant }) {
-    const zcap = parseConnectionZcap(grant.zcap);
-    if (zcap === undefined) {
-        throw new TypeError('A grant to record must carry a capability with an id, a controller, ' +
-            'and an invocation target.');
-    }
+function checkedDelegatedZcap({ did, spaceUrl, zcap: value }) {
+    const zcap = requiredConnectionZcap({ value, what: 'grant to record' });
     if (zcap.controller !== did) {
         throw new TypeError(`A grant to record must be delegated to the party "${did}"; its ` +
             `controller is "${zcap.controller}".`);
@@ -214,19 +233,189 @@ function checkedGrant({ did, spaceUrl, grant }) {
         throw new TypeError('A grant to record must target this Space; its invocation target is ' +
             `"${zcap.invocationTarget}".`);
     }
+    return zcap;
+}
+/**
+ * The capability of one grant to record: {@link checkedDelegatedZcap}, and
+ * its kind one this build writes.
+ *
+ * @param options {object}
+ * @param options.did {string}
+ * @param options.spaceUrl {string}
+ * @param options.grant {object}
+ * @returns {ConnectionZcap}
+ */
+function checkedGrant({ did, spaceUrl, grant }) {
+    const zcap = checkedDelegatedZcap({ did, spaceUrl, zcap: grant.zcap });
     if (!GRANT_KINDS.includes(grant.grantKind)) {
         throw new TypeError(`Unknown grant kind "${grant.grantKind}".`);
     }
     return zcap;
 }
+/**
+ * A capability's `expires` as epoch milliseconds. The codec has already
+ * checked the member is present and parses.
+ *
+ * @param zcap {ConnectionZcap}
+ * @returns {number}
+ */
+function expiresAtOf(zcap) {
+    return Date.parse(zcap.expires);
+}
+/**
+ * Whether a capability's `expires` is past by more than the revocation clock
+ * skew.
+ *
+ * @param options {object}
+ * @param options.zcap {ConnectionZcap}
+ * @param options.now {Date}
+ * @returns {boolean}
+ */
+function expiredBeyondSkew({ zcap, now }) {
+    return expiresAtOf(zcap) + REVOCATION_CLOCK_SKEW_MS <= now.getTime();
+}
+/**
+ * The index of the latest record in each scope of a list of grant records
+ * ({@link latestIndexPerScope} over their capabilities).
+ *
+ * @param options {object}
+ * @param options.grants {ConnectionGrantRecord[]}
+ * @returns {Map<string, number>}   scope key to the latest record's index
+ */
+function latestPerScope({ grants }) {
+    return latestIndexPerScope({ zcaps: grants.map(grant => grant.zcap) });
+}
+/**
+ * The capabilities an envelope carries (`message.object.zcaps`), or
+ * `undefined` when it carries no such list.
+ *
+ * @param message {object}   the envelope, verbatim
+ * @returns {unknown[] | undefined}
+ */
+function envelopeZcaps(message) {
+    const { object } = message;
+    if (!isJsonObject(object) || !Array.isArray(object.zcaps)) {
+        return undefined;
+    }
+    return object.zcaps;
+}
+/**
+ * Checks an envelope a write queues beside the records it carries: its
+ * `object.zcaps` must be a non-empty list whose zcap ids are exactly
+ * `zcapIds`, so a reused message cannot queue a capability the write does
+ * not record. Refuses with a `TypeError`.
+ *
+ * @param options {object}
+ * @param options.message {object}   the envelope, verbatim
+ * @param options.zcapIds {Iterable<string>}   the ids the write records
+ * @param options.what {string}   the write's name, for the message
+ */
+function assertEnvelopeCarries({ message, zcapIds, what }) {
+    const zcaps = envelopeZcaps(message);
+    if (zcaps === undefined || zcaps.length === 0) {
+        throw new TypeError(`A ${what} message must carry a non-empty \`object.zcaps\` list.`);
+    }
+    const messageIds = new Set(zcaps.map(value => parseConnectionZcap(value)?.id));
+    const recordedIds = new Set(zcapIds);
+    if (messageIds.size !== recordedIds.size ||
+        [...messageIds].some(id => id === undefined || !recordedIds.has(id))) {
+        throw new TypeError(`A ${what} message's zcaps must be exactly the recorded zcaps.`);
+    }
+}
+/**
+ * Refuses a `seed` without its `seedTag` (or the reverse) and a tag that does
+ * not verify under `hmacKey` with a `TypeError`, before anything is read.
+ * A write carrying neither passes.
+ *
+ * @param options {object}
+ * @param options.hmacKey {ConnectionIdKey}
+ * @param [options.seed] {string}
+ * @param [options.seedTag] {string}
+ * @returns {Promise<void>}
+ */
+async function assertPairwiseSeed({ hmacKey, seed, seedTag }) {
+    if (seed === undefined && seedTag === undefined) {
+        return;
+    }
+    if (seed === undefined || seedTag === undefined) {
+        throw new TypeError('A connection seed is written with its tag, or not.');
+    }
+    if (!(await verifyConnectionSeedTag({ hmacKey, seed, seedTag }))) {
+        throw new TypeError("The connection seed's tag does not verify under this directory's key.");
+    }
+}
+/**
+ * The outbox after queueing `message`: the pending items with every zcap
+ * `supersedes` admits removed from their envelopes (an envelope left with
+ * none is dropped), then the new envelope stamped `createdAt: stamp`. A
+ * zcap the codec cannot parse is kept.
+ *
+ * @param options {object}
+ * @param options.outbox {Array<ConnectionOutboxItem>}   the pending items
+ * @param options.message {object}   the envelope to queue, verbatim
+ * @param options.stamp {string}   the queueing time, ISO 8601 UTC
+ * @param options.supersedes {Function}   whether the new envelope supersedes
+ *   a pending zcap
+ * @returns {Array<ConnectionOutboxItem>}
+ */
+function supersedeAndQueueEnvelope({ outbox, message, stamp, supersedes }) {
+    const queued = [];
+    for (const item of outbox) {
+        const zcaps = envelopeZcaps(item.message);
+        if (zcaps === undefined) {
+            queued.push(item);
+            continue;
+        }
+        const kept = zcaps.filter(value => {
+            const zcap = parseConnectionZcap(value);
+            return zcap === undefined || !supersedes(zcap);
+        });
+        if (kept.length === zcaps.length) {
+            queued.push(item);
+        }
+        else if (kept.length > 0) {
+            const itemObject = item.message.object;
+            queued.push({
+                ...item,
+                message: { ...item.message, object: { ...itemObject, zcaps: kept } }
+            });
+        }
+    }
+    queued.push({ message, createdAt: stamp });
+    return queued;
+}
 /**
  * Records a consent on the party's entry: creates the entry, or merges into
  * it. Each new grant is added by its capability id (one already recorded is
  * left as stored), `name` is set when it passes the display-name rule (left
  * as it was otherwise), `origin`, `url`, and `appKey` are set when given,
- * `retired` is cleared, and `lastSeen` moves to `now`. `firstSeen` is set
- * only on create, and `label` is never touched. A zero-grant consent writes
- * too, so an App Connect app with no grants is indexed by its key.
+ * `retired` and `declined` are cleared, and `lastSeen` moves to `now`.
+ * `firstSeen` is set only on create, and `label` is never touched. Every
+ * grant of one call carries the same `grantedAt`. A zero-grant consent
+ * writes too, so an App Connect app with no grants is indexed by its key.
+ *
+ * With `unlessRetired`, a retired entry is left as stored and the result's
+ * outcome is `unchanged`. A party's own fresh consent un-retires its entry,
+ * and a restore the owner runs from a listing does not: the entry was
+ * retired by a revoke that landed after that listing was read, and the
+ * restore must not undo it. The check runs inside the compare-and-swap, so
+ * a revoke racing the write is met on the re-read.
+ *
+ * A `message` (an envelope carrying exactly the grants of this call) is
+ * queued on `outbox` in the same write, stamped `now`, so a restore that
+ * records fresh grants and owes the party their envelope has no tear between
+ * the two. Each zcap of this call is first removed from every pending
+ * envelope that carries it (an envelope left with none is dropped), so no
+ * two pending envelopes name one zcap id. A consent torn after its write
+ * lands and re-run therefore leaves one pending envelope, the re-run's, and
+ * a grant recorded earlier with no envelope is told on the first call that
+ * brings one.
+ *
+ * A `seed` and its `seedTag` (both or neither) are written when the entry
+ * carries no seed, and left as stored when it carries the same one. An entry
+ * carrying a different seed is refused with an `Error`, since the seed is
+ * written once. A tag that does not verify under `hmacKey` is refused with a
+ * `TypeError` before anything is read.
  *
  * Refuses an entry of another kind with {@link ConnectionKindMismatchError},
  * and a grant delegated to another party or targeting another Space with a
@@ -246,10 +435,18 @@ function checkedGrant({ did, spaceUrl, grant }) {
  * @param [options.origin] {string}   the attested Web origin (App Connect)
  * @param [options.url] {string}   the canonical app URL (App Connect)
  * @param [options.appKey] {string}   the app-key Resource id (App Connect)
+ * @param [options.seed] {string}   the wallet's pairwise seed toward the
+ *   party, base64url with no padding
+ * @param [options.seedTag] {string}   the seed's tag (`connectionSeedTag`)
+ * @param [options.message] {object}   an envelope to queue on `outbox` with
+ *   the consent, carrying exactly the grants of this call
+ * @param [options.unlessRetired] {boolean}   leave a retired entry as
+ *   stored, with the outcome `unchanged`
  * @param [options.now] {Date}
  * @returns {Promise<ConnectionWriteResult>}
  */
-export async function recordGrants({ store, hmacKey, did, kind, spaceUrl, grants, name, origin, url, appKey, now = new Date() }) {
+export async function recordGrants({ store, hmacKey, did, kind, spaceUrl, grants, name, origin, url, appKey, seed, seedTag, message, unlessRetired, now = new Date() }) {
+    await assertPairwiseSeed({ hmacKey, seed, seedTag });
     const stamp = now.toISOString();
     const recorded = [];
     const seen = new Set();
@@ -264,6 +461,13 @@ export async function recordGrants({ store, hmacKey, did, kind, spaceUrl, grants
             recorded.push({ zcap, grantKind: grant.grantKind, grantedAt: stamp });
         }
     }
+    if (message !== undefined) {
+        assertEnvelopeCarries({
+            message,
+            zcapIds: recorded.map(grant => grant.zcap.id),
+            what: 'consent'
+        });
+    }
     const normalizedName = name === undefined ? undefined : normalizeDisplayName({ value: name });
     const declared = {
         ...(normalizedName !== undefined && { name: normalizedName }),
@@ -276,27 +480,51 @@ export async function recordGrants({ store, hmacKey, did, kind, spaceUrl, grants
         hmacKey,
         did,
         change(current) {
+            const stored = current?.entry;
+            const held = new Set(stored?.grants.map(grant => grant.zcap.id));
+            let body;
             if (current === undefined) {
-                return {
-                    body: {
-                        ...newConnectionEntry({ kind, did, now }),
-                        ...declared,
-                        grants: recorded
-                    }
+                body = {
+                    ...newConnectionEntry({ kind, did, now }),
+                    ...declared,
+                    grants: recorded
+                };
+            }
+            else {
+                assertKind({ entry: current.entry, kind });
+                if (unlessRetired && current.entry.retired !== undefined) {
+                    return { stop: 'unchanged' };
+                }
+                body = {
+                    ...current.body,
+                    ...declared,
+                    lastSeen: stamp,
+                    grants: [
+                        ...current.entry.grants,
+                        ...recorded.filter(grant => !held.has(grant.zcap.id))
+                    ]
+                };
+                delete body.retired;
+                delete body.declined;
+            }
+            if (seed !== undefined && stored?.seed === undefined) {
+                body = { ...body, seed, seedTag };
+            }
+            else if (seed !== undefined && stored?.seed !== seed) {
+                throw new Error('The connections entry already carries a different pairwise seed; ' +
+                    'a seed is written once.');
+            }
+            if (message !== undefined) {
+                body = {
+                    ...body,
+                    outbox: supersedeAndQueueEnvelope({
+                        outbox: stored?.outbox ?? [],
+                        message,
+                        stamp,
+                        supersedes: zcap => seen.has(zcap.id)
+                    })
                 };
             }
-            assertKind({ entry: current.entry, kind });
-            const held = new Set(current.entry.grants.map(grant => grant.zcap.id));
-            const body = {
-                ...current.body,
-                ...declared,
-                lastSeen: stamp,
-                grants: [
-                    ...current.entry.grants,
-                    ...recorded.filter(grant => !held.has(grant.zcap.id))
-                ]
-            };
-            delete body.retired;
             return { body };
         }
     });
@@ -334,8 +562,9 @@ export async function removeGrants({ store, hmacKey, did, zcapIds }) {
 }
 /**
  * Retires the party's entry, of any kind, once a revocation has handled its
- * grants: empties `grants`, drops `appKey`, and stamps `retired`. `name`,
- * `label`, `origin`, `url`, `firstSeen`, `lastSeen`, and `writers` stay, so a
+ * grants: empties `grants`, `grantsReceived`, and `outbox`, drops `appKey`,
+ * and stamps `retired`. `name`, `label`, `origin`, `url`, `firstSeen`,
+ * `lastSeen`, `writers`, `seed`, `seedTag`, and `declined` stay, so a
  * departed party keeps resolving. An entry already retired with nothing left
  * to empty writes nothing, and an absent entry writes nothing.
  *
@@ -381,12 +610,16 @@ export async function retireConnection({ store, hmacKey, did, handledZcapIds, sp
             const { entry } = current;
             if (entry.retired !== undefined &&
                 entry.grants.length === 0 &&
+                entry.grantsReceived.length === 0 &&
+                entry.outbox.length === 0 &&
                 entry.appKey === undefined) {
                 return { stop: 'unchanged' };
             }
             const body = {
                 ...current.body,
                 grants: [],
+                grantsReceived: [],
+                outbox: [],
                 retired: entry.retired ?? now.toISOString()
             };
             delete body.appKey;
@@ -515,4 +748,404 @@ export async function setConnectionLabel({ store, hmacKey, did, kind, label, nam
         }
     });
 }
+/**
+ * Records the capabilities a party handed the wallet on its entry's
+ * `grantsReceived`. Each new record is merged in turn: one whose capability
+ * id is already held is left as stored, so the drain's re-run is a no-op;
+ * one with the `grantKind` and `invocationTarget` of a held record replaces
+ * it when its `expires` is strictly later or when the held record has
+ * lapsed as of `now` (at the earlier of its `expires` and `receivedAt` plus
+ * `channelMaxLifetimeMs`), and leaves the held record otherwise; any other
+ * is appended. Every record whose `expires`
+ * is past by more than the revocation clock skew is then dropped. A new
+ * record carries `receivedAt: now`.
+ *
+ * Each grant is checked strictly before anything is read, refused with a
+ * `TypeError`: its known members well-formed, its `controller` the wallet's
+ * pairwise DID toward the party, its `invocationTarget` outside this Space,
+ * its kind one of `RECEIVED_GRANT_KINDS`, an `'inbox'` grant allowing POST,
+ * and an `expires` in strict ISO 8601 form, with any number of fractional
+ * second digits (a format one engine's `Date.parse` accepts and another's
+ * refuses would make the entry unparseable there). A retired entry is refused
+ * with an `Error`, and an absent entry writes nothing.
+ *
+ * @param options {object}
+ * @param options.store {ConnectionsStore}
+ * @param options.hmacKey {ConnectionIdKey}
+ * @param options.did {string}   the party's DID
+ * @param options.pairwiseDid {string}   the wallet's pairwise did:key toward
+ *   the party, every received grant's controller
+ * @param options.spaceUrl {string}   this Space's container URL, which no
+ *   received grant may target
+ * @param options.grants {Array<object>}   `{ zcap, grantKind }` per grant
+ * @param options.channelMaxLifetimeMs {number}   how long after `receivedAt`
+ *   a received record lapses at the latest
+ * @param [options.now] {Date}
+ * @returns {Promise<ConnectionWriteResult>}
+ */
+export async function recordReceivedGrants({ store, hmacKey, did, pairwiseDid, spaceUrl, grants, channelMaxLifetimeMs, now = new Date() }) {
+    const stamp = now.toISOString();
+    const incoming = [];
+    for (const grant of grants) {
+        const zcap = requiredConnectionZcap({
+            value: grant.zcap,
+            what: 'received grant'
+        });
+        if (zcap.controller !== pairwiseDid) {
+            throw new TypeError(`A received grant must be delegated to the pairwise DID ` +
+                `"${pairwiseDid}"; its controller is "${zcap.controller}".`);
+        }
+        if (isTargetInSpace({ target: zcap.invocationTarget, spaceUrl })) {
+            throw new TypeError('A received grant must target the party, not this Space; its ' +
+                `invocation target is "${zcap.invocationTarget}".`);
+        }
+        if (!RECEIVED_GRANT_KINDS.includes(grant.grantKind)) {
+            throw new TypeError(`Unknown received grant kind "${grant.grantKind}".`);
+        }
+        if (grant.grantKind === 'inbox' &&
+            !allowsAction({ allowedAction: zcap.allowedAction, action: 'POST' })) {
+            throw new TypeError('An inbox grant must allow POST.');
+        }
+        if (!STRICT_ISO_8601.test(zcap.expires)) {
+            throw new TypeError("A received grant's `expires` must be an ISO 8601 date-time; got " +
+                `"${zcap.expires}".`);
+        }
+        incoming.push({ zcap, grantKind: grant.grantKind, receivedAt: stamp });
+    }
+    return writePartyConnection({
+        store,
+        hmacKey,
+        did,
+        change(current) {
+            if (current === undefined) {
+                return { stop: 'absent' };
+            }
+            if (current.entry.retired !== undefined) {
+                throw new Error('The connections entry is retired; it records no received grants.');
+            }
+            const merged = [...current.entry.grantsReceived];
+            for (const record of incoming) {
+                if (merged.some(held => held.zcap.id === record.zcap.id)) {
+                    continue;
+                }
+                const sameChannel = merged.findIndex(held => held.grantKind === record.grantKind &&
+                    held.zcap.invocationTarget === record.zcap.invocationTarget);
+                if (sameChannel === -1) {
+                    merged.push(record);
+                }
+                else if (expiresAtOf(record.zcap) > expiresAtOf(merged[sameChannel].zcap) ||
+                    receivedGrantLapsed({
+                        grant: {
+                            expires: merged[sameChannel].zcap.expires,
+                            receivedAt: merged[sameChannel].receivedAt
+                        },
+                        now,
+                        maxLifetimeMs: channelMaxLifetimeMs
+                    })) {
+                    merged[sameChannel] = record;
+                }
+            }
+            const kept = merged.filter(record => !expiredBeyondSkew({ zcap: record.zcap, now }));
+            if (kept.length === current.entry.grantsReceived.length &&
+                kept.every((record, index) => record === current.entry.grantsReceived[index])) {
+                return { stop: 'unchanged' };
+            }
+            return { body: { ...current.body, grantsReceived: kept } };
+        }
+    });
+}
+/**
+ * The renewal's pivot: appends the renewed grant records and queues the
+ * envelope that carries them to the party, in one compare-and-swap. Each
+ * renewed record keeps its source's `grantKind` and `grantedAt` and carries
+ * `renewedAt: now`; the source record stays as stored. On `outbox`, every
+ * zcap sharing a renewed zcap's scope is removed from the envelopes already
+ * pending, an envelope left with none is dropped, and `message` is appended
+ * with `createdAt: now`.
+ *
+ * A renewed zcap must copy its source's `invocationTarget` as stored, since
+ * the scope compares it verbatim (a trailing `*` marker included).
+ *
+ * Refuses with an `Error`, writing nothing: a retired entry (whose `retired`
+ * stays), an entry with no live inbox channel (`receivedGrants`, then
+ * `liveInboxChannel`), a renewal whose source record is gone, a renewal
+ * whose source is no longer the latest record of its scope (a concurrent
+ * renewal ran), and a renewal whose `expires` is not strictly later than its
+ * source's. The last is what keeps a renewal minted under a short-lived parent from
+ * being appended at every login. A renewed zcap not delegated to the party,
+ * not targeting this Space, or of another scope than its source, and a
+ * `message` whose zcap ids are not exactly the renewed zcap ids, are refused
+ * with a `TypeError`. An absent entry writes nothing.
+ *
+ * @param options {object}
+ * @param options.store {ConnectionsStore}
+ * @param options.hmacKey {ConnectionIdKey}
+ * @param options.did {string}   the party's DID, every renewed grant's
+ *   controller
+ * @param options.pairwiseDid {string}   the wallet's pairwise did:key toward
+ *   the party, the inbox channel's controller
+ * @param options.spaceUrl {string}   this Space's container URL
+ * @param options.renewals {Array<object>}   `{ zcap, sourceZcapId }` per
+ *   renewed grant: the new capability and the id of the record it renews
+ * @param options.message {object}   the envelope to queue, verbatim
+ * @param options.channelMaxLifetimeMs {number}   how long after `receivedAt`
+ *   an inbox record lapses at the latest
+ * @param [options.now] {Date}
+ * @returns {Promise<ConnectionWriteResult>}
+ */
+export async function recordRenewedGrants({ store, hmacKey, did, pairwiseDid, spaceUrl, renewals, message, channelMaxLifetimeMs, now = new Date() }) {
+    if (renewals.length === 0) {
+        throw new TypeError('A renewal write needs at least one renewed grant.');
+    }
+    const renewed = renewals.map(renewal => ({
+        zcap: checkedDelegatedZcap({ did, spaceUrl, zcap: renewal.zcap }),
+        sourceZcapId: renewal.sourceZcapId
+    }));
+    if (new Set(renewed.map(renewal => renewal.sourceZcapId)).size !==
+        renewed.length) {
+        throw new TypeError('Each renewed grant must renew a different record.');
+    }
+    assertEnvelopeCarries({
+        message,
+        zcapIds: renewed.map(renewal => renewal.zcap.id),
+        what: 'renewal'
+    });
+    const renewedScopes = new Set(renewed.map(renewal => grantScopeKey({ zcap: renewal.zcap })));
+    const stamp = now.toISOString();
+    return writePartyConnection({
+        store,
+        hmacKey,
+        did,
+        change(current) {
+            if (current === undefined) {
+                return { stop: 'absent' };
+            }
+            const { entry } = current;
+            if (entry.retired !== undefined) {
+                throw new Error('The connections entry is retired; its grants are not renewed.');
+            }
+            const channel = liveInboxChannel({
+                grants: receivedGrants({ entry, pairwiseDid, spaceUrl }),
+                now,
+                maxLifetimeMs: channelMaxLifetimeMs
+            });
+            if (channel === undefined) {
+                throw new Error('The connections entry holds no live inbox channel to deliver a ' +
+                    'renewal through.');
+            }
+            const latest = latestPerScope({ grants: entry.grants });
+            const appended = [];
+            for (const { zcap, sourceZcapId } of renewed) {
+                const sourceIndex = entry.grants.findIndex(grant => grant.zcap.id === sourceZcapId);
+                const source = entry.grants[sourceIndex];
+                if (source === undefined) {
+                    throw new Error(`The grant "${sourceZcapId}" a renewal renews is no longer on ` +
+                        'the connections entry.');
+                }
+                const scope = grantScopeKey({ zcap: source.zcap });
+                if (grantScopeKey({ zcap }) !== scope) {
+                    throw new TypeError(`A renewal of "${sourceZcapId}" must keep its controller, ` +
+                        'invocation target, and allowed actions.');
+                }
+                if (latest.get(scope) !== sourceIndex) {
+                    throw new Error(`The grant "${sourceZcapId}" is no longer the latest of its ` +
+                        'scope; a concurrent renewal superseded it.');
+                }
+                if (expiresAtOf(zcap) <= expiresAtOf(source.zcap)) {
+                    throw new Error(`A renewal of "${sourceZcapId}" must expire strictly later than ` +
+                        'the record it renews.');
+                }
+                appended.push({
+                    zcap,
+                    grantKind: source.grantKind,
+                    grantedAt: source.grantedAt,
+                    renewedAt: stamp
+                });
+            }
+            return {
+                body: {
+                    ...current.body,
+                    grants: [...entry.grants, ...appended],
+                    outbox: supersedeAndQueueEnvelope({
+                        outbox: entry.outbox,
+                        message,
+                        stamp,
+                        supersedes: zcap => renewedScopes.has(grantScopeKey({ zcap }))
+                    })
+                }
+            };
+        }
+    });
+}
+/**
+ * Removes the outbox item(s) queued at `createdAt`, once a push delivered
+ * them. None queued then writes nothing, and an absent entry writes nothing.
+ *
+ * @param options {object}
+ * @param options.store {ConnectionsStore}
+ * @param options.hmacKey {ConnectionIdKey}
+ * @param options.did {string}   the party's DID
+ * @param options.createdAt {string}   the delivered item's `createdAt`
+ * @returns {Promise<ConnectionWriteResult>}
+ */
+export async function settleOutboxItem({ store, hmacKey, did, createdAt }) {
+    return writePartyConnection({
+        store,
+        hmacKey,
+        did,
+        change(current) {
+            if (current === undefined) {
+                return { stop: 'absent' };
+            }
+            const kept = current.entry.outbox.filter(item => item.createdAt !== createdAt);
+            if (kept.length === current.entry.outbox.length) {
+                return { stop: 'unchanged' };
+            }
+            return { body: { ...current.body, outbox: kept } };
+        }
+    });
+}
+/**
+ * Drops the grant records renewal superseded, and the outbox items no push
+ * can still deliver. In each scope holding more than one record, every
+ * record but the latest is dropped when its `expires` is past by more than
+ * the revocation clock skew, or when its capability id is among
+ * `deadChainZcapIds`. The latest record of a scope always stays. An outbox
+ * item is discarded when every zcap its envelope carries is past `expires` by
+ * more than the skew; an item carrying a zcap this build cannot read stays.
+ * Nothing to drop writes nothing, and an absent
+ * entry writes nothing.
+ *
+ * @param options {object}
+ * @param options.store {ConnectionsStore}
+ * @param options.hmacKey {ConnectionIdKey}
+ * @param options.did {string}   the party's DID
+ * @param [options.deadChainZcapIds] {Iterable<string>}   ids of superseded
+ *   records whose chain revocation reads as dead (the signer gone from the
+ *   account document, or the parent naming another annex generation) and
+ *   whose successor's outbox item was settled. A grant `agentGrantDue` reads
+ *   as due by replacement does not qualify on that alone: a grant under an
+ *   in-place-renewed delegation stays live until that delegation expires.
+ * @param [options.now] {Date}
+ * @returns {Promise<ConnectionWriteResult>}
+ */
+export async function pruneSupersededGrants({ store, hmacKey, did, deadChainZcapIds = [], now = new Date() }) {
+    const deadChains = new Set(deadChainZcapIds);
+    return writePartyConnection({
+        store,
+        hmacKey,
+        did,
+        change(current) {
+            if (current === undefined) {
+                return { stop: 'absent' };
+            }
+            const { entry } = current;
+            const kept = new Set(latestPerScope({ grants: entry.grants }).values());
+            const grants = entry.grants.filter((grant, index) => kept.has(index) ||
+                !(expiredBeyondSkew({ zcap: grant.zcap, now }) ||
+                    deadChains.has(grant.zcap.id)));
+            const outbox = entry.outbox.filter(item => {
+                const zcaps = envelopeZcaps(item.message)?.map(parseConnectionZcap);
+                return (zcaps === undefined ||
+                    zcaps.length === 0 ||
+                    !zcaps.every(zcap => zcap !== undefined && expiredBeyondSkew({ zcap, now })));
+            });
+            if (grants.length === entry.grants.length &&
+                outbox.length === entry.outbox.length) {
+                return { stop: 'unchanged' };
+            }
+            return { body: { ...current.body, grants, outbox } };
+        }
+    });
+}
+/**
+ * Empties the party's `grantsReceived` and `outbox`: the agent revoke's
+ * first write, so no client pushes to the party once it starts. Both already
+ * empty writes nothing, and an absent entry writes nothing.
+ *
+ * @param options {object}
+ * @param options.store {ConnectionsStore}
+ * @param options.hmacKey {ConnectionIdKey}
+ * @param options.did {string}   the party's DID
+ * @returns {Promise<ConnectionWriteResult>}
+ */
+export async function clearReceivedGrants({ store, hmacKey, did }) {
+    return writePartyConnection({
+        store,
+        hmacKey,
+        did,
+        change(current) {
+            if (current === undefined) {
+                return { stop: 'absent' };
+            }
+            if (current.entry.grantsReceived.length === 0 &&
+                current.entry.outbox.length === 0) {
+                return { stop: 'unchanged' };
+            }
+            return { body: { ...current.body, grantsReceived: [], outbox: [] } };
+        }
+    });
+}
+/**
+ * Drops one record from the party's `grantsReceived` by its capability id,
+ * and leaves `outbox` as it is: what a push refused by the party's server
+ * (a 401, a 403, or a WAS host's masked 404) does with the channel it went
+ * through, since the refusal says the capability is expired or revoked. The
+ * queued envelopes stay for the party's next invitation, and a replacement
+ * channel the party then hands over is stored by `recordReceivedGrants`
+ * whatever its `expires`, since the dropped record is gone. A record not
+ * held writes nothing, and an absent entry writes nothing.
+ *
+ * @param options {object}
+ * @param options.store {ConnectionsStore}
+ * @param options.hmacKey {ConnectionIdKey}
+ * @param options.did {string}   the party's DID
+ * @param options.zcapId {string}   the `id` of the received capability
+ * @returns {Promise<ConnectionWriteResult>}
+ */
+export async function dropReceivedGrant({ store, hmacKey, did, zcapId }) {
+    return writePartyConnection({
+        store,
+        hmacKey,
+        did,
+        change(current) {
+            if (current === undefined) {
+                return { stop: 'absent' };
+            }
+            const kept = current.entry.grantsReceived.filter(record => record.zcap.id !== zcapId);
+            if (kept.length === current.entry.grantsReceived.length) {
+                return { stop: 'unchanged' };
+            }
+            return { body: { ...current.body, grantsReceived: kept } };
+        }
+    });
+}
+/**
+ * Records the owner's decline of the party's offer: sets `declined` to
+ * `now`. An entry already declined keeps its time and writes nothing, and an
+ * absent entry writes nothing. A later consent (`recordGrants`) clears it.
+ *
+ * @param options {object}
+ * @param options.store {ConnectionsStore}
+ * @param options.hmacKey {ConnectionIdKey}
+ * @param options.did {string}   the party's DID
+ * @param [options.now] {Date}
+ * @returns {Promise<ConnectionWriteResult>}
+ */
+export async function markDeclined({ store, hmacKey, did, now = new Date() }) {
+    return writePartyConnection({
+        store,
+        hmacKey,
+        did,
+        change(current) {
+            if (current === undefined) {
+                return { stop: 'absent' };
+            }
+            if (current.entry.declined !== undefined) {
+                return { stop: 'unchanged' };
+            }
+            return { body: { ...current.body, declined: now.toISOString() } };
+        }
+    });
+}
 //# sourceMappingURL=upsert.js.map