@m6d/cortex-cli 0.2.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

@@ -0,0 +1,183 @@
+import { z } from "zod";
+import { canCarrySecret } from "../egress/url";
+
+export { canCarrySecret };
+
+/*
+ * A credential is a value Cortex presents to an upstream: one it holds
+ * (`static`) or one it acquires (`oauth2-client-credentials`, RFC 6749 §4.4).
+ * The definition is the same on both sides; the Control Center stores it,
+ * a code config declares it, and each side resolves it to a bearer through
+ * the helper and cache below with its own egress-guarded fetch.
+ */
+
+export const CREDENTIAL_KINDS = ["static", "oauth2-client-credentials"] as const;
+export type CredentialKind = (typeof CREDENTIAL_KINDS)[number];
+
+export const credentialDefinitionSchema = z.discriminatedUnion("kind", [
+    z.object({
+        kind: z.literal("static"),
+        value: z.string().min(1),
+    }),
+    z.object({
+        kind: z.literal("oauth2-client-credentials"),
+        /** 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(),
+    }),
+]);
+export type CredentialDefinition = z.infer<typeof credentialDefinitionSchema>;
+export type OAuth2ClientCredentials = Extract<
+    CredentialDefinition,
+    { kind: "oauth2-client-credentials" }
+>;
+
+/** One POST to the token endpoint through the caller's guarded fetch; `null` when the transport failed. */
+export type TokenPost = (
+    url: string,
+    init: { headers: Record<string, string>; body: string },
+) => Promise<{ status: number; body: string } | null>;
+
+/** A bearer and when it stops being one; `null` when the issuer did not say. */
+export type AcquiredToken = { token: string; expiresAt: number | null };
+
+export type AcquireResult =
+    | { ok: true; value: AcquiredToken }
+    | {
+          ok: false;
+          error:
+              | "token_url_insecure"
+              | "token_request_failed"
+              | "token_rejected"
+              | "token_response_invalid";
+      };
+
+const tokenResponseSchema = z.object({
+    access_token: z.string().min(1),
+    token_type: z.string().optional(),
+    // Some issuers (Azure AD v1 among them) send the lifetime as a string.
+    expires_in: z
+        .union([z.number(), z.string().regex(/^\d+$/).transform(Number)])
+        .pipe(z.number().nonnegative())
+        .optional(),
+});
+
+/**
+ * The client credentials grant: a form-encoded POST with the client
+ * authenticated by `client_secret_basic` (RFC 6749 §2.3.1, each half
+ * form-encoded before base64). The endpoint's body never leaves this
+ * function: a failure is one of three literals, since the body may echo
+ * the client secret or carry the issuer's own error detail.
+ */
+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");
+    const answer = await post(definition.tokenUrl, {
+        headers: {
+            Authorization: `Basic ${basic}`,
+            "Content-Type": "application/x-www-form-urlencoded",
+            Accept: "application/json",
+        },
+        body: new URLSearchParams({
+            grant_type: "client_credentials",
+            ...(definition.scope ? { scope: definition.scope } : {}),
+        }).toString(),
+    });
+    if (!answer) return { ok: false, error: "token_request_failed" } satisfies AcquireResult;
+    if (answer.status < 200 || answer.status >= 300) {
+        return { ok: false, error: "token_rejected" } satisfies AcquireResult;
+    }
+    let parsed: z.ZodSafeParseResult<z.infer<typeof tokenResponseSchema>>;
+    try {
+        parsed = tokenResponseSchema.safeParse(JSON.parse(answer.body));
+    } catch {
+        return { ok: false, error: "token_response_invalid" } satisfies AcquireResult;
+    }
+    if (!parsed.success || (parsed.data.token_type ?? "bearer").toLowerCase() !== "bearer") {
+        return { ok: false, error: "token_response_invalid" } satisfies AcquireResult;
+    }
+    const issuedAt = Date.now();
+    return {
+        ok: true as const,
+        value: {
+            token: parsed.data.access_token,
+            expiresAt:
+                parsed.data.expires_in === undefined
+                    ? null
+                    : issuedAt + parsed.data.expires_in * 1000,
+        },
+    } satisfies AcquireResult;
+}
+
+/** A token is not reused inside this margin of its expiry: the call it is presented on still has to complete. */
+const EXPIRY_MARGIN_MS = 30_000;
+
+/** Equal definitions share one key; a rotated secret is another definition and another token. Kept in memory only, like the definitions themselves. */
+function keyOf(definition: CredentialDefinition) {
+    return JSON.stringify(definition);
+}
+
+/**
+ * Acquired tokens by definition, reused until their expiry margin. Concurrent
+ * acquisitions of one definition share a single request; a token the issuer
+ * gave no expiry for is answered but not kept, since nothing says when it
+ * stops working. `invalidate` is for the caller that saw a 401: the next
+ * resolve acquires again. Pure, so the console's client bundle may import
+ * the schemas beside it.
+ */
+export function createCredentialCache(now: () => number = Date.now) {
+    const tokens = new Map<string, AcquiredToken>();
+    const inFlight = new Map<string, Promise<AcquireResult>>();
+
+    return {
+        async get(definition: CredentialDefinition, acquire: () => Promise<AcquireResult>) {
+            const key = keyOf(definition);
+            const cached = tokens.get(key);
+            if (
+                cached &&
+                cached.expiresAt !== null &&
+                cached.expiresAt - EXPIRY_MARGIN_MS > now()
+            ) {
+                return { ok: true, value: cached } satisfies AcquireResult;
+            }
+            tokens.delete(key);
+            const pending = inFlight.get(key);
+            if (pending) return pending;
+            const acquiring = acquire()
+                .then((result) => {
+                    if (
+                        result.ok &&
+                        result.value.expiresAt !== null &&
+                        result.value.expiresAt - EXPIRY_MARGIN_MS > now()
+                    ) {
+                        tokens.set(key, result.value);
+                    }
+                    return result;
+                })
+                .finally(() => inFlight.delete(key));
+            inFlight.set(key, acquiring);
+            return acquiring;
+        },
+        invalidate(definition: CredentialDefinition) {
+            tokens.delete(keyOf(definition));
+        },
+    };
+}
+
+export type CredentialCache = ReturnType<typeof createCredentialCache>;

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,72 +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);
 }
 
-/**
- * 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.
- */
-export function isTlsOrLoopback(url: string) {
-    try {
-        const { protocol, hostname } = new URL(url);
-        if (protocol === "https:") return true;
-        return (
-            protocol === "http:" &&
-            (hostname === "localhost" || hostname === "127.0.0.1" || hostname === "[::1]")
-        );
-    } catch {
-        return false;
-    }
-}
+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

@@ -0,0 +1,109 @@
+/*
+ * 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 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 canCarrySecret(url: string, relaxed = isEgressRelaxed()) {
+    try {
+        const { protocol, hostname: raw } = new URL(url);
+        if (protocol === "https:") return true;
+        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(),
     /**