@net-mesh/browser 0.37.0

package/dist/store/json.d.ts

@@ -0,0 +1,50 @@
+/**
+ * The store's JSON parser: step 2 of the frozen ladder (brief §1.12).
+ *
+ * `JSON.parse` cannot implement that step. It accepts duplicate keys
+ * and silently keeps the last one, it has no depth bound, and — the one
+ * that matters most — `JSON.parse('1e999')` returns `Infinity`, so
+ * "numbers finite" is not a property it gives you. A protocol that
+ * digests or compares values cannot have two spellings of one value,
+ * and it cannot have a value that is not a number.
+ *
+ * So the ladder's second rung is a real parser:
+ *
+ * - depth ≤ {@link MAX_JSON_DEPTH}, counting objects and arrays;
+ * - **duplicate keys refused**, not resolved;
+ * - every number finite, and spelled by the JSON grammar (no `NaN`,
+ *   `Infinity`, `+1`, `.5`, `1.`, `01`, or hex);
+ * - objects built with **null prototypes**, so no parsed document can
+ *   introduce a `__proto__` key that later traversal would follow;
+ * - trailing content refused.
+ *
+ * It returns a refusal rather than throwing: the caller counts it and
+ * answers `invalid-data`, and no mutation has happened by then.
+ */
+/** Depth bound for a store message (brief §1.12). */
+export declare const MAX_JSON_DEPTH = 16;
+/** A parsed JSON document. Objects have null prototypes. */
+export type JsonValue = null | boolean | number | string | JsonValue[] | JsonObject;
+/** A parsed JSON object: own properties only, no prototype. */
+export interface JsonObject {
+    [key: string]: JsonValue;
+}
+/** Why a document was refused, and where. */
+export interface JsonFailure {
+    readonly ok: false;
+    readonly reason: JsonRefusal;
+    /** Byte offset into the text, for the counter's detail. */
+    readonly at: number;
+}
+export type JsonRefusal = 'empty' | 'unexpected-token' | 'unexpected-end' | 'trailing-content' | 'depth-exceeded' | 'duplicate-key' | 'number-not-finite' | 'number-grammar' | 'string-control-char' | 'string-escape' | 'literal';
+export type JsonResult = {
+    readonly ok: true;
+    readonly value: JsonValue;
+} | JsonFailure;
+/**
+ * Parse one JSON document under the store's rules.
+ *
+ * The bounds are checked while scanning, not afterwards, so a depth
+ * bomb costs its prefix and nothing more.
+ */
+export declare function parseStoreJson(text: string): JsonResult;

package/dist/store/json.js

@@ -0,0 +1,283 @@
+/**
+ * The store's JSON parser: step 2 of the frozen ladder (brief §1.12).
+ *
+ * `JSON.parse` cannot implement that step. It accepts duplicate keys
+ * and silently keeps the last one, it has no depth bound, and — the one
+ * that matters most — `JSON.parse('1e999')` returns `Infinity`, so
+ * "numbers finite" is not a property it gives you. A protocol that
+ * digests or compares values cannot have two spellings of one value,
+ * and it cannot have a value that is not a number.
+ *
+ * So the ladder's second rung is a real parser:
+ *
+ * - depth ≤ {@link MAX_JSON_DEPTH}, counting objects and arrays;
+ * - **duplicate keys refused**, not resolved;
+ * - every number finite, and spelled by the JSON grammar (no `NaN`,
+ *   `Infinity`, `+1`, `.5`, `1.`, `01`, or hex);
+ * - objects built with **null prototypes**, so no parsed document can
+ *   introduce a `__proto__` key that later traversal would follow;
+ * - trailing content refused.
+ *
+ * It returns a refusal rather than throwing: the caller counts it and
+ * answers `invalid-data`, and no mutation has happened by then.
+ */
+/** Depth bound for a store message (brief §1.12). */
+export const MAX_JSON_DEPTH = 16;
+class Refused extends Error {
+    reason;
+    at;
+    constructor(reason, at) {
+        super(reason);
+        this.reason = reason;
+        this.at = at;
+    }
+}
+/**
+ * Parse one JSON document under the store's rules.
+ *
+ * The bounds are checked while scanning, not afterwards, so a depth
+ * bomb costs its prefix and nothing more.
+ */
+export function parseStoreJson(text) {
+    const parser = new Parser(text);
+    try {
+        const value = parser.document();
+        return { ok: true, value };
+    }
+    catch (error) {
+        if (error instanceof Refused) {
+            return { ok: false, reason: error.reason, at: error.at };
+        }
+        throw error;
+    }
+}
+class Parser {
+    src;
+    i = 0;
+    constructor(src) {
+        this.src = src;
+    }
+    document() {
+        this.skipWhitespace();
+        if (this.i >= this.src.length)
+            throw new Refused('empty', this.i);
+        const value = this.value(0);
+        this.skipWhitespace();
+        if (this.i !== this.src.length)
+            throw new Refused('trailing-content', this.i);
+        return value;
+    }
+    value(depth) {
+        const c = this.src.charCodeAt(this.i);
+        switch (c) {
+            case 123 /* Code.OpenBrace */:
+                return this.object(depth + 1);
+            case 91 /* Code.OpenBracket */:
+                return this.array(depth + 1);
+            case 34 /* Code.Quote */:
+                return this.string();
+            default:
+                break;
+        }
+        if (c === 45 /* Code.Minus */ || (c >= 48 /* Code.Zero */ && c <= 57 /* Code.Nine */))
+            return this.number();
+        if (this.src.startsWith('true', this.i)) {
+            this.i += 4;
+            return true;
+        }
+        if (this.src.startsWith('false', this.i)) {
+            this.i += 5;
+            return false;
+        }
+        if (this.src.startsWith('null', this.i)) {
+            this.i += 4;
+            return null;
+        }
+        // `NaN`, `Infinity`, `-Infinity` and `undefined` all land here: they
+        // are not JSON, and accepting them is how a non-finite number gets
+        // in without going through the number grammar.
+        throw new Refused(Number.isNaN(c) ? 'unexpected-end' : 'literal', this.i);
+    }
+    object(depth) {
+        if (depth > MAX_JSON_DEPTH)
+            throw new Refused('depth-exceeded', this.i);
+        this.i += 1; // '{'
+        const out = Object.create(null);
+        this.skipWhitespace();
+        if (this.peek() === 125 /* Code.CloseBrace */) {
+            this.i += 1;
+            return out;
+        }
+        for (;;) {
+            this.skipWhitespace();
+            if (this.peek() !== 34 /* Code.Quote */)
+                throw new Refused('unexpected-token', this.i);
+            const at = this.i;
+            const key = this.string();
+            // Own-property lookup: a document containing `__proto__` must be
+            // refused as a duplicate only if it really repeats, never because
+            // the draft object inherited something.
+            if (Object.prototype.hasOwnProperty.call(out, key)) {
+                throw new Refused('duplicate-key', at);
+            }
+            this.skipWhitespace();
+            if (this.peek() !== 58 /* Code.Colon */)
+                throw new Refused('unexpected-token', this.i);
+            this.i += 1;
+            this.skipWhitespace();
+            out[key] = this.value(depth);
+            this.skipWhitespace();
+            const sep = this.peek();
+            if (sep === 44 /* Code.Comma */) {
+                this.i += 1;
+                continue;
+            }
+            if (sep === 125 /* Code.CloseBrace */) {
+                this.i += 1;
+                return out;
+            }
+            throw new Refused(sep === -1 ? 'unexpected-end' : 'unexpected-token', this.i);
+        }
+    }
+    array(depth) {
+        if (depth > MAX_JSON_DEPTH)
+            throw new Refused('depth-exceeded', this.i);
+        this.i += 1; // '['
+        const out = [];
+        this.skipWhitespace();
+        if (this.peek() === 93 /* Code.CloseBracket */) {
+            this.i += 1;
+            return out;
+        }
+        for (;;) {
+            this.skipWhitespace();
+            out.push(this.value(depth));
+            this.skipWhitespace();
+            const sep = this.peek();
+            if (sep === 44 /* Code.Comma */) {
+                this.i += 1;
+                continue;
+            }
+            if (sep === 93 /* Code.CloseBracket */) {
+                this.i += 1;
+                return out;
+            }
+            throw new Refused(sep === -1 ? 'unexpected-end' : 'unexpected-token', this.i);
+        }
+    }
+    string() {
+        this.i += 1; // '"'
+        let out = '';
+        for (;;) {
+            if (this.i >= this.src.length)
+                throw new Refused('unexpected-end', this.i);
+            const c = this.src.charCodeAt(this.i);
+            if (c === 34 /* Code.Quote */) {
+                this.i += 1;
+                return out;
+            }
+            if (c === 92 /* Code.Backslash */) {
+                out += this.escape();
+                continue;
+            }
+            // Raw control characters are not permitted in a JSON string; a
+            // parser that accepts them accepts two spellings of one value.
+            if (c < 32 /* Code.Space */)
+                throw new Refused('string-control-char', this.i);
+            out += this.src[this.i];
+            this.i += 1;
+        }
+    }
+    escape() {
+        this.i += 1;
+        const c = this.src[this.i];
+        this.i += 1;
+        switch (c) {
+            case '"':
+                return '"';
+            case '\\':
+                return '\\';
+            case '/':
+                return '/';
+            case 'b':
+                return '\b';
+            case 'f':
+                return '\f';
+            case 'n':
+                return '\n';
+            case 'r':
+                return '\r';
+            case 't':
+                return '\t';
+            case 'u': {
+                const hex = this.src.slice(this.i, this.i + 4);
+                if (!/^[0-9a-fA-F]{4}$/.test(hex))
+                    throw new Refused('string-escape', this.i);
+                this.i += 4;
+                return String.fromCharCode(Number.parseInt(hex, 16));
+            }
+            default:
+                throw new Refused('string-escape', this.i - 1);
+        }
+    }
+    number() {
+        const start = this.i;
+        if (this.peek() === 45 /* Code.Minus */)
+            this.i += 1;
+        // Integer part: `0` alone, or a non-zero digit followed by digits.
+        if (this.peek() === 48 /* Code.Zero */) {
+            this.i += 1;
+            if (this.isDigit(this.peek()))
+                throw new Refused('number-grammar', start);
+        }
+        else if (this.isDigit(this.peek())) {
+            while (this.isDigit(this.peek()))
+                this.i += 1;
+        }
+        else {
+            throw new Refused('number-grammar', start);
+        }
+        if (this.peek() === 46 /* Code.Dot */) {
+            this.i += 1;
+            if (!this.isDigit(this.peek()))
+                throw new Refused('number-grammar', start);
+            while (this.isDigit(this.peek()))
+                this.i += 1;
+        }
+        const e = this.src[this.i];
+        if (e === 'e' || e === 'E') {
+            this.i += 1;
+            const sign = this.peek();
+            if (sign === 43 /* Code.Plus */ || sign === 45 /* Code.Minus */)
+                this.i += 1;
+            if (!this.isDigit(this.peek()))
+                throw new Refused('number-grammar', start);
+            while (this.isDigit(this.peek()))
+                this.i += 1;
+        }
+        const value = Number(this.src.slice(start, this.i));
+        // `1e999` is grammatical JSON and is not a number. This is the check
+        // `JSON.parse` does not do.
+        if (!Number.isFinite(value))
+            throw new Refused('number-not-finite', start);
+        return value;
+    }
+    isDigit(c) {
+        return c >= 48 /* Code.Zero */ && c <= 57 /* Code.Nine */;
+    }
+    peek() {
+        if (this.i >= this.src.length)
+            return -1;
+        return this.src.charCodeAt(this.i);
+    }
+    skipWhitespace() {
+        for (;;) {
+            const c = this.peek();
+            if (c === 32 /* Code.Space */ || c === 9 /* Code.Tab */ || c === 10 /* Code.LF */ || c === 13 /* Code.CR */) {
+                this.i += 1;
+                continue;
+            }
+            return;
+        }
+    }
+}

package/dist/store/ledger.d.ts

@@ -0,0 +1,187 @@
+/**
+ * Slice E — the action ledger (§1.10).
+ *
+ * The rule the whole module exists for: **a sequence number identifies
+ * one request, not a slot.** A retained `s` replayed with the same
+ * request returns the same outcome; replayed with a *different* request
+ * it is refused and the retained entry is left alone. Without that, a
+ * caller could overwrite the record of what it asked for.
+ *
+ * ## Why a rejection is retained
+ *
+ * Authorization denial and a handler throw both retain an entry. If a
+ * refusal were simply absent, a later policy change would turn an
+ * earlier refusal into an execution of the same sequence — the same
+ * request succeeding the second time because the record of its refusal
+ * was not kept.
+ *
+ * ## Why the floor exists, and what it cannot say
+ *
+ * The window is bounded three ways (count, bytes, age), and eviction
+ * happens in `s` order so an entry is never dropped while a lower one
+ * is retained. The floor is the highest evicted `s`: at or below it the
+ * owner knows a sequence has been used but no longer knows the outcome,
+ * which is `result-expired` — explicitly NOT a claim that it did or did
+ * not commit. A handle that is gone is a different answer again
+ * (`closed`), because then the owner does not even know the sequence
+ * existed.
+ *
+ * ## The binding, and the one `await`
+ *
+ * The request binding is a canonical `name \x1f json` string, retained
+ * verbatim while it is small and as a SHA-256 when it is not. The small
+ * form is the common case and has no `await` at all, which is the point:
+ * the asynchronous path is the only one where the handle, the policy and
+ * the ledger can change under the request, and it is the only one that
+ * has to revalidate.
+ */
+import type { JsonObject, JsonValue } from './json.js';
+import { type Decimal, type Hex } from './wire.js';
+import type { StoreErrorCode } from './errors.js';
+/** Outcomes retained per handle (§2). */
+export declare const LEDGER_MAX_ENTRIES = 32;
+/** Bytes retained per handle (§2). */
+export declare const LEDGER_MAX_BYTES: number;
+/** How long an outcome is retained (§2). */
+export declare const LEDGER_MAX_AGE_MS = 60000;
+/** Above this, a binding is retained as its digest rather than verbatim. */
+export declare const BINDING_INLINE_MAX_BYTES = 2048;
+/** The highest sequence a handle can reach. It does not wrap. */
+export declare const MAX_SEQUENCE: bigint;
+/**
+ * What a request was, in the form the ledger keeps.
+ *
+ * The form is recorded with the value so a 2 KiB boundary crossing
+ * cannot make two encodings of one request compare unequal.
+ */
+export interface RequestBinding {
+    readonly form: 'inline' | 'digest';
+    readonly value: string;
+}
+/** What happened, in the form a replay can reproduce. */
+export type Outcome = {
+    readonly kind: 'result';
+    readonly out: JsonObject;
+} | {
+    readonly kind: 'refusal';
+    readonly code: StoreErrorCode;
+};
+/** What the owner should do with an arriving `act`. */
+export type Disposition = 
+/** Never seen, above the floor: run it. */
+{
+    readonly kind: 'execute';
+}
+/** Retained, same request: reply the retained outcome under a new envelope. */
+ | {
+    readonly kind: 'replay';
+    readonly outcome: Outcome;
+}
+/** Retained, DIFFERENT request under the same sequence. */
+ | {
+    readonly kind: 'conflict';
+}
+/** Used, evicted: the outcome is no longer known. */
+ | {
+    readonly kind: 'expired';
+}
+/** The counter is exhausted; a fresh handle is the only way on. */
+ | {
+    readonly kind: 'exhausted';
+};
+/**
+ * The canonical form of one request.
+ *
+ * Object keys sort ascending by UTF-16 code unit, there is no
+ * insignificant whitespace, and numbers are rendered by
+ * `Number.prototype.toString` — exact for every value the store admits,
+ * because §1.12 already refuses `NaN`, `Infinity` and duplicate keys,
+ * and identifiers needing full integer precision are strings by §1.1.
+ *
+ * Only the owner computes this and only the owner compares it: it never
+ * crosses the wire, so self-consistency is what matters.
+ */
+export declare function canonicalRequest(name: string, input: JsonValue): string;
+/** How many bytes a canonical form occupies. */
+export declare function canonicalBytes(canonical: string): number;
+/** Whether this binding needs the asynchronous digest path. */
+export declare function needsDigest(canonical: string): boolean;
+/** The binding for a small canonical form. Synchronous by construction. */
+export declare function inlineBinding(canonical: string): RequestBinding;
+/**
+ * The binding for a large canonical form.
+ *
+ * The caller must treat the `await` as a boundary: no authorization
+ * decision and no transaction context may cross it (§1.10).
+ */
+export declare function digestBinding(canonical: string): Promise<RequestBinding>;
+/**
+ * One handle's outcomes.
+ *
+ * Keyed by sequence, bounded by count, bytes and age, evicted in `s`
+ * order so the floor can only ever describe a contiguous prefix.
+ */
+export declare class HandleLedger {
+    #private;
+    private readonly maxEntries;
+    private readonly maxBytes;
+    private readonly maxAgeMs;
+    constructor(maxEntries?: number, maxBytes?: number, maxAgeMs?: number);
+    get floor(): Decimal;
+    get size(): number;
+    get bytesHeld(): number;
+    /**
+     * What to do with `(s, binding)`.
+     *
+     * Pure: it moves nothing, so the owner can call it before the
+     * transaction and — on the digest path — again after the `await`.
+     */
+    disposition(s: bigint, binding: RequestBinding, now: number): Disposition;
+    /**
+     * Retain an outcome.
+     *
+     * A refusal is retained exactly like a result: that is what stops a
+     * policy change from turning an earlier denial into a later
+     * execution of the same sequence.
+     */
+    retain(s: bigint, binding: RequestBinding, outcome: Outcome, now: number): void;
+    /** Drop everything past its age, advancing the floor. */
+    expire(now: number): void;
+    private evict;
+    private drop;
+    private ordered;
+}
+/**
+ * Latest-value inputs (§1.11).
+ *
+ * Monotone per `(handle, name)`: a sequence at or below the last seen
+ * one is dropped and counted. There is no retention, no replay and no
+ * gap recovery, and **loss does not imply a successor** — a dropped
+ * input may be the last one, so the game must tolerate a missing final
+ * input. The coalescing design invites the opposite assumption, which
+ * is why it is stated here beside the code.
+ */
+export declare class InputSequences {
+    #private;
+    /** How many inputs this handle has dropped as stale. */
+    get dropped(): number;
+    /** Whether this input is newer than the last for its name. */
+    admit(name: string, s: bigint): boolean;
+    /** The last admitted sequence for a name, or null. */
+    latest(name: string): Decimal | null;
+}
+/** Per-handle ledger state, created on demand. */
+export declare class LedgerTable {
+    #private;
+    ledger(h: Hex): HandleLedger;
+    inputs(h: Hex): InputSequences;
+    /**
+     * Forget a handle's ledger.
+     *
+     * §2: the ledger goes with the handle, which is why a replay after
+     * eviction is `closed` and not `result-expired` — the owner no
+     * longer knows the sequence existed.
+     */
+    forget(h: Hex): void;
+    get size(): number;
+}