ftown 0.20.9 → 0.24.0

package/dist/ledger-reoffer.d.ts

@@ -0,0 +1,56 @@
+import type { LedgerOfferOutcome, ServerLedgerRead } from './security/bridge/security.js';
+export declare const REOFFER_PAIR_WINDOW_MS = 30000;
+/** At most one POST per this interval, whatever the (our head, server head) pair. */
+export declare const REOFFER_MIN_POST_SPACING_MS = 30000;
+/** After a 404 (the server does not know the account), nothing is posted for this long unless a read finds the account again. */
+export declare const REOFFER_UNKNOWN_ACCOUNT_PAUSE_MS = 3600000;
+export declare const REOFFER_FIRST_BACKOFF_MS = 30000;
+export declare const REOFFER_MAX_BACKOFF_MS = 600000;
+export declare const REOFFER_MAX_RETRY_AFTER_MS = 3600000;
+/** Each backoff wait is multiplied by 1 - REOFFER_JITTER + 2 * REOFFER_JITTER * random(). */
+export declare const REOFFER_JITTER = 0.2;
+/** The server's answer to POST /api/account/ledger { ledger, expectHead }. */
+export interface LedgerPostAnswer {
+    status: number;
+    /** The parsed JSON body, or null when it is absent, oversized or not JSON. */
+    body: unknown;
+    /** Retry-After in ms (seconds or an HTTP date), or null. */
+    retryAfterMs: number | null;
+}
+export interface LedgerReofferDeps {
+    /** A fresh read of the server's chain, offered to the replica as 'server' (BridgeSecurityService.readServerLedger). */
+    read(): Promise<ServerLedgerRead>;
+    /** The stored chain and its head; null when there is nothing this bridge may send (no chain, or this bridge is not active in it). */
+    local(): Promise<{
+        ledger: unknown;
+        head: string;
+    } | null>;
+    /** POST /api/account/ledger { ledger, expectHead }. Throws on a network failure. */
+    post(ledger: unknown, expectHead: string): Promise<LedgerPostAnswer>;
+    /** Offers a chain the server answered with to the replica as 'server'. */
+    offer(ledger: unknown): Promise<LedgerOfferOutcome>;
+    /** Monotonic clock (ms). */
+    now(): number;
+    /** [0, 1), for the jitter. */
+    random(): number;
+    /** Timer; returns a cancel function. */
+    schedule(run: () => void, ms: number): () => void;
+    log(line: string): void;
+}
+/** posted: the server answered 2xx (the next read confirms it). not_behind: nothing to send. skipped: the pair, or any POST, was sent less
+ *  than 30 s ago. failed: backing off. deferred: an earlier failure's wait has not passed (a retry is scheduled). stopped: shut down, or
+ *  paused after the server said it does not know the account. */
+export type ReofferOutcome = 'posted' | 'not_behind' | 'skipped' | 'failed' | 'deferred' | 'stopped';
+export interface LedgerReoffer {
+    /** A server read showed the server holding a strict prefix of our chain (so the server knows the account: a 404 pause ends): start one
+     *  paced attempt (it reads again before it posts). */
+    noteServerBehind(): void;
+    /** Runs an attempt now unless one is running (joined) or a backoff wait is pending ('deferred'); for a relay token refused with a plain
+     *  401, which may mean the server lacks our records. It posts only when its own fresh read says 'behind'. */
+    check(): Promise<ReofferOutcome>;
+    /** Cancels the retry timer; nothing runs afterwards. */
+    stop(): void;
+}
+/** The backoff wait after `failures` failed attempts in a row (>= 1), for a given random() draw. */
+export declare function reofferBackoffMs(failures: number, random: number): number;
+export declare function createLedgerReoffer(deps: LedgerReofferDeps): LedgerReoffer;

package/dist/ledger-reoffer.js

@@ -0,0 +1,210 @@
+export const REOFFER_PAIR_WINDOW_MS = 30_000;
+/** At most one POST per this interval, whatever the (our head, server head) pair. */
+export const REOFFER_MIN_POST_SPACING_MS = 30_000;
+/** After a 404 (the server does not know the account), nothing is posted for this long unless a read finds the account again. */
+export const REOFFER_UNKNOWN_ACCOUNT_PAUSE_MS = 3_600_000;
+export const REOFFER_FIRST_BACKOFF_MS = 30_000;
+export const REOFFER_MAX_BACKOFF_MS = 600_000;
+export const REOFFER_MAX_RETRY_AFTER_MS = 3_600_000;
+/** Each backoff wait is multiplied by 1 - REOFFER_JITTER + 2 * REOFFER_JITTER * random(). */
+export const REOFFER_JITTER = 0.2;
+/** The backoff wait after `failures` failed attempts in a row (>= 1), for a given random() draw. */
+export function reofferBackoffMs(failures, random) {
+    const base = Math.min(REOFFER_FIRST_BACKOFF_MS * 2 ** Math.max(0, failures - 1), REOFFER_MAX_BACKOFF_MS);
+    return Math.round(base * (1 - REOFFER_JITTER + 2 * REOFFER_JITTER * random));
+}
+const messageOf = (error) => error instanceof Error ? error.message : String(error);
+const field = (body, key) => typeof body === 'object' && body !== null && !Array.isArray(body) ? body[key] : undefined;
+export function createLedgerReoffer(deps) {
+    let running = null;
+    let failures = 0;
+    /** Monotonic time before which no attempt starts (after a failure). */
+    let readyAt = Number.NEGATIVE_INFINITY;
+    let cancelTimer = null;
+    let stopped = false;
+    /** The server said it does not know this account: no attempt before this monotonic time (unless a read finds the account). */
+    let pausedUntil = Number.NEGATIVE_INFINITY;
+    /** The last POST (any pair), for the global floor. */
+    let lastPostAt = Number.NEGATIVE_INFINITY;
+    /** The last POST was answered 2xx: the next read must no longer show the server behind, else that counts as a failure. */
+    let confirming = false;
+    /** (our head, server head) -> when it was last posted. */
+    const sent = new Map();
+    /** Local heads whose ledger_rejected answer was logged. */
+    const rejectedLogged = new Set();
+    const cancel = () => { cancelTimer?.(); cancelTimer = null; };
+    const paused = () => deps.now() < pausedUntil;
+    /** (Re)arms the one retry timer: an attempt `ms` from now, unless one is running then. */
+    const arm = (ms) => {
+        cancel();
+        if (stopped)
+            return;
+        cancelTimer = deps.schedule(() => { cancelTimer = null; if (running === null)
+            void start(); }, Math.max(0, ms));
+    };
+    const settled = (outcome) => {
+        failures = 0;
+        readyAt = Number.NEGATIVE_INFINITY;
+        cancel();
+        return outcome;
+    };
+    const failed = (reason, retryAfterMs = null, quiet = false) => {
+        failures += 1;
+        let wait = reofferBackoffMs(failures, deps.random());
+        if (retryAfterMs !== null && retryAfterMs > wait)
+            wait = Math.min(retryAfterMs, REOFFER_MAX_RETRY_AFTER_MS);
+        readyAt = deps.now() + wait;
+        // The first failure at each larger step is logged; once the wait stops growing, the bridge stays quiet.
+        const grew = failures === 1 || reofferBackoffMs(failures, 0.5) > reofferBackoffMs(failures - 1, 0.5);
+        if (!quiet && grew)
+            deps.log(`[ledger] could not send our account history to the server (${reason}); retrying in ${Math.round(wait / 1000)} s`);
+        arm(wait);
+        return 'failed';
+    };
+    const unknownAccount = () => {
+        if (!paused())
+            deps.log('[ledger] the server does not know this account (404); this computer will not send its account history to it for an hour');
+        pausedUntil = deps.now() + REOFFER_UNKNOWN_ACCOUNT_PAUSE_MS;
+        confirming = false;
+        failures = 0;
+        readyAt = Number.NEGATIVE_INFINITY;
+        cancel();
+        return 'stopped';
+    };
+    const offerQuietly = async (ledger) => {
+        try {
+            return await deps.offer(ledger);
+        }
+        catch {
+            return null;
+        }
+    };
+    const send = async (serverHead) => {
+        const local = await deps.local();
+        if (local === null)
+            return settled('not_behind');
+        const now = deps.now();
+        for (const [key, at] of sent)
+            if (now < at || now - at >= REOFFER_PAIR_WINDOW_MS)
+                sent.delete(key);
+        const pair = `${local.head}\n${serverHead}`;
+        const pairAt = sent.get(pair);
+        // Both floors, after the fresh read: this pair at most once per 30 s, and any POST at most once per 30 s.
+        const floorAt = now >= lastPostAt ? lastPostAt + REOFFER_MIN_POST_SPACING_MS : Number.NEGATIVE_INFINITY;
+        const until = Math.max(pairAt === undefined ? Number.NEGATIVE_INFINITY : pairAt + REOFFER_PAIR_WINDOW_MS, floorAt);
+        if (until > now) {
+            // A retry after a failure can come back before a floor ends (the first wait may be 24 s): try again when it does.
+            if (failures > 0)
+                arm(until - now);
+            return 'skipped';
+        }
+        sent.set(pair, now);
+        lastPostAt = now;
+        let answer;
+        try {
+            answer = await deps.post(local.ledger, serverHead);
+        }
+        catch (error) {
+            return failed(messageOf(error));
+        }
+        if (stopped)
+            return 'stopped';
+        const { status, body } = answer;
+        const error = field(body, 'error');
+        const chain = field(body, 'ledger');
+        const answered = typeof chain === 'object' && chain !== null;
+        if (status >= 200 && status < 300) {
+            if (answered)
+                await offerQuietly(chain);
+            // Not settled yet: the next read must show the server holding our chain.
+            confirming = true;
+            return 'posted';
+        }
+        if (status === 404)
+            return unknownAccount();
+        if (status === 409 && error === 'head_changed') {
+            // Another write landed since our read: judge the server's chain; if it is still a prefix of ours, the retry reads and sends again.
+            const outcome = answered ? await offerQuietly(chain) : null;
+            if (outcome !== null && outcome.decision !== 'reject' && outcome.relation !== 'behind')
+                return settled('not_behind');
+            return failed('head_changed');
+        }
+        if (status === 409 && error === 'diverged') {
+            if (answered)
+                await offerQuietly(chain);
+            return failed('the server holds a different history');
+        }
+        if (status === 409 && error === 'ledger_rejected') {
+            const first = !rejectedLogged.has(local.head);
+            rejectedLogged.add(local.head);
+            if (first)
+                deps.log('[ledger] the server rejected our account history; retrying later');
+            return failed('ledger_rejected', null, true);
+        }
+        if (status === 429)
+            return failed('rate limited', answer.retryAfterMs);
+        return failed(`HTTP ${status}`);
+    };
+    const attempt = async () => {
+        if (stopped)
+            return 'stopped';
+        if (paused())
+            return 'stopped';
+        const read = await deps.read();
+        if (stopped)
+            return 'stopped';
+        if (read.kind === 'unknown_account')
+            return unknownAccount();
+        if (read.kind === 'failed')
+            return failed(`read failed: ${read.reason}`);
+        // The account is there again.
+        pausedUntil = Number.NEGATIVE_INFINITY;
+        const { relation, head } = read.outcome;
+        const wasConfirming = confirming;
+        confirming = false;
+        if (relation !== 'behind' || head === null)
+            return settled('not_behind');
+        // The server answered 2xx to our last POST, yet still lacks our records: a hostile or broken server, not progress.
+        if (wasConfirming)
+            return failed('the server accepted our history but still lacks it');
+        return send(head);
+    };
+    const start = () => {
+        const run = attempt().catch((error) => failed(messageOf(error)));
+        running = run.finally(() => { running = null; });
+        return running;
+    };
+    return {
+        noteServerBehind() {
+            if (stopped)
+                return;
+            // The caller's read found the account: a 404 pause is over.
+            pausedUntil = Number.NEGATIVE_INFINITY;
+            if (running !== null || cancelTimer !== null)
+                return;
+            const wait = readyAt - deps.now();
+            if (wait > 0)
+                arm(wait);
+            else
+                void start();
+        },
+        check() {
+            if (stopped || paused())
+                return Promise.resolve('stopped');
+            if (running !== null)
+                return running;
+            if (readyAt - deps.now() > 0) {
+                if (cancelTimer === null)
+                    arm(readyAt - deps.now());
+                return Promise.resolve('deferred');
+            }
+            cancel();
+            return start();
+        },
+        stop() {
+            stopped = true;
+            cancel();
+        },
+    };
+}
+//# sourceMappingURL=ledger-reoffer.js.map

package/dist/ledger-reoffer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ledger-reoffer.js","sourceRoot":"","sources":["../src/ledger-reoffer.ts"],"names":[],"mappings":"AAoBA,MAAM,CAAC,MAAM,sBAAsB,GAAG,MAAM,CAAC;AAC7C,qFAAqF;AACrF,MAAM,CAAC,MAAM,2BAA2B,GAAG,MAAM,CAAC;AAClD,iIAAiI;AACjI,MAAM,CAAC,MAAM,gCAAgC,GAAG,SAAS,CAAC;AAC1D,MAAM,CAAC,MAAM,wBAAwB,GAAG,MAAM,CAAC;AAC/C,MAAM,CAAC,MAAM,sBAAsB,GAAG,OAAO,CAAC;AAC9C,MAAM,CAAC,MAAM,0BAA0B,GAAG,SAAS,CAAC;AACpD,6FAA6F;AAC7F,MAAM,CAAC,MAAM,cAAc,GAAG,GAAG,CAAC;AA6ClC,oGAAoG;AACpG,MAAM,UAAU,gBAAgB,CAAC,QAAgB,EAAE,MAAc;IAC/D,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,wBAAwB,GAAG,CAAC,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,QAAQ,GAAG,CAAC,CAAC,EAAE,sBAAsB,CAAC,CAAC;IACzG,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,GAAG,CAAC,CAAC,GAAG,cAAc,GAAG,CAAC,GAAG,cAAc,GAAG,MAAM,CAAC,CAAC,CAAC;AAC/E,CAAC;AAED,MAAM,SAAS,GAAG,CAAC,KAAc,EAAU,EAAE,CAAC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AACrG,MAAM,KAAK,GAAG,CAAC,IAAa,EAAE,GAAW,EAAW,EAAE,CACpD,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAE,IAAgC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AAEzH,MAAM,UAAU,mBAAmB,CAAC,IAAuB;IACzD,IAAI,OAAO,GAAmC,IAAI,CAAC;IACnD,IAAI,QAAQ,GAAG,CAAC,CAAC;IACjB,uEAAuE;IACvE,IAAI,OAAO,GAAG,MAAM,CAAC,iBAAiB,CAAC;IACvC,IAAI,WAAW,GAAwB,IAAI,CAAC;IAC5C,IAAI,OAAO,GAAG,KAAK,CAAC;IACpB,8HAA8H;IAC9H,IAAI,WAAW,GAAG,MAAM,CAAC,iBAAiB,CAAC;IAC3C,sDAAsD;IACtD,IAAI,UAAU,GAAG,MAAM,CAAC,iBAAiB,CAAC;IAC1C,0HAA0H;IAC1H,IAAI,UAAU,GAAG,KAAK,CAAC;IACvB,0DAA0D;IAC1D,MAAM,IAAI,GAAG,IAAI,GAAG,EAAkB,CAAC;IACvC,2DAA2D;IAC3D,MAAM,cAAc,GAAG,IAAI,GAAG,EAAU,CAAC;IAEzC,MAAM,MAAM,GAAG,GAAS,EAAE,GAAG,WAAW,EAAE,EAAE,CAAC,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;IACpE,MAAM,MAAM,GAAG,GAAY,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,WAAW,CAAC;IACvD,0FAA0F;IAC1F,MAAM,GAAG,GAAG,CAAC,EAAU,EAAQ,EAAE;QAC/B,MAAM,EAAE,CAAC;QACT,IAAI,OAAO;YAAE,OAAO;QACpB,WAAW,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,EAAE,GAAG,WAAW,GAAG,IAAI,CAAC,CAAC,IAAI,OAAO,KAAK,IAAI;YAAE,KAAK,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;IAClH,CAAC,CAAC;IACF,MAAM,OAAO,GAAG,CAAC,OAAuB,EAAkB,EAAE;QAC1D,QAAQ,GAAG,CAAC,CAAC;QACb,OAAO,GAAG,MAAM,CAAC,iBAAiB,CAAC;QACnC,MAAM,EAAE,CAAC;QACT,OAAO,OAAO,CAAC;IACjB,CAAC,CAAC;IACF,MAAM,MAAM,GAAG,CAAC,MAAc,EAAE,eAA8B,IAAI,EAAE,KAAK,GAAG,KAAK,EAAkB,EAAE;QACnG,QAAQ,IAAI,CAAC,CAAC;QACd,IAAI,IAAI,GAAG,gBAAgB,CAAC,QAAQ,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;QACrD,IAAI,YAAY,KAAK,IAAI,IAAI,YAAY,GAAG,IAAI;YAAE,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,YAAY,EAAE,0BAA0B,CAAC,CAAC;QAC5G,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC;QAC5B,wGAAwG;QACxG,MAAM,IAAI,GAAG,QAAQ,KAAK,CAAC,IAAI,gBAAgB,CAAC,QAAQ,EAAE,GAAG,CAAC,GAAG,gBAAgB,CAAC,QAAQ,GAAG,CAAC,EAAE,GAAG,CAAC,CAAC;QACrG,IAAI,CAAC,KAAK,IAAI,IAAI;YAAE,IAAI,CAAC,GAAG,CAAC,8DAA8D,MAAM,kBAAkB,IAAI,CAAC,KAAK,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC;QAChJ,GAAG,CAAC,IAAI,CAAC,CAAC;QACV,OAAO,QAAQ,CAAC;IAClB,CAAC,CAAC;IACF,MAAM,cAAc,GAAG,GAAmB,EAAE;QAC1C,IAAI,CAAC,MAAM,EAAE;YAAE,IAAI,CAAC,GAAG,CAAC,yHAAyH,CAAC,CAAC;QACnJ,WAAW,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,gCAAgC,CAAC;QAC5D,UAAU,GAAG,KAAK,CAAC;QACnB,QAAQ,GAAG,CAAC,CAAC;QACb,OAAO,GAAG,MAAM,CAAC,iBAAiB,CAAC;QACnC,MAAM,EAAE,CAAC;QACT,OAAO,SAAS,CAAC;IACnB,CAAC,CAAC;IACF,MAAM,YAAY,GAAG,KAAK,EAAE,MAAe,EAAsC,EAAE;QACjF,IAAI,CAAC;YAAC,OAAO,MAAM,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QAAC,CAAC;QAAC,MAAM,CAAC;YAAC,OAAO,IAAI,CAAC;QAAC,CAAC;IACjE,CAAC,CAAC;IAEF,MAAM,IAAI,GAAG,KAAK,EAAE,UAAkB,EAA2B,EAAE;QACjE,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,KAAK,EAAE,CAAC;QACjC,IAAI,KAAK,KAAK,IAAI;YAAE,OAAO,OAAO,CAAC,YAAY,CAAC,CAAC;QACjD,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,KAAK,MAAM,CAAC,GAAG,EAAE,EAAE,CAAC,IAAI,IAAI;YAAE,IAAI,GAAG,GAAG,EAAE,IAAI,GAAG,GAAG,EAAE,IAAI,sBAAsB;gBAAE,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACnG,MAAM,IAAI,GAAG,GAAG,KAAK,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;QAC5C,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAC9B,0GAA0G;QAC1G,MAAM,OAAO,GAAG,GAAG,IAAI,UAAU,CAAC,CAAC,CAAC,UAAU,GAAG,2BAA2B,CAAC,CAAC,CAAC,MAAM,CAAC,iBAAiB,CAAC;QACxG,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,iBAAiB,CAAC,CAAC,CAAC,MAAM,GAAG,sBAAsB,EAAE,OAAO,CAAC,CAAC;QACnH,IAAI,KAAK,GAAG,GAAG,EAAE,CAAC;YAChB,kHAAkH;YAClH,IAAI,QAAQ,GAAG,CAAC;gBAAE,GAAG,CAAC,KAAK,GAAG,GAAG,CAAC,CAAC;YACnC,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;QACpB,UAAU,GAAG,GAAG,CAAC;QACjB,IAAI,MAAwB,CAAC;QAC7B,IAAI,CAAC;YAAC,MAAM,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;QAAC,CAAC;QAC3D,OAAO,KAAK,EAAE,CAAC;YAAC,OAAO,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC;QAAC,CAAC;QAClD,IAAI,OAAO;YAAE,OAAO,SAAS,CAAC;QAC9B,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,CAAC;QAChC,MAAM,KAAK,GAAG,KAAK,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QACnC,MAAM,KAAK,GAAG,KAAK,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;QACpC,MAAM,QAAQ,GAAG,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,CAAC;QAC7D,IAAI,MAAM,IAAI,GAAG,IAAI,MAAM,GAAG,GAAG,EAAE,CAAC;YAClC,IAAI,QAAQ;gBAAE,MAAM,YAAY,CAAC,KAAK,CAAC,CAAC;YACxC,yEAAyE;YACzE,UAAU,GAAG,IAAI,CAAC;YAClB,OAAO,QAAQ,CAAC;QAClB,CAAC;QACD,IAAI,MAAM,KAAK,GAAG;YAAE,OAAO,cAAc,EAAE,CAAC;QAC5C,IAAI,MAAM,KAAK,GAAG,IAAI,KAAK,KAAK,cAAc,EAAE,CAAC;YAC/C,mIAAmI;YACnI,MAAM,OAAO,GAAG,QAAQ,CAAC,CAAC,CAAC,MAAM,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;YAC5D,IAAI,OAAO,KAAK,IAAI,IAAI,OAAO,CAAC,QAAQ,KAAK,QAAQ,IAAI,OAAO,CAAC,QAAQ,KAAK,QAAQ;gBAAE,OAAO,OAAO,CAAC,YAAY,CAAC,CAAC;YACrH,OAAO,MAAM,CAAC,cAAc,CAAC,CAAC;QAChC,CAAC;QACD,IAAI,MAAM,KAAK,GAAG,IAAI,KAAK,KAAK,UAAU,EAAE,CAAC;YAC3C,IAAI,QAAQ;gBAAE,MAAM,YAAY,CAAC,KAAK,CAAC,CAAC;YACxC,OAAO,MAAM,CAAC,sCAAsC,CAAC,CAAC;QACxD,CAAC;QACD,IAAI,MAAM,KAAK,GAAG,IAAI,KAAK,KAAK,iBAAiB,EAAE,CAAC;YAClD,MAAM,KAAK,GAAG,CAAC,cAAc,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YAC9C,cAAc,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YAC/B,IAAI,KAAK;gBAAE,IAAI,CAAC,GAAG,CAAC,kEAAkE,CAAC,CAAC;YACxF,OAAO,MAAM,CAAC,iBAAiB,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;QAC/C,CAAC;QACD,IAAI,MAAM,KAAK,GAAG;YAAE,OAAO,MAAM,CAAC,cAAc,EAAE,MAAM,CAAC,YAAY,CAAC,CAAC;QACvE,OAAO,MAAM,CAAC,QAAQ,MAAM,EAAE,CAAC,CAAC;IAClC,CAAC,CAAC;IAEF,MAAM,OAAO,GAAG,KAAK,IAA6B,EAAE;QAClD,IAAI,OAAO;YAAE,OAAO,SAAS,CAAC;QAC9B,IAAI,MAAM,EAAE;YAAE,OAAO,SAAS,CAAC;QAC/B,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC;QAC/B,IAAI,OAAO;YAAE,OAAO,SAAS,CAAC;QAC9B,IAAI,IAAI,CAAC,IAAI,KAAK,iBAAiB;YAAE,OAAO,cAAc,EAAE,CAAC;QAC7D,IAAI,IAAI,CAAC,IAAI,KAAK,QAAQ;YAAE,OAAO,MAAM,CAAC,gBAAgB,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;QACzE,8BAA8B;QAC9B,WAAW,GAAG,MAAM,CAAC,iBAAiB,CAAC;QACvC,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,GAAG,IAAI,CAAC,OAAO,CAAC;QACxC,MAAM,aAAa,GAAG,UAAU,CAAC;QACjC,UAAU,GAAG,KAAK,CAAC;QACnB,IAAI,QAAQ,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI;YAAE,OAAO,OAAO,CAAC,YAAY,CAAC,CAAC;QACzE,mHAAmH;QACnH,IAAI,aAAa;YAAE,OAAO,MAAM,CAAC,oDAAoD,CAAC,CAAC;QACvF,OAAO,IAAI,CAAC,IAAI,CAAC,CAAC;IACpB,CAAC,CAAC;IAEF,MAAM,KAAK,GAAG,GAA4B,EAAE;QAC1C,MAAM,GAAG,GAAG,OAAO,EAAE,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;QAC1E,OAAO,GAAG,GAAG,CAAC,OAAO,CAAC,GAAG,EAAE,GAAG,OAAO,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;QACjD,OAAO,OAAO,CAAC;IACjB,CAAC,CAAC;IAEF,OAAO;QACL,gBAAgB;YACd,IAAI,OAAO;gBAAE,OAAO;YACpB,4DAA4D;YAC5D,WAAW,GAAG,MAAM,CAAC,iBAAiB,CAAC;YACvC,IAAI,OAAO,KAAK,IAAI,IAAI,WAAW,KAAK,IAAI;gBAAE,OAAO;YACrD,MAAM,IAAI,GAAG,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;YAClC,IAAI,IAAI,GAAG,CAAC;gBAAE,GAAG,CAAC,IAAI,CAAC,CAAC;;gBACnB,KAAK,KAAK,EAAE,CAAC;QACpB,CAAC;QACD,KAAK;YACH,IAAI,OAAO,IAAI,MAAM,EAAE;gBAAE,OAAO,OAAO,CAAC,OAAO,CAAiB,SAAS,CAAC,CAAC;YAC3E,IAAI,OAAO,KAAK,IAAI;gBAAE,OAAO,OAAO,CAAC;YACrC,IAAI,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,CAAC,EAAE,CAAC;gBAC7B,IAAI,WAAW,KAAK,IAAI;oBAAE,GAAG,CAAC,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;gBACpD,OAAO,OAAO,CAAC,OAAO,CAAiB,UAAU,CAAC,CAAC;YACrD,CAAC;YACD,MAAM,EAAE,CAAC;YACT,OAAO,KAAK,EAAE,CAAC;QACjB,CAAC;QACD,IAAI;YACF,OAAO,GAAG,IAAI,CAAC;YACf,MAAM,EAAE,CAAC;QACX,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/ledger-startup.d.ts

@@ -0,0 +1,176 @@
+import { type IdentityResetReason, type IdentityResetResult } from './identity-reset.js';
+import type { BridgeMode } from './revocation-gating.js';
+import { type LedgerBridgeIdentity } from './security/bridge/ledger-identity.js';
+import { BridgeLedgerStore, type OwnBridgeStatus, type ReconcileResult } from './security/bridge/ledger-store.js';
+import type { EndpointPublic } from './security/protocol.js';
+export declare const LEGACY_ACCOUNT_RESET_MESSAGE = "[Bridge] Old account data from a previous ftown version was cleared. Pair this computer again with the link below.";
+export declare const NOT_IN_LEDGER_MESSAGE = "This computer is not in your account's ledger. Run `ftown start --new-identity` to pair it again.";
+export declare const PAIRING_REJECTED_HINT = "Pairing did not complete. Run `ftown start` to try again.";
+export declare const PAIRING_REVOKED_MESSAGE: string;
+export declare const SERVER_LEDGER_MISMATCH_MESSAGE = "[Bridge] The server's account ledger does not list this computer. If it was removed from your account, run `ftown start --new-identity` to pair it again.";
+export declare const UPDATE_RESTART_UNPAIRED_MESSAGE = "[Bridge] An update restart cannot pair this computer. Run `ftown start` to pair it.";
+export declare const UPDATED_TO_LEDGER_MESSAGE = "[Bridge] ftown was updated to the passkey ledger; run `ftown start` to pair this computer.";
+export declare const DO_NOT_RESET_LINE = "[Bridge] Do NOT run --new-identity: this computer may hold the only copy. Open Security in the dashboard to choose a history.";
+export declare const HELD_OFFLINE_LINE = "[Bridge] Starting offline: local sessions keep working, and the relay is retried in the background.";
+export declare const HELD_NO_RELAY_URL_LINE = "[Bridge] No relay URL was saved by an earlier start, so this computer cannot start offline. Run `ftown start` again later.";
+/** What this computer holds that the server lacks (BridgeSecurityService.uniqueHistory), for the held-history notice. */
+export interface HeldHistory {
+    afterRevision: number;
+    records: number;
+    removals: number;
+    passkeys: number;
+}
+/** Printed once when the server refuses the key of a computer that is an active member of its own history (step 5): never reset advice. */
+export declare function heldHistoryNotice(unique: HeldHistory | null): string[];
+/** Only account bridges use the passkey ledger (legacy reset, pairing, ledger replica, relay token by proof). */
+export declare function usesLedger(mode: BridgeMode): boolean;
+export interface IdentityResetDeps {
+    hasLegacyAccountState: (dataDir: string) => boolean;
+    beginIdentityReset: (dataDir: string, reason: IdentityResetReason) => void;
+    completePendingIdentityReset: (dataDir: string) => IdentityResetResult | null;
+}
+export type IdentityResetOutcome = {
+    kind: 'continue';
+    reset: IdentityResetResult | null;
+}
+/** Exit 1 after printing `message`; nothing was changed on disk. */
+ | {
+    kind: 'exit';
+    message: string;
+};
+/**
+ * Step 2. Account mode: `--new-identity`, or any v1 account state on disk, starts a manual reset (the latter says so in one line).
+ * An update restart (a v1 -> v2 auto-update) has no visible terminal for the pairing link: with v1 state on disk it changes nothing
+ * and exits, and the next `ftown start` resets and pairs. Every mode then finishes a pending reset, as before (a revoked restart or a
+ * crash may have left one).
+ */
+export declare function resetIdentityForStart(input: {
+    dataDir: string;
+    mode: BridgeMode;
+    newIdentity: boolean;
+    updateRestart: boolean;
+    log: (line: string) => void;
+}, deps?: Partial<IdentityResetDeps>): IdentityResetOutcome;
+export type OwnStatusAction = 'continue' | 'revoked_restart' | 'exit_absent';
+/** Step 4. Only a signed revocation resets the identity; a bridge the ledger does not list fails closed and is never reset. */
+export declare function ownStatusAction(own: OwnBridgeStatus): OwnStatusAction;
+/** A ledger identity bound to its account: endpoint and accountId are set. */
+export type BoundLedgerIdentity = LedgerBridgeIdentity & {
+    endpoint: EndpointPublic;
+    accountId: string;
+};
+export type AccountStartup = {
+    kind: 'ready';
+    identity: BoundLedgerIdentity;
+    store: BridgeLedgerStore;
+    reconciled: ReconcileResult;
+} | {
+    kind: 'revoked';
+}
+/** Exit 1 after printing `message` (null: the cause was already printed). */
+ | {
+    kind: 'exit';
+    message: string | null;
+};
+export interface AccountStartupDeps {
+    dataDir: string;
+    bridgeId: string;
+    /** False during an update restart: it must come back with its existing identity and never pair. */
+    allowPairing: boolean;
+    /** One pairing attempt (runLedgerPairing) with the unbound identity and the empty store; binds both on success. Throws
+     *  Error('pairing_expired') (its hint already printed), Error('pairing_revoked') (the account already revokes this bridge id) or
+     *  Error('pairing_rejected'). */
+    pair: (identity: LedgerBridgeIdentity, store: BridgeLedgerStore) => Promise<unknown>;
+    /** The server's ledger for this account (GET /api/account/ledger?accountId=…, bounded). */
+    fetchLedger: (accountId: string) => Promise<unknown>;
+    /** Injectable for tests. */
+    loadOrCreateIdentity?: (dataDir: string) => Promise<LedgerBridgeIdentity>;
+    reconcile?: (dataDir: string) => Promise<ReconcileResult>;
+    readIdentity?: (dataDir: string) => Promise<LedgerBridgeIdentity | null>;
+}
+export declare function ledgerUnavailableMessage(reason: string): string;
+/**
+ * Steps 3-4, account mode only, before any network use of the identity:
+ * - keys exist (created when absent), then identity and replica are reconciled;
+ * - 'unpaired' -> one pairing attempt (expired/rejected -> exit 1 with the hint);
+ * - 'needs_ledger' -> the server ledger is adopted only through adoptBound (any failure -> exit 1; the identity stays bound);
+ * - own status from the trusted replica: 'revoked' -> revoked restart; 'absent' -> exit 1 (never a reset); 'active' -> ready.
+ * Corrupted local files throw (they are never reset).
+ */
+export declare function startAccountIdentity(deps: AccountStartupDeps): Promise<AccountStartup>;
+export type RelayStartup = {
+    kind: 'revoked';
+}
+/** Exit 1 after printing `message`. */
+ | {
+    kind: 'exit';
+    message: string;
+} | {
+    kind: 'online';
+    token: string;
+    relayUrl: string;
+}
+/** The server is unreachable for now, or refused a computer that may hold the only copy of its history (`notice`, printed once instead
+ *  of the unreachable line): start with the saved relay URL and keep retrying in the background. */
+ | {
+    kind: 'offline';
+    relayUrl: string;
+    reason: string;
+    notice?: string[];
+};
+export declare function offlineWithoutRelayUrlMessage(reason: string): string;
+/**
+ * Step 5, the first relay token. A proven revocation (the token hooks offer the server's evidence first) wins over everything. A refusal
+ * (401/403) of a computer that is still an active member of its own history (`held` returns the notice: a divergence with the server, a
+ * server behind us, a failed re-offer, or any refusal without proof of our removal) starts OFFLINE and prints the notice once, never the
+ * reset advice: this computer may hold the only copy. Any other refusal (this computer is not an active member: unpaired/absent) exits
+ * with the reset advice. A temporary failure (network, timeout, 5xx, cooldown) starts offline with the saved relay URL. Without a saved
+ * relay URL there is no offline start: exit. After a successful token the revocation is checked again (the token response's ledger may
+ * prove it).
+ */
+export declare function startRelay(input: {
+    getToken: () => Promise<string>;
+    relayUrl: () => string | null;
+    bridgeRevoked: () => boolean;
+    apiUrl: string;
+    /** The held-history notice when this computer is an active member of its own history (heldHistoryNotice), else null. */
+    held?: () => string[] | null;
+}): Promise<RelayStartup>;
+export declare function endpointRefusedMessage(reason: string): string;
+export type RegistrationAttempt = {
+    kind: 'registered';
+} | {
+    kind: 'retry';
+} | {
+    kind: 'revoked';
+} | {
+    kind: 'exit';
+    message: string;
+};
+export interface EndpointRegistrarDeps {
+    /** PUT /api/security/endpoints with this bridge's own ledger endpoint (registerBridgeEndpoint). */
+    register: (token: string) => Promise<void>;
+    tokens: {
+        getToken(): Promise<string>;
+        cooldownRemainingMs(): number;
+    };
+    bridgeRevoked: () => boolean;
+    /** This computer is an active member of its own history: a refusal is then not final (it may hold the only copy; the startup notice
+     *  said so): no reset advice, keep retrying with the backoff until the server accepts the key again. */
+    held?: () => boolean;
+    log: (line: string) => void;
+    /** Returns a cancel function. Defaults to an unref'd setTimeout. */
+    schedule?: (run: () => void, ms: number) => () => void;
+    /** First background delay (default 15 s), doubling to maxDelayMs (default 10 min); never earlier than the token cooldown. */
+    baseDelayMs?: number;
+    maxDelayMs?: number;
+}
+export interface EndpointRegistrar {
+    /** Step 6 at an online start, with the first token: a refusal exits, a temporary failure is retried in the background. */
+    registerNow(token: string): Promise<RegistrationAttempt>;
+    /** Retries getToken() + registration in the background until it succeeds or is refused, honouring the token cooldown. */
+    retryInBackground(): void;
+    registered(): boolean;
+    stop(): void;
+}
+export declare function createEndpointRegistrar(deps: EndpointRegistrarDeps): EndpointRegistrar;