@fitzzero/quickdraw-core 5.1.0 → 5.1.2

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

@@ -1,8 +1,9 @@
-import { L as Logger } from '../../logger-BY28acW-.js';
+import { L as Logger } from '../../logger-Yz93KzdV.js';
 import { IncomingHttpHeaders, IncomingMessage, ServerResponse } from 'node:http';
-import { M as MaybePromise, P as Principal } from '../../types-Cu0vmx7c.js';
-import { b as AuthenticateRequest, H as HttpRequest } from '../../auth-BhWqdyb-.js';
-import '../../infer-Teo1xpsd.js';
+import { M as MaybePromise, P as Principal } from '../../types-CYliTP65.js';
+import { A as AllowedOrigin } from '../../origins-kvpxnVcW.js';
+import { b as AuthenticateRequest, H as HttpRequest } from '../../auth-DXiSJZaf.js';
+import '../../infer-BmoZsL9a.js';
 import 'socket.io';
 
 /**
@@ -60,10 +61,11 @@ interface SessionCookieOptions {
 }
 /**
  * Sets the session cookie, under the name {@link sessionCookieNameFor} gives
- * the response's request, so `socketAuth` and the HTTP transport read it.
+ * the response's request, so `socketAuth` and the HTTP transport read it,
+ * and clears a stale `__Host-session` that would shadow it.
  */
 declare function setSessionCookie(res: CookieResponse, jwt: string, options?: SessionCookieOptions): void;
-/** Clears the session cookie `setSessionCookie` sets on the same request. */
+/** Clears the session cookie `setSessionCookie` sets on the same request, and a stale `__Host-session` beside it. */
 declare function clearSessionCookie(res: CookieResponse, options?: SessionCookieOptions): void;
 
 interface JWTPayload {
@@ -86,7 +88,13 @@ interface JWTPayload {
  */
 declare function createJWT(payload: Omit<JWTPayload, "exp" | "iat">, secret: string, expiresIn?: string): Promise<string>;
 /**
- * Verify and decode a JWT token.
+ * Verify and decode a JWT token: its signature and expiry, nothing more.
+ * It is never a session check: a token of a session that was signed out,
+ * logged out everywhere or revoked still verifies until the JWT expires (7
+ * days by default). Check a session token with `liveSession({ sessions,
+ * jwtSecret }, token)`, `bearerAuth(...)` or `socketAuth(...)`, which ask the
+ * session store on every call. In development it warns once per process
+ * when it verifies a token that carries a session (`sid`).
  *
  * @param token - The JWT token to verify
  * @param secret - The secret key for verification
@@ -190,10 +198,12 @@ declare const googleProvider: OAuthProvider<GoogleUser>;
  * 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.
+ * Development only: routes are mounted only when ENABLE_MOCK_OAUTH is
+ * "true" and NODE_ENV is "development" or "test" (an allowlist: an unset
+ * NODE_ENV, "prod" or "staging" mount nothing, the 5.1 audit's AUTH-3), every
+ * handler re-checks NODE_ENV at request time, and mounting them logs a
+ * warning. Apps should add a third layer and refuse to boot outside
+ * development with the flag set.
  */
 
 interface MockOAuthUser {
@@ -203,6 +213,7 @@ interface MockOAuthUser {
     picture?: string | null;
 }
 declare const DEFAULT_MOCK_PATH_PREFIX = "/auth/mock/provider";
+/** True when ENABLE_MOCK_OAUTH is "true" and NODE_ENV is "development" or "test". */
 declare function isMockOAuthEnabled(): boolean;
 interface MockOAuthProviderOptions {
     /**
@@ -259,8 +270,9 @@ interface RegisterMockOAuthOptions {
  * 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.
+ * No-ops (returning false) unless `isMockOAuthEnabled()` — i.e. without
+ * ENABLE_MOCK_OAUTH=true, or unless NODE_ENV is development or test, the
+ * routes are never mounted. Mounting them logs a warning.
  */
 declare function registerMockOAuthProvider(router: MockOAuthRouter, options: RegisterMockOAuthOptions): boolean;
 
@@ -351,8 +363,8 @@ interface RequireAuthOptions {
     /**
      * Cookie to read the JWT from. Default: the names `setSessionCookie` and
      * the auth routes set on the same request (`sessionCookieNamesFor`):
-     * `__Host-session` over HTTPS, `session` (then `__Host-session`) over
-     * plain HTTP or when `COOKIE_DOMAIN` is set.
+     * `__Host-session` over HTTPS, `__Host-session` then `session` over plain
+     * HTTP or when `COOKIE_DOMAIN` is set.
      */
     cookieName?: string;
 }
@@ -385,13 +397,6 @@ interface AuthRouteRequest extends IncomingMessage {
 /** The response the routes answer: Express's, which also sets cookies. */
 type AuthRouteResponse = ServerResponse & CookieResponse;
 
-/**
- * An allowed origin: exact (`"https://app.example.com"`), or a pattern over
- * whole origins, anchored at both ends
- * (`/^https:\/\/[a-z0-9-]+\.preview\.example\.com$/`).
- */
-type AllowedOrigin = string | RegExp;
-
 /** The cookie that carries a sign-in in progress, on a request that is not secure. */
 declare const OAUTH_STATE_COOKIE = "qd_oauth";
 /**
@@ -607,7 +612,8 @@ declare namespace discord {
  * The development sign-in: a picker of the app's demo users, served by the
  * routes through `registerMockOAuthProvider`. Left out (its routes answer
  * nothing) unless `isMockOAuthEnabled()`: `ENABLE_MOCK_OAUTH=true` and
- * `NODE_ENV` other than `production`.
+ * `NODE_ENV` `development` or `test` (an unset `NODE_ENV` leaves it out: set
+ * `NODE_ENV=development`). Mounting it logs a warning.
  */
 declare function mock(options: MockSignInOptions): MockSignInProvider;
 
@@ -767,8 +773,8 @@ interface SocketAuthOptions<P extends Principal = Principal> {
      * The session cookie's name. Default: the name the auth routes set on the
      * same handshake: `"session"` when `COOKIE_DOMAIN` gives the cookie a
      * domain; else `"__Host-session"` over HTTPS, where the plain name a
-     * sibling site could plant is never read, and `"session"` (then
-     * `"__Host-session"`) over plain HTTP. A name given here is the only one
+     * sibling site could plant is never read, and `"session"` over plain HTTP,
+     * where `"__Host-session"` is read first all the same. A name given here is the only one
      * read, on any handshake: give the routes' `cookie.name` here, or
      * `"session"` when their `cookie.domain` is set without `COOKIE_DOMAIN`. A
      * name the handshake repeats counts as no credential.
@@ -785,9 +791,11 @@ interface SocketAuthOptions<P extends Principal = Principal> {
      * Development sign-in without a session: a socket whose handshake carries
      * `auth: { userId }` and no token is that user, as this function answers:
      * their principal (its `userId` the one named), or `null` to refuse the
-     * handshake (an unknown id). For a game editor or load-test bots. Never in
-     * production: `socketAuth` throws when it is given while `NODE_ENV` is
-     * `"production"`, and refuses such a handshake there anyway. HTTP calls
+     * handshake (an unknown id). For a game editor or load-test bots. Only
+     * while `NODE_ENV` is `development` or `test`: `socketAuth` throws when it
+     * is given otherwise (an unset `NODE_ENV` included: set
+     * `NODE_ENV=development`), refuses such a handshake once `NODE_ENV` says
+     * otherwise, and `createServer` warns at startup while it is on. HTTP calls
      * never use it. Pass it only when the app's own flag is on:
      * `devCredentials: env.ENABLE_DEV_CREDENTIALS ? findDevUser : undefined`.
      */
@@ -813,13 +821,19 @@ interface CookieOriginRequest {
  * `Sec-Fetch-Site` names another site, and a socket handshake only when
  * `Sec-Fetch-Site` is `same-origin` or with `allowMissingOrigin`. A bearer
  * token is not ambient: check only a credential that came from the cookie
- * (`request.credential === "cookie"` on an HTTP `authenticate` request).
+ * (`request.sessionCookie` on an HTTP `authenticate` request, where the
+ * transport hands an `authenticate` other than socketAuth's the cookie; it is
+ * in `auth.token` only for socketAuth's). Then check the session against the
+ * store, on every call (`liveSession`).
  *
  * @example
  * authenticate: async (request) => {
- *   if (request.transport === "http" && request.credential === "cookie" &&
- *       !cookieOriginAllowed(request, allowedOrigins)) {
- *     throw new QuickdrawError("FORBIDDEN", "This page may not use the session cookie");
+ *   if (request.transport === "http" && request.sessionCookie !== undefined) {
+ *     if (!cookieOriginAllowed(request, allowedOrigins)) {
+ *       throw new QuickdrawError("FORBIDDEN", "This page may not use the session cookie");
+ *     }
+ *     const session = await liveSession({ sessions, jwtSecret }, request.sessionCookie);
+ *     // ...
  *   }
  *   // ...
  * }
@@ -836,6 +850,41 @@ declare function socketAuth<P extends Principal>(options: SocketAuthOptions<P> &
 }): SessionAuthenticate<P>;
 declare function socketAuth(options: SocketAuthOptions): SessionAuthenticate<Principal>;
 
+/** Options of {@link bearerAuth}: the auth routes' session store and secret, and how a principal is built. */
+interface BearerAuthOptions<P extends Principal = Principal> extends SessionKeys {
+    /**
+     * Builds the principal of a session's user, for example `kind: "agent"`
+     * for an MCP caller; its `userId` must be the session's. Default
+     * `{ userId, kind: "user" }`.
+     */
+    readonly loadPrincipal?: PrincipalLoader<P>;
+}
+/**
+ * What {@link bearerAuth} returns: the principal a bearer token signs in,
+ * `null` for no token, and a rejection (`UNAUTHENTICATED`) for a token that
+ * is not a live session's.
+ */
+type BearerAuthenticate<P extends Principal> = (token: unknown) => Promise<P | null>;
+/**
+ * Checks bearer tokens against the auth routes' sessions, on every call: no
+ * token (anything but a non-empty string) is anonymous (`null`); a token
+ * whose session was signed out, revoked or has expired, or a JWT without a
+ * session, is refused with `UNAUTHENTICATED`; a live session's token is its
+ * user's principal, built as `socketAuth` builds it. It records no socket
+ * session: for `createServer`'s `authenticate` use `socketAuth`.
+ *
+ * @example
+ * const verifySession = bearerAuth({ sessions, jwtSecret, loadPrincipal: (userId) => ({ userId, kind: "agent" }) });
+ * // the MCP bridge's principal hook
+ * createMcpRegistry({ ..., principal: (request) => verifySession(request.transport === "http" ? request.token : process.env.AGENT_TOKEN) });
+ * // an authenticate that takes bearer tokens only
+ * createHttpRouter({ dispatcher, auth: { authenticate: ({ auth }) => verifySession(auth.token) } });
+ */
+declare function bearerAuth<P extends Principal>(options: BearerAuthOptions<P> & {
+    readonly loadPrincipal: PrincipalLoader<P>;
+}): BearerAuthenticate<P>;
+declare function bearerAuth(options: BearerAuthOptions): BearerAuthenticate<Principal>;
+
 /** Options of {@link requireSession}. */
 interface RequireSessionOptions<P extends Principal = Principal> {
     /**
@@ -927,4 +976,4 @@ declare function requireSession(keys: SessionKeys, options?: RequireSessionOptio
  */
 declare function sessionOf<P extends Principal = Principal>(req: object): RequestSession<P>;
 
-export { type AllowedOrigin, type AuthCookieOptions, type AuthMiddleware, type AuthProfile, type AuthProvider, type AuthProviderInfo, type AuthRateLimits, type AuthRequest, type AuthResponse, type AuthRouteRequest, type AuthRouteResponse, type AuthRoutes, type AuthRoutesOptions, type AuthSession, type CookieOriginRequest, type CookieResponse, type CookieSettings, DEFAULT_MOCK_PATH_PREFIX, DEFAULT_SESSION_TTL_MS, type DevCredentials, type DiscordUser, GUEST_MAX_BODY_BYTES, type GoogleUser, type GuestOptions, type GuestProvider, type GuestUser, HOST_OAUTH_STATE_COOKIE, HOST_SESSION_COOKIE, type IssuedSession, type JWTPayload, MIN_JWT_SECRET_LENGTH, type MemorySessionStore, type MockOAuthProviderOptions, type MockOAuthRouter, type MockOAuthUser, type MockSignInOptions, type MockSignInProvider, OAUTH_RETURN_ORIGIN_COOKIE, OAUTH_STATE_COOKIE, OAUTH_STATE_TTL_MS, type OAuthClientOptions, type OAuthConfig, type OAuthProvider, type OAuthSignInProvider, type OAuthTokenResponse, type OptionalClientOptions, type PrincipalLoader, type RegisterMockOAuthOptions, type RequestSession, type RequireAuthOptions, type RequireSessionOptions, SESSION_COOKIE, type SessionAuthenticate, type SessionCookieOptions, type SessionKeys, type SessionMeta, type SessionMiddleware, type SessionRequest, type SessionStore, type SocketAuthOptions, type ValidateOriginOptions, clearSessionCookie, cookieOriginAllowed, createAuthRoutes, createJWT, createMemorySessionStore, createMockOAuthProvider, createOAuthURL, createRequireAuth, discord, discordProvider, exchangeOAuthCode, extractBearerOrCookieToken, getDiscordAvatarUrl, google, googleProvider, guest, isMockOAuthEnabled, issueSession, liveSession, mock, registerMockOAuthProvider, requireSession, sessionOf, setSessionCookie, socketAuth, validateRedirectOrigin, verifyJWT };
+export { AllowedOrigin, type AuthCookieOptions, type AuthMiddleware, type AuthProfile, type AuthProvider, type AuthProviderInfo, type AuthRateLimits, type AuthRequest, type AuthResponse, type AuthRouteRequest, type AuthRouteResponse, type AuthRoutes, type AuthRoutesOptions, type AuthSession, type BearerAuthOptions, type BearerAuthenticate, type CookieOriginRequest, type CookieResponse, type CookieSettings, DEFAULT_MOCK_PATH_PREFIX, DEFAULT_SESSION_TTL_MS, type DevCredentials, type DiscordUser, GUEST_MAX_BODY_BYTES, type GoogleUser, type GuestOptions, type GuestProvider, type GuestUser, HOST_OAUTH_STATE_COOKIE, HOST_SESSION_COOKIE, type IssuedSession, type JWTPayload, MIN_JWT_SECRET_LENGTH, type MemorySessionStore, type MockOAuthProviderOptions, type MockOAuthRouter, type MockOAuthUser, type MockSignInOptions, type MockSignInProvider, OAUTH_RETURN_ORIGIN_COOKIE, OAUTH_STATE_COOKIE, OAUTH_STATE_TTL_MS, type OAuthClientOptions, type OAuthConfig, type OAuthProvider, type OAuthSignInProvider, type OAuthTokenResponse, type OptionalClientOptions, type PrincipalLoader, type RegisterMockOAuthOptions, type RequestSession, type RequireAuthOptions, type RequireSessionOptions, SESSION_COOKIE, type SessionAuthenticate, type SessionCookieOptions, type SessionKeys, type SessionMeta, type SessionMiddleware, type SessionRequest, type SessionStore, type SocketAuthOptions, type ValidateOriginOptions, bearerAuth, clearSessionCookie, cookieOriginAllowed, createAuthRoutes, createJWT, createMemorySessionStore, createMockOAuthProvider, createOAuthURL, createRequireAuth, discord, discordProvider, exchangeOAuthCode, extractBearerOrCookieToken, getDiscordAvatarUrl, google, googleProvider, guest, isMockOAuthEnabled, issueSession, liveSession, mock, registerMockOAuthProvider, requireSession, sessionOf, setSessionCookie, socketAuth, validateRedirectOrigin, verifyJWT };