@markii/host 0.0.0-stage → 0.17.0-next.2

package/dist/run/grant-flow.js

@@ -0,0 +1,390 @@
+/**
+ * Slice 2's grant/prompt flow (docs: GitHub issue #1's locked design
+ * comment) — vscode-free by design, same split as `./run-host.ts` and
+ * `./script-requirements.ts`: this module decides WHAT to prompt and WHAT
+ * to persist, but never calls `vscode.window.showInformationMessage` or
+ * `context.workspaceState` directly. The extension-host adapter
+ * (`extension.ts`/`preview-panel.ts` — the only files allowed to import
+ * `vscode`) supplies the actual prompt UI and Memento, both behind the thin
+ * interfaces below, so this file stays unit-testable with plain fakes.
+ *
+ * ## Keying
+ *
+ * `computeGrantKey` (`@markii/runtime`) hashes the note's executable
+ * closure — that closure is its own script blocks
+ * (`RunRequirements.grantScripts`) plus, for a bundle-backed run, the
+ * resolved source text of every `src=`-referenced script file
+ * (`GrantFlowRequirements.bundleModules`, F-1 fix), with `vaultModules`/
+ * `packs` left empty: `require` (bundle-local or pack) stays unwired for
+ * the whole `.mkz` Run-path arc (GitHub issue #9's design comment), so a
+ * bundle-backed run's closure has no OTHER bundle-local code to fold in
+ * yet beyond its `src=` targets. Any edit to any script's code — inline or
+ * `src=`-referenced — changes the hash, which is what makes "any code
+ * change re-prompts" fall out of the keying scheme for free rather than
+ * needing its own diffing logic here.
+ *
+ * The bundle-fs capability (`permissions.bundle`) is out of this module
+ * entirely (consent unification, SECURITY-RELEVANT): it needs no
+ * user-facing prompt, so it is never part of `GrantFlowRequirements`, the
+ * stored grant, or the grant key. `./run-flow.ts` passes the manifest's
+ * declared bundle-fs grants straight through to `spawnRun` — see its own
+ * comment on why that is still safe (path-jail + the read-only tier for
+ * auto/scheduled, both unaffected by this module).
+ *
+ * ## Storage
+ *
+ * One `{key, allowedHosts}` record per document, keyed by the document's
+ * URI string, all held under one Memento key (`GRANTS_STORAGE_KEY`) as a
+ * plain map. A stored record whose `key` no longer matches the freshly
+ * computed one is a MISS — this module never trusts a stale record's
+ * `allowedHosts`, even partially; the whole grant re-derives from scratch.
+ * A record is only ever WRITTEN when `allowedHosts` ends up non-empty — a
+ * full decline is never persisted, so it simply re-prompts next time (see
+ * `runGrantFlow`'s own comment on this, C-3) — and `clearGrantForDocument`
+ * removes a document's record outright, for the `markii.resetScriptGrants`
+ * command.
+ *
+ * ## The prompt shapes
+ *
+ * - One prompt per statically-known host (`promptHost`), worded exactly
+ *   "This note's scripts can send data to <host>. Allow?" — see
+ *   `hostPromptMessage`. Used only while the distinct safe host count is at
+ *   or under `MAX_HOST_PROMPTS`; above that, `promptManyHosts` (below) takes
+ *   over instead so a note can never turn one Run press into a wall of
+ *   modals (the PROMPT-STORM fix — see `MAX_HOST_PROMPTS`'s doc comment).
+ * - `promptManyHosts`, exactly once, in place of the whole per-host loop
+ *   when there are more than `MAX_HOST_PROMPTS` distinct safe hosts: one
+ *   all-or-nothing gate ("This note requests network access to many hosts
+ *   (N). Allow all or deny all?", `manyHostsPromptMessage`) rather than N
+ *   separate dialogs.
+ * - Exactly one extra prompt (`promptUnknownHosts`,
+ *   `UNKNOWN_HOSTS_PROMPT_MESSAGE`) when the closure could reach hosts that
+ *   cannot be listed in advance (`RunRequirements.hasUnknownHosts`, or a
+ *   host string this module refuses to render — see `isSafeHostForPrompt`).
+ *   Accepting it does NOT add anything to `allowedHosts` — there is no host
+ *   name to grant — it is a consent gate: declining it clears every
+ *   already-collected per-host answer too, since a script that can reach
+ *   addresses it never named cannot be trusted to only use the hosts it DID
+ *   name. A dynamically-built address a script hits at RUN TIME, whether or
+ *   not this prompt was accepted, is never added to `allowedHosts` here (it
+ *   is not known in advance); it fails at execution with the ordinary
+ *   `'capability-denied'` kind, same as any other ungranted host.
+ */
+import { computeGrantKey, } from '@markii/runtime';
+/**
+ * Exact prompt wording — normative per the locked design comment. Exported
+ * so a test (and the adapter that renders it) both anchor on the same
+ * string.
+ *
+ * `declaredHosts` is what the note's own scripts declare through their
+ * `permissions` fence attribute (`./script-requirements.ts`'s
+ * `scriptDeclaredHosts`). It is DISPLAY-ONLY: it never changes what is
+ * prompted for or granted, only what the user reads before answering, so
+ * a note cannot talk its way into a host the literal-URL scan did not
+ * find. `host` is always the one host this prompt asks about. With no
+ * declaration the wording is unchanged, so a host that does not pass the
+ * list sees exactly the message it saw before.
+ */
+export function hostPromptMessage(host, declaredHosts) {
+    const ask = `This note's scripts can send data to ${host}. Allow?`;
+    if (!declaredHosts || declaredHosts.length === 0)
+        return ask;
+    return `This note's scripts can send data to ${host}. The note declares ${declaredHosts.join(', ')}. Allow?`;
+}
+/** Exact wording of the one extra "hosts can't be listed in advance" prompt. */
+export const UNKNOWN_HOSTS_PROMPT_MESSAGE = "This note builds network addresses at run time, which can't be listed in advance and will be denied; only the hosts written directly in the note can be granted. Allow those?";
+/** Button labels every prompt in this flow uses — both a plain "Allow" and a "Don't allow" refusal are always offered, never a bare dismiss-only message. */
+export const ALLOW_LABEL = 'Allow';
+export const DONT_ALLOW_LABEL = "Don't allow";
+/**
+ * PROMPT-STORM fix (report section 8, item 6, docs/archive/PENTEST-REPORT-2026-08-23.md):
+ * `runGrantFlow`'s per-host loop below is sequential and modal, one dialog
+ * per statically-extracted host. A hostile note with hundreds of literal
+ * `net.fetch_json("https://hostN/")` calls would otherwise re-open hundreds
+ * of modals on EVERY `markii.runScripts` press — and because a FULL decline
+ * is deliberately never persisted (C-3, so one mis-click can't permanently
+ * lock out network access), nothing about answering them once makes them
+ * stop recurring on the next Run press either. That makes the per-host loop
+ * itself a denial-of-service surface against the user's own attention, not
+ * just an annoyance.
+ *
+ * The guard: cap how many per-host prompts one run will ever show. When the
+ * distinct SAFE static host count is at or under this cap, the ordinary
+ * per-host flow runs exactly as before (this is overwhelmingly the common
+ * case — most notes touch a small, fixed set of APIs). Above the cap, the
+ * per-host loop is skipped entirely in favor of ONE consolidated prompt
+ * (`promptManyHosts`) that grants either every one of those hosts or none of
+ * them — still a single, honest, all-or-nothing consent decision, just sized
+ * to the actual scale of what's being asked, rather than a wall of modals a
+ * user would rationally start rubber-stamping. 10 is comfortably above what
+ * a legitimate dashboard-style note (docs/scripting.md's callout on
+ * dashboards being a first-class use case) is expected to reach while still
+ * catching a hostile host list before it becomes hundreds of dialogs.
+ */
+export const MAX_HOST_PROMPTS = 10;
+/** Exact wording of the consolidated "many hosts" gate — normative, mirroring `hostPromptMessage`/`UNKNOWN_HOSTS_PROMPT_MESSAGE`'s pattern of an exported, test-anchored string. */
+export function manyHostsPromptMessage(hostCount) {
+    return `This note requests network access to many hosts (${hostCount}). Allow all or deny all?`;
+}
+const GRANTS_STORAGE_KEY = 'markii.netGrants';
+function hasOwn(value, key) {
+    return Object.prototype.hasOwnProperty.call(value, key);
+}
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** Never trusts a Memento's stored shape — a corrupt/foreign/hand-edited value degrades to "no stored grant" rather than throwing or partially applying. */
+function isStoredGrant(value) {
+    if (!isPlainObject(value))
+        return false;
+    if (!hasOwn(value, 'key') || typeof value.key !== 'string')
+        return false;
+    if (!hasOwn(value, 'allowedHosts') ||
+        !Array.isArray(value.allowedHosts) ||
+        !value.allowedHosts.every((host) => typeof host === 'string')) {
+        return false;
+    }
+    return true;
+}
+function readAllGrants(memento) {
+    const raw = memento.get(GRANTS_STORAGE_KEY, {});
+    return isPlainObject(raw) ? raw : {};
+}
+/**
+ * Reads the stored grant for `documentKey`, if any, and re-runs every one of
+ * its `allowedHosts` through `isSafeHostForPrompt` before returning it (N-6):
+ * a stored record's hosts were only ever validated at COLLECTION time,
+ * possibly under an older/buggier version of this module, or (with direct
+ * `workspaceState` write access) never validated at all. Trusting the shape
+ * check alone and not re-deriving the safety property at read time would let
+ * a planted or stale record become the effective allowlist verbatim. Any
+ * host that fails re-validation is dropped from the returned grant, and
+ * `droppedUnsafeHost` is set so `runGrantFlow` know it must not treat this as
+ * a clean cache hit — see its own comment at the call site.
+ */
+function readGrant(memento, documentKey) {
+    const all = readAllGrants(memento);
+    if (!hasOwn(all, documentKey))
+        return undefined;
+    const candidate = all[documentKey];
+    if (!isStoredGrant(candidate))
+        return undefined;
+    const safeHosts = candidate.allowedHosts.filter(isSafeHostForPrompt);
+    return {
+        grant: {
+            key: candidate.key,
+            allowedHosts: safeHosts,
+        },
+        droppedUnsafeHost: safeHosts.length !== candidate.allowedHosts.length,
+    };
+}
+async function writeGrant(memento, documentKey, grant) {
+    const all = readAllGrants(memento);
+    const next = { ...all, [documentKey]: grant };
+    await memento.update(GRANTS_STORAGE_KEY, next);
+}
+/**
+ * A conservative hostname-shape check for what this module is willing to
+ * interpolate into a prompt string. `extractRunRequirements`
+ * (`./script-requirements.ts`) already derives every host in
+ * `RunRequirements.hosts` from `new URL(literal).hostname` — which can
+ * never itself contain whitespace or control characters — but this is a
+ * second, independent gate at the point of DISPLAY: defense in depth
+ * against a future host-extraction bug (or a deliberately different caller
+ * of this module) ever interpolating raw, unvalidated note text into a
+ * modal dialog. Accepts ordinary DNS names, bracketed IPv6 literals, and
+ * plain IPv4 literals; rejects everything else, including any control or
+ * whitespace character.
+ */
+const SAFE_HOSTNAME_PATTERN = /^(?:[a-z0-9]([a-z0-9-]*[a-z0-9])?)(?:\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$|^\[[0-9a-f:]+\]$|^(?:[0-9]{1,3}\.){3}[0-9]{1,3}$/i;
+export function isSafeHostForPrompt(host) {
+    // SAFE_HOSTNAME_PATTERN is a full, anchored (^...$) match against a
+    // closed character set, so no whitespace or control character can ever
+    // pass it -- no separate check is needed.
+    return (typeof host === 'string' &&
+        host.length > 0 &&
+        host.length <= 253 &&
+        SAFE_HOSTNAME_PATTERN.test(host));
+}
+/**
+ * Splits `hosts` into the ones safe to render in a per-host prompt, and
+ * whether the "can't be listed in advance" prompt is needed — either
+ * because the static scan already said so (`hasUnknownHosts`), or because
+ * at least one extracted host failed `isSafeHostForPrompt` and must never
+ * be shown verbatim. Failing toward the broader prompt (never toward
+ * silently dropping a host with no prompt at all) mirrors
+ * `extractRunRequirements`'s own philosophy.
+ */
+function partitionHosts(hosts, hasUnknownHosts) {
+    const safeHosts = [];
+    let needsUnknownPrompt = hasUnknownHosts;
+    for (const host of hosts) {
+        if (isSafeHostForPrompt(host)) {
+            safeHosts.push(host);
+        }
+        else {
+            needsUnknownPrompt = true;
+        }
+    }
+    return { safeHosts, needsUnknownPrompt };
+}
+function closureFrom(requirements) {
+    return {
+        scripts: [...requirements.grantScripts],
+        // F-1 fix: was unconditionally `{}` — see `GrantFlowRequirements.bundleModules`'s
+        // doc comment for why that let a bundle script's contents change under an
+        // unchanged grant key.
+        bundleModules: { ...(requirements.bundleModules ?? {}) },
+        vaultModules: {},
+        packs: [],
+    };
+}
+/**
+ * Runs the whole grant flow for one Run press: computes the closure's grant
+ * key, reuses a matching stored grant with NO prompting at all, or (on a
+ * miss — first run or any code change) prompts fresh for every host and the
+ * unknown-hosts gate, persists the result, and returns the allowlist
+ * `spawnRun` should use.
+ */
+export async function runGrantFlow(options) {
+    const { documentKey, requirements, memento, promptHost, promptUnknownHosts, promptManyHosts, } = options;
+    const declaredHosts = options.declaredHosts ?? [];
+    const key = await computeGrantKey(closureFrom(requirements));
+    const stored = readGrant(memento, documentKey);
+    // N-6: a matching key alone is not enough to reuse a stored grant with no
+    // prompting -- only take the fast path when EVERY stored host still
+    // passes today's safety re-check. If `readGrant` had to drop anything,
+    // the record is not trusted at all here; fall through to the ordinary
+    // prompt flow below, which re-derives from the note's CURRENT
+    // requirements and, once answered, overwrites the untrusted record via
+    // the normal `writeGrant` call at the end of this function.
+    if (stored && stored.grant.key === key && !stored.droppedUnsafeHost) {
+        return { allowedHosts: [...stored.grant.allowedHosts] };
+    }
+    const { safeHosts, needsUnknownPrompt } = partitionHosts(requirements.hosts, requirements.hasUnknownHosts);
+    let allowedHosts;
+    if (safeHosts.length > MAX_HOST_PROMPTS) {
+        // PROMPT-STORM guard: too many distinct hosts for the per-host loop --
+        // fold the whole set into one consolidated all-or-nothing gate instead
+        // of opening `safeHosts.length` modals in a row. See `MAX_HOST_PROMPTS`'s
+        // doc comment.
+        const allowAll = await promptManyHosts(safeHosts.length);
+        allowedHosts = allowAll ? [...safeHosts] : [];
+    }
+    else {
+        allowedHosts = [];
+        for (const host of safeHosts) {
+            // Each prompt is modal; they must appear one at a time, never all at
+            // once, so this loop is deliberately sequential rather than
+            // `Promise.all`-ed.
+            const allowed = await promptHost(host, declaredHosts);
+            if (allowed)
+                allowedHosts.push(host);
+        }
+    }
+    let finalAllowedHosts = allowedHosts;
+    // The gate governs the per-host answers just collected: declining
+    // withdraws them. With NO grantable host it governs nothing, and asking
+    // anyway produces a dialog the user cannot satisfy — Allow grants no
+    // host, Deny withdraws no host, and because a run that ends with an
+    // empty allowlist is deliberately never persisted (C-3 below), the same
+    // unanswerable dialog reopens on every single Run press. A real note hit
+    // this: every `net.*` call site built its URL from a variable, so the
+    // static scan resolved zero hosts, and the gate became an infinite loop
+    // around a decision with no effect.
+    //
+    // Skipping it here cannot widen anything, and the equivalence is exact
+    // rather than a judgement call: with `safeHosts` empty, `allowedHosts`
+    // is already `[]` at this point, so BOTH branches of the gate produce
+    // `[]`. The outcome is identical with the prompt and without it.
+    //
+    // The user is not left uninformed, per AGENTS.md's "clean is not
+    // silent": the request is still denied at execution time with the
+    // ordinary `'capability-denied'` kind, which shows the component's quiet
+    // failure marker and writes the full reason to the host's diagnostics
+    // surface — naming the host actually attempted, which is strictly more
+    // useful than this gate's "some address, somewhere" wording could be.
+    if (needsUnknownPrompt && safeHosts.length > 0) {
+        const allowed = await promptUnknownHosts();
+        if (!allowed) {
+            // Declining the "can't be listed in advance" gate withdraws every
+            // per-host answer already collected too — see this module's top doc
+            // comment.
+            finalAllowedHosts = [];
+        }
+    }
+    // C-3: a FULL decline (no host ended up allowed) is deliberately NOT
+    // persisted. Persisting `{key, allowedHosts: []}` would otherwise disable
+    // network for this note's exact current code FOREVER — a single
+    // mis-click on "Don't allow" (or declining the unknown-hosts gate) would
+    // silently and permanently suppress every future prompt, with no stored
+    // record even hinting that happened and no way to revoke it short of
+    // editing the code (which changes the grant key anyway). Only ever
+    // writing a grant with at least one allowed host means a full decline
+    // simply re-prompts on the next Run press, exactly like a first run — the
+    // ordinary, recoverable outcome. A PARTIAL grant (at least one host
+    // allowed) is still persisted normally, and `clearGrantForDocument` below
+    // gives an explicit way to revoke a persisted grant when the user wants a
+    // fresh prompt without changing the note's code.
+    if (finalAllowedHosts.length > 0) {
+        await writeGrant(memento, documentKey, {
+            key,
+            allowedHosts: finalAllowedHosts,
+        });
+    }
+    return { allowedHosts: finalAllowedHosts };
+}
+/**
+ * The NON-INTERACTIVE half of `runGrantFlow`, for auto/scheduled runs
+ * (GitHub issue #11): resolves this note's effective net + bundle-fs
+ * allowlist from ONLY what is already persisted, and NEVER prompts, NEVER
+ * writes. It is exactly `runGrantFlow`'s stored-grant fast path in
+ * isolation.
+ *
+ * This is the code half of the security promise auto/scheduled execution
+ * makes (docs/security.md, docs/scripting.md): a run that was not triggered
+ * by a click must never open a modal on a timer, and must never widen what
+ * the note can reach beyond a grant the user already made by hand under the
+ * exact same executable closure. On ANY miss — no stored grant, a grant for
+ * different code (the key no longer matches), or a stored host that fails
+ * today's `isSafeHostForPrompt` re-check (N-6) — this returns an EMPTY
+ * allowlist rather than falling back to prompting. An ungranted host then
+ * fails at execution with the ordinary `'capability-denied'` kind, exactly
+ * as it would on a manual run the user declined, and the consuming
+ * component shows its quiet stale/empty state.
+ *
+ * The read-only tier (`tierForTrigger('auto'|'scheduled')` in
+ * `@markii/runtime`) is a SEPARATE, independent gate applied in the worker;
+ * this function governs only which hosts are reachable, that one governs
+ * which capabilities (no POST/PATCH/bundle-write) may run at all.
+ */
+export async function resolveStoredGrant(options) {
+    const empty = { allowedHosts: [] };
+    const stored = readGrant(options.memento, options.documentKey);
+    // N-6: a stored host that no longer passes today's safety re-check makes
+    // the whole record untrusted here, exactly as it does in `runGrantFlow` —
+    // but with no prompt to fall through to, an untrusted record simply yields
+    // the empty allowlist.
+    if (!stored || stored.droppedUnsafeHost)
+        return empty;
+    const key = await computeGrantKey(closureFrom(options.requirements));
+    if (stored.grant.key !== key)
+        return empty;
+    return { allowedHosts: [...stored.grant.allowedHosts] };
+}
+/**
+ * Clears the persisted grant (if any) for `documentKey` — the
+ * `markii.resetScriptGrants` command's whole implementation (C-3): with no
+ * stored record, `runGrantFlow`'s next call for this document is
+ * indistinguishable from a first run, so it prompts fresh for every host
+ * again. A no-op, not an error, when there is nothing stored for this
+ * document.
+ */
+export async function clearGrantForDocument(memento, documentKey) {
+    const all = readAllGrants(memento);
+    if (!hasOwn(all, documentKey))
+        return;
+    const next = { ...all };
+    delete next[documentKey];
+    await memento.update(GRANTS_STORAGE_KEY, next);
+}

package/dist/run/ip-address.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Address classification for the run path's network jail (GitHub issue #10).
+ *
+ * A network grant is a hostname string, so the host the user consented to and
+ * the address the request actually reaches are two different things. This
+ * module answers the second half: given an address, is it somewhere a note's
+ * script has any business reaching?
+ *
+ * Pure and dependency-free (the address validators are local), so it
+ * is exhaustively testable without a socket, a resolver, or a worker.
+ */
+/**
+ * True for a dotted-quad IPv4 literal: four decimal octets, 0 to 255, with
+ * no leading zeros (`010.0.0.1` is refused, since some SSRF filters
+ * mis-parse it as decimal) and no extra characters.
+ */
+export declare function isIPv4(value: string): boolean;
+/**
+ * True for an IPv6 literal without a zone index: up to eight groups of one
+ * to four hex digits, at most one `::` run, and an optional trailing
+ * dotted-quad standing for the last two groups.
+ */
+export declare function isIPv6(value: string): boolean;
+/**
+ * Where an address lives. Everything that is not `'public'` is somewhere a
+ * script reaching it would be a surprise to the person who granted a
+ * hostname: their own machine, their own LAN, or a range that is not
+ * globally routable at all.
+ */
+export type AddressScope = 'public' | 'loopback' | 'private' | 'link-local' | 'unspecified' | 'multicast' | 'reserved';
+/** Every scope except `'public'`: not reachable by default from a note's script. */
+export declare function isRestrictedScope(scope: AddressScope): boolean;
+/** Human wording for a denial or a grant prompt. Kept here so one vocabulary describes a scope everywhere. */
+export declare function describeScope(scope: AddressScope): string;
+/**
+ * Classifies `address`, or returns `undefined` when it is not an IP literal
+ * at all (a hostname, or anything malformed). The local `isIPv4`/`isIPv6`
+ * validators decide what counts as an IP; they reject the leading-zero octet forms
+ * (`010.0.0.1`) that some SSRF filters mis-parse as decimal.
+ */
+export declare function classifyIpAddress(address: string): AddressScope | undefined;