@fitzzero/quickdraw-core 3.5.0 → 3.7.0

package/dist/server/express/index.js

@@ -0,0 +1,60 @@
+import { ipKeyGenerator, rateLimit } from 'express-rate-limit';
+
+// src/server/express/rateLimit.ts
+function handler(_req, res, _next, options) {
+  const retryAfterSec = Math.max(1, Math.ceil((options.windowMs ?? 6e4) / 1e3));
+  if (!res.getHeader("Retry-After")) {
+    res.setHeader("Retry-After", String(retryAfterSec));
+  }
+  res.status(options.statusCode ?? 429).json({ error: "Rate limit exceeded" });
+}
+var jsonLimiter = {
+  standardHeaders: true,
+  legacyHeaders: false,
+  handler
+};
+function stripIp(raw) {
+  const ip = raw ?? "unknown";
+  return ip.startsWith("::ffff:") ? ip.slice(7) : ip;
+}
+function bearerOrIp(req) {
+  const auth = req.headers.authorization ?? "";
+  if (auth.startsWith("Bearer ")) return auth.slice(7);
+  return ipKeyGenerator(stripIp(req.ip));
+}
+function createJsonRateLimiter(options) {
+  return rateLimit({ ...jsonLimiter, ...options });
+}
+function createAuthLimiter(overrides = {}) {
+  return createJsonRateLimiter({
+    windowMs: 15 * 60 * 1e3,
+    max: 20,
+    skip: (req) => req.path.endsWith("/status"),
+    ...overrides
+  });
+}
+function createAuthStatusLimiter(overrides = {}) {
+  return createJsonRateLimiter({
+    windowMs: 15 * 60 * 1e3,
+    max: 120,
+    ...overrides
+  });
+}
+function createWebhookLimiter(overrides = {}) {
+  return createJsonRateLimiter({
+    windowMs: 60 * 1e3,
+    max: 300,
+    ...overrides
+  });
+}
+function createPublicApiLimiter(overrides = {}) {
+  return createJsonRateLimiter({
+    windowMs: 60 * 1e3,
+    max: 60,
+    ...overrides
+  });
+}
+
+export { bearerOrIp, createAuthLimiter, createAuthStatusLimiter, createJsonRateLimiter, createPublicApiLimiter, createWebhookLimiter, stripIp };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/server/express/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/server/express/rateLimit.ts"],"names":[],"mappings":";;;AAqBA,SAAS,OAAA,CAAQ,IAAA,EAAe,GAAA,EAAe,KAAA,EAAqB,OAAA,EAAwB;AAC1F,EAAA,MAAM,aAAA,GAAgB,IAAA,CAAK,GAAA,CAAI,CAAA,EAAG,IAAA,CAAK,MAAM,OAAA,CAAQ,QAAA,IAAY,GAAA,IAAU,GAAI,CAAC,CAAA;AAChF,EAAA,IAAI,CAAC,GAAA,CAAI,SAAA,CAAU,aAAa,CAAA,EAAG;AACjC,IAAA,GAAA,CAAI,SAAA,CAAU,aAAA,EAAe,MAAA,CAAO,aAAa,CAAC,CAAA;AAAA,EACpD;AACA,EAAA,GAAA,CAAI,MAAA,CAAO,QAAQ,UAAA,IAAc,GAAG,EAAE,IAAA,CAAK,EAAE,KAAA,EAAO,qBAAA,EAAuB,CAAA;AAC7E;AAEA,IAAM,WAAA,GAA8B;AAAA,EAClC,eAAA,EAAiB,IAAA;AAAA,EACjB,aAAA,EAAe,KAAA;AAAA,EACf;AACF,CAAA;AAGO,SAAS,QAAQ,GAAA,EAAiC;AACvD,EAAA,MAAM,KAAK,GAAA,IAAO,SAAA;AAClB,EAAA,OAAO,GAAG,UAAA,CAAW,SAAS,IAAI,EAAA,CAAG,KAAA,CAAM,CAAC,CAAA,GAAI,EAAA;AAClD;AAOO,SAAS,WAAW,GAAA,EAAsB;AAC/C,EAAA,MAAM,IAAA,GAAO,GAAA,CAAI,OAAA,CAAQ,aAAA,IAAiB,EAAA;AAC1C,EAAA,IAAI,KAAK,UAAA,CAAW,SAAS,GAAG,OAAO,IAAA,CAAK,MAAM,CAAC,CAAA;AACnD,EAAA,OAAO,cAAA,CAAe,OAAA,CAAQ,GAAA,CAAI,EAAE,CAAC,CAAA;AACvC;AAKO,SAAS,sBAAsB,OAAA,EAAkD;AACtF,EAAA,OAAO,UAAU,EAAE,GAAG,WAAA,EAAa,GAAG,SAAS,CAAA;AACjD;AAGO,SAAS,iBAAA,CAAkB,SAAA,GAA4B,EAAC,EAA4B;AACzF,EAAA,OAAO,qBAAA,CAAsB;AAAA,IAC3B,QAAA,EAAU,KAAK,EAAA,GAAK,GAAA;AAAA,IACpB,GAAA,EAAK,EAAA;AAAA,IACL,MAAM,CAAC,GAAA,KAAQ,GAAA,CAAI,IAAA,CAAK,SAAS,SAAS,CAAA;AAAA,IAC1C,GAAG;AAAA,GACJ,CAAA;AACH;AAGO,SAAS,uBAAA,CAAwB,SAAA,GAA4B,EAAC,EAA4B;AAC/F,EAAA,OAAO,qBAAA,CAAsB;AAAA,IAC3B,QAAA,EAAU,KAAK,EAAA,GAAK,GAAA;AAAA,IACpB,GAAA,EAAK,GAAA;AAAA,IACL,GAAG;AAAA,GACJ,CAAA;AACH;AAGO,SAAS,oBAAA,CAAqB,SAAA,GAA4B,EAAC,EAA4B;AAC5F,EAAA,OAAO,qBAAA,CAAsB;AAAA,IAC3B,UAAU,EAAA,GAAK,GAAA;AAAA,IACf,GAAA,EAAK,GAAA;AAAA,IACL,GAAG;AAAA,GACJ,CAAA;AACH;AAGO,SAAS,sBAAA,CAAuB,SAAA,GAA4B,EAAC,EAA4B;AAC9F,EAAA,OAAO,qBAAA,CAAsB;AAAA,IAC3B,UAAU,EAAA,GAAK,GAAA;AAAA,IACf,GAAA,EAAK,EAAA;AAAA,IACL,GAAG;AAAA,GACJ,CAAA;AACH","file":"index.js","sourcesContent":["/**\n * Express rate-limit presets built on express-rate-limit.\n *\n * Lives in the dedicated `/server/express` subpath so the core `/server`\n * entry point carries no express-rate-limit dependency. All presets are\n * factories (not module-level singletons) so env/config is read at call time.\n *\n * Note: distinct from the Socket.IO `createRateLimiter` exported from\n * `/server` — these protect REST routes (OAuth, webhooks, public APIs).\n */\n\nimport type { NextFunction, Request, Response } from \"express\";\nimport {\n  ipKeyGenerator,\n  rateLimit,\n  type Options,\n  type RateLimitRequestHandler,\n} from \"express-rate-limit\";\n\ntype PartialOptions = Partial<Options>;\n\nfunction handler(_req: Request, res: Response, _next: NextFunction, options: Options): void {\n  const retryAfterSec = Math.max(1, Math.ceil((options.windowMs ?? 60_000) / 1000));\n  if (!res.getHeader(\"Retry-After\")) {\n    res.setHeader(\"Retry-After\", String(retryAfterSec));\n  }\n  res.status(options.statusCode ?? 429).json({ error: \"Rate limit exceeded\" });\n}\n\nconst jsonLimiter: PartialOptions = {\n  standardHeaders: true,\n  legacyHeaders: false,\n  handler,\n};\n\n/** Normalize IPv4-mapped IPv6 addresses (::ffff:1.2.3.4 → 1.2.3.4). */\nexport function stripIp(raw: string | undefined): string {\n  const ip = raw ?? \"unknown\";\n  return ip.startsWith(\"::ffff:\") ? ip.slice(7) : ip;\n}\n\n/**\n * Key by Bearer token when present, falling back to client IP. Lets\n * token-authenticated clients get their own bucket instead of sharing\n * a NAT'd IP.\n */\nexport function bearerOrIp(req: Request): string {\n  const auth = req.headers.authorization ?? \"\";\n  if (auth.startsWith(\"Bearer \")) return auth.slice(7);\n  return ipKeyGenerator(stripIp(req.ip));\n}\n\n/**\n * Base factory: JSON 429 body + Retry-After header + standard headers.\n */\nexport function createJsonRateLimiter(options: PartialOptions): RateLimitRequestHandler {\n  return rateLimit({ ...jsonLimiter, ...options });\n}\n\n/** OAuth flows: 20 requests / 15 min per IP (status sub-routes excluded). */\nexport function createAuthLimiter(overrides: PartialOptions = {}): RateLimitRequestHandler {\n  return createJsonRateLimiter({\n    windowMs: 15 * 60 * 1000,\n    max: 20,\n    skip: (req) => req.path.endsWith(\"/status\"),\n    ...overrides,\n  });\n}\n\n/** Auth status polling: 120 requests / 15 min per IP. */\nexport function createAuthStatusLimiter(overrides: PartialOptions = {}): RateLimitRequestHandler {\n  return createJsonRateLimiter({\n    windowMs: 15 * 60 * 1000,\n    max: 120,\n    ...overrides,\n  });\n}\n\n/** Inbound webhooks: 300 requests / min per IP. */\nexport function createWebhookLimiter(overrides: PartialOptions = {}): RateLimitRequestHandler {\n  return createJsonRateLimiter({\n    windowMs: 60 * 1000,\n    max: 300,\n    ...overrides,\n  });\n}\n\n/** Generic public API: 60 requests / min per IP. */\nexport function createPublicApiLimiter(overrides: PartialOptions = {}): RateLimitRequestHandler {\n  return createJsonRateLimiter({\n    windowMs: 60 * 1000,\n    max: 60,\n    ...overrides,\n  });\n}\n"]}

package/dist/server/index.d.ts

@@ -827,6 +827,10 @@ interface DiscordUser {
  * Discord OAuth provider configuration.
  */
 declare const discordProvider: OAuthProvider<DiscordUser>;
+/**
+ * Get Discord avatar URL.
+ */
+declare function getDiscordAvatarUrl(user: DiscordUser): string;
 
 /**
  * Google user information.
@@ -843,6 +847,206 @@ interface GoogleUser {
  */
 declare const googleProvider: OAuthProvider<GoogleUser>;
 
+/**
+ * Mock OAuth provider for local development and tests.
+ *
+ * Implements a real OAuth 2.0 authorization-code flow served by the app's own
+ * API, so `createOAuthURL` and `exchangeOAuthCode` work unchanged — the mock
+ * is just a provider whose authorize/token/userinfo endpoints the app mounts
+ * via `registerMockOAuthProvider`. Users are supplied by the app (typically
+ * seeded demo accounts); no real credentials are involved.
+ *
+ * Production hard-block: routes are never mounted when NODE_ENV is
+ * "production" or ENABLE_MOCK_OAUTH !== "true", and every handler re-checks
+ * NODE_ENV at request time. Apps should add a third layer and refuse to boot
+ * in production with the flag set.
+ */
+
+interface MockOAuthUser {
+    id: string;
+    email: string;
+    name: string;
+    picture?: string | null;
+}
+declare const DEFAULT_MOCK_PATH_PREFIX = "/auth/mock/provider";
+declare function isMockOAuthEnabled(): boolean;
+interface MockOAuthProviderOptions {
+    /**
+     * Base URL the API server can use to reach itself for the token/userinfo
+     * exchange (server-side fetch). Defaults to apiBaseUrl — override in
+     * containers/codespaces where the public URL isn't self-reachable
+     * (e.g. "http://localhost:4000").
+     */
+    internalBaseUrl?: string;
+    /** Route prefix for the mock endpoints. Default: "/auth/mock/provider". */
+    pathPrefix?: string;
+}
+/**
+ * Create the mock OAuth provider definition.
+ *
+ * `parseUserInfo` returns a GoogleUser-compatible shape with `id` set to the
+ * user's email, so `providerAccountId` stays stable across database re-seeds.
+ */
+declare function createMockOAuthProvider(apiBaseUrl: string, options?: MockOAuthProviderOptions): OAuthProvider<GoogleUser>;
+interface MockRequest {
+    url?: string;
+    originalUrl?: string;
+    query?: Record<string, unknown>;
+    headers: Record<string, string | string[] | undefined>;
+    body?: unknown;
+}
+interface MockResponse {
+    status(code: number): MockResponse;
+    json(body: unknown): unknown;
+    send(body: string): unknown;
+    redirect(url: string): unknown;
+}
+type MockHandler = (req: MockRequest, res: MockResponse) => void | Promise<void>;
+interface MockOAuthRouter {
+    get(path: string, handler: MockHandler): unknown;
+    post(path: string, handler: MockHandler): unknown;
+}
+interface RegisterMockOAuthOptions {
+    /**
+     * Supply the users shown in the dev login picker (typically seeded demo
+     * accounts). Injected so core never touches the app's database.
+     */
+    listUsers: () => Promise<MockOAuthUser[]>;
+    /** Route prefix — must match createMockOAuthProvider's. */
+    pathPrefix?: string;
+    /**
+     * Extra origins allowed for redirect_uri beyond CLIENT_URL /
+     * EXTRA_ALLOWED_ORIGINS / localhost / private LAN IPs.
+     */
+    allowedRedirectOrigins?: string[];
+    logger?: Logger;
+}
+/**
+ * Mount the mock OAuth provider endpoints (authorize, token, userinfo) on an
+ * Express-compatible router.
+ *
+ * No-ops (returning false) unless `isMockOAuthEnabled()` — i.e. in production
+ * or without ENABLE_MOCK_OAUTH=true the routes are never mounted.
+ */
+declare function registerMockOAuthProvider(router: MockOAuthRouter, options: RegisterMockOAuthOptions): boolean;
+
+/**
+ * Origin validation utility for OAuth redirect and CORS security.
+ */
+declare const OAUTH_RETURN_ORIGIN_COOKIE = "oauth_return_origin";
+interface ValidateOriginOptions {
+    /**
+     * The primary web client origin. Defaults to process.env.CLIENT_URL.
+     */
+    clientUrl?: string;
+    /**
+     * Additional exact-match origins. Defaults to the comma-separated
+     * process.env.EXTRA_ALLOWED_ORIGINS. Lets a single API back multiple web
+     * hosts (e.g. prod + staging).
+     */
+    extraAllowedOrigins?: string[];
+    /**
+     * App-specific origin patterns (e.g. preview-deploy subdomains).
+     */
+    allowedPatterns?: RegExp[];
+    /**
+     * Allow GitHub Codespace forwarded-port origins
+     * (https://{workspace}-{username}-{port}.app.github.dev). Default: true.
+     */
+    allowCodespaces?: boolean;
+    /**
+     * Allow http://localhost:* when NODE_ENV !== "production". Default: true.
+     */
+    allowLocalhostInDev?: boolean;
+}
+/**
+ * Validates if an origin is safe for OAuth redirect / CORS.
+ *
+ * Only the origin (scheme + host + port) is compared, never the path, to
+ * prevent path-injection bypasses.
+ *
+ * @param origin - The origin to validate
+ * @param options - Override env-derived defaults
+ * @returns The validated origin if allowed, null otherwise
+ */
+declare function validateRedirectOrigin(origin: string, options?: ValidateOriginOptions): string | null;
+
+/**
+ * Secure session cookie helpers.
+ *
+ * Uses a structural response type so the module works with Express (or any
+ * compatible framework) without a runtime/type dependency on it.
+ */
+declare const SESSION_COOKIE = "session";
+interface CookieSettings {
+    httpOnly: boolean;
+    secure: boolean;
+    sameSite: "lax" | "none";
+    path: string;
+    domain?: string;
+    maxAge?: number;
+}
+interface CookieResponse {
+    cookie(name: string, value: string, options: CookieSettings): unknown;
+    clearCookie(name: string, options: CookieSettings): unknown;
+}
+interface SessionCookieOptions {
+    /** Cookie name. Default: "session". */
+    cookieName?: string;
+    /** Lifetime in ms. Default: 30 days. */
+    maxAgeMs?: number;
+    /** Cookie domain. Defaults to process.env.COOKIE_DOMAIN. */
+    domain?: string;
+}
+declare function setSessionCookie(res: CookieResponse, jwt: string, options?: SessionCookieOptions): void;
+declare function clearSessionCookie(res: CookieResponse, options?: SessionCookieOptions): void;
+
+/**
+ * REST authentication middleware factory.
+ *
+ * Authenticates requests via session cookie or Bearer token, verifies the JWT,
+ * then checks session revocation via an injected lookup (the app owns the
+ * database). Uses structural request/response types so there is no runtime or
+ * type dependency on Express.
+ */
+interface AuthRequest {
+    cookies?: Record<string, string>;
+    headers: {
+        authorization?: string;
+    };
+    userId?: string;
+}
+interface AuthResponse {
+    status(code: number): {
+        json(body: unknown): unknown;
+    };
+}
+interface RequireAuthOptions {
+    /**
+     * Look up the session for a token. Return null when the session does not
+     * exist; sessions past expiresAt are rejected. This mirrors the socket auth
+     * path so a revoked/logged-out session can no longer authenticate REST
+     * requests until the JWT naturally expires.
+     */
+    getSession: (token: string) => Promise<{
+        expiresAt: Date;
+    } | null>;
+    /** JWT signing secret. Defaults to process.env.JWT_SECRET. */
+    jwtSecret?: string;
+    /** Cookie to read the JWT from. Default: "session". */
+    cookieName?: string;
+}
+/**
+ * Extract a JWT from the session cookie or Authorization header
+ * (cookie takes priority).
+ */
+declare function extractBearerOrCookieToken(req: AuthRequest, cookieName?: string): string | null;
+/**
+ * Create an Express-compatible middleware that attaches req.userId on success
+ * and responds 401 on failure.
+ */
+declare function createRequireAuth(options: RequireAuthOptions): (req: AuthRequest, res: AuthResponse, next: () => void) => Promise<void>;
+
 /**
  * Environment variable validation utilities.
  * Helps ensure required environment variables are set before the application starts.
@@ -927,6 +1131,28 @@ declare function checkEnv(options: ValidateEnvOptions): EnvValidationResult;
  */
 declare function requireEnv(name: string, defaultValue?: string): string;
 
+/**
+ * AES-256-GCM encryption helpers for at-rest secrets (e.g. stored OAuth tokens).
+ *
+ * Requires ENCRYPTION_KEY: a 64-character hex string (32 bytes).
+ * Ciphertext format: "iv:authTag:ciphertext" (all hex).
+ */
+
+declare function encrypt(plaintext: string): string;
+declare function decrypt(ciphertext: string): string;
+/**
+ * Returns true when the value looks like AES-256-GCM ciphertext
+ * (iv:authTag:data, all hex). Plaintext OAuth tokens (e.g. gho_xxx) will not match.
+ */
+declare function isEncrypted(value: string): boolean;
+/**
+ * Decrypt if the value is in encrypted format, otherwise return as-is.
+ * Allows graceful handling of pre-migration plaintext tokens.
+ */
+declare function decryptIfEncrypted(value: string): string;
+/** Safe wrapper that returns `null` instead of throwing on invalid/stale ciphertext. */
+declare function tryDecrypt(ciphertext: string, logger?: Logger): string | null;
+
 /**
  * Options for customizing field generation.
  */
@@ -1106,4 +1332,4 @@ declare function createMcpRoutes(router: Router, options: McpHttpRoutesOptions):
  */
 declare function generateToolMetadata(options: GenerateToolMetadataOptions): void;
 
-export { AdminListPayload, AdminListResponse, AdminSetACLPayload, AdminSubscribersResponse, BaseService, BaseServiceInstance, BaseServiceOptions, type DiscordUser, type EnvValidationResult, type GenerateToolMetadataOptions, type GoogleUser, InstallAdminMethodsOptions, type JWTPayload, type McpHttpRoutesOptions, ServiceMethodContext as McpMethodContext, ServiceMethodDefinition as McpMethodDefinition, McpRegistry, type McpRegistryInstance, type McpRegistryOptions, type McpServiceInstance, type McpStdioServerOptions, type McpToolDefinition, type MethodSpec, type OAuthConfig, type OAuthProvider, type OAuthTokenResponse, PrismaDelegate, QuickdrawServerOptions, QuickdrawServerResult, QuickdrawSocket, type RateLimitOptions, type RateLimiter, type RedisAdapterOptions, type RedisAdapterResult, type ServiceInfo, type ServiceMethodInfo, ServiceRegistry, ServiceRegistryInstance, type ServiceRegistryOptions, type ServiceToolSpec, type ValidateEnvOptions, type ZodToAdminFieldsOptions, applyRateLimitMiddleware, bootstrapMcpServer, checkEnv, createJWT, createMcpRoutes, createMcpStdioServer, createOAuthURL, createQuickdrawServer, createRateLimiter, createTieredRateLimiter, discordProvider, exchangeOAuthCode, generateToolMetadata, getDefaultEntityFields, googleProvider, isRedisAdapterAvailable, mergeWithDefaultFields, requireEnv, setupRedisAdapter, validateEnv, verifyJWT, zodToAdminFields };
+export { AdminListPayload, AdminListResponse, AdminSetACLPayload, AdminSubscribersResponse, type AuthRequest, type AuthResponse, BaseService, BaseServiceInstance, BaseServiceOptions, type CookieResponse, type CookieSettings, DEFAULT_MOCK_PATH_PREFIX, type DiscordUser, type EnvValidationResult, type GenerateToolMetadataOptions, type GoogleUser, InstallAdminMethodsOptions, type JWTPayload, type McpHttpRoutesOptions, ServiceMethodContext as McpMethodContext, ServiceMethodDefinition as McpMethodDefinition, McpRegistry, type McpRegistryInstance, type McpRegistryOptions, type McpServiceInstance, type McpStdioServerOptions, type McpToolDefinition, type MethodSpec, type MockOAuthProviderOptions, type MockOAuthRouter, type MockOAuthUser, OAUTH_RETURN_ORIGIN_COOKIE, type OAuthConfig, type OAuthProvider, type OAuthTokenResponse, PrismaDelegate, QuickdrawServerOptions, QuickdrawServerResult, QuickdrawSocket, type RateLimitOptions, type RateLimiter, type RedisAdapterOptions, type RedisAdapterResult, type RegisterMockOAuthOptions, type RequireAuthOptions, SESSION_COOKIE, type ServiceInfo, type ServiceMethodInfo, ServiceRegistry, ServiceRegistryInstance, type ServiceRegistryOptions, type ServiceToolSpec, type SessionCookieOptions, type ValidateEnvOptions, type ValidateOriginOptions, type ZodToAdminFieldsOptions, applyRateLimitMiddleware, bootstrapMcpServer, checkEnv, clearSessionCookie, createJWT, createMcpRoutes, createMcpStdioServer, createMockOAuthProvider, createOAuthURL, createQuickdrawServer, createRateLimiter, createRequireAuth, createTieredRateLimiter, decrypt, decryptIfEncrypted, discordProvider, encrypt, exchangeOAuthCode, extractBearerOrCookieToken, generateToolMetadata, getDefaultEntityFields, getDiscordAvatarUrl, googleProvider, isEncrypted, isMockOAuthEnabled, isRedisAdapterAvailable, mergeWithDefaultFields, registerMockOAuthProvider, requireEnv, setSessionCookie, setupRedisAdapter, tryDecrypt, validateEnv, validateRedirectOrigin, verifyJWT, zodToAdminFields };