ftown 0.21.0 → 0.24.0

package/dist/security/ledger/announce.js

@@ -0,0 +1,101 @@
+import { LEDGER_LIMITS } from './protocol.js';
+import { signDomain, verifyDomain } from './proof.js';
+/** Signed bytes: UTF-8 of HEAD_ANNOUNCE_DOMAIN + JSON of { accountId, at, head, keyId, kind, revision } in that key order. */
+export const HEAD_ANNOUNCE_DOMAIN = 'ftown-head-announce-v1\n';
+/** Receivers accept |now - at| <= this. */
+export const HEAD_ANNOUNCE_MAX_AGE_MS = 120_000;
+const KEYS = ['type', 'version', 'accountId', 'kind', 'keyId', 'head', 'revision', 'at', 'signature'];
+/** Canonical unpadded base64url of exactly 32 bytes: 43 chars, the last one carrying no stray bits. */
+const B64URL_32 = /^[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048]$/;
+/** Canonical unpadded base64url of exactly 64 bytes. */
+const B64URL_64 = /^[A-Za-z0-9_-]{85}[AQgw]$/;
+/** A ledger bridgeId (protocol token). */
+const BRIDGE_ID = /^[A-Za-z0-9_-]{1,200}$/;
+function validFields(record) {
+    const { accountId, kind, keyId, head, revision, at } = record;
+    if (typeof accountId !== 'string' || !B64URL_32.test(accountId))
+        return false;
+    if (typeof head !== 'string' || !B64URL_32.test(head))
+        return false;
+    if (kind !== 'device' && kind !== 'bridge')
+        return false;
+    if (typeof keyId !== 'string' || !(kind === 'device' ? B64URL_32 : BRIDGE_ID).test(keyId))
+        return false;
+    if (typeof revision !== 'number' || !Number.isSafeInteger(revision) || revision < 0 || revision > LEDGER_LIMITS.maxTransitions)
+        return false;
+    return typeof at === 'number' && Number.isSafeInteger(at) && at >= 0;
+}
+function signedBytes(fields) {
+    const ordered = {
+        accountId: fields.accountId,
+        at: fields.at,
+        head: fields.head,
+        keyId: fields.keyId,
+        kind: fields.kind,
+        revision: fields.revision,
+    };
+    return new TextEncoder().encode(HEAD_ANNOUNCE_DOMAIN + JSON.stringify(ordered));
+}
+/** Strict shape: exactly the nine keys, literal type/version, canonical base64url ids, safe integers. Anything else → null; never throws. */
+export function parseHeadAnnouncement(value) {
+    try {
+        if (typeof value !== 'object' || value === null || Array.isArray(value))
+            return null;
+        const record = value;
+        const keys = Object.keys(record);
+        if (keys.length !== KEYS.length || !keys.every(key => KEYS.indexOf(key) !== -1))
+            return null;
+        if (record.type !== 'ledger_head' || record.version !== 1)
+            return null;
+        if (!validFields(record))
+            return null;
+        if (typeof record.signature !== 'string' || !B64URL_64.test(record.signature))
+            return null;
+        const { accountId, kind, keyId, head, revision, at, signature } = record;
+        return { type: 'ledger_head', version: 1, accountId, kind, keyId, head, revision, at, signature };
+    }
+    catch {
+        return null;
+    }
+}
+/** Signs with the member's ECDSA P-256 auth private key. Extra properties of `fields` are ignored; invalid fields throw invalid_head_announcement. */
+export async function signHeadAnnouncement(key, fields) {
+    const { accountId, kind, keyId, head, revision, at } = fields;
+    const copy = { accountId, kind, keyId, head, revision, at };
+    if (!validFields(copy))
+        throw new Error('invalid_head_announcement');
+    const signature = await signDomain(key, signedBytes(copy));
+    return { type: 'ledger_head', version: 1, accountId, kind, keyId, head, revision, at, signature };
+}
+/**
+ * True only when `announcement` is well formed, of `checkpoint`'s account, from a member of `checkpoint` (by kind + keyId) that is not
+ * revoked there, within HEAD_ANNOUNCE_MAX_AGE_MS of `now` either way, and signed by that member's authPublicKey. `checkpoint` must be the
+ * receiver's TRUSTED view of its own chain. Cheap checks run first: at most one signature verification per call. Never throws.
+ */
+export async function verifyHeadAnnouncement(checkpoint, announcement, now) {
+    try {
+        const parsed = parseHeadAnnouncement(announcement);
+        if (!parsed || parsed.accountId !== checkpoint.accountId)
+            return false;
+        if (typeof now !== 'number' || !Number.isFinite(now) || Math.abs(now - parsed.at) > HEAD_ANNOUNCE_MAX_AGE_MS)
+            return false;
+        let authPublicKey;
+        if (parsed.kind === 'device') {
+            if (checkpoint.revokedDeviceIds.indexOf(parsed.keyId) !== -1)
+                return false;
+            authPublicKey = checkpoint.devices.filter(entry => entry.endpoint.id === parsed.keyId)[0]?.authPublicKey;
+        }
+        else {
+            if (checkpoint.revokedBridgeIds.indexOf(parsed.keyId) !== -1)
+                return false;
+            authPublicKey = checkpoint.bridges.filter(entry => entry.bridgeId === parsed.keyId)[0]?.authPublicKey;
+        }
+        if (!authPublicKey)
+            return false;
+        return await verifyDomain(authPublicKey, parsed.signature, signedBytes(parsed));
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=announce.js.map

package/dist/security/ledger/announce.js.map

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

package/dist/security/ledger/ledger.d.ts

@@ -1,16 +1,63 @@
 import type { Ledger, LedgerAuthority, LedgerCheckpoint, LedgerGenesis, LedgerOperation, LedgerTransition, Signed } from './protocol.js';
-export type LedgerErrorCode = 'invalid_ledger' | 'ledger_other_account' | 'ledger_revoked' | 'ledger_limit';
-/** 'keep' and 'adopt' imply the candidate's payloads belong to a valid chain, so its ledgerRevocations may be merged; 'reject' does not. */
+export type LedgerErrorCode = 'invalid_ledger' | 'ledger_other_account' | 'ledger_revoked' | 'ledger_limit' | 'resolution_incomplete';
+/** How a candidate chain relates to the local one, from record heads alone (see relate). */
+export type LedgerRelation = 'same' | 'ahead' | 'behind' | 'diverged';
+/** relateHead: what a bare `{ revision, head }` of another replica says about it. 'unknown' (ahead, diverged or another account) needs its chain. */
+export type LedgerHeadRelation = 'same' | 'behind' | 'unknown';
+/** The last record two chains share. Revision 0 is the genesis, whose head is the accountId. */
+export interface LedgerForkPoint {
+    revision: number;
+    head: string;
+}
+/** What an adopted resolve_fork discarded from the local chain: its records after the fork point, in chain order. `deviceIds`/`bridgeIds` list
+ *  revocations among them that the adopted chain lacks; a resolution is only adopted when it carries every one of them, so both are always
+ *  empty (kept so callers can go on merging them). Everything is empty unless a diverged chain was adopted. */
+export interface LedgerDiscarded {
+    records: Signed<LedgerTransition>[];
+    deviceIds: string[];
+    bridgeIds: string[];
+}
+/** chooseLedger's verdict. `ledger` is the chain to STORE afterwards (never the candidate as passed in): local on 'keep'/'reject'; on 'adopt'
+ *  local's own prefix records byte-for-byte followed by the candidate's verified records after the fork point; the parsed candidate on a first
+ *  bind. `checkpoint` is the RAW checkpoint of that chain. `relation` is null only when there is none: no local chain (first bind), or a
+ *  candidate that is malformed or of another account. 'keep' + 'diverged' = a VALID different history (alert the owner); 'reject' = an invalid
+ *  candidate (ignore it). `seen`: see LedgerSeen. */
 export interface LedgerChoice {
     decision: 'adopt' | 'keep' | 'reject';
+    relation: LedgerRelation | null;
     checkpoint: LedgerCheckpoint;
-    discarded: Signed<LedgerTransition>[];
+    discarded: LedgerDiscarded;
+    ledger: Ledger;
+    seen: LedgerSeen;
+}
+/** Removals found on a VALID diverged chain that chooseLedger kept out ('keep' + 'diverged'): the device endpoint ids / bridgeIds revoked by
+ *  the candidate's records after the fork point whose signer was already an authority at the fork point, de-duplicated, in chain order.
+ *  Empty for every other verdict. Callers add them to their STICKY set (local enforcement only); they never enter a chain. A bridge that
+ *  finds its own bridgeId here must not treat it as its own removal (status only). No attack surface: chooseLedger just verified those
+ *  records; authorities are add-only, so whoever signed such a removal could equally append it to our own chain; and a resolution must
+ *  carry every removal of the branch it discards, so enforcing them early agrees with every state the two chains can converge to. Records
+ *  signed by an authority added only on the candidate's branch contribute nothing. */
+export interface LedgerSeen {
+    deviceIds: string[];
+    bridgeIds: string[];
+}
+/** resolutionPlan: the fork point, and the operations to append to the chosen chain, in order, before its resolve_fork. */
+export interface LedgerResolutionPlan {
+    fork: LedgerForkPoint;
+    carry: LedgerOperation[];
 }
 /** A checkpoint that verifyLedger or chooseLedger returned for the local chain whose last head is `head`. */
 export interface LedgerCache {
     head: string;
     checkpoint: LedgerCheckpoint;
 }
+/** describeFork: the last shared record and each side's payloads after it, in chain order (payloads only, no signatures). */
+export interface LedgerFork {
+    relation: LedgerRelation;
+    fork: LedgerForkPoint;
+    mine: LedgerTransition[];
+    theirs: LedgerTransition[];
+}
 /** No untrusted text, key material or underlying crypto error enters this error. */
 export declare class LedgerError extends Error {
     readonly code: LedgerErrorCode;
@@ -28,8 +75,8 @@ export declare function signInChallenge(nonce: string): Promise<Uint8Array<Array
 export declare function authorityConsentChallenge(accountId: string, authority: Pick<LedgerAuthority, 'credentialId' | 'publicKey'>): Promise<Uint8Array<ArrayBuffer>>;
 /** The issuedAt of the last transition, or the genesis createdAt: the `lastIssuedAt` argument of nextTransition. */
 export declare function ledgerLastIssuedAt(ledger: Ledger): number;
-/** Every device endpoint id and bridgeId revoked anywhere in the chain, in chain order. Only for chains that verified (or that
- *  chooseLedger did not reject): replicas keep the union over all of them and never trust those ids again. Throws on a malformed shape. */
+/** Every device endpoint id and bridgeId revoked anywhere in the chain, in chain order. Only for chains that verified: replicas keep the
+ *  union over the chains they held (plus chooseLedger's `discarded` ids) and never trust those ids again. Throws on a malformed shape. */
 export declare function ledgerRevocations(ledger: Ledger): {
     deviceIds: string[];
     bridgeIds: string[];
@@ -46,16 +93,62 @@ export declare function parseLedger(value: unknown): Ledger;
 /** Verifies ONE chain from genesis and returns its last checkpoint. Every record's passkey signature is checked against an authority of the
  *  PREVIOUS state (genesis: its own authority) with genesis.rpId/origins. Throws LedgerError: invalid_ledger, or a more specific code. */
 export declare function verifyLedger(ledger: Ledger, now?: number): Promise<LedgerCheckpoint>;
-/** Fork choice, a pure total order on valid chains of one account: longer wins, then more revoke_device/revoke_bridge records in the
- *  whole chain, then the lexicographically smaller head.
- *  - different genesis or invalid candidate -> 'reject'; equal chain or a prefix of local -> 'keep' (decided from record heads alone)
- *  - otherwise the order decides; when a fork wins, `discarded` lists the local records after the common prefix.
- *  `cache` is the checkpoint of the already-verified local chain; when it vouches for `local`, local signatures and timestamps are not
- *  re-checked, and an extension only has its new records verified. Throws only when `local` is invalid (and not vouched for), or when
- *  `local` is null and the candidate is invalid. */
+/** The head of every record, index = revision: [accountId, head of revision 1, ..., head of the tip]. O(n) SHA-256 over the parsed chain and no
+ *  signature work; compute it once per chain and keep it for relate/forkPoint/relateHead. Throws like parseLedger. */
+export declare function ledgerHeads(ledger: Ledger): Promise<string[]>;
+/** How `candidate` relates to `local` (both ledgerHeads lists of chains of ONE account): 'same' (identical heads), 'ahead' (candidate strictly
+ *  extends local), 'behind' (local strictly extends candidate), 'diverged' (they differ at some revision both have). Pure, O(min(n, m)) string
+ *  compares, no hashing. Another account is not a relation: throws ledger_other_account (genesis heads differ); a malformed list throws
+ *  invalid_ledger. Every head of the shorter list is compared, so a list whose tip matches but whose middle differs is 'diverged'. */
+export declare function relate(local: readonly string[], candidate: readonly string[]): LedgerRelation;
+/** The last record `local` and `candidate` (ledgerHeads lists) share, or null when even the genesis differs. Same cost as relate. */
+export declare function forkPoint(local: readonly string[], candidate: readonly string[]): LedgerForkPoint | null;
+/** What another replica's bare `{ revision, head }` (an RPC answer or head announcement; other fields ignored) says relative to `local`
+ *  (a ledgerHeads list): 'same', 'behind' (local holds that head at that revision and more), or 'unknown' (ahead, diverged or another
+ *  account: fetch its chain and run chooseLedger). O(1). Throws invalid_ledger on a malformed head or revision. */
+export declare function relateHead(local: readonly string[], other: {
+    revision: number;
+    head: string;
+}): LedgerHeadRelation;
+/**
+ * The append-only acceptance rule, the same on every replica (server, browser, bridge). The candidate's relation decides:
+ * - no local chain (first bind): verified from genesis and adopted, relation null; an invalid candidate throws.
+ * - malformed or another account: 'reject', relation null.
+ * - 'same' / 'behind': 'keep', decided from record heads alone (no candidate signature is checked).
+ * - 'ahead': only the records after local's head are verified, on top of local's state -> 'adopt', or 'reject' if any is invalid.
+ * - 'diverged': the candidate's records after the fork point are verified on top of the shared prefix -> 'reject' if invalid. It is
+ *   'adopt'ed only under the owner-signed resolve_fork rule of resolves(); `discarded.records` then lists local's records after the fork.
+ *   Otherwise 'keep': a valid different history is never adopted, whatever its length or content; `seen` lists its removals to enforce locally.
+ * The candidate's copy of the shared prefix is never verified and never stored: its heads equal local's, so its payloads and state do, and
+ * only the candidate's records after the fork point (after local's tip when 'ahead') are checked. Store `choice.ledger`, which keeps local's
+ * prefix records byte-for-byte; re-encoded prefix signatures therefore cost nothing and are dropped. `cache` is the checkpoint of the
+ * already-verified local chain: when it vouches for `local` (same last head, hash-linked) local is not re-verified, else local is verified
+ * from genesis. Throws only when `local` is invalid (and not vouched for), or when `local` is null and the candidate is invalid.
+ */
 export declare function chooseLedger(local: Ledger | null, candidate: Ledger, now?: number, cache?: LedgerCache): Promise<LedgerChoice>;
+/** describeFork(local, other): where the two chains part and each side's payloads after that point, for showing two histories side by side.
+ *  Works for any relation of one account (for 'same' both lists are empty). Throws ledger_other_account for another account, else like parseLedger.
+ *  Neither chain is verified: pass only a local chain and one that chooseLedger classified as 'keep' + 'diverged'. */
+export declare function describeFork(local: Ledger, other: Ledger): Promise<LedgerFork>;
+/** What keeping `chosen` over `other` requires first: their fork point, and `carry`, the operations to append to `chosen` (each signed as an
+ *  ordinary record, in this order) before resolveForkTransition. In `other`'s chain order: one revoke_device / revoke_bridge per id revoked on
+ *  other's branch after the fork and not revoked in `chosen` (an id that is not a member of `chosen` is tombstoned, so it can never be added
+ *  there), and one add_authority, with the ORIGINAL authority and consent (a consent binds only accountId, credentialId and key), per authority
+ *  added on other's branch and absent from `chosen` with the same credentialId and key. Building a carried record can still throw (for example
+ *  ledger_limit, or invalid_ledger when `chosen` holds that credentialId or key under another authority): then `chosen` cannot be kept.
+ *  Throws ledger_other_account for another account and invalid_ledger unless the chains diverge. Neither chain is verified: pass only a
+ *  verified local chain and one that chooseLedger classified as 'keep' + 'diverged'. */
+export declare function resolutionPlan(chosen: Ledger, other: Ledger): Promise<LedgerResolutionPlan>;
+/** The unsigned resolve_fork that keeps `chosen` and discards `other` from their fork point: appended to `chosen`, forkHead = the last shared
+ *  record, discardedFirst = other's first record after it, discardedHead/discardedRevision = other's tip. Verifies `chosen` (skipped when
+ *  `cache` vouches for it, as in chooseLedger) and throws invalid_ledger when the chains do not diverge or `credentialId` was not an authority
+ *  at the fork point (one added on chosen's own branch cannot discard the other); resolution_incomplete while resolutionPlan(chosen, other)
+ *  still has operations to carry; ledger_other_account for another account; else nextTransition's errors. `other` is not verified: pass only
+ *  a chain that chooseLedger classified as 'keep' + 'diverged'. */
+export declare function resolveForkTransition(chosen: Ledger, other: Ledger, credentialId: string, now?: number, cache?: LedgerCache): Promise<LedgerTransition>;
 /** Pure next-payload builder for the signer. Applies the operation to a copy of the checkpoint with the verifier's rules and throws the
- *  same errors. Not checked here (they need async crypto): endpoint id = SHA-256(point), points on the curve, and the add_authority
- *  consent signature (only its shape is checked); verifyLedger enforces all three.
+ *  same errors. Not checked here (they need async crypto or the chain): endpoint id = SHA-256(point), points on the curve, the add_authority
+ *  consent signature (only its shape is checked) and resolve_fork's forkHead and signer rules (build it with resolveForkTransition);
+ *  verifyLedger enforces all of them.
  *  `lastIssuedAt` is the issuedAt of the ledger's last record (see ledgerLastIssuedAt); the result's issuedAt is max(now, lastIssuedAt). */
 export declare function nextTransition(checkpoint: LedgerCheckpoint, credentialId: string, operation: LedgerOperation, now?: number, lastIssuedAt?: number): LedgerTransition;