@interop/wallet-core 0.94.0 → 0.96.0

package/dist/connections/writers.d.ts

@@ -0,0 +1,217 @@
+import type { ConnectionEntry, ConnectionWriterPolicy } from './entry.js';
+import type { ConnectionsListing } from './read.js';
+import type { ConnectionIdKey } from './resourceId.js';
+import type { ConnectionsStore } from './store.js';
+/**
+ * The writer first-seen record, kept by the client: the account and
+ * `writerId` this client's writer first appeared under, and when it last
+ * touched its member. One slot, so a writer that moves to another account
+ * starts over.
+ */
+export interface WriterFirstSeenRecord {
+    accountDid: string;
+    writerId: string;
+    /**
+     * ISO 8601 UTC start of the session the record was written in.
+     */
+    firstSessionAt: string;
+    /**
+     * ISO 8601 UTC time of the latest successful registration or touch.
+     */
+    lastTouchedAt?: string;
+}
+/**
+ * The seam for the writer first-seen record. Where it lives is the wallet's
+ * choice: it rides the session's persistence, and a forget of this client's
+ * local state clears it along with the `writerId`.
+ */
+export interface WriterFirstSeenStore {
+    get(): Promise<unknown>;
+    put(record: WriterFirstSeenRecord): Promise<void>;
+}
+/**
+ * What {@link registerConnectionWriter} did.
+ *
+ * - `deferred` -- the writer has not yet been encountered in a second session
+ *   under this account; the first-seen record is (re)written and the
+ *   directory is untouched.
+ * - `fresh` -- the latest touch is within the touch interval; no I/O.
+ * - `registered` -- the writer member was added (the entry created if it was
+ *   absent).
+ * - `touched` -- the writer member's `lastSeen` was advanced.
+ * - `raced` -- every attempt lost a conditional write; the next call retries.
+ * - `unlisted` -- no entry stands and the verified document does not list
+ *   this client, so none is created.
+ * - `retired` -- the entry is retired and the verified document no longer
+ *   lists this client; nothing is written.
+ * - `kind-mismatch` -- the entry at this client's id is not a
+ *   `wallet-client` entry; nothing is written, and the caller logs it.
+ * - `refused` -- the entry cannot be parsed, or comes from a newer build;
+ *   nothing is written.
+ */
+export type WriterRegistrationOutcome = 'deferred' | 'fresh' | 'registered' | 'touched' | 'raced' | 'unlisted' | 'retired' | 'kind-mismatch' | 'refused';
+/**
+ * Registers this client's writer on its own `wallet-client` entry once the
+ * writer is encountered in a second session under the account, and touches
+ * the member's `lastSeen` at most once per touch interval after that. Call it
+ * on the wallet's connect or sync path; calls within the interval cost no
+ * I/O. The interval runs from the last settled call, whatever its outcome,
+ * so an entry this client cannot write (`unlisted`, `retired`,
+ * `kind-mismatch`, `refused`) is re-read once per interval and not on every
+ * call. Only `raced` leaves the next call to try again at once.
+ *
+ * An absent entry is created (`kind: 'wallet-client'`, `id` this client's
+ * did:key, `name` the platform label), which converges a lost
+ * enrollment-time write, but only while the verified account document lists
+ * this client. A retired entry is un-retired while the document lists this
+ * client (a forget torn after its retirement) and left alone otherwise. A
+ * new member first makes room under the per-entry writer cap.
+ *
+ * @param options {object}
+ * @param options.store {ConnectionsStore}
+ * @param options.hmacKey {ConnectionIdKey}   the collection's blinded-index
+ *   key
+ * @param options.local {WriterFirstSeenStore}
+ * @param options.accountDid {string}   the account the first-seen record is
+ *   kept under
+ * @param options.did {string}   this client's did:key
+ * @param options.writerId {string}   this client's writer
+ * @param options.label {string}   the coarse platform self-description a new
+ *   member (and a new entry's `name`) takes; held to the display-name rule,
+ *   and refused with a `TypeError` outside it
+ * @param options.listedInDocument {boolean}   whether the verified account
+ *   document lists this client
+ * @param options.sessionStartedAt {Date}   when the current session began; a
+ *   first-seen record written at or after it is this session's own
+ * @param [options.now] {Date}
+ * @param [options.policy] {Partial<ConnectionWriterPolicy>}
+ * @returns {Promise<WriterRegistrationOutcome>}
+ */
+export declare function registerConnectionWriter({ store, hmacKey, local, accountDid, did, writerId, label, listedInDocument, sessionStartedAt, now, policy }: {
+    store: ConnectionsStore;
+    hmacKey: ConnectionIdKey;
+    local: WriterFirstSeenStore;
+    accountDid: string;
+    did: string;
+    writerId: string;
+    label: string;
+    listedInDocument: boolean;
+    sessionStartedAt: Date;
+    now?: Date;
+    policy?: Partial<ConnectionWriterPolicy>;
+}): Promise<WriterRegistrationOutcome>;
+/**
+ * What {@link touchConnectionWriter} did.
+ *
+ * - `unregistered` -- no listed entry carries the writer; nothing is written.
+ * - `retired` -- the writer's entry is retired; nothing is written.
+ * - `fresh` -- the member was touched within the touch interval.
+ * - `touched` -- the member's `lastSeen` was advanced.
+ * - `refused` -- the entry cannot be written by this build.
+ * - `raced` -- every attempt lost a conditional write.
+ */
+export type WriterTouchOutcome = 'unregistered' | 'retired' | 'fresh' | 'touched' | 'refused' | 'raced';
+/**
+ * Touches a registered writer's member from a pulled revision's `writerId`:
+ * the remembered session's pull path, throttled like the client's own touch.
+ * The writer is found in a listing already read, so the call costs no extra
+ * listing read, and a member the listing shows as fresh costs no I/O at all.
+ * An unregistered `writerId` is ignored, and so is a writer on a retired
+ * entry, so a replayed revision cannot keep a departed client's writer
+ * alive.
+ *
+ * @param options {object}
+ * @param options.store {ConnectionsStore}
+ * @param options.hmacKey {ConnectionIdKey}
+ * @param options.listing {ConnectionsListing}   the latest listing read
+ * @param options.writerId {string}   the pulled revision's `writerId`
+ * @param [options.now] {Date}
+ * @param [options.policy] {Partial<ConnectionWriterPolicy>}
+ * @returns {Promise<WriterTouchOutcome>}
+ */
+export declare function touchConnectionWriter({ store, hmacKey, listing, writerId, now, policy }: {
+    store: ConnectionsStore;
+    hmacKey: ConnectionIdKey;
+    listing: ConnectionsListing;
+    writerId: string;
+    now?: Date;
+    policy?: Partial<ConnectionWriterPolicy>;
+}): Promise<WriterTouchOutcome>;
+/**
+ * The outcome of a sweep: the listing with each written entry replaced by
+ * what was written, the writers it changed, and the entries whose write
+ * failed for a reason other than a lost race, each with the error the store
+ * raised, for the caller's log.
+ */
+export interface ConnectionWritersSweep {
+    listing: ConnectionsListing;
+    markedInactive: string[];
+    dropped: string[];
+    failed: Array<{
+        resourceId: string;
+        err: unknown;
+    }>;
+}
+/**
+ * Sweeps every entry of a listing already read: the per-entry two-phase
+ * expiry of `writers`, run at the directory listing read on both session
+ * kinds. Safe to run from any replica, and concurrently. Every write is
+ * conditional on the ETag the listing read, and a lost race is skipped: the
+ * entry as read still labels its revisions. Any other failed write is skipped
+ * the same way and reported in `failed`, so one unreachable entry does not
+ * fail the listing read the sweep rides on; the next sweep converges it. An
+ * entry this build cannot write (a newer `version`), or one read without an
+ * ETag, is left alone.
+ *
+ * @param options {object}
+ * @param options.store {ConnectionsStore}
+ * @param options.listing {ConnectionsListing}
+ * @param [options.now] {Date}
+ * @param [options.policy] {Partial<ConnectionWriterPolicy>}
+ * @returns {Promise<ConnectionWritersSweep>}
+ */
+export declare function sweepConnectionWriters({ store, listing, now, policy }: {
+    store: ConnectionsStore;
+    listing: ConnectionsListing;
+    now?: Date;
+    policy?: Partial<ConnectionWriterPolicy>;
+}): Promise<ConnectionWritersSweep>;
+/**
+ * How a history view renders one revision's writer. `undefined` from
+ * {@link resolveWriter} means no entry carries the writer: the view renders
+ * its fallback label ("another session").
+ */
+export interface ResolvedWriter {
+    /**
+     * The entry's display name: the user's `label`, else its `name`, else the
+     * writer member's platform label.
+     */
+    label: string;
+    active: boolean;
+    /**
+     * Whether the writer's entry is retired.
+     */
+    retired: boolean;
+    /**
+     * Present only when the entry's did:key carries a signing key the verified
+     * account document lists. The view may then link the revision to that
+     * client's row.
+     */
+    clientSigningKeyMultibase?: string;
+}
+/**
+ * Resolves a revision's `writerId` against the directory's entries.
+ *
+ * @param options {object}
+ * @param options.writerId {string}
+ * @param options.entries {ConnectionEntry[]}   the listed entries
+ * @param options.enrolledSigningKeys {ReadonlySet<string>}   the signing-key
+ *   multibases of the enrolled clients in the verified account document
+ * @returns {ResolvedWriter | undefined}
+ */
+export declare function resolveWriter({ writerId, entries, enrolledSigningKeys }: {
+    writerId: string;
+    entries: ConnectionEntry[];
+    enrolledSigningKeys: ReadonlySet<string>;
+}): ResolvedWriter | undefined;
+//# sourceMappingURL=writers.d.ts.map

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

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