@net-mesh/browser 0.37.0

package/dist/store/visibility.js

@@ -0,0 +1,282 @@
+/**
+ * Declarative visibility: say which parts of the state are secret, and
+ * the host removes them from every player's view before anything is
+ * sent.
+ *
+ * ```ts
+ * defineStore({
+ *   …,
+ *   visibility: {
+ *     'players.*.hand': 'owner',     // only the player whose id is that key
+ *     'deck':           'nobody',    // the host only
+ *     'deck.length':    'everyone',  // …but everyone may count it
+ *     'waypoint':       ['command'], // players reading the `command` audience
+ *   },
+ * });
+ * ```
+ *
+ * Why this exists: a hand-written `project` fails SILENTLY — the game
+ * works and the secret is readable in the browser. Rules declared here
+ * are enforced by the SDK, after any hand-written projection, so code
+ * can narrow what a rule allows but never widen it.
+ *
+ * **The rules.**
+ *
+ * - A path is dot-separated keys; `*` matches any key of an object (or
+ *   index of an array). `deck.length` — a path ending in `.length` —
+ *   reveals only the length of an array its parent rule hides.
+ * - `'everyone'`, `'nobody'` (the host only), `'owner'` (the player
+ *   whose peer id is the key matched by the path's FIRST `*` — the
+ *   `ships[context.peer]` pattern needs no setup), or a list of
+ *   audiences (any one of them suffices).
+ * - Unlisted paths are visible, as without rules. A rule covers
+ *   everything beneath its path, and a deeper rule cannot re-open what
+ *   a shallower one hid (except `.length`).
+ *
+ * **What hidden looks like.** An entry of a collection (a path ending
+ * in `*`) is removed. A field becomes the {@link HIDDEN} marker — never
+ * `0`, `""` or `null`, which a game would read as real values — so the
+ * state validator must accept it there: wrap that field's parser with
+ * {@link hiddenOr}. A counted array becomes an array of markers of the
+ * same length.
+ *
+ * **Presets**, for the common shapes: `'open'` (everyone sees
+ * everything — an explicit decision rather than an accident) and
+ * `'card-game'` (`players.*.hand` owner, `deck` nobody, `deck.length`
+ * everyone). A preset takes overrides: `{ preset: 'card-game',
+ * 'players.*.score': 'nobody' }`.
+ *
+ * **What it cannot do.** The host itself holds everything: a player who
+ * hosts can read every secret in their own tab. Games with real stakes
+ * need a host that is not a player.
+ */
+import { StoreError } from './errors.js';
+/** The one hidden value. Plain JSON, so it survives the wire. */
+export const HIDDEN = Object.freeze({ $hidden: true });
+/** Whether a value is the hidden marker (the original, or one parsed off the wire). */
+export function isHidden(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        !Array.isArray(value) &&
+        Object.keys(value).length === 1 &&
+        value.$hidden === true);
+}
+/** Wrap a field's parser so the field may also be {@link HIDDEN}. */
+export function hiddenOr(parse) {
+    return value => (isHidden(value) ? HIDDEN : parse(value));
+}
+const PRESETS = Object.freeze({
+    'card-game': Object.freeze({
+        'players.*.hand': 'owner',
+        deck: 'nobody',
+        'deck.length': 'everyone',
+    }),
+});
+const SEGMENT = /^(\*|[^.*]+)$/;
+/**
+ * Check and compile a visibility declaration. Throws `invalid-data` for
+ * anything that could not be enforced as written — at definition time,
+ * not at the first projection.
+ */
+export function compileVisibility(visibility) {
+    let declared;
+    if (visibility === 'open') {
+        declared = {};
+    }
+    else if (typeof visibility === 'string') {
+        const preset = PRESETS[visibility];
+        if (preset === undefined)
+            throw new StoreError('invalid-data', `unknown visibility preset '${visibility}'`);
+        declared = { ...preset };
+    }
+    else if (typeof visibility === 'object' && visibility !== null) {
+        const { preset, ...rest } = visibility;
+        declared = {};
+        if (preset !== undefined) {
+            const base = PRESETS[preset];
+            if (base === undefined)
+                throw new StoreError('invalid-data', `unknown visibility preset '${String(preset)}'`);
+            Object.assign(declared, base);
+        }
+        Object.assign(declared, rest);
+    }
+    else {
+        throw new StoreError('invalid-data', 'visibility is a preset name or an object of path → rule');
+    }
+    const rules = [];
+    let perPlayer = false;
+    for (const [path, rule] of Object.entries(declared)) {
+        const segments = path.split('.');
+        if (path.length === 0 || !segments.every(segment => SEGMENT.test(segment))) {
+            throw new StoreError('invalid-data', `visibility path '${path}' is not dot-separated keys and '*'`);
+        }
+        const counts = segments.length > 1 && segments[segments.length - 1] === 'length';
+        const valid = rule === 'everyone' ||
+            rule === 'nobody' ||
+            rule === 'owner' ||
+            (Array.isArray(rule) && rule.length > 0 && rule.every(label => typeof label === 'string' && label.length > 0));
+        if (!valid) {
+            throw new StoreError('invalid-data', `visibility rule for '${path}' must be 'everyone', 'nobody', 'owner' or a non-empty list of audiences`);
+        }
+        if (rule === 'owner') {
+            if (!segments.includes('*')) {
+                throw new StoreError('invalid-data', `'owner' needs a '*' in the path to name the owner: '${path}'`);
+            }
+            perPlayer = true;
+        }
+        rules.push(Object.freeze({ path, segments: Object.freeze(segments), rule, counts }));
+    }
+    // Shallow first: a hidden parent removes its subtree before a child
+    // rule could be looked at.
+    rules.sort((a, b) => a.segments.length - b.segments.length);
+    return Object.freeze({ rules: Object.freeze(rules), perPlayer });
+}
+function allows(rule, captures, viewer) {
+    if (rule === 'everyone')
+        return true;
+    if (rule === 'nobody' || viewer === null)
+        return false;
+    if (rule === 'owner')
+        return captures[0] === viewer.peer;
+    return rule.some(label => viewer.audience.includes(label));
+}
+/** Every concrete location a pattern names in `value`. */
+function matches(value, segments) {
+    const out = [];
+    const walk = (node, depth, keys, captures) => {
+        if (depth === segments.length) {
+            out.push({ keys: [...keys], captures: [...captures], value: node });
+            return;
+        }
+        if (typeof node !== 'object' || node === null)
+            return;
+        const segment = segments[depth];
+        if (segment === '*') {
+            const entries = Array.isArray(node)
+                ? node.map((child, index) => [index, child])
+                : Object.entries(node);
+            for (const [key, child] of entries) {
+                walk(child, depth + 1, [...keys, key], [...captures, String(key)]);
+            }
+            return;
+        }
+        if (Array.isArray(node) || !Object.prototype.hasOwnProperty.call(node, segment))
+            return;
+        walk(node[segment], depth + 1, [...keys, segment], captures);
+    };
+    walk(value, 0, [], []);
+    return out;
+}
+const DROP = Symbol('drop');
+function record(edits, keys, value) {
+    let node = edits;
+    for (const key of keys) {
+        let child = node.children.get(key);
+        if (child === undefined) {
+            child = { children: new Map() };
+            node.children.set(key, child);
+        }
+        node = child;
+    }
+    node.value = value;
+}
+function rebuild(node, edits) {
+    if ('value' in edits)
+        return edits.value;
+    if (edits.children.size === 0 || typeof node !== 'object' || node === null)
+        return node;
+    if (Array.isArray(node)) {
+        const out = [];
+        node.forEach((child, index) => {
+            const edit = edits.children.get(index);
+            const next = edit === undefined ? child : rebuild(child, edit);
+            if (next !== DROP)
+                out.push(next);
+        });
+        return out;
+    }
+    const out = {};
+    for (const [key, child] of Object.entries(node)) {
+        const edit = edits.children.get(key);
+        const next = edit === undefined ? child : rebuild(child, edit);
+        if (next !== DROP)
+            out[key] = next;
+    }
+    return out;
+}
+const SEP = '\u0000';
+/**
+ * Apply compiled rules for one viewer (`null`: nobody in particular —
+ * sees only what `'everyone'` may).
+ */
+export function applyVisibility(compiled, state, viewer) {
+    if (compiled.rules.length === 0)
+        return state;
+    const edits = { children: new Map() };
+    // Every hidden location, by its joined path, so "is this under a
+    // hidden ancestor" is a lookup per prefix, not a scan of all of them.
+    const hidden = new Set();
+    let touched = false;
+    for (const rule of compiled.rules) {
+        if (rule.counts)
+            continue;
+        // A `.length` rule on this path may reveal the count.
+        const countRule = compiled.rules.find(candidate => candidate.counts &&
+            candidate.segments.length === rule.segments.length + 1 &&
+            candidate.segments.slice(0, -1).every((segment, index) => segment === rule.segments[index]));
+        // Last pattern segment a wildcard: an entry of a collection, removed.
+        const entry = rule.segments[rule.segments.length - 1] === '*';
+        for (const match of matches(state, rule.segments)) {
+            let prefix = '';
+            let under = false;
+            for (let i = 0; i < match.keys.length - 1 && !under; i += 1) {
+                prefix = i === 0 ? String(match.keys[0]) : `${prefix}${SEP}${String(match.keys[i])}`;
+                under = hidden.has(prefix);
+            }
+            if (under)
+                continue;
+            if (allows(rule.rule, match.captures, viewer))
+                continue;
+            let replacement = entry ? DROP : HIDDEN;
+            if (countRule !== undefined && Array.isArray(match.value) && allows(countRule.rule, match.captures, viewer)) {
+                replacement = match.value.map(() => HIDDEN);
+            }
+            record(edits, match.keys, replacement);
+            hidden.add(match.keys.map(String).join(SEP));
+            touched = true;
+        }
+    }
+    return (touched ? rebuild(state, edits) : state);
+}
+/**
+ * The view a viewer would receive under a definition's declared rules,
+ * for tests and tools. (A host also applies its hand-written `project`
+ * / `projectFor` first; this is the rules alone.)
+ */
+export function projectVisible(definition, state, viewer) {
+    if (definition.visibility === undefined)
+        return state;
+    return applyVisibility(compileVisibility(definition.visibility), state, viewer);
+}
+/**
+ * Throw if `viewer` could read any of `paths` (concrete dot paths, e.g.
+ * `players.bob.hand`) under the definition's rules. Absent, or the
+ * hidden marker, is hidden; anything else is a leak.
+ */
+export function assertHidden(definition, state, viewer, paths) {
+    const view = projectVisible(definition, state, viewer);
+    for (const path of paths) {
+        let node = view;
+        for (const key of path.split('.')) {
+            if (typeof node !== 'object' || node === null || !Object.prototype.hasOwnProperty.call(node, key)) {
+                node = undefined;
+                break;
+            }
+            node = node[key];
+        }
+        const leaked = node !== undefined && !isHidden(node) && !(Array.isArray(node) && node.every(element => isHidden(element)));
+        if (leaked) {
+            throw new Error(`'${path}' is visible to ${viewer === null ? 'nobody in particular' : viewer.peer}`);
+        }
+    }
+}

package/dist/store/wire.d.ts

@@ -0,0 +1,309 @@
+/**
+ * The store's wire protocol: shapes, the parser ladder, canonical
+ * encodings (brief §1.4, §1.12, §2).
+ *
+ * Two entry points, and they share every rule: {@link decodeMessage}
+ * refuses anything the protocol does not define, and
+ * {@link encodeMessage} refuses to *produce* anything it would refuse
+ * to accept. One validator, both directions — a producer that can emit
+ * a frame the parser rejects is a bug that only shows up on the far
+ * side of a network.
+ *
+ * ## The ladder, and where it stops here
+ *
+ * §1.12 is ordered, cheap checks first, and none of them may run after
+ * a mutation. This module implements the rungs that are decidable from
+ * the frame alone:
+ *
+ * 1. **byte length** against the runtime's admissible size → `capacity`
+ *    (a declared bound was reached), refused **before** parsing;
+ * 2. **JSON** under `json.ts` — depth, duplicate keys, finite numbers;
+ * 3. **envelope** — `v` known, `k` in the closed set, `q`/`h` present
+ *    exactly where the kind requires them;
+ * 4. **direction** — a replica that receives `act`, or an owner that
+ *    receives `delta`, refuses `invalid-data`;
+ * 6. **payload** — per-kind required/optional fields, unknown fields
+ *    refused, and every value in its canonical spelling.
+ *
+ * Rung 4's *admission class* (`not-ready` for gameplay before
+ * readiness) and rung 5 (**binding**: handle active, bound to this
+ * authenticated peer, per-kind generation checks) are **not here**.
+ * They are decidable only against handle state, which is owner dispatch
+ * — a later slice. This module deliberately answers "is this a legal
+ * frame", never "may this caller do this now", and callers must not
+ * read a successful decode as authorization.
+ */
+import { type StoreErrorCode } from './errors.js';
+import { type JsonObject, type JsonValue } from './json.js';
+/** The only protocol version this build speaks. */
+export declare const WIRE_VERSION = 1;
+/** Exact hex lengths (brief §1.12: lowercase only, exact length). */
+export declare const HANDLE_HEX_LENGTH = 32;
+export declare const REQUEST_HEX_LENGTH = 16;
+export declare const INCARNATION_HEX_LENGTH = 16;
+/** Audience bounds (brief §2). */
+export declare const MAX_AUDIENCE_LABELS = 32;
+export declare const MAX_AUDIENCE_LABEL_BYTES = 128;
+/**
+ * Interest keys per request, and bytes per key. Interest is a spatial
+ * filter, not a permission, so its bound is separate from — and larger
+ * than — the audience's; the frame budget is what really caps it.
+ */
+export declare const MAX_INTEREST_KEYS = 256;
+export declare const MAX_INTEREST_KEY_BYTES = 64;
+/** Snapshot bounds (brief §2). */
+export declare const MAX_SNAPSHOT_BYTES: number;
+export declare const MAX_SNAPSHOT_CHUNKS = 255;
+/** Patch bounds (brief §2, applied structurally here, semantically in `patch.ts`). */
+export declare const MAX_PATCH_OPS = 256;
+export declare const MAX_PATH_SEGMENTS = 8;
+export declare const MAX_PATH_SEGMENT_BYTES = 64;
+/** `no.detail` is truncated at the owner to this (brief §2). */
+export declare const MAX_DETAIL_BYTES = 256;
+/** The largest value a canonical decimal may carry. */
+export declare const MAX_DECIMAL = 18446744073709551615n;
+/** Caller → owner kinds (brief §1.4). */
+export declare const CALLER_KINDS: readonly ["join", "resume", "resync", "act", "in", "aud", "alive", "leave", "int"];
+/** Owner → caller kinds (brief §1.4). */
+export declare const OWNER_KINDS: readonly ["man", "snap", "delta", "res", "ok", "no"];
+export type CallerKind = (typeof CALLER_KINDS)[number];
+export type OwnerKind = (typeof OWNER_KINDS)[number];
+export type MessageKind = CallerKind | OwnerKind;
+/**
+ * A decimal field, kept as the **wire spelling**.
+ *
+ * `g`, `r`, `s`, `base`, `have` and `bytes` are `u64`-ranged decimal
+ * strings, not JSON numbers, and they are not converted on decode: the
+ * canonical spelling is the value's identity here, and re-deriving it
+ * from a `number` would silently lose precision above 2^53 and give one
+ * value two spellings. Use {@link decimalValue} when arithmetic is
+ * actually needed.
+ */
+export type Decimal = string;
+/** Lowercase, exact-length hex. */
+export type Hex = string;
+export interface JoinMessage {
+    readonly k: 'join';
+    readonly q: Hex;
+    readonly def: string;
+    readonly ver: number;
+    /** Which store of this definition — the owner's declared address. */
+    readonly store: string;
+    readonly key: string;
+    readonly aud: readonly string[];
+    readonly int?: readonly string[];
+}
+export interface ResumeMessage {
+    readonly k: 'resume';
+    readonly q: Hex;
+    readonly h: Hex;
+    readonly aud: readonly string[];
+    readonly int?: readonly string[];
+}
+/** Replace the caller's interest set; answered by a delta, then `ok`. */
+export interface InterestMessage {
+    readonly k: 'int';
+    readonly q: Hex;
+    readonly h: Hex;
+    readonly int: readonly string[];
+}
+export interface ResyncMessage {
+    readonly k: 'resync';
+    readonly q: Hex;
+    readonly h: Hex;
+    readonly g: Decimal;
+    readonly have: Decimal;
+}
+export interface AudienceMessage {
+    readonly k: 'aud';
+    readonly q: Hex;
+    readonly h: Hex;
+    readonly aud: readonly string[];
+}
+export interface AliveMessage {
+    readonly k: 'alive';
+    readonly q: Hex;
+    readonly h: Hex;
+}
+export interface LeaveMessage {
+    readonly k: 'leave';
+    readonly q: Hex;
+    readonly h: Hex;
+}
+export interface ActMessage {
+    readonly k: 'act';
+    readonly q: Hex;
+    readonly h: Hex;
+    readonly s: Decimal;
+    readonly name: string;
+    readonly in: JsonObject;
+}
+export interface InputMessage {
+    readonly k: 'in';
+    readonly h: Hex;
+    readonly name: string;
+    readonly s: Decimal;
+    readonly in: JsonObject;
+}
+export interface ManifestMessage {
+    readonly k: 'man';
+    readonly q?: Hex;
+    readonly h: Hex;
+    readonly inc: Hex;
+    readonly g: Decimal;
+    readonly r: Decimal;
+    readonly n: number;
+    readonly bytes: Decimal;
+}
+export interface SnapMessage {
+    readonly k: 'snap';
+    readonly h: Hex;
+    readonly g: Decimal;
+    readonly r: Decimal;
+    readonly i: number;
+    readonly n: number;
+    readonly d: string;
+}
+export interface DeltaMessage {
+    readonly k: 'delta';
+    readonly h: Hex;
+    readonly g: Decimal;
+    readonly base: Decimal;
+    readonly r: Decimal;
+    readonly ops: readonly WireOp[];
+}
+export interface ResultMessage {
+    readonly k: 'res';
+    readonly q: Hex;
+    readonly h: Hex;
+    readonly s: Decimal;
+    readonly out: JsonObject;
+}
+export interface OkMessage {
+    readonly k: 'ok';
+    readonly q: Hex;
+    readonly h: Hex;
+}
+export interface NoMessage {
+    readonly k: 'no';
+    readonly q?: Hex;
+    readonly h?: Hex;
+    readonly code: StoreErrorCode;
+    readonly s?: Decimal;
+    readonly detail?: string;
+}
+/** A patch operation as it appears on the wire (semantics: `patch.ts`). */
+export type WireOp = {
+    readonly o: 'r';
+    readonly p: readonly string[];
+    readonly val: JsonValue;
+} | {
+    readonly o: 'x';
+    readonly p: readonly string[];
+};
+/** Every kind a caller sends. What an **owner** can receive. */
+export type CallerMessage = JoinMessage | ResumeMessage | InterestMessage | ResyncMessage | AudienceMessage | AliveMessage | LeaveMessage | ActMessage | InputMessage;
+/** Every kind an owner sends. What a **replica** can receive. */
+export type OwnerMessage = ManifestMessage | SnapMessage | DeltaMessage | ResultMessage | OkMessage | NoMessage;
+/**
+ * What a given side can receive.
+ *
+ * The direction rung (§1.12) is a type here as well as a check: an
+ * owner's decode cannot yield a `delta`, so a dispatcher does not need
+ * a dead branch to prove it.
+ */
+export type MessageFor<T extends Side> = T extends 'owner' ? CallerMessage : OwnerMessage;
+export type StoreMessage = JoinMessage | ResumeMessage | InterestMessage | ResyncMessage | AudienceMessage | AliveMessage | LeaveMessage | ActMessage | InputMessage | ManifestMessage | SnapMessage | DeltaMessage | ResultMessage | OkMessage | NoMessage;
+/** Which side is reading (rung 4: direction). */
+export type Side = 'owner' | 'replica';
+/** Which rung refused the frame. */
+export type DecodeStage = 'bytes' | 'json' | 'envelope' | 'direction' | 'payload';
+export interface DecodeRefusal {
+    readonly ok: false;
+    /** The wire code a dispatcher answers with. */
+    readonly code: StoreErrorCode;
+    readonly stage: DecodeStage;
+    /**
+     * A stable, countable reason. The dispatcher counts these; they are
+     * not caller-facing text, and they never carry frame content.
+     */
+    readonly reason: string;
+}
+export type DecodeResult<T extends Side = Side> = {
+    readonly ok: true;
+    readonly message: MessageFor<T>;
+} | DecodeRefusal;
+export interface DecodeOptions<T extends Side = Side> {
+    /**
+     * The admissible frame size, **derived at runtime** from the
+     * transport (`LeafNode.maxEventBytes()` minus the kind's envelope
+     * reserve) and never hardcoded here — a store that guessed this
+     * number would be wrong on the first transport that changed.
+     */
+    readonly maxBytes: number;
+    /** The side reading the frame, for the direction rung. */
+    readonly as: T;
+}
+/** UTF-8 byte length without allocating a copy of the bytes. */
+export declare function utf8Length(text: string): number;
+/**
+ * Decode one store frame.
+ *
+ * Never throws for bad input: a refusal is a value, because the
+ * dispatcher must count it and answer, and an exception path is how
+ * "count it" gets skipped.
+ */
+export declare function decodeMessage<T extends Side>(frame: string, options: DecodeOptions<T>): DecodeResult<T>;
+/** Lowercase hex, exact length checked by the caller. */
+export declare function isCanonicalHex(value: string): boolean;
+/**
+ * ASCII digits, no sign, no leading zero unless the value is exactly
+ * `"0"`, ≤ 20 digits, ≤ 2^64 − 1 (brief §1.12).
+ */
+export declare function isCanonicalDecimal(value: string): boolean;
+/**
+ * Standard alphabet, correctly padded, no whitespace or line breaks.
+ *
+ * Also rejects a *decodable but non-canonical* tail: base64 pads to a
+ * multiple of four, and the bits before the padding must be zero, so
+ * `"QQ=="` is canonical for `A` while `"QR=="` decodes to the same byte
+ * and is not.
+ */
+export declare function isCanonicalBase64(value: string): boolean;
+/** The numeric value of a canonical decimal field. */
+export declare function decimalValue(value: Decimal): bigint;
+/**
+ * Whether a value survives JSON serialization as itself.
+ *
+ * `JSON.stringify` is **lossy and silent**: `NaN`, `Infinity` and
+ * `-Infinity` become `null`, and `undefined`, functions and symbols
+ * are dropped from objects and become `null` in arrays. Validating the
+ * serialized text therefore cannot see what was asked for — the
+ * evidence is already gone — so an action input of `{n: NaN}` encoded
+ * happily as `{"n":null}` and sent a value the caller never wrote.
+ *
+ * It also TRANSFORMS some values and THROWS on others, all before any
+ * scan of the serialized text could see anything: a `toJSON` method
+ * replaces its object wholesale (a `Date` ships as a string), a
+ * `Map`/`Set` ships as `{}` with its entries gone, an own symbol key
+ * is never serialized at all, and a cycle or a `BigInt` raises a bare
+ * `TypeError` out of the serializer itself.
+ *
+ * These are ordinary values at the type level; no cast or exotic
+ * object is needed to produce them. So the source values are checked
+ * **before** serialization, and an inadmissible one is a refusal
+ * rather than a substitution or an escape. `null` itself stays
+ * admissible: an intentional null is data.
+ */
+export declare function inadmissibleValue(value: unknown, path: string): string | null;
+/**
+ * Encode a message in its canonical spelling.
+ *
+ * Validates the **source values** first — because serialization
+ * destroys the evidence of a non-finite number — then validates the
+ * serialized frame through {@link decodeMessage}'s own rules, so a
+ * producer cannot emit a frame the parser would refuse. Throws rather
+ * than returning a refusal: this is a local programming error, not
+ * untrusted input.
+ */
+export declare function encodeMessage(message: StoreMessage): string;