harper-knowledge 0.1.0

package/dist/oauth/metadata.js

@@ -0,0 +1,55 @@
+/**
+ * OAuth Metadata Endpoints
+ *
+ * Serves RFC 9728 Protected Resource Metadata and RFC 8414 Authorization
+ * Server Metadata at their well-known URLs.
+ */
+import { getBaseUrl } from "../http-utils.js";
+const SCOPES = ["mcp:read", "mcp:write"];
+/**
+ * Handle GET /.well-known/oauth-protected-resource
+ *
+ * RFC 9728 — tells MCP clients where to find the authorization server
+ * and what scopes are supported.
+ */
+export function handleProtectedResourceMetadata(request) {
+    const baseUrl = getBaseUrl(request);
+    return jsonResponse(200, {
+        resource: `${baseUrl}/mcp`,
+        authorization_servers: [baseUrl],
+        scopes_supported: SCOPES,
+        bearer_methods_supported: ["header"],
+        resource_name: "Harper Knowledge Base MCP Server",
+    });
+}
+/**
+ * Handle GET /.well-known/oauth-authorization-server
+ *
+ * RFC 8414 — describes the authorization server's capabilities,
+ * endpoints, and supported grant types.
+ */
+export function handleAuthServerMetadata(request) {
+    const baseUrl = getBaseUrl(request);
+    return jsonResponse(200, {
+        issuer: baseUrl,
+        authorization_endpoint: `${baseUrl}/oauth/authorize`,
+        token_endpoint: `${baseUrl}/oauth/token`,
+        registration_endpoint: `${baseUrl}/oauth/register`,
+        jwks_uri: `${baseUrl}/oauth/jwks`,
+        scopes_supported: SCOPES,
+        response_types_supported: ["code"],
+        grant_types_supported: ["authorization_code", "refresh_token"],
+        token_endpoint_auth_methods_supported: ["none"],
+        code_challenge_methods_supported: ["S256"],
+        service_documentation: "https://harper.fast/",
+    });
+}
+function jsonResponse(status, body) {
+    return new Response(JSON.stringify(body), {
+        status,
+        headers: {
+            "Content-Type": "application/json",
+            "Cache-Control": "public, max-age=3600",
+        },
+    });
+}

package/dist/oauth/middleware.d.ts

@@ -0,0 +1,22 @@
+/**
+ * OAuth Middleware
+ *
+ * Route dispatcher for all OAuth endpoints. Registered via
+ * scope.server.http() before the MCP and webhook middlewares.
+ *
+ * Routes:
+ *   GET  /.well-known/oauth-protected-resource   → metadata
+ *   GET  /.well-known/oauth-authorization-server  → metadata
+ *   POST /oauth/register                          → DCR
+ *   GET  /oauth/authorize                         → login page
+ *   POST /oauth/authorize                         → credential validation + redirect
+ *   POST /oauth/token                             → code exchange / refresh
+ *   GET  /oauth/jwks                              → public key set
+ */
+import type { HarperRequest } from "../types.ts";
+type MiddlewareFn = (request: HarperRequest, next: (req: HarperRequest) => Promise<unknown>) => Promise<unknown>;
+/**
+ * Create the OAuth middleware for Harper's scope.server.http().
+ */
+export declare function createOAuthMiddleware(): MiddlewareFn;
+export {};

package/dist/oauth/middleware.js

@@ -0,0 +1,64 @@
+/**
+ * OAuth Middleware
+ *
+ * Route dispatcher for all OAuth endpoints. Registered via
+ * scope.server.http() before the MCP and webhook middlewares.
+ *
+ * Routes:
+ *   GET  /.well-known/oauth-protected-resource   → metadata
+ *   GET  /.well-known/oauth-authorization-server  → metadata
+ *   POST /oauth/register                          → DCR
+ *   GET  /oauth/authorize                         → login page
+ *   POST /oauth/authorize                         → credential validation + redirect
+ *   POST /oauth/token                             → code exchange / refresh
+ *   GET  /oauth/jwks                              → public key set
+ */
+import { handleProtectedResourceMetadata, handleAuthServerMetadata, } from "./metadata.js";
+import { handleRegister } from "./register.js";
+import { handleAuthorizeGet, handleAuthorizePost } from "./authorize.js";
+import { handleToken } from "./token.js";
+import { getJwks } from "./keys.js";
+/**
+ * Create the OAuth middleware for Harper's scope.server.http().
+ */
+export function createOAuthMiddleware() {
+    return async (request, next) => {
+        const pathname = request.pathname || "";
+        const method = (request.method || "GET").toUpperCase();
+        // Well-known metadata endpoints
+        if (pathname === "/.well-known/oauth-protected-resource" &&
+            method === "GET") {
+            return handleProtectedResourceMetadata(request);
+        }
+        if (pathname === "/.well-known/oauth-authorization-server" &&
+            method === "GET") {
+            return handleAuthServerMetadata(request);
+        }
+        // OAuth endpoints
+        if (pathname === "/oauth/register" && method === "POST") {
+            return handleRegister(request);
+        }
+        if (pathname === "/oauth/authorize") {
+            if (method === "GET") {
+                return handleAuthorizeGet(request);
+            }
+            if (method === "POST") {
+                return handleAuthorizePost(request);
+            }
+        }
+        if (pathname === "/oauth/token" && method === "POST") {
+            return handleToken(request);
+        }
+        if (pathname === "/oauth/jwks" && method === "GET") {
+            return new Response(JSON.stringify(await getJwks()), {
+                status: 200,
+                headers: {
+                    "Content-Type": "application/json",
+                    "Cache-Control": "public, max-age=3600",
+                },
+            });
+        }
+        // Not an OAuth route — pass through
+        return next(request);
+    };
+}

package/dist/oauth/register.d.ts

@@ -0,0 +1,14 @@
+/**
+ * OAuth Dynamic Client Registration (RFC 7591)
+ *
+ * POST /oauth/register — allows MCP clients to register themselves
+ * and receive a client_id for the authorization flow.
+ */
+import type { HarperRequest } from "../types.ts";
+/**
+ * Handle POST /oauth/register
+ *
+ * Accepts a registration request and stores the client in OAuthClient table.
+ * Public clients (no client_secret) are the default — PKCE provides security.
+ */
+export declare function handleRegister(request: HarperRequest): Promise<Response>;

package/dist/oauth/register.js

@@ -0,0 +1,83 @@
+/**
+ * OAuth Dynamic Client Registration (RFC 7591)
+ *
+ * POST /oauth/register — allows MCP clients to register themselves
+ * and receive a client_id for the authorization flow.
+ */
+import crypto from "node:crypto";
+import { readBody } from "../http-utils.js";
+/**
+ * Handle POST /oauth/register
+ *
+ * Accepts a registration request and stores the client in OAuthClient table.
+ * Public clients (no client_secret) are the default — PKCE provides security.
+ */
+export async function handleRegister(request) {
+    let body;
+    try {
+        const raw = await readBody(request);
+        body = JSON.parse(raw);
+    }
+    catch {
+        return errorResponse(400, "invalid_client_metadata", "Invalid JSON body");
+    }
+    // Validate redirect_uris (required)
+    const redirectUris = body.redirect_uris;
+    if (!Array.isArray(redirectUris) || redirectUris.length === 0) {
+        return errorResponse(400, "invalid_redirect_uri", "redirect_uris is required and must be a non-empty array");
+    }
+    // Validate each redirect URI: only localhost or https allowed
+    for (const uri of redirectUris) {
+        if (typeof uri !== "string") {
+            return errorResponse(400, "invalid_redirect_uri", "Each redirect_uri must be a string");
+        }
+        try {
+            const parsed = new URL(uri);
+            const isLocalhost = parsed.hostname === "localhost" ||
+                parsed.hostname === "127.0.0.1" ||
+                parsed.hostname === "::1";
+            const isHttps = parsed.protocol === "https:";
+            if (!isLocalhost && !isHttps) {
+                return errorResponse(400, "invalid_redirect_uri", `redirect_uri must use https:// or be localhost: ${uri}`);
+            }
+        }
+        catch {
+            return errorResponse(400, "invalid_redirect_uri", `Invalid redirect_uri: ${uri}`);
+        }
+    }
+    const clientId = crypto.randomUUID();
+    const clientName = typeof body.client_name === "string" ? body.client_name : "Unknown Client";
+    const grantTypes = Array.isArray(body.grant_types)
+        ? body.grant_types
+        : ["authorization_code"];
+    const responseTypes = Array.isArray(body.response_types)
+        ? body.response_types
+        : ["code"];
+    const record = {
+        id: clientId,
+        clientName,
+        redirectUris,
+        grantTypes,
+        responseTypes,
+        scope: typeof body.scope === "string" ? body.scope : "mcp:read mcp:write",
+    };
+    await databases.kb.OAuthClient.put(record);
+    logger?.info?.(`OAuth client registered: ${clientId} (${clientName})`);
+    return new Response(JSON.stringify({
+        client_id: clientId,
+        client_name: clientName,
+        redirect_uris: redirectUris,
+        grant_types: grantTypes,
+        response_types: responseTypes,
+        client_id_issued_at: Math.floor(Date.now() / 1000),
+    }), {
+        status: 201,
+        headers: { "Content-Type": "application/json" },
+    });
+}
+function errorResponse(status, error, description) {
+    return new Response(JSON.stringify({ error, error_description: description }), {
+        status,
+        headers: { "Content-Type": "application/json" },
+    });
+}

package/dist/oauth/token.d.ts

@@ -0,0 +1,15 @@
+/**
+ * OAuth Token Endpoint
+ *
+ * POST /oauth/token — exchanges authorization codes for JWT access tokens
+ * and handles refresh token grants.
+ *
+ * Supports:
+ * - grant_type=authorization_code (with PKCE verification)
+ * - grant_type=refresh_token (with token rotation)
+ */
+import type { HarperRequest } from "../types.ts";
+/**
+ * Handle POST /oauth/token
+ */
+export declare function handleToken(request: HarperRequest): Promise<Response>;

package/dist/oauth/token.js

@@ -0,0 +1,178 @@
+/**
+ * OAuth Token Endpoint
+ *
+ * POST /oauth/token — exchanges authorization codes for JWT access tokens
+ * and handles refresh token grants.
+ *
+ * Supports:
+ * - grant_type=authorization_code (with PKCE verification)
+ * - grant_type=refresh_token (with token rotation)
+ */
+import crypto from "node:crypto";
+import { SignJWT } from "jose";
+import { readBody, parseFormBody, getBaseUrl } from "../http-utils.js";
+import { getPrivateKey, getKeyId } from "./keys.js";
+/** Access token lifetime: 1 hour */
+const ACCESS_TOKEN_EXPIRY = "1h";
+/**
+ * Handle POST /oauth/token
+ */
+export async function handleToken(request) {
+    let form;
+    try {
+        const rawBody = await readBody(request);
+        // Accept both form-urlencoded and JSON
+        const contentType = getContentType(request);
+        if (contentType.includes("json")) {
+            const json = JSON.parse(rawBody);
+            form = {};
+            for (const [k, v] of Object.entries(json)) {
+                form[k] = String(v);
+            }
+        }
+        else {
+            form = parseFormBody(rawBody);
+        }
+    }
+    catch {
+        return errorResponse(400, "invalid_request", "Invalid request body");
+    }
+    const grantType = form.grant_type;
+    if (grantType === "authorization_code") {
+        return handleAuthorizationCodeGrant(form, request);
+    }
+    if (grantType === "refresh_token") {
+        return handleRefreshTokenGrant(form, request);
+    }
+    return errorResponse(400, "unsupported_grant_type", "Unsupported grant_type");
+}
+/**
+ * Exchange an authorization code for tokens.
+ */
+async function handleAuthorizationCodeGrant(form, request) {
+    const code = form.code;
+    const redirectUri = form.redirect_uri;
+    const clientId = form.client_id;
+    const codeVerifier = form.code_verifier;
+    if (!code || !redirectUri || !clientId || !codeVerifier) {
+        return errorResponse(400, "invalid_request", "Missing required parameters: code, redirect_uri, client_id, code_verifier");
+    }
+    // Look up the authorization code
+    const codeRecord = await databases.kb.OAuthCode.get(code);
+    if (!codeRecord) {
+        return errorResponse(400, "invalid_grant", "Invalid or expired authorization code");
+    }
+    // Delete immediately — one-time use enforced before validation to prevent
+    // race conditions where two concurrent requests both read the same code
+    await databases.kb.OAuthCode.delete(code);
+    // Reject pending records (used during GitHub OAuth flow, not real auth codes)
+    if (codeRecord.type === "pending") {
+        return errorResponse(400, "invalid_grant", "Invalid or expired authorization code");
+    }
+    // Validate client_id and redirect_uri match
+    if (codeRecord.clientId !== clientId) {
+        return errorResponse(400, "invalid_grant", "client_id does not match the authorization code");
+    }
+    if (codeRecord.redirectUri !== redirectUri) {
+        return errorResponse(400, "invalid_grant", "redirect_uri does not match the authorization code");
+    }
+    // PKCE verification: SHA256(code_verifier) must equal stored code_challenge
+    // Uses timing-safe comparison to prevent side-channel attacks
+    const expectedChallenge = base64urlEncode(crypto.createHash("sha256").update(codeVerifier).digest());
+    const storedChallenge = String(codeRecord.codeChallenge);
+    const expectedBuf = Buffer.from(expectedChallenge);
+    const storedBuf = Buffer.from(storedChallenge);
+    if (expectedBuf.length !== storedBuf.length ||
+        !crypto.timingSafeEqual(expectedBuf, storedBuf)) {
+        return errorResponse(400, "invalid_grant", "PKCE code_verifier validation failed");
+    }
+    // Issue tokens
+    const userId = codeRecord.userId;
+    const scope = codeRecord.scope;
+    return issueTokens(userId, clientId, scope, request);
+}
+/**
+ * Exchange a refresh token for new tokens (with rotation).
+ */
+async function handleRefreshTokenGrant(form, request) {
+    const refreshToken = form.refresh_token;
+    const clientId = form.client_id;
+    if (!refreshToken || !clientId) {
+        return errorResponse(400, "invalid_request", "Missing required parameters: refresh_token, client_id");
+    }
+    // Look up the refresh token
+    const tokenRecord = await databases.kb.OAuthRefreshToken.get(refreshToken);
+    if (!tokenRecord) {
+        return errorResponse(400, "invalid_grant", "Invalid or expired refresh token");
+    }
+    if (tokenRecord.clientId !== clientId) {
+        return errorResponse(400, "invalid_grant", "client_id does not match the refresh token");
+    }
+    // Delete old refresh token (rotation)
+    await databases.kb.OAuthRefreshToken.delete(refreshToken);
+    const userId = tokenRecord.userId;
+    const scope = tokenRecord.scope;
+    return issueTokens(userId, clientId, scope, request);
+}
+/**
+ * Issue a JWT access token and an opaque refresh token.
+ */
+async function issueTokens(userId, clientId, scope, request) {
+    const baseUrl = getBaseUrl(request);
+    // Sign JWT access token
+    const accessToken = await new SignJWT({
+        scope,
+        client_id: clientId,
+    })
+        .setProtectedHeader({ alg: "RS256", kid: getKeyId() })
+        .setSubject(userId)
+        .setIssuer(baseUrl)
+        .setAudience(`${baseUrl}/mcp`)
+        .setExpirationTime(ACCESS_TOKEN_EXPIRY)
+        .setIssuedAt()
+        .setJti(crypto.randomUUID())
+        .sign(await getPrivateKey());
+    // Generate opaque refresh token
+    const refreshToken = crypto.randomBytes(32).toString("hex");
+    await databases.kb.OAuthRefreshToken.put({
+        id: refreshToken,
+        clientId,
+        userId,
+        scope,
+    });
+    logger?.info?.(`OAuth tokens issued for user ${userId}, client ${clientId}`);
+    return new Response(JSON.stringify({
+        access_token: accessToken,
+        token_type: "Bearer",
+        expires_in: 3600,
+        refresh_token: refreshToken,
+        scope,
+    }), {
+        status: 200,
+        headers: {
+            "Content-Type": "application/json",
+            "Cache-Control": "no-store",
+        },
+    });
+}
+function base64urlEncode(buffer) {
+    return buffer.toString("base64url");
+}
+function getContentType(request) {
+    const headers = request.headers;
+    if (!headers)
+        return "";
+    if (typeof headers.get === "function") {
+        return headers.get("content-type") || "";
+    }
+    return (headers["content-type"] || "");
+}
+function errorResponse(status, error, description) {
+    return new Response(JSON.stringify({ error, error_description: description }), {
+        status,
+        headers: {
+            "Content-Type": "application/json",
+            "Cache-Control": "no-store",
+        },
+    });
+}

package/dist/oauth/validate.d.ts

@@ -0,0 +1,30 @@
+/**
+ * OAuth JWT Bearer Token Validation
+ *
+ * Validates JWT access tokens on incoming MCP requests.
+ * Verifies the signature, issuer, audience, expiration, and scope.
+ */
+import type { HarperRequest } from "../types.ts";
+export interface ValidatedCaller {
+    /** User identifier (from JWT sub claim, e.g. "github:octocat") */
+    userId: string;
+    /** OAuth client ID */
+    clientId: string;
+    /** Granted scopes */
+    scopes: string[];
+}
+export interface AuthResult {
+    /** Validated caller, or null if no valid token */
+    caller: ValidatedCaller | null;
+    /** Whether an Authorization header with Bearer token was present */
+    hasToken: boolean;
+}
+/**
+ * Validate the Bearer token from an MCP request.
+ *
+ * Returns { caller, hasToken } so the MCP middleware can distinguish:
+ * - No token → anonymous read-only access
+ * - Valid token → authenticated access with granted scopes
+ * - Invalid token → 401 (token present but verification failed)
+ */
+export declare function validateMcpAuth(request: HarperRequest): Promise<AuthResult>;

package/dist/oauth/validate.js

@@ -0,0 +1,52 @@
+/**
+ * OAuth JWT Bearer Token Validation
+ *
+ * Validates JWT access tokens on incoming MCP requests.
+ * Verifies the signature, issuer, audience, expiration, and scope.
+ */
+import { jwtVerify, createLocalJWKSet } from "jose";
+import { getBaseUrl, getHeader } from "../http-utils.js";
+import { getJwks } from "./keys.js";
+/**
+ * Validate the Bearer token from an MCP request.
+ *
+ * Returns { caller, hasToken } so the MCP middleware can distinguish:
+ * - No token → anonymous read-only access
+ * - Valid token → authenticated access with granted scopes
+ * - Invalid token → 401 (token present but verification failed)
+ */
+export async function validateMcpAuth(request) {
+    const token = extractBearerToken(request);
+    if (!token)
+        return { caller: null, hasToken: false };
+    try {
+        const baseUrl = getBaseUrl(request);
+        const jwks = createLocalJWKSet(await getJwks());
+        const { payload } = await jwtVerify(token, jwks, {
+            issuer: baseUrl,
+            audience: `${baseUrl}/mcp`,
+        });
+        return {
+            caller: {
+                userId: payload.sub || "unknown",
+                clientId: payload.client_id || "unknown",
+                scopes: typeof payload.scope === "string" ? payload.scope.split(" ") : [],
+            },
+            hasToken: true,
+        };
+    }
+    catch (error) {
+        logger?.warn?.(`JWT validation failed: ${error.message}`);
+        return { caller: null, hasToken: true };
+    }
+}
+/**
+ * Extract the Bearer token from the Authorization header.
+ */
+function extractBearerToken(request) {
+    const authValue = getHeader(request, "authorization");
+    if (!authValue)
+        return null;
+    const match = authValue.match(/^Bearer\s+(.+)$/i);
+    return match ? match[1] : null;
+}

package/dist/resources/HistoryResource.d.ts

@@ -0,0 +1,38 @@
+/**
+ * History Resource
+ *
+ * REST endpoint for knowledge entry edit history.
+ *
+ * Routes:
+ *   GET /History/<entryId>  — get edit history for a knowledge entry
+ */
+declare const HistoryResource_base: any;
+export declare class HistoryResource extends HistoryResource_base {
+    static loadAsInstance: boolean;
+    /**
+     * GET /History/<entryId> — get edit history for a knowledge entry.
+     * Public read access (same as KnowledgeEntry).
+     */
+    get(target?: any): Promise<{
+        status: number;
+        data: {
+            error: string;
+        };
+        entryId?: undefined;
+        editCount?: undefined;
+        edits?: undefined;
+    } | {
+        entryId: string;
+        editCount: number;
+        edits: {
+            id: string;
+            entryId: string;
+            editSummary?: string;
+            changedFields: string[];
+            createdAt?: Date;
+        }[];
+        status?: undefined;
+        data?: undefined;
+    }>;
+}
+export {};

package/dist/resources/HistoryResource.js

@@ -0,0 +1,38 @@
+/**
+ * History Resource
+ *
+ * REST endpoint for knowledge entry edit history.
+ *
+ * Routes:
+ *   GET /History/<entryId>  — get edit history for a knowledge entry
+ */
+import { getHistory } from "../core/history.js";
+function getResourceClass() {
+    return globalThis.Resource;
+}
+export class HistoryResource extends getResourceClass() {
+    static loadAsInstance = false;
+    /**
+     * GET /History/<entryId> — get edit history for a knowledge entry.
+     * Public read access (same as KnowledgeEntry).
+     */
+    async get(target) {
+        const entryId = this.getId();
+        if (!entryId) {
+            return {
+                status: 400,
+                data: { error: "Entry ID required: GET /History/<entryId>" },
+            };
+        }
+        const limitParam = target?.get?.("limit") || target?.limit;
+        const limit = limitParam ? parseInt(String(limitParam), 10) : 50;
+        const edits = await getHistory(String(entryId), limit);
+        // Strip sensitive fields from public responses (usernames, previous values)
+        const publicEdits = edits.map(({ editedBy: _u, previousSnapshot: _s, ...rest }) => rest);
+        return {
+            entryId: String(entryId),
+            editCount: publicEdits.length,
+            edits: publicEdits,
+        };
+    }
+}

package/dist/resources/KnowledgeEntryResource.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Knowledge Entry Resource
+ *
+ * REST endpoint for knowledge base entries.
+ * GET is public; POST, PUT, DELETE require authentication.
+ *
+ * Routes:
+ *   GET  /Knowledge/<id>      — return single entry
+ *   GET  /Knowledge/?query=.. — search entries
+ *   POST /Knowledge/          — create new entry (auth required)
+ *   PUT  /Knowledge/<id>      — update entry (auth required)
+ *   DELETE /Knowledge/<id>    — deprecate entry (team role required)
+ */
+declare const KnowledgeEntryResource_base: any;
+export declare class KnowledgeEntryResource extends KnowledgeEntryResource_base {
+    static loadAsInstance: boolean;
+    /**
+     * GET /Knowledge/<id> — return a single entry by ID.
+     * GET /Knowledge/?query=... — search the knowledge base.
+     * PUBLIC — no auth required.
+     */
+    get(target?: any): Promise<Omit<import("../types.ts").KnowledgeEntry, "embedding"> | Omit<import("../types.ts").SearchResult, "embedding">[] | {
+        status: number;
+        data: {
+            error: string;
+        };
+        error?: undefined;
+    } | {
+        error: string;
+        status?: undefined;
+        data?: undefined;
+    }>;
+    /**
+     * POST /Knowledge/ — create a new knowledge entry.
+     * AUTH REQUIRED. AI agents have their confidence forced to "ai-generated".
+     */
+    post(_target: any, data: any): Promise<import("../types.ts").KnowledgeEntry | {
+        status: number;
+        data: {
+            error: string;
+        };
+    }>;
+    /**
+     * PUT /Knowledge/<id> — create or update an entry.
+     * AUTH REQUIRED. AI agents have their confidence forced to "ai-generated".
+     */
+    put(_target: any, data: any): Promise<import("../types.ts").KnowledgeEntry | {
+        status: number;
+        data: {
+            error: string;
+        };
+    }>;
+    /**
+     * DELETE /Knowledge/<id> — deprecate an entry (soft delete).
+     * AUTH REQUIRED: team role only.
+     */
+    delete(_target?: any): Promise<true | {
+        status: number;
+        data: {
+            error: string;
+        };
+    }>;
+}
+export {};