ftown 0.20.9 → 0.24.0

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

@@ -0,0 +1,153 @@
+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';
+export type OwnBridgeStatus = 'active' | 'revoked' | 'absent';
+export type ReconcileResult = 'ok' | 'unpaired' | 'needs_ledger';
+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;
+    /** 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 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;
+}
+/** 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);
+    /** The stored state, or null while no ledger is stored. Throws LedgerStoreError for a corrupted or wrong-account file. */
+    read(): Promise<BridgeLedgerState | null>;
+    /** applyRevocations(checkpoint, sticky) of the stored chain, or null while no ledger is stored. */
+    trusted(): Promise<LedgerCheckpoint | null>;
+    /** 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 (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 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>;
+    /**
+     * Recovery when the identity is bound but the store is empty (reconcileIdentityAndStore returned 'needs_ledger'): accepts a server
+     * ledger only if its account is the identity's bound account and its trusted roster lists this identity's bridge keys (endpoint id and
+     * authPublicKey). Returns trusted(). Throws LedgerStoreError('ledger_store_bound_rejected') and writes nothing otherwise.
+     */
+    adoptBound(ledger: unknown, now?: number): Promise<LedgerCheckpoint>;
+    /** Records the time of the last successful server ledger read. No-op while no ledger is stored. */
+    markServerRead(now: number): Promise<void>;
+}
+/**
+ * Startup recovery between the identity file and the ledger store, under the store's queue:
+ * - identity bound, store holds its account's ledger -> 'ok'; store holds another account's -> throws ledger_store_wrong_account;
+ * - identity bound, store empty -> 'needs_ledger' (fetch the server ledger, then adoptBound); a bound identity is never unbound;
+ * - identity unbound (or absent), store empty -> 'unpaired';
+ * - identity unbound, store's trusted roster lists this identity's bridge keys -> binds the identity to that account -> 'ok';
+ * - otherwise (absent identity, or keys not listed) the stale ledger.json is deleted -> 'unpaired'.
+ * Corrupted files throw (LedgerStoreError / BridgeSecurityError('key_unavailable')) and are never reset.
+ */
+export declare function reconcileIdentityAndStore(dataDir: string, options?: {
+    now?: () => number;
+}): Promise<ReconcileResult>;