@interop/wallet-core 0.71.0 → 0.72.0

package/dist/menders/index.js

@@ -0,0 +1,37 @@
+/*!
+ * Copyright (c) 2026 Interop Alliance. All rights reserved.
+ */
+/**
+ * The `@interop/wallet-core/menders` subpath: the mender registry keyed by
+ * invariant. A wallet declares its own table of invariants (data: what must
+ * hold between ceremonies) and its own registrations (code: what converges a
+ * violated one); this module carries the structure both wallets share.
+ *
+ * - the vocabularies: `AUTHORITIES`, `TRIGGERS`, `CHAIN_TRIGGERS`,
+ *   `ACCOUNT_SHAPES`, `EVIDENCE`, `MEND_OUTCOMES`, `GAP_KINDS`, and
+ *   `INVARIANT_IDS`, each an `as const` array with its union
+ * - the types: `InvariantDeclaration`, `RegistrationSite`, `Registration`,
+ *   `MendOutcome`, `MendReportEntry`, `MendReport`, `InvariantGap`,
+ *   `LoginRoute`
+ * - the readers: `menderRegistry` (`all`, `byId`, `sites`, `admits`,
+ *   `dueAt`), which refuses a duplicated id, an undeclared report, or a
+ *   guard on a non-routing site at construction, and `heldAuthorities`, the
+ *   held set a session's account-ceremony context derives
+ * - the runner: `runMenderBlock`, one try, warn, and skip discipline over
+ *   one chain trigger's registrations, `mendReportAccumulator`, the
+ *   pre-session report collector its `onOutcome` feeds, and `errorNameOf`,
+ *   the name a report carries for a thrown value of any shape
+ * - the derived sets a wallet's audit tests pin:
+ *   `transientReachableInvariants`, `deriveGaps`, `undeclaredGaps`, and
+ *   `undeclaredInvariants`
+ *
+ * Nothing here executes a ceremony. The runner calls the convergers a
+ * wallet registers and nothing else; the ceremonies stay explicit sequenced
+ * code, and the registry describes the menders from the outside.
+ */
+export { deriveGaps, transientReachableInvariants, undeclaredGaps, undeclaredInvariants } from './derive.js';
+export { INVARIANT_IDS } from './ids.js';
+export { heldAuthorities, menderRegistry } from './registry.js';
+export { errorNameOf, MEND_REPORT_SHAPE_ERROR, mendReportAccumulator, runMenderBlock } from './runner.js';
+export { ACCOUNT_SHAPES, AUTHORITIES, CHAIN_TRIGGERS, EVIDENCE, GAP_KINDS, MEND_OUTCOMES, TRIGGERS } from './vocabulary.js';
+//# sourceMappingURL=index.js.map

package/dist/menders/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/menders/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,OAAO,EACL,UAAU,EACV,4BAA4B,EAC5B,cAAc,EACd,oBAAoB,EACrB,MAAM,aAAa,CAAA;AACpB,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AAExC,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,eAAe,CAAA;AAE/D,OAAO,EACL,WAAW,EACX,uBAAuB,EACvB,qBAAqB,EACrB,cAAc,EACf,MAAM,aAAa,CAAA;AAYpB,OAAO,EACL,cAAc,EACd,WAAW,EACX,cAAc,EACd,QAAQ,EACR,SAAS,EACT,aAAa,EACb,QAAQ,EACT,MAAM,iBAAiB,CAAA"}

package/dist/menders/registry.d.ts

@@ -0,0 +1,84 @@
+/*!
+ * Copyright (c) 2026 Interop Alliance. All rights reserved.
+ */
+/**
+ * The registry readers over a declaration table and its per-trigger
+ * registration sites: `all` and `byId` read declarations, `admits` is the
+ * one admission test (every reported invariant declares an authority the
+ * session holds and admits this login route), and `dueAt` reads the sites
+ * listed under one chain trigger that `admits` passes, in list order.
+ * Registration order is execution order; there is no dependency graph and
+ * no priority. The table and the sites are checked once, at construction: a
+ * duplicated declaration id, a site reporting an undeclared invariant, or a
+ * guard on a non-routing site is a `TypeError` there, so no reader meets the
+ * defect later, depending on what a login happens to hold.
+ */
+import type { InvariantId } from './ids.js';
+import type { InvariantDeclaration, LoginRoute, RegistrationSite } from './types.js';
+import type { Authority, ChainTrigger } from './vocabulary.js';
+/**
+ * The two authorities a session's account-ceremony context resolves to; the
+ * remaining values, `none` and `account`, are the ones every resolved kind
+ * subsumes. Derived from the vocabulary, so a new authority is a compile
+ * error in `heldAuthorities` rather than a value it can never return.
+ */
+export type ResolvedAuthority = Exclude<Authority, 'none' | 'account'>;
+/**
+ * The readers over one wallet's table. `Site` is the converge-free index
+ * shape or a wallet's registration type extending it, so the same readers
+ * serve the audit and the runner.
+ */
+export interface MenderRegistry<Site extends RegistrationSite, Deps, Ceremony extends string = string> {
+    all(): ReadonlyArray<InvariantDeclaration<Deps, Ceremony>>;
+    byId(id: InvariantId): InvariantDeclaration<Deps, Ceremony> | undefined;
+    sites(): ReadonlyArray<Site>;
+    /**
+     * Whether a site's every reported invariant declares an authority in
+     * `held` and, when a route is given, admits it. The one admission test,
+     * shared by `dueAt` and by a runner admitting a site the caller supplies.
+     *
+     * @throws {TypeError}   when the site reports an undeclared invariant,
+     *   reachable only for a site the registry does not index
+     */
+    admits(options: {
+        site: RegistrationSite;
+        held: ReadonlyArray<Authority>;
+        route?: LoginRoute;
+    }): boolean;
+    dueAt(options: {
+        held: ReadonlyArray<Authority>;
+        trigger: ChainTrigger;
+        route?: LoginRoute;
+    }): ReadonlyArray<Site>;
+}
+/**
+ * The held set a session derives from its account-ceremony context: `none`
+ * always, plus `account` and the resolved kind when a context resolves.
+ *
+ * @param options {object}
+ * @param [options.kind] {ResolvedAuthority}   the resolved context kind,
+ *   absent for a guest, a no-WAS session, or a transient session whose
+ *   record carries no standing members
+ * @returns {ReadonlyArray<Authority>}
+ */
+export declare function heldAuthorities({ kind }: {
+    kind?: ResolvedAuthority;
+}): ReadonlyArray<Authority>;
+/**
+ * Builds the readers over one wallet's declarations and sites, checking
+ * both once: every declaration id is unique, every reported id is declared,
+ * and only a `login-routing` site carries `guardedBy`.
+ *
+ * @param options {object}
+ * @param options.declarations {ReadonlyArray<InvariantDeclaration>}
+ * @param options.sites {ReadonlyArray<RegistrationSite>}   every
+ *   registration site, any trigger, in execution order within a trigger
+ * @returns {MenderRegistry}
+ * @throws {TypeError}   on a duplicated declaration id, an undeclared
+ *   report, or a guard on a non-routing site
+ */
+export declare function menderRegistry<Site extends RegistrationSite, Deps, Ceremony extends string = string>({ declarations, sites }: {
+    declarations: ReadonlyArray<InvariantDeclaration<Deps, Ceremony>>;
+    sites: ReadonlyArray<Site>;
+}): MenderRegistry<Site, Deps, Ceremony>;
+//# sourceMappingURL=registry.d.ts.map

package/dist/menders/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/menders/registry.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAA;AAC3C,OAAO,KAAK,EACV,oBAAoB,EACpB,UAAU,EACV,gBAAgB,EACjB,MAAM,YAAY,CAAA;AACnB,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAE9D;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,GAAG,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC,CAAA;AAEtE;;;;GAIG;AACH,MAAM,WAAW,cAAc,CAC7B,IAAI,SAAS,gBAAgB,EAC7B,IAAI,EACJ,QAAQ,SAAS,MAAM,GAAG,MAAM;IAEhC,GAAG,IAAI,aAAa,CAAC,oBAAoB,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAA;IAC1D,IAAI,CAAC,EAAE,EAAE,WAAW,GAAG,oBAAoB,CAAC,IAAI,EAAE,QAAQ,CAAC,GAAG,SAAS,CAAA;IACvE,KAAK,IAAI,aAAa,CAAC,IAAI,CAAC,CAAA;IAC5B;;;;;;;OAOG;IACH,MAAM,CAAC,OAAO,EAAE;QACd,IAAI,EAAE,gBAAgB,CAAA;QACtB,IAAI,EAAE,aAAa,CAAC,SAAS,CAAC,CAAA;QAC9B,KAAK,CAAC,EAAE,UAAU,CAAA;KACnB,GAAG,OAAO,CAAA;IACX,KAAK,CAAC,OAAO,EAAE;QACb,IAAI,EAAE,aAAa,CAAC,SAAS,CAAC,CAAA;QAC9B,OAAO,EAAE,YAAY,CAAA;QACrB,KAAK,CAAC,EAAE,UAAU,CAAA;KACnB,GAAG,aAAa,CAAC,IAAI,CAAC,CAAA;CACxB;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,EAC9B,IAAI,EACL,EAAE;IACD,IAAI,CAAC,EAAE,iBAAiB,CAAA;CACzB,GAAG,aAAa,CAAC,SAAS,CAAC,CAE3B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAC5B,IAAI,SAAS,gBAAgB,EAC7B,IAAI,EACJ,QAAQ,SAAS,MAAM,GAAG,MAAM,EAChC,EACA,YAAY,EACZ,KAAK,EACN,EAAE;IACD,YAAY,EAAE,aAAa,CAAC,oBAAoB,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAA;IACjE,KAAK,EAAE,aAAa,CAAC,IAAI,CAAC,CAAA;CAC3B,GAAG,cAAc,CAAC,IAAI,EAAE,IAAI,EAAE,QAAQ,CAAC,CAsDvC"}

package/dist/menders/registry.js

@@ -0,0 +1,62 @@
+/**
+ * The held set a session derives from its account-ceremony context: `none`
+ * always, plus `account` and the resolved kind when a context resolves.
+ *
+ * @param options {object}
+ * @param [options.kind] {ResolvedAuthority}   the resolved context kind,
+ *   absent for a guest, a no-WAS session, or a transient session whose
+ *   record carries no standing members
+ * @returns {ReadonlyArray<Authority>}
+ */
+export function heldAuthorities({ kind }) {
+    return kind ? ['none', 'account', kind] : ['none'];
+}
+/**
+ * Builds the readers over one wallet's declarations and sites, checking
+ * both once: every declaration id is unique, every reported id is declared,
+ * and only a `login-routing` site carries `guardedBy`.
+ *
+ * @param options {object}
+ * @param options.declarations {ReadonlyArray<InvariantDeclaration>}
+ * @param options.sites {ReadonlyArray<RegistrationSite>}   every
+ *   registration site, any trigger, in execution order within a trigger
+ * @returns {MenderRegistry}
+ * @throws {TypeError}   on a duplicated declaration id, an undeclared
+ *   report, or a guard on a non-routing site
+ */
+export function menderRegistry({ declarations, sites }) {
+    const index = new Map();
+    for (const decl of declarations) {
+        if (index.has(decl.id)) {
+            throw new TypeError(`An invariant is declared twice: ${decl.id}`);
+        }
+        index.set(decl.id, decl);
+    }
+    const requireDeclared = (id) => {
+        const decl = index.get(id);
+        if (!decl) {
+            throw new TypeError(`A registration reports an undeclared invariant: ${id}`);
+        }
+        return decl;
+    };
+    for (const site of sites) {
+        site.reports.forEach(requireDeclared);
+        const { trigger, guardedBy } = site;
+        if (guardedBy !== undefined && trigger !== 'login-routing') {
+            throw new TypeError(`A ${trigger} site carries a guard; only a login-routing site may`);
+        }
+    }
+    const admits = ({ site, held, route }) => site.reports.every(id => {
+        const decl = requireDeclared(id);
+        return (held.includes(decl.authority) &&
+            (route === undefined || !decl.when || decl.when(route)));
+    });
+    return {
+        all: () => declarations,
+        byId: id => index.get(id),
+        sites: () => sites,
+        admits,
+        dueAt: ({ held, trigger, route }) => sites.filter(site => site.trigger === trigger && admits({ site, held, route }))
+    };
+}
+//# sourceMappingURL=registry.js.map

package/dist/menders/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/menders/registry.ts"],"names":[],"mappings":"AAgEA;;;;;;;;;GASG;AACH,MAAM,UAAU,eAAe,CAAC,EAC9B,IAAI,EAGL;IACC,OAAO,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,SAAS,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAA;AACpD,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,cAAc,CAI5B,EACA,YAAY,EACZ,KAAK,EAIN;IACC,MAAM,KAAK,GAAG,IAAI,GAAG,EAAqD,CAAA;IAC1E,KAAK,MAAM,IAAI,IAAI,YAAY,EAAE,CAAC;QAChC,IAAI,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC;YACvB,MAAM,IAAI,SAAS,CAAC,mCAAmC,IAAI,CAAC,EAAE,EAAE,CAAC,CAAA;QACnE,CAAC;QACD,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,EAAE,IAAI,CAAC,CAAA;IAC1B,CAAC;IACD,MAAM,eAAe,GAAG,CACtB,EAAe,EACuB,EAAE;QACxC,MAAM,IAAI,GAAG,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,CAAA;QAC1B,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,MAAM,IAAI,SAAS,CACjB,mDAAmD,EAAE,EAAE,CACxD,CAAA;QACH,CAAC;QACD,OAAO,IAAI,CAAA;IACb,CAAC,CAAA;IACD,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,eAAe,CAAC,CAAA;QACrC,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,GAAG,IAAI,CAAA;QACnC,IAAI,SAAS,KAAK,SAAS,IAAI,OAAO,KAAK,eAAe,EAAE,CAAC;YAC3D,MAAM,IAAI,SAAS,CACjB,KAAK,OAAO,sDAAsD,CACnE,CAAA;QACH,CAAC;IACH,CAAC;IACD,MAAM,MAAM,GAAG,CAAC,EACd,IAAI,EACJ,IAAI,EACJ,KAAK,EAKN,EAAW,EAAE,CACZ,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE;QACtB,MAAM,IAAI,GAAG,eAAe,CAAC,EAAE,CAAC,CAAA;QAChC,OAAO,CACL,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC;YAC7B,CAAC,KAAK,KAAK,SAAS,IAAI,CAAC,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CACxD,CAAA;IACH,CAAC,CAAC,CAAA;IACJ,OAAO;QACL,GAAG,EAAE,GAAG,EAAE,CAAC,YAAY;QACvB,IAAI,EAAE,EAAE,CAAC,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;QACzB,KAAK,EAAE,GAAG,EAAE,CAAC,KAAK;QAClB,MAAM;QACN,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,EAAE,EAAE,CAClC,KAAK,CAAC,MAAM,CACV,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,OAAO,KAAK,OAAO,IAAI,MAAM,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAClE;KACJ,CAAA;AACH,CAAC"}

package/dist/menders/runner.d.ts

@@ -0,0 +1,143 @@
+/*!
+ * Copyright (c) 2026 Interop Alliance. All rights reserved.
+ */
+/**
+ * The mender runner: one try, warn, and skip discipline over the
+ * registrations listed under one chain trigger. `runMenderBlock` runs them
+ * in list order, since registration order is execution order and there is
+ * no dependency graph. A seed step's failure aborts the block; a
+ * registration's failure warns through the wallet's own `Logger` and the
+ * block continues. Beside it sits `mendReportAccumulator`, the report
+ * collector a wallet creates before a `Session` exists, so the entries a
+ * routing site reports and the entries this runner reports assemble into
+ * one `MendReport`.
+ */
+import type { Logger } from '../log.js';
+import type { MenderRegistry } from './registry.js';
+import type { LoginRoute, MendReport, MendReportEntry, Registration, RegistrationSite } from './types.js';
+import type { Authority, ChainTrigger } from './vocabulary.js';
+/**
+ * The `errorName` a normalized entry carries when a registration resolves
+ * with entries that do not match the invariants it reports.
+ */
+export declare const MEND_REPORT_SHAPE_ERROR = "MendReportShapeError";
+/**
+ * The report collector a wallet creates ahead of session assembly. A
+ * routing entry reports into it from its own call site before a `Session`
+ * exists, {@link runMenderBlock} reports the chain's entries into it
+ * through `onOutcome`, and the wallet hands `settled` to the session as its
+ * mend report.
+ */
+export interface MendReportAccumulator<Ceremony extends string = string> {
+    /**
+     * Records one entry. Bound to the accumulator, so it can be passed
+     * directly as {@link runMenderBlock}'s `onOutcome`.
+     */
+    report(entry: MendReportEntry<Ceremony>): void;
+    /**
+     * Every entry recorded so far, in report order.
+     */
+    entries(): MendReport<Ceremony>;
+    /**
+     * Resolves {@link MendReportAccumulator.settled} with the entries
+     * recorded so far. Idempotent: the first call fixes the resolved report,
+     * and a later `report` call still lands in `entries()`.
+     */
+    settle(): MendReport<Ceremony>;
+    /**
+     * The assembled report, resolved by `settle`. It never rejects.
+     */
+    readonly settled: Promise<MendReport<Ceremony>>;
+}
+/**
+ * Creates a report accumulator. Generic over the wallet's ceremony-id
+ * union, which defaults to `string`.
+ *
+ * @returns {MendReportAccumulator}
+ */
+export declare function mendReportAccumulator<Ceremony extends string = string>(): MendReportAccumulator<Ceremony>;
+/**
+ * Runs one registration block: the registrations listed under `trigger`
+ * whose every reported invariant declares an authority the session holds
+ * and admits this login route, in list order.
+ *
+ * The discipline, in one place. An optional `seed` registration runs first,
+ * and its failure aborts the block: nothing behind it runs, which is what a
+ * rejected chain seed does today. Past the seed, a registration that throws
+ * warns once per reported invariant with that declaration's own `warn`
+ * string, reports `failed` for each of them, and the block carries on to
+ * the next registration. Only `err.name` rides a report: a thrown error's
+ * message routinely carries a DID or a Space id, so the error itself goes
+ * to the logger alone.
+ *
+ * A registration that resolves with the wrong number of entries, or with an
+ * entry whose `invariant` is not the id it reports at that position, is a
+ * programming error. It warns and is normalized to `failed` entries
+ * carrying {@link MEND_REPORT_SHAPE_ERROR} rather than throwing, so a
+ * mismatched adapter cannot tear a login.
+ *
+ * `trigger` is one of the two chain values, so a `ceremony-tail` entry is
+ * out of reach here. Such an entry has no registration at all: its body
+ * stays inside its ceremony's sequenced code and it reports from there.
+ *
+ * `Deps` is the wallet's own type, one object per registration block,
+ * handed to the seed and to every `converge` unread. This runner never
+ * inspects it, and the raw passphrase does not cross into this package.
+ *
+ * `registrations` overrides which registrations the block runs, for a wallet
+ * that runs one trigger's list in parts (a settle point partway through, say).
+ * The same authority and route tests still admit each one, and one listed
+ * under another trigger is refused, so the override narrows the block and
+ * never widens it.
+ *
+ * A registry may index converge-free sites beside its registrations -- a
+ * wallet's routing entries, or an entry whose own call site fires it -- and
+ * such a site is never executed here, whichever list the block runs from.
+ *
+ * @param options {object}
+ * @param options.registry {MenderRegistry}   the wallet's declarations and
+ *   its registrations
+ * @param options.trigger {ChainTrigger}   which chain is running
+ * @param options.held {ReadonlyArray<Authority>}   the session's held
+ *   authorities, from `heldAuthorities`
+ * @param options.route {LoginRoute}   the login route each declaration's
+ *   `when` predicate reads
+ * @param options.deps {Deps}   passed to the seed and to every `converge`
+ * @param options.logger {Logger}   the wallet's own sink, so its warn
+ *   copy keeps the wallet's namespace
+ * @param [options.registrations] {ReadonlyArray<Registration>}   the
+ *   registrations to run, in place of the ones the registry lists under
+ *   `trigger`. Each is admitted by the same authority and route tests
+ * @param [options.seed] {Registration}   the step whose failure aborts the
+ *   block. Admitted by the same authority and route tests as any other
+ *   registration; one it does not pass is skipped rather than failed
+ * @param [options.onOutcome] {(entry: MendReportEntry) => void}   called
+ *   once per reported entry, in order. The single place a chain entry's
+ *   outcome is reported
+ * @returns {Promise<MendReport>}   the block's entries in order. It never
+ *   rejects; a seed failure resolves with the seed's `failed` entries alone
+ * @throws {TypeError}   when the seed or an override registration is listed
+ *   under a trigger other than `trigger`, a programming error
+ */
+export declare function runMenderBlock<Deps, Ceremony extends string = string, Site extends RegistrationSite = Registration<Deps, Ceremony>>({ registry, trigger, held, route, deps, logger, registrations, seed, onOutcome }: {
+    registry: MenderRegistry<Site, Deps, Ceremony>;
+    trigger: ChainTrigger;
+    held: ReadonlyArray<Authority>;
+    route: LoginRoute;
+    deps: Deps;
+    logger: Logger;
+    registrations?: ReadonlyArray<Registration<Deps, Ceremony>>;
+    seed?: Registration<Deps, Ceremony>;
+    onOutcome?: (entry: MendReportEntry<Ceremony>) => void;
+}): Promise<MendReport<Ceremony>>;
+/**
+ * The thrown value's class name alone. Its message may carry a DID or a
+ * Space id, so a report keeps the name and the logger keeps the error. A
+ * value that is not an `Error` still yields a name, so a report site never
+ * carries `undefined` where a name belongs.
+ *
+ * @param err {unknown}
+ * @returns {string}
+ */
+export declare function errorNameOf(err: unknown): string;
+//# sourceMappingURL=runner.d.ts.map

package/dist/menders/runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../../src/menders/runner.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;GAUG;AACH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAA;AACvC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAA;AACnD,OAAO,KAAK,EACV,UAAU,EACV,UAAU,EACV,eAAe,EACf,YAAY,EACZ,gBAAgB,EACjB,MAAM,YAAY,CAAA;AACnB,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAE9D;;;GAGG;AACH,eAAO,MAAM,uBAAuB,yBAAyB,CAAA;AAE7D;;;;;;GAMG;AACH,MAAM,WAAW,qBAAqB,CAAC,QAAQ,SAAS,MAAM,GAAG,MAAM;IACrE;;;OAGG;IACH,MAAM,CAAC,KAAK,EAAE,eAAe,CAAC,QAAQ,CAAC,GAAG,IAAI,CAAA;IAC9C;;OAEG;IACH,OAAO,IAAI,UAAU,CAAC,QAAQ,CAAC,CAAA;IAC/B;;;;OAIG;IACH,MAAM,IAAI,UAAU,CAAC,QAAQ,CAAC,CAAA;IAC9B;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,CAAA;CAChD;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,SAAS,MAAM,GAAG,MAAM,KAC7B,qBAAqB,CAAC,QAAQ,CAAC,CAqBnC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8DG;AACH,wBAAsB,cAAc,CAClC,IAAI,EACJ,QAAQ,SAAS,MAAM,GAAG,MAAM,EAChC,IAAI,SAAS,gBAAgB,GAAG,YAAY,CAAC,IAAI,EAAE,QAAQ,CAAC,EAC5D,EACA,QAAQ,EACR,OAAO,EACP,IAAI,EACJ,KAAK,EACL,IAAI,EACJ,MAAM,EACN,aAAa,EACb,IAAI,EACJ,SAAS,EACV,EAAE;IACD,QAAQ,EAAE,cAAc,CAAC,IAAI,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAA;IAC9C,OAAO,EAAE,YAAY,CAAA;IACrB,IAAI,EAAE,aAAa,CAAC,SAAS,CAAC,CAAA;IAC9B,KAAK,EAAE,UAAU,CAAA;IACjB,IAAI,EAAE,IAAI,CAAA;IACV,MAAM,EAAE,MAAM,CAAA;IACd,aAAa,CAAC,EAAE,aAAa,CAAC,YAAY,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAA;IAC3D,IAAI,CAAC,EAAE,YAAY,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAA;IACnC,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,eAAe,CAAC,QAAQ,CAAC,KAAK,IAAI,CAAA;CACvD,GAAG,OAAO,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,CAqChC;AA6HD;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAQhD"}

package/dist/menders/runner.js

@@ -0,0 +1,222 @@
+/**
+ * The `errorName` a normalized entry carries when a registration resolves
+ * with entries that do not match the invariants it reports.
+ */
+export const MEND_REPORT_SHAPE_ERROR = 'MendReportShapeError';
+/**
+ * Creates a report accumulator. Generic over the wallet's ceremony-id
+ * union, which defaults to `string`.
+ *
+ * @returns {MendReportAccumulator}
+ */
+export function mendReportAccumulator() {
+    const recorded = [];
+    let resolveSettled = () => undefined;
+    const settled = new Promise(resolve => {
+        resolveSettled = resolve;
+    });
+    let assembled;
+    return {
+        report(entry) {
+            recorded.push(entry);
+        },
+        entries: () => [...recorded],
+        settle() {
+            if (!assembled) {
+                assembled = [...recorded];
+                resolveSettled(assembled);
+            }
+            return assembled;
+        },
+        settled
+    };
+}
+/**
+ * Runs one registration block: the registrations listed under `trigger`
+ * whose every reported invariant declares an authority the session holds
+ * and admits this login route, in list order.
+ *
+ * The discipline, in one place. An optional `seed` registration runs first,
+ * and its failure aborts the block: nothing behind it runs, which is what a
+ * rejected chain seed does today. Past the seed, a registration that throws
+ * warns once per reported invariant with that declaration's own `warn`
+ * string, reports `failed` for each of them, and the block carries on to
+ * the next registration. Only `err.name` rides a report: a thrown error's
+ * message routinely carries a DID or a Space id, so the error itself goes
+ * to the logger alone.
+ *
+ * A registration that resolves with the wrong number of entries, or with an
+ * entry whose `invariant` is not the id it reports at that position, is a
+ * programming error. It warns and is normalized to `failed` entries
+ * carrying {@link MEND_REPORT_SHAPE_ERROR} rather than throwing, so a
+ * mismatched adapter cannot tear a login.
+ *
+ * `trigger` is one of the two chain values, so a `ceremony-tail` entry is
+ * out of reach here. Such an entry has no registration at all: its body
+ * stays inside its ceremony's sequenced code and it reports from there.
+ *
+ * `Deps` is the wallet's own type, one object per registration block,
+ * handed to the seed and to every `converge` unread. This runner never
+ * inspects it, and the raw passphrase does not cross into this package.
+ *
+ * `registrations` overrides which registrations the block runs, for a wallet
+ * that runs one trigger's list in parts (a settle point partway through, say).
+ * The same authority and route tests still admit each one, and one listed
+ * under another trigger is refused, so the override narrows the block and
+ * never widens it.
+ *
+ * A registry may index converge-free sites beside its registrations -- a
+ * wallet's routing entries, or an entry whose own call site fires it -- and
+ * such a site is never executed here, whichever list the block runs from.
+ *
+ * @param options {object}
+ * @param options.registry {MenderRegistry}   the wallet's declarations and
+ *   its registrations
+ * @param options.trigger {ChainTrigger}   which chain is running
+ * @param options.held {ReadonlyArray<Authority>}   the session's held
+ *   authorities, from `heldAuthorities`
+ * @param options.route {LoginRoute}   the login route each declaration's
+ *   `when` predicate reads
+ * @param options.deps {Deps}   passed to the seed and to every `converge`
+ * @param options.logger {Logger}   the wallet's own sink, so its warn
+ *   copy keeps the wallet's namespace
+ * @param [options.registrations] {ReadonlyArray<Registration>}   the
+ *   registrations to run, in place of the ones the registry lists under
+ *   `trigger`. Each is admitted by the same authority and route tests
+ * @param [options.seed] {Registration}   the step whose failure aborts the
+ *   block. Admitted by the same authority and route tests as any other
+ *   registration; one it does not pass is skipped rather than failed
+ * @param [options.onOutcome] {(entry: MendReportEntry) => void}   called
+ *   once per reported entry, in order. The single place a chain entry's
+ *   outcome is reported
+ * @returns {Promise<MendReport>}   the block's entries in order. It never
+ *   rejects; a seed failure resolves with the seed's `failed` entries alone
+ * @throws {TypeError}   when the seed or an override registration is listed
+ *   under a trigger other than `trigger`, a programming error
+ */
+export async function runMenderBlock({ registry, trigger, held, route, deps, logger, registrations, seed, onOutcome }) {
+    const report = [];
+    const collect = (entries) => {
+        for (const entry of entries) {
+            report.push(entry);
+            onOutcome?.(entry);
+        }
+    };
+    for (const supplied of [...(seed ? [seed] : []), ...(registrations ?? [])]) {
+        if (supplied.trigger !== trigger) {
+            throw new TypeError(`A ${supplied.trigger} registration was handed to the ${trigger} block`);
+        }
+    }
+    const admitted = (site) => registry.admits({ site, held, route });
+    const listed = (registrations?.filter(admitted) ?? registry.dueAt({ held, trigger, route })).filter((isRegistration));
+    // One ordered list, the seed first: the seed is the one step whose throw
+    // ends the block.
+    const steps = seed && admitted(seed) ? [seed, ...listed] : listed;
+    for (const registration of steps) {
+        const outcome = await runRegistration({
+            registry,
+            registration,
+            deps,
+            logger,
+            trigger
+        });
+        collect(outcome.entries);
+        if (outcome.threw && registration === seed) {
+            return report;
+        }
+    }
+    return report;
+}
+/**
+ * Runs one registration under the block's discipline, returning its entries
+ * and whether it threw.
+ */
+async function runRegistration({ registry, registration, deps, logger, trigger }) {
+    try {
+        const entries = await registration.converge(deps);
+        if (!matchesReports({ registration, entries })) {
+            logger.warn('A mender registration returned entries that do not match the invariants it reports', { trigger, reports: [...registration.reports] });
+            // A malformed return is a defect in the adapter rather than a mend
+            // failure: the step ran to completion, so a malformed seed does not
+            // abort the block.
+            return {
+                entries: failedEntries({
+                    registry,
+                    registration,
+                    errorName: MEND_REPORT_SHAPE_ERROR
+                }),
+                threw: false
+            };
+        }
+        return { entries, threw: false };
+    }
+    catch (err) {
+        for (const id of registration.reports) {
+            logger.warn(registry.byId(id)?.warn ?? `Could not converge ${id}`, {
+                invariant: id,
+                trigger,
+                err
+            });
+        }
+        return {
+            entries: failedEntries({
+                registry,
+                registration,
+                errorName: errorNameOf(err)
+            }),
+            threw: true
+        };
+    }
+}
+/**
+ * Whether a site carries a converger, so the block can run it. A wallet's
+ * registry indexes its converge-free sites beside its registrations.
+ *
+ * @param site {RegistrationSite}
+ * @returns {boolean}
+ */
+function isRegistration(site) {
+    return typeof site.converge === 'function';
+}
+/**
+ * Whether a registration's entries name the invariants it reports, in that
+ * order.
+ */
+function matchesReports({ registration, entries }) {
+    return (entries.length === registration.reports.length &&
+        entries.every((entry, index) => entry.invariant === registration.reports[index]));
+}
+/**
+ * One `failed` entry per reported invariant, carrying the declaration's
+ * ceremonies where it names any.
+ */
+function failedEntries({ registry, registration, errorName }) {
+    return registration.reports.map(id => {
+        const ceremonies = registry.byId(id)?.ceremonies;
+        return {
+            invariant: id,
+            outcome: 'failed',
+            errorName,
+            ...(ceremonies && ceremonies.length > 0 ? { ceremonies } : {})
+        };
+    });
+}
+/**
+ * The thrown value's class name alone. Its message may carry a DID or a
+ * Space id, so a report keeps the name and the logger keeps the error. A
+ * value that is not an `Error` still yields a name, so a report site never
+ * carries `undefined` where a name belongs.
+ *
+ * @param err {unknown}
+ * @returns {string}
+ */
+export function errorNameOf(err) {
+    if (err instanceof Error) {
+        return err.name;
+    }
+    if (typeof err === 'object' && err !== null && 'name' in err) {
+        return String(err.name);
+    }
+    return 'Error';
+}
+//# sourceMappingURL=runner.js.map

package/dist/menders/runner.js.map

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