tosijs-ui 1.16.23 → 1.16.24

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog
 
+## 1.16.24
+
+`dist/iife.js` grows by about 0.2 kB gzip.
+
+- **Composition rules chain.** A rule may apply to another rule, so `un:check:square` slashes
+  the checked square, and `unCheckLock` draws instead of the placeholder. `iconSvg` reports a
+  chained rule as needing the renderer, as it does any rule. Chains stop at four rules deep,
+  which keeps a hostile icon name cheap to resolve, and a custom rule whose prefix can match
+  nothing no longer recurses. `defineIcons` may now warn about a new name that reads as a
+  chain (`unCheckFoo`); it is a warning, and your definition still wins.
+- **The icon composition demo shows the bracket form.** It printed `icons.check:square()`,
+  which is not JavaScript; a name with a `:` now shows as `icons['check:square']()`.
+- **Prettier never formats SVG files.** `*.svg` is in `.prettierignore` and a `requirePragma`
+  override, and `tosijs-format` excludes it on the command line as it does markdown. Prettier
+  has no SVG parser of its own, but an editor association or a plugin such as
+  `prettier-plugin-xml` would reflow a drawing tool's export. Adopters using `tosijs-format`
+  get the command-line exclusion. To cover editors too, add `*.svg` to `.prettierignore` and
+  `{ "files": ["*.svg"], "options": { "requirePragma": true } }` to your Prettier `overrides`.
+
+### Dev-server access
+
+- **A live example's "Save to source" is offered wherever the dev server admits the page**:
+  a LAN device under `trustLan`, or a tunnel visitor with an edit session, not only
+  `localhost`. The dev server marks the pages it serves with `editableSources` on, and an
+  example on such a page asks with a `HEAD` request when it connects, once per source file; it
+  believes only an answer carrying the dev server's own header. A deployed static site is never
+  asked.
+- **Every source write admitted by `trustLan` is logged** with the device's address, the file
+  (quoted, so a crafted name cannot forge a log line) and whether it was saved.
+- **The dev server suggests `trustLan` only to a refused device on a private network**, the
+  one case it would admit; anyone else is pointed at an edit link.
+
 ## 1.16.23
 
 - **`rule:icon` applies an icon composition rule explicitly.** A `:` marks the boundary

package/bin/format.ts

@@ -2,8 +2,8 @@
 /*
 tosijs-format — the house format step, shipped as a command (#187).
 
-    tosijs-format           eslint --fix, then prettier --write (markdown excluded)
-    tosijs-format --check   eslint, then prettier --check (markdown excluded); exit 1 on any finding
+    tosijs-format           eslint --fix, then prettier --write (markdown and SVG excluded)
+    tosijs-format --check   eslint, then prettier --check (markdown and SVG excluded); exit 1 on any finding
 
 **Prettier never touches markdown** in this stack. The rule itself lives in the Prettier
 CONFIG, where every entry point reads it (editors, lint-staged, a bare `prettier --write`):
@@ -31,10 +31,11 @@ import { parseArgv } from './resolve-site-config.ts'
 
 const { has } = parseArgv(process.argv.slice(2), {
   bin: 'tosijs-format',
-  summary: 'the house format step: eslint, then prettier (never markdown)',
+  summary:
+    'the house format step: eslint, then prettier (never markdown or SVG)',
   flags: ['check'],
   usage:
-    `  tosijs-format            eslint --fix ., then prettier --write . (markdown excluded)\n` +
+    `  tosijs-format            eslint --fix ., then prettier --write . (markdown and SVG excluded)\n` +
     `  tosijs-format --check    check only: exit 1 on anything unformatted or any lint error\n\n` +
     `Uses the project's own prettier and eslint (node_modules/.bin). ESLint runs only when the\n` +
     `project has an eslint.config.* file.`,
@@ -81,13 +82,18 @@ if (hasEslintConfig) {
   }
 }
 
-// The exclusion is the point of this command: prettier never touches markdown.
+/*
+The exclusion is the point of this command: prettier never touches markdown, or SVG.
+Prettier has no SVG parser of its own, but an editor association or a plugin
+(prettier-plugin-xml) gives it one, and an SVG is a drawing tool's export, not source to
+reflow.
+*/
 if (
   run([
     bin('prettier'),
     check ? '--check' : '--write',
     '.',
-    '!**/*.{md,markdown,mdx}',
+    '!**/*.{md,markdown,mdx,svg}',
   ]) !== 0
 ) {
   failed = true

package/dist/doc-system/site/dev-auth.d.ts

@@ -295,6 +295,44 @@ export declare function mayWriteSource(opts: {
     /** did the request carry forwarding headers? A proxied request is never LAN trust */
     proxied?: boolean;
 }): boolean;
+/**
+ * Who a `/__docstore/source` request is admitted as, or null to refuse it.
+ *
+ * The WHOLE gate for that endpoint, taking the real `Request`: `mayWriteSource` on the peer and
+ * listener, `trustLan` refused through a proxy, and the same-origin check (#90) on the direct
+ * path. It was inline in the server closure, where the 1.16.22 review could only verify LAN
+ * trust by hand (#3346); here it is tested with the headers a browser actually sends.
+ *
+ * `'lan'` is a write admitted only because the project trusts its LAN, which the server logs.
+ */
+export declare function sourceRequestAdmission(request: {
+    url?: string;
+    headers: {
+        get(name: string): string | null;
+    };
+}, opts: {
+    viaTunnel: boolean;
+    peer?: string | null;
+    auth: AuthState;
+    trustLan?: boolean;
+    now: number;
+}): 'loopback' | 'lan' | 'session' | null;
+/**
+ * Whether to tell a refused source request about `trustLan`: only a direct, unproxied device on
+ * a private network, the one case turning it on would admit, and only while it is off. Anyone
+ * else is pointed at an edit link, which is what would help them.
+ */
+export declare function suggestsTrustLan(opts: {
+    viaTunnel: boolean;
+    peer?: string | null;
+    proxied: boolean;
+    trustLan: boolean;
+}): boolean;
+/**
+ * The log line for a source write admitted only by `trustLan`. The file name is the client's,
+ * so it is quoted as JSON: a newline or an escape sequence in it cannot forge a log line.
+ */
+export declare function trustLanWriteRecord(peer: string | null | undefined, file: unknown, status: number): string;
 /**
  * May the holder of this session token write?
  *

package/dist/doc-system/site/dev-auth.js

@@ -658,6 +658,57 @@ export function mayWriteSource(opts) {
         opts.proxied !== true &&
         isPrivateNetworkAddress(opts.peer));
 }
+/**
+ * Who a `/__docstore/source` request is admitted as, or null to refuse it.
+ *
+ * The WHOLE gate for that endpoint, taking the real `Request`: `mayWriteSource` on the peer and
+ * listener, `trustLan` refused through a proxy, and the same-origin check (#90) on the direct
+ * path. It was inline in the server closure, where the 1.16.22 review could only verify LAN
+ * trust by hand (#3346); here it is tested with the headers a browser actually sends.
+ *
+ * `'lan'` is a write admitted only because the project trusts its LAN, which the server logs.
+ */
+export function sourceRequestAdmission(request, opts) {
+    const session = readCookie(request.headers.get('cookie'), SESSION_COOKIE);
+    const allowed = mayWriteSource({
+        viaTunnel: opts.viaTunnel,
+        peer: opts.peer,
+        hasValidSession: validSessionCookie(opts.auth, session, opts.now),
+        // A share link's session may browse and may not save (asked AFTER validity, which is
+        // the call-order `cookieMayWrite` documents).
+        sessionMayWrite: cookieMayWrite(opts.auth, session),
+        trustLan: opts.trustLan === true,
+        proxied: isProxiedRequest(request.headers),
+    }) &&
+        // CSRF (#90): the direct path is peer-address-only. The tunnel path is legitimately
+        // cross-site and is gated by the session cookie instead.
+        (opts.viaTunnel || isSameOriginRequest(request));
+    if (!allowed)
+        return null;
+    if (opts.viaTunnel)
+        return 'session';
+    return isLoopbackAddressForAuth(opts.peer) ? 'loopback' : 'lan';
+}
+/**
+ * Whether to tell a refused source request about `trustLan`: only a direct, unproxied device on
+ * a private network, the one case turning it on would admit, and only while it is off. Anyone
+ * else is pointed at an edit link, which is what would help them.
+ */
+export function suggestsTrustLan(opts) {
+    return (!opts.trustLan &&
+        !opts.viaTunnel &&
+        !opts.proxied &&
+        isPrivateNetworkAddress(opts.peer));
+}
+/**
+ * The log line for a source write admitted only by `trustLan`. The file name is the client's,
+ * so it is quoted as JSON: a newline or an escape sequence in it cannot forge a log line.
+ */
+export function trustLanWriteRecord(peer, file, status) {
+    const name = typeof file === 'string' ? JSON.stringify(file) : '(no file)';
+    const outcome = status >= 200 && status < 300 ? 'saved' : `refused (${status})`;
+    return `✎ trustLan: ${peer ?? 'unknown'} ${outcome} ${name}`;
+}
 /**
  * May the holder of this session token write?
  *

package/dist/doc-system/site/dev-server.js

@@ -22,7 +22,8 @@ import { resolveTunnelLocalPort } from './site-config.js';
 import { acquireBuildLock, describeHolder } from './build-lock.js';
 import { sinkPathFor, appendToSink } from './debug-sink.js';
 import { invitePageHtml } from './invite-page.js';
-import { TUNNEL_LINK_CMD, resolveLinkArrival, isLockedDown, hasTunnel, isLoopbackAddressForAuth as isLoopbackAddress, mayReadSite, shouldInterceptLinkToken, createAuthState, issueLink, resolveShareTtlMs, cookieMayWrite, readCookie, redeemThroughGate, createRedemptionGate, resolveLinkSettings, sessionCookie, urlWithoutToken, mayWriteSource, isSameOriginRequest, validSessionCookie, sessionRejection, mayDriveWithAgent, isProxiedRequest, SESSION_COOKIE, } from './dev-auth.js';
+import { TUNNEL_LINK_CMD, resolveLinkArrival, isLockedDown, hasTunnel, isLoopbackAddressForAuth as isLoopbackAddress, mayReadSite, shouldInterceptLinkToken, createAuthState, issueLink, resolveShareTtlMs, readCookie, redeemThroughGate, createRedemptionGate, resolveLinkSettings, sessionCookie, urlWithoutToken, isSameOriginRequest, validSessionCookie, sessionRejection, mayDriveWithAgent, isProxiedRequest, sourceRequestAdmission, suggestsTrustLan, trustLanWriteRecord, SESSION_COOKIE, } from './dev-auth.js';
+import { SOURCE_ACCESS_HEADER, SOURCE_ENDPOINT_SNIPPET, } from '../../live-example/source-access.js';
 /**
  * Every path the dev server watches for changes.
  *
@@ -842,7 +843,11 @@ export async function devServer(config, opts = {}) {
         if (!(await file.exists()))
             return new Response('not found', { status: 404 });
         return new Response(await file.text(), {
-            headers: { 'Content-Type': 'text/plain; charset=utf-8' },
+            headers: {
+                'Content-Type': 'text/plain; charset=utf-8',
+                // Lets a live example off localhost offer Save to source (source-access.ts).
+                [SOURCE_ACCESS_HEADER]: 'editable',
+            },
         });
     }
     /*
@@ -1067,7 +1072,11 @@ export async function devServer(config, opts = {}) {
                     ? HALTIJA_TUNNEL_SNIPPET
                     : ''
                 : HALTIJA_SNIPPET;
-        const extras = haltijaExtra + (testMode ? '' : statusSnippet(request, viaTunnel));
+        const extras = haltijaExtra +
+            (testMode ? '' : statusSnippet(request, viaTunnel)) +
+            // Tells a live example there is a source endpoint to ask (source-access.ts), so a
+            // deployed static site, which has none, is never asked.
+            (config.editableSources ? SOURCE_ENDPOINT_SNIPPET : '');
         const encoding = negotiateEncoding(request?.headers.get('accept-encoding') ?? null);
         if (extras && filePath.endsWith('.html')) {
             const html = await Bun.file(filePath).text();
@@ -1891,28 +1900,27 @@ export async function devServer(config, opts = {}) {
               "looks local" is precisely what a tunnel counterfeits.
               */
             const peer = srv?.requestIP?.(request)?.address;
-            const session = readCookie(request.headers.get('cookie'), SESSION_COOKIE);
-            const authorized = mayWriteSource({
+            const admission = sourceRequestAdmission(request, {
                 viaTunnel,
                 peer,
-                hasValidSession: validSessionCookie(auth, session, Date.now()),
-                // A share link's session may browse and may not save (asked AFTER validity, which
-                // is the call-order `cookieMayWrite` documents).
-                sessionMayWrite: cookieMayWrite(auth, session),
+                auth,
                 trustLan: config.trustLan === true,
-                proxied: isProxiedRequest(request.headers),
-            }) &&
-                /*
-                CSRF (#90). The direct path is peer-address-only, so without this any page the
-                developer visits can write any file under the repo root — `.git/hooks/*` included.
-                Non-tunnel only: the tunnel path is legitimately cross-site and is gated by the
-                session cookie instead.
-                */
-                csrfOk(request, viaTunnel);
-            if (!authorized) {
-                console.warn(`⚠️  refused ${request.method} /__docstore/source from ${peer ?? 'unknown'} — ` +
-                    `no session (use \`${TUNNEL_LINK_CMD}\` for an edit link` +
-                    `${config.trustLan ? '' : ', or set trustLan: true for LAN devices'}).`);
+                now: Date.now(),
+            });
+            if (admission === null) {
+                // A HEAD is a page asking whether it may offer Save to source; a no is not news.
+                if (request.method !== 'HEAD') {
+                    console.warn(`⚠️  refused ${request.method} /__docstore/source from ${peer ?? 'unknown'} — ` +
+                        `no session (use \`${TUNNEL_LINK_CMD}\` for an edit link` +
+                        `${suggestsTrustLan({
+                            viaTunnel,
+                            peer,
+                            proxied: isProxiedRequest(request.headers),
+                            trustLan: config.trustLan === true,
+                        })
+                            ? '; trustLan: true in the site config admits devices on this network'
+                            : ''}).`);
+                }
                 return new Response('not authorized to edit source', {
                     status: 403,
                     headers: { 'Content-Type': 'text/plain; charset=utf-8' },
@@ -1920,8 +1928,28 @@ export async function devServer(config, opts = {}) {
             }
             if (request.method === 'GET')
                 return handleReadSource(request);
-            if (request.method === 'POST')
-                return handleWriteSource(request);
+            if (request.method === 'HEAD') {
+                const read = await handleReadSource(request);
+                return new Response(null, {
+                    status: read.status,
+                    headers: read.headers,
+                });
+            }
+            if (request.method === 'POST') {
+                // A write admitted only by LAN trust is recorded with its outcome (#3346).
+                const file = admission === 'lan'
+                    ? await request
+                        .clone()
+                        .json()
+                        .then((body) => body?.file)
+                        .catch(() => undefined)
+                    : undefined;
+                const response = await handleWriteSource(request);
+                if (admission === 'lan') {
+                    console.log(trustLanWriteRecord(peer, file, response.status));
+                }
+                return response;
+            }
             return new Response('method not allowed', { status: 405 });
         }
         /*

package/dist/doc-system/site/site-config.d.ts

@@ -614,8 +614,9 @@ export interface SiteConfig {
      * Trust the local network for reading and editing source (#227). With `editableSources` on,
      * a browser on another device on your LAN (a phone, a headset) can open and save source
      * directly, as one at this keyboard can, instead of needing the tunnel and an invite link.
-     * That is "Edit page source"; a live example's "Save to source" is still offered only on
-     * `localhost`.
+     * That covers "Edit page source" and a live example's "Save to source", which is offered
+     * wherever the server admits the page. Every write admitted this way is logged with the
+     * device's address and the file.
      *
      * Trusted: a direct peer at a private address (RFC 1918 IPv4, IPv6 unique-local or
      * link-local). Never trusted: tunnel traffic (it needs a session as before) or a request

package/dist/icon-rules.d.ts

@@ -32,5 +32,7 @@ export declare function matchRule(rule: IconRule, name: string): {
     baseName: string;
     match: RegExpMatchArray | string;
 } | null;
-/** Whether some rule would draw `name`: it matches, and the icon it applies to exists. */
-export declare const ruleDraws: (name: string) => boolean;
+/** Whether some rule would draw `name`: it matches, and what it applies to draws (rules chain). */
+export declare const ruleDraws: (name: string, depth?: number) => boolean;
+/** A registered icon, suffixes on one, or a rule that draws (`un:check:square`, `unCheckLock`). */
+export declare const drawable: (name: string, depth?: number) => boolean;

package/dist/icon-rules.js

@@ -92,8 +92,21 @@ export function matchRule(rule, name) {
         match: rule.prefix,
     };
 }
-/** Whether some rule would draw `name`: it matches, and the icon it applies to exists. */
-export const ruleDraws = (name) => iconRules.some((rule) => {
-    const matched = matchRule(rule, name);
-    return matched != null && canResolve(matched.baseName);
-});
+/*
+How deep rules may chain. Real composites need two (`un:check:square`); the bound is what keeps a
+hostile name cheap. Unbounded, `'un'.repeat(400) + 'Lock'` took over a second, because every
+level asks every rule again (1.16.24 review), and a custom prefix that can match nothing
+(`/^(?:big)?/`) never shortened the name and overflowed the stack.
+*/
+const MAX_RULE_DEPTH = 4;
+/** Whether some rule would draw `name`: it matches, and what it applies to draws (rules chain). */
+export const ruleDraws = (name, depth = 0) => depth < MAX_RULE_DEPTH &&
+    iconRules.some((rule) => {
+        const matched = matchRule(rule, name);
+        return (matched != null &&
+            // A rule must shorten the name, or it is not applying to anything.
+            matched.baseName.length < name.length &&
+            drawable(matched.baseName, depth + 1));
+    });
+/** A registered icon, suffixes on one, or a rule that draws (`un:check:square`, `unCheckLock`). */
+export const drawable = (name, depth = 0) => canResolve(name) || ruleDraws(name, depth);

package/dist/icons.js

@@ -450,7 +450,9 @@ icon. Put a `:` at the boundary to ask for the rule: `check:square`,
 `un:lock`, `spin90:loader`. The explicit form applies the rule (unless
 you `defineIcons` that exact name, which warns), needs no capital letter
 after the prefix, and takes suffixes and stacking
-as usual (`spin90:loader40s`, `un:lock$shield`). A `:` is not valid in a
+as usual (`spin90:loader40s`, `un:lock$shield`). Rules chain: a rule
+may apply to another rule, so `un:check:square` slashes the checked square
+(and `unCheckLock` works too). A `:` is not valid in a
 JavaScript identifier, so write `icons['check:square']()`, or
 `<tosi-icon icon="check:square">`.
 
@@ -590,7 +592,7 @@ copies or substantial portions of the Software.
 import { elements, svgElements, Color, vars, varDefault, withAttributes, } from 'tosijs';
 import iconData from './icon-data.js';
 import { splitSuffixes, suffixNumber } from './icon-suffixes.js';
-import { iconRules, spinRule, matchRule, canResolve, suffixedIcon, } from './icon-rules.js';
+import { iconRules, spinRule, matchRule, drawable, suffixedIcon, } from './icon-rules.js';
 export { iconRules } from './icon-rules.js';
 export const defineIcons = (newIcons) => {
     const data = iconData;
@@ -608,7 +610,7 @@ export const defineIcons = (newIcons) => {
     for (const name of isNew) {
         const readsAsRule = iconRules.some((rule) => {
             const matched = matchRule(rule, name);
-            if (matched == null || !canResolve(matched.baseName))
+            if (matched == null || !drawable(matched.baseName))
                 return false;
             return (typeof rule.prefix !== 'string' ||
                 name.includes(':') ||
@@ -784,8 +786,11 @@ export function wrapIcon(prop, parts, ...children) {
 function composeIcon(prop, parts) {
     for (const rule of iconRules) {
         const matched = matchRule(rule, prop);
-        // Only apply if baseName can actually resolve to an icon
-        if (!matched || !canResolve(matched.baseName))
+        // Only apply if baseName draws (an icon, or another rule: `un:check:square`), and the
+        // rule shortened the name: a prefix that matched nothing is not applying to anything.
+        if (!matched ||
+            matched.baseName.length >= prop.length ||
+            !drawable(matched.baseName))
             continue;
         const result = rule.apply(safeIconSuffix(matched.baseName), matched.match, parts);
         if (typeof result === 'string')