keryx 0.22.0 → 0.23.0

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