ftown 0.20.9 → 0.24.0

package/dist/security/bridge/security.d.ts

@@ -1,15 +1,101 @@
 import type { ApplicationJson, ApprovedEndpoint, BridgeInvitation, BridgeSecurity, EndpointIdentity, EnrollmentPacket, InboundTransportContext, InvitationOptions, LocalRecoveryAuthority, SecureApplication, SecureEnvelope, SecurePublication, VerifiedApplication, VerifiedPrincipal } from '../protocol.js';
-import { BridgePolicyStore, type PolicyOptions } from './policy.js';
-import type { AccountHead, AccountHistory, VerifiedAccountTrust } from '../account-protocol.js';
+import { BridgePolicyStore, type LedgerOwnStatus, type PolicyOptions } from './policy.js';
+import type { LedgerHeadRelation, LedgerRelation } from '../ledger/ledger.js';
+import type { Ledger } from '../ledger/protocol.js';
+import { type HeadAnnouncement } from '../ledger/announce.js';
+import type { BridgeLedgerStore, LedgerSource } from './ledger-store.js';
 export declare const applicationJson: (value: unknown) => ApplicationJson;
+/** Account mode: the local ledger replica is the only source of browser authority. */
+export interface BridgeLedgerOptions {
+    store: BridgeLedgerStore;
+    /** Must equal the service's bridgeId. */
+    bridgeId: string;
+    /** This bridge's auth key (raw P-256, base64url) as listed in its add_bridge. */
+    authPublicKey: string;
+    /** The server's copy of the ledger (GET /api/account/ledger), read by startLedger and refreshLedger. Bound it with a timeout. */
+    fetchLedger: () => Promise<unknown>;
+    /** Wall clock for offline grace and server contact; defaults to the policy clock. */
+    now?: () => number;
+    /** Monotonic clock for the in-process grace bound; defaults to performance.now(). */
+    monotonic?: () => number;
+}
 export interface BridgeSecurityOptions extends PolicyOptions {
     relayUserId: string;
     browserOrigin?: string;
-    readAccountHistory?: (signal?: AbortSignal) => Promise<AccountHistory | null>;
-    /** Jitter source for account-read retry backoff; defaults to Math.random. */
-    random?: () => number;
+    /** Absent for Solo and --local: their devices come only from invitations and the local CLI. */
+    ledger?: BridgeLedgerOptions;
+}
+/** A refused history (the store's divergence entry, server preferred), as the status shows it: heads cut to 8 characters. */
+export interface LedgerDivergenceStatus {
+    source: LedgerSource;
+    otherHead: string;
+    otherRevision: number;
+    ourRevision: number;
+    firstSeen: number;
+    /** The revision both histories last share; null when unknown. */
+    forkRevision: number | null;
+    /** That history removes this computer (status only: this bridge keeps its own history and is never reset by it). */
+    removedOnOtherHistory: boolean;
+}
+/** What this bridge holds that the server lacks (its records after the fork point, or after the server's revision when the server is
+ *  behind): the removals (revoke_device / revoke_bridge) and passkeys (add_authority) among them. */
+export interface UniqueHistory {
+    afterRevision: number;
+    records: number;
+    removals: number;
+    passkeys: number;
+}
+export interface LedgerStatus {
+    accountId: string | null;
+    revision: number | null;
+    head: string | null;
+    own: LedgerOwnStatus;
+    /** Another valid history of this account was refused (CONTRACT §5); null when none is recorded. */
+    divergence: LedgerDivergenceStatus | null;
+    /** The last server chain this bridge evaluated was a strict prefix of its own (the bridge re-offers its chain). */
+    serverBehind: boolean;
+    /** A refused history (from the server or the relay) removes this computer. Status only. */
+    removedOnOtherHistory: boolean;
+    /** Head announcements from the ledger channel since start: verified against the trusted checkpoint ('accepted'), or refused ('dropped':
+     *  bad signature, unknown or revoked member, other account, stale, or no trusted chain yet). This bridge's own echoes are not counted. */
+    announcements: {
+        accepted: number;
+        dropped: number;
+    };
+}
+type OfferDecision = 'adopt' | 'keep' | 'reject';
+/** An offer's decision, the candidate's relation to the stored chain (null: none, e.g. malformed) and its tip (null: unparseable). */
+export interface LedgerOfferOutcome {
+    decision: OfferDecision;
+    relation: LedgerRelation | null;
+    head: string | null;
+    revision: number | null;
+}
+/** readServerLedger: the server's chain was read and offered ('read'), the server does not know the account (404), or the read failed. */
+export type ServerLedgerRead = {
+    kind: 'read';
+    outcome: LedgerOfferOutcome;
+} | {
+    kind: 'unknown_account';
+    reason: string;
+} | {
+    kind: 'failed';
+    reason: string;
+};
+/** The stored chain as a trusted browser may read it (ledger_head / ledger_chain). */
+export interface MemberLedger {
+    ledger: Ledger;
+    accountId: string;
+    head: string;
+    revision: number;
+}
+/** ledger_head: the stored tip only. */
+export interface MemberHead {
+    accountId: string;
+    head: string;
+    revision: number;
 }
-export declare class BridgeSecurityService implements BridgeSecurity {
+export declare class BridgeSecurityService implements Omit<BridgeSecurity, 'adoptAccount'> {
     readonly identity: EndpointIdentity;
     readonly bridgeId: string;
     readonly options: BridgeSecurityOptions;
@@ -24,13 +110,26 @@ export declare class BridgeSecurityService implements BridgeSecurity {
     private bridgeRevokedEmitted;
     private readonly verified;
     private closed;
-    private accountTimer;
-    private accountTimerDue;
-    private accountPushHealthy;
-    private accountReadFailures;
-    private accountRefresh;
-    private accountTrigger;
-    private readonly accountAbort;
+    private readonly ledgerNow;
+    /** Ledger offers and their projections run one at a time, so the policy never sees an older view after a newer one. */
+    private ledgerTail;
+    private status;
+    private readonly announcements;
+    private readonly headListeners;
+    private readonly ledgerMonotonic;
+    /** The trusted view of the last projection (null: none yet, or another account's). */
+    private trustedView;
+    /** The state of the last projection (null: none yet, or an empty store), and the record heads of its chain (null: not computed). */
+    private held;
+    private heads;
+    private readonly approvalListeners;
+    private readonly approvalEmitted;
+    private readonly pendingOffers;
+    private serverBehind;
+    /** The server's revision when it was last seen behind us (null: unknown). */
+    private serverRevision;
+    private refreshing;
+    private refreshQueued;
     constructor(identity: EndpointIdentity, bridgeId: string, dataDir: string, options: BridgeSecurityOptions);
     private context;
     private freshness;
@@ -49,31 +148,111 @@ export declare class BridgeSecurityService implements BridgeSecurity {
     createInvitation(actor: VerifiedPrincipal | LocalRecoveryAuthority, options: InvitationOptions): Promise<BridgeInvitation>;
     listDevices(actor: VerifiedPrincipal): Promise<ApprovedEndpoint[]>;
     revokeEndpoint(actor: VerifiedPrincipal, endpointId: string): Promise<void>;
-    /** Called once at startup; legacy/Solo stores never adopt an unsigned server directory. */
-    startAccount(trust?: VerifiedAccountTrust): Promise<void>;
-    private recordAccountRead;
-    /** After failures the server is the only writer of account state, so retrying fast buys nothing: back off with jitter. */
-    private nextAccountReadDelay;
-    /** Safety read: 1 h while push is healthy and the last read succeeded, else the 10 min cadence; failed reads back off from 60 s to 30 min. */
-    private scheduleAccountRead;
-    private trackedAccountRead;
-    /** Push (nudge subscription) health; losing it pulls the next safety read in to the 10 min cadence. */
-    setAccountPushHealthy(healthy: boolean): void;
-    /** Push-driven re-read (account nudge); bursts coalesce into at most one trailing read. */
-    requestAccountRefresh(): void;
-    private accountFailure;
+    /**
+     * Account mode only (no-op without a ledger). Loads the replica, projects it and checks this bridge's own status; a stored chain that
+     * already revokes this bridge is signed proof on its own, so it emits and nothing is fetched. Otherwise offers the server's ledger
+     * once; a fetch failure is logged, not fatal, and a successful read that is not rejected counts as server contact.
+     * Throws when the local replica cannot be read (corrupted, another account's, or unreadable; it is never reset) or the policy
+     * cannot be written.
+     */
+    startLedger(): Promise<void>;
+    /**
+     * Reads the server's ledger and offers it ('server') through readServerLedger. A result that is not 'reject' counts as server contact;
+     * a fetch failure is logged, never thrown. Single in flight: calls during a read share one trailing read, so a change announced
+     * mid-read is not missed. The wiring calls it on every relay (re)subscribe and on a `ledger_head` that differs from ledgerStatus().head,
+     * and checks ledgerStatus().serverBehind afterwards.
+     */
+    refreshLedger(): Promise<void>;
+    private refreshOnce;
+    /**
+     * One read of the server's ledger (not coalesced), offered as 'server'; a result that is not 'reject' counts as server contact. Never
+     * throws: a 404 is 'unknown_account' (the server does not know this account), any other failure 'failed'. The re-offer runs it right
+     * before it posts; refreshLedger runs it for everything else.
+     */
+    readServerLedger(): Promise<ServerLedgerRead>;
+    /** offerLedgerResult(candidate, source).decision. */
+    offerLedger(candidate: unknown, source: LedgerSource): Promise<OfferDecision>;
+    /**
+     * Offers an untrusted chain (the relay, a relay-token response, a server read or answer) to the replica, then projects the result and
+     * checks this bridge's own status. Never throws: an invalid candidate, a closed service and a local storage failure all return 'reject'.
+     * Per source at most one offer waits behind the one in flight; a newer one replaces it, and the replaced caller gets the newer outcome.
+     * A chain equal to the stored one or a prefix of it is answered keep/same or keep/behind from record heads alone (no signature check),
+     * unless a divergence is recorded for that source (the store clears it). The outcome of a 'server' chain sets serverBehind. Offers never
+     * count as server contact: readServerLedger and noteServerContact decide that.
+     */
+    offerLedgerResult(candidate: unknown, source: LedgerSource): Promise<LedgerOfferOutcome>;
+    private evaluate;
+    /** Records what a non-rejected 'server' chain says about the server: behind (a strict prefix of ours) or not. */
+    private observed;
+    private setServerBehind;
+    /**
+     * A relay-token answer that carried no chain: the server's head is `head` (at `revision` when the answer named one, else the head the
+     * request sent). Classified against the stored chain from record heads alone: 'same', 'behind' (sets serverBehind), or 'unknown'
+     * (ahead, diverged, or not a head of ours: the caller reads the server). null without a ledger, a head, or a stored chain.
+     */
+    noteServerHead(server: {
+        head: string | null;
+        revision: number | null;
+    }): LedgerHeadRelation | null;
+    /**
+     * What this bridge holds that the server does not (for the startup message when the server refuses our key): our records after the
+     * fork point of a recorded server divergence, or after the server's revision when it was seen behind us; null when neither is known.
+     */
+    uniqueHistory(): UniqueHistory | null;
+    /**
+     * Account mode, read-only (ledger_head / ledger_chain): the stored chain, for a BROWSER that is a member of this bridge's trusted
+     * checkpoint (listed with exactly this endpoint key, not revoked; policy access, offline grace and own status included). Throws
+     * BridgeSecurityError('permission_denied') for anyone else, Solo, --local and the local CLI.
+     */
+    memberLedger(principal: VerifiedPrincipal): Promise<MemberLedger>;
+    /** ledger_head: like memberLedger, but answers the tip only, without touching the chain. */
+    memberHead(principal: VerifiedPrincipal): Promise<MemberHead>;
+    private memberState;
+    /** A successful server contact (the token provider calls this after a relay-token response): re-anchors offline grace at now and
+     *  persists it (the replica's lastServerReadAt and the clock high-water). An invalid time is ignored. */
+    noteServerContact(now?: number): void;
+    ledgerStatus(): LedgerStatus;
+    /**
+     * A head announcement from the ledger channel (parsed, from an owner publication), judged against this bridge's TRUSTED checkpoint (sticky
+     * revocations applied) and the record heads of its stored chain: its relation ('same', 'behind' or 'unknown': the caller runs a paced server
+     * read) when it verifies, else null. This bridge's own announcements (kind bridge, its bridgeId) return null before any work and are not
+     * counted; every other null is counted as dropped, every relation as accepted. At most one signature verification, then an O(1) compare.
+     * Never throws. An announcement is never proof: nothing here changes the replica.
+     */
+    judgeHeadAnnouncement(announcement: HeadAnnouncement): Promise<LedgerHeadRelation | null>;
+    /** Account mode: fires (synchronously, after the projection) whenever the stored head or this bridge's own status changes, e.g. after an
+     *  adopt. Listener errors are logged. */
+    onLedgerHead(listener: () => void): () => void;
+    private ledgerTask;
+    /** This bridge's keys, exactly as its add_bridge lists them. */
+    private ownKeys;
+    /**
+     * This bridge in `trusted` (applyRevocations of the projected RAW chain `ledger`). 'active' = listed with exactly its keys. 'revoked' =
+     * the RAW chain proves the removal of THIS bridge (ledgerRemovesBridge: it added these keys, then revoked the id), the only status that
+     * resets the identity, decided exactly like the startup check (store.ownBridgeStatus). A sticky-only id, a removal seen on a refused
+     * history (C1c `seen`, never merged for our own id anyway) or a tombstone of our id is 'absent': fail closed, never a reset.
+     */
+    private ownOf;
+    /** `trusted` is always the store's applyRevocations output, never its raw checkpoint. Own status acts before the policy write, so
+     *  neither the revocation nor its emission waits on (or is lost to) a policy storage failure. */
+    private projectState;
+    private project;
+    private emitLedgerHead;
     private emitRevoked;
-    private pinnedCheckpoint;
-    /** A refused fetched history is still evidence, but only against the pin as it stands now: adoption is not serialized
-     *  with reads, and a fork from an older pin must never confirm. Pins only move forward by verified extension. */
-    private adoptFetched;
-    confirmRevocationEvidence(evidence: AccountHistory): Promise<boolean>;
     private emitBridgeRevoked;
     private notifyBridgeRevoked;
-    refreshAccount(): Promise<void>;
-    adoptAccount(actor: VerifiedPrincipal, head: AccountHead): Promise<AccountHead>;
     onRevoked(listener: (endpointId: string) => void): () => void;
+    /**
+     * Account mode only: fires when a request (hello or application) is refused with approval_required for an endpoint the trusted
+     * ledger does not know, e.g. a browser whose add_device this replica has not seen yet (the wiring refreshes the ledger). Never for
+     * a revoked endpoint, never in Solo/local, never for the provisioned local CLI. At most once per endpoint per 2 s; listener errors
+     * are logged; the refusal itself is unchanged.
+     */
+    onApprovalRequired(listener: (endpointId: string) => void): () => void;
+    private senderPrincipal;
+    private noteApprovalRequired;
     /** Fires at most once per instance, only on signed proof that this bridge was revoked. */
     onBridgeRevoked(listener: () => void): () => void;
     close(): Promise<void>;
 }
+export {};