@zackbart/connecta 0.40.0 → 0.42.0

package/dist/storage/d1-driver.js

@@ -1,15 +1,43 @@
+import { Effect, Option } from "effect";
+import { RequestScope } from "../runtime/request-scope.js";
+import { hasTimingTraces, traceFor } from "../timing-trace.js";
+import { utf8Length } from "../bytes.js";
+// Request-wide totals include admission, credentials and catalog work. These
+// I/O-spanning observations are not pure storage latency or CPU attribution.
+function timedD1(family, statements, operation) {
+    return Effect.suspend(() => {
+        if (!hasTimingTraces())
+            return operation;
+        return Effect.flatMap(Effect.serviceOption(RequestScope), (owner) => {
+            const trace = Option.isSome(owner) ? traceFor(owner.value.identity) : undefined;
+            if (!trace)
+                return operation;
+            const start = performance.now();
+            let bytes = 0;
+            return operation.pipe(Effect.tap((value) => Effect.sync(() => {
+                // Count serialized application result bytes, not D1 wire bytes.
+                try {
+                    bytes = utf8Length(JSON.stringify(value) ?? "");
+                }
+                catch {
+                    /* no payload retained */
+                }
+            })), Effect.ensuring(Effect.sync(() => trace.record(family, performance.now() - start, bytes, statements))));
+        });
+    });
+}
 import { effectSqlDriver, sqlDriverEdge, sqlPromise } from "./sql-driver.js";
 export function d1Driver(db) {
     const prepare = (statement) => statement.params.length > 0 ? db.prepare(statement.sql).bind(...statement.params) : db.prepare(statement.sql);
     return sqlDriverEdge(effectSqlDriver({
-        all: (statement) => sqlPromise(() => prepare(statement)
+        all: (statement) => timedD1("d1.read", 1, sqlPromise(() => prepare(statement)
             .all()
-            .then((result) => result.results)),
-        run: (statement) => sqlPromise(() => prepare(statement)
+            .then((result) => result.results))),
+        run: (statement) => timedD1("d1.write", 1, sqlPromise(() => prepare(statement)
             .run()
-            .then((result) => result.meta.changes ?? 0)),
+            .then((result) => result.meta.changes ?? 0))),
         // D1's public binding API preserves per-statement changes, including zero;
         // execute the whole array once. No withTransaction, RETURNING, or replay.
-        batch: (statements) => sqlPromise(() => db.batch(statements.map(prepare)).then((results) => results.map((result) => result.meta.changes ?? 0))),
+        batch: (statements) => timedD1("d1.batch", statements.length, sqlPromise(() => db.batch(statements.map(prepare)).then((results) => results.map((result) => result.meta.changes ?? 0)))),
     }));
 }

package/dist/storage/keys.js

@@ -58,7 +58,8 @@ export const scopes = {
 export const RESULT_TTL_SECONDS = 900;
 /**
  * A stashed result: chunk 0 at `result:<id>`, chunk n at `result:<id>#<n>`.
- * The value is the paging envelope `src/meta-tools.ts` writes and reads.
+ * The value is the paging envelope `src/meta-tools.ts` writes and reads, or at
+ * chunk 0 the refusal `src/result-seal.ts` writes for a result it did not publish.
  */
 export const resultKeys = {
     family: {
@@ -176,6 +177,8 @@ export const connectorHealthKeys = {
     discovery: (connectorId, partitionDigest) => validateStorageKey(`connector-health:v1:${connectorId}:${partitionDigest}:discovery`),
     status: (connectorId, partitionDigest) => validateStorageKey(`connector-health:v1:${connectorId}:${partitionDigest}:status`),
 };
+const responseCacheLocatorPrefix = (id, config) => validateStorageKey(`response-cache:v1:${id}:${config}:`);
+const responseCacheLocatorSeparator = ":";
 /**
  * SDK catalog response cache, complete manifests published after their chunks.
  * Secret-bearing inputs reach these keys only through `secretDigest`.
@@ -189,13 +192,17 @@ export const responseCacheKeys = {
         codec: textCodec,
         ttl: {
             kind: "configured",
-            by: "bounded downstream ttlMs; generations and hash refresh baselines expire after 48 hours",
+            by: "bounded downstream ttlMs; generations, refusal fences and hash refresh baselines expire after 48 hours",
         },
         durable: false,
     },
     prefix: (id) => validateStorageKey(`response-cache:v1:${id}:`),
     generation: (id) => validateStorageKey(`response-cache:v1:${id}:generation`),
-    namespace: (id, config, generation) => validateStorageKey(`response-cache:v1:${id}:${config}:${generation}:`),
+    namespace: (id, config, generation) => validateStorageKey(`${responseCacheLocatorPrefix(id, config)}${generation}${responseCacheLocatorSeparator}`),
+    /** SQL binds these layout parts around the stored generation; it owns no delimiters. */
+    locatorPrefix: responseCacheLocatorPrefix,
+    locatorSeparator: responseCacheLocatorSeparator,
+    locatedEntry: (prefix, generation, partition) => validateStorageKey(`${prefix}${generation}${responseCacheLocatorSeparator}${partition}`),
     entry: (namespace, partition) => validateStorageKey(`${namespace}${partition}`),
     refreshDigest: (id, config, partition) => validateStorageKey(`response-cache:v1:${id}:refresh-digest:${config}:${partition}`),
     chunk: (entry, revision, index) => validateStorageKey(`${entry}:chunk:${revision}:${index}`),
@@ -350,19 +357,21 @@ export const oauthRefreshActiveKeys = {
     prefix: "oauth:refresh-active:",
     holder: (epoch, holder) => validateStorageKey(`oauth:refresh-active:${epoch}:${holder}`),
 };
-/** Single-use browser links (`used`/`started`/`failed`/`closed`) and MRTR rounds. */
+/** Single-use browser links and forced resets (`used`/`started`/`failed`), and MRTR rounds. */
 export const oauthConnectKeys = {
     family: {
         name: "oauth-connect",
         scope: "connector",
-        prefixes: ["oauth:connect-used:", "oauth:request-used:"],
+        prefixes: ["oauth:connect-used:", "oauth:connect-reset:", "oauth:request-used:"],
         version: { number: 1, in: "untagged" },
         codec: textCodec,
-        // The link's remaining lifetime, or fifteen minutes when retiring it.
-        ttl: { kind: "fixed", seconds: 15 * 60 },
+        // A link's remaining lifetime, fifteen minutes for a round, or thirty for a
+        // reset, which must outlive every link its flow can issue.
+        ttl: { kind: "fixed", seconds: 30 * 60 },
         durable: false,
     },
     used: (nonce) => validateStorageKey(`oauth:connect-used:${nonce}`),
+    reset: (flow) => validateStorageKey(`oauth:connect-reset:${flow}`),
     retry: (nonce) => validateStorageKey(`oauth:request-used:${nonce}`),
 };
 /**

package/dist/storage/sql-native.js

@@ -27,7 +27,7 @@ import { Effect } from "effect";
 import { activityBehaviorFacts, activityPackageVersion, activityClientFact, InvalidActivityCursorError, } from "../activity.js";
 import { assertKnownOptions, ConfigError, keys, optionsOf } from "../config-schema.js";
 import { agentFrictionForCode } from "../activity-friction.js";
-import { accessTokenKeys, validateStorageKey } from "./keys.js";
+import { accessTokenKeys, responseCacheKeys, validateStorageKey } from "./keys.js";
 const sql = (text, ...params) => ({
     sql: text,
     params,
@@ -132,6 +132,34 @@ export function nativeSqlStorage(driver) {
                 return new Map(rows.map((row) => [row.key, textOf(row.value, row.value_bytes, "Stored access token metadata")]));
             });
         },
+        catalogSnapshot(keys, generationKey, prefix, suffixes) {
+            return Effect.gen(function* () {
+                if (keys.length < 1 || keys.length > 4 || suffixes.length > 3)
+                    throw new RangeError("Catalog locator exceeds bounds");
+                for (const key of [...keys, generationKey, prefix, ...suffixes])
+                    validateStorageKey(key);
+                yield* ensure();
+                const rows = yield* driver.all(sql(`WITH initial AS (
+            SELECT key, value FROM connecta_kv WHERE key IN (${keys.map(() => "?").join(",")}) AND ${live}
+          ), suffixes(suffix) AS (VALUES ${suffixes.map(() => "(?)").join(",") || "(NULL)"}), wanted(key) AS (
+            SELECT key FROM initial UNION ALL
+            SELECT ? || (SELECT value FROM initial WHERE key = ?) || ? || suffix FROM suffixes
+          ) SELECT key, ${textColumn("value")} FROM connecta_kv
+            WHERE key IN (SELECT key FROM wanted) AND ${live}`, ...keys, ...suffixes, prefix, generationKey, responseCacheKeys.locatorSeparator));
+                const values = new Map(rows.map((row) => [row.key, textOf(row.value, row.value_bytes, "Stored catalog locator")]));
+                for (const key of keys)
+                    if (!values.has(key))
+                        values.set(key, null);
+                const generation = values.get(generationKey);
+                if (generation)
+                    for (const suffix of suffixes) {
+                        const key = responseCacheKeys.locatedEntry(prefix, generation, suffix);
+                        if (!values.has(key))
+                            values.set(key, null);
+                    }
+                return values;
+            });
+        },
         getMany(keys) {
             return Effect.gen(function* () {
                 for (const key of keys)
@@ -157,6 +185,25 @@ export function nativeSqlStorage(driver) {
                 return values;
             });
         },
+        setMany(entries, opts) {
+            return Effect.gen(function* () {
+                if (entries.length > 64)
+                    throw new RangeError("setMany accepts at most 64 rows");
+                for (const [key] of entries)
+                    validateStorageKey(key);
+                const expiry = expiryOptions(opts);
+                if (!entries.length)
+                    return;
+                yield* ensure();
+                const changes = yield* driver.batch([
+                    expirySweep(),
+                    ...entries.map(([key, value]) => sql(`INSERT INTO connecta_kv (key, value, expires_at_ms) VALUES (?, ?, ${expiry.expression})
+           ON CONFLICT (key) DO UPDATE SET value = excluded.value, expires_at_ms = excluded.expires_at_ms`, key, value, expiry.value)),
+                ]);
+                if (changes.length !== entries.length + 1 || changes.slice(1).some((changed) => changed !== 1))
+                    throw new Error("SQL multi-set confirmation is incomplete");
+            });
+        },
         set(key, value, opts) {
             return Effect.gen(function* () {
                 validateStorageKey(key);
@@ -334,11 +381,20 @@ function activityRow(read) {
     }
     return row;
 }
+// Operation metadata shares the existing kind-tagged text slot; no new columns.
+function parseOperation(raw) {
+    try {
+        return raw === null ? undefined : JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+}
 function rowToEvent(row) {
     // Rows written before `friction` had a column derive it from the code.
     // Friction without a code — an oversized but successful result — exists
     // only in the column, which is why the column exists.
-    const friction = row.friction ?? agentFrictionForCode(row.error_code ?? undefined);
+    const friction = row.event_kind === "operation" ? undefined : (row.friction ?? agentFrictionForCode(row.error_code ?? undefined));
     const packageVersion = activityPackageVersion(row.package_version);
     const clientName = activityClientFact(row.client_name, "name");
     const clientVersion = activityClientFact(row.client_version, "version");
@@ -351,6 +407,7 @@ function rowToEvent(row) {
             classification: row.classification,
             resultBytes: row.result_bytes,
             kind: row.event_kind,
+            operation: row.event_kind === "operation" ? parseOperation(row.drift_kind) : undefined,
             pool: row.pool_name,
             actorBasis: row.actor_basis,
             drift: {
@@ -461,7 +518,7 @@ export function nativeSqlActivityStore(driver, kind, options = {}) {
                     // Stored beside the code rather than derived from it: a truncated
                     // result is friction on a call that succeeded, and
                     // `error_code IS NOT NULL` stays an honest count of failures.
-                    event.friction ?? null, event.approval ?? null, activityPackageVersion(event.packageVersion) ?? null, event.serverName, event.serverVersion, activityClientFact(event.clientName, "name") ?? null, activityClientFact(event.clientVersion, "version") ?? null, event.deploymentId ?? null, facts.classification ?? null, facts.resultBytes ?? null, facts.kind ?? null, facts.drift?.kind ?? null, facts.drift?.addedTools ?? null, facts.drift?.removedTools ?? null, facts.drift?.changedTools ?? null, facts.pool ?? null, facts.actorBasis ?? null),
+                    event.kind === "operation" ? null : (event.friction ?? null), event.approval ?? null, activityPackageVersion(event.packageVersion) ?? null, event.serverName, event.serverVersion, activityClientFact(event.clientName, "name") ?? null, activityClientFact(event.clientVersion, "version") ?? null, event.deploymentId ?? null, facts.classification ?? null, facts.resultBytes ?? null, facts.kind ?? null, facts.kind === "operation" ? JSON.stringify(facts.operation ?? null) : (facts.drift?.kind ?? null), facts.drift?.addedTools ?? null, facts.drift?.removedTools ?? null, facts.drift?.changedTools ?? null, facts.pool ?? null, facts.actorBasis ?? null),
                     sql(`DELETE FROM tool_call_activity WHERE id IN (
             SELECT id FROM tool_call_activity
             WHERE occurred_at_ms < ?

package/dist/storage/sql.js

@@ -10,6 +10,12 @@ export function sqlStorage(driver, kind) {
     const root = {};
     const native = {
         ...store,
+        setMany: (entries, options) => {
+            let write = store.setMany(entries, options);
+            for (const [key] of entries)
+                write = observedWrite(root, key, write);
+            return write;
+        },
         set: (key, value, options) => observedWrite(root, key, store.set(key, value, options)),
         delete: (key) => observedWrite(root, key, store.delete(key)),
         compareAndSet: (key, expected, next, options) => observedWrite(root, key, store.compareAndSet(key, expected, next, options)),

package/dist/timing-trace.js

@@ -0,0 +1,84 @@
+const families = new Set([
+    "catalog.cache.lookup",
+    "catalog.cache.hit",
+    "catalog.cache.expired",
+    "catalog.chunks",
+    "catalog.validated.hit",
+    "catalog.validated.miss",
+    "catalog.intake",
+    "catalog.decode",
+    "catalog.validate",
+    "catalog.accepted",
+    "catalog",
+    "admission",
+    "connector",
+    "result",
+    "d1.read",
+    "d1.write",
+    "d1.batch",
+    "memo.hit",
+    "memo.miss",
+    "memo.fresh",
+]);
+const traces = new WeakMap();
+let active = 0;
+let firstRequest = true;
+export const hasTimingTraces = () => active > 0;
+export const traceFor = (identity) => identity ? traces.get(identity) : undefined;
+const finite = (value) => (Number.isFinite(value) && value >= 0 ? value : 0);
+export class TimingTrace {
+    first;
+    started = performance.now();
+    totals = new Map();
+    closed = false;
+    constructor(first) {
+        this.first = first;
+    }
+    record(family, durationMs = 0, bytes = 0, statements = 0, absent = 0, items = 0) {
+        if (this.closed || !families.has(family))
+            return;
+        const total = this.totals.get(family) ?? { count: 0, durationMs: 0, bytes: 0, statements: 0, absent: 0, items: 0 };
+        total.count++;
+        total.durationMs += finite(durationMs);
+        total.bytes += finite(bytes);
+        total.statements += finite(statements);
+        total.absent += finite(absent);
+        total.items += finite(items);
+        this.totals.set(family, total);
+    }
+    finish(logger) {
+        if (this.closed)
+            return;
+        this.closed = true;
+        try {
+            logger.info("connecta.timing", {
+                version: 1,
+                isolateFirstRequest: this.first,
+                durationMs: performance.now() - this.started,
+                weakReferences: typeof WeakRef === "function" && typeof FinalizationRegistry === "function",
+                operations: Object.fromEntries(this.totals),
+            });
+        }
+        catch {
+            /* Observability cannot change a request's outcome. */
+        }
+        this.totals.clear();
+    }
+}
+/** Called for each MCP request, including those not sampled. */
+export function startTimingTrace(identity, sampleRate, logger) {
+    const first = firstRequest;
+    firstRequest = false;
+    if (sampleRate <= 0 || (sampleRate < 1 && Math.random() >= sampleRate))
+        return undefined;
+    const trace = new TimingTrace(first);
+    traces.set(identity, trace);
+    active++;
+    return () => {
+        if (traces.get(identity) !== trace)
+            return;
+        traces.delete(identity);
+        active--;
+        trace.finish(logger);
+    };
+}

package/dist/tool-safety.d.ts

@@ -0,0 +1,33 @@
+import type { ToolDef } from "./types.js";
+/** What deployment code may say about one tool. */
+export type ClassificationOverride = "read" | "read-repeatable" | "write" | "hidden";
+export declare function sourceClassification(tool: ToolDef): "read" | "write";
+/** The source said this tool writes, as opposed to saying nothing. */
+export declare function sourceDeclaresWrite(tool: ToolDef): boolean;
+/**
+ * Deployment override, then fail-closed annotations. `"read"` speaks only where
+ * the source is silent: a declared write stays a write, because a read annotation
+ * lets a host resend the call. `"read-repeatable"` is the deployment accepting
+ * that resend for a tool it has checked, so it serves as a read regardless. Either
+ * way a source write stays write-like, so Connecta itself never replays it.
+ */
+export declare function classifyTool(definition: ToolDef, override?: Exclude<ClassificationOverride, "hidden">): "read" | "write";
+export declare function carryToolClassification(source: ToolDef, served: ToolDef, acceptRepeat?: boolean): ToolDef;
+/** Replay and outcome policy only; admission and presentation use the served class. */
+export declare function isWriteLike(tool: ToolDef): boolean;
+/** The surface that runs a read-only program: it never dispatches a write-like call. */
+export declare const READ_PROGRAM_SOURCE: "execute_read_code";
+/**
+ * What a read program refuses: anything write-like, unless the deployment accepted
+ * repeats. A plain `"read"` over a source write stays out, because only
+ * `"read-repeatable"` says a host's resend of the program is acceptable.
+ */
+export declare function readProgramRefuses(tool: ToolDef): boolean;
+export declare function cloneTool(tool: ToolDef): ToolDef;
+/**
+ * The only permission decision for a connector call. Approval is client-owned.
+ * A read-only endpoint refuses every write on every surface; a writable one
+ * sends writes through call_destructive_tool and writing programs, never call_tool
+ * or a read program.
+ */
+export declare function writeRefusal(classification: ToolDef["classification"], surface: string, readOnly?: boolean): "read_only_endpoint" | "destructive_tool_requires_approval" | undefined;

package/dist/tool-safety.js

@@ -1,33 +1,69 @@
-/** Deployment override, then fail-closed annotations. */
+function sourceFactsOf(annotations) {
+    const readOnly = annotations?.readOnlyHint;
+    const destructive = annotations?.destructiveHint;
+    if (readOnly === true && destructive !== true)
+        return "read";
+    // Anything but a clean read or silence counts as declared, including contradictory
+    // or malformed hints: an override must not turn an unclear statement into a read.
+    return readOnly === undefined && destructive !== true ? "silent" : "declared_write";
+}
+// Source policy is fail-closed annotations, with silence kept apart from a
+// declared write. Deployment overrides never enter it. It is private metadata,
+// not catalog data. Keep it through host-owned clones without exposing it to
+// tools or storage.
+const sourceFacts = new WeakMap();
+const factsFor = (tool) => sourceFacts.get(tool) ?? sourceFactsOf(tool.annotations);
+export function sourceClassification(tool) {
+    return factsFor(tool) === "read" ? "read" : "write";
+}
+/** The source said this tool writes, as opposed to saying nothing. */
+export function sourceDeclaresWrite(tool) {
+    return factsFor(tool) === "declared_write";
+}
+/**
+ * Deployment override, then fail-closed annotations. `"read"` speaks only where
+ * the source is silent: a declared write stays a write, because a read annotation
+ * lets a host resend the call. `"read-repeatable"` is the deployment accepting
+ * that resend for a tool it has checked, so it serves as a read regardless. Either
+ * way a source write stays write-like, so Connecta itself never replays it.
+ */
 export function classifyTool(definition, override) {
-    if (override !== undefined)
+    if (override === "read-repeatable")
+        return "read";
+    if (override === "write" || (override === "read" && !sourceDeclaresWrite(definition)))
         return override;
-    return definition.annotations?.readOnlyHint === true && definition.annotations?.destructiveHint !== true
-        ? "read"
-        : "write";
-}
-// Source policy is fail-closed annotations.
-// Deployment overrides never enter it. It is private metadata, not catalog data.
-// Keep it through host-owned clones without exposing it to tools or storage.
-const sourceClassifications = new WeakMap();
-export function sourceClassification(tool) {
-    return sourceClassifications.get(tool) ?? classifyTool(tool);
+    return sourceClassification(definition);
 }
-export function carryToolClassification(source, served) {
-    sourceClassifications.set(served, sourceClassification(source));
+// Tools a deployment set to `"read-repeatable"`, private like the source facts.
+const repeatAccepted = new WeakSet();
+export function carryToolClassification(source, served, acceptRepeat = repeatAccepted.has(source)) {
+    sourceFacts.set(served, factsFor(source));
+    if (acceptRepeat)
+        repeatAccepted.add(served);
     return served;
 }
 /** Replay and outcome policy only; admission and presentation use the served class. */
 export function isWriteLike(tool) {
     return tool.classification !== "read" || sourceClassification(tool) === "write";
 }
+/** The surface that runs a read-only program: it never dispatches a write-like call. */
+export const READ_PROGRAM_SOURCE = "execute_read_code";
+/**
+ * What a read program refuses: anything write-like, unless the deployment accepted
+ * repeats. A plain `"read"` over a source write stays out, because only
+ * `"read-repeatable"` says a host's resend of the program is acceptable.
+ */
+export function readProgramRefuses(tool) {
+    return isWriteLike(tool) && !repeatAccepted.has(tool);
+}
 export function cloneTool(tool) {
     return carryToolClassification(tool, structuredClone(tool));
 }
 /**
  * The only permission decision for a connector call. Approval is client-owned.
  * A read-only endpoint refuses every write on every surface; a writable one
- * sends writes through call_destructive_tool and programs, never call_tool.
+ * sends writes through call_destructive_tool and writing programs, never call_tool
+ * or a read program.
  */
 export function writeRefusal(classification, surface, readOnly = false) {
     if (classification === "read")

package/dist/types.d.ts

@@ -335,6 +335,12 @@ export type ConnectorSkillResourceContents = {
     text?: never;
 });
 /** The whole plugin contract — the one open seam. */
+/** A complete cached catalog and the times it was fetched and expires, in epoch milliseconds. */
+export interface ConnectorCatalogPeek {
+    tools: ToolDef[];
+    fetchedAt: number;
+    expiresAt: number;
+}
 export interface Connector {
     /** Serve only read-classified tools on every endpoint. Defaults to false. */
     readOnly?: boolean;
@@ -399,6 +405,16 @@ export interface Connector {
      * fetched lazily over the network and are not known at construction time.
      */
     staticTools?: ToolDef[];
+    /**
+     * Optional: the newest complete catalog this context could be served, fresh
+     * or stale, read from storage alone. No transport, no authorization and no
+     * writes. Discovery lists its result and marks it; call resolution never
+     * reads it. `remoteMcp()` implements it. A custom connector omits it and
+     * discovery falls back to the catalog core retains for an authenticated owner.
+     * A wrapper that replaces `listTools` must replace or remove this as well, or
+     * discovery lists what the wrapper would have changed.
+     */
+    peekCatalog?(ctx: ConnectorContext): Promise<ConnectorCatalogPeek | undefined>;
     /**
      * Optional: what this connector is, for `Connecta.describeConfig()` and the
      * operator surfaces built on it — where it points, how it authenticates,
@@ -616,6 +632,21 @@ export interface Executor {
      * rewrite; set this to say the same thing minification-proof.
      */
     readonly name?: string;
+    /**
+     * The run's wall-clock deadline, in whole milliseconds, when this sandbox has
+     * one: time from `execute()` to its own timeout result. Connecta ends a
+     * program's reads just before it, so a slow read becomes a catchable
+     * `timeout` rather than the whole run's failure. Omit it if the sandbox
+     * has no fixed deadline. See documentation/code-mode.md#cancellation-and-limits.
+     */
+    readonly deadlineMs?: number;
+    /**
+     * The largest stored result, in UTF-8 bytes, that one program may read whole
+     * with `connecta.result(id, { all: true })` and still have budget left to use
+     * it. Default 1.5 MiB. Set it lower when a tighter CPU or memory limit would
+     * end the run first.
+     */
+    readonly maxReadBytes?: number;
     execute(code: string, providers: ExecutorProvider[]): Promise<ExecuteResult>;
     /** Release runtime resources. Node's built-in pool implements this. */
     close?(): void | Promise<void>;
@@ -842,6 +873,11 @@ export interface InboundAuth {
     kind: string;
     /** This provider may admit a human identity to operator mutation routes. */
     interactiveOperator?: true;
+    /**
+     * This provider checks credentials against the deployment's own URL and was
+     * given none, so construction refuses a configuration without `publicUrl`.
+     */
+    requiresPublicUrl?: true;
     /**
      * Recognize credential syntax or trusted runtime context, without verifying
      * it or doing I/O. The first recognizing provider owns the verdict, including

package/dist/url-safety.js

@@ -13,11 +13,11 @@
  * legacy IPv4 spelling (`2130706433`, `0x7f.1`, `0177.0.0.1`) into dotted
  * decimal and every IPv6 literal into compressed hex, so one canonical form is
  * all this module reads. It never resolves a name: that needs DNS, which the
- * Workers-safe core cannot do, and a name that resolves somewhere private — or
- * rebinds after the check — is out of scope. Pure Web API, no `node:` import.
+ * Workers-safe core cannot do. The owned Node transport additionally resolves
+ * and pins learned destinations at connect time. Pure Web API, no `node:` import.
  */
 function classifyIpv4(octets) {
-    const [a = 0, b = 0] = octets;
+    const [a = 0, b = 0, c = 0] = octets;
     if (a === 127)
         return "loopback";
     if (a === 0 ||
@@ -25,7 +25,14 @@ function classifyIpv4(octets) {
         (a === 172 && b >= 16 && b <= 31) ||
         (a === 192 && b === 168) ||
         (a === 169 && b === 254) ||
-        (a === 100 && b >= 64 && b <= 127)) {
+        (a === 100 && b >= 64 && b <= 127) ||
+        (a === 192 && b === 0 && (c === 0 || c === 2)) || // IETF protocol, documentation
+        (a === 192 && b === 88 && c === 99) || // 6to4 relay anycast
+        (a === 198 && (b === 18 || b === 19)) || // benchmarking
+        (a === 198 && b === 51 && c === 100) || // documentation
+        (a === 203 && b === 0 && c === 113) || // documentation
+        a >= 224 // multicast, reserved, broadcast
+    ) {
         return "private";
     }
     return "public";
@@ -61,24 +68,35 @@ function ipv6Pieces(host) {
     return [...head, ...Array.from({ length: missing }, () => 0), ...tail];
 }
 function classifyIpv6(pieces) {
-    const [first = 0] = pieces;
-    const leadingZeros = pieces.slice(0, 5).every((piece) => piece === 0);
-    if (leadingZeros && pieces[5] === 0 && pieces[6] === 0) {
-        if (pieces[7] === 0)
-            return "private"; // ::
-        if (pieces[7] === 1)
-            return "loopback"; // ::1
+    const [p0 = 0, p1 = 0, p2 = 0, p3 = 0, p4 = 0, p5 = 0, p6 = 0, p7 = 0] = pieces;
+    const v4 = (high, low) => classifyIpv4([high >> 8, high & 0xff, low >> 8, low & 0xff]);
+    // A transitional form reaches, at most, the IPv4 address it carries. Only a
+    // mapped address can reach this host, so only it stays `loopback`; every
+    // other non-public carrier is `private`, keeping it out of a loopback
+    // connector's learned URLs.
+    const carried = (high, low) => (v4(high, low) === "public" ? "public" : "private");
+    const zeros = p0 === 0 && p1 === 0 && p2 === 0 && p3 === 0;
+    if (zeros && p4 === 0) {
+        if (p5 === 0xffff)
+            return v4(p6, p7); // ::ffff:a.b.c.d mapped
+        if (p5 === 0) {
+            if (p6 === 0 && p7 === 1)
+                return "loopback"; // ::1
+            return carried(p6, p7); // :: and ::a.b.c.d compatible
+        }
     }
-    // ::ffff:a.b.c.d reaches the mapped IPv4 destination; classify that.
-    if (leadingZeros && pieces[5] === 0xffff) {
-        const high = pieces[6] ?? 0;
-        const low = pieces[7] ?? 0;
-        return classifyIpv4([high >> 8, high & 0xff, low >> 8, low & 0xff]);
+    if (zeros && p4 === 0xffff && p5 === 0)
+        return carried(p6, p7); // ::ffff:0:a.b.c.d translated
+    if (p0 === 0x64 && p1 === 0xff9b && p2 === 0 && p3 === 0 && p4 === 0 && p5 === 0)
+        return carried(p6, p7); // NAT64
+    if (p0 === 0x2002)
+        return carried(p1, p2); // 6to4
+    // Global unicast is 2000::/3. Outside it: unique-local, link-local,
+    // site-local, multicast, local-use NAT64, reserved. Inside it, special-purpose
+    // 2001::/23 and documentation 2001:db8::/32 and 3fff::/20 are not destinations.
+    if ((p0 & 0xe000) !== 0x2000 || (p0 === 0x2001 && (p1 < 0x200 || p1 === 0xdb8)) || (p0 === 0x3fff && p1 < 0x1000)) {
+        return "private";
     }
-    if ((first & 0xfe00) === 0xfc00)
-        return "private"; // fc00::/7
-    if ((first & 0xffc0) === 0xfe80)
-        return "private"; // fe80::/10
     return "public";
 }
 /**