keryx 0.22.1 → 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.1",
+  "version": "0.23.0",
   "module": "index.ts",
   "type": "module",
   "license": "MIT",

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);
+}

package/util/oauthHandlers/responses.ts

@@ -0,0 +1,56 @@
+const JSON_HEADERS = { "Content-Type": "application/json" };
+
+/** Headers for endpoints that must not be cached (RFC 7662 §4, RFC 7009 §2.2). */
+const JSON_NOSTORE_HEADERS = {
+  "Content-Type": "application/json",
+  "Cache-Control": "no-store",
+};
+
+/** JSON response with status 200 by default. */
+export function jsonResponse(
+  body: unknown,
+  status = 200,
+  extraHeaders?: Record<string, string>,
+): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { ...JSON_HEADERS, ...extraHeaders },
+  });
+}
+
+/** JSON response with `Cache-Control: no-store`. */
+export function jsonNoStoreResponse(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: JSON_NOSTORE_HEADERS,
+  });
+}
+
+/** Standard OAuth error-shape response (`{ error, error_description }`). */
+export function oauthError(
+  code: string,
+  description: string,
+  status = 400,
+  extraHeaders?: Record<string, string>,
+): Response {
+  return jsonResponse(
+    { error: code, error_description: description },
+    status,
+    extraHeaders,
+  );
+}
+
+/**
+ * Parse a form-urlencoded body (with JSON fallback) into URLSearchParams.
+ * OAuth endpoints accept both encodings for client convenience; RFC 6749
+ * specifies form-urlencoded, but several libraries default to JSON.
+ */
+export async function parseFormBody(req: Request): Promise<URLSearchParams> {
+  const contentType = req.headers.get("content-type") ?? "";
+  if (contentType.includes("application/json")) {
+    const json = await req.json();
+    return new URLSearchParams(json as Record<string, string>);
+  }
+  const text = await req.text();
+  return new URLSearchParams(text);
+}

package/util/oauthHandlers/revoke.ts

@@ -0,0 +1,49 @@
+import { api } from "../../api";
+import { accessKey, refreshKey, tokenLookupOrder } from "./keys";
+import { parseFormBody } from "./responses";
+import type { RefreshTokenData, TokenData } from "./types";
+
+const ok = () =>
+  new Response(null, {
+    status: 200,
+    headers: { "Cache-Control": "no-store" },
+  });
+
+/**
+ * OAuth 2.0 Token Revocation endpoint (RFC 7009).
+ *
+ * Always returns 200 (even for unknown tokens or client mismatches) so callers
+ * cannot probe token state. When a token is found and the supplied `client_id`
+ * matches, the paired access+refresh keys are deleted together.
+ */
+export async function handleRevoke(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 (!token || !clientId) return ok();
+
+  const accessK = accessKey(token);
+  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;
+    if (data.clientId !== clientId) return ok();
+
+    // Discriminate by which keyspace matched, not by data shape: a seeded
+    // access token may legitimately omit `refreshToken`.
+    const pairedKey =
+      key === accessK
+        ? (data as TokenData).refreshToken
+          ? refreshKey((data as TokenData).refreshToken!)
+          : null
+        : accessKey((data as RefreshTokenData).accessToken);
+
+    await api.redis.redis.del(...(pairedKey ? [key, pairedKey] : [key]));
+    return ok();
+  }
+
+  return ok();
+}

package/util/oauthHandlers/token.ts

@@ -0,0 +1,148 @@
+import { randomUUID } from "crypto";
+import { api } from "../../api";
+import { config } from "../../config";
+import { base64UrlEncode } from "../oauth";
+import { accessKey, codeKey, refreshKey } from "./keys";
+import { jsonResponse, oauthError, parseFormBody } from "./responses";
+import type { AuthCode, RefreshTokenData, TokenData } from "./types";
+
+/**
+ * Mint a new access/refresh token pair, store both in Redis with
+ * cross-references, and return them together with the access-token TTL.
+ *
+ * The cross-reference (access token's `refreshToken`, refresh token's
+ * `accessToken`) lets `/oauth/revoke` and the `refresh_token` grant cascade the
+ * deletion to both keys without a secondary index.
+ */
+async function issueTokenPair(
+  userId: number,
+  clientId: string,
+  scopes: string[],
+): Promise<{ accessToken: string; refreshToken: string; expiresIn: number }> {
+  const accessToken = randomUUID();
+  const refreshToken = randomUUID();
+
+  const tokenData: TokenData = { userId, clientId, scopes, refreshToken };
+  const refreshData: RefreshTokenData = {
+    userId,
+    clientId,
+    scopes,
+    accessToken,
+  };
+
+  await api.redis.redis.set(
+    accessKey(accessToken),
+    JSON.stringify(tokenData),
+    "EX",
+    config.session.ttl,
+  );
+  await api.redis.redis.set(
+    refreshKey(refreshToken),
+    JSON.stringify(refreshData),
+    "EX",
+    config.server.mcp.oauthRefreshTtl,
+  );
+
+  return { accessToken, refreshToken, expiresIn: config.session.ttl };
+}
+
+function tokenResponse(
+  accessToken: string,
+  refreshToken: string,
+  expiresIn: number,
+): Response {
+  return jsonResponse({
+    access_token: accessToken,
+    refresh_token: refreshToken,
+    token_type: "Bearer",
+    expires_in: expiresIn,
+  });
+}
+
+async function handleAuthorizationCodeGrant(
+  body: URLSearchParams,
+): Promise<Response> {
+  const code = body.get("code");
+  const codeVerifier = body.get("code_verifier");
+  const redirectUri = body.get("redirect_uri");
+  const clientId = body.get("client_id");
+
+  if (!code || !codeVerifier) {
+    return oauthError("invalid_request", "code and code_verifier are required");
+  }
+
+  const codeRaw = await api.redis.redis.get(codeKey(code));
+  if (!codeRaw) {
+    return oauthError("invalid_grant", "Invalid or expired authorization code");
+  }
+
+  const codeData = JSON.parse(codeRaw) as AuthCode;
+  // Delete the code immediately (single use)
+  await api.redis.redis.del(codeKey(code));
+
+  if (clientId !== codeData.clientId) {
+    return oauthError("invalid_grant", "client_id mismatch");
+  }
+  if (redirectUri && redirectUri !== codeData.redirectUri) {
+    return oauthError("invalid_grant", "redirect_uri mismatch");
+  }
+
+  const digest = await crypto.subtle.digest(
+    "SHA-256",
+    new TextEncoder().encode(codeVerifier),
+  );
+  const computedChallenge = base64UrlEncode(new Uint8Array(digest));
+  if (computedChallenge !== codeData.codeChallenge) {
+    return oauthError("invalid_grant", "PKCE verification failed");
+  }
+
+  const pair = await issueTokenPair(codeData.userId, codeData.clientId, []);
+  return tokenResponse(pair.accessToken, pair.refreshToken, pair.expiresIn);
+}
+
+async function handleRefreshTokenGrant(
+  body: URLSearchParams,
+): Promise<Response> {
+  const refreshToken = body.get("refresh_token");
+  const clientId = body.get("client_id");
+
+  if (!refreshToken) {
+    return oauthError("invalid_request", "refresh_token is required");
+  }
+
+  const raw = await api.redis.redis.get(refreshKey(refreshToken));
+  if (!raw) {
+    return oauthError("invalid_grant", "Invalid or expired refresh token");
+  }
+
+  const stored = JSON.parse(raw) as RefreshTokenData;
+  if (clientId !== stored.clientId) {
+    return oauthError("invalid_grant", "client_id mismatch");
+  }
+
+  // Rotate: invalidate the old pair before issuing a new one. Deleting first
+  // closes the replay window if the new-pair write fails partway through.
+  await api.redis.redis.del(
+    refreshKey(refreshToken),
+    accessKey(stored.accessToken),
+  );
+
+  const pair = await issueTokenPair(
+    stored.userId,
+    stored.clientId,
+    stored.scopes,
+  );
+  return tokenResponse(pair.accessToken, pair.refreshToken, pair.expiresIn);
+}
+
+/** OAuth token exchange endpoint (RFC 6749). */
+export async function handleToken(req: Request): Promise<Response> {
+  const body = await parseFormBody(req);
+  const grantType = body.get("grant_type");
+
+  if (grantType === "authorization_code")
+    return handleAuthorizationCodeGrant(body);
+  if (grantType === "refresh_token") return handleRefreshTokenGrant(body);
+
+  return jsonResponse({ error: "unsupported_grant_type" }, 400);
+}

package/util/oauthHandlers/types.ts

@@ -0,0 +1,44 @@
+export type OAuthClient = {
+  client_id: string;
+  redirect_uris: string[];
+  client_name?: string;
+  grant_types?: string[];
+  response_types?: string[];
+  token_endpoint_auth_method?: string;
+};
+
+export type AuthCode = {
+  clientId: string;
+  userId: number;
+  codeChallenge: string;
+  redirectUri: string;
+};
+
+export type TokenData = {
+  userId: number;
+  clientId: string;
+  scopes: string[];
+  refreshToken?: string;
+};
+
+export type RefreshTokenData = {
+  userId: number;
+  clientId: string;
+  scopes: string[];
+  accessToken: string;
+};
+
+/** Route paths for the OAuth endpoints served by this framework. */
+export const OAUTH_PATHS = {
+  register: "/oauth/register",
+  authorize: "/oauth/authorize",
+  token: "/oauth/token",
+  introspect: "/oauth/introspect",
+  revoke: "/oauth/revoke",
+} as const;
+
+/** Well-known metadata paths (RFC 8414 + RFC 9728). */
+export const OAUTH_WELL_KNOWN_PATHS = {
+  authorizationServer: "/.well-known/oauth-authorization-server",
+  protectedResource: "/.well-known/oauth-protected-resource",
+} as const;

package/util/webStaticFiles.ts

@@ -1,9 +1,34 @@
+import { realpath } from "node:fs/promises";
 import path from "node:path";
 import type { parse } from "node:url";
 import { logger } from "../api";
 import { config } from "../config";
 import { getSecurityHeaders } from "./webResponse";
 
+/**
+ * Verify that the resolved on-disk path, with symlinks followed, stays
+ * inside the static root. Returns the real base path + target path if
+ * safe, or `null` if the target escapes (via symlink or otherwise).
+ */
+async function resolveWithinStaticRoot(
+  targetPath: string,
+  basePath: string,
+): Promise<string | null> {
+  try {
+    const realBase = await realpath(basePath);
+    const realTarget = await realpath(targetPath);
+    if (
+      realTarget !== realBase &&
+      !realTarget.startsWith(realBase + path.sep)
+    ) {
+      return null;
+    }
+    return realTarget;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Attempt to serve a static file for the given request. Returns a `Response`
  * if a matching file is found, or `null` to let other handlers deal with it.
@@ -54,6 +79,9 @@ export async function handleStaticFile(
         const indexFile = Bun.file(indexPath);
         const indexExists = await indexFile.exists();
         if (indexExists) {
+          if ((await resolveWithinStaticRoot(indexPath, basePath)) === null) {
+            return null;
+          }
           return buildStaticFileResponse(
             req,
             indexFile,
@@ -64,6 +92,12 @@ export async function handleStaticFile(
       return null; // File not found, let other handlers deal with it
     }
 
+    // Follow symlinks and confirm the real path stays inside staticDir —
+    // prevents symlinks inside staticDir from serving files outside it.
+    if ((await resolveWithinStaticRoot(fullPath, basePath)) === null) {
+      return null;
+    }
+
     return buildStaticFileResponse(req, file, finalPath);
   } catch (error) {
     logger.error(`Error serving static file ${finalPath}: ${error}`);

package/util/oauthHandlers.ts

@@ -1,463 +0,0 @@
-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 {
-  base64UrlEncode,
-  redirectUrisMatch,
-  validateRedirectUri,
-} from "./oauth";
-import {
-  type AuthPageParams,
-  type OAuthTemplates,
-  renderAuthPage,
-  renderSuccessPage,
-} from "./oauthTemplates";
-
-export type OAuthClient = {
-  client_id: string;
-  redirect_uris: string[];
-  client_name?: string;
-  grant_types?: string[];
-  response_types?: string[];
-  token_endpoint_auth_method?: string;
-};
-
-export type AuthCode = {
-  clientId: string;
-  userId: number;
-  codeChallenge: string;
-  redirectUri: string;
-};
-
-export type TokenData = {
-  userId: number;
-  clientId: string;
-  scopes: string[];
-};
-
-/** 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",
-]);
-
-/**
- * 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 new Response(
-    JSON.stringify({
-      resource,
-      authorization_servers: [origin],
-      scopes_supported: ["mcp"],
-    }),
-    {
-      status: 200,
-      headers: { "Content-Type": "application/json" },
-    },
-  );
-}
-
-/** OAuth 2.1 authorization server metadata endpoint. */
-export function handleMetadata(origin: string): Response {
-  const issuer = origin;
-  return new Response(
-    JSON.stringify({
-      issuer,
-      authorization_endpoint: `${issuer}/oauth/authorize`,
-      token_endpoint: `${issuer}/oauth/token`,
-      registration_endpoint: `${issuer}/oauth/register`,
-      response_types_supported: ["code"],
-      grant_types_supported: ["authorization_code"],
-      code_challenge_methods_supported: ["S256"],
-      token_endpoint_auth_methods_supported: ["none"],
-      client_id_metadata_document_supported: false,
-    }),
-    {
-      status: 200,
-      headers: { "Content-Type": "application/json" },
-    },
-  );
-}
-
-/** Dynamic client registration endpoint (RFC 7591). */
-export async function handleRegister(req: Request): Promise<Response> {
-  let body: any;
-  try {
-    body = await req.json();
-  } catch {
-    return new Response(
-      JSON.stringify({
-        error: "invalid_request",
-        error_description: "Invalid JSON body",
-      }),
-      { status: 400, headers: { "Content-Type": "application/json" } },
-    );
-  }
-
-  if (
-    !body.redirect_uris ||
-    !Array.isArray(body.redirect_uris) ||
-    body.redirect_uris.length === 0
-  ) {
-    return new Response(
-      JSON.stringify({
-        error: "invalid_request",
-        error_description: "redirect_uris is required",
-      }),
-      { status: 400, headers: { "Content-Type": "application/json" } },
-    );
-  }
-
-  for (const uri of body.redirect_uris) {
-    if (typeof uri !== "string") {
-      return new Response(
-        JSON.stringify({
-          error: "invalid_request",
-          error_description: "Each redirect_uri must be a string",
-        }),
-        { status: 400, headers: { "Content-Type": "application/json" } },
-      );
-    }
-    const validation = validateRedirectUri(uri);
-    if (!validation.valid) {
-      return new Response(
-        JSON.stringify({
-          error: "invalid_request",
-          error_description: validation.error,
-        }),
-        { status: 400, headers: { "Content-Type": "application/json" } },
-      );
-    }
-  }
-
-  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(
-    `oauth:client:${clientId}`,
-    JSON.stringify(client),
-    "EX",
-    config.server.mcp.oauthClientTtl,
-  );
-
-  return new Response(JSON.stringify(client), {
-    status: 201,
-    headers: { "Content-Type": "application/json" },
-  });
-}
-
-/** 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, {
-    loginAction: api.actions.actions.find((a: Action) => a.mcp?.isLoginAction),
-    signupAction: api.actions.actions.find(
-      (a: Action) => a.mcp?.isSignupAction,
-    ),
-  });
-}
-
-/** 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 mode = fields.mode ?? "";
-  const clientId = fields.client_id ?? "";
-  const redirectUri = fields.redirect_uri ?? "";
-  const codeChallenge = fields.code_challenge ?? "";
-  const codeChallengeMethod = fields.code_challenge_method ?? "";
-  const responseType = fields.response_type ?? "";
-  const state = fields.state ?? "";
-
-  const oauthParams: AuthPageParams = {
-    clientId,
-    redirectUri,
-    codeChallenge,
-    codeChallengeMethod,
-    responseType,
-    state,
-    error: "",
-  };
-
-  const authActions = {
-    loginAction: api.actions.actions.find((a: Action) => a.mcp?.isLoginAction),
-    signupAction: api.actions.actions.find(
-      (a: Action) => a.mcp?.isSignupAction,
-    ),
-  };
-
-  // Validate client
-  const clientRaw = await api.redis.redis.get(`oauth:client:${clientId}`);
-  if (!clientRaw) {
-    oauthParams.error = "Unknown client";
-    return renderAuthPage(oauthParams, templates, authActions);
-  }
-  const client = JSON.parse(clientRaw) as OAuthClient;
-
-  const uriMatch = client.redirect_uris.some((registered) =>
-    redirectUrisMatch(registered, redirectUri),
-  );
-  if (!uriMatch) {
-    oauthParams.error = "Invalid redirect URI";
-    return renderAuthPage(oauthParams, templates, authActions);
-  }
-
-  if (codeChallengeMethod !== "S256") {
-    oauthParams.error = "code_challenge_method must be S256";
-    return renderAuthPage(oauthParams, templates, authActions);
-  }
-
-  // Build action params from all non-OAuth fields
-  const actionParams: Record<string, unknown> = {};
-  for (const [key, value] of Object.entries(fields)) {
-    if (!OAUTH_FIELDS.has(key)) {
-      actionParams[key] = value;
-    }
-  }
-
-  let userId: number;
-
-  if (mode === "signup") {
-    const signupAction = api.actions.actions.find(
-      (a: Action) => a.mcp?.isSignupAction,
-    );
-    if (!signupAction) {
-      oauthParams.error = "No signup action configured";
-      return renderAuthPage(oauthParams, templates, authActions);
-    }
-    const connection = new Connection("oauth", "oauth-signup");
-    try {
-      const { response, error } = await connection.act(
-        signupAction.name,
-        actionParams,
-      );
-      if (error) {
-        oauthParams.error = error.message;
-        return renderAuthPage(oauthParams, templates, authActions);
-      }
-      userId = (response as OAuthActionResponse).user.id;
-    } finally {
-      connection.destroy();
-    }
-  } else {
-    const loginAction = api.actions.actions.find(
-      (a: Action) => a.mcp?.isLoginAction,
-    );
-    if (!loginAction) {
-      oauthParams.error = "No login action configured";
-      return renderAuthPage(oauthParams, templates, authActions);
-    }
-    const connection = new Connection("oauth", "oauth-login");
-    try {
-      const { response, error } = await connection.act(
-        loginAction.name,
-        actionParams,
-      );
-      if (error) {
-        oauthParams.error = error.message;
-        return renderAuthPage(oauthParams, templates, authActions);
-      }
-      userId = (response as OAuthActionResponse).user.id;
-    } finally {
-      connection.destroy();
-    }
-  }
-
-  // Generate auth code
-  const code = randomUUID();
-  const codeData: AuthCode = {
-    clientId,
-    userId,
-    codeChallenge,
-    redirectUri,
-  };
-
-  await api.redis.redis.set(
-    `oauth:code:${code}`,
-    JSON.stringify(codeData),
-    "EX",
-    config.server.mcp.oauthCodeTtl,
-  );
-
-  const redirectUrl = new URL(redirectUri);
-  redirectUrl.searchParams.set("code", code);
-  if (state) redirectUrl.searchParams.set("state", state);
-
-  return renderSuccessPage(redirectUrl.toString(), templates);
-}
-
-/** OAuth token exchange endpoint. */
-export async function handleToken(req: Request): Promise<Response> {
-  let body: URLSearchParams;
-  const contentType = req.headers.get("content-type") ?? "";
-
-  if (contentType.includes("application/x-www-form-urlencoded")) {
-    const text = await req.text();
-    body = new URLSearchParams(text);
-  } else if (contentType.includes("application/json")) {
-    const json = await req.json();
-    body = new URLSearchParams(json as Record<string, string>);
-  } else {
-    // Try form-urlencoded as default
-    const text = await req.text();
-    body = new URLSearchParams(text);
-  }
-
-  const grantType = body.get("grant_type");
-  const code = body.get("code");
-  const codeVerifier = body.get("code_verifier");
-  const redirectUri = body.get("redirect_uri");
-  const clientId = body.get("client_id");
-
-  if (grantType !== "authorization_code") {
-    return new Response(JSON.stringify({ error: "unsupported_grant_type" }), {
-      status: 400,
-      headers: { "Content-Type": "application/json" },
-    });
-  }
-
-  if (!code || !codeVerifier) {
-    return new Response(
-      JSON.stringify({
-        error: "invalid_request",
-        error_description: "code and code_verifier are required",
-      }),
-      { status: 400, headers: { "Content-Type": "application/json" } },
-    );
-  }
-
-  // Look up auth code
-  const codeRaw = await api.redis.redis.get(`oauth:code:${code}`);
-  if (!codeRaw) {
-    return new Response(
-      JSON.stringify({
-        error: "invalid_grant",
-        error_description: "Invalid or expired authorization code",
-      }),
-      { status: 400, headers: { "Content-Type": "application/json" } },
-    );
-  }
-
-  const codeData = JSON.parse(codeRaw) as AuthCode;
-
-  // Delete the code immediately (single use)
-  await api.redis.redis.del(`oauth:code:${code}`);
-
-  // Validate client_id matches
-  if (clientId !== codeData.clientId) {
-    return new Response(
-      JSON.stringify({
-        error: "invalid_grant",
-        error_description: "client_id mismatch",
-      }),
-      { status: 400, headers: { "Content-Type": "application/json" } },
-    );
-  }
-
-  // Validate redirect_uri matches
-  if (redirectUri && redirectUri !== codeData.redirectUri) {
-    return new Response(
-      JSON.stringify({
-        error: "invalid_grant",
-        error_description: "redirect_uri mismatch",
-      }),
-      { status: 400, headers: { "Content-Type": "application/json" } },
-    );
-  }
-
-  // Verify PKCE: BASE64URL(SHA256(code_verifier)) === stored code_challenge
-  const encoder = new TextEncoder();
-  const digest = await crypto.subtle.digest(
-    "SHA-256",
-    encoder.encode(codeVerifier),
-  );
-  const computedChallenge = base64UrlEncode(new Uint8Array(digest));
-
-  if (computedChallenge !== codeData.codeChallenge) {
-    return new Response(
-      JSON.stringify({
-        error: "invalid_grant",
-        error_description: "PKCE verification failed",
-      }),
-      { status: 400, headers: { "Content-Type": "application/json" } },
-    );
-  }
-
-  // Generate access token
-  const accessToken = randomUUID();
-  const tokenData: TokenData = {
-    userId: codeData.userId,
-    clientId: codeData.clientId,
-    scopes: [],
-  };
-
-  await api.redis.redis.set(
-    `oauth:token:${accessToken}`,
-    JSON.stringify(tokenData),
-    "EX",
-    config.session.ttl,
-  );
-
-  return new Response(
-    JSON.stringify({
-      access_token: accessToken,
-      token_type: "Bearer",
-      expires_in: config.session.ttl,
-    }),
-    {
-      status: 200,
-      headers: { "Content-Type": "application/json" },
-    },
-  );
-}