browser-broker 0.1.0

package/dist/src/artifacts/names.js

@@ -0,0 +1,229 @@
+/**
+ * Turning things a caller supplies into things that are safe to be a file
+ * name — and nothing else. No filesystem call happens in this file.
+ *
+ * ── Why the rules are strict here rather than at the point of writing ───
+ *
+ * `SCHEMA.md` §1.7a states the reasoning and it is the reason this module is
+ * separate from the one that writes files: **a file name travels further
+ * than a database column does.** A column is read by things that were
+ * written to read it. A name ends up in log lines, in terminal output
+ * somebody screenshots, in error messages, in a shell history, in the title
+ * bar of whatever opened the image. It leaks by default, and it leaks to
+ * places nobody enumerated.
+ *
+ * Four rules follow from that, and §1.7a puts them in an order that matters:
+ *
+ * 1. **Query strings are stripped entirely, before anything else.** A query
+ *    string is where identifiers, tokens, search terms and session material
+ *    live — the part of an address most likely to carry something that should
+ *    never have been written down, and the part least likely to help anybody
+ *    tell two files apart. It is stripped first so that no later rule can be
+ *    the thing that happened to remove it: a collapse rule that turned `?` and
+ *    `=` into hyphens would leave the token in the name, spelled differently.
+ * 2. **Safe characters only**, so the name is the same on every filesystem and
+ *    survives being pasted anywhere.
+ * 3. **Truncated to a bounded length**, so a deep path does not produce a name
+ *    that is unusable or unprintable. What truncation loses is recoverable
+ *    from `captures.url` (§1.7); nothing depends on the name being complete.
+ * 4. **Never interpreted as a path.** The derivation produces **one path
+ *    segment**, and the separators that would make it more than one are not in
+ *    the safe set.
+ *
+ * **A label a caller supplies is subject to rules two, three and four as
+ * well** (§1.7a). It is a label, not a location.
+ *
+ * ── What this module structurally guarantees, and what it does not ──────
+ *
+ * **Structural.** Everything returned by {@link slugFromUrl} and
+ * {@link sanitiseLabel} is drawn from {@link SAFE_CHARACTERS} — the functions
+ * build their output by testing each character against that set rather than by
+ * removing a list of bad ones, so a character nobody thought of is excluded by
+ * default rather than included by default. Neither separator, `.` and `:` are
+ * outside the set, so no return value can be a traversal, an absolute path, a
+ * drive-qualified path, or more than one segment.
+ *
+ * **Not structural, and worth saying rather than implying.** Nothing here can
+ * stop a caller putting a secret in the *path* of an address, and the path is
+ * kept: only the query string is dropped. §1.7a's rule is about where secrets
+ * overwhelmingly live, not a claim that an address is safe once it is stripped.
+ * A service that wanted that guarantee would have to drop the address
+ * entirely, which would defeat what the slug is for.
+ */
+/**
+ * The characters a derived name may contain. Lower-case letters, digits, and
+ * the hyphen — nothing else, and in particular neither separator, no dot, no
+ * colon and no tilde.
+ *
+ * An allowlist rather than a denylist, because a denylist has to be right
+ * about every filesystem's rules on every platform forever, and this has to be
+ * right once.
+ */
+const SAFE_CHARACTERS = /^[a-z0-9-]$/;
+/**
+ * How long a derived part may be.
+ *
+ * A bound rather than a limit anybody has to remember: §1.7a asks for
+ * truncation so a deep path cannot produce an unprintable name, and the
+ * number matters less than there being one. Chosen so that the five parts
+ * §1.7a's shape assembles — slug, label, width, when, identifier — stay well
+ * inside the shortest path-component limit in common use.
+ */
+export const MAXIMUM_PART_LENGTH = 48;
+/** What a name is when every character in it was unsafe. */
+const EMPTY_PART = 'unnamed';
+/**
+ * Reduce a string to the safe set, collapse runs, and truncate.
+ *
+ * **Runs collapse to one hyphen and the ends are trimmed**, so the result
+ * never begins or ends with a separator-looking character and never contains a
+ * run of them. That is presentation rather than safety — the safety is that
+ * nothing outside {@link SAFE_CHARACTERS} survives at all — but a name of
+ * forty hyphens is a name that tells a reader nothing, and truncating it would
+ * spend the whole budget on nothing.
+ *
+ * **Never empty.** A string that reduces to nothing returns {@link EMPTY_PART}
+ * rather than an empty string, because an empty part would collapse the shape
+ * §1.7a describes into one with a doubled separator and make two different
+ * captures produce the same name.
+ */
+function reduce(value) {
+    const characters = [];
+    for (const character of value.toLowerCase()) {
+        if (SAFE_CHARACTERS.test(character)) {
+            characters.push(character);
+            continue;
+        }
+        // Anything outside the set becomes a separator rather than disappearing,
+        // so two distinguishable inputs do not collapse into one name.
+        if (characters.length > 0 && characters[characters.length - 1] !== '-') {
+            characters.push('-');
+        }
+    }
+    const collapsed = characters.join('').replace(/^-+|-+$/g, '');
+    if (collapsed === '')
+        return EMPTY_PART;
+    return collapsed.slice(0, MAXIMUM_PART_LENGTH).replace(/-+$/g, '') || EMPTY_PART;
+}
+/**
+ * Strip a query string, and a fragment, from an address — textually, before
+ * anything parses it.
+ *
+ * **Textual and first, on purpose.** Doing it by parsing would mean handing
+ * the whole address including its query to a parser, and the value of the rule
+ * is that the query is gone before anything else touches it. `?` opens a query
+ * and `#` opens a fragment; whichever comes first ends the part that is kept.
+ *
+ * A fragment is stripped alongside the query although §1.7a names only the
+ * query. It is the same class of material — client-side state a caller chose,
+ * frequently carrying identifiers — and keeping it would put it in a file
+ * name for no benefit, since it never distinguishes two pages the server
+ * served.
+ */
+function withoutQuery(address) {
+    const end = Math.min(...['?', '#'].map((mark) => {
+        const at = address.indexOf(mark);
+        return at === -1 ? address.length : at;
+    }));
+    return address.slice(0, end);
+}
+/**
+ * The page slug: host and path, query stripped first, reduced to one safe
+ * segment.
+ *
+ * **Derived, never supplied** (§1.7a). A caller's own label describes what it
+ * was *doing*; the address describes what it was *looking at*, and only the
+ * second is reliably distinct between two pieces of work that happen to be
+ * described the same way.
+ *
+ * **An address this cannot parse still produces a name.** A capture is never
+ * refused for the sake of its file name — the whole shape of §3.11 is that the
+ * only refusals are argument mistakes — so an unparseable address falls back to
+ * reducing the stripped text directly. It is a worse name and it is still a
+ * name.
+ *
+ * ── TWO INDEPENDENT MECHANISMS KEEP THE QUERY OUT, and saying so matters ──
+ *
+ * Worth stating exactly, because a reader who assumes only one is at work will
+ * draw the wrong conclusion from a change to either:
+ *
+ * 1. **On the parseable path, taking `hostname` and `pathname` excludes the
+ *    query by construction.** Neither property contains it, so even handed a
+ *    full address the parser would not put a query in the name.
+ * 2. **{@link withoutQuery} strips it textually first**, which is what covers
+ *    the **fallback path** — where there is no parser to be structural about
+ *    it, and where the whole address would otherwise be reduced verbatim.
+ *
+ * So the strip is not redundant: it is the *only* mechanism on the branch that
+ * handles an address this cannot parse, and that is exactly the branch where an
+ * odd address ends up. Removing it leaks a token from any unparseable address.
+ * Belt and braces on one path, sole defence on the other.
+ */
+export function slugFromUrl(address) {
+    if (address === undefined || address.trim() === '')
+        return EMPTY_PART;
+    const stripped = withoutQuery(address);
+    try {
+        const parsed = new URL(stripped);
+        // Host and path only. Not the scheme, not any credentials the address
+        // carries in front of the host, and not the port — none of which help
+        // anybody tell two pictures apart, and the first of which is the single
+        // most sensitive thing an address can hold.
+        return reduce(`${parsed.hostname}${parsed.pathname}`);
+    }
+    catch {
+        return reduce(stripped);
+    }
+}
+/**
+ * A caller's own label, made safe.
+ *
+ * Rules two, three and four of §1.7a apply here as they do to the slug: safe
+ * characters, bounded, and never a path. Rule one does not, because a label is
+ * not an address and has no query string to strip — but note that a label
+ * containing `?` is reduced by the same safe-character pass, so a caller that
+ * pasted an address into the label field does not smuggle one through.
+ */
+export function sanitiseLabel(label) {
+    if (label === undefined || label.trim() === '')
+        return EMPTY_PART;
+    return reduce(label);
+}
+/**
+ * A sortable stamp for the moment a capture was taken.
+ *
+ * Digits only, most significant first, so a directory listing sorts into time
+ * order within a page and a view — which is the fourth of the five sorting
+ * levels §1.7a's shape is chosen for. Derived from the instant's own text
+ * rather than formatted by hand so that it is the same on every platform.
+ */
+export function stampFromInstant(when) {
+    return when
+        .toISOString()
+        .replace(/[^0-9]/g, '')
+        .slice(0, 14);
+}
+/**
+ * Assemble the five parts §1.7a specifies, in the order it specifies them:
+ * `<page-slug>-<view-label>-<width>-<when>-<id>.png`.
+ *
+ * That order is what makes a directory listing readable: all the pictures of
+ * one page together, then within a page all the pictures of one view, then the
+ * widths, then the sequence in time, then an identifier that guarantees
+ * uniqueness without anybody coordinating.
+ *
+ * **Every variable part goes through the rules above**, including the
+ * identifier — which is generated rather than supplied and would pass anyway,
+ * but passing it through means there is no part of this name that a future
+ * change could make caller-controlled without also making it safe.
+ */
+export function captureFileName(parts) {
+    const width = reduce(String(Math.trunc(parts.viewportWidth)));
+    return ([
+        slugFromUrl(parts.url),
+        sanitiseLabel(parts.label),
+        width,
+        stampFromInstant(parts.takenAt),
+        reduce(parts.id),
+    ].join('-') + '.png');
+}

package/dist/src/artifacts/store.js

@@ -0,0 +1,174 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { BrokerError } from "../errors.js";
+/**
+ * Every kind, in the order §1.7a lists them.
+ *
+ * **Named entries, not a derived list.** A test that walks this array and
+ * asserts each directory exists is a test that goes green when an entry is
+ * deleted, because it would then be walking a shorter list. So the test that
+ * matters names each folder outright and this constant is for code that
+ * genuinely needs to iterate.
+ */
+export const ARTIFACT_KINDS = [
+    'images',
+    'snapshots',
+    'console',
+    'network',
+    'downloads',
+];
+/**
+ * A path segment that identifies a lease, made safe.
+ *
+ * A claim identifier is generated by this service and is already safe, so this
+ * looks redundant — and it is not, for the reason rule two above gives: the
+ * value arriving here is the one thing in the assembled path that came from
+ * outside this module, and a check that only holds while an upstream promise
+ * holds is a check that fails silently the day the promise changes.
+ */
+function safeSegment(value, what) {
+    const reduced = value.toLowerCase().replace(/[^a-z0-9-]/g, '');
+    if (reduced === '' || reduced !== value.toLowerCase()) {
+        throw new BrokerError('artifact.no_request_path', `${what} is not usable as a directory name. Expected letters, digits and hyphens; found ${JSON.stringify(value)}.`);
+    }
+    return reduced;
+}
+/**
+ * Is this path absolute in **either** namespace?
+ *
+ * ── Why the platform's own answer is the wrong one ──────────────────────
+ *
+ * `path.isAbsolute` asks the namespace the host process happens to be running
+ * in, and the two namespaces disagree about what an absolute path even is. On
+ * a platform whose separator is the forward slash, `C:` followed by a
+ * backslash is not a root — it is a perfectly legal **relative filename that
+ * contains backslashes**, so the refusal never fires and the path is joined
+ * onto the root as one long oddly-named file. The same string refuses on the
+ * other platform. Identical input, opposite outcome, from the same code.
+ *
+ * That is not a hypothetical, and this codebase already answers it in one
+ * place: `store/network-path.ts` reads its share root with
+ * {@link path.win32.parse} **unconditionally**, on every platform, for
+ * exactly this reason. This follows that approach rather than inventing a
+ * second one, so both guards recognise both spellings the same way.
+ *
+ * ── Both checks, and honesty about what the second one adds ─────────────
+ *
+ * **The two are not independently load-bearing, and pretending otherwise
+ * would mislead the next reader.** The drive-letter parser also reports a
+ * root for a leading forward slash, so deleting the first check changes no
+ * outcome any test observes — deleting the *second* is what turns the guard
+ * off for a drive-qualified name and a share.
+ *
+ * The first check stays because this rule is "absolute in either namespace"
+ * and one line per namespace is how that reads as code. Leaning on one
+ * parser's incidental coverage of the other's case would make the rule
+ * correct by coincidence rather than by statement.
+ *
+ * A guard that only fires on the platform it was written on is worse than no
+ * guard, because it reports a protection that does not exist.
+ */
+function isAbsoluteInEitherNamespace(target) {
+    // POSIX: a leading forward slash. Named for its own sake — see above.
+    if (path.posix.isAbsolute(target)) {
+        return true;
+    }
+    // The other namespace: a drive letter followed by a colon and a separator,
+    // in either separator spelling; a two-separator share prefix naming a host
+    // and a share; and a bare leading backslash. Reading the parsed root covers
+    // every one of those spellings without this file having to enumerate them
+    // as patterns of its own.
+    return path.win32.parse(target).root !== '';
+}
+export class ArtifactStore {
+    #root;
+    /**
+     * @param root `BROKER_ARTIFACTS_ROOT`, already resolved by the environment
+     *   snapshot. Taken as a string rather than read from the environment here,
+     *   so that this class has no configuration of its own and a test does not
+     *   have to arrange a process environment to use one.
+     */
+    constructor(root) {
+        this.#root = path.resolve(root);
+    }
+    /** Where the tree is rooted. Read by nothing that stores it. */
+    get root() {
+        return this.#root;
+    }
+    /**
+     * The directory for one lease's artefacts of one kind, created if absent.
+     *
+     * Created lazily rather than at claim time: a lease that takes no captures
+     * should not leave an empty tree behind, and there is no moment in a
+     * daemonless service at which a setup step could have run instead.
+     */
+    directoryFor(claimId, kind) {
+        const directory = path.join(this.#root, 'claims', safeSegment(claimId, 'A claim identifier'), kind);
+        fs.mkdirSync(directory, { recursive: true });
+        return directory;
+    }
+    /**
+     * Write one file into a lease's tree, and report where it went **relative to
+     * the root**.
+     *
+     * The refusal below is the second of this file's two rules, and it asks two
+     * questions rather than one. It compares the resolved destination against
+     * the resolved root, which catches a name that climbs out through `..`; and
+     * it asks {@link isAbsoluteInEitherNamespace} whether the supplied name was
+     * absolute in **either** namespace, which is what catches the spellings the
+     * host platform does not read as roots. Both are needed — see that
+     * function for why one platform's answer is not the answer.
+     */
+    write(claimId, kind, fileName, contents) {
+        const directory = this.directoryFor(claimId, kind);
+        const absolutePath = path.resolve(directory, fileName);
+        const relative = path.relative(this.#root, absolutePath);
+        // `..` at the front means the destination climbed out of the root; an
+        // absolute answer means it was never under it at all. Either is a bug in
+        // whatever composed the name, and neither may be written.
+        //
+        // **The supplied name is tested as well as the computed result**, and that
+        // is not belt and braces — it is the only check that catches a name
+        // absolute in the *other* namespace. Such a name is a legal relative
+        // filename to `path.resolve` here, so it resolves quietly under the root
+        // and the computed answer is relative and clean. Nothing downstream can
+        // notice; the name itself has to be asked.
+        if (relative.startsWith('..') ||
+            isAbsoluteInEitherNamespace(relative) ||
+            isAbsoluteInEitherNamespace(fileName)) {
+            throw new BrokerError('artifact.no_request_path', `A capture would have been written outside the artifact root. Refusing: ${JSON.stringify(fileName)} does not resolve under it.`);
+        }
+        fs.writeFileSync(absolutePath, contents);
+        return {
+            // Stored with forward slashes whatever platform wrote it, so a row
+            // written on one machine reads on another. A separator is presentation;
+            // making it part of the stored value would reintroduce, one layer down,
+            // exactly the machine-specificity rule one exists to remove.
+            relativePath: relative.split(path.sep).join('/'),
+            absolutePath,
+            bytes: contents.byteLength,
+        };
+    }
+    /**
+     * Turn a recorded relative path back into a location on this machine.
+     *
+     * **This is the only way bytes are ever served** (§1.9, `artifact.no_request_path`):
+     * a recorded path resolves under the root or nothing is served, so a caller
+     * never supplies a filesystem path and traversal has no input to arrive
+     * through. The refusal is the same one `write` makes, from the other
+     * direction, and it is deliberately duplicated rather than shared through a
+     * flag — the two callers are asking different questions and a shared
+     * parameterised helper would be one edit away from answering only one of
+     * them.
+     */
+    resolve(relativePath) {
+        const absolutePath = path.resolve(this.#root, relativePath);
+        const relative = path.relative(this.#root, absolutePath);
+        if (relative.startsWith('..') ||
+            isAbsoluteInEitherNamespace(relative) ||
+            isAbsoluteInEitherNamespace(relativePath)) {
+            throw new BrokerError('artifact.no_request_path', `A recorded path does not resolve under the artifact root. Refusing to serve ${JSON.stringify(relativePath)}.`);
+        }
+        return absolutePath;
+    }
+}

package/dist/src/bin/broker-tool.js

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+import { serviceUnavailable } from "../cli/index.js";
+import { BrokerError } from "../errors.js";
+import { createRuntime } from "../service/runtime.js";
+import { linesFrom, serveSession } from "../tool/session.js";
+/**
+ * The executable shim for the tool surface: **the process a caller spawns.**
+ *
+ * `MILESTONES.md` #27: the service is spawned by its caller, serves that
+ * session, and exits with it. There is no port to bind, no daemon to start
+ * and nothing to leave running — this file reads standard input until it
+ * ends, and then the process has nothing left to do.
+ *
+ * ── Why the loop is not in this file ────────────────────────────────────
+ *
+ * Everything above the streams lives in `session.ts` and is importable, so
+ * the parity matrix drives the real handler in process rather than by
+ * spawning something per case. `MILESTONES.md` reserves spawning for the case
+ * where the process boundary is itself the thing under test — which is what
+ * this file's own smoke test does, and it is the only thing that does.
+ *
+ * ── The service it serves ───────────────────────────────────────────────
+ *
+ * The real one, built the same way the command line builds its own
+ * (`service/runtime.ts`), differing only in the adapter it records — §1.6
+ * keeps one row per decision and one column saying which door it came in
+ * through, and this door is `tool-stdio`.
+ *
+ * {@link serviceUnavailable} covers the one case where a service cannot be
+ * built at all: opening the store is what can fail, and it fails with a rule
+ * attached. Refusing every operation by name is the right answer there — a
+ * caller that spawned this gets an honest refusal and the whole wire path
+ * stays real — and it is reached only in that case, because a surface that
+ * refused everything unconditionally would be unusable rather than degraded.
+ *
+ * **Human text never goes to standard output**, because standard output is
+ * the protocol stream and one stray line would corrupt the framing for every
+ * message after it. The startup refusal below therefore goes to the error
+ * stream, and the session still serves — a caller mid-conversation gets
+ * refusals it can read rather than a process that vanished.
+ */
+let runtime;
+try {
+    runtime = await createRuntime({ adapter: 'tool-stdio' });
+}
+catch (error) {
+    if (!(error instanceof BrokerError)) {
+        throw error;
+    }
+    process.stderr.write(`refused (${error.rule}): ${error.message}\n`);
+}
+try {
+    await serveSession(linesFrom(process.stdin), {
+        service: runtime?.service ?? serviceUnavailable(),
+        streams: {
+            write: (line) => process.stdout.write(`${line}\n`),
+            log: (line) => process.stderr.write(`${line}\n`),
+        },
+    });
+}
+finally {
+    runtime?.close();
+}

package/dist/src/bin/broker.js

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+import { run } from "../cli/index.js";
+import { createRuntime } from "../service/runtime.js";
+import { BrokerError } from "../errors.js";
+/**
+ * The executable entry point. Argument vector in, exit code out.
+ *
+ * ── What this file adds, and why it is the only thing it adds ───────────
+ *
+ * The dispatcher stays importable and stays free of any decision, so the
+ * command line can be driven in process (`MILESTONES.md`). What it does not
+ * do is build itself a service — `RunOptions.service` is injected precisely
+ * so that a conformance driver can hand it one, and a dispatcher that
+ * constructed its own could only be tested by spawning.
+ *
+ * That leaves somebody to build the real one, and this is that somebody: the
+ * shipped executable, which is the only caller whose service should be the
+ * real one by default.
+ *
+ * ── The fallback is kept, and narrowed to what it was for ───────────────
+ *
+ * `serviceUnavailable()` remains the answer when a service genuinely cannot
+ * be built, and it is now reached by the path that name describes rather than
+ * by every path. Building one means opening a store, and a store can
+ * legitimately refuse to open — a location on a network filesystem, a
+ * malformed configuration variable, a directory nothing may write to. Those
+ * refusals are the service *declining*, and they already have their own
+ * sentences naming the rule that refused, so they are reported as themselves
+ * rather than flattened into "not built".
+ */
+const argv = process.argv.slice(2);
+/**
+ * Commands that must answer without a service, and therefore without a store.
+ *
+ * `doctor` is the one that matters most and the reason this list is not
+ * empty: a store that does not exist yet is the state it is most useful in,
+ * and `cli/index.ts` goes to some length not to create one while answering. A
+ * binary that built a runtime first would create the store *before* the
+ * command ran and hand `doctor` a fault it had itself caused — the exact
+ * failure that file's comment describes, reintroduced one layer up.
+ *
+ * **The bare spawn is here for a subtler reason, and it is the one this list
+ * exists to get right.** With no arguments the dispatcher opens the store,
+ * steps it and reports what stepping did — that report is the whole of what
+ * the command does. Building a runtime first would step the schema, so by the
+ * time the command ran there would be nothing left to step, and a spawn
+ * against a store that did not exist a moment ago would truthfully say
+ * "already at version 5, nothing to do". The command would still be honest;
+ * it would simply have been robbed of the thing it reports. Stepping is done
+ * once per spawn, by whoever is going to speak about it.
+ *
+ * `--help` and `--version` are here for the ordinary reason: neither reads
+ * anything, and opening a database to print a version string would make the
+ * two commands most likely to be run on a broken installation the two most
+ * likely to fail on one.
+ */
+function needsNoService(words) {
+    if (words.includes('--help') || words.includes('-h'))
+        return true;
+    if (words.includes('--version') || words.includes('-v'))
+        return true;
+    // Only `--json` can accompany a bare spawn; anything else is a command.
+    if (words.every((word) => word.startsWith('-')))
+        return true;
+    return words[0] === 'doctor';
+}
+if (needsNoService(argv)) {
+    process.exitCode = await run(argv);
+}
+else {
+    let runtime;
+    try {
+        runtime = await createRuntime({ adapter: 'cli' });
+    }
+    catch (error) {
+        if (error instanceof BrokerError) {
+            // The store declined to open. Reported with the rule that refused it,
+            // in the same shape every other refusal takes, rather than as a stack
+            // trace or as a claim that the service was never built.
+            process.stderr.write(`refused (${error.rule}): ${error.message}\n`);
+            process.exitCode = 4;
+        }
+        else {
+            throw error;
+        }
+    }
+    if (runtime !== undefined) {
+        try {
+            process.exitCode = await run(argv, {
+                service: runtime.service,
+                // `broker login` is performed by a person and is not one of the ten
+                // operations the flat seam carries, so it reaches the service through
+                // the typed interface. Supplied here rather than constructed in the
+                // dispatcher for the reason `RunOptions.service` gives: a dispatcher
+                // that built its own service could only be tested by spawning.
+                broker: runtime.broker,
+                store: runtime.store,
+                environment: runtime.environment,
+                // `broker reconcile` asks a live browser what it has open (§2.6,
+                // §4.3). It is the runtime's own provider rather than one built in
+                // the dispatcher, so this process decides adoption once — and it is
+                // passed here, from the shipped executable, because a command reached
+                // only by a test is a command that does not exist.
+                session: runtime.session,
+            });
+        }
+        finally {
+            runtime.close();
+        }
+    }
+}