harper-knowledge 0.1.0

package/dist/oauth/authorize.js

@@ -0,0 +1,438 @@
+/**
+ * OAuth Authorization Endpoint
+ *
+ * GET /oauth/authorize — MCP OAuth 2.1 authorization endpoint.
+ *
+ * Shows a login page with GitHub as the primary auth method and a
+ * subtle link to fall back to Harper credentials. If the user has an
+ * active session (from a prior GitHub login), issues an auth code
+ * immediately.
+ *
+ * Org membership is checked against the ALLOWED_GITHUB_ORGS env var
+ * for GitHub logins. Harper credential logins bypass org checks.
+ */
+import crypto from "node:crypto";
+import { readBody, parseFormBody } from "../http-utils.js";
+import { checkOrgMembership } from "./github.js";
+/**
+ * Handle GET /oauth/authorize
+ *
+ * Three modes:
+ * 1. Returning from GitHub login (`pending` param) — complete authorization.
+ * 2. User already has a session — issue auth code directly.
+ * 3. First visit — show login page with GitHub button + Harper credentials.
+ */
+export async function handleAuthorizeGet(request) {
+    const url = new URL(request.url || request.pathname || "/", `http://${request.host || "localhost"}`);
+    const pendingId = url.searchParams.get("pending");
+    // Returning from GitHub login — complete the authorization
+    if (pendingId) {
+        return handleAuthorizeComplete(request, pendingId);
+    }
+    // First visit — extract and validate OAuth params
+    const params = extractParams(url.searchParams);
+    const validation = await validateAuthorizeParams(params);
+    if (validation.error) {
+        return errorPage(validation.error);
+    }
+    // If user already has a session from @harperfast/oauth, issue code directly
+    const session = request.session;
+    if (session?.user && session?.oauth?.accessToken) {
+        return issueAuthCodeGitHub(request, params, session);
+    }
+    // Show login page
+    return loginPage(params);
+}
+/**
+ * Handle POST /oauth/authorize — Harper credential login.
+ */
+export async function handleAuthorizePost(request) {
+    let form;
+    try {
+        const rawBody = await readBody(request);
+        form = parseFormBody(rawBody);
+    }
+    catch {
+        return errorPage("Invalid request body");
+    }
+    const username = form.username || "";
+    const password = form.password || "";
+    // Reconstruct the OAuth params from the hidden form fields
+    const params = {
+        client_id: form.client_id || "",
+        redirect_uri: form.redirect_uri || "",
+        response_type: form.response_type || "code",
+        state: form.state || "",
+        code_challenge: form.code_challenge || "",
+        code_challenge_method: form.code_challenge_method || "S256",
+        scope: form.scope || "mcp:read mcp:write",
+    };
+    // Re-validate OAuth params
+    const validation = await validateAuthorizeParams(params);
+    if (validation.error) {
+        return errorPage(validation.error);
+    }
+    if (!username || !password) {
+        return loginPage(params, "Username and password are required.");
+    }
+    // Validate credentials against Harper Operations API
+    const valid = await validateHarperCredentials(username, password);
+    if (!valid) {
+        return loginPage(params, "Invalid username or password.");
+    }
+    // Issue authorization code for Harper user
+    const code = crypto.randomUUID();
+    await databases.kb.OAuthCode.put({
+        id: code,
+        clientId: params.client_id,
+        userId: `harper:${username}`,
+        scope: params.scope,
+        codeChallenge: params.code_challenge,
+        codeChallengeMethod: params.code_challenge_method,
+        redirectUri: params.redirect_uri,
+        type: "code",
+    });
+    const redirectUrl = new URL(params.redirect_uri);
+    redirectUrl.searchParams.set("code", code);
+    redirectUrl.searchParams.set("state", params.state);
+    logger?.info?.(`OAuth code issued for Harper user ${username}, client ${params.client_id}`);
+    return new Response(null, {
+        status: 302,
+        headers: { Location: redirectUrl.toString() },
+    });
+}
+/**
+ * Complete authorization after the user returns from GitHub login.
+ */
+async function handleAuthorizeComplete(request, pendingId) {
+    const session = request.session;
+    if (!session?.user) {
+        return errorPage("Authentication required. Please try again.");
+    }
+    // Look up the stored OAuth params
+    const pending = await databases.kb.OAuthCode.get(pendingId);
+    if (!pending || pending.type !== "pending") {
+        return errorPage("Authorization session expired. Please try again.");
+    }
+    // Delete the pending record (one-time use)
+    await databases.kb.OAuthCode.delete(pendingId);
+    // Check org membership using the GitHub access token from the session
+    const accessToken = session?.oauth?.accessToken;
+    if (!accessToken) {
+        return errorPage("No GitHub access token in session. Please try logging in again.");
+    }
+    const authorized = await checkOrgMembership(accessToken);
+    if (!authorized) {
+        const username = session.oauthUser?.username || session.user;
+        logger?.warn?.(`OAuth denied: user ${username} not in allowed orgs`);
+        return errorPage(`User ${username} is not a member of an authorized GitHub organization.`);
+    }
+    // Issue authorization code
+    const code = crypto.randomUUID();
+    const mcpClientState = pending.userId;
+    const username = session.oauthUser?.username || session.user;
+    await databases.kb.OAuthCode.put({
+        id: code,
+        clientId: pending.clientId,
+        userId: `github:${username}`,
+        scope: pending.scope,
+        codeChallenge: pending.codeChallenge,
+        codeChallengeMethod: pending.codeChallengeMethod,
+        redirectUri: pending.redirectUri,
+        type: "code",
+    });
+    const redirectUrl = new URL(pending.redirectUri);
+    redirectUrl.searchParams.set("code", code);
+    redirectUrl.searchParams.set("state", mcpClientState);
+    logger?.info?.(`OAuth code issued for user ${username}, client ${pending.clientId}`);
+    return new Response(null, {
+        status: 302,
+        headers: { Location: redirectUrl.toString() },
+    });
+}
+/**
+ * Issue an auth code immediately (user already has a GitHub session).
+ */
+async function issueAuthCodeGitHub(_request, params, session) {
+    const accessToken = session.oauth?.accessToken;
+    if (!accessToken) {
+        return errorPage("No GitHub access token in session. Please try logging in again.");
+    }
+    const authorized = await checkOrgMembership(accessToken);
+    if (!authorized) {
+        const username = session.oauthUser?.username || session.user;
+        logger?.warn?.(`OAuth denied: user ${username} not in allowed orgs`);
+        return errorPage(`User ${username} is not a member of an authorized GitHub organization.`);
+    }
+    const code = crypto.randomUUID();
+    const username = session.oauthUser?.username || session.user;
+    await databases.kb.OAuthCode.put({
+        id: code,
+        clientId: params.client_id,
+        userId: `github:${username}`,
+        scope: params.scope,
+        codeChallenge: params.code_challenge,
+        codeChallengeMethod: params.code_challenge_method,
+        redirectUri: params.redirect_uri,
+        type: "code",
+    });
+    const redirectUrl = new URL(params.redirect_uri);
+    redirectUrl.searchParams.set("code", code);
+    redirectUrl.searchParams.set("state", params.state);
+    logger?.info?.(`OAuth code issued for user ${username}, client ${params.client_id}`);
+    return new Response(null, {
+        status: 302,
+        headers: { Location: redirectUrl.toString() },
+    });
+}
+/**
+ * Validate credentials against Harper's Operations API (localhost:9925).
+ */
+async function validateHarperCredentials(username, password) {
+    try {
+        const response = await fetch("http://localhost:9925/", {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: `Basic ${Buffer.from(`${username}:${password}`).toString("base64")}`,
+            },
+            body: JSON.stringify({ operation: "user_info" }),
+        });
+        return response.ok;
+    }
+    catch (error) {
+        logger?.error?.("Harper credential validation failed:", error.message);
+        return false;
+    }
+}
+function extractParams(searchParams) {
+    return {
+        client_id: searchParams.get("client_id") || "",
+        redirect_uri: searchParams.get("redirect_uri") || "",
+        response_type: searchParams.get("response_type") || "",
+        state: searchParams.get("state") || "",
+        code_challenge: searchParams.get("code_challenge") || "",
+        code_challenge_method: searchParams.get("code_challenge_method") || "",
+        scope: searchParams.get("scope") || "mcp:read mcp:write",
+    };
+}
+async function validateAuthorizeParams(params) {
+    if (!params.client_id) {
+        return { error: "Missing required parameter: client_id" };
+    }
+    if (!params.redirect_uri) {
+        return { error: "Missing required parameter: redirect_uri" };
+    }
+    if (params.response_type !== "code") {
+        return { error: 'response_type must be "code"' };
+    }
+    if (!params.state) {
+        return { error: "Missing required parameter: state" };
+    }
+    if (!params.code_challenge) {
+        return {
+            error: "Missing required parameter: code_challenge (PKCE is required)",
+        };
+    }
+    if (params.code_challenge_method !== "S256") {
+        return { error: 'code_challenge_method must be "S256"' };
+    }
+    // Validate client exists
+    const client = await databases.kb.OAuthClient.get(params.client_id);
+    if (!client) {
+        return { error: "Unknown client_id" };
+    }
+    // Validate redirect_uri matches registration (exact match)
+    const registeredUris = client.redirectUris;
+    if (!registeredUris || !registeredUris.includes(params.redirect_uri)) {
+        return {
+            error: "redirect_uri does not match any registered URI for this client",
+        };
+    }
+    return {};
+}
+/**
+ * Build the GitHub login redirect URL, stashing OAuth params in the DB.
+ */
+async function buildGitHubLoginUrl(params) {
+    const pendingId = crypto.randomUUID();
+    await databases.kb.OAuthCode.put({
+        id: pendingId,
+        clientId: params.client_id,
+        userId: params.state,
+        scope: params.scope,
+        codeChallenge: params.code_challenge,
+        codeChallengeMethod: params.code_challenge_method,
+        redirectUri: params.redirect_uri,
+        type: "pending",
+    });
+    const returnPath = `/oauth/authorize?pending=${pendingId}`;
+    return `/oauth/github/login?redirect=${encodeURIComponent(returnPath)}`;
+}
+/**
+ * Render the login page.
+ */
+async function loginPage(params, errorMsg) {
+    const githubLoginUrl = await buildGitHubLoginUrl(params);
+    const clientName = (await databases.kb.OAuthClient.get(params.client_id))
+        ?.clientName || params.client_id;
+    const errorHtml = errorMsg
+        ? `<div class="error-msg">${escapeHtml(errorMsg)}</div>`
+        : "";
+    const html = `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Authorize — Harper Knowledge</title>
+<style>
+  * { box-sizing: border-box; margin: 0; padding: 0; }
+  body {
+    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+    background: #0f1117; color: #e1e4e8;
+    display: flex; align-items: center; justify-content: center;
+    min-height: 100vh; padding: 1rem;
+  }
+  .card {
+    background: #1c1f26; border: 1px solid #2d333b; border-radius: 12px;
+    padding: 2rem; width: 100%; max-width: 380px;
+  }
+  h1 { font-size: 1.15rem; font-weight: 600; margin-bottom: 0.25rem; }
+  .subtitle { color: #8b949e; font-size: 0.85rem; margin-bottom: 1.5rem; }
+  .client-name { color: #c9d1d9; font-weight: 500; }
+  .github-btn {
+    display: flex; align-items: center; justify-content: center; gap: 0.5rem;
+    width: 100%; padding: 0.7rem 1rem;
+    background: #238636; color: #fff; border: none; border-radius: 6px;
+    font-size: 0.95rem; font-weight: 500; cursor: pointer;
+    text-decoration: none; transition: background 0.15s;
+  }
+  .github-btn:hover { background: #2ea043; }
+  .github-btn svg { width: 20px; height: 20px; fill: currentColor; }
+  .divider {
+    display: flex; align-items: center; gap: 0.75rem;
+    margin: 1.25rem 0; color: #484f58; font-size: 0.8rem;
+  }
+  .divider::before, .divider::after {
+    content: ''; flex: 1; height: 1px; background: #2d333b;
+  }
+  .cred-toggle {
+    display: block; width: 100%; text-align: center;
+    color: #484f58; font-size: 0.8rem; background: none; border: none;
+    cursor: pointer; padding: 0.25rem; transition: color 0.15s;
+  }
+  .cred-toggle:hover { color: #8b949e; }
+  .cred-form { display: none; margin-top: 1rem; }
+  .cred-form.visible { display: block; }
+  label {
+    display: block; color: #8b949e; font-size: 0.8rem; margin-bottom: 0.25rem;
+  }
+  input[type="text"], input[type="password"] {
+    width: 100%; padding: 0.5rem 0.6rem;
+    background: #0d1117; border: 1px solid #2d333b; border-radius: 6px;
+    color: #e1e4e8; font-size: 0.9rem; margin-bottom: 0.75rem;
+    outline: none; transition: border-color 0.15s;
+  }
+  input:focus { border-color: #58a6ff; }
+  .submit-btn {
+    width: 100%; padding: 0.6rem 1rem;
+    background: #21262d; color: #c9d1d9; border: 1px solid #363b42;
+    border-radius: 6px; font-size: 0.9rem; cursor: pointer;
+    transition: background 0.15s, border-color 0.15s;
+  }
+  .submit-btn:hover { background: #30363d; border-color: #484f58; }
+  .error-msg {
+    background: #3d1214; border: 1px solid #da3633; border-radius: 6px;
+    color: #f85149; font-size: 0.85rem; padding: 0.5rem 0.75rem;
+    margin-bottom: 1rem;
+  }
+</style>
+</head>
+<body>
+<div class="card">
+  <h1>Authorize</h1>
+  <p class="subtitle"><span class="client-name">${escapeHtml(clientName)}</span> wants to access Harper Knowledge</p>
+  ${errorHtml}
+  <a href="${escapeAttr(githubLoginUrl)}" class="github-btn">
+    <svg viewBox="0 0 16 16"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg>
+    Sign in with GitHub
+  </a>
+  <div class="divider">or</div>
+  <button type="button" class="cred-toggle" onclick="document.querySelector('.cred-form').classList.toggle('visible');this.style.display='none'">
+    Sign in with Harper credentials
+  </button>
+  <form method="POST" action="/oauth/authorize" class="cred-form${errorMsg ? " visible" : ""}">
+    <input type="hidden" name="client_id" value="${escapeAttr(params.client_id)}">
+    <input type="hidden" name="redirect_uri" value="${escapeAttr(params.redirect_uri)}">
+    <input type="hidden" name="response_type" value="${escapeAttr(params.response_type)}">
+    <input type="hidden" name="state" value="${escapeAttr(params.state)}">
+    <input type="hidden" name="code_challenge" value="${escapeAttr(params.code_challenge)}">
+    <input type="hidden" name="code_challenge_method" value="${escapeAttr(params.code_challenge_method)}">
+    <input type="hidden" name="scope" value="${escapeAttr(params.scope)}">
+    <label for="username">Username</label>
+    <input type="text" id="username" name="username" autocomplete="username" required>
+    <label for="password">Password</label>
+    <input type="password" id="password" name="password" autocomplete="current-password" required>
+    <button type="submit" class="submit-btn">Sign in</button>
+  </form>
+</div>
+</body>
+</html>`;
+    return new Response(html, {
+        status: errorMsg ? 400 : 200,
+        headers: {
+            "Content-Type": "text/html; charset=utf-8",
+            "X-Frame-Options": "DENY",
+            "X-Content-Type-Options": "nosniff",
+            "Referrer-Policy": "no-referrer",
+            "Content-Security-Policy": "default-src 'none'; style-src 'unsafe-inline'; form-action 'self'",
+        },
+    });
+}
+function errorPage(message) {
+    const html = `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>Authorization Error</title>
+<style>
+  body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+    background: #0f1117; color: #e1e4e8;
+    display: flex; align-items: center; justify-content: center; min-height: 100vh; }
+  .error { background: #1c1f26; border: 1px solid #da3633; border-radius: 12px;
+    padding: 2rem; max-width: 420px; }
+  h1 { color: #f85149; font-size: 1.1rem; margin-bottom: 0.5rem; }
+</style>
+</head>
+<body>
+<div class="error">
+  <h1>Authorization Error</h1>
+  <p>${escapeHtml(message)}</p>
+</div>
+</body>
+</html>`;
+    return new Response(html, {
+        status: 400,
+        headers: {
+            "Content-Type": "text/html; charset=utf-8",
+            "X-Frame-Options": "DENY",
+            "X-Content-Type-Options": "nosniff",
+            "Referrer-Policy": "no-referrer",
+            "Content-Security-Policy": "default-src 'none'; style-src 'unsafe-inline'; form-action 'self'",
+        },
+    });
+}
+function escapeHtml(s) {
+    return s
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;");
+}
+function escapeAttr(s) {
+    return s
+        .replace(/&/g, "&amp;")
+        .replace(/"/g, "&quot;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;");
+}

package/dist/oauth/github.d.ts

@@ -0,0 +1,28 @@
+/**
+ * GitHub Org Membership Check
+ *
+ * Checks if a GitHub user belongs to an allowed organization.
+ * The actual GitHub OAuth login is handled by @harperfast/oauth —
+ * this module only does the org allowlist check using the session's
+ * GitHub access token.
+ *
+ * Configuration:
+ *   ALLOWED_GITHUB_ORGS — Comma-separated list of allowed GitHub org logins.
+ *     Empty/unset = deny all (secure by default).
+ *     "*" = allow any authenticated user.
+ */
+/**
+ * Parse the ALLOWED_GITHUB_ORGS environment variable.
+ */
+export declare function getAllowedOrgs(): string[];
+/**
+ * Check if a GitHub user belongs to an allowed org.
+ *
+ * Uses the GitHub access token from the @harperfast/oauth session
+ * to query the GitHub API for the user's org memberships.
+ *
+ * - Empty/unset ALLOWED_GITHUB_ORGS → deny all
+ * - ALLOWED_GITHUB_ORGS="*" → allow any authenticated user
+ * - ALLOWED_GITHUB_ORGS="org1,org2" → allow members of listed orgs
+ */
+export declare function checkOrgMembership(accessToken: string): Promise<boolean>;

package/dist/oauth/github.js

@@ -0,0 +1,62 @@
+/**
+ * GitHub Org Membership Check
+ *
+ * Checks if a GitHub user belongs to an allowed organization.
+ * The actual GitHub OAuth login is handled by @harperfast/oauth —
+ * this module only does the org allowlist check using the session's
+ * GitHub access token.
+ *
+ * Configuration:
+ *   ALLOWED_GITHUB_ORGS — Comma-separated list of allowed GitHub org logins.
+ *     Empty/unset = deny all (secure by default).
+ *     "*" = allow any authenticated user.
+ */
+const GITHUB_API_URL = "https://api.github.com";
+/**
+ * Parse the ALLOWED_GITHUB_ORGS environment variable.
+ */
+export function getAllowedOrgs() {
+    const orgsEnv = process.env.ALLOWED_GITHUB_ORGS || "";
+    return orgsEnv
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean);
+}
+/**
+ * Check if a GitHub user belongs to an allowed org.
+ *
+ * Uses the GitHub access token from the @harperfast/oauth session
+ * to query the GitHub API for the user's org memberships.
+ *
+ * - Empty/unset ALLOWED_GITHUB_ORGS → deny all
+ * - ALLOWED_GITHUB_ORGS="*" → allow any authenticated user
+ * - ALLOWED_GITHUB_ORGS="org1,org2" → allow members of listed orgs
+ */
+export async function checkOrgMembership(accessToken) {
+    const allowedOrgs = getAllowedOrgs();
+    if (allowedOrgs.length === 0) {
+        return false;
+    }
+    if (allowedOrgs.includes("*")) {
+        return true;
+    }
+    try {
+        const response = await fetch(`${GITHUB_API_URL}/user/orgs`, {
+            headers: {
+                Authorization: `Bearer ${accessToken}`,
+                Accept: "application/vnd.github+json",
+            },
+        });
+        if (!response.ok) {
+            logger?.error?.("Failed to fetch GitHub user orgs");
+            return false;
+        }
+        const orgs = (await response.json());
+        const userOrgLogins = orgs.map((o) => o.login.toLowerCase());
+        return allowedOrgs.some((allowed) => userOrgLogins.includes(allowed.toLowerCase()));
+    }
+    catch (error) {
+        logger?.error?.("GitHub org membership check failed:", error.message);
+        return false;
+    }
+}

package/dist/oauth/keys.d.ts

@@ -0,0 +1,33 @@
+/**
+ * OAuth RSA Key Management
+ *
+ * Generates, stores, loads, and caches an RS256 key pair for signing JWT
+ * access tokens. The key is stored in the OAuthSigningKey table so all
+ * Harper worker threads share the same key.
+ */
+import { type JWK } from "jose";
+/**
+ * Ensure a signing key exists. Loads from DB or generates a new one.
+ * Called once during handleApplication() on each worker thread.
+ */
+export declare function ensureSigningKey(): Promise<void>;
+/**
+ * Get the private key for signing JWTs.
+ * Lazily initializes if not yet loaded.
+ */
+export declare function getPrivateKey(): Promise<CryptoKey>;
+/**
+ * Get the public key JWK for token verification and JWKS endpoint.
+ * Lazily initializes if not yet loaded.
+ */
+export declare function getPublicKeyJwk(): Promise<JWK>;
+/**
+ * Get the key ID for the JWT header.
+ */
+export declare function getKeyId(): string;
+/**
+ * Get the JWKS response body for the /oauth/jwks endpoint.
+ */
+export declare function getJwks(): Promise<{
+    keys: JWK[];
+}>;

package/dist/oauth/keys.js

@@ -0,0 +1,100 @@
+/**
+ * OAuth RSA Key Management
+ *
+ * Generates, stores, loads, and caches an RS256 key pair for signing JWT
+ * access tokens. The key is stored in the OAuthSigningKey table so all
+ * Harper worker threads share the same key.
+ */
+import { generateKeyPair, exportJWK, importJWK } from "jose";
+const KEY_ID = "primary";
+let cachedPrivateKey = null;
+let cachedPublicKeyJwk = null;
+/**
+ * Ensure a signing key exists. Loads from DB or generates a new one.
+ * Called once during handleApplication() on each worker thread.
+ */
+export async function ensureSigningKey() {
+    const existing = await databases.kb.OAuthSigningKey.get(KEY_ID);
+    if (existing && existing.publicKeyJwk && existing.privateKeyJwk) {
+        cachedPublicKeyJwk = toJwk(existing.publicKeyJwk);
+        cachedPrivateKey = (await importJWK(toJwk(existing.privateKeyJwk), "RS256"));
+        logger?.info?.("OAuth signing key loaded from database");
+        return;
+    }
+    // Generate a new RSA key pair
+    const { publicKey, privateKey } = await generateKeyPair("RS256", {
+        extractable: true,
+    });
+    const pubJwk = await exportJWK(publicKey);
+    const privJwk = await exportJWK(privateKey);
+    pubJwk.kid = KEY_ID;
+    pubJwk.use = "sig";
+    pubJwk.alg = "RS256";
+    try {
+        await databases.kb.OAuthSigningKey.put({
+            id: KEY_ID,
+            publicKeyJwk: JSON.stringify(pubJwk),
+            privateKeyJwk: JSON.stringify(privJwk),
+            algorithm: "RS256",
+        });
+    }
+    catch {
+        // Another worker may have created the key concurrently — reload
+        const reloaded = await databases.kb.OAuthSigningKey.get(KEY_ID);
+        if (reloaded && reloaded.publicKeyJwk && reloaded.privateKeyJwk) {
+            cachedPublicKeyJwk = toJwk(reloaded.publicKeyJwk);
+            cachedPrivateKey = (await importJWK(toJwk(reloaded.privateKeyJwk), "RS256"));
+            logger?.info?.("OAuth signing key loaded after concurrent creation");
+            return;
+        }
+        throw new Error("Failed to create or load OAuth signing key");
+    }
+    cachedPrivateKey = privateKey;
+    cachedPublicKeyJwk = pubJwk;
+    logger?.info?.("OAuth signing key generated and stored");
+}
+/**
+ * Get the private key for signing JWTs.
+ * Lazily initializes if not yet loaded.
+ */
+export async function getPrivateKey() {
+    if (!cachedPrivateKey) {
+        await ensureSigningKey();
+    }
+    return cachedPrivateKey;
+}
+/**
+ * Get the public key JWK for token verification and JWKS endpoint.
+ * Lazily initializes if not yet loaded.
+ */
+export async function getPublicKeyJwk() {
+    if (!cachedPublicKeyJwk) {
+        await ensureSigningKey();
+    }
+    return cachedPublicKeyJwk;
+}
+/**
+ * Get the key ID for the JWT header.
+ */
+export function getKeyId() {
+    return KEY_ID;
+}
+/**
+ * Get the JWKS response body for the /oauth/jwks endpoint.
+ */
+export async function getJwks() {
+    return { keys: [await getPublicKeyJwk()] };
+}
+/**
+ * Normalize a value from Harper's table into a JWK object.
+ * Harper's `Any` column type may return the JWK as a string or wrapped object.
+ */
+function toJwk(value) {
+    if (typeof value === "string") {
+        return JSON.parse(value);
+    }
+    if (value && typeof value === "object") {
+        return value;
+    }
+    throw new Error(`Cannot convert ${typeof value} to JWK`);
+}

package/dist/oauth/metadata.d.ts

@@ -0,0 +1,21 @@
+/**
+ * OAuth Metadata Endpoints
+ *
+ * Serves RFC 9728 Protected Resource Metadata and RFC 8414 Authorization
+ * Server Metadata at their well-known URLs.
+ */
+import type { HarperRequest } from "../types.ts";
+/**
+ * Handle GET /.well-known/oauth-protected-resource
+ *
+ * RFC 9728 — tells MCP clients where to find the authorization server
+ * and what scopes are supported.
+ */
+export declare function handleProtectedResourceMetadata(request: HarperRequest): Response;
+/**
+ * Handle GET /.well-known/oauth-authorization-server
+ *
+ * RFC 8414 — describes the authorization server's capabilities,
+ * endpoints, and supported grant types.
+ */
+export declare function handleAuthServerMetadata(request: HarperRequest): Response;