@fitzzero/quickdraw-core 3.6.0 → 3.8.0

package/dist/server/express/index.d.ts

@@ -0,0 +1,37 @@
+import { Request } from 'express';
+import { Options, RateLimitRequestHandler } from 'express-rate-limit';
+
+/**
+ * Express rate-limit presets built on express-rate-limit.
+ *
+ * Lives in the dedicated `/server/express` subpath so the core `/server`
+ * entry point carries no express-rate-limit dependency. All presets are
+ * factories (not module-level singletons) so env/config is read at call time.
+ *
+ * Note: distinct from the Socket.IO `createRateLimiter` exported from
+ * `/server` — these protect REST routes (OAuth, webhooks, public APIs).
+ */
+
+type PartialOptions = Partial<Options>;
+/** Normalize IPv4-mapped IPv6 addresses (::ffff:1.2.3.4 → 1.2.3.4). */
+declare function stripIp(raw: string | undefined): string;
+/**
+ * Key by Bearer token when present, falling back to client IP. Lets
+ * token-authenticated clients get their own bucket instead of sharing
+ * a NAT'd IP.
+ */
+declare function bearerOrIp(req: Request): string;
+/**
+ * Base factory: JSON 429 body + Retry-After header + standard headers.
+ */
+declare function createJsonRateLimiter(options: PartialOptions): RateLimitRequestHandler;
+/** OAuth flows: 20 requests / 15 min per IP (status sub-routes excluded). */
+declare function createAuthLimiter(overrides?: PartialOptions): RateLimitRequestHandler;
+/** Auth status polling: 120 requests / 15 min per IP. */
+declare function createAuthStatusLimiter(overrides?: PartialOptions): RateLimitRequestHandler;
+/** Inbound webhooks: 300 requests / min per IP. */
+declare function createWebhookLimiter(overrides?: PartialOptions): RateLimitRequestHandler;
+/** Generic public API: 60 requests / min per IP. */
+declare function createPublicApiLimiter(overrides?: PartialOptions): RateLimitRequestHandler;
+
+export { bearerOrIp, createAuthLimiter, createAuthStatusLimiter, createJsonRateLimiter, createPublicApiLimiter, createWebhookLimiter, stripIp };

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

@@ -1,7 +1,7 @@
-import { a as QuickdrawSocket, P as PrismaDelegate, b as BaseServiceOptions, I as InstallAdminMethodsOptions, A as AdminListPayload, c as AdminListResponse, d as AdminSetACLPayload, e as AdminSubscribersResponse, S as ServiceRegistryInstance, B as BaseServiceInstance, f as QuickdrawServerOptions, Q as QuickdrawServerResult } from '../types-DniMxkQs.js';
+import { a as QuickdrawSocket, P as PrismaDelegate, b as BaseServiceOptions, I as InstallAdminMethodsOptions, A as AdminListPayload, c as AdminListResponse, d as AdminSetACLPayload, e as AdminSubscribersResponse, S as ServiceRegistryInstance, B as BaseServiceInstance, f as QuickdrawServerOptions, Q as QuickdrawServerResult } from '../types-ClgSr90l.js';
 import { Server, Socket } from 'socket.io';
 import { z } from 'zod';
-import { ACL, Logger, AccessLevel, ServiceMethodContext, ServiceMethodDefinition, AdminServiceMeta, AdminFieldConfig } from '../shared/index.js';
+import { ACL, Logger, AccessLevel, ServiceMethodContext, ServiceMethodDefinition, ServiceChannelContext, ServiceChannelDefinition, AdminServiceMeta, AdminFieldConfig } from '../shared/index.js';
 import { Router } from 'express';
 import 'http';
 
@@ -19,6 +19,7 @@ import 'http';
  * @typeParam TCreateInput - The create input type
  * @typeParam TUpdateInput - The update input type
  * @typeParam TServiceMethods - Service method definitions map
+ * @typeParam TChannels - Service channel payload map (high-frequency fire-and-forget events)
  *
  * @example
  * ```typescript
@@ -48,7 +49,9 @@ declare abstract class BaseService<TEntity extends {
 } = Record<string, {
     payload: unknown;
     response: unknown;
-}>> {
+}>, TChannels extends {
+    [K in keyof TChannels]: unknown;
+} = Record<string, unknown>> {
     readonly serviceName: string;
     protected readonly hasEntryACL: boolean;
     protected readonly defaultACL: ACL;
@@ -57,6 +60,7 @@ declare abstract class BaseService<TEntity extends {
     protected delegate: PrismaDelegate<TEntity, TCreateInput, TUpdateInput> | undefined;
     protected io: Server | null;
     private readonly publicMethods;
+    private readonly publicChannels;
     private adminMeta;
     constructor(options: BaseServiceOptions);
     /**
@@ -138,6 +142,28 @@ declare abstract class BaseService<TEntity extends {
      * ```
      */
     emitToRoom(roomName: string, eventName: string, data: unknown): void;
+    /**
+     * Emit a custom event to a room using Socket.io's volatile flag.
+     *
+     * Volatile events are dropped for clients whose connection is backpressured
+     * instead of being buffered — exactly what you want for high-frequency state
+     * that is superseded by the next emit (game snapshots, cursor positions).
+     * Never use this for events a client must not miss.
+     *
+     * Intentionally does no per-call logging: this is a hot path, typically
+     * called at tick rate (10–60Hz).
+     *
+     * @example
+     * ```typescript
+     * // In a 20Hz game loop
+     * this.emitToRoomVolatile(
+     *   this.getRoomName(worldId),
+     *   'game:snapshot',
+     *   snapshot
+     * );
+     * ```
+     */
+    emitToRoomVolatile(roomName: string, eventName: string, data: unknown): void;
     /**
      * Emit a custom event to a specific user's room.
      * Users join `user:{userId}` on connection (set up in auth middleware).
@@ -274,6 +300,58 @@ declare abstract class BaseService<TEntity extends {
      * Get all public methods for registry discovery.
      */
     getPublicMethods(): ServiceMethodDefinition<unknown, unknown>[];
+    /**
+     * Define a channel: a fire-and-forget event for high-frequency traffic
+     * (game input, cursor positions, typing indicators).
+     *
+     * Channels differ from methods:
+     * - No ack, no response — the handler returns void and errors are logged,
+     *   never sent to the client.
+     * - Exempt from the global rate limiter; each channel enforces its own
+     *   per-socket token bucket (`ratePerSecond`/`burst`). Excess messages are
+     *   silently dropped; sustained extreme abuse disconnects the socket.
+     * - Access checks are fully synchronous and in-memory: authentication is
+     *   always required; "Moderate"/"Admin" check the socket's serviceAccess;
+     *   entry-level access is expressed via `requireRoom` (the socket must
+     *   already be in that room, which was ACL-gated at subscribe time).
+     * - `schema` is required — channel payloads are untrusted input arriving
+     *   at tick rate.
+     *
+     * Routes as the Socket.io event `channel:<serviceName>:<name>`.
+     *
+     * @example
+     * ```typescript
+     * this.defineChannel(
+     *   "input",
+     *   "Read",
+     *   (payload, ctx) => this.sim.applyInput(ctx.userId, payload),
+     *   {
+     *     schema: gameInputSchema,
+     *     ratePerSecond: 30,
+     *     requireRoom: () => this.getRoomName(GLOBAL_WORLD_ID),
+     *   },
+     * );
+     * ```
+     */
+    defineChannel<K extends keyof TChannels & string>(name: K, access: AccessLevel, handler: (payload: TChannels[K], context: ServiceChannelContext) => void, options: {
+        schema: z.ZodType<TChannels[K]>;
+        /** Sustained messages/second per socket. Default: 30 */
+        ratePerSecond?: number;
+        /** Bucket capacity for bursts. Default: 2 × ratePerSecond */
+        burst?: number;
+        /** Room the socket must already be in (null result skips the check). */
+        requireRoom?: (payload: TChannels[K]) => string | null;
+    }): ServiceChannelDefinition<TChannels[K]>;
+    /**
+     * Get all channels for registry discovery.
+     */
+    getPublicChannels(): ServiceChannelDefinition<unknown>[];
+    /**
+     * Synchronous, in-memory access check for a channel message.
+     * Called by the registry on the hot path — must not touch the database.
+     * Returns false to silently drop the message.
+     */
+    checkChannelAccess(channel: ServiceChannelDefinition<unknown>, socket: QuickdrawSocket, payload: unknown): boolean;
     /**
      * Verify that all expected service methods have been defined via defineMethod().
      * Call at the end of initMethods() to catch missing implementations at boot time.
@@ -416,6 +494,7 @@ declare class ServiceRegistry implements ServiceRegistryInstance {
     private readonly logResponses;
     private connectionHandlerInstalled;
     private readonly methodRegistry;
+    private readonly channelRegistry;
     constructor(io: Server, options?: ServiceRegistryOptions);
     /**
      * Install the single connection handler that wires all registered services.
@@ -434,6 +513,20 @@ declare class ServiceRegistry implements ServiceRegistryInstance {
      * Discover and store all public methods from a service.
      */
     private discoverServiceMethods;
+    /**
+     * Discover and store all channels from a service.
+     */
+    private discoverServiceChannels;
+    /**
+     * Register a channel as a socket event listener.
+     *
+     * This is the hot path for high-frequency traffic: no ack, no async access
+     * checks, no per-message logging. Order of operations per message:
+     * token bucket → schema validation → in-memory access check → handler.
+     * Any failure silently drops the message; sustained extreme flooding
+     * disconnects the socket.
+     */
+    private registerChannelListener;
     /**
      * Register a method as a socket event listener.
      */
@@ -624,6 +717,12 @@ interface RateLimitOptions {
      * Events to exclude from rate limiting (e.g., ['ping', 'pong'])
      */
     excludeEvents?: string[];
+    /**
+     * Event-name prefixes to exclude from rate limiting.
+     * Pass `[CHANNEL_EVENT_PREFIX]` ("channel:") so channel traffic bypasses
+     * the global limiter — channels enforce their own per-socket token buckets.
+     */
+    excludePrefixes?: string[];
     /**
      * Custom key generator for grouping requests.
      * Default uses socket.id.
@@ -662,7 +761,7 @@ interface RateLimiter {
     /**
      * Configuration options.
      */
-    options: Required<Pick<RateLimitOptions, "windowMs" | "maxRequests" | "excludeEvents">>;
+    options: Required<Pick<RateLimitOptions, "windowMs" | "maxRequests" | "excludeEvents" | "excludePrefixes">>;
 }
 /**
  * Create a rate limiter instance.
@@ -827,6 +926,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 +946,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 +1230,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 +1431,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 };