@m6d/cortex-cli 0.21.0 → 0.22.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@m6d/cortex-cli",
-    "version": "0.21.0",
+    "version": "0.22.0",
     "description": "Scaffold Cortex projects and manage a Cortex deployment",
     "license": "MIT",
     "type": "module",

package/src/contracts/client-tools/index.ts

@@ -60,6 +60,27 @@ export type LocationResult = LatLng & { accuracy?: number };
 
 export type RequestLocationOutcome = ClientToolOutcome<LocationResult>;
 
+/**
+ * Asks the end user to connect their own account to an MCP server that signs
+ * in each end user. Its call is stamped with where the sign-in starts
+ * (`ConnectAccountBinding` in the wire contract).
+ */
+export const CONNECT_ACCOUNT_TOOL = "connectAccount";
+
+/** The model's arguments: the MCP server to connect, by name. */
+export type ConnectAccountInput = { server: string };
+
+/**
+ * `completed` once the account is connected with the access it needs,
+ * `cancelled` when the end user said Not now or cancelled the sign-in,
+ * `failed` when the sign-in came back without that access, or ran out
+ * first.
+ */
+export type ConnectAccountOutcome = ClientToolOutcome<never>;
+
+/** How long a sign-in Cortex starts stays open, and so how long the widget waits for its connection. */
+export const SIGN_IN_TTL_MS = 10 * 60 * 1000;
+
 /**
  * Parse a `message` event into a handshake, or null when the origin doesn't
  * match the tool's `embedOrigin` or the payload isn't a well-formed handshake.

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

@@ -10,6 +10,7 @@ export {
     canCarrySecret,
     egressAllowedHosts,
     isEgressAllowedHost,
+    isLoopback,
     isPrivateAddress,
     normalizeHost,
 } from "./url";

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

@@ -79,7 +79,7 @@ export function isPrivateAddress(address: string) {
 }
 
 /** Loopback by its normalized spelling: `[::1]` arrives from a URL without its brackets. */
-function isLoopback(hostname: string) {
+export function isLoopback(hostname: string) {
     return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "::1";
 }
 

package/src/contracts/management/procedures.generated.ts

@@ -233,6 +233,7 @@ export const managementProcedureKinds = {
   "credentials.delete": "mutation",
   "credentials.list": "query",
   "credentials.names": "query",
+  "credentials.rotateKey": "mutation",
   "credentials.update": "mutation",
   "datasetHosts.create": "mutation",
   "datasetHosts.delete": "mutation",
@@ -257,6 +258,8 @@ export const managementProcedureKinds = {
   "manifests.sync": "mutation",
   "mcpServers.create": "mutation",
   "mcpServers.delete": "mutation",
+  "mcpServers.detectSignIn": "query",
+  "mcpServers.disconnect": "mutation",
   "mcpServers.get": "query",
   "mcpServers.list": "query",
   "mcpServers.publish": "mutation",
@@ -885,7 +888,7 @@ export type ManagementProcedures = {
     output: {
       id: string;
       actorId: string;
-      credentialKind: "session" | "managementKey" | "operatorToken" | "system";
+      credentialKind: "session" | "managementKey" | "operatorToken" | "oauthToken" | "system";
       credentialId: string | null;
       entityType: string;
       entityId: string;
@@ -902,6 +905,7 @@ export type ManagementProcedures = {
         displayName: Partial<Record<"en" | "ar", string>>;
         fingerprint: string;
       } | null;
+      oauthClientName: string | null;
       before: unknown;
       after: unknown;
     };
@@ -922,7 +926,7 @@ export type ManagementProcedures = {
       items: Array<{
         id: string;
         actorId: string;
-        credentialKind: "session" | "managementKey" | "operatorToken" | "system";
+        credentialKind: "session" | "managementKey" | "operatorToken" | "oauthToken" | "system";
         credentialId: string | null;
         entityType: string;
         entityId: string;
@@ -939,6 +943,7 @@ export type ManagementProcedures = {
           displayName: Partial<Record<"en" | "ar", string>>;
           fingerprint: string;
         } | null;
+        oauthClientName: string | null;
       }>;
       /** Every row the caller may see, ignoring the search and filters. */
       count: number;
@@ -1134,15 +1139,17 @@ export type ManagementProcedures = {
       name: string;
     };
   };
-  /** Create a named credential, with a display name (a text per locale, `{}` for none), over a stored secret: `static` presents the secret's value; `oauth2-client-credentials` exchanges it, as the client secret of `clientId`, for a bearer at `tokenUrl` (https, or http on loopback or on a host `EGRESS_ALLOWED_HOSTS` admits). A credential's name and kind never change. Needs `secrets:write` too: whatever presents the credential sends its secret. */
+  /** Create a credential over a stored secret, with a display name (`{}` for none). `static` presents the secret's value; `oauth2-client-credentials` gets a bearer at `tokenUrl` (https) as `clientId`, by `authMethod`: `client_secret_basic` sends the secret; `private_key_jwt` signs with a key Cortex generates into a new secret named `secretName`, which nothing else may compose or rewrite (`signing_key_secret`), and needs `issuer` and an engine public URL to publish its key under (`jwks_unavailable`); `none` is a public app for MCP sign-in at `issuer`, with no secret. `issuer` is the authorization server's exact identifier. Name, kind and auth method never change. Needs `secrets:write`. */
   "credentials.create": {
     input: {
       displayName: Partial<Record<"en" | "ar", string>>;
       kind: "static" | "oauth2-client-credentials";
+      authMethod: "client_secret_basic" | "private_key_jwt" | "none";
       secretName: string;
       tokenUrl: string;
       clientId: string;
       scope: string;
+      issuer: string;
       /** A name: lowercase letters, digits, and single hyphens. */
       name: string;
     };
@@ -1151,10 +1158,12 @@ export type ManagementProcedures = {
       name: string;
       displayName: Partial<Record<"en" | "ar", string>>;
       kind: "static" | "oauth2-client-credentials";
-      secretName: string;
+      authMethod: "client_secret_basic" | "private_key_jwt" | "none" | null;
+      secretName: string | null;
       tokenUrl: string | null;
       clientId: string | null;
       scope: string | null;
+      issuer: string | null;
       createdAt: string;
       updatedAt: string;
     };
@@ -1169,15 +1178,17 @@ export type ManagementProcedures = {
       name: string;
       displayName: Partial<Record<"en" | "ar", string>>;
       kind: "static" | "oauth2-client-credentials";
-      secretName: string;
+      authMethod: "client_secret_basic" | "private_key_jwt" | "none" | null;
+      secretName: string | null;
       tokenUrl: string | null;
       clientId: string | null;
       scope: string | null;
+      issuer: string | null;
       createdAt: string;
       updatedAt: string;
     };
   };
-  /** List credentials with pagination and search: the name tools, dataset hosts and triggers reference, its display name, its kind, the secret it composes, and how many rows name it with the first few (`usedBy`). */
+  /** List credentials with pagination and search: the name tools, dataset hosts and triggers reference, its display name, its kind and auth method, the secret it composes, how many rows name it with the first few (`usedBy`), and, for a `private_key_jwt` one, the URL of its public key set (`jwksUrl`, null without an engine public URL), which its authorization server is registered with, and the `kid` of the key it signs with now (null for any other). */
   "credentials.list": {
     input: {
       pageIndex?: number;
@@ -1190,10 +1201,12 @@ export type ManagementProcedures = {
         name: string;
         displayName: Partial<Record<"en" | "ar", string>>;
         kind: "static" | "oauth2-client-credentials";
-        secretName: string;
+        authMethod: "client_secret_basic" | "private_key_jwt" | "none" | null;
+        secretName: string | null;
         tokenUrl: string | null;
         clientId: string | null;
         scope: string | null;
+        issuer: string | null;
         createdAt: string;
         updatedAt: string;
         usedBy: {
@@ -1205,6 +1218,8 @@ export type ManagementProcedures = {
             id: string;
           }>;
         };
+        jwksUrl: string | null;
+        kid: string | null;
       }>;
       /** Every row the caller may see, ignoring the search and filters. */
       count: number;
@@ -1212,25 +1227,47 @@ export type ManagementProcedures = {
       filteredCount: number;
     };
   };
-  /** Each credential's name and display name, in name order, for a picker. `present`: what a tool, dataset host, webhook or trigger run may present upstream (every credential but a trigger's fire credential). `fire`: what a trigger may be fired with (static credentials). */
+  /** Each credential's name and display name, in name order, for a picker. `present`: what a tool, dataset host, webhook or trigger run may present upstream (every credential but a trigger's fire credential). `fire`: what a trigger may be fired with (static credentials). `signIn`: what an MCP server's sign-in may present as its pre-registered app (OAuth2 client credentials ones naming their `issuer`). */
   "credentials.names": {
     input: {
-      use: "present" | "fire";
+      use: "present" | "fire" | "signIn";
     };
     output: Array<{
       name: string;
       displayName: Partial<Record<"en" | "ar", string>>;
     }>;
   };
-  /** Change a credential's display name, the secret it composes and, for an OAuth2 one, its token URL, client id and scope. Applies to the next call of every tool, dataset host and trigger naming it. Changing the secret or the token URL needs `secrets:write` too (`secret_binding_forbidden`): either sends a stored secret somewhere new. */
+  /** Replace a `private_key_jwt` credential's signing key with a new one, under a new `kid`, rewriting its secret (`no_signing_key` for any other credential). Its key set serves only the new public key at once, so assertions verify again once the authorization server refetches it. */
+  "credentials.rotateKey": {
+    input: {
+      id: string;
+    };
+    output: {
+      id: string;
+      name: string;
+      displayName: Partial<Record<"en" | "ar", string>>;
+      kind: "static" | "oauth2-client-credentials";
+      authMethod: "client_secret_basic" | "private_key_jwt" | "none" | null;
+      secretName: string | null;
+      tokenUrl: string | null;
+      clientId: string | null;
+      scope: string | null;
+      issuer: string | null;
+      createdAt: string;
+      updatedAt: string;
+    };
+  };
+  /** Change a credential's display name, the secret it composes and, for an OAuth2 one, its token URL, client id, scope and issuer. Applies to the next call of every tool, dataset host and trigger naming it. Changing the secret, the token URL or the issuer needs `secrets:write` too (`secret_binding_forbidden`): each sends a stored secret somewhere new. A `private_key_jwt` one keeps its secret, which holds its key, like its kind and auth method (`kind_locked`). */
   "credentials.update": {
     input: {
       displayName: Partial<Record<"en" | "ar", string>>;
       kind: "static" | "oauth2-client-credentials";
+      authMethod: "client_secret_basic" | "private_key_jwt" | "none";
       secretName: string;
       tokenUrl: string;
       clientId: string;
       scope: string;
+      issuer: string;
       id: string;
     };
     output: {
@@ -1238,10 +1275,12 @@ export type ManagementProcedures = {
       name: string;
       displayName: Partial<Record<"en" | "ar", string>>;
       kind: "static" | "oauth2-client-credentials";
-      secretName: string;
+      authMethod: "client_secret_basic" | "private_key_jwt" | "none" | null;
+      secretName: string | null;
       tokenUrl: string | null;
       clientId: string | null;
       scope: string | null;
+      issuer: string | null;
       createdAt: string;
       updatedAt: string;
     };
@@ -2178,6 +2217,11 @@ export type ManagementProcedures = {
             value: string;
           };
         }>;
+        signIn?: {
+          connects: "shared" | "endUser";
+          scope?: string;
+          credential?: string;
+        };
         include?: Array<string>;
         exclude?: Array<string>;
         audience: "all" | {
@@ -2185,7 +2229,7 @@ export type ManagementProcedures = {
         } | {
           agents: Array<string>;
         };
-        overridable?: Array<"displayName" | "include" | "exclude" | "headers">;
+        overridable?: Array<"displayName" | "include" | "exclude" | "headers" | "signIn">;
       }>;
       webhooks?: Array<{
         name: string;
@@ -2713,6 +2757,11 @@ export type ManagementProcedures = {
             value: string;
           };
         }>;
+        signIn?: {
+          connects: "shared" | "endUser";
+          scope?: string;
+          credential?: string;
+        };
         include?: Array<string>;
         exclude?: Array<string>;
         audience: "all" | {
@@ -2720,7 +2769,7 @@ export type ManagementProcedures = {
         } | {
           agents: Array<string>;
         };
-        overridable?: Array<"displayName" | "include" | "exclude" | "headers">;
+        overridable?: Array<"displayName" | "include" | "exclude" | "headers" | "signIn">;
       }>;
       webhooks?: Array<{
         name: string;
@@ -2816,7 +2865,30 @@ export type ManagementProcedures = {
       id: string;
     };
   };
-  /** One MCP server by id with its url, headers, tool filters, and sharing. */
+  /** Find how Cortex would sign in to the MCP server with OAuth, from its metadata: the authorization server's issuer, the method Cortex would use (`preRegistered`, `clientIdDocument`, `dynamicRegistration`, or null for none), the scopes on offer, whether PKCE with S256 is supported, and the resource tokens are for. A pre-registered app for another issuer is refused as `sign_in_issuer_mismatch`. */
+  "mcpServers.detectSignIn": {
+    input: {
+      id: string;
+    };
+    output: {
+      issuer: string;
+      method: "preRegistered" | "clientIdDocument" | "dynamicRegistration" | null;
+      scopes: Array<string>;
+      pkce: boolean;
+      resource: string;
+    };
+  };
+  /** Forget every connection Cortex holds to the MCP server: the shared one, or every end user's. Its turns report it not connected until someone signs in again. The tokens are not revoked at the authorization server. */
+  "mcpServers.disconnect": {
+    input: {
+      id: string;
+    };
+    output: {
+      id: string;
+      name: string;
+    };
+  };
+  /** One MCP server by id with its url, headers, sign-in, tool filters, and sharing; its shared connection, never its tokens, with `stepUp` once its server refused a call for lack of scope (the scopes it lacks, and whether a sign-in may still ask for them); how many end users are connected or must sign in again; and `signInUrl`, where a browser form-posts an operator token and the server's id to connect it (null while the engine or the console has no public URL). */
   "mcpServers.get": {
     input: {
       id: string;
@@ -2855,6 +2927,11 @@ export type ManagementProcedures = {
           value: string;
         };
       }>;
+      signIn: {
+        connects: "shared" | "endUser";
+        scope?: string;
+        credential?: string;
+      } | null;
       include: Array<string>;
       exclude: Array<string>;
       status: "draft" | "published" | "disabled";
@@ -2881,6 +2958,22 @@ export type ManagementProcedures = {
         type: "string" | "number" | "boolean";
         computed: boolean;
       }>;
+      connection: {
+        status: "connected" | "needs_scope" | "broken";
+        issuer: string;
+        scope: string;
+        expiresAt: string | null;
+        updatedAt: string;
+        stepUp: {
+          missing: string;
+          grantable: boolean;
+        } | null;
+      } | null;
+      endUsers: {
+        connected: number;
+        broken: number;
+      };
+      signInUrl: string | null;
     };
   };
   /** List MCP servers with pagination and search. */
@@ -3010,7 +3103,7 @@ export type ManagementProcedures = {
       unchanged: boolean;
     };
   };
-  /** Update an MCP server's draft: which of its tools agents may call (`include`, empty for every tool, and `exclude`, tool names as the server spells them). Saved as a draft; call publish to make it live. The url and headers (each with a prefix and its value from a credential, the run token, a variable or a constant) apply live without a publish. */
+  /** Update an MCP server's draft: which of its tools agents may call (`include`, empty for every tool, and `exclude`, tool names as the server spells them). Saved as a draft; call publish to make it live. The url, headers (each with a prefix and its value from a credential, the run token, a variable or a constant) and `signIn` apply live without a publish. `signIn` (null for none) has Cortex sign in with OAuth: `connects` is `shared` (an operator connects once for every agent) or `endUser` (each end user connects their own), `scope` what to ask for, and `credential` names the app registered with the authorization server beforehand, an `oauth2-client-credentials` credential naming its `issuer`. A server that signs in declares no Authorization header. */
   "mcpServers.update": {
     input: {
       url: string;
@@ -3030,6 +3123,11 @@ export type ManagementProcedures = {
           value: string;
         };
       }>;
+      signIn: {
+        connects: "shared" | "endUser";
+        scope?: string;
+        credential?: string;
+      } | null;
       include: Array<string>;
       exclude: Array<string>;
       id: string;
@@ -3754,7 +3852,7 @@ export type ManagementProcedures = {
       displayName: Partial<Record<"en" | "ar", string>>;
     }>;
   };
-  /** Replace a secret's value in place. */
+  /** Replace a secret's value in place; a `private_key_jwt` credential's generated key is refused (`signing_key_secret`), since only `credentials.rotateKey` rewrites it. */
   "secrets.rotate": {
     input: {
       id: string;

package/src/contracts/manifest/index.ts

@@ -1196,24 +1196,68 @@ export const mcpToolNamesSchema = z
     )
     .max(200);
 
-const manifestMcpServerSchema = z.strictObject({
-    /** Prefixes every tool the server contributes: scripts call `tools.<name>_<tool>()`. */
-    name: identifierSchema,
-    displayName: displayNameSchema.default({}),
-    url: upstreamUrlSchema,
-    headers: declaredHeadersSchema(
-        presentedHeaderSchema.refine(
-            (name) => !mcpTransportHeaders.has(name.toLowerCase()),
-            "a header the MCP transport sets",
-        ),
-        headerSourceSchema,
-    ),
-    /** The server's own tool names to offer; empty offers every tool. */
-    include: mcpToolNamesSchema.default([]),
-    exclude: mcpToolNamesSchema.default([]),
-    audience: audienceSchema,
-    overridable: overridable(["displayName", "include", "exclude", "headers"]),
+/** Who holds an MCP server's sign-in: one connection an operator makes for every agent, or one per end user of each agent. */
+export const MCP_CONNECTION_OWNERS = ["shared", "endUser"] as const;
+
+/**
+ * How Cortex signs in to an MCP server that takes OAuth: who connects, the
+ * scope it asks for (absent, what the server advertises), and, for an
+ * authorization server that takes neither a client ID document nor dynamic
+ * registration, the credential holding the app registered there beforehand:
+ * an OAuth2 client credentials one naming that server as its issuer.
+ */
+export const mcpSignInSchema = z.strictObject({
+    connects: z.enum(MCP_CONNECTION_OWNERS),
+    scope: z.string().trim().min(1).max(1_000).optional(),
+    credential: nameSchema.optional(),
 });
+export type McpSignIn = z.infer<typeof mcpSignInSchema>;
+
+/**
+ * The index of the Authorization header a server that signs in declares
+ * beside its sign-in, whose token travels under that header; -1 when it
+ * signs in without one, or declares one without signing in.
+ */
+export function authorizationBesideSignIn(server: {
+    signIn?: McpSignIn | null;
+    headers: ReadonlyArray<{ header: string }>;
+}) {
+    return server.signIn
+        ? server.headers.findIndex((entry) => entry.header.toLowerCase() === "authorization")
+        : -1;
+}
+
+const manifestMcpServerSchema = z
+    .strictObject({
+        /** Prefixes every tool the server contributes: scripts call `tools.<name>_<tool>()`. */
+        name: identifierSchema,
+        displayName: displayNameSchema.default({}),
+        url: upstreamUrlSchema,
+        headers: declaredHeadersSchema(
+            presentedHeaderSchema.refine(
+                (name) => !mcpTransportHeaders.has(name.toLowerCase()),
+                "a header the MCP transport sets",
+            ),
+            headerSourceSchema,
+        ),
+        /** Absent, every request carries only its headers. */
+        signIn: mcpSignInSchema.optional(),
+        /** The server's own tool names to offer; empty offers every tool. */
+        include: mcpToolNamesSchema.default([]),
+        exclude: mcpToolNamesSchema.default([]),
+        audience: audienceSchema,
+        overridable: overridable(["displayName", "include", "exclude", "headers", "signIn"]),
+    })
+    .superRefine((server, context) => {
+        const index = authorizationBesideSignIn(server);
+        if (index >= 0) {
+            context.addIssue({
+                code: "custom",
+                path: ["headers", index, "header"],
+                message: "the sign-in's token travels under Authorization",
+            });
+        }
+    });
 export type ManifestMcpServer = z.input<typeof manifestMcpServerSchema>;
 
 /**

package/src/contracts/server/index.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { REQUEST_LOCATION_TOOL } from "../client-tools/index";
+import { CONNECT_ACCOUNT_TOOL, REQUEST_LOCATION_TOOL } from "../client-tools/index";
 import { backendErrorSchema } from "../errors/index";
 import { pendingApprovalSchema, TRIGGER_ANSWER_TOOL_NAME } from "../triggers/index";
 import { isRecord, readJsonPointer } from "../json/index";
@@ -139,6 +139,7 @@ export const BUILT_IN_TOOL_NAMES = [
     "searchRegistries",
     "searchThreadHistory",
     REQUEST_LOCATION_TOOL,
+    CONNECT_ACCOUNT_TOOL,
     TRIGGER_ANSWER_TOOL_NAME,
 ] as const;
 

package/src/contracts/wire/index.ts

@@ -164,6 +164,47 @@ export type ClientToolBinding = {
     embedOrigin: string;
 };
 
+/**
+ * How the widget connects an end user's account for a `connectAccount`
+ * call, stamped on the call: where the engine starts a sign-in, at the URL
+ * browsers reach it, the agent it is for, and each server the call may
+ * name, by name: its display name, and the scope it still needs when the
+ * account is connected but lacks access.
+ */
+export type ConnectAccountBinding = {
+    startUrl: string;
+    agent: string;
+    servers: Record<string, { displayName: Partial<LocalizedText>; scope?: string }>;
+};
+
+/**
+ * Response of `GET /connections/:server?call=<toolCallId>`: where the
+ * caller's own account stands with the agent's MCP server of that name, for
+ * the card of that `connectAccount` call. `connected` with all a sign-in
+ * may ask for; `pending` while it is not connected, or lacks access a
+ * sign-in may still grant; `refused` once the card's own sign-in came back
+ * without it, or no sign-in may ask again.
+ */
+export type AccountConnection = {
+    status: "connected" | "pending" | "refused";
+};
+
+/**
+ * The form `POST /oauth/start` takes, posted into the window a sign-in runs
+ * in with its bearer in the body, so no link can start one: the console's
+ * operator token and the server's id for the shared connection.
+ */
+export type SharedSignInStart = { operatorToken: string; mcpServerId: string };
+
+/** An end user's own start: their token, their agent, the server's name, and the `connectAccount` call it answers. */
+export type EndUserSignInStart = {
+    token: string;
+    agent: string;
+    server: string;
+    threadId: string;
+    toolCallId: string;
+};
+
 /**
  * What Cortex offers this agent's clients, fetched once at widget startup.
  * The widget hides UI for anything absent; Cortex enforces each.
@@ -263,6 +304,8 @@ export type ToolCallMetadata = {
     answeredBy?: "client";
     /** Set beside `answeredBy` on a call of a client tool with an embedded page: the widget mounts the embed for it. */
     embed?: ClientToolBinding;
+    /** Set beside `answeredBy` on a `connectAccount` call: the widget starts the sign-in with it. */
+    connect?: ConnectAccountBinding;
 };
 
 /** The `metadata.cortex` a tool call carries, when Cortex stamped one. */

package/src/scaffold/files.ts

@@ -28,7 +28,7 @@ import { applyPorts, type Ports } from "@/scaffold/ports";
  * `@m6d/cortex` range below are stamped by scripts/sync-package-versions.ts
  * before the CLI publishes, so a scaffold pins what was current then.
  */
-const CORTEX_VERSION = "0.20.0";
+const CORTEX_VERSION = "0.21.0";
 
 /** This machine as Cortex's containers name it: the one private host the stack's egress policy admits. */
 export const DOCKER_HOST = "host.docker.internal";
@@ -147,7 +147,7 @@ function packageJson({ name, datasets, setup }: Project) {
                 verify: "bun run format:check && bun run lint && bun run spellcheck && bun run check && bun run audit",
             },
             dependencies: {
-                "@m6d/cortex": "~0.8.0",
+                "@m6d/cortex": "~0.9.0",
                 // drizzle 1.0 is in beta; this is the build `@m6d/cortex/drizzle` is tested against.
                 ...(datasets ? { "drizzle-orm": "1.0.0-beta.15-859cf75" } : {}),
                 hono: "^4.12.3",