@interop/wallet-core 0.107.0 → 0.108.0

package/dist/connections/replicas.d.ts

@@ -0,0 +1,227 @@
+import type { ConnectionIdKey } from './resourceId.js';
+import type { ConnectionsStore } from './store.js';
+import type { ConnectionWriteResult } from './upsert.js';
+/**
+ * The intent markers a replica item carries.
+ */
+export declare const REPLICA_MARKERS: readonly ["stoppedAt", "restartedAt", "lostAt"];
+/**
+ * One value of {@link REPLICA_MARKERS}.
+ */
+export type ReplicaMarker = (typeof REPLICA_MARKERS)[number];
+/**
+ * The registration ceremony's entry write, before anything touches the
+ * replica server: creates the `replica-server` entry, or merges into it.
+ * `url` is set, `name` when it passes the display-name rule, and `lastSeen`
+ * moves to `now`. Each item of `replicas` is added by its `fromSpace` (stored
+ * URL-normalized) with its freshly minted replica Space id; an item already
+ * listed for that source Space is left as stored, so a re-run adopts the ids
+ * an earlier run persisted. An item already listed that carries `lostAt` is
+ * refused with an `Error`: its replica Space is gone, so adopting its id
+ * would register under a lost Space while the item kept reading as lost.
+ * Delete removes the item (`removeReplica`) before the Space is registered
+ * again. `retired` and `declined` are cleared, since the user's registration
+ * is a fresh consent toward the server. `firstSeen` is set only on create,
+ * and `label` is never touched.
+ *
+ * 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 and a retired entry keeps it.
+ *
+ * Refuses an entry of another kind with {@link ConnectionKindMismatchError},
+ * and a `fromSpace` that is not a container URL, a `spaceId` that is not a
+ * fresh id, two items naming one source Space, or a `seed` without its tag
+ * (or the reverse) with a `TypeError`, before anything is written. The tag
+ * is not verified here; the caller minted both under the directory's key.
+ *
+ * @param options {object}
+ * @param options.store {ConnectionsStore}
+ * @param options.hmacKey {ConnectionIdKey}
+ * @param options.did {string}   the replica server's `serverDid`
+ * @param options.url {string}   the replica server's base URL
+ * @param options.replicas {Array<object>}   `{ fromSpace, spaceId }` per
+ *   replica Space to record
+ * @param [options.name] {string}   the replica server's host name
+ * @param [options.seed] {string}   the bootstrap seed, base64url with no
+ *   padding
+ * @param [options.seedTag] {string}   the seed's tag (`connectionSeedTag`)
+ * @param [options.now] {Date}
+ * @returns {Promise<ConnectionWriteResult>}
+ */
+export declare function recordReplicas({ store, hmacKey, did, url, replicas, name, seed, seedTag, now }: {
+    store: ConnectionsStore;
+    hmacKey: ConnectionIdKey;
+    did: string;
+    url: string;
+    replicas: Array<{
+        fromSpace: string;
+        spaceId: string;
+    }>;
+    name?: string;
+    seed?: string;
+    seedTag?: string;
+    now?: Date;
+}): Promise<ConnectionWriteResult>;
+/**
+ * Records one pull grant on the entry, and with it a first registration's
+ * pending id, in one write. The grant is appended as a `'grant'` record
+ * stamped `grantedAt: now`; one already recorded by its capability id is
+ * left as stored. With `pendingRegistrationId`, the item for `fromSpace`
+ * gains it, unless its first registration already landed (`registrationId`
+ * present) or it is pending under another id, each refused with an `Error`:
+ * the pending id is recorded before its POST, so a second id would orphan a
+ * registration that may have landed under the first.
+ *
+ * With `renews`, the id of the recorded grant the capability renews, the
+ * record is a renewal under `renewedGrantRecord`, the rule
+ * `recordRenewedGrants` applies: it keeps the source's `grantKind` and
+ * `grantedAt` and carries `renewedAt: now`, the source stays as stored, and
+ * the capability must share the source's scope (controller, invocation
+ * target, allowed actions) and expire strictly later. A source no longer on
+ * the entry, no longer the latest record of its scope, or a capability not
+ * expiring strictly later, is refused with an `Error`. The login pass records a renewal this
+ * way, with no pending id; the two together are refused with a `TypeError`.
+ *
+ * This write touches neither `declined` nor `retired`: the pass records a
+ * renewal through it, and a declined entry must stay declined until the
+ * owner's re-start (`setReplicaMarker` with `restartedAt`) clears it.
+ *
+ * Refuses an entry of another kind with {@link ConnectionKindMismatchError},
+ * a retired entry with an `Error`, and a capability not delegated to the
+ * server's DID or not targeting `fromSpace` (`checkedDelegatedZcap`), one
+ * allowing any action but `GET` (a pull grant reads and nothing else), or a
+ * `pendingRegistrationId` that is not a fresh id, with a `TypeError`. An entry listing no item for
+ * `fromSpace` is refused with an `Error`. An absent entry writes nothing.
+ *
+ * @param options {object}
+ * @param options.store {ConnectionsStore}
+ * @param options.hmacKey {ConnectionIdKey}
+ * @param options.did {string}   the replica server's `serverDid`, the
+ *   grant's controller
+ * @param options.fromSpace {string}   the source Space the grant reads from
+ * @param options.zcap {object}   the pull capability
+ * @param [options.pendingRegistrationId] {string}   a first registration's
+ *   id, recorded before its POST
+ * @param [options.renews] {string}   the capability id of the recorded grant
+ *   this one renews
+ * @param [options.now] {Date}
+ * @returns {Promise<ConnectionWriteResult>}
+ */
+export declare function recordReplicaGrant({ store, hmacKey, did, fromSpace: spaceValue, zcap: zcapValue, pendingRegistrationId, renews, now }: {
+    store: ConnectionsStore;
+    hmacKey: ConnectionIdKey;
+    did: string;
+    fromSpace: string;
+    zcap: object;
+    pendingRegistrationId?: string;
+    renews?: string;
+    now?: Date;
+}): Promise<ConnectionWriteResult>;
+/**
+ * Moves a landed first registration's id from `pendingRegistrationId` to
+ * `registrationId` on the item for `fromSpace`. An item already settled on
+ * `registrationId` with no pending id writes nothing. An item whose pending
+ * id is another, or that carries neither, is refused with an `Error`.
+ *
+ * Refuses an entry of another kind with {@link ConnectionKindMismatchError},
+ * and an entry listing no item for `fromSpace` with an `Error`. An absent
+ * entry writes nothing.
+ *
+ * @param options {object}
+ * @param options.store {ConnectionsStore}
+ * @param options.hmacKey {ConnectionIdKey}
+ * @param options.did {string}   the replica server's `serverDid`
+ * @param options.fromSpace {string}   the item's source Space
+ * @param options.registrationId {string}   the id that landed
+ * @returns {Promise<ConnectionWriteResult>}
+ */
+export declare function settleReplicaRegistration({ store, hmacKey, did, fromSpace: value, registrationId }: {
+    store: ConnectionsStore;
+    hmacKey: ConnectionIdKey;
+    did: string;
+    fromSpace: string;
+    registrationId: string;
+}): Promise<ConnectionWriteResult>;
+/**
+ * Sets one intent marker to `now` on each named item, or on every item when
+ * `fromSpaces` is omitted: `stoppedAt` is the user's Stop, `restartedAt` the
+ * re-start, and `lostAt` the replica Space reading absent under the account's
+ * own authority. An item already carrying the marker keeps its time. Setting
+ * `restartedAt` also clears the entry's `declined`, in the same write, since
+ * the re-start is the owner's consent. Nothing to set writes nothing.
+ *
+ * Refuses an entry of another kind with {@link ConnectionKindMismatchError},
+ * a named source Space the entry lists no item for with an `Error`, and an
+ * empty `fromSpaces` with a `TypeError`, since it would mark nothing while
+ * the re-start's decline clearing still ran. An absent entry writes nothing.
+ *
+ * @param options {object}
+ * @param options.store {ConnectionsStore}
+ * @param options.hmacKey {ConnectionIdKey}
+ * @param options.did {string}   the replica server's `serverDid`
+ * @param options.marker {ReplicaMarker}
+ * @param [options.fromSpaces] {Iterable<string>}   the items to mark, by
+ *   source Space; omitted, every item
+ * @param [options.now] {Date}
+ * @returns {Promise<ConnectionWriteResult>}
+ */
+export declare function setReplicaMarker({ store, hmacKey, did, marker, fromSpaces, now }: {
+    store: ConnectionsStore;
+    hmacKey: ConnectionIdKey;
+    did: string;
+    marker: ReplicaMarker;
+    fromSpaces?: Iterable<string>;
+    now?: Date;
+}): Promise<ConnectionWriteResult>;
+/**
+ * Clears one intent marker on each named item, or on every item when
+ * `fromSpaces` is omitted: a completed re-start clears `stoppedAt` and then
+ * `restartedAt`. An item without the marker is left as stored, and nothing
+ * to clear writes nothing.
+ *
+ * Refuses an entry of another kind with {@link ConnectionKindMismatchError},
+ * a named source Space the entry lists no item for with an `Error`, and an
+ * empty `fromSpaces` with a `TypeError`. An absent entry writes nothing.
+ *
+ * @param options {object}
+ * @param options.store {ConnectionsStore}
+ * @param options.hmacKey {ConnectionIdKey}
+ * @param options.did {string}   the replica server's `serverDid`
+ * @param options.marker {ReplicaMarker}
+ * @param [options.fromSpaces] {Iterable<string>}   the items to clear, by
+ *   source Space; omitted, every item
+ * @returns {Promise<ConnectionWriteResult>}
+ */
+export declare function clearReplicaMarker({ store, hmacKey, did, marker, fromSpaces }: {
+    store: ConnectionsStore;
+    hmacKey: ConnectionIdKey;
+    did: string;
+    marker: ReplicaMarker;
+    fromSpaces?: Iterable<string>;
+}): Promise<ConnectionWriteResult>;
+/**
+ * Removes the item for `fromSpace`, once its replica Space is gone. An
+ * entry listing no such item writes nothing. The entry is not retired here:
+ * `retireConnection` runs once the list is empty.
+ *
+ * Refuses an entry of another kind with {@link ConnectionKindMismatchError},
+ * and an item whose source Space a recorded grant still targets with an
+ * `Error`: Stop revokes and removes the pull grants first, so a grant left
+ * recorded means a Stop torn before its last step, and the removal would
+ * hide it from the readers that finish it. An absent entry writes nothing.
+ *
+ * @param options {object}
+ * @param options.store {ConnectionsStore}
+ * @param options.hmacKey {ConnectionIdKey}
+ * @param options.did {string}   the replica server's `serverDid`
+ * @param options.fromSpace {string}   the item's source Space
+ * @returns {Promise<ConnectionWriteResult>}
+ */
+export declare function removeReplica({ store, hmacKey, did, fromSpace: value }: {
+    store: ConnectionsStore;
+    hmacKey: ConnectionIdKey;
+    did: string;
+    fromSpace: string;
+}): Promise<ConnectionWriteResult>;
+//# sourceMappingURL=replicas.d.ts.map

package/dist/connections/replicas.d.ts.map

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