@moxxy/core 0.5.0 → 0.5.1

package/src/usage-stats.ts

@@ -1,8 +1,7 @@
 import { promises as fs } from 'node:fs';
-import * as os from 'node:os';
-import * as path from 'node:path';
 import { addModelTotals, createMutex, type ModelUsageTotals } from '@moxxy/sdk';
-import { writeFileAtomic } from '@moxxy/sdk/server';
+import { moxxyPath, writeFileAtomic } from '@moxxy/sdk/server';
+import { z } from 'zod';
 
 /**
  * Cross-session token usage, persisted at ~/.moxxy/usage.json. A forward-going
@@ -30,13 +29,36 @@ export interface UsageStatsFile {
 }
 
 export function usageStatsPath(): string {
-  return path.join(os.homedir(), '.moxxy', 'usage.json');
+  // Route through `moxxyPath` so a `$MOXXY_HOME` override relocates the usage
+  // aggregate alongside the rest of the data dir. Identical to
+  // `~/.moxxy/usage.json` when MOXXY_HOME is unset.
+  return moxxyPath('usage.json');
 }
 
 function emptyStats(): UsageStatsFile {
   return { version: 1, updatedAt: new Date().toISOString(), models: {} };
 }
 
+// Validates the on-disk shape so a hand-edited or partially-written file with a
+// non-numeric counter (e.g. `inputTokens: "100"`) can't flow into
+// `addModelTotals` and corrupt the persisted aggregate via string concatenation.
+// A failed parse falls through to `emptyStats()`, exactly like malformed JSON.
+const storedModelUsageSchema = z.object({
+  calls: z.number(),
+  inputTokens: z.number(),
+  outputTokens: z.number(),
+  cacheReadTokens: z.number(),
+  cacheCreationTokens: z.number(),
+  firstSeen: z.string(),
+  lastSeen: z.string(),
+});
+
+const usageStatsFileSchema = z.object({
+  version: z.literal(1),
+  updatedAt: z.string(),
+  models: z.record(z.string(), storedModelUsageSchema),
+});
+
 /**
  * Read the usage aggregate. Returns an empty file when missing or unparseable —
  * usage stats are an optional, non-load-blocking layer.
@@ -44,17 +66,12 @@ function emptyStats(): UsageStatsFile {
 export async function loadUsageStats(filePath: string = usageStatsPath()): Promise<UsageStatsFile> {
   try {
     const raw = await fs.readFile(filePath, 'utf8');
-    const parsed = JSON.parse(raw) as unknown;
-    if (
-      parsed &&
-      typeof parsed === 'object' &&
-      typeof (parsed as UsageStatsFile).models === 'object' &&
-      (parsed as UsageStatsFile).models !== null
-    ) {
-      return parsed as UsageStatsFile;
-    }
+    const result = usageStatsFileSchema.safeParse(JSON.parse(raw));
+    if (result.success) return result.data;
+    // shape-invalid (e.g. a non-numeric counter) — start fresh rather than let
+    // a corrupt entry poison the aggregate via string-concat addition.
   } catch {
-    // missing or malformed — start fresh
+    // missing or malformed JSON — start fresh
   }
   return emptyStats();
 }
@@ -97,7 +114,7 @@ export async function mergeUsageStats(
       if (d.calls === 0) continue;
       const existing = models[key];
       models[key] = existing
-        ? { ...addModelTotals(existing, d), firstSeen: existing.firstSeen, lastSeen: now }
+        ? { ...addModelTotals(existing, d), firstSeen: existing.firstSeen ?? now, lastSeen: now }
         : { ...d, firstSeen: now, lastSeen: now };
     }
     const next: UsageStatsFile = { version: 1, updatedAt: now, models };
@@ -113,7 +130,15 @@ export async function mergeUsageStats(
   });
 }
 
-/** Reset the aggregate to empty (the user-facing `/usage clear`). */
+/**
+ * Reset the aggregate to empty (the user-facing `/usage clear`). Runs inside the
+ * same `mergeMutex` as `mergeUsageStats` so a clear can't interleave with an
+ * in-flight merge's read-modify-write — otherwise the merge could write its
+ * stale-plus-delta snapshot back after the clear lands and resurrect the cleared
+ * aggregate (or the clear could clobber a concurrent merge).
+ */
 export async function clearUsageStats(filePath: string = usageStatsPath()): Promise<void> {
-  await writeAtomic(emptyStats(), filePath);
+  await mergeMutex.run(async () => {
+    await writeAtomic(emptyStats(), filePath);
+  });
 }

package/src/view/parse-extended.test.ts

@@ -60,6 +60,21 @@ describe('attribute coercion', () => {
     hasErr('<view><heading level="5">x</heading></view>', /must be ≤ 3/);
   });
 
+  it('rejects JS numeric-literal syntax (hex/binary/octal/exponent) — only plain decimals', () => {
+    // `Number()` would silently turn these into surprising values: `0x4`→4 (a
+    // human reads hex 16), `0b100`→4, `1e1`→10. The agent must get a clear error
+    // instead of a guessed value that doesn't match what it typed.
+    hasErr('<view><grid cols="0x4"></grid></view>', /must be a number/);
+    hasErr('<view><grid cols="0b100"></grid></view>', /must be a number/);
+    hasErr('<view><grid cols="0o7"></grid></view>', /must be a number/);
+    hasErr('<view><grid cols="1e1"></grid></view>', /must be a number/);
+    hasErr('<view><grid cols="Infinity"></grid></view>', /must be a number/);
+    // Plain decimals (incl. whitespace-padded, signed, fractional) still coerce.
+    expect(find(ok('<view><grid cols="  3  "></grid></view>').root, 'grid')!.props.cols).toBe(3);
+    expect(find(ok('<view><image src="/x" w="1.5" /></view>').root, 'image')!.props.w).toBe(1.5);
+    expect(find(ok('<view><image src="/x" w="-2" /></view>').root, 'image')!.props.w).toBe(-2);
+  });
+
   it('validates each enum attribute', () => {
     ok('<view><stack gap="lg" align="center"></stack></view>');
     ok('<view><row justify="between"></row></view>');
@@ -87,6 +102,23 @@ describe('text + entities + comments', () => {
     expect(firstText(find(doc.root, 'text')!)).toBe('a & b <tag> "q"');
   });
 
+  it('decodes decimal + hex numeric character references in text', () => {
+    const doc = ok('<view><text>&#x3C;&#60; &#9731; &#x263A;</text></view>');
+    expect(firstText(find(doc.root, 'text')!)).toBe('<< ☃ ☺');
+  });
+
+  it('decodes entities in a single pass — a double-encoded ampersand is not re-decoded', () => {
+    // `&amp;#58;` must become the literal `&#58;`, not `:` (which a chained
+    // replace of `&amp;`-then-`&#58;` would wrongly produce).
+    const doc = ok('<view><text>a &amp;#58; b</text></view>');
+    expect(firstText(find(doc.root, 'text')!)).toBe('a &#58; b');
+  });
+
+  it('leaves an out-of-range / malformed numeric reference as literal text', () => {
+    const doc = ok('<view><text>&#xZZ; &#999999999; ok</text></view>');
+    expect(firstText(find(doc.root, 'text')!)).toBe('&#xZZ; &#999999999; ok');
+  });
+
   it('drops whitespace-only text nodes', () => {
     const doc = ok('<view>\n  <stack>\n    <text>hi</text>\n  </stack>\n</view>');
     const stack = find(doc.root, 'stack')!;
@@ -162,6 +194,19 @@ describe('security rejections', () => {
     hasErr('<view><image src="data:text/html,<script>" />\n</view>', /disallowed URL scheme/);
     hasErr('<view><link href="ftp://x">y</link></view>', /disallowed URL scheme/);
   });
+
+  it('numeric-entity-obfuscated scheme is decoded then rejected (no relative-URL bypass)', () => {
+    // A browser decodes `&#58;`/`&#x3a;` to `:` at click time, so the parser
+    // must too BEFORE the scheme check — otherwise `javascript&#58;alert(1)`
+    // looks like a harmless relative URL here yet executes as javascript: in the
+    // shared view. (Named-only entity decoding missed these → live click-XSS.)
+    hasErr('<view><link href="javascript&#58;alert(1)">x</link></view>', /disallowed URL scheme/);
+    hasErr('<view><link href="javascript&#x3a;alert(1)">x</link></view>', /disallowed URL scheme/);
+    hasErr('<view><link href="java&#115;cript:alert(1)">x</link></view>', /disallowed URL scheme/);
+    hasErr('<view><image src="data&#58;text/html,x" /></view>', /disallowed URL scheme/);
+    // A double-encoded ampersand must NOT be re-decoded into a live scheme.
+    ok('<view><link href="https://x/?a&amp;#58;b">y</link></view>');
+  });
 });
 
 describe('action extraction', () => {
@@ -252,4 +297,39 @@ describe('large / deep documents', () => {
     const doc = ok(`<view>${inner}</view>`);
     expect(firstText(doc.root)).toBe('deep');
   });
+
+  it('rejects nesting past the depth cap instead of overflowing the stack', () => {
+    let inner = '<text>deep</text>';
+    for (let i = 0; i < 1000; i++) inner = `<stack>${inner}</stack>`;
+    const r = parse(`<view>${inner}</view>`);
+    expect(r.ok).toBe(false);
+    if (r.ok) return;
+    expect(r.errors.some((e) => /view nesting too deep/.test(e.message))).toBe(true);
+  });
+});
+
+describe('brace attribute values', () => {
+  it('strips outer braces and treats the inner text as the literal value', () => {
+    const doc = ok('<view><text>{plain}</text><image src="/x.png" alt={hello} /></view>');
+    expect(find(doc.root, 'image')!.props.alt).toBe('hello');
+  });
+
+  it('runs the URL-scheme check on the de-braced value (no { } bypass)', () => {
+    // The braces must NOT classify `{javascript:…}` as a harmless relative URL.
+    hasErr('<view><link href={javascript:alert(1)}>x</link></view>', /disallowed URL scheme/);
+    ok('<view><link href={https://ok.test/}>x</link></view>');
+  });
+});
+
+describe('component allow-list / expander coverage', () => {
+  it('rejects a component-flagged tag that has no registered expander', () => {
+    const allow = [
+      { tag: 'view', attrs: {}, allowedChildren: 'any' as const },
+      { tag: 'widget', attrs: {}, allowedChildren: 'none' as const, component: true },
+    ];
+    const r = parseView('<view><widget /></view>', allow);
+    expect(r.ok).toBe(false);
+    if (r.ok) return;
+    expect(r.errors.some((e) => /no registered expander/.test(e.message))).toBe(true);
+  });
 });

package/src/view/parse.test.ts

@@ -229,4 +229,18 @@ describe('validateDoc', () => {
     expect(errsFor('link', { href: 'https://example.com' })).toEqual([]);
     expect(errsFor('image', { src: 'data:image/png;base64,AAAA' })).toEqual([]);
   });
+
+  it('rejects a pathologically deep hand-built AST instead of overflowing the stack', () => {
+    // A validator that itself throws RangeError is worse than one that rejects.
+    // Build a tree far deeper than the parser's source-length budget would allow.
+    let root: ViewNode = { kind: 'element', tag: 'stack', props: {}, children: [] };
+    for (let i = 0; i < 20000; i++) {
+      root = { kind: 'element', tag: 'stack', props: {}, children: [root] };
+    }
+    let errs: ReadonlyArray<{ message: string }> = [];
+    expect(() => {
+      errs = validateDoc({ root }, DEFAULT_VIEW_TAGS);
+    }).not.toThrow();
+    expect(errs.some((e) => /view nesting too deep/.test(e.message))).toBe(true);
+  });
 });

package/src/view/parse.ts

@@ -19,6 +19,16 @@ import type {
  * nodes. The browser renderer applies the same allow-list as defense in depth.
  */
 
+/**
+ * Hard cap on view-tree nesting depth, honored by every recursive descent
+ * (convert/expand/validateDoc). Comfortably above any legitimate UI but far
+ * below Node's native call-stack limit, so a hostile or malformed AST yields a
+ * normal {@link ViewParseError} instead of an uncaught `RangeError: Maximum
+ * call stack size exceeded`. parseView already converts a thrown overflow into
+ * a clean result; validateDoc has no such guard, so the cap is the wall there.
+ */
+const MAX_VIEW_DEPTH = 256;
+
 // ---------------------------------------------------------------------------
 // Tokenizer
 // ---------------------------------------------------------------------------
@@ -169,7 +179,13 @@ function parseAttrs(s: string): RawAttr[] {
           }
           i++;
         }
-        value = s.slice(start, i); // keep braces; raw
+        // There is no JSX-expression evaluation behind `{...}`; strip the outer
+        // braces and treat the inner text as the literal value so it flows
+        // through coerceValue (incl. the href/src URL-scheme check) on the
+        // de-braced string — keeping the braces would smuggle a `{javascript:…}`
+        // past isSafeViewUrl as a bogus relative URL.
+        const raw = s.slice(start, i);
+        value = raw.startsWith('{') && raw.endsWith('}') ? raw.slice(1, -1) : raw;
       } else {
         while (i < n && !/\s/.test(s[i]!)) {
           value += s[i]!;
@@ -228,14 +244,47 @@ function build(tokens: Token[], src: string): BNode {
   return elements[0]!;
 }
 
+const NAMED_ENTITIES: Record<string, string> = {
+  lt: '<',
+  gt: '>',
+  quot: '"',
+  apos: "'",
+  amp: '&',
+};
+
+/**
+ * Decode the named + numeric HTML character references a browser would resolve.
+ * Done in a SINGLE pass (one regex) so each `&…;` is consumed exactly once: a
+ * double-encoded `&amp;#58;` yields the literal `&#58;` rather than being
+ * re-decoded to `:` (which a naive chain of `.replace()` calls would do).
+ *
+ * Numeric references (`&#58;`, `&#x3a;`) MUST be decoded here, not just the
+ * named ones: this output feeds the href/src URL-scheme check in coerceValue,
+ * and a browser decodes `javascript&#58;alert(1)` to `javascript:` at click
+ * time. Decoding numeric refs first means isSafeViewUrl sees the same `:` the
+ * browser will, so an entity-obfuscated `javascript:`/`data:text` scheme is
+ * rejected instead of sailing through as a bogus relative URL. The SDK check
+ * additionally strips C0 control chars, so a numeric ref that decodes to one
+ * cannot smuggle a scheme either.
+ */
 function decodeEntities(s: string): string {
-  return s
-    .replace(/&lt;/g, '<')
-    .replace(/&gt;/g, '>')
-    .replace(/&quot;/g, '"')
-    .replace(/&#39;/g, "'")
-    .replace(/&apos;/g, "'")
-    .replace(/&amp;/g, '&');
+  if (s.indexOf('&') === -1) return s;
+  return s.replace(/&(#x[0-9a-fA-F]+|#[0-9]+|[a-zA-Z][a-zA-Z0-9]*);/g, (whole, body: string) => {
+    if (body[0] === '#') {
+      const code = body[1] === 'x' || body[1] === 'X' ? parseInt(body.slice(2), 16) : parseInt(body.slice(1), 10);
+      // Reject out-of-range / non-character code points (surrogates, > U+10FFFF);
+      // leave the raw text untouched rather than emit U+FFFD or throw.
+      if (!Number.isFinite(code) || code < 0 || code > 0x10ffff || (code >= 0xd800 && code <= 0xdfff)) {
+        return whole;
+      }
+      try {
+        return String.fromCodePoint(code);
+      } catch {
+        return whole;
+      }
+    }
+    return Object.prototype.hasOwnProperty.call(NAMED_ENTITIES, body) ? NAMED_ENTITIES[body]! : whole;
+  });
 }
 
 // ---------------------------------------------------------------------------
@@ -262,7 +311,13 @@ function coerceValue(
     return '';
   }
   if (spec.type === 'number') {
-    const num = Number(value);
+    // Only accept a plain decimal the agent actually wrote. JS `Number()` also
+    // parses `0x10`/`0b1`/`0o7`/`1e3` — so `cols="0x4"` would silently become 4
+    // (a human reads hex 16) and `cols="1e1"` → 10, surprising the author.
+    // Require an optional sign + digits with at most one decimal point; reject
+    // everything else with a clear error instead of guessing.
+    const trimmed = value.trim();
+    const num = /^[+-]?(\d+\.?\d*|\.\d+)$/.test(trimmed) ? Number(trimmed) : NaN;
     if (!Number.isFinite(num)) {
       errors.push({ message: `<${tag}> attribute "${name}" must be a number` });
       return 0;
@@ -326,11 +381,16 @@ function coerceAttrs(b: BNode, spec: ViewTagSpec | undefined, errors: ViewParseE
   return out;
 }
 
-function convert(b: BNode, specByTag: Map<string, ViewTagSpec>, errors: ViewParseError[]): ViewNode {
+function convert(b: BNode, specByTag: Map<string, ViewTagSpec>, errors: ViewParseError[], depth = 0): ViewNode {
   const spec = specByTag.get(b.tag);
   if (!spec) errors.push({ message: `unknown tag <${b.tag}>` });
   const props = coerceAttrs(b, spec, errors);
   const children: ViewNode[] = [];
+  if (depth >= MAX_VIEW_DEPTH) {
+    // Bound the descent rather than recurse into a native stack overflow.
+    errors.push({ message: `<${b.tag}> view nesting too deep (max ${MAX_VIEW_DEPTH})` });
+    return finalizeNode({ kind: 'element', tag: b.tag, props, children }, spec);
+  }
   for (const c of b.children) {
     if (!isBNode(c)) {
       const v = c.text.replace(/\s+/g, ' ').trim();
@@ -347,7 +407,7 @@ function convert(b: BNode, specByTag: Map<string, ViewTagSpec>, errors: ViewPars
           errors.push({ message: `<${b.tag}> may not contain <${c.tag}>` });
         }
       }
-      children.push(convert(c, specByTag, errors));
+      children.push(convert(c, specByTag, errors, depth + 1));
     }
   }
   return finalizeNode({ kind: 'element', tag: b.tag, props, children }, spec);
@@ -442,10 +502,37 @@ function expandResults(node: Extract<ViewNode, { kind: 'element' }>): ViewNode {
   return el('stack', { gap: 'md' }, cards);
 }
 
-function expand(node: ViewNode): ViewNode {
+/**
+ * Per-component expanders keyed by tag. A {@link ViewTagSpec} marked
+ * `component: true` MUST have an entry here; expand() asserts that invariant so
+ * an unexpanded component can never reach a frontend that only knows
+ * primitives. Add a new rich component by registering its expander, not by
+ * editing expand()'s control flow.
+ */
+const EXPANDERS: Record<string, (node: Extract<ViewNode, { kind: 'element' }>) => ViewNode> = {
+  results: expandResults,
+};
+
+function expand(
+  node: ViewNode,
+  specByTag: Map<string, ViewTagSpec>,
+  errors: ViewParseError[],
+  depth = 0,
+): ViewNode {
   if (node.kind !== 'element') return node;
-  if (node.tag === 'results') return expandResults(node);
-  return { ...node, children: node.children.map(expand) };
+  if (depth >= MAX_VIEW_DEPTH) {
+    errors.push({ message: `<${node.tag}> view nesting too deep (max ${MAX_VIEW_DEPTH})` });
+    return node;
+  }
+  const expander = EXPANDERS[node.tag];
+  if (expander) return expander(node);
+  // A component-flagged tag with no registered expander would survive to the
+  // renderer as a non-primitive — reject it instead of leaking it through.
+  if (specByTag.get(node.tag)?.component) {
+    errors.push({ message: `<${node.tag}> is a component with no registered expander` });
+    return node;
+  }
+  return { ...node, children: node.children.map((c) => expand(c, specByTag, errors, depth + 1)) };
 }
 
 // ---------------------------------------------------------------------------
@@ -460,7 +547,8 @@ export function parseView(source: string, allowList: ReadonlyArray<ViewTagSpec>)
     const errors: ViewParseError[] = [];
     let root = convert(rootB, specByTag, errors);
     if (errors.length) return { ok: false, errors };
-    root = expand(root);
+    root = expand(root, specByTag, errors);
+    if (errors.length) return { ok: false, errors };
     const title = root.kind === 'element' && root.tag === 'view' && typeof root.props.title === 'string' ? root.props.title : undefined;
     return { ok: true, doc: { root, ...(title ? { title } : {}) } };
   } catch (e) {
@@ -473,8 +561,15 @@ export function parseView(source: string, allowList: ReadonlyArray<ViewTagSpec>)
 export function validateDoc(doc: ViewDoc, allowList: ReadonlyArray<ViewTagSpec>): ViewParseError[] {
   const specByTag = new Map(allowList.map((s) => [s.tag, s]));
   const errors: ViewParseError[] = [];
-  const walk = (node: ViewNode) => {
+  const walk = (node: ViewNode, depth: number) => {
     if (node.kind !== 'element') return;
+    if (depth >= MAX_VIEW_DEPTH) {
+      // Match parseView's hardening: a deep AST handed straight to validateDoc
+      // (over the transport, or from a replacement renderer) must reject, not
+      // throw an uncaught RangeError at the caller.
+      errors.push({ message: `<${node.tag}> view nesting too deep (max ${MAX_VIEW_DEPTH})` });
+      return;
+    }
     const spec = specByTag.get(node.tag);
     if (!spec) {
       errors.push({ message: `unknown tag <${node.tag}>` });
@@ -507,10 +602,10 @@ export function validateDoc(doc: ViewDoc, allowList: ReadonlyArray<ViewTagSpec>)
       } else if (spec.allowedChildren !== 'any' && c.value.trim()) {
         errors.push({ message: `<${node.tag}> may not contain text` });
       }
-      walk(c);
+      walk(c, depth + 1);
     }
   };
-  walk(doc.root);
+  walk(doc.root, 0);
   return errors;
 }