@grackle-ai/auth 0.72.3

package/README.md

@@ -0,0 +1,26 @@
+# @grackle-ai/auth
+
+Authentication and authorization primitives for [Grackle](https://github.com/nick-pape/grackle).
+
+## Features
+
+- **API key management** — Generate, persist, and verify 256-bit API keys with constant-time comparison
+- **Browser sessions** — HMAC-signed cookie sessions with automatic expiry and cleanup
+- **Pairing codes** — Time-limited 6-character codes with IP-based rate limiting for device pairing
+- **OAuth 2.1** — Dynamic client registration, PKCE (S256), authorization codes, and refresh token rotation
+- **HMAC-signed tokens** — OAuth access tokens and scoped task tokens for MCP authentication
+- **MCP request auth** — Middleware that authenticates API key, OAuth, and scoped token bearers
+- **Security headers** — CSP and defense-in-depth headers for HTTP responses
+
+## Logger Configuration
+
+Auth modules use a pluggable logger. Call `setAuthLogger()` at startup to inject your application logger:
+
+```typescript
+import { setAuthLogger } from "@grackle-ai/auth";
+import { logger } from "./my-logger.js";
+
+setAuthLogger(logger);
+```
+
+If not configured, a default console-based logger is used.

package/dist/api-key.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Load or create the API key. On first run, a random 256-bit key is
+ * generated and written to `<homePath>/api-key` with 0600 permissions.
+ *
+ * @param homePath - The Grackle home directory (e.g., `~/.grackle`).
+ */
+export declare function loadOrCreateApiKey(homePath: string): string;
+/** Verify a bearer token matches the API key. */
+export declare function verifyApiKey(token: string): boolean;
+/** Reset cached key (for testing). */
+export declare function _resetCachedKeyForTesting(): void;
+//# sourceMappingURL=api-key.d.ts.map

package/dist/api-key.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-key.d.ts","sourceRoot":"","sources":["../src/api-key.ts"],"names":[],"mappings":"AAqCA;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAQ3D;AAED,iDAAiD;AACjD,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAcnD;AAED,sCAAsC;AACtC,wBAAgB,yBAAyB,IAAI,IAAI,CAEhD"}

package/dist/api-key.js

@@ -0,0 +1,65 @@
+import { randomBytes } from "node:crypto";
+import { readFileSync, writeFileSync, existsSync, mkdirSync, chmodSync } from "node:fs";
+import { join } from "node:path";
+import { API_KEY_FILENAME } from "@grackle-ai/common";
+import { getAuthLogger } from "./auth-logger.js";
+const API_KEY_BYTE_LENGTH = 32;
+let cachedKey = undefined;
+/** Attempt to read an existing API key from disk. Returns undefined if none exists. */
+function tryLoadApiKey(keyPath) {
+    if (existsSync(keyPath)) {
+        const content = readFileSync(keyPath, "utf8").trim();
+        if (content.length > 0) {
+            return content;
+        }
+    }
+    return undefined;
+}
+/** Generate a new random API key, write it to disk with 0600 permissions, and return it. */
+function createApiKey(homePath, keyPath) {
+    const key = randomBytes(API_KEY_BYTE_LENGTH).toString("hex");
+    mkdirSync(homePath, { recursive: true });
+    writeFileSync(keyPath, key + "\n", { mode: 0o600 });
+    // Ensure permissions on Windows (best-effort)
+    try {
+        chmodSync(keyPath, 0o600);
+    }
+    catch { /* Windows may not support this */ }
+    getAuthLogger().info({ keyPath }, "Generated new API key");
+    return key;
+}
+/**
+ * Load or create the API key. On first run, a random 256-bit key is
+ * generated and written to `<homePath>/api-key` with 0600 permissions.
+ *
+ * @param homePath - The Grackle home directory (e.g., `~/.grackle`).
+ */
+export function loadOrCreateApiKey(homePath) {
+    if (cachedKey) {
+        return cachedKey;
+    }
+    const keyPath = join(homePath, API_KEY_FILENAME);
+    cachedKey = tryLoadApiKey(keyPath) ?? createApiKey(homePath, keyPath);
+    return cachedKey;
+}
+/** Verify a bearer token matches the API key. */
+export function verifyApiKey(token) {
+    if (!cachedKey) {
+        return false;
+    }
+    // Constant-time comparison to prevent timing attacks
+    if (token.length !== cachedKey.length) {
+        return false;
+    }
+    let result = 0;
+    for (let i = 0; i < cachedKey.length; i++) {
+        // eslint-disable-next-line no-bitwise
+        result |= token.charCodeAt(i) ^ cachedKey.charCodeAt(i);
+    }
+    return result === 0;
+}
+/** Reset cached key (for testing). */
+export function _resetCachedKeyForTesting() {
+    cachedKey = undefined;
+}
+//# sourceMappingURL=api-key.js.map

package/dist/api-key.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-key.js","sourceRoot":"","sources":["../src/api-key.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,UAAU,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACxF,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEjD,MAAM,mBAAmB,GAAW,EAAE,CAAC;AAEvC,IAAI,SAAS,GAAuB,SAAS,CAAC;AAE9C,uFAAuF;AACvF,SAAS,aAAa,CAAC,OAAe;IACpC,IAAI,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;QACxB,MAAM,OAAO,GAAG,YAAY,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC;QACrD,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACvB,OAAO,OAAO,CAAC;QACjB,CAAC;IACH,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,4FAA4F;AAC5F,SAAS,YAAY,CAAC,QAAgB,EAAE,OAAe;IACrD,MAAM,GAAG,GAAG,WAAW,CAAC,mBAAmB,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;IAE7D,SAAS,CAAC,QAAQ,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACzC,aAAa,CAAC,OAAO,EAAE,GAAG,GAAG,IAAI,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IAEpD,8CAA8C;IAC9C,IAAI,CAAC;QACH,SAAS,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IAC5B,CAAC;IAAC,MAAM,CAAC,CAAC,kCAAkC,CAAC,CAAC;IAE9C,aAAa,EAAE,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,EAAE,uBAAuB,CAAC,CAAC;IAC3D,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAC,QAAgB;IACjD,IAAI,SAAS,EAAE,CAAC;QACd,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,EAAE,gBAAgB,CAAC,CAAC;IACjD,SAAS,GAAG,aAAa,CAAC,OAAO,CAAC,IAAI,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IACtE,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,iDAAiD;AACjD,MAAM,UAAU,YAAY,CAAC,KAAa;IACxC,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,OAAO,KAAK,CAAC;IACf,CAAC;IACD,qDAAqD;IACrD,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS,CAAC,MAAM,EAAE,CAAC;QACtC,OAAO,KAAK,CAAC;IACf,CAAC;IACD,IAAI,MAAM,GAAG,CAAC,CAAC;IACf,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,SAAS,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAC1C,sCAAsC;QACtC,MAAM,IAAI,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;IAC1D,CAAC;IACD,OAAO,MAAM,KAAK,CAAC,CAAC;AACtB,CAAC;AAED,sCAAsC;AACtC,MAAM,UAAU,yBAAyB;IACvC,SAAS,GAAG,SAAS,CAAC;AACxB,CAAC"}

package/dist/auth-context.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Authentication context resolved from an incoming MCP request.
+ *
+ * - `"api-key"`: Full-access authentication via the global API key.
+ * - `"scoped"`: Session-scoped token identifying a specific task/session/persona.
+ * - `"oauth"`: OAuth-authorized client — full tool access (user explicitly approved).
+ */
+export type AuthContext = {
+    type: "api-key";
+} | {
+    type: "scoped";
+    taskId: string;
+    workspaceId?: string;
+    personaId: string;
+    taskSessionId: string;
+} | {
+    type: "oauth";
+    clientId: string;
+};
+//# sourceMappingURL=auth-context.d.ts.map

package/dist/auth-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-context.d.ts","sourceRoot":"","sources":["../src/auth-context.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,MAAM,WAAW,GACnB;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,GACnB;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAA;CAAE,GAClG;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC"}

package/dist/auth-context.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=auth-context.js.map

package/dist/auth-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-context.js","sourceRoot":"","sources":["../src/auth-context.ts"],"names":[],"mappings":""}

package/dist/auth-logger.d.ts

@@ -0,0 +1,12 @@
+/** Logger interface for auth modules. */
+export interface AuthLogger {
+    info(obj: object, msg: string, ...args: unknown[]): void;
+    warn(objOrMsg: object | string, msg?: string, ...args: unknown[]): void;
+}
+/** Default console-based logger. */
+export declare const defaultAuthLogger: AuthLogger;
+/** Set the logger used by all auth modules. Call once at startup. */
+export declare function setAuthLogger(l: AuthLogger): void;
+/** Get the current auth logger. */
+export declare function getAuthLogger(): AuthLogger;
+//# sourceMappingURL=auth-logger.d.ts.map

package/dist/auth-logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-logger.d.ts","sourceRoot":"","sources":["../src/auth-logger.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,MAAM,WAAW,UAAU;IACzB,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IACzD,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;CACzE;AAED,oCAAoC;AACpC,eAAO,MAAM,iBAAiB,EAAE,UAW/B,CAAC;AAIF,qEAAqE;AACrE,wBAAgB,aAAa,CAAC,CAAC,EAAE,UAAU,GAAG,IAAI,CAEjD;AAED,mCAAmC;AACnC,wBAAgB,aAAa,IAAI,UAAU,CAE1C"}

package/dist/auth-logger.js

@@ -0,0 +1,24 @@
+/** Default console-based logger. */
+export const defaultAuthLogger = {
+    info(_obj, msg, ...args) {
+        console.log("[auth]", msg, ...args);
+    },
+    warn(objOrMsg, msg, ...args) {
+        if (typeof objOrMsg === "string") {
+            console.warn("[auth]", objOrMsg, msg, ...args);
+        }
+        else {
+            console.warn("[auth]", msg, ...args);
+        }
+    },
+};
+let logger = defaultAuthLogger;
+/** Set the logger used by all auth modules. Call once at startup. */
+export function setAuthLogger(l) {
+    logger = l;
+}
+/** Get the current auth logger. */
+export function getAuthLogger() {
+    return logger;
+}
+//# sourceMappingURL=auth-logger.js.map

package/dist/auth-logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-logger.js","sourceRoot":"","sources":["../src/auth-logger.ts"],"names":[],"mappings":"AAMA,oCAAoC;AACpC,MAAM,CAAC,MAAM,iBAAiB,GAAe;IAC3C,IAAI,CAAC,IAAY,EAAE,GAAW,EAAE,GAAG,IAAe;QAChD,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC;IACtC,CAAC;IACD,IAAI,CAAC,QAAyB,EAAE,GAAY,EAAE,GAAG,IAAe;QAC9D,IAAI,OAAO,QAAQ,KAAK,QAAQ,EAAE,CAAC;YACjC,OAAO,CAAC,IAAI,CAAC,QAAQ,EAAE,QAAQ,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC;QACjD,CAAC;aAAM,CAAC;YACN,OAAO,CAAC,IAAI,CAAC,QAAQ,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC;QACvC,CAAC;IACH,CAAC;CACF,CAAC;AAEF,IAAI,MAAM,GAAe,iBAAiB,CAAC;AAE3C,qEAAqE;AACrE,MAAM,UAAU,aAAa,CAAC,CAAa;IACzC,MAAM,GAAG,CAAC,CAAC;AACb,CAAC;AAED,mCAAmC;AACnC,MAAM,UAAU,aAAa;IAC3B,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/auth-middleware.d.ts

@@ -0,0 +1,16 @@
+import type http from "node:http";
+import type { AuthContext } from "./auth-context.js";
+/**
+ * Authenticate an incoming MCP HTTP request.
+ *
+ * Supports three authentication modes:
+ * 1. **API key**: A 64-character hex Bearer token compared constant-time against the server API key.
+ * 2. **OAuth token**: An HMAC-signed token with `typ === "oauth"`, audience-validated against the request.
+ * 3. **Scoped token**: An HMAC-signed token (contains a `.`) verified against the API key as signing secret.
+ *
+ * @param req - The incoming HTTP request.
+ * @param apiKey - The server's API key (used for both direct comparison and as the HMAC signing secret).
+ * @returns An {@link AuthContext} if authentication succeeds, or `undefined` for a 401.
+ */
+export declare function authenticateMcpRequest(req: http.IncomingMessage, apiKey: string): AuthContext | undefined;
+//# sourceMappingURL=auth-middleware.d.ts.map

package/dist/auth-middleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-middleware.d.ts","sourceRoot":"","sources":["../src/auth-middleware.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAuBrD;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,IAAI,CAAC,eAAe,EAAE,MAAM,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CA8DzG"}

package/dist/auth-middleware.js

@@ -0,0 +1,93 @@
+import { timingSafeEqual } from "node:crypto";
+import { verifyOAuthAccessToken } from "./oauth-token.js";
+import { isRevokedTask, verifyScopedToken } from "./scoped-token.js";
+/** Expected length of API key tokens (64 hex characters). */
+const API_KEY_LENGTH = 64;
+/**
+ * Normalize loopback hostnames so that `localhost` and `127.0.0.1` compare equal.
+ * Parses the URL and replaces `localhost` with `127.0.0.1`, returning the origin.
+ */
+function normalizeLoopback(url) {
+    try {
+        const parsed = new URL(url);
+        if (parsed.hostname === "localhost") {
+            parsed.hostname = "127.0.0.1";
+        }
+        return parsed.origin;
+    }
+    catch {
+        return url;
+    }
+}
+/**
+ * Authenticate an incoming MCP HTTP request.
+ *
+ * Supports three authentication modes:
+ * 1. **API key**: A 64-character hex Bearer token compared constant-time against the server API key.
+ * 2. **OAuth token**: An HMAC-signed token with `typ === "oauth"`, audience-validated against the request.
+ * 3. **Scoped token**: An HMAC-signed token (contains a `.`) verified against the API key as signing secret.
+ *
+ * @param req - The incoming HTTP request.
+ * @param apiKey - The server's API key (used for both direct comparison and as the HMAC signing secret).
+ * @returns An {@link AuthContext} if authentication succeeds, or `undefined` for a 401.
+ */
+export function authenticateMcpRequest(req, apiKey) {
+    const authHeader = req.headers.authorization || "";
+    const match = /^Bearer\s+(.+)$/i.exec(authHeader);
+    if (!match) {
+        return undefined;
+    }
+    const token = match[1];
+    if (token.length === 0) {
+        return undefined;
+    }
+    // Path 1: API key authentication (fixed-length hex token)
+    if (token.length === API_KEY_LENGTH && apiKey.length === API_KEY_LENGTH) {
+        const a = Buffer.from(token);
+        const b = Buffer.from(apiKey);
+        if (a.length === b.length && timingSafeEqual(a, b)) {
+            return { type: "api-key" };
+        }
+        // Fall through — a 64-char token that doesn't match the API key is invalid
+        return undefined;
+    }
+    // Path 2: Token with dot separator — try OAuth first, then scoped
+    if (token.includes(".")) {
+        // Try OAuth access token (distinguished by typ === "oauth")
+        const oauthClaims = verifyOAuthAccessToken(token, apiKey);
+        if (oauthClaims) {
+            // Validate audience if present — when non-empty, must match this server's resource URL.
+            // Empty aud is accepted because the client may omit the resource indicator (RFC 8707).
+            // Use the socket's local port (server-controlled) rather than the Host header (client-controlled)
+            // to prevent token replay via Host spoofing.
+            // Normalize trailing slashes and treat "localhost" as equivalent to "127.0.0.1" since
+            // MCP clients may connect via either hostname.
+            if (oauthClaims.aud) {
+                const localPort = req.socket.localPort;
+                const expectedAudience = localPort ? `http://127.0.0.1:${localPort}` : undefined;
+                const normalizedAud = normalizeLoopback(oauthClaims.aud.replace(/\/+$/, ""));
+                if (!expectedAudience || normalizedAud !== expectedAudience) {
+                    return undefined;
+                }
+            }
+            return { type: "oauth", clientId: oauthClaims.sub };
+        }
+        // Fall through to scoped token
+        const claims = verifyScopedToken(token, apiKey);
+        if (!claims) {
+            return undefined;
+        }
+        if (isRevokedTask(claims.sub)) {
+            return undefined;
+        }
+        return {
+            type: "scoped",
+            taskId: claims.sub,
+            workspaceId: claims.pid || undefined,
+            personaId: claims.per,
+            taskSessionId: claims.sid,
+        };
+    }
+    return undefined;
+}
+//# sourceMappingURL=auth-middleware.js.map

package/dist/auth-middleware.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-middleware.js","sourceRoot":"","sources":["../src/auth-middleware.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+export type { AuthLogger } from "./auth-logger.js";
+export { defaultAuthLogger, setAuthLogger } from "./auth-logger.js";
+export { loadOrCreateApiKey, verifyApiKey } from "./api-key.js";
+export { SESSION_COOKIE_NAME, createSession, validateSessionCookie, parseCookies, clearSessions, startSessionCleanup, stopSessionCleanup, } from "./session.js";
+export { generatePairingCode, redeemPairingCode, clearPairing, startPairingCleanup, stopPairingCleanup, } from "./pairing.js";
+export type { ClientRecord, AuthCodeRecord, RefreshTokenRecord } from "./oauth.js";
+export { registerClient, getClient, createAuthorizationCode, consumeAuthorizationCode, createRefreshToken, consumeRefreshToken, computeCodeChallenge, verifyCodeChallenge, clearOAuthState, startOAuthCleanup, stopOAuthCleanup, } from "./oauth.js";
+export type { OAuthTokenClaims } from "./oauth-token.js";
+export { OAUTH_ACCESS_TOKEN_TTL_MS, OAUTH_REFRESH_TOKEN_TTL_MS, createOAuthAccessToken, verifyOAuthAccessToken, } from "./oauth-token.js";
+export type { ScopedTokenClaims } from "./scoped-token.js";
+export { createScopedToken, verifyScopedToken, revokeTask, isRevokedTask, pruneRevocations, clearRevocations, } from "./scoped-token.js";
+export type { AuthContext } from "./auth-context.js";
+export { authenticateMcpRequest } from "./auth-middleware.js";
+export { WEB_CONTENT_SECURITY_POLICY, setSecurityHeaders } from "./security-headers.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,YAAY,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAGpE,OAAO,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAGhE,OAAO,EACL,mBAAmB,EACnB,aAAa,EACb,qBAAqB,EACrB,YAAY,EACZ,aAAa,EACb,mBAAmB,EACnB,kBAAkB,GACnB,MAAM,cAAc,CAAC;AAGtB,OAAO,EACL,mBAAmB,EACnB,iBAAiB,EACjB,YAAY,EACZ,mBAAmB,EACnB,kBAAkB,GACnB,MAAM,cAAc,CAAC;AAGtB,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AACnF,OAAO,EACL,cAAc,EACd,SAAS,EACT,uBAAuB,EACvB,wBAAwB,EACxB,kBAAkB,EAClB,mBAAmB,EACnB,oBAAoB,EACpB,mBAAmB,EACnB,eAAe,EACf,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,YAAY,CAAC;AAGpB,YAAY,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACzD,OAAO,EACL,yBAAyB,EACzB,0BAA0B,EAC1B,sBAAsB,EACtB,sBAAsB,GACvB,MAAM,kBAAkB,CAAC;AAG1B,YAAY,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAC3D,OAAO,EACL,iBAAiB,EACjB,iBAAiB,EACjB,UAAU,EACV,aAAa,EACb,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,mBAAmB,CAAC;AAG3B,YAAY,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGrD,OAAO,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAG9D,OAAO,EAAE,2BAA2B,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/index.js

@@ -0,0 +1,15 @@
+export { defaultAuthLogger, setAuthLogger } from "./auth-logger.js";
+// ─── API Key ────────────────────────────────────────────────
+export { loadOrCreateApiKey, verifyApiKey } from "./api-key.js";
+// ─── Sessions ───────────────────────────────────────────────
+export { SESSION_COOKIE_NAME, createSession, validateSessionCookie, parseCookies, clearSessions, startSessionCleanup, stopSessionCleanup, } from "./session.js";
+// ─── Pairing ────────────────────────────────────────────────
+export { generatePairingCode, redeemPairingCode, clearPairing, startPairingCleanup, stopPairingCleanup, } from "./pairing.js";
+export { registerClient, getClient, createAuthorizationCode, consumeAuthorizationCode, createRefreshToken, consumeRefreshToken, computeCodeChallenge, verifyCodeChallenge, clearOAuthState, startOAuthCleanup, stopOAuthCleanup, } from "./oauth.js";
+export { OAUTH_ACCESS_TOKEN_TTL_MS, OAUTH_REFRESH_TOKEN_TTL_MS, createOAuthAccessToken, verifyOAuthAccessToken, } from "./oauth-token.js";
+export { createScopedToken, verifyScopedToken, revokeTask, isRevokedTask, pruneRevocations, clearRevocations, } from "./scoped-token.js";
+// ─── Auth Middleware ────────────────────────────────────────
+export { authenticateMcpRequest } from "./auth-middleware.js";
+// ─── Security Headers ──────────────────────────────────────
+export { WEB_CONTENT_SECURITY_POLICY, setSecurityHeaders } from "./security-headers.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEpE,+DAA+D;AAC/D,OAAO,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAEhE,+DAA+D;AAC/D,OAAO,EACL,mBAAmB,EACnB,aAAa,EACb,qBAAqB,EACrB,YAAY,EACZ,aAAa,EACb,mBAAmB,EACnB,kBAAkB,GACnB,MAAM,cAAc,CAAC;AAEtB,+DAA+D;AAC/D,OAAO,EACL,mBAAmB,EACnB,iBAAiB,EACjB,YAAY,EACZ,mBAAmB,EACnB,kBAAkB,GACnB,MAAM,cAAc,CAAC;AAItB,OAAO,EACL,cAAc,EACd,SAAS,EACT,uBAAuB,EACvB,wBAAwB,EACxB,kBAAkB,EAClB,mBAAmB,EACnB,oBAAoB,EACpB,mBAAmB,EACnB,eAAe,EACf,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,YAAY,CAAC;AAIpB,OAAO,EACL,yBAAyB,EACzB,0BAA0B,EAC1B,sBAAsB,EACtB,sBAAsB,GACvB,MAAM,kBAAkB,CAAC;AAI1B,OAAO,EACL,iBAAiB,EACjB,iBAAiB,EACjB,UAAU,EACV,aAAa,EACb,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,mBAAmB,CAAC;AAK3B,+DAA+D;AAC/D,OAAO,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAE9D,8DAA8D;AAC9D,OAAO,EAAE,2BAA2B,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/oauth-token.d.ts

@@ -0,0 +1,38 @@
+/** Default access token time-to-live: 1 hour in milliseconds. */
+export declare const OAUTH_ACCESS_TOKEN_TTL_MS: number;
+/** Default refresh token time-to-live: 30 days in milliseconds. */
+export declare const OAUTH_REFRESH_TOKEN_TTL_MS: number;
+/** Claims embedded in an OAuth access token payload. */
+export interface OAuthTokenClaims {
+    /** Token type discriminator — always "oauth" for OAuth access tokens. */
+    typ: "oauth";
+    /** Subject — the OAuth client ID that was authorized. */
+    sub: string;
+    /** Audience — the resource URL (MCP server URL) this token was issued for. */
+    aud: string;
+    /** Issued-at time (epoch seconds). */
+    iat: number;
+    /** Expiry time (epoch seconds). */
+    exp: number;
+}
+/**
+ * Create an OAuth access token with the given client ID and resource, signed with the provided secret.
+ *
+ * @param clientId - The OAuth client ID (subject).
+ * @param resource - The resource URL (audience) this token is scoped to.
+ * @param signingSecret - Secret used to HMAC-sign the token (typically the API key).
+ * @param ttlMs - Token time-to-live in milliseconds (default: 1 hour).
+ * @returns The signed opaque token string.
+ */
+export declare function createOAuthAccessToken(clientId: string, resource: string, signingSecret: string, ttlMs?: number): string;
+/**
+ * Verify an OAuth access token's signature and expiry.
+ *
+ * Uses constant-time comparison for the HMAC signature.
+ *
+ * @param token - The token string to verify.
+ * @param signingSecret - The secret used to verify the HMAC signature.
+ * @returns The decoded claims if valid, or `undefined` if verification fails.
+ */
+export declare function verifyOAuthAccessToken(token: string, signingSecret: string): OAuthTokenClaims | undefined;
+//# sourceMappingURL=oauth-token.d.ts.map

package/dist/oauth-token.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth-token.d.ts","sourceRoot":"","sources":["../src/oauth-token.ts"],"names":[],"mappings":"AAEA,iEAAiE;AACjE,eAAO,MAAM,yBAAyB,EAAE,MAAuB,CAAC;AAEhE,mEAAmE;AACnE,eAAO,MAAM,0BAA0B,EAAE,MAAiC,CAAC;AAE3E,wDAAwD;AACxD,MAAM,WAAW,gBAAgB;IAC/B,yEAAyE;IACzE,GAAG,EAAE,OAAO,CAAC;IACb,yDAAyD;IACzD,GAAG,EAAE,MAAM,CAAC;IACZ,8EAA8E;IAC9E,GAAG,EAAE,MAAM,CAAC;IACZ,sCAAsC;IACtC,GAAG,EAAE,MAAM,CAAC;IACZ,mCAAmC;IACnC,GAAG,EAAE,MAAM,CAAC;CACb;AAiBD;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,MAAM,EACrB,KAAK,GAAE,MAAkC,GACxC,MAAM,CAaR;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS,CA4DzG"}

package/dist/oauth-token.js

@@ -0,0 +1,101 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+/** Default access token time-to-live: 1 hour in milliseconds. */
+export const OAUTH_ACCESS_TOKEN_TTL_MS = 60 * 60 * 1000;
+/** Default refresh token time-to-live: 30 days in milliseconds. */
+export const OAUTH_REFRESH_TOKEN_TTL_MS = 30 * 24 * 60 * 60 * 1000;
+/** Encode a buffer as base64url (no padding). */
+function toBase64Url(buf) {
+    return buf.toString("base64url");
+}
+/** Decode a base64url string to a Buffer. */
+function fromBase64Url(str) {
+    return Buffer.from(str, "base64url");
+}
+/** Compute HMAC-SHA256 signature over a payload string. */
+function sign(payload, secret) {
+    return createHmac("sha256", secret).update(payload).digest();
+}
+/**
+ * Create an OAuth access token with the given client ID and resource, signed with the provided secret.
+ *
+ * @param clientId - The OAuth client ID (subject).
+ * @param resource - The resource URL (audience) this token is scoped to.
+ * @param signingSecret - Secret used to HMAC-sign the token (typically the API key).
+ * @param ttlMs - Token time-to-live in milliseconds (default: 1 hour).
+ * @returns The signed opaque token string.
+ */
+export function createOAuthAccessToken(clientId, resource, signingSecret, ttlMs = OAUTH_ACCESS_TOKEN_TTL_MS) {
+    const now = Math.floor(Date.now() / 1000);
+    const payload = {
+        typ: "oauth",
+        sub: clientId,
+        aud: resource,
+        iat: now,
+        exp: now + Math.floor(ttlMs / 1000),
+    };
+    const payloadStr = JSON.stringify(payload);
+    const payloadEncoded = toBase64Url(Buffer.from(payloadStr, "utf8"));
+    const signature = toBase64Url(sign(payloadEncoded, signingSecret));
+    return `${payloadEncoded}.${signature}`;
+}
+/**
+ * Verify an OAuth access token's signature and expiry.
+ *
+ * Uses constant-time comparison for the HMAC signature.
+ *
+ * @param token - The token string to verify.
+ * @param signingSecret - The secret used to verify the HMAC signature.
+ * @returns The decoded claims if valid, or `undefined` if verification fails.
+ */
+export function verifyOAuthAccessToken(token, signingSecret) {
+    const dotIndex = token.indexOf(".");
+    if (dotIndex === -1 || dotIndex === 0 || dotIndex === token.length - 1) {
+        return undefined;
+    }
+    // Reject tokens with multiple dots
+    if (token.indexOf(".", dotIndex + 1) !== -1) {
+        return undefined;
+    }
+    const payloadEncoded = token.slice(0, dotIndex);
+    const signatureEncoded = token.slice(dotIndex + 1);
+    // Verify signature using constant-time comparison
+    const expectedSignature = sign(payloadEncoded, signingSecret);
+    let actualSignature;
+    try {
+        actualSignature = fromBase64Url(signatureEncoded);
+    }
+    catch {
+        return undefined;
+    }
+    if (expectedSignature.length !== actualSignature.length) {
+        return undefined;
+    }
+    if (!timingSafeEqual(expectedSignature, actualSignature)) {
+        return undefined;
+    }
+    // Decode and parse payload — parse as Record first for runtime validation
+    let raw;
+    try {
+        const payloadStr = fromBase64Url(payloadEncoded).toString("utf8");
+        raw = JSON.parse(payloadStr);
+    }
+    catch {
+        return undefined;
+    }
+    // Validate claim types to prevent bypass via crafted payloads
+    if (raw.typ !== "oauth" ||
+        typeof raw.sub !== "string" ||
+        typeof raw.aud !== "string" ||
+        !Number.isFinite(raw.iat) ||
+        !Number.isFinite(raw.exp)) {
+        return undefined;
+    }
+    const claims = raw;
+    // Check expiry (exp must be strictly greater than both iat and now)
+    const now = Math.floor(Date.now() / 1000);
+    if (claims.exp <= now || claims.exp <= claims.iat) {
+        return undefined;
+    }
+    return claims;
+}
+//# sourceMappingURL=oauth-token.js.map

package/dist/oauth-token.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth-token.js","sourceRoot":"","sources":["../src/oauth-token.ts"],"names":[],"mappings":"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"}

package/dist/oauth.d.ts

@@ -0,0 +1,102 @@
+/** Registered OAuth client record. */
+export interface ClientRecord {
+    clientId: string;
+    redirectUris: string[];
+    clientName: string;
+    createdAt: number;
+}
+/**
+ * Register a new OAuth client with dynamic client registration.
+ *
+ * @param redirectUris - List of allowed redirect URIs for this client.
+ * @param clientName - Human-readable name for the client (optional).
+ * @returns The newly registered client record.
+ */
+export declare function registerClient(redirectUris: string[], clientName?: string): ClientRecord | undefined;
+/**
+ * Look up a registered client by ID.
+ *
+ * @param clientId - The client ID to look up.
+ * @returns The client record, or undefined if not found.
+ */
+export declare function getClient(clientId: string): ClientRecord | undefined;
+/** Authorization code record bound to PKCE parameters. */
+export interface AuthCodeRecord {
+    code: string;
+    clientId: string;
+    redirectUri: string;
+    codeChallenge: string;
+    resource: string;
+    createdAt: number;
+    expiresAt: number;
+}
+/**
+ * Create a single-use authorization code bound to the given parameters.
+ *
+ * @param clientId - The client that requested authorization.
+ * @param redirectUri - The redirect URI for this authorization.
+ * @param codeChallenge - PKCE S256 code challenge.
+ * @param resource - The resource URL the client wants to access.
+ * @returns The generated authorization code string.
+ */
+export declare function createAuthorizationCode(clientId: string, redirectUri: string, codeChallenge: string, resource: string): string;
+/**
+ * Compute the S256 code challenge from a code verifier.
+ *
+ * @param codeVerifier - The PKCE code verifier string.
+ * @returns The base64url-encoded SHA-256 hash.
+ */
+export declare function computeCodeChallenge(codeVerifier: string): string;
+/**
+ * Verify that a code verifier matches a code challenge using S256.
+ *
+ * @param codeVerifier - The PKCE code verifier from the token request.
+ * @param codeChallenge - The code challenge stored at authorization time.
+ * @returns True if the verifier matches the challenge.
+ */
+export declare function verifyCodeChallenge(codeVerifier: string, codeChallenge: string): boolean;
+/**
+ * Consume an authorization code, validating all parameters.
+ *
+ * The code is deleted regardless of whether validation succeeds (single-use).
+ *
+ * @param code - The authorization code to consume.
+ * @param clientId - The client ID making the token request.
+ * @param redirectUri - The redirect URI from the token request.
+ * @param codeVerifier - The PKCE code verifier.
+ * @param resource - The resource URL from the token request.
+ * @returns The auth code record if valid, or undefined.
+ */
+export declare function consumeAuthorizationCode(code: string, clientId: string, redirectUri: string, codeVerifier: string, resource: string): AuthCodeRecord | undefined;
+/** Refresh token record with client and resource binding. */
+export interface RefreshTokenRecord {
+    token: string;
+    clientId: string;
+    resource: string;
+    createdAt: number;
+    expiresAt: number;
+}
+/**
+ * Create a new refresh token for the given client and resource.
+ *
+ * @param clientId - The client this refresh token is issued to.
+ * @param resource - The resource URL this refresh token is scoped to.
+ * @returns The generated refresh token string.
+ */
+export declare function createRefreshToken(clientId: string, resource: string): string;
+/**
+ * Consume a refresh token with rotation — the old token is invalidated and
+ * a new one must be issued in its place.
+ *
+ * @param token - The refresh token to consume.
+ * @param clientId - The client ID making the refresh request.
+ * @returns The refresh token record if valid, or undefined.
+ */
+export declare function consumeRefreshToken(token: string, clientId: string): RefreshTokenRecord | undefined;
+/** Start the periodic OAuth state cleanup timer. Call once on server startup. */
+export declare function startOAuthCleanup(): void;
+/** Stop the periodic OAuth state cleanup timer. */
+export declare function stopOAuthCleanup(): void;
+/** Clear all OAuth state. Intended for testing only. */
+export declare function clearOAuthState(): void;
+//# sourceMappingURL=oauth.d.ts.map

package/dist/oauth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth.d.ts","sourceRoot":"","sources":["../src/oauth.ts"],"names":[],"mappings":"AAuBA,sCAAsC;AACtC,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;CACnB;AAKD;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,YAAY,EAAE,MAAM,EAAE,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,CAwBpG;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,CAEpE;AAID,0DAA0D;AAC1D,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAKD;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,EACnB,aAAa,EAAE,MAAM,EACrB,QAAQ,EAAE,MAAM,GACf,MAAM,CAeR;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAEjE;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,YAAY,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,OAAO,CAGxF;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,MAAM,GACf,cAAc,GAAG,SAAS,CA+B5B;AAID,6DAA6D;AAC7D,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAKD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAW7E;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS,CAmBnG;AAMD,iFAAiF;AACjF,wBAAgB,iBAAiB,IAAI,IAAI,CAuBxC;AAED,mDAAmD;AACnD,wBAAgB,gBAAgB,IAAI,IAAI,CAKvC;AAED,wDAAwD;AACxD,wBAAgB,eAAe,IAAI,IAAI,CAItC"}