@m6d/cortex-cli 0.2.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@m6d/cortex-cli",
-    "version": "0.2.0",
+    "version": "0.3.0",
     "description": "Scaffold and operate Cortex servers",
     "license": "MIT",
     "type": "module",

package/src/contracts/credentials/index.ts

@@ -0,0 +1,166 @@
+import { z } from "zod";
+import { isTlsOrLoopback } from "../egress/url";
+
+export { isTlsOrLoopback };
+
+/*
+ * 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 only over TLS, or to loopback. */
+        tokenUrl: z.url().refine(isTlsOrLoopback, "token URL must be https, or http to loopback"),
+        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_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,
+) {
+    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

@@ -63,22 +63,7 @@ export function isBlockedAddress(address: string) {
     return isIP(address) === 6 ? isBlockedV6(address) : isBlockedV4(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 { isTlsOrLoopback } from "./url";
 
 export function egressError() {
     const error: NodeJS.ErrnoException = new Error("egress blocked");

package/src/contracts/egress/url.ts

@@ -0,0 +1,17 @@
+/**
+ * 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.
+ */
+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;
+    }
+}

package/src/contracts/runtime/sync.ts

@@ -27,14 +27,25 @@ export const tokenUsageSchema = z.object({
     total: tokenCountSchema,
 }) satisfies z.ZodType<TokenUsage>;
 
+const componentNamesSchema = z.array(z.string().min(1).max(128)).max(1_000);
+
 /**
  * What a server offers every agent the Control Center creates for it, sent
  * whole at boot in `server.declare`: the `{{variables}}` its session loader
- * and request context fill, SDK ones included. Agents in the server's own
- * code never appear here; the Control Center is blind to them.
+ * and request context fill, SDK ones included, and the names of the
+ * components its code declares at server level, which reach those agents
+ * too and which the Control Center therefore refuses on its own components.
+ * Agents in the server's own code never appear here; the Control Center is
+ * blind to them.
  */
 export const serverDeclarationSchema = z.object({
     variables: z.array(variableDeclarationSchema),
+    components: z.object({
+        tool: componentNamesSchema,
+        skill: componentNamesSchema,
+        trigger: componentNamesSchema,
+        dataset_host: componentNamesSchema,
+    }),
 });
 export type ServerDeclaration = z.infer<typeof serverDeclarationSchema>;
 

package/src/contracts/runtime/triggers.ts

@@ -129,7 +129,8 @@ export type TriggerDeclaration = z.infer<typeof triggerDeclarationSchema>;
 /**
  * `POST /api/runtime/agents/:agentSlug/triggers/:name/auth`: a server holding a
  * bearer for a cc trigger asks cc whether it is the trigger's secret. Only the
- * hash travels; a positive answer carries the trigger's credential, if any.
+ * hash travels; a positive answer carries the bearer the run acts with, if
+ * the trigger has a credential, resolved by cc (acquired, for an OAuth2 one).
  */
 export const triggerAuthRequestSchema = z.object({
     secretHash: sha256HexSchema,
@@ -140,6 +141,8 @@ export const triggerAuthResponseSchema = z.discriminatedUnion("ok", [
     z.object({
         ok: z.literal(true),
         credential: z.string().nullable(),
+        /** When the bearer stops working, ISO 8601; null for one that does not expire or has no credential. */
+        expiresAt: z.iso.datetime().nullable(),
         /** The bearer was a single-use test secret, now spent: the server must not cache this verdict. */
         oneShot: z.boolean(),
     }),

package/src/scaffold/files.ts

@@ -27,7 +27,7 @@ export type Database = "postgres" | "mssql";
 // sync (scripts/sync-package-versions.ts) restamps it and files.test.ts holds
 // them to that.
 export const DEPENDENCIES = {
-    "@m6d/cortex-server": "~0.2.0",
+    "@m6d/cortex-server": "~0.3.0",
     "@tanstack/ai": "^0.55.0",
     "@tanstack/ai-openai": "^0.22.8",
     hono: "^4.12.3",
@@ -167,9 +167,10 @@ ${on === "" ? "" : `${on}\n`}    agents: {
         assistant: defineAgent({
             systemPrompt: "You are a helpful assistant.",
             // Applications that serve datasets for grouped questions (see the
-            // README's "Dataset hosts"): the host applies its own access rules,
-            // the agent only picks which datasets to expose and pin.
-            // datasetHosts: [{ name: "store", url: "https://store.example/api/datasets", pinned: ["orders"] }],
+            // README's "Dataset hosts"): the host applies its own access rules
+            // under the run's token the list below forwards, the agent only
+            // picks which datasets to expose and pin.
+            // datasetHosts: [{ name: "store", url: "https://store.example/api/datasets", credentials: [{ header: "X-End-User-Token", credential: { kind: "run-token" } }], pinned: ["orders"] }],
         }),
     },