@skaile/forge-app-actions 0.2.1 → 0.4.0

package/src/runtime/server/http/create-handler.ts

@@ -0,0 +1,220 @@
+// server/http/create-handler.ts
+//
+// Projects server actions as a plain JSON-over-HTTP API. Deliberately outside
+// `runtime/server/utils/` (like the MCP adapter) so the Nuxt module's auto-import
+// of that directory never pulls it in, and written against `node:http` only:
+// no H3, Vue or AI SDK import, so Express/Vite hosts can mount it too.
+
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { bearerOf } from "../../internal/bearer";
+import type { ActionManifestEntry, ActionsManifest } from "../../internal/manifest";
+import { invokeAction } from "../utils/invoke-action";
+import { forAudience, type ServerAction } from "../utils/server-actions";
+
+/** What the `authorize` callback receives and may change. */
+export interface ActionsHttpAuthorizeDecision {
+  /** The host event (under Nitro an `H3Event`), or the Node request when the host passed none. */
+  event: unknown;
+  req: IncomingMessage;
+  /** `Authorization: Bearer …` without the prefix, or `null` when there is no bearer header. */
+  bearer: string | null;
+  /** Defaults to `false`; both the manifest and every call answer 401 unless the callback sets it. */
+  allowed: boolean;
+  /** What the actions see as `ctx.principal`. */
+  principal?: unknown;
+  /** What the actions see as `ctx.deps`, e.g. injected service clients. */
+  deps?: unknown;
+}
+
+export interface ActionsHttpHandlerOptions {
+  /** Narrowed to the `user` audience by the handler itself; the rest answer 404. */
+  actions: readonly ServerAction[];
+  /** Mount path, e.g. `/api/actions`. The manifest is `GET <route>`, a call `POST <route>/<id>`. */
+  route: string;
+  /**
+   * Asked once per request, before any action id is looked up or any body is
+   * read. Set `decision.allowed = true` to let it in. An error thrown here
+   * denies. A host that authenticates by cookie MUST also check the request's
+   * origin here before allowing a `POST`: this adapter performs no CSRF defence.
+   */
+  authorize: (decision: ActionsHttpAuthorizeDecision) => void | Promise<void>;
+}
+
+/** Per-request inputs a host may supply instead of the handler deriving them from `req`. */
+export interface ActionsHttpRequestInput {
+  /** Passed to `authorize` and to the actions as `ctx.event`. Defaults to `req`. */
+  event?: unknown;
+  /** The raw request body, for hosts whose framework already consumed the stream. Called only after authorization. */
+  readBody?: () => Promise<string | undefined>;
+}
+
+/** Bodies above this answer 413. */
+const MAX_BODY_BYTES = 1024 * 1024;
+
+/** The body shape an H3 error serializes to, so Nuxt clients decode it like any other error. */
+function errorBody(statusCode: number, message: string, data?: unknown) {
+  return {
+    statusCode,
+    statusMessage: message,
+    message,
+    ...(data === undefined ? {} : { data }),
+  };
+}
+
+function send(
+  res: ServerResponse,
+  status: number,
+  body: unknown,
+  headers: Record<string, string> = {},
+) {
+  res.writeHead(status, {
+    "content-type": "application/json; charset=utf-8",
+    "cache-control": "no-store",
+    "x-content-type-options": "nosniff",
+    ...headers,
+  });
+  res.end(JSON.stringify(body) ?? "null");
+}
+
+async function readStream(req: IncomingMessage): Promise<string> {
+  const chunks: Buffer[] = [];
+  let size = 0;
+  for await (const chunk of req) {
+    const buffer = typeof chunk === "string" ? Buffer.from(chunk) : (chunk as Buffer);
+    size += buffer.length;
+    if (size > MAX_BODY_BYTES) throw Object.assign(new Error("body too large"), { tooLarge: true });
+    chunks.push(buffer);
+  }
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+/**
+ * Where `req.url` points relative to `route`: the manifest (`null`), an action
+ * id (already decoded), or outside the API (`undefined`).
+ */
+function actionIdOf(url: string | undefined, route: string): string | null | undefined {
+  const pathname = new URL(url ?? "/", "http://localhost").pathname;
+  if (pathname !== route && !pathname.startsWith(`${route}/`)) return undefined;
+  const rest = pathname.slice(route.length).replace(/^\/+/, "");
+  if (rest === "") return null;
+  if (rest.includes("/")) return undefined;
+  try {
+    return decodeURIComponent(rest);
+  } catch {
+    return undefined;
+  }
+}
+
+function manifestOf(actions: readonly ServerAction[]): ActionsManifest {
+  return {
+    actions: actions.map(
+      (action): ActionManifestEntry => ({
+        id: action.id,
+        name: action.name,
+        description: action.description,
+        kind: action.kind,
+        inputSchema: action.inputSchema,
+      }),
+    ),
+  };
+}
+
+/**
+ * A Node `(req, res, input?)` handler for the HTTP projection of server actions.
+ *
+ * - `GET <route>`: `{ actions: [{ id, name, description, kind, inputSchema }] }` of the
+ *   `user`-audience actions, `cache-control: no-store`.
+ * - `POST <route>/<id>`: the JSON body is the action's input; the response is its raw
+ *   result. A failure is an H3-shaped error body (`statusCode`, `statusMessage`, `message`,
+ *   `data.issues` for schema errors) with the outcome's status.
+ *
+ * Both routes deny by default (401) until `authorize` sets `decision.allowed`.
+ * Unknown and non-`user` actions answer 404, malformed JSON 400. Input parsing and
+ * the action's own `authorize` happen inside `action.run`, once, via `invokeAction`.
+ */
+export function createActionsHttpHandler(
+  options: ActionsHttpHandlerOptions,
+): (req: IncomingMessage, res: ServerResponse, input?: ActionsHttpRequestInput) => Promise<void> {
+  const route = `/${options.route.replace(/^\/+|\/+$/g, "")}`;
+  const actions = forAudience(options.actions, "user");
+  const byId = new Map<string, ServerAction>();
+  for (const action of actions) {
+    const other = byId.get(action.id);
+    if (other) throw new Error(`Duplicate action id: ${action.id} (${other.name}, ${action.name})`);
+    byId.set(action.id, action);
+  }
+
+  return async (req, res, input = {}) => {
+    const id = actionIdOf(req.url, route);
+    if (id === undefined) {
+      return send(res, 404, errorBody(404, "Not found"));
+    }
+    const method = req.method ?? "GET";
+    const allowedMethod = id === null ? "GET" : "POST";
+    if (method !== allowedMethod && !(id === null && method === "HEAD")) {
+      return send(
+        res,
+        405,
+        errorBody(405, `Use ${allowedMethod} here`),
+        { allow: allowedMethod },
+      );
+    }
+
+    const event = input.event ?? req;
+    const decision: ActionsHttpAuthorizeDecision = {
+      event,
+      req,
+      bearer: bearerOf(req.headers.authorization),
+      allowed: false,
+      principal: undefined,
+      deps: undefined,
+    };
+    try {
+      await options.authorize(decision);
+    } catch {
+      decision.allowed = false;
+    }
+    if (decision.allowed !== true) {
+      return send(res, 401, errorBody(401, "Invalid or missing credential"), {
+        "www-authenticate": "Bearer",
+      });
+    }
+
+    if (id === null) return send(res, 200, manifestOf(actions));
+
+    const action = byId.get(id);
+    if (!action) return send(res, 404, errorBody(404, `Unknown action: ${id}`));
+
+    let raw: string | undefined;
+    try {
+      raw = await (input.readBody ? input.readBody() : readStream(req));
+    } catch (error) {
+      const tooLarge = (error as { tooLarge?: boolean } | null)?.tooLarge === true;
+      return send(res, tooLarge ? 413 : 400, errorBody(tooLarge ? 413 : 400, "Unreadable body"));
+    }
+    let body: unknown = {};
+    if (raw !== undefined && raw.trim() !== "") {
+      try {
+        body = JSON.parse(raw);
+      } catch {
+        return send(res, 400, errorBody(400, "Malformed JSON body"));
+      }
+    }
+
+    const outcome = await invokeAction(action, body, {
+      principal: decision.principal,
+      event,
+      deps: decision.deps,
+    });
+    if (outcome.ok) return send(res, 200, outcome.result);
+    return send(
+      res,
+      outcome.status,
+      errorBody(
+        outcome.status,
+        outcome.message,
+        outcome.issues === undefined ? undefined : { issues: outcome.issues },
+      ),
+    );
+  };
+}

package/src/runtime/server/http/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Explicit entry point for the HTTP projection of server actions, via the
+ * `./http` subpath. The Nuxt module mounts the routes itself when
+ * `forgeAppActions.http` is set; use these to serve actions from elsewhere.
+ */
+
+export type { ActionManifestEntry, ActionsManifest } from "../../internal/manifest";
+export * from "./create-handler";
+export type { HttpAuthorizeDecision } from "./route";

package/src/runtime/server/http/route.ts

@@ -0,0 +1,54 @@
+// server/http/route.ts
+//
+// The Nitro handler `forgeAppActions.http` mounts. Not importable from app code;
+// apps reach the same projection through `@skaile/forge-app-actions/http`.
+
+import type { H3Event } from "h3";
+import { defineEventHandler, readRawBody } from "h3";
+import { useNitroApp, useRuntimeConfig } from "nitropack/runtime";
+import { serverActionRegistry } from "../utils/server-actions";
+import { createActionsHttpHandler } from "./create-handler";
+
+/** What the `forge-app-actions:http:authorize` hook receives and may change. */
+export interface HttpAuthorizeDecision {
+  event: H3Event;
+  /** `Authorization: Bearer …` without the prefix, or `null` when there is no bearer header. */
+  bearer: string | null;
+  /** Defaults to `false`; manifest and calls answer 401 unless the hook sets it. */
+  allowed: boolean;
+  /** What the actions see as `ctx.principal`. */
+  principal?: unknown;
+  /** What the actions see as `ctx.deps`, e.g. injected service clients. */
+  deps?: unknown;
+}
+
+/** `GET <route>` (manifest) and `POST <route>/:id` over the registered server actions. */
+export default defineEventHandler(async (event) => {
+  const { http } = useRuntimeConfig(event).forgeAppActions as { http: { route: string } };
+  // The handler writes the response itself; h3 sees `res.writableEnded` and sends nothing more.
+  await createActionsHttpHandler({
+    actions: serverActionRegistry.list(),
+    route: http.route,
+    authorize: async (inner) => {
+      const decision: HttpAuthorizeDecision = {
+        event,
+        bearer: inner.bearer,
+        allowed: false,
+        principal: undefined,
+        deps: undefined,
+      };
+      // The hook's typing comes from the module's type template, which is absent
+      // when this package is type-checked on its own.
+      const { hooks } = useNitroApp() as unknown as {
+        hooks: { callHook(name: string, decision: HttpAuthorizeDecision): Promise<void> };
+      };
+      await hooks.callHook("forge-app-actions:http:authorize", decision);
+      inner.allowed = decision.allowed === true;
+      inner.principal = decision.principal;
+      inner.deps = decision.deps;
+    },
+  })(event.node.req, event.node.res, {
+    event,
+    readBody: () => readRawBody(event, "utf8"),
+  });
+});

package/src/runtime/server/index.ts

@@ -6,3 +6,5 @@
 
 export * from "./utils/capability-registry";
 export * from "./utils/client-capability-bridge";
+export * from "./utils/server-actions";
+export * from "./utils/invoke-action";

package/src/runtime/server/mcp/create-handler.ts

@@ -0,0 +1,134 @@
+// server/mcp/create-handler.ts
+//
+// Projects server actions as MCP tools. Deliberately outside `runtime/server/utils/`
+// so the Nuxt module's auto-import of that directory never pulls the MCP SDK
+// into apps that do not enable `forgeAppActions.mcp`.
+
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { toolNameOf } from "../../internal/tool-name";
+import { invokeAction } from "../utils/invoke-action";
+import type { ServerAction, ServerActionScope } from "../utils/server-actions";
+
+export { toolNameOf };
+
+export interface ActionsMcpServerOptions {
+  /** Served as given; narrow them with `forAudience(actions, "llm")` first to honor audiences. */
+  actions: readonly ServerAction[];
+  serverInfo: { name: string; version: string };
+  /** `principal`, `event` and `deps` handed to every action as `ctx`; its `name` is derived per action. */
+  context: ServerActionScope;
+}
+
+type ToolInputSchema = { type: "object"; [key: string]: unknown };
+
+const text = (value: string) => [{ type: "text" as const, text: value }];
+
+const failure = (message: string) => ({ isError: true as const, content: text(message) });
+
+/**
+ * An MCP server whose tools are the given server actions, named
+ * `toolNameOf(action.name)`. Every call goes through `invokeAction` with `context`;
+ * a failed call (invalid input, denied by the action's `authorize`, handler error)
+ * is an `isError` result carrying the outcome's message, never an HTTP error.
+ */
+export function createActionsMcpServer(options: ActionsMcpServerOptions): Server {
+  const byTool = new Map<string, ServerAction>();
+  for (const action of options.actions) {
+    const toolName = toolNameOf(action.name);
+    const other = byTool.get(toolName);
+    if (other) {
+      throw new Error(
+        `Tool name collision: ${other.name} and ${action.name} both map to ${toolName}`,
+      );
+    }
+    byTool.set(toolName, action);
+  }
+
+  const server = new Server(options.serverInfo, { capabilities: { tools: {} } });
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: [...byTool].map(([name, action]) => ({
+      name,
+      description: action.description,
+      inputSchema: action.inputSchema as ToolInputSchema,
+    })),
+  }));
+
+  server.setRequestHandler(CallToolRequestSchema, async ({ params }) => {
+    const action = byTool.get(params.name);
+    if (!action) return failure(`unknown tool: ${params.name}`);
+    const outcome = await invokeAction(action, params.arguments ?? {}, options.context);
+    if (!outcome.ok) return failure(outcome.message);
+    const { result } = outcome;
+    const content = text(JSON.stringify(result) ?? "null");
+    if (result !== null && typeof result === "object" && !Array.isArray(result)) {
+      return { content, structuredContent: result as Record<string, unknown> };
+    }
+    return { content };
+  });
+
+  return server;
+}
+
+export type ActionsMcpHttpHandlerOptions = ActionsMcpServerOptions;
+
+const reply = (
+  res: ServerResponse,
+  status: number,
+  body: unknown,
+  headers: Record<string, string> = {},
+) => {
+  res.writeHead(status, {
+    "content-type": "application/json; charset=utf-8",
+    "cache-control": "no-store",
+    "x-content-type-options": "nosniff",
+    ...headers,
+  });
+  res.end(JSON.stringify(body));
+};
+
+const ACCEPT = "application/json, text/event-stream";
+
+/**
+ * A Node `(req, res, parsedBody?)` handler for the Streamable HTTP MCP endpoint.
+ * Stateless: every POST serves one JSON-RPC exchange with a fresh server and
+ * ends, so no session outlives a request. Authorization is the caller's job
+ * (the Nitro route runs the `forge-app-actions:mcp:authorize` hook first);
+ * `GET`/`DELETE` answer 405.
+ */
+export function createActionsMcpHttpHandler(
+  options: ActionsMcpHttpHandlerOptions,
+): (req: IncomingMessage, res: ServerResponse, parsedBody?: unknown) => Promise<void> {
+  return async (req, res, parsedBody) => {
+    if (req.method !== "POST") {
+      return reply(res, 405, { error: "Use POST for Streamable HTTP MCP" }, { allow: "POST" });
+    }
+    // The transport insists on both media types; plain `curl` clients that omit
+    // them are served anyway. The transport reads `rawHeaders`, so the header
+    // goes into both views of the request.
+    const accept = String(req.headers.accept ?? "");
+    if (!accept.includes("application/json") || !accept.includes("text/event-stream")) {
+      req.headers.accept = ACCEPT;
+      req.rawHeaders.push("Accept", ACCEPT);
+    }
+    const server = createActionsMcpServer(options);
+    const transport = new StreamableHTTPServerTransport({
+      sessionIdGenerator: undefined,
+      enableJsonResponse: true,
+    });
+    res.on("close", () => {
+      void transport.close();
+      void server.close();
+    });
+    try {
+      await server.connect(transport);
+      await transport.handleRequest(req, res, parsedBody);
+    } catch {
+      if (!res.headersSent) reply(res, 500, { error: "Internal server error" });
+      else res.end();
+    }
+  };
+}

package/src/runtime/server/mcp/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Explicit entry point for the MCP projection of server actions, via the
+ * `./mcp` subpath. The Nuxt module mounts the route itself when
+ * `forgeAppActions.mcp` is set; use these to serve actions from elsewhere.
+ */
+
+export * from "./create-handler";
+export type { McpAuthorizeDecision } from "./route";

package/src/runtime/server/mcp/route.ts

@@ -0,0 +1,90 @@
+// server/mcp/route.ts
+//
+// The Nitro handler `forgeAppActions.mcp` mounts. Not importable from app code;
+// apps reach the same projection through `@skaile/forge-app-actions/mcp`.
+
+import type { H3Event } from "h3";
+import {
+  defineEventHandler,
+  getRequestHeader,
+  readRawBody,
+  setResponseHeaders,
+  setResponseStatus,
+} from "h3";
+import { useNitroApp, useRuntimeConfig } from "nitropack/runtime";
+import { bearerOf } from "../../internal/bearer";
+import { forAudience, serverActionRegistry } from "../utils/server-actions";
+import { createActionsMcpHttpHandler } from "./create-handler";
+
+/** What the `forge-app-actions:mcp:authorize` hook receives and may change. */
+export interface McpAuthorizeDecision {
+  event: H3Event;
+  /** `Authorization: Bearer …` without the prefix, or `null` when there is no bearer header. */
+  bearer: string | null;
+  /** Defaults to `false`; the request is rejected with 401 unless the hook sets it. */
+  allowed: boolean;
+  /** What the actions see as `ctx.principal`. */
+  principal?: unknown;
+  /** What the actions see as `ctx.deps`, e.g. injected service clients. */
+  deps?: unknown;
+}
+
+/** The Streamable HTTP MCP endpoint over the registered server actions. */
+export default defineEventHandler(async (event) => {
+  const reply = (status: number, body: unknown, headers: Record<string, string> = {}) => {
+    setResponseStatus(event, status);
+    setResponseHeaders(event, { "cache-control": "no-store", ...headers });
+    return body;
+  };
+
+  if (event.method !== "POST") {
+    return reply(405, { error: "Use POST for Streamable HTTP MCP" }, { allow: "POST" });
+  }
+
+  const decision: McpAuthorizeDecision = {
+    event,
+    bearer: bearerOf(getRequestHeader(event, "authorization")),
+    allowed: false,
+    principal: undefined,
+    deps: undefined,
+  };
+  try {
+    // The hook's typing comes from the module's type template, which is absent
+    // when this package is type-checked on its own.
+    const { hooks } = useNitroApp() as unknown as {
+      hooks: { callHook(name: string, decision: McpAuthorizeDecision): Promise<void> };
+    };
+    await hooks.callHook("forge-app-actions:mcp:authorize", decision);
+  } catch {
+    decision.allowed = false;
+  }
+  if (decision.allowed !== true) {
+    return reply(
+      401,
+      { error: "Invalid or missing agent credential" },
+      { "www-authenticate": "Bearer" },
+    );
+  }
+
+  let parsed: unknown;
+  // Read here so the transport does not wait on a stream Nitro may already have consumed.
+  try {
+    parsed = JSON.parse((await readRawBody(event, "utf8")) ?? "");
+  } catch {
+    return reply(400, {
+      jsonrpc: "2.0",
+      id: null,
+      error: { code: -32700, message: "Parse error" },
+    });
+  }
+
+  const { mcp } = useRuntimeConfig(event).forgeAppActions as {
+    mcp: { name: string; version: string };
+  };
+  // The handler writes the response itself; h3 sees `res.writableEnded` and sends nothing more.
+  await createActionsMcpHttpHandler({
+    actions: forAudience(serverActionRegistry.list(), "llm"),
+    serverInfo: { name: mcp.name, version: mcp.version },
+    context: { principal: decision.principal, event, deps: decision.deps },
+  })(event.node.req, event.node.res, parsed);
+});

package/src/runtime/server/utils/invoke-action.ts

@@ -0,0 +1,71 @@
+// server/utils/invoke-action.ts
+//
+// Directly in `runtime/server/utils/` for the same reason as `server-actions.ts`.
+// Transport-neutral: no H3, MCP or AI SDK import, so every projection (MCP, HTTP,
+// chat tools) classifies failures the same way.
+
+import * as z from "zod";
+import type { ServerAction, ServerActionScope } from "./server-actions";
+
+/** What a projection maps to its own error shape: `status` is HTTP-style, whatever the transport. */
+export type ActionOutcome =
+  | { ok: true; result: unknown }
+  | { ok: false; status: number; message: string; issues?: unknown[] };
+
+/**
+ * A ZodError by shape, not `instanceof`: the schema belongs to the app, whose
+ * zod instance may differ from the one bundled with this package.
+ */
+function isZodError(error: unknown): error is z.core.$ZodError {
+  const candidate = error as { name?: unknown; issues?: unknown } | null;
+  return (
+    typeof candidate?.name === "string" &&
+    /^\$?ZodError$/.test(candidate.name) &&
+    Array.isArray(candidate.issues)
+  );
+}
+
+/** The message to show the caller: an H3 error carries it in `statusMessage`. */
+function messageOf(error: unknown): string {
+  if (error && typeof error === "object") {
+    const { statusMessage, message } = error as { statusMessage?: unknown; message?: unknown };
+    if (typeof statusMessage === "string" && statusMessage) return statusMessage;
+    if (typeof message === "string") return message;
+  }
+  return String(error);
+}
+
+/** An explicit HTTP-style status on the error (H3 errors carry `statusCode`), if it is a valid one. */
+function statusOf(error: unknown): number | undefined {
+  const { statusCode } = (error ?? {}) as { statusCode?: unknown };
+  return typeof statusCode === "number" && Number.isInteger(statusCode) && statusCode >= 400 && statusCode < 600
+    ? statusCode
+    : undefined;
+}
+
+/**
+ * Runs `action` and classifies the result: schema error → 400 with
+ * `invalid input: …` and its `issues`; an error with a numeric `statusCode` →
+ * that status; anything else → 500. Calls `action.run` only: parsing and the
+ * action's `authorize` happen there, exactly once, so this never reparses or
+ * authorizes a second time.
+ */
+export async function invokeAction(
+  action: ServerAction,
+  input: unknown,
+  ctx: ServerActionScope,
+): Promise<ActionOutcome> {
+  try {
+    return { ok: true, result: await action.run(input, ctx) };
+  } catch (error) {
+    if (isZodError(error)) {
+      return {
+        ok: false,
+        status: 400,
+        message: `invalid input: ${z.prettifyError(error)}`,
+        issues: error.issues,
+      };
+    }
+    return { ok: false, status: statusOf(error) ?? 500, message: messageOf(error) };
+  }
+}