keryx 0.22.0 → 0.23.0

package/config/server/mcp.ts

@@ -13,5 +13,9 @@ export const configServerMcp = {
     60 * 60 * 24 * 30,
   ), // 30 days, in seconds
   oauthCodeTtl: await loadFromEnvIfSet("MCP_OAUTH_CODE_TTL", 300), // 5 minutes, in seconds
+  oauthRefreshTtl: await loadFromEnvIfSet(
+    "MCP_OAUTH_REFRESH_TTL",
+    60 * 60 * 24 * 30,
+  ), // 30 days, in seconds
   markdownDepthLimit: await loadFromEnvIfSet("MCP_MARKDOWN_DEPTH_LIMIT", 5),
 };

package/initializers/oauth.ts

@@ -10,10 +10,14 @@ import {
 import {
   handleAuthorizeGet,
   handleAuthorizePost,
+  handleIntrospect,
   handleMetadata,
   handleProtectedResourceMetadata,
   handleRegister,
+  handleRevoke,
   handleToken,
+  OAUTH_PATHS,
+  OAUTH_WELL_KNOWN_PATHS,
   type TokenData,
 } from "../util/oauthHandlers";
 import {
@@ -70,7 +74,7 @@ export class OAuthInitializer extends Initializer {
         return new Response(null, { status: 204, headers: corsHeaders });
       }
 
-      const prmPrefix = "/.well-known/oauth-protected-resource";
+      const prmPrefix = OAUTH_WELL_KNOWN_PATHS.protectedResource;
       if (path.startsWith(prmPrefix) && method === "GET") {
         const resourcePath = path.slice(prmPrefix.length) || "";
         return appendHeaders(
@@ -79,7 +83,7 @@ export class OAuthInitializer extends Initializer {
         );
       }
       if (
-        path === "/.well-known/oauth-authorization-server" &&
+        path === OAUTH_WELL_KNOWN_PATHS.authorizationServer &&
         method === "GET"
       ) {
         return appendHeaders(handleMetadata(origin), corsHeaders);
@@ -89,13 +93,15 @@ export class OAuthInitializer extends Initializer {
       if (
         config.rateLimit.enabled &&
         ip &&
-        (path === "/oauth/register" ||
-          path === "/oauth/authorize" ||
-          path === "/oauth/token")
+        (path === OAUTH_PATHS.register ||
+          path === OAUTH_PATHS.authorize ||
+          path === OAUTH_PATHS.token ||
+          path === OAUTH_PATHS.introspect ||
+          path === OAUTH_PATHS.revoke)
       ) {
         // /oauth/register gets a stricter, dedicated rate limit
         const overrides =
-          path === "/oauth/register"
+          path === OAUTH_PATHS.register
             ? {
                 limit: config.rateLimit.oauthRegisterLimit,
                 windowMs: config.rateLimit.oauthRegisterWindowMs,
@@ -123,18 +129,24 @@ export class OAuthInitializer extends Initializer {
         }
       }
 
-      if (path === "/oauth/register" && method === "POST") {
+      if (path === OAUTH_PATHS.register && method === "POST") {
         return appendHeaders(await handleRegister(req), corsHeaders);
       }
-      if (path === "/oauth/authorize" && method === "GET") {
+      if (path === OAUTH_PATHS.authorize && method === "GET") {
         return handleAuthorizeGet(url, templates);
       }
-      if (path === "/oauth/authorize" && method === "POST") {
+      if (path === OAUTH_PATHS.authorize && method === "POST") {
         return handleAuthorizePost(req, templates);
       }
-      if (path === "/oauth/token" && method === "POST") {
+      if (path === OAUTH_PATHS.token && method === "POST") {
         return appendHeaders(await handleToken(req), corsHeaders);
       }
+      if (path === OAUTH_PATHS.introspect && method === "POST") {
+        return appendHeaders(await handleIntrospect(req), corsHeaders);
+      }
+      if (path === OAUTH_PATHS.revoke && method === "POST") {
+        return appendHeaders(await handleRevoke(req), corsHeaders);
+      }
 
       return null;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "keryx",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "module": "index.ts",
   "type": "module",
   "license": "MIT",

package/testing/index.ts

@@ -2,6 +2,14 @@ import { afterAll, beforeAll } from "bun:test";
 import { api } from "../api";
 import type { WebServer } from "../servers/web";
 
+export {
+  buildWebSocket,
+  createSession,
+  createUser,
+  subscribeToChannel,
+  waitForBroadcastMessages,
+} from "./websocket";
+
 /**
  * Generous lifecycle hook timeout (15s) for `beforeAll` / `afterAll`.
  *

package/testing/websocket.ts

@@ -0,0 +1,171 @@
+import { expect } from "bun:test";
+import { api } from "../api";
+import type { WebServer } from "../servers/web";
+
+const wsUrl = () => {
+  const web = api.servers.servers.find(
+    (s: { name: string }) => s.name === "web",
+  ) as WebServer | undefined;
+  return (web?.url || "")
+    .replace("https://", "wss://")
+    .replace("http://", "ws://");
+};
+
+/**
+ * Open a WebSocket against the running test server and return the socket along
+ * with a mutable array that accumulates every `message` event as it arrives.
+ *
+ * The promise resolves once the socket's `open` event fires, so callers can
+ * immediately send actions without an additional readiness check.
+ *
+ * @param options.headers - Request headers to include in the WebSocket upgrade
+ *   (for example a session cookie). Optional.
+ * @returns An object with the open `socket` and the live `messages` array that
+ *   every subsequent handler populates.
+ */
+export const buildWebSocket = async (
+  options: { headers?: Record<string, string> } = {},
+) => {
+  const socket = new WebSocket(wsUrl(), { headers: options.headers });
+  const messages: MessageEvent[] = [];
+  socket.addEventListener("message", (event) => {
+    messages.push(event);
+  });
+  socket.addEventListener("error", (event) => {
+    console.error(event);
+  });
+  await new Promise((resolve) => {
+    socket.addEventListener("open", resolve);
+  });
+  return { socket, messages };
+};
+
+/**
+ * Send a `user:create` action over the given WebSocket and return the created
+ * user from the server's response.
+ *
+ * Assumes this is the first action sent on the socket — it reads `messages[0]`.
+ *
+ * @throws {Error} If the server responds with an error payload.
+ */
+export const createUser = async (
+  socket: WebSocket,
+  messages: MessageEvent[],
+  name: string,
+  email: string,
+  password: string,
+) => {
+  socket.send(
+    JSON.stringify({
+      messageType: "action",
+      action: "user:create",
+      messageId: 1,
+      params: { name, email, password },
+    }),
+  );
+
+  while (messages.length === 0) await Bun.sleep(10);
+  const response = JSON.parse(messages[0].data);
+
+  if (response.error) {
+    throw new Error(`User creation failed: ${response.error.message}`);
+  }
+
+  return response.response.user;
+};
+
+/**
+ * Send a `session:create` action over the given WebSocket and return the
+ * response payload (user + session).
+ *
+ * Assumes `createUser` was invoked first — it reads `messages[1]`.
+ *
+ * @throws {Error} If the server responds with an error payload.
+ */
+export const createSession = async (
+  socket: WebSocket,
+  messages: MessageEvent[],
+  email: string,
+  password: string,
+) => {
+  socket.send(
+    JSON.stringify({
+      messageType: "action",
+      action: "session:create",
+      messageId: 2,
+      params: { email, password },
+    }),
+  );
+
+  while (messages.length < 2) await Bun.sleep(10);
+  const response = JSON.parse(messages[1].data);
+
+  if (response.error) {
+    throw new Error(`Session creation failed: ${response.error.message}`);
+  }
+
+  return response.response;
+};
+
+/**
+ * Subscribe the socket to a channel and wait for the server's subscribe
+ * confirmation.
+ *
+ * Matches the confirmation by content rather than index, because presence
+ * broadcast events (join/leave) delivered via Redis pub/sub can arrive before
+ * the subscribe confirmation and shift message indices.
+ */
+export const subscribeToChannel = async (
+  socket: WebSocket,
+  messages: MessageEvent[],
+  channel: string,
+) => {
+  socket.send(JSON.stringify({ messageType: "subscribe", channel }));
+
+  let response: Record<string, any> | undefined;
+  while (!response) {
+    for (const m of messages) {
+      const parsed = JSON.parse(m.data);
+      if (parsed.subscribed?.channel === channel) {
+        response = parsed;
+        break;
+      }
+    }
+    if (!response) await Bun.sleep(10);
+  }
+  return response;
+};
+
+/**
+ * Wait briefly and return all broadcast (non-action-reply) messages received on
+ * the socket so far, asserting the expected count.
+ *
+ * Broadcasts are distinguished from action replies by the absence of a
+ * `messageId` field. Uses `expect()` internally so callers see a readable
+ * failure with the raw broadcast payload dumped to stderr on mismatch.
+ *
+ * @throws {Error} When the observed broadcast count does not equal
+ *   `expectedCount`.
+ */
+export const waitForBroadcastMessages = async (
+  messages: MessageEvent[],
+  expectedCount: number,
+) => {
+  await Bun.sleep(100);
+
+  const broadcastMessages: Record<string, any>[] = [];
+  for (const message of messages) {
+    const parsedMessage = JSON.parse(message.data);
+    if (!parsedMessage.messageId) {
+      broadcastMessages.push(parsedMessage);
+    }
+  }
+
+  try {
+    expect(broadcastMessages.length).toBe(expectedCount);
+  } catch (e) {
+    console.error(JSON.stringify(broadcastMessages, null, 2));
+    throw e;
+  }
+  return broadcastMessages;
+};

package/util/oauthHandlers/authorize.ts

@@ -0,0 +1,170 @@
+import { randomUUID } from "crypto";
+import { api } from "../../api";
+import type { Action, OAuthActionResponse } from "../../classes/Action";
+import { Connection } from "../../classes/Connection";
+import { config } from "../../config";
+import { redirectUrisMatch } from "../oauth";
+import {
+  type AuthPageParams,
+  type OAuthTemplates,
+  renderAuthPage,
+  renderSuccessPage,
+} from "../oauthTemplates";
+import { clientKey, codeKey } from "./keys";
+import type { AuthCode, OAuthClient } from "./types";
+
+/** OAuth protocol fields that should not be forwarded to login/signup actions. */
+const OAUTH_FIELDS = new Set([
+  "mode",
+  "client_id",
+  "redirect_uri",
+  "code_challenge",
+  "code_challenge_method",
+  "response_type",
+  "state",
+]);
+
+function findAuthActions() {
+  return {
+    loginAction: api.actions.actions.find((a: Action) => a.mcp?.isLoginAction),
+    signupAction: api.actions.actions.find(
+      (a: Action) => a.mcp?.isSignupAction,
+    ),
+  };
+}
+
+/** Render the OAuth authorize page (GET). */
+export function handleAuthorizeGet(
+  url: URL,
+  templates: OAuthTemplates,
+): Response {
+  const params: AuthPageParams = {
+    clientId: url.searchParams.get("client_id") ?? "",
+    redirectUri: url.searchParams.get("redirect_uri") ?? "",
+    codeChallenge: url.searchParams.get("code_challenge") ?? "",
+    codeChallengeMethod: url.searchParams.get("code_challenge_method") ?? "",
+    responseType: url.searchParams.get("response_type") ?? "",
+    state: url.searchParams.get("state") ?? "",
+    error: "",
+  };
+
+  return renderAuthPage(params, templates, findAuthActions());
+}
+
+/**
+ * Run the registered login or signup action inside an ephemeral OAuth
+ * connection and return the authenticated user id. Returns an error string if
+ * the action is not configured or the action itself returned an error.
+ */
+async function runAuthAction(
+  mode: "signup" | "login",
+  fields: Record<string, string>,
+): Promise<{ userId: number } | { error: string }> {
+  const isSignup = mode === "signup";
+  const action = api.actions.actions.find((a: Action) =>
+    isSignup ? a.mcp?.isSignupAction : a.mcp?.isLoginAction,
+  );
+  if (!action) {
+    return {
+      error: isSignup
+        ? "No signup action configured"
+        : "No login action configured",
+    };
+  }
+
+  const actionParams: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(fields)) {
+    if (!OAUTH_FIELDS.has(key)) actionParams[key] = value;
+  }
+
+  const connection = new Connection(
+    "oauth",
+    isSignup ? "oauth-signup" : "oauth-login",
+  );
+  try {
+    const { response, error } = await connection.act(action.name, actionParams);
+    if (error) return { error: error.message };
+    return { userId: (response as OAuthActionResponse).user.id };
+  } finally {
+    connection.destroy();
+  }
+}
+
+/** Handle the OAuth authorize form POST (signin/signup). */
+export async function handleAuthorizePost(
+  req: Request,
+  templates: OAuthTemplates,
+): Promise<Response> {
+  let fields: Record<string, string>;
+  try {
+    const contentType = req.headers.get("content-type") ?? "";
+    if (contentType.includes("application/x-www-form-urlencoded")) {
+      const text = await req.text();
+      const params = new URLSearchParams(text);
+      fields = Object.fromEntries(params.entries());
+    } else {
+      const form = await req.formData();
+      fields = {};
+      form.forEach((value, key) => {
+        fields[key] = String(value);
+      });
+    }
+  } catch {
+    return new Response("Bad Request", { status: 400 });
+  }
+
+  const oauthParams: AuthPageParams = {
+    clientId: fields.client_id ?? "",
+    redirectUri: fields.redirect_uri ?? "",
+    codeChallenge: fields.code_challenge ?? "",
+    codeChallengeMethod: fields.code_challenge_method ?? "",
+    responseType: fields.response_type ?? "",
+    state: fields.state ?? "",
+    error: "",
+  };
+  const authActions = findAuthActions();
+
+  const renderError = (error: string) => {
+    oauthParams.error = error;
+    return renderAuthPage(oauthParams, templates, authActions);
+  };
+
+  const clientRaw = await api.redis.redis.get(clientKey(oauthParams.clientId));
+  if (!clientRaw) return renderError("Unknown client");
+  const client = JSON.parse(clientRaw) as OAuthClient;
+
+  const uriMatch = client.redirect_uris.some((registered) =>
+    redirectUrisMatch(registered, oauthParams.redirectUri),
+  );
+  if (!uriMatch) return renderError("Invalid redirect URI");
+
+  if (oauthParams.codeChallengeMethod !== "S256") {
+    return renderError("code_challenge_method must be S256");
+  }
+
+  const mode = fields.mode === "signup" ? "signup" : "login";
+  const result = await runAuthAction(mode, fields);
+  if ("error" in result) return renderError(result.error);
+
+  const code = randomUUID();
+  const codeData: AuthCode = {
+    clientId: oauthParams.clientId,
+    userId: result.userId,
+    codeChallenge: oauthParams.codeChallenge,
+    redirectUri: oauthParams.redirectUri,
+  };
+
+  await api.redis.redis.set(
+    codeKey(code),
+    JSON.stringify(codeData),
+    "EX",
+    config.server.mcp.oauthCodeTtl,
+  );
+
+  const redirectUrl = new URL(oauthParams.redirectUri);
+  redirectUrl.searchParams.set("code", code);
+  if (oauthParams.state)
+    redirectUrl.searchParams.set("state", oauthParams.state);
+
+  return renderSuccessPage(redirectUrl.toString(), templates);
+}

package/util/oauthHandlers/index.ts

@@ -0,0 +1,17 @@
+export { handleAuthorizeGet, handleAuthorizePost } from "./authorize";
+export { handleIntrospect } from "./introspect";
+export {
+  handleMetadata,
+  handleProtectedResourceMetadata,
+} from "./metadata";
+export { handleRegister } from "./register";
+export { handleRevoke } from "./revoke";
+export { handleToken } from "./token";
+export {
+  type AuthCode,
+  OAUTH_PATHS,
+  OAUTH_WELL_KNOWN_PATHS,
+  type OAuthClient,
+  type RefreshTokenData,
+  type TokenData,
+} from "./types";

package/util/oauthHandlers/introspect.ts

@@ -0,0 +1,59 @@
+import { api } from "../../api";
+import { clientKey, tokenLookupOrder } from "./keys";
+import { jsonNoStoreResponse, oauthError, parseFormBody } from "./responses";
+import type { RefreshTokenData, TokenData } from "./types";
+
+const NOSTORE_HEADER = { "Cache-Control": "no-store" };
+
+/**
+ * OAuth 2.0 Token Introspection endpoint (RFC 7662).
+ *
+ * Requires a registered `client_id` in the form body; unknown clients get 401
+ * so random callers cannot probe token state. Looks up `token` in both the
+ * access-token and refresh-token keyspaces (honoring `token_type_hint` for
+ * lookup order). Returns `{ active: false }` for any miss so we do not leak
+ * whether a token existed and expired versus never existed.
+ */
+export async function handleIntrospect(req: Request): Promise<Response> {
+  const body = await parseFormBody(req);
+  const token = body.get("token");
+  const hint = body.get("token_type_hint");
+  const clientId = body.get("client_id");
+
+  if (!clientId) {
+    return oauthError(
+      "invalid_client",
+      "client_id is required",
+      401,
+      NOSTORE_HEADER,
+    );
+  }
+
+  const clientRaw = await api.redis.redis.get(clientKey(clientId));
+  if (!clientRaw) {
+    return oauthError("invalid_client", "Unknown client", 401, NOSTORE_HEADER);
+  }
+
+  if (!token) return jsonNoStoreResponse({ active: false });
+
+  for (const key of tokenLookupOrder(token, hint)) {
+    const raw = await api.redis.redis.get(key);
+    if (!raw) continue;
+
+    const data = JSON.parse(raw) as TokenData | RefreshTokenData;
+    const ttlSeconds = await api.redis.redis.ttl(key);
+    const nowSeconds = Math.floor(Date.now() / 1000);
+    const exp = ttlSeconds > 0 ? nowSeconds + ttlSeconds : undefined;
+
+    return jsonNoStoreResponse({
+      active: true,
+      client_id: data.clientId,
+      scope: data.scopes.join(" "),
+      token_type: "Bearer",
+      exp,
+      sub: String(data.userId),
+    });
+  }
+
+  return jsonNoStoreResponse({ active: false });
+}

package/util/oauthHandlers/keys.ts

@@ -0,0 +1,19 @@
+/** Redis key builders for OAuth records. */
+export const clientKey = (id: string) => `oauth:client:${id}`;
+export const codeKey = (code: string) => `oauth:code:${code}`;
+export const accessKey = (token: string) => `oauth:token:${token}`;
+export const refreshKey = (token: string) => `oauth:refresh:${token}`;
+
+/**
+ * When looking up an unknown bearer token (introspect/revoke), the caller may
+ * pass `token_type_hint` to hint at which keyspace to try first. Tokens are
+ * UUIDs so there is no collision risk; the hint is purely an optimization.
+ */
+export function tokenLookupOrder(
+  token: string,
+  hint: string | null,
+): [string, string] {
+  return hint === "refresh_token"
+    ? [refreshKey(token), accessKey(token)]
+    : [accessKey(token), refreshKey(token)];
+}

package/util/oauthHandlers/metadata.ts

@@ -0,0 +1,38 @@
+import { jsonResponse } from "./responses";
+import { OAUTH_PATHS } from "./types";
+
+/**
+ * RFC 9728 — Protected Resource Metadata.
+ * MCP clients fetch this first to discover the authorization server.
+ */
+export function handleProtectedResourceMetadata(
+  origin: string,
+  resourcePath: string,
+): Response {
+  const resource = resourcePath ? `${origin}${resourcePath}` : origin;
+  return jsonResponse({
+    resource,
+    authorization_servers: [origin],
+    scopes_supported: ["mcp"],
+  });
+}
+
+/** OAuth 2.1 authorization server metadata endpoint (RFC 8414). */
+export function handleMetadata(origin: string): Response {
+  const issuer = origin;
+  return jsonResponse({
+    issuer,
+    authorization_endpoint: `${issuer}${OAUTH_PATHS.authorize}`,
+    token_endpoint: `${issuer}${OAUTH_PATHS.token}`,
+    registration_endpoint: `${issuer}${OAUTH_PATHS.register}`,
+    introspection_endpoint: `${issuer}${OAUTH_PATHS.introspect}`,
+    revocation_endpoint: `${issuer}${OAUTH_PATHS.revoke}`,
+    response_types_supported: ["code"],
+    grant_types_supported: ["authorization_code", "refresh_token"],
+    code_challenge_methods_supported: ["S256"],
+    token_endpoint_auth_methods_supported: ["none"],
+    introspection_endpoint_auth_methods_supported: ["none"],
+    revocation_endpoint_auth_methods_supported: ["none"],
+    client_id_metadata_document_supported: false,
+  });
+}

package/util/oauthHandlers/register.ts

@@ -0,0 +1,58 @@
+import { randomUUID } from "crypto";
+import { api } from "../../api";
+import { config } from "../../config";
+import { validateRedirectUri } from "../oauth";
+import { clientKey } from "./keys";
+import { jsonResponse, oauthError } from "./responses";
+import type { OAuthClient } from "./types";
+
+/** Dynamic client registration endpoint (RFC 7591). */
+export async function handleRegister(req: Request): Promise<Response> {
+  let body: any;
+  try {
+    body = await req.json();
+  } catch {
+    return oauthError("invalid_request", "Invalid JSON body");
+  }
+
+  if (
+    !body.redirect_uris ||
+    !Array.isArray(body.redirect_uris) ||
+    body.redirect_uris.length === 0
+  ) {
+    return oauthError("invalid_request", "redirect_uris is required");
+  }
+
+  for (const uri of body.redirect_uris) {
+    if (typeof uri !== "string") {
+      return oauthError(
+        "invalid_request",
+        "Each redirect_uri must be a string",
+      );
+    }
+    const validation = validateRedirectUri(uri);
+    if (!validation.valid) {
+      // `error` is always populated when `valid` is false; see oauth.ts
+      return oauthError("invalid_request", validation.error!);
+    }
+  }
+
+  const clientId = randomUUID();
+  const client: OAuthClient = {
+    client_id: clientId,
+    redirect_uris: body.redirect_uris,
+    client_name: body.client_name,
+    grant_types: body.grant_types ?? ["authorization_code"],
+    response_types: body.response_types ?? ["code"],
+    token_endpoint_auth_method: body.token_endpoint_auth_method ?? "none",
+  };
+
+  await api.redis.redis.set(
+    clientKey(clientId),
+    JSON.stringify(client),
+    "EX",
+    config.server.mcp.oauthClientTtl,
+  );
+
+  return jsonResponse(client, 201);
+}