@nylorun/runtime 0.16.0-beta → 0.19.0-beta

package/dist/api/http/routes/vaults.js

@@ -1,16 +1,25 @@
 import { z } from "zod";
-import { CreateCredentialRequestSchema, CreateVaultRequestSchema, RotateCredentialRequestSchema, } from "@nylorun/core/contracts";
-import { CreateCredentialRequest, CreateVaultRequest, CredentialInfo, DeletedResponse, ListCredentialsResponse, ListVaultsResponse, RotateCredentialRequest, VaultInfo, } from "../../components.js";
-import { ownerOf } from "../../../tenant/auth.js";
-import { fail } from "../../../tenant/http.js";
+import { CreateCredentialRequestSchema, CreateVaultRequestSchema, RotateCredentialRequestSchema, StartOAuthRequestSchema, } from "@nylorun/core/contracts";
+import { CreateCredentialRequest, CreateVaultRequest, CredentialInfo, DeletedResponse, ListCredentialsResponse, ListVaultsResponse, RotateCredentialRequest, StartOAuthRequest, StartOAuthResponse, VaultInfo, } from "../../components.js";
+import { HttpError } from "../../../tenant/http.js";
+import { VaultError } from "../../../vault/error.js";
 import { readJson } from "../body.js";
-import { pathSegments, tenantRoute } from "../define.js";
+import { tenantRoute } from "../define.js";
 import { jsonResponse } from "../respond.js";
-const OWN_VAULTS = {
+/** The Management API's vault routes (`/v1/tenant/vaults`): a management key. */
+const MANAGEMENT = { credentials: ["management"], scopes: "never" };
+/**
+ * The OAuth callback: a browser sent back by the authorization server, with no credential and no
+ * protocol header. The `state` it carries is the grant.
+ */
+const CALLBACK = {
     credentials: ["application", "subject", "token"],
-    scopes: ["vaults:own"],
-    browser: true,
+    scopes: "any",
+    anonymous: true,
+    unversioned: true,
 };
+/** Where the authorization server sends the browser back. */
+export const OAUTH_CALLBACK_PATH = "/v1/oauth/callback";
 const json = (schema, description) => ({
     description,
     content: { "application/json": { schema } },
@@ -21,126 +30,102 @@ const body = (schema) => ({
 });
 const vaultId = z.object({ vaultId: z.string() });
 const credentialId = vaultId.extend({ credentialId: z.string() });
-/**
- * Who a vault route acts for: the subject, or no one in particular (an application key). Below
- * a vault, the vault must be the subject's before anything else.
- */
-async function ownerFor(c) {
-    const { vault } = c.env.tenant;
-    const owner = ownerOf(c.get("scope"));
-    const id = c.req.param("vaultId");
-    if (id !== undefined && owner !== undefined)
-        await vault.assertOwner(id, owner);
-    return owner;
-}
-export function vaultRoutes(api) {
-    tenantRoute(api, OWN_VAULTS, {
+/** The vault routes under `base` (`/v1/tenant/vaults`). */
+function vaultRoutesAt(api, base, access) {
+    tenantRoute(api, access, {
         method: "post",
-        path: "/v1/vaults",
+        path: `${base}`,
         tags: ["Vaults"],
         summary: "Create a vault",
+        description: "With `scope: \"installation\"` the installation's own vault, owned by `installation`, which any session may attach; or a vault of one person (`ownerUserId`), which only that person's sessions attach.",
         request: { body: body(CreateVaultRequest) },
         responses: {
             200: json(VaultInfo, "The vault"),
             409: { description: "The idempotency key was used for another vault" },
         },
     }, async (c) => {
-        const owner = await ownerFor(c);
         const request = CreateVaultRequestSchema.parse(await readJson(c.req.raw));
-        if (owner !== undefined && request.ownerUserId !== owner)
-            fail(403, "ownerUserId must be the subject");
         return jsonResponse(200, await c.env.tenant.vault.createVault(request));
     });
-    tenantRoute(api, OWN_VAULTS, {
+    tenantRoute(api, access, {
         method: "get",
-        path: "/v1/vaults",
+        path: `${base}`,
         tags: ["Vaults"],
-        summary: "List a person's vaults",
+        summary: "List vaults",
+        description: "The installation vaults, after the vaults of `ownerUserId` when it names a person.",
         request: {
             query: z.object({
                 ownerUserId: z
                     .string()
                     .optional()
-                    .meta({ description: "Whose vaults; required with an application key acting for no one" }),
+                    .meta({ description: "Also list this person's vaults" }),
             }),
         },
         responses: { 200: json(ListVaultsResponse, "The vaults") },
     }, async (c) => {
-        const owner = await ownerFor(c);
-        const ownerUserId = c.req.query("ownerUserId") ?? owner ?? fail(400, "ownerUserId is required");
-        if (owner !== undefined && ownerUserId !== owner)
-            fail(403, "ownerUserId must be the subject");
-        return jsonResponse(200, { vaults: await c.env.tenant.vault.listVaults(ownerUserId) });
+        return jsonResponse(200, {
+            vaults: await c.env.tenant.vault.listVaults(c.req.query("ownerUserId"), {
+                installation: true,
+            }),
+        });
     });
-    tenantRoute(api, OWN_VAULTS, {
+    tenantRoute(api, access, {
         method: "get",
-        path: "/v1/vaults/{vaultId}",
+        path: `${base}/{vaultId}`,
         tags: ["Vaults"],
         summary: "Get a vault",
         request: { params: vaultId },
         responses: { 200: json(VaultInfo, "The vault") },
     }, async (c) => {
-        await ownerFor(c);
         return jsonResponse(200, await c.env.tenant.vault.getVault(c.req.param("vaultId")));
     });
-    tenantRoute(api, OWN_VAULTS, {
+    tenantRoute(api, access, {
         method: "delete",
-        path: "/v1/vaults/{vaultId}",
+        path: `${base}/{vaultId}`,
         tags: ["Vaults"],
         summary: "Delete a vault and its credentials",
         request: { params: vaultId },
         responses: { 200: json(DeletedResponse, "Deleted") },
     }, async (c) => {
-        await ownerFor(c);
         return jsonResponse(200, await c.env.tenant.vault.deleteVault(c.req.param("vaultId")));
     });
-    tenantRoute(api, OWN_VAULTS, {
+    tenantRoute(api, access, {
         method: "post",
-        path: "/v1/vaults/{vaultId}/credentials",
+        path: `${base}/{vaultId}/credentials`,
         tags: ["Vaults"],
         summary: "Add a credential",
-        description: "A bearer token or OAuth tokens, bound to the URLs a tool may send them to. A subject token cannot store OAuth refresh credentials.",
+        description: "A bearer token or OAuth tokens, bound to the URLs a tool may send them to.",
         request: { params: vaultId, body: body(CreateCredentialRequest) },
         responses: { 200: json(CredentialInfo, "The credential, without its secret") },
     }, async (c) => {
-        await ownerFor(c);
         const request = CreateCredentialRequestSchema.parse(await readJson(c.req.raw));
-        // The Runtime calls a refresh credential's token endpoint itself: never for a browser.
-        if (c.get("scope").kind === "token" &&
-            request.auth.type === "oauth" &&
-            request.auth.refresh)
-            fail(403, "A subject token cannot store OAuth refresh credentials", {
-                code: "scope_required",
-            });
         return jsonResponse(200, await c.env.tenant.keys.createCredential(c.req.param("vaultId"), request));
     });
-    tenantRoute(api, OWN_VAULTS, {
+    tenantRoute(api, access, {
         method: "get",
-        path: "/v1/vaults/{vaultId}/credentials",
+        path: `${base}/{vaultId}/credentials`,
         tags: ["Vaults"],
         summary: "List a vault's credentials",
         request: { params: vaultId },
         responses: { 200: json(ListCredentialsResponse, "The credentials, without their secrets") },
     }, async (c) => {
-        await ownerFor(c);
         return jsonResponse(200, {
             credentials: await c.env.tenant.vault.listCredentials(c.req.param("vaultId")),
         });
     });
-    tenantRoute(api, OWN_VAULTS, {
+    tenantRoute(api, access, {
         method: "get",
-        path: "/v1/vaults/{vaultId}/credentials/{credentialId}",
+        path: `${base}/{vaultId}/credentials/{credentialId}`,
         tags: ["Vaults"],
         summary: "Get a credential",
         request: { params: credentialId },
         responses: { 200: json(CredentialInfo, "The credential, without its secret") },
     }, async (c) => {
-        await ownerFor(c);
         return jsonResponse(200, await c.env.tenant.vault.getCredential(c.req.param("vaultId"), c.req.param("credentialId")));
     });
-    tenantRoute(api, OWN_VAULTS, {
+    tenantRoute(api, access, {
         method: "post",
-        path: "/v1/vaults/{vaultId}/credentials/{credentialId}",
+        path: `${base}/{vaultId}/credentials/{credentialId}`,
         tags: ["Vaults"],
         summary: "Rotate a credential's secret",
         request: { params: credentialId, body: body(RotateCredentialRequest) },
@@ -149,19 +134,106 @@ export function vaultRoutes(api) {
             409: { description: "A credential's type cannot change" },
         },
     }, async (c) => {
-        await ownerFor(c);
         const request = RotateCredentialRequestSchema.parse(await readJson(c.req.raw));
         return jsonResponse(200, await c.env.tenant.keys.rotateCredential(c.req.param("vaultId"), c.req.param("credentialId"), request));
     });
-    tenantRoute(api, OWN_VAULTS, {
+    tenantRoute(api, access, {
         method: "delete",
-        path: "/v1/vaults/{vaultId}/credentials/{credentialId}",
+        path: `${base}/{vaultId}/credentials/{credentialId}`,
         tags: ["Vaults"],
         summary: "Delete a credential",
         request: { params: credentialId },
         responses: { 200: json(DeletedResponse, "Deleted") },
     }, async (c) => {
-        await ownerFor(c);
         return jsonResponse(200, await c.env.tenant.vault.deleteCredential(c.req.param("vaultId"), c.req.param("credentialId")));
     });
+    tenantRoute(api, access, {
+        method: "post",
+        path: `${base}/{vaultId}/oauth/start`,
+        tags: ["Vaults"],
+        summary: "Start an MCP OAuth connect",
+        description: "Signs the installation in to the remote MCP server at `url` (declared as `server`) and stores its OAuth credential, bound to `url`, in this installation vault. The Runtime discovers the server's authorization server (RFC 9728, RFC 8414), registers itself (RFC 7591) unless `clientId` names a registered client, and answers the URL to open in a browser; the sign-in returns to `GET /v1/oauth/callback` within `expiresAt`. The callback URL is `NYLORUN_PUBLIC_URL` + `/v1/oauth/callback`, or this request's own origin when the Host has no public URL. Application keys acting for no one only. `oauth_client_required` when the server offers no registration and no `clientId` was given.",
+        request: { params: vaultId, body: body(StartOAuthRequest) },
+        responses: {
+            200: json(StartOAuthResponse, "Where to send the browser"),
+            502: {
+                description: "The authorization server, or its discovery, failed or refused (`oauth_failed`)",
+            },
+        },
+    }, async (c) => {
+        const request = StartOAuthRequestSchema.parse(await readJson(c.req.raw));
+        const tenant = c.env.tenant;
+        const base = tenant.config.publicUrl ?? new URL(c.req.url).origin;
+        return jsonResponse(200, await tenant.keys.startOAuth({
+            vaultId: c.req.param("vaultId"),
+            server: request.server,
+            url: request.url,
+            ...(request.clientId === undefined ? {} : { clientId: request.clientId }),
+            redirectUri: `${base}${OAUTH_CALLBACK_PATH}`,
+        }));
+    });
+}
+export function vaultRoutes(api) {
+    vaultRoutesAt(api, "/v1/tenant/vaults", MANAGEMENT);
+    tenantRoute(api, CALLBACK, {
+        method: "get",
+        path: OAUTH_CALLBACK_PATH,
+        tags: ["Vaults"],
+        summary: "Finish an MCP OAuth connect",
+        description: "Where the authorization server sends the browser back with `code` and `state` (or `error`). Exchanges the code once and stores the credential; answers a small HTML page. Needs no credential and no `Nylorun-Protocol`. A `state` is used once, for ten minutes (`oauth_state_invalid`).",
+        request: {
+            query: z.object({
+                code: z.string().optional(),
+                state: z.string().optional(),
+                error: z.string().optional(),
+            }),
+        },
+        responses: {
+            200: { description: "Connected", content: { "text/html": { schema: z.string() } } },
+            502: { description: "The authorization server refused the code (`oauth_failed`)" },
+        },
+    }, async (c) => {
+        const state = c.req.query("state");
+        const code = c.req.query("code");
+        const error = c.req.query("error");
+        if (!state)
+            return page(400, "Sign-in failed", "The authorization server sent no state. Start the connect again.");
+        try {
+            await c.env.tenant.keys.finishOAuth({
+                state,
+                ...(code === undefined ? {} : { code }),
+                ...(error === undefined ? {} : { error }),
+            });
+        }
+        catch (failure) {
+            if (failure instanceof HttpError || failure instanceof VaultError)
+                return page(failure.status, "Sign-in failed", failure.message);
+            c.env.tenant.config.logger.error("oauth_callback_failed", {
+                error: failure instanceof Error ? failure.name : "unknown",
+            });
+            return page(500, "Sign-in failed", "The connect failed. Start it again.");
+        }
+        return page(200, "Connected", "Connected. You can close this tab.");
+    });
+}
+const ESCAPES = { "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" };
+const escape = (text) => text.replace(/[&<>"']/g, (char) => ESCAPES[char]);
+/** The callback's answer: a small page that loads nothing, is never cached and leaks no referrer. */
+function page(status, title, message) {
+    const html = `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${escape(title)} · Nylorun</title>
+<style>body{font:16px/1.5 system-ui,sans-serif;max-width:32rem;margin:15vh auto;padding:0 1rem;color:#1a1a1a;background:#fff}@media (prefers-color-scheme:dark){body{color:#eee;background:#111}}h1{font-size:1.25rem}</style>
+</head><body><h1>${escape(title)}</h1><p>${escape(message)}</p></body></html>
+`;
+    return new Response(html, {
+        status,
+        headers: {
+            "content-type": "text/html; charset=utf-8",
+            "cache-control": "no-store",
+            "referrer-policy": "no-referrer",
+            "content-security-policy": "default-src 'none'; style-src 'unsafe-inline'",
+            "x-content-type-options": "nosniff",
+        },
+    });
 }

package/dist/api/openapi.d.ts

@@ -1,19 +1,18 @@
 /**
- * The Runtime's OpenAPI 3.2 documents, generated from the routes as declared for serving:
- *
- * - the Tenant API (`tenantDocument`): every Tenant route, with `/health`, `/ready` and
- *   `/openapi.json`. Served at `GET /openapi.json`, packed as `@nylorun/runtime/openapi.json`
- *   and attached to each release.
- * - the Admin API (`adminDocument`): served at `GET /v1/admin/openapi.json` behind the admin
- *   key, packed as `@nylorun/runtime/admin-openapi.json`.
+ * The Runtime's two OpenAPI 3.2 documents, generated from the routes as declared for serving
+ * (protocol 8): the Runtime API (`runtimeDocument`: `/openapi/runtime.json`, alias
+ * `/openapi.json`, `@nylorun/runtime/openapi.json`) and the Management API (`managementDocument`:
+ * `/openapi/management.json`, `@nylorun/runtime/management-openapi.json`). Both are attached to
+ * each release. Each has described tags in the order a developer uses them; the Runtime API
+ * groups them (`x-tagGroups`).
  *
  * Event streams are `text/event-stream` with an `itemSchema` (OpenAPI 3.2). Nothing here reads
  * the environment: the same Runtime makes the same document.
  */
 import { OpenApiGeneratorV32 } from "@asteasolutions/zod-to-openapi";
 type OpenApiDocument = ReturnType<OpenApiGeneratorV32["generateDocument"]>;
-/** The Tenant API's document. */
-export declare function tenantDocument(): OpenApiDocument;
-/** The Admin API's document. */
-export declare function adminDocument(): OpenApiDocument;
+/** The Runtime API's document: `/openapi/runtime.json` and `/openapi.json`. */
+export declare function runtimeDocument(): OpenApiDocument;
+/** The Management API's document: `/openapi/management.json`. */
+export declare function managementDocument(): OpenApiDocument;
 export {};