toolroll 0.9.45 → 0.9.46

package/dist/mcp-http.d.ts

@@ -11,7 +11,8 @@
  */
 import type { IncomingMessage, ServerResponse } from "node:http";
 import type { Store } from "./store.js";
-import { type RunOperateAs } from "./mcp-person.js";
+import { type Person, type RunOperateAs } from "./mcp-person.js";
+import { type Admission } from "./request-budget.js";
 export type McpHttpOptions = {
     store: Store;
     clock: () => Date;
@@ -20,7 +21,11 @@ export type McpHttpOptions = {
     evidenceRoot?: string;
     /** The console's own sign-in for an `so_` bearer: the address's tries, expiry, revocation, a removed account. */
     signedIn: (request: IncomingMessage) => boolean;
+    /** Where an MCP client finds how to sign in (mcp-oauth.ts), named on a 401; null when this address offers none. */
+    resourceMetadata?: (request: IncomingMessage) => string | null;
     /** Runs a person's command on the server (operate.ts); resolved from operate.ts when not injected. */
     runAs?: RunOperateAs;
+    /** A person token's request budget (request-budget.ts), charged once per request before its body is read. */
+    admit?: (person: Person) => Admission;
 };
 export declare function createMcpHttp(options: McpHttpOptions): (request: IncomingMessage, response: ServerResponse) => Promise<void>;

package/dist/mcp-http.js

@@ -10,10 +10,12 @@
  * Host check runs before this route. A revoked or expired token answers 401 on its next request.
  */
 import { PACKAGE_VERSION } from "./version.js";
-import { parseApiToken, secretMatches } from "./api-tokens.js";
+import { parseApiToken, secretMatches, tokenLive, tokenProjects } from "./api-tokens.js";
+import { oauthProjects, oauthTokenAllowed, RESOURCE_PATH } from "./mcp-oauth.js";
 import { authenticateCoordinator } from "./coordinator.js";
 import { LEGACY, MAX_REQUEST, META_CAPABILITIES, META_SERVER, META_VERSION, MODERN, TOOLS, UNSUPPORTED_VERSION, callCoordinatorTool, capabilitiesShape, readMessage, shapeResult, toolsPayload, } from "./mcp-core.js";
 import { callPersonTool, personTools } from "./mcp-person.js";
+import { limitWords } from "./request-budget.js";
 /** The most decisions a coordinator credential is remembered to have read (propose_answer needs one). */
 const READ_DECISIONS_KEPT = 200;
 export function createMcpHttp(options) {
@@ -38,15 +40,20 @@ export function createMcpHttp(options) {
             // The secret is checked here too, so this door never rests on how signedIn reads the request.
             if (parsed === null || kept === null || !secretMatches(parsed.secret, kept.secretHash))
                 return null;
-            if (kept.row.revokedAt !== null || Date.parse(kept.row.expiresAt) <= options.clock().getTime())
+            if (!tokenLive(kept.row, options.clock().getTime()))
                 return null;
             const account = store.accountOf(kept.row.account);
             if (account === null || account.revokedAt !== null)
                 return null;
+            // An MCP sign-in's token: only while its access is fresh, and only in the projects the person chose (mcp-oauth.ts).
+            if (!oauthTokenAllowed(store, kept.row.id, RESOURCE_PATH, options.clock()))
+                return null;
+            const granted = oauthProjects(store, kept.row.id);
+            const projects = tokenProjects(tokenProjects(account.projects, kept.row.projects), granted);
             return {
                 kind: "person",
                 person: {
-                    principal: { kind: "person", account: kept.row.account, generation: account.generation, scope: kept.row.access, tokenId: kept.row.id, projects: account.projects === null ? null : [...account.projects] },
+                    principal: { kind: "person", account: kept.row.account, generation: account.generation, scope: kept.row.access, tokenId: kept.row.id, projects },
                     role: account.role,
                     tokenName: kept.row.name,
                 },
@@ -100,7 +107,18 @@ export function createMcpHttp(options) {
             return refuse(response, 403, "browser requests are refused — connect an MCP client with your API token");
         const caller = callerOf(request);
         if (caller === null) {
-            return refuse(response, 401, "sign in with your API token (Authorization: Bearer so_…) or a coordinator credential — passwords and cookies are not accepted here", { "www-authenticate": 'Bearer realm="toolroll-mcp"' });
+            const metadata = options.resourceMetadata?.(request) ?? null;
+            return refuse(response, 401, "sign in with your API token (Authorization: Bearer so_…) or a coordinator credential — passwords and cookies are not accepted here", { "www-authenticate": `Bearer realm="toolroll-mcp"${metadata === null ? "" : `, resource_metadata="${metadata}"`}` });
+        }
+        // A person's token is counted once per request, notifications included; a coordinator keeps its own proposal limit.
+        if (caller.kind === "person" && options.admit !== undefined) {
+            const admitted = options.admit(caller.person);
+            if (!admitted.ok && admitted.status === 503)
+                return refuse(response, 503, "request limits could not be checked; nothing ran — try again shortly");
+            if (!admitted.ok) {
+                request.resume();
+                return send(response, 429, { jsonrpc: "2.0", id: null, error: { code: -32000, message: limitWords(admitted.limit, admitted.retryAfter), data: { limit: admitted.limit, retryAfter: admitted.retryAfter } } }, { "retry-after": String(admitted.retryAfter) });
+            }
         }
         if (!/^application\/json\s*(;|$)/i.test(request.headers["content-type"] ?? ""))
             return refuse(response, 415, "send the JSON-RPC message as application/json");

package/dist/mcp-oauth.d.ts

@@ -0,0 +1,82 @@
+/**
+ * MCP sign-in: OAuth 2.1 for /mcp, as the MCP authorization spec describes, so an engineer's MCP client connects
+ * without a pasted token. This console is both the authorization server and the protected resource.
+ *
+ *   /mcp's 401 names /.well-known/oauth-protected-resource/mcp (RFC 9728), which names this console's
+ *   /.well-known/oauth-authorization-server (RFC 8414). A client registers itself (RFC 7591, public clients only),
+ *   sends the person to /oauth/authorize with a S256 PKCE challenge and resource=<origin>/mcp, and trades the code
+ *   at /oauth/token for a short-lived access token and a refresh secret that rotates on every use.
+ *
+ * The person signs in with the console's own sign-in (password or identity provider, unchanged), then consents on
+ * one page: read or act, and which of their projects, confirmed with their password or a fresh provider check, the
+ * same step-up as making an API token. Nothing is granted without that form, its session CSRF value and a same-site
+ * post.
+ *
+ * A grant is an ordinary API token (api-tokens.ts): its access token is `so_<id>_<secret>`, it is listed and revoked
+ * with every other token (console Sessions & tokens, `toolroll tokens`), and /mcp runs it through the same person
+ * path. Its v113 binding (store.oauthGrant) adds what an ordinary token doesn't have: it works only at /mcp, its
+ * access secret lasts an hour, it is tied to the account generation that consented, and it reaches only the projects
+ * chosen (still intersected with the person's live access on every call). Only hashes are kept: of codes, access
+ * secrets and refresh secrets. Approvals, people and policy are never reachable: those have no tool and no scope.
+ */
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { Store } from "./store.js";
+/** How long each piece lives. A code is spent at once; a grant ends after 30 days and the person consents again. */
+export declare const OAUTH_TIMES: {
+    readonly requestMs: number;
+    readonly codeMs: 60000;
+    readonly accessSeconds: 3600;
+    readonly grantDays: 30;
+};
+/** The most sign-ins waiting at once, and registered clients kept. */
+export declare const OAUTH_LIMITS: {
+    readonly requests: 200;
+    readonly requestsPerSource: 20;
+    readonly clients: 500;
+    readonly clientsPerSource: 20;
+};
+export declare const OAUTH_SCOPES: readonly ["read", "act"];
+export declare const RESOURCE_PATH = "/mcp";
+export declare const resourceMetadataUrl: (origin: string) => string;
+/**
+ * Whether an API token may sign in to this request's path now. An ordinary token: yes (its own checks are elsewhere).
+ * An MCP sign-in's token: only at /mcp, only while its access secret is fresh and the account is at the generation
+ * that consented.
+ */
+export declare function oauthTokenAllowed(store: Store, tokenId: string, path: string, now: Date): boolean;
+/** The projects an MCP sign-in's token was granted (the person's live access still applies), or null for an ordinary token. */
+export declare const oauthProjects: (store: Store, tokenId: string) => string[] | null;
+export type OAuthSession = {
+    name: string;
+    role: "approver" | "viewer";
+    csrf: string;
+    /** Signed in with an identity provider: its name, and whether it checked the person in the last ten minutes. */
+    sso: {
+        label: string;
+        fresh: boolean;
+    } | null;
+};
+export type OAuthHttpOptions = {
+    store: Store;
+    clock: () => Date;
+    /** This console's canonical origin for the request (the https public address, or this computer's loopback one); null: no sign-in here. */
+    originOf: (request: IncomingMessage) => string | null;
+    /** Trusted direct peer, or the last hop appended by the console's loopback proxy. */
+    requesterKey: (request: IncomingMessage) => string;
+    /** The browser session signed in by cookie, or null. A bearer never consents. */
+    session: (request: IncomingMessage) => OAuthSession | null;
+    /** A posted form came from a page of this console (its Origin, or Referer, names an allowed host). */
+    sameSite: (request: IncomingMessage) => boolean;
+    /** The step-up: the person's password, or (empty) a fresh identity-provider check. */
+    confirm: (session: OAuthSession, typed: string) => boolean;
+    /** The projects this person may choose: each a project the server knows that they can use now. */
+    projectsFor: (account: string) => string[];
+};
+/**
+ * A redirect a client may register: https anywhere, or http on 127.0.0.1 / [::1] (RFC 8252 §7.3), with no
+ * credentials or fragment.
+ */
+export declare function redirectAllowed(value: string): boolean;
+/** A redirect matches a registered one exactly; on a loopback http address any port does (RFC 8252 §7.3). */
+export declare function redirectMatches(presented: string, registered: readonly string[]): string | null;
+export declare function createOAuthHttp(options: OAuthHttpOptions): (request: IncomingMessage, response: ServerResponse, url: URL) => Promise<boolean>;