@m6d/cortex-cli 0.12.1 → 0.14.0

package/src/contracts/{runtime → datasets}/datasets.ts

@@ -11,10 +11,15 @@ import { isRecord } from "../json";
  */
 
 export const DATASET_IDENTIFIER_PATTERN = /^[a-zA-Z][a-zA-Z0-9_]*$/;
+/** The longest dataset or host name. */
+export const DATASET_IDENTIFIER_MAX = 64;
 /** `column` on the dataset queried, or `relation.relation.column` along declared relations. */
 export const DATASET_COLUMN_REF_PATTERN = /^[a-zA-Z][a-zA-Z0-9_]*(\.[a-zA-Z][a-zA-Z0-9_]*)*$/;
 
-export const datasetIdentifierSchema = z.string().regex(DATASET_IDENTIFIER_PATTERN).max(64);
+export const datasetIdentifierSchema = z
+    .string()
+    .regex(DATASET_IDENTIFIER_PATTERN)
+    .max(DATASET_IDENTIFIER_MAX);
 export const datasetColumnRefSchema = z.string().regex(DATASET_COLUMN_REF_PATTERN).max(256);
 
 export const DATASET_COLUMN_TYPES = ["string", "number", "boolean", "date"] as const;
@@ -355,46 +360,6 @@ export const datasetResultSchema = z.object({
 });
 export type DatasetResult = z.infer<typeof datasetResultSchema>;
 
-export const DATASET_ERROR_KINDS = [
-    "invalid_query",
-    "unsupported",
-    "forbidden",
-    "timeout",
-    "internal",
-] as const;
-export type DatasetErrorKind = (typeof DATASET_ERROR_KINDS)[number];
-
-/** The HTTP status each error kind travels under, both from a host and from the server's own refusals. */
-export const DATASET_ERROR_STATUS = {
-    invalid_query: 400,
-    unsupported: 400,
-    forbidden: 403,
-    timeout: 504,
-    internal: 500,
-} as const satisfies Record<DatasetErrorKind, number>;
-
-export const datasetErrorSchema = z.object({
-    error: z.object({
-        kind: z.enum(DATASET_ERROR_KINDS),
-        detail: z.string().max(512),
-    }),
-});
-export type DatasetError = z.infer<typeof datasetErrorSchema>;
-
-/**
- * A dataset host as an agent's published configuration carries it: the
- * datasets the agent exposes, already the published manifest's definitions,
- * and which of them ride in every turn. The Control Center runs the queries
- * for a host it registered, so the server needs no URL or credential here.
- */
-export const datasetHostDeclarationSchema = z.object({
-    name: datasetIdentifierSchema,
-    manifestVersion: datasetManifestSchema.shape.version,
-    datasets: z.array(datasetDefinitionSchema).max(500),
-    pinned: z.array(datasetIdentifierSchema).max(50).default([]),
-});
-export type DatasetHostDeclaration = z.infer<typeof datasetHostDeclarationSchema>;
-
 /** The definitions a query may reach, by dataset name. */
 export type DatasetCatalog = ReadonlyMap<string, DatasetDefinition>;
 
@@ -659,7 +624,7 @@ export function boundDatasetResult(
 /**
  * Every way a query can be wrong given the catalog, as messages the model
  * can act on; an empty list means the host will understand it. Checked
- * before anything leaves the server, so a host can trust the shape and only
+ * before anything leaves Cortex, so a host can trust the shape and only
  * has to translate.
  */
 export function validateDatasetQuery(catalog: DatasetCatalog, query: DatasetQuery) {

package/src/contracts/datasets/index.ts

@@ -0,0 +1,3 @@
+export * from "./datasets";
+export * from "./dataset-sql";
+export * from "./dataset-sql-guide";

package/src/contracts/egress-policy/index.ts

@@ -0,0 +1,16 @@
+/*
+ * The egress policy as far as no socket is needed: which addresses are
+ * private, which hosts the deployment admits, which URLs a secret may travel
+ * to, and the redaction of the credentials an answer echoes back. Free of
+ * node modules, so a browser bundle judges a URL the same way Cortex does.
+ * Cortex's `guardedFetch` enforces the rest at the socket.
+ */
+
+export {
+    canCarrySecret,
+    egressAllowedHosts,
+    isEgressAllowedHost,
+    isPrivateAddress,
+    normalizeHost,
+} from "./url";
+export { credentialForms, redactedUrl, scrubAnswer, scrubCredentialStrings } from "./scrub";

package/src/contracts/{egress → egress-policy}/scrub.ts

@@ -25,11 +25,11 @@ export function credentialForms(value: string) {
 }
 
 /**
- * The one boundary every upstream body crosses before it is stored or sent
- * on, in cc and the server alike: U+0000 is dropped from keys and values
- * because Postgres refuses it in text and jsonb on both cc's execution log
- * and the server's transcript, then the credentials the request presented
- * are redacted. Dropping first, on the patterns as well, means a credential
+ * The one boundary every upstream body crosses before Cortex stores it or
+ * sends it on: U+0000 is dropped from keys and values because Postgres
+ * refuses it in text and jsonb, in the tool execution log and the thread's
+ * transcript alike, then the credentials the request presented are
+ * redacted. Dropping first, on the patterns as well, means a credential
  * an upstream spelled with U+0000 inside it still matches; redacting first
  * would let the strip reassemble it.
  */
@@ -59,3 +59,32 @@ export function scrubCredentialStrings(value: unknown, credentials: string[]): u
         ]),
     );
 }
+
+/**
+ * What a party answered (a manifest, a tool it lists, the values it fills),
+ * fit to store or show a model: the credentials it was sent redacted from
+ * every string in it, or null when one of its `names` carries one, since a
+ * redacted identifier would name something else. Functions in it, such as a
+ * tool's executor, stay as they are.
+ */
+export function scrubAnswer<T>(answer: T, credentials: string[], names: readonly string[] = []) {
+    const carries = names.some((name) => {
+        const plain = name.replaceAll("\u0000", "");
+        return scrubCredentialStrings(plain, credentials) !== plain;
+    });
+    return carries ? null : (scrubCredentialStrings(answer, credentials) as T);
+}
+
+/**
+ * A URL as it may be logged or shown: its origin and path, without the
+ * userinfo, query or fragment a secret can ride in. Text that does not
+ * parse as a URL keeps what comes before its query or fragment.
+ */
+export function redactedUrl(raw: string) {
+    try {
+        const url = new URL(raw);
+        return `${url.origin}${url.pathname}`;
+    } catch {
+        return raw.split(/[?#]/)[0] ?? raw;
+    }
+}

package/src/contracts/{egress → egress-policy}/url.ts

@@ -2,7 +2,7 @@
  * The egress policy as far as a URL alone can tell: which addresses are
  * private, which hosts the deployment admits, and where a secret may be
  * sent. Pure and free of node modules, so a browser bundle judges a URL the
- * same way the server does.
+ * same way Cortex does.
  */
 
 type Range = { first: number; last: number };
@@ -33,8 +33,8 @@ function isBlockedV4(address: string) {
 }
 
 /**
- * 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
+ * The IPv4 address in the last 32 bits of an 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) {
@@ -45,15 +45,28 @@ function mappedV4(mapped: string) {
     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);
+/**
+ * The IPv4 address an IPv6 one reaches, for the prefixes where only the
+ * address may follow: IPv4-mapped (`::ffff:0:0/96`) and NAT64's well-known
+ * `64:ff9b::/96`. `undefined` for any other IPv6 address.
+ */
+function embeddedV4(address: string) {
+    for (const prefix of ["::ffff:", "64:ff9b::"]) {
+        if (address.startsWith(prefix)) return mappedV4(address.slice(prefix.length));
     }
+    return undefined;
+}
+
+function isBlockedV6(address: string) {
+    const normalized = normalizeHost(address);
+    const embedded = embeddedV4(normalized);
+    if (embedded !== undefined) return embedded === null || isBlockedV4(embedded);
     return (
         normalized === "::" ||
         normalized === "::1" ||
+        // NAT64's local-use /48: the operator may embed the IPv4 address at
+        // any RFC 6052 prefix length, so no position can be read reliably.
+        normalized.startsWith("64:ff9b:1:") ||
         normalized.startsWith("fc") ||
         normalized.startsWith("fd") ||
         /^fe[89ab]/.test(normalized)
@@ -115,7 +128,7 @@ export function isEgressAllowedHost(hostname: string, allowed = egressAllowedHos
  * http to loopback, or over plain http to a host the policy admits. Pass
  * `allowed` 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): `[]` admits nothing.
+ * URL the browser or the CLI dials, not Cortex): `[]` admits nothing.
  */
 export function canCarrySecret(url: string, allowed = egressAllowedHosts()) {
     try {

package/src/contracts/errors/index.ts

@@ -0,0 +1,38 @@
+import { z } from "zod";
+
+/*
+ * The one error envelope a backend answers Cortex with, in the dataset
+ * protocol and the server protocol alike: `{ error: { kind, detail } }`
+ * under the kind's HTTP status, or a closer one HTTP defines (401 for a
+ * wrong server key, 404 for an unknown tool, 413 for a body too large). The
+ * detail reaches the model.
+ */
+
+export const BACKEND_ERROR_KINDS = [
+    "invalid_request",
+    "unsupported",
+    "forbidden",
+    "timeout",
+    "internal",
+] as const;
+export type BackendErrorKind = (typeof BACKEND_ERROR_KINDS)[number];
+
+/** The HTTP status each kind travels under. */
+export const BACKEND_ERROR_STATUS = {
+    invalid_request: 400,
+    unsupported: 400,
+    forbidden: 403,
+    timeout: 504,
+    internal: 500,
+} as const satisfies Record<BackendErrorKind, number>;
+
+/** The longest detail Cortex accepts; a backend cuts a longer one down to it. */
+export const BACKEND_ERROR_DETAIL_MAX = 512;
+
+export const backendErrorSchema = z.object({
+    error: z.object({
+        kind: z.enum(BACKEND_ERROR_KINDS),
+        detail: z.string().max(BACKEND_ERROR_DETAIL_MAX),
+    }),
+});
+export type BackendError = z.infer<typeof backendErrorSchema>;

package/src/contracts/json/index.ts

@@ -7,6 +7,11 @@ export function isRecord(value: unknown): value is Record<string, unknown> {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
+/** `value` when it is a record, else undefined. */
+export function asRecord(value: unknown) {
+    return isRecord(value) ? value : undefined;
+}
+
 /**
  * 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