@m6d/cortex-cli 0.3.0 → 0.4.0

package/src/config/validate.ts

@@ -18,7 +18,7 @@ export function validateConfig(config: Record<string, unknown>, label: string) {
     if (!paths.length) return;
 
     report.fail({
-        what: `${label} has ${paths.length} undefined value${paths.length === 1 ? "" : "s"}`,
+        what: `${label} has ${report.plural(paths.length, "undefined value")}`,
         blocks: [
             paths.map((entry) => `  ${entry}`).join("\n"),
             "These keys are present but evaluate to undefined — usually a missing\nenvironment variable. Bun loads .env from the directory you run in; check\nthat ./.env exists and is complete.",
@@ -32,7 +32,7 @@ function findUndefined(value: object, prefix: string, seen: WeakSet<object>): st
     if (seen.has(value)) return [];
     seen.add(value);
 
-    return (Object.entries(value) as [string, unknown][]).flatMap(function ([key, child]) {
+    return (Object.entries(value) as [string, unknown][]).flatMap(([key, child]) => {
         const path = prefix ? `${prefix}.${key}` : key;
         if (child === undefined) return [path];
         if (typeof child !== "object" || child === null) return [];

package/src/contracts/charts/chart-spec.ts

@@ -155,12 +155,15 @@ function firstViolation(
 }
 
 const URL_FUNCTION = /url\(([^)]*)\)/gi;
-/** Every CSS function that names a resource to load; only url() can point at a fragment. */
-export const IMAGE_FUNCTION = /\b(url|src|image|image-set|-webkit-image-set|cross-fade|element)\(/i;
-/** The same set without url(), whose argument is checked for a fragment instead. */
-const OTHER_IMAGE_FUNCTION = /\b(src|image|image-set|-webkit-image-set|cross-fade|element)\(/i;
-const OTHER_IMAGE_FUNCTION_GLOBAL =
-    /\b(src|image|image-set|-webkit-image-set|cross-fade|element)\([^)]*\)/gi;
+/** The CSS functions besides url() that name a resource to load; only url() can point at a fragment, so its argument is checked instead. */
+const OTHER_IMAGE_FUNCTION_NAMES = "src|image|image-set|-webkit-image-set|cross-fade|element";
+/** Every CSS function that names a resource to load. */
+export const IMAGE_FUNCTION = new RegExp(String.raw`\b(url|${OTHER_IMAGE_FUNCTION_NAMES})\(`, "i");
+const OTHER_IMAGE_FUNCTION = new RegExp(String.raw`\b(${OTHER_IMAGE_FUNCTION_NAMES})\(`, "i");
+const OTHER_IMAGE_FUNCTION_GLOBAL = new RegExp(
+    String.raw`\b(${OTHER_IMAGE_FUNCTION_NAMES})\([^)]*\)`,
+    "gi",
+);
 const CSS_ESCAPE = /\\([0-9a-f]{1,6})\s?|\\(.)/gi;
 
 /** Style text with its CSS escapes decoded, so a url() hidden behind one reads as itself. */

package/src/contracts/credentials/index.ts

@@ -1,7 +1,7 @@
 import { z } from "zod";
-import { isTlsOrLoopback } from "../egress/url";
+import { canCarrySecret } from "../egress/url";
 
-export { isTlsOrLoopback };
+export { canCarrySecret };
 
 /*
  * A credential is a value Cortex presents to an upstream: one it holds
@@ -21,8 +21,13 @@ export const credentialDefinitionSchema = z.discriminatedUnion("kind", [
     }),
     z.object({
         kind: z.literal("oauth2-client-credentials"),
-        /** The token endpoint; a client secret travels only over TLS, or to loopback. */
-        tokenUrl: z.url().refine(isTlsOrLoopback, "token URL must be https, or http to loopback"),
+        /** The token endpoint; a client secret travels over TLS, to loopback, or to a private host while the egress policy is relaxed. */
+        tokenUrl: z
+            .url()
+            .refine(
+                (url) => canCarrySecret(url),
+                "token URL must be https, or http to loopback (or a private host while the egress policy is relaxed)",
+            ),
         clientId: z.string().min(1),
         clientSecret: z.string().min(1),
         scope: z.string().min(1).optional(),
@@ -45,7 +50,14 @@ export type AcquiredToken = { token: string; expiresAt: number | null };
 
 export type AcquireResult =
     | { ok: true; value: AcquiredToken }
-    | { ok: false; error: "token_request_failed" | "token_rejected" | "token_response_invalid" };
+    | {
+          ok: false;
+          error:
+              | "token_url_insecure"
+              | "token_request_failed"
+              | "token_rejected"
+              | "token_response_invalid";
+      };
 
 const tokenResponseSchema = z.object({
     access_token: z.string().min(1),
@@ -68,6 +80,11 @@ export async function acquireOAuth2ClientCredentials(
     definition: OAuth2ClientCredentials,
     post: TokenPost,
 ) {
+    // Judged again here, not only when the definition was saved: the policy
+    // may have tightened since, and a secret never travels where it may not.
+    if (!canCarrySecret(definition.tokenUrl)) {
+        return { ok: false, error: "token_url_insecure" } satisfies AcquireResult;
+    }
     const basic = Buffer.from(
         `${encodeURIComponent(definition.clientId)}:${encodeURIComponent(definition.clientSecret)}`,
     ).toString("base64");

package/src/contracts/egress/index.ts

@@ -1,7 +1,7 @@
 import { lookup } from "node:dns/promises";
-import { isIP } from "node:net";
 import type { LookupFunction } from "node:net";
 import { Agent } from "undici";
+import { isEgressRelaxed, isPrivateAddress } from "./url";
 
 /*
  * The outbound network policy for URLs a tenant controls (tool endpoints,
@@ -13,57 +13,18 @@ import { Agent } from "undici";
 
 export { credentialForms, scrubCredentialStrings } from "./scrub";
 
-type Range = { first: number; last: number };
-
-/** IPv4 /8 and /16 blocks that never denote a public host, as `[a, b]` octet ranges. */
-const BLOCKED_V4 = [
-    { a: 0 },
-    { a: 10 },
-    { a: 127 },
-    { a: 100, b: { first: 64, last: 127 } },
-    { a: 169, b: { first: 254, last: 254 } },
-    { a: 172, b: { first: 16, last: 31 } },
-    { a: 192, b: { first: 168, last: 168 } },
-    { a: 198, b: { first: 18, last: 19 } },
-] satisfies Array<{ a: number; b?: Range }>;
-
-/** Multicast and reserved: everything from 224.0.0.0 up. */
-const BLOCKED_V4_FROM = 224;
-
-function isBlockedV4(address: string) {
-    const [a = 0, b = 0] = address.split(".").map(Number);
-    if (a >= BLOCKED_V4_FROM) return true;
-    return BLOCKED_V4.some(
-        (block) => block.a === a && (!block.b || (b >= block.b.first && b <= block.b.last)),
-    );
-}
-
-function isBlockedV6(address: string) {
-    const normalized = address.toLowerCase();
-    if (normalized.startsWith("::ffff:")) {
-        const mapped = normalized.slice("::ffff:".length);
-        return isIP(mapped) === 4 ? isBlockedV4(mapped) : true;
-    }
-    return (
-        normalized === "::" ||
-        normalized === "::1" ||
-        normalized.startsWith("fc") ||
-        normalized.startsWith("fd") ||
-        /^fe[89ab]/.test(normalized)
-    );
-}
-
 /**
- * Whether an IP address may be dialed. `EGRESS_ALLOW_PRIVATE_NETWORK=true` is
+ * Whether an IP address must not be dialed. `EGRESS_ALLOW_PRIVATE_NETWORK=true` is
  * the development opt-out for localhost and private demo backends; it disables
- * every range check and must never be set in production.
+ * every range check, lets a secret travel over plain http to a private host
+ * (`canCarrySecret`), and must never be set in production.
  */
-export function isBlockedAddress(address: string) {
-    if (process.env.EGRESS_ALLOW_PRIVATE_NETWORK === "true") return false;
-    return isIP(address) === 6 ? isBlockedV6(address) : isBlockedV4(address);
+function isBlockedAddress(address: string) {
+    if (isEgressRelaxed()) return false;
+    return isPrivateAddress(address);
 }
 
-export { isTlsOrLoopback } from "./url";
+export { canCarrySecret, isEgressRelaxed } from "./url";
 
 export function egressError() {
     const error: NodeJS.ErrnoException = new Error("egress blocked");

package/src/contracts/egress/scrub.ts

@@ -1,3 +1,5 @@
+import { isRecord } from "../json";
+
 const REDACTION_MARKER = "[REDACTED]";
 
 /**
@@ -49,7 +51,7 @@ export function scrubCredentialStrings(value: unknown, credentials: string[]): u
     if (Array.isArray(value)) {
         return value.map((item) => scrubCredentialStrings(item, credentials));
     }
-    if (typeof value !== "object" || value === null) return value;
+    if (!isRecord(value)) return value;
     return Object.fromEntries(
         Object.entries(value).map(([name, child]) => [
             scrub(name),

package/src/contracts/egress/url.ts

@@ -1,16 +1,108 @@
+/*
+ * Where a secret may be sent, judged from the URL alone. Pure and free of
+ * node modules, so a browser bundle judges a URL the same way the server does.
+ */
+
+type Range = { first: number; last: number };
+
+/** IPv4 /8 and /16 blocks that never denote a public host, as `[a, b]` octet ranges. */
+const BLOCKED_V4 = [
+    { a: 0 },
+    { a: 10 },
+    { a: 127 },
+    { a: 100, b: { first: 64, last: 127 } },
+    { a: 169, b: { first: 254, last: 254 } },
+    { a: 172, b: { first: 16, last: 31 } },
+    { a: 192, b: { first: 168, last: 168 } },
+    { a: 198, b: { first: 18, last: 19 } },
+] satisfies Array<{ a: number; b?: Range }>;
+
+/** Multicast and reserved: everything from 224.0.0.0 up. */
+const BLOCKED_V4_FROM = 224;
+
+const V4_LITERAL = /^\d{1,3}(\.\d{1,3}){3}$/;
+
+function isBlockedV4(address: string) {
+    const [a = 0, b = 0] = address.split(".").map(Number);
+    if (a >= BLOCKED_V4_FROM) return true;
+    return BLOCKED_V4.some(
+        (block) => block.a === a && (!block.b || (b >= block.b.first && b <= block.b.last)),
+    );
+}
+
+/**
+ * The IPv4 address inside an IPv4-mapped IPv6 one, which arrives dotted from a
+ * DNS answer (`::ffff:8.8.8.8`) and as two hex groups from a parsed URL
+ * (`::ffff:808:808`). `null` when the tail is neither.
+ */
+function mappedV4(mapped: string) {
+    if (V4_LITERAL.test(mapped)) return mapped;
+    const groups = mapped.split(":");
+    if (groups.length !== 2 || !groups.every((group) => /^[0-9a-f]{1,4}$/.test(group))) return null;
+    const [high = 0, low = 0] = groups.map((group) => parseInt(group, 16));
+    return [high >> 8, high & 255, low >> 8, low & 255].join(".");
+}
+
+function isBlockedV6(address: string) {
+    const normalized = address.toLowerCase();
+    if (normalized.startsWith("::ffff:")) {
+        const mapped = mappedV4(normalized.slice("::ffff:".length));
+        return mapped === null || isBlockedV4(mapped);
+    }
+    return (
+        normalized === "::" ||
+        normalized === "::1" ||
+        normalized.startsWith("fc") ||
+        normalized.startsWith("fd") ||
+        /^fe[89ab]/.test(normalized)
+    );
+}
+
+/** Whether an IP literal (v4 dotted, or v6 without brackets) lies in a range that never denotes a public host. */
+export function isPrivateAddress(address: string) {
+    return address.includes(":") ? isBlockedV6(address) : isBlockedV4(address);
+}
+
+function isLoopback(hostname: string) {
+    return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "[::1]";
+}
+
+/**
+ * A host on the developer's own network: a private IP literal, a bare compose
+ * service name such as `app`, or a `.internal` / `.local` / `.localhost` name
+ * such as `host.docker.internal`. Public names and addresses are not.
+ */
+function isPrivateHost(hostname: string) {
+    const bare = hostname.replace(/^\[|\]$/g, "");
+    if (bare.includes(":") || V4_LITERAL.test(bare)) return isPrivateAddress(bare);
+    return !hostname.includes(".") || /\.(internal|local|localhost)$/.test(hostname);
+}
+
+/**
+ * The development opt-out of the egress policy: `EGRESS_ALLOW_PRIVATE_NETWORK=true`
+ * lifts every range check and lets a secret travel over plain http within the
+ * private network. Read lazily and through `globalThis`, so a browser bundle,
+ * which has no `process`, sees it off.
+ */
+export function isEgressRelaxed() {
+    return globalThis.process?.env?.EGRESS_ALLOW_PRIVATE_NETWORK === "true";
+}
+
 /**
- * Whether a credential may travel to this URL: over TLS anywhere, or over
- * plain http to loopback alone, for a service on the developer's machine.
- * Pure, so a browser bundle can judge a URL the same way the server does.
+ * Whether a secret may be sent to this URL: over TLS anywhere, or over plain
+ * http to loopback, and while the egress policy is relaxed to any private host.
+ * Pass `relaxed` explicitly where the policy is known from elsewhere (the
+ * browser form reads it from the session) or must stay strict regardless of it
+ * (a URL the browser or the CLI dials, not the server).
  */
-export function isTlsOrLoopback(url: string) {
+export function canCarrySecret(url: string, relaxed = isEgressRelaxed()) {
     try {
-        const { protocol, hostname } = new URL(url);
+        const { protocol, hostname: raw } = new URL(url);
         if (protocol === "https:") return true;
-        return (
-            protocol === "http:" &&
-            (hostname === "localhost" || hostname === "127.0.0.1" || hostname === "[::1]")
-        );
+        if (protocol !== "http:") return false;
+        // A trailing dot is the DNS root, the same name: `host.docker.internal.` is `host.docker.internal`.
+        const hostname = raw.replace(/\.$/, "");
+        return isLoopback(hostname) || (relaxed && isPrivateHost(hostname));
     } catch {
         return false;
     }

package/src/contracts/graph/helpers.ts

@@ -30,9 +30,7 @@ export function defineDomain(def: Omit<DomainDef, "__brand">) {
 }
 
 export function defineEndpoint(input: EndpointInput) {
-    const propertiesDescriptions = input.propertiesDescriptions ?? {};
-
-    const normalized = input.autoGenerated;
+    const generated = input.autoGenerated;
 
     return {
         __brand: "endpoint" as const,
@@ -40,13 +38,13 @@ export function defineEndpoint(input: EndpointInput) {
         description: input.description ?? input.name,
         path: input.path,
         method: input.method,
-        propertiesDescriptions,
-        params: normalized ? [...normalized.params] : [],
-        body: normalized ? [...normalized.body] : [],
-        response: normalized ? [...normalized.response] : [],
-        successStatus: normalized?.successStatus ?? 200,
-        errorStatuses: normalized ? [...normalized.errorStatuses] : [],
-        responseKind: normalized?.responseKind ?? "object",
+        propertiesDescriptions: input.propertiesDescriptions ?? {},
+        params: generated ? [...generated.params] : [],
+        body: generated ? [...generated.body] : [],
+        response: generated ? [...generated.response] : [],
+        successStatus: generated?.successStatus ?? 200,
+        errorStatuses: generated ? [...generated.errorStatuses] : [],
+        responseKind: generated?.responseKind ?? "object",
         queries: input.queries,
         mutates: input.mutates,
         returns: input.returns,

package/src/contracts/json/index.ts

@@ -0,0 +1,21 @@
+/**
+ * An object that is neither null nor an array: the shape a JSON object parses to, and the
+ * guard every walker over an untyped payload (a JSON Schema, an OpenAPI document, a parsed
+ * config or cache file) starts from.
+ */
+export function isRecord(value: unknown): value is Record<string, unknown> {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * One reference token of a JSON Pointer (RFC 6901): `~` is written `~0` and `/` is written
+ * `~1`. Escaping replaces `~` first and unescaping `~1` first, so a literal `~1` survives the
+ * round trip.
+ */
+export function escapePointerToken(token: string) {
+    return token.replaceAll("~", "~0").replaceAll("/", "~1");
+}
+
+export function unescapePointerToken(token: string) {
+    return token.replaceAll("~1", "/").replaceAll("~0", "~");
+}

package/src/contracts/runtime/api.ts

@@ -4,12 +4,12 @@ import {
     boundVariablesSchema,
     catalogVersionSchema,
     greetingSchema,
+    IDENTIFIER_PATTERN,
     localeSchema,
     localizedTextSchema,
     mentionedToolSchema,
     slugSchema,
     suggestionsSchema,
-    TOOL_NAME_PATTERN,
     toolSurfaceSchema,
     variableDeclarationSchema,
 } from "./grammar";
@@ -106,7 +106,7 @@ export type ToolEmbed = z.infer<typeof toolEmbedSchema>;
 
 const toolSignatureBaseSchema = z.object({
     toolId: z.uuid(),
-    name: z.string().regex(TOOL_NAME_PATTERN),
+    name: z.string().regex(IDENTIFIER_PATTERN),
     version: z.number().int().positive(),
     readOnly: z.boolean(),
     /**