ftown 0.21.0 → 0.25.0

package/dist/security/bridge/ledger-rpc.js

@@ -0,0 +1,58 @@
+/*
+ * The two read-only ledger RPCs a trusted browser sends over the encrypted command channel (CONTRACT §9, §11): `ledger_head` (this bridge's
+ * account, head and revision) and `ledger_chain` (its stored chain, in pages that fit one encrypted relay frame). Pure: request parsing and
+ * paging only. command-rpc.ts authorizes the caller (BridgeSecurityService.memberLedger) and answers.
+ *
+ * Wire (the usual command envelope; route { kind: 'command', command: <type>, requestId, sessionId: null }):
+ *   ledger_head   payload { bridgeId }                                   -> data { accountId, head, revision }
+ *   ledger_chain  payload { bridgeId, fromRevision?: 0, limit?: 1025 }   -> data { accountId, head, revision, fromRevision, records, more }
+ * records[i] is the record at revision fromRevision + i (revision 0 is the signed genesis, revision n is transitions[n - 1]), each exactly as
+ * stored ({ payload, signature }). A page holds at most `limit` records and, past its first record, at most LEDGER_CHAIN_PAGE_BYTES of
+ * record JSON; `more` says records after the page exist. head/revision are the stored tip when the page was cut.
+ */
+import { LEDGER_LIMITS } from '../ledger/protocol.js';
+/** Record JSON per ledger_chain page (as the review and preview chunks): with the envelope it stays far below one relay frame. */
+export const LEDGER_CHAIN_PAGE_BYTES = 98_304;
+/** The largest `limit`, and its default: every record of the largest chain. */
+export const LEDGER_CHAIN_MAX_LIMIT = LEDGER_LIMITS.maxTransitions + 1;
+function isPayload(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isCount(value, min, max) {
+    return typeof value === 'number' && Number.isSafeInteger(value) && value >= min && value <= max;
+}
+/** ledger_head: exactly { bridgeId } naming this bridge. */
+export function parseLedgerHeadQuery(payload, bridgeId) {
+    return isPayload(payload) && Object.keys(payload).length === 1 && payload.bridgeId === bridgeId;
+}
+/** ledger_chain: { bridgeId, fromRevision?, limit? } naming this bridge, nothing else; null when malformed. */
+export function parseLedgerChainQuery(payload, bridgeId) {
+    if (!isPayload(payload) || payload.bridgeId !== bridgeId)
+        return null;
+    if (Object.keys(payload).some(key => key !== 'bridgeId' && key !== 'fromRevision' && key !== 'limit'))
+        return null;
+    const fromRevision = payload.fromRevision === undefined ? 0 : payload.fromRevision;
+    const limit = payload.limit === undefined ? LEDGER_CHAIN_MAX_LIMIT : payload.limit;
+    if (!isCount(fromRevision, 0, LEDGER_LIMITS.maxTransitions) || !isCount(limit, 1, LEDGER_CHAIN_MAX_LIMIT))
+        return null;
+    return { fromRevision, limit };
+}
+export function ledgerHeadAnswer(held) {
+    return { accountId: held.accountId, head: held.head, revision: held.revision };
+}
+/** The page of `held` that starts at query.fromRevision (empty, more false, past the tip). Never splits a record; always makes progress.
+ *  `held` is only read; the page carries copies of its records. */
+export function ledgerChainPage(held, query, maxBytes = LEDGER_CHAIN_PAGE_BYTES) {
+    const all = [held.ledger.genesis, ...held.ledger.transitions];
+    const records = [];
+    let bytes = 0;
+    for (let revision = query.fromRevision; revision < all.length && records.length < query.limit; revision++) {
+        const size = Buffer.byteLength(JSON.stringify(all[revision]), 'utf8');
+        if (records.length > 0 && bytes + size > maxBytes)
+            break;
+        records.push(structuredClone(all[revision]));
+        bytes += size;
+    }
+    return { ...ledgerHeadAnswer(held), fromRevision: query.fromRevision, records, more: query.fromRevision + records.length < all.length };
+}
+//# sourceMappingURL=ledger-rpc.js.map

package/dist/security/bridge/ledger-rpc.js.map

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

package/dist/security/bridge/ledger-store.d.ts

@@ -1,3 +1,4 @@
+import type { LedgerRelation } from '../ledger/ledger.js';
 import type { BridgePairLink, PairApproval } from '../ledger/pairing.js';
 import type { Ledger, LedgerCheckpoint, LedgerTransition, Signed } from '../ledger/protocol.js';
 export type LedgerSource = 'server' | 'relay';
@@ -7,36 +8,103 @@ export interface StickyRevocations {
     deviceIds: string[];
     bridgeIds: string[];
 }
+/** A valid history of this account from `source` that diverges from the stored chain and was refused. Times are wall-clock ms. */
+export interface LedgerDivergence {
+    source: LedgerSource;
+    /** The refused chain's last head and revision (the first new head that source showed; an older refused head coming back changes nothing). */
+    otherHead: string;
+    otherRevision: number;
+    /** The revision of the last record both histories share; null when unknown (an entry written by an earlier 0.22 build). */
+    forkRevision: number | null;
+    /** A refused history from this source removes THIS bridge (status only: never a sticky entry, never an identity reset). */
+    removedOnOtherHistory: boolean;
+    /** When this source was first seen diverging (kept while it keeps diverging, also when its head moves). */
+    firstSeen: number;
+    /** When it was last seen; persisted at most every DIVERGENCE_LAST_SEEN_RESOLUTION_MS. */
+    lastSeen: number;
+}
+/** The last REFUSED_HEADS_PER_SOURCE refused heads per source, oldest first: a REFUSED line is logged once per head (persisted, so also
+ *  across restarts and after the divergence entry was cleared). */
+export interface RefusedHeads {
+    server: string[];
+    relay: string[];
+}
+/** This bridge's own keys, exactly as its add_bridge lists them (and as BridgeSecurityService's 'active' check compares them). */
+export interface OwnBridgeKeys {
+    bridgeId: string;
+    endpointId: string;
+    endpointPublicKey: string;
+    authPublicKey: string;
+}
 export interface BridgeLedgerState {
     ledger: Ledger;
     /** The stored chain's own checkpoint (raw). Never use it for a trust decision. */
     checkpoint: LedgerCheckpoint;
     /** applyRevocations(checkpoint, sticky): the checkpoint for every trust decision. */
     trusted: LedgerCheckpoint;
-    /** Union of the revocations of every chain this replica kept or adopted. */
+    /** The revocations of every chain this replica adopted, plus those of records an owner-chosen history discarded, plus the removals
+     *  chooseLedger saw on refused histories (`seen`, C1c) except this bridge's own id. Trust only, never evidence of this bridge's removal. */
     sticky: StickyRevocations;
     lastServerReadAt: number | null;
+    /** At most one entry per source, ordered server first. */
+    divergences: LedgerDivergence[];
+    refused: RefusedHeads;
+}
+/** The last record of a chain: its revision (0 = genesis) and head (the genesis head is the accountId). */
+export interface LedgerTip {
+    revision: number;
+    head: string;
 }
 export interface LedgerOfferResult {
     decision: 'adopt' | 'keep' | 'reject';
+    /** How the candidate relates to the chain stored before the decision; null when it has none (empty store, malformed, another account). */
+    relation: LedgerRelation | null;
+    /** The candidate's tip; null when it does not parse. */
+    candidate: LedgerTip | null;
     /** The stored state after the decision; null while the store is empty. */
     state: BridgeLedgerState | null;
-    /** Local records discarded by a winning fork, for the owner to re-sign; empty otherwise. */
+    /** Local records an owner-chosen history (adopt + diverged) discarded; empty otherwise. */
     discarded: Signed<LedgerTransition>[];
+    /** A diverged candidate that a resolve_fork already in OUR chain discards (the other side is behind the owner's decision): answered
+     *  keep with relation 'behind' (so a server holding it gets our chain re-offered), never recorded as a divergence, never logged. */
+    covered: boolean;
 }
 export interface BridgeLedgerStoreOptions {
     /** The account the bridge identity is bound to: ledgers of any other account are rejected even while the store is empty, and a
      *  stored ledger of another account throws LedgerStoreError('ledger_store_wrong_account'). */
     accountId?: string | null;
     now?: () => number;
+    /** The `[ledger]` lines (refused history, owner-chosen adoption, ignored chain). Defaults to console.warn. */
+    log?: (line: string) => void;
+    /** This bridge's own bridgeId. A refused history's removal of it is recorded as status only, never added to the sticky set. Without it,
+     *  no bridge removal of a refused history is added to the sticky set at all (device removals still are). */
+    bridgeId?: string | null;
 }
-export type LedgerStoreErrorCode = 'ledger_store_corrupt' | 'ledger_store_wrong_account' | 'ledger_store_pairing_rejected' | 'ledger_store_bound_rejected';
+/** Divergence lastSeen is rewritten at most this often while the same other head keeps arriving. */
+export declare const DIVERGENCE_LAST_SEEN_RESOLUTION_MS: number;
+/** "ignored an invalid chain" is logged at most once per this interval per source. */
+export declare const INVALID_CHAIN_LOG_SPACING_MS = 60000;
+/** A REFUSED line for a head not refused before is logged at most once per this interval per source. */
+export declare const REFUSED_LOG_SPACING_MS = 60000;
+/** Refused heads remembered per source (persisted), and verdicts on refused chains cached per process. */
+export declare const REFUSED_HEADS_PER_SOURCE = 16;
+export declare const REFUSED_VERDICT_CACHE_SIZE = 16;
+/** The first 8 characters of a head, as the log lines and the status show it. */
+export declare const shortHead: (head: string) => string;
+export type LedgerStoreErrorCode = 'ledger_store_corrupt' | 'ledger_store_wrong_account' | 'ledger_store_pairing_rejected' | 'ledger_store_pairing_revoked' | 'ledger_store_bound_rejected';
 /** Not retryable; file contents and crypto errors never enter it. Read/write failures throw BridgeSecurityError('storage_unavailable'). */
 export declare class LedgerStoreError extends Error {
     readonly code: LedgerStoreErrorCode;
     readonly retryable = false;
     constructor(code: LedgerStoreErrorCode);
 }
+/**
+ * Proof in the RAW chain `ledger` that THIS bridge was removed: an add_bridge of exactly these keys (bridgeId, endpoint id, endpoint public
+ * key and auth key), followed by a revoke_bridge of its bridgeId. A revoke_bridge of an id the chain never added with these keys is only a
+ * tombstone (C1b: revoking a non-member is valid) and proves nothing about this bridge. Sticky entries and refused histories never count:
+ * this is the only evidence that resets the identity, on a running bridge and at startup alike.
+ */
+export declare function ledgerRemovesBridge(ledger: Ledger, own: OwnBridgeKeys): boolean;
 export declare class BridgeLedgerStore {
     private readonly replica;
     constructor(dataDir: string, options?: BridgeLedgerStoreOptions);
@@ -44,21 +112,22 @@ export declare class BridgeLedgerStore {
     read(): Promise<BridgeLedgerState | null>;
     /** applyRevocations(checkpoint, sticky) of the stored chain, or null while no ledger is stored. */
     trusted(): Promise<LedgerCheckpoint | null>;
-    /** 'revoked' iff bridgeId is revoked in trusted(); 'active' iff trusted() lists bridgeId with this auth key; else 'absent'. */
-    ownBridgeStatus(bridgeId: string, authPublicKey: string): Promise<OwnBridgeStatus>;
-    /** ownBridgeStatus(bridgeId, …) === 'revoked': by the stored chain or by any chain this replica ever kept or adopted. */
-    ownBridgeRevoked(bridgeId: string): Promise<boolean>;
+    /** The startup decision (ledger-startup ownStatusAction): 'active' iff trusted() lists this bridge with exactly its keys; 'revoked' iff the
+     *  stored RAW chain proves its removal (ledgerRemovesBridge: it added these keys, then revoked the id); else 'absent' (a tombstone, a
+     *  sticky-only id or a removal seen on a refused history is no removal). The same rule as BridgeSecurityService's running check. */
+    ownBridgeStatus(own: OwnBridgeKeys): Promise<OwnBridgeStatus>;
     /**
-     * Offers an untrusted candidate chain from the server or the relay. Never binds an empty store, and never throws for a bad candidate:
-     * it is rejected. Throws LedgerStoreError for a corrupted or wrong-account local file, and BridgeSecurityError('storage_unavailable')
-     * when the file cannot be read or written.
+     * Offers an untrusted candidate chain from the server or the relay (see decide for the rule). Never binds an empty store, and never
+     * throws for a bad candidate: it is rejected. Throws LedgerStoreError for a corrupted or wrong-account local file, and
+     * BridgeSecurityError('storage_unavailable') when the file cannot be read or written.
      */
     offer(candidate: unknown, source: LedgerSource): Promise<LedgerOfferResult>;
     /**
      * The pairing path, after openPairApproval. Runs confirmPairedLedger(link, approval, ledger, now, sticky) with this replica's sticky
-     * set, then binds the empty store (or applies the replica rule to a bound store of the same account); the request's bridge must be in
-     * the resulting trusted roster. Returns trusted(). Throws LedgerStoreError('ledger_store_pairing_rejected') and writes nothing on any
-     * pairing failure.
+     * set, then binds the empty store (or applies the append-only rule to a bound store of the same account); the request's bridge must be in
+     * the resulting trusted roster. Returns trusted(). Throws LedgerStoreError('ledger_store_pairing_revoked') when the chain (or this
+     * replica's sticky set) revokes the request's bridge id, LedgerStoreError('ledger_store_pairing_rejected') on any other pairing failure;
+     * writes nothing in either case.
      */
     adoptPaired(link: BridgePairLink, approval: PairApproval, ledger: unknown, now?: number): Promise<LedgerCheckpoint>;
     /**