@stacknet/userutils 0.6.4 → 0.6.5

package/dist/server/index.d.cts

@@ -0,0 +1,499 @@
+type Web3Chain = 'ethereum' | 'solana' | 'polygon' | 'arbitrum' | 'base';
+/**
+ * Client-safe session metadata. Does NOT contain the JWT.
+ * Use ServerSession (from @stacknet/userutils/server) for server-side code that needs the JWT.
+ */
+interface Session {
+    id: string;
+    app_identity_id: string;
+    global_identity_commitment: string;
+    expires_at: number;
+    created_at: number;
+    stack_id?: string;
+    signed_by: string[];
+    user_id?: string;
+    address?: string;
+    chain?: Web3Chain;
+    auth_method?: string;
+}
+
+/**
+ * Server-only session type that includes the JWT.
+ * NEVER export this from the client bundle.
+ */
+interface ServerSession extends Session {
+    jwt: string;
+}
+
+/** Decode JWT payload without verification (server-side helper) */
+declare function decodeJWTPayload(jwt: string): Record<string, any> | null;
+/** Sign a JWT with HMAC-SHA256 */
+declare function signJWT(payload: Record<string, any>, secret: string): string;
+/** Verify a JWT signature with HMAC-SHA256 (constant-time comparison) */
+declare function verifyJWTSignature(jwt: string, secret: string): boolean;
+/** Verify JWT and return payload if valid (checks signature + expiry) */
+declare function verifyJWT(jwt: string, secret: string): Record<string, any> | null;
+/**
+ * Check if JWT needs refresh and return a new one if so.
+ * Returns null if no refresh needed or JWT is invalid.
+ */
+declare function maybeRefreshJWT(jwt: string, secret: string, expirySeconds?: number, refreshWindowSeconds?: number): string | null;
+/** Generate a cryptographically secure random token */
+declare function generateToken(bytes?: number): string;
+/** Options controlling how the real client IP is extracted from a Request.
+ *
+ *  The previous implementation trusted `X-Forwarded-For[0]` unconditionally,
+ *  which lets any direct caller pin arbitrary values and bypass per-IP rate
+ *  limits. The correct read depends on how many reverse proxies sit between
+ *  the app and the real client: with N trusted hops, the real client IP is
+ *  at position `(length - N)` in the XFF list, because each trusted hop
+ *  appends its peer IP and the attacker-controlled prefix is pushed left. */
+interface IPExtractorConfig {
+    /** Number of trusted reverse-proxy hops between this app and the real client.
+     *  - `0`: do NOT trust X-Forwarded-For (app is directly internet-exposed).
+     *  - `1` (default): one trusted proxy (e.g. single LB, Vercel edge, Nginx).
+     *  - `N`: N trusted hops; the real client IP is `XFF[length - N]`.
+     *  If XFF has fewer entries than expected, the chain is misconfigured or
+     *  spoofed and the extractor falls through to the next source. */
+    trustedProxyCount?: number;
+    /** Trust the `X-Real-IP` header. Only enable if your proxy sets it AND
+     *  strips any inbound `X-Real-IP` from clients. Default: `false`. */
+    trustRealIpHeader?: boolean;
+    /** Override entirely — return the real client IP from a request however
+     *  you know best (e.g. a platform-specific header like `cf-connecting-ip`
+     *  or `x-vercel-forwarded-for`). If this returns a non-empty string it
+     *  wins; if it returns null/empty the other strategies run. */
+    customExtractor?: (request: Request) => string | null | undefined;
+}
+/** Extract the real client IP address from a request.
+ *
+ *  Default behavior (`trustedProxyCount: 1`) is safe for the common case of
+ *  one trusted reverse proxy. Consumers with no proxy must pass `0`, and
+ *  consumers behind multiple proxies must pass the exact hop count. */
+declare function extractIP(request: Request, config?: IPExtractorConfig): string;
+
+/** Server-side configuration for handler factories */
+interface ServerConfig {
+    /** HMAC-SHA256 secret for signing JWTs */
+    authSecret: string;
+    /** StackNet backend URL (always https://stacknet.magma-rpc.com) */
+    stacknetUrl: string;
+    /** StackNet stack identifier */
+    stackId: string;
+    /** JWT secret for re-signing to StackNet (defaults to authSecret) */
+    stacknetJwtSecret?: string;
+    /** Cookie domain for subdomain sharing (e.g. '.geoff.ai') */
+    cookieDomain?: string;
+    /** Use Secure flag on cookies (default: true) */
+    secureCookies?: boolean;
+    /** Session max age in seconds (default: 604800 = 7 days) */
+    sessionMaxAge?: number;
+    /** JWT expiry in seconds (default: 900 = 15 minutes) */
+    jwtExpiry?: number;
+    /**
+     * Google OAuth client ID (single). Used by createGoogleOneTapHandler to
+     * validate the `aud` claim on incoming Google ID tokens. Required for
+     * Google One Tap — without it, an ID token issued to any other Google
+     * application could be replayed against this endpoint.
+     */
+    googleClientId?: string;
+    /**
+     * Google OAuth client IDs (multiple). Use when the stack accepts tokens
+     * from more than one Google client (e.g. web + native).
+     */
+    googleClientIds?: string[];
+    /**
+     * How the handlers should derive the real client IP for rate-limit keys.
+     * Defaults to `{ trustedProxyCount: 1 }`. Set `trustedProxyCount: 0` if
+     * the app is exposed directly (no proxy) — otherwise any caller can pin
+     * their X-Forwarded-For and bypass rate limiting.
+     */
+    ipConfig?: IPExtractorConfig;
+}
+
+/** Rate limiter interface — implement with Redis, Upstash, or use the in-memory default */
+interface RateLimiter {
+    check(key: string): Promise<{
+        allowed: boolean;
+        remaining: number;
+        retryAfter?: number;
+    }>;
+}
+/** Replay store interface — for preventing JWT re-sign replay attacks */
+interface ReplayStore {
+    has(key: string): Promise<boolean>;
+    set(key: string, ttlSeconds: number): Promise<void>;
+}
+/**
+ * In-memory rate limiter with sliding window.
+ *
+ * Safe default for single-process deployments. For multi-process or
+ * distributed environments, provide a Redis-backed RateLimiter instead.
+ */
+declare function createInMemoryRateLimiter(opts: {
+    maxRequests: number;
+    windowMs: number;
+}): RateLimiter;
+/** In-memory replay store (single-process, entries auto-expire) */
+declare function createInMemoryReplayStore(): ReplayStore;
+
+interface AuthCallbackOptions {
+    rateLimiter?: RateLimiter;
+}
+/**
+ * Factory: POST handler for auth callback (login completion).
+ *
+ * Accepts wallet signature verification or OTP results from client,
+ * validates with StackNet, sets HttpOnly JWT cookie + public session cookie + CSRF cookie.
+ */
+declare function createAuthCallback(config: ServerConfig, opts?: AuthCallbackOptions): (request: Request) => Promise<Response>;
+
+/**
+ * Factory: POST handler for logout.
+ * Revokes session with StackNet and clears all auth cookies.
+ */
+declare function createLogoutHandler(config: Pick<ServerConfig, 'stacknetUrl' | 'secureCookies' | 'cookieDomain'> & {
+    /**
+     * HMAC secret used to verify the JWT signature before extracting the
+     * sessionId for upstream revocation. STRONGLY RECOMMENDED.
+     *
+     * Without this, the handler skips upstream revocation entirely and only
+     * clears cookies — because trusting an unverified JWT for the sessionId
+     * would let an attacker plant a forged cookie and trigger DELETE on
+     * another user's session.
+     */
+    authSecret?: string;
+}): (request: Request) => Promise<Response>;
+
+/**
+ * Factory: GET handler for session validation.
+ * Reads HttpOnly JWT cookie, validates, returns public session info.
+ * Transparently refreshes JWT if close to expiry.
+ */
+declare function createSessionHandler(config: Pick<ServerConfig, 'authSecret' | 'jwtExpiry' | 'secureCookies' | 'cookieDomain' | 'sessionMaxAge'>): (request: Request) => Promise<Response>;
+
+interface OTPHandlerConfig extends Pick<ServerConfig, 'authSecret' | 'secureCookies' | 'cookieDomain' | 'sessionMaxAge' | 'jwtExpiry'> {
+    /** The OTP secret to validate against */
+    otpSecret: string;
+    /** Rate limiter (default: 5 attempts per 5 min per IP) */
+    rateLimiter?: RateLimiter;
+    /** How to extract the real client IP for rate-limit keys. Defaults to
+     *  `{ trustedProxyCount: 1 }`. Set `trustedProxyCount: 0` if the handler
+     *  is exposed directly (no proxy in front). */
+    ipConfig?: IPExtractorConfig;
+}
+/**
+ * Factory: POST handler for OTP verification.
+ * Validates OTP code, creates session JWT, sets HttpOnly cookie.
+ */
+declare function createOTPHandler(config: OTPHandlerConfig): (request: Request) => Promise<Response>;
+
+interface OAuthHandlerConfig {
+    rateLimiter?: RateLimiter;
+}
+/**
+ * Factory: OAuth flow handlers.
+ *
+ * Returns two handlers:
+ * - GET  /api/auth/oauth/[provider] — Starts OAuth flow, returns redirect URL
+ * - POST /api/auth/oauth/[provider]/callback — Handles OAuth callback, sets cookies
+ */
+declare function createOAuthHandlers(config: ServerConfig, opts?: OAuthHandlerConfig): {
+    startFlow: (request: Request) => Promise<Response>;
+    handleCallback: (request: Request) => Promise<Response>;
+};
+
+interface GoogleOneTapHandlerConfig {
+    rateLimiter?: RateLimiter;
+}
+/**
+ * Factory: POST handler for Google One Tap credential verification.
+ *
+ * Receives the Google JWT credential from the client, verifies it with
+ * Google's tokeninfo endpoint, then creates a StackNet session.
+ */
+declare function createGoogleOneTapHandler(config: ServerConfig, opts?: GoogleOneTapHandlerConfig): (request: Request) => Promise<Response>;
+
+interface PreviewCodeHandlerOptions {
+    rateLimiter?: RateLimiter;
+    /** Maximum session length in seconds (default 3600 = 1h). Preview
+     *  codes are meant for short-lived demo access — keep this
+     *  meaningfully shorter than a normal wallet/OAuth session. */
+    sessionMaxAge?: number;
+}
+/**
+ * Factory: POST handler for preview-code login.
+ *
+ * Flow:
+ *   1. Client POSTs `{code: "692232"}` to this route.
+ *   2. Handler validates the code against
+ *      `${config.stacknetUrl}/v1/preview-codes/:code` (public read —
+ *      the 6-digit code is itself the bearer credential).
+ *   3. Rejects on not-found / revoked / expired / exhausted.
+ *   4. Mints a local JWT (signed with `config.authSecret`) with
+ *      `sub = global_id = "preview_<code>"` and `auth_method =
+ *      "preview_code"`. Sets it as the `stackauth_jwt` HttpOnly
+ *      cookie so `useSession` recognizes the user as authenticated.
+ *   5. Also sets the public `stackauth_session` cookie + CSRF cookie
+ *      to match the normal wallet / OAuth callback shape.
+ *
+ * The preview-code bearer (`pc_<code>`) is expected to already be in
+ * `localStorage['stacknet-api-key']` — the widget sets that
+ * client-side after a successful POST here. Together, the cookie
+ * drives same-origin `useSession` / server-rendered pages, and the
+ * bearer drives direct stacknet API calls from the browser.
+ *
+ * Security:
+ *   - Rate-limited per IP (10 attempts / minute by default).
+ *   - Format guard: only 6-digit numeric codes reach the upstream
+ *     validator so nothing weird hits stacknet.
+ *   - No upstream JWT is trusted — the stacknet response is a
+ *     read-only row and the session JWT is freshly signed locally
+ *     with the app's own `authSecret`.
+ */
+declare function createPreviewCodeHandler(config: ServerConfig, opts?: PreviewCodeHandlerOptions): (request: Request) => Promise<Response>;
+
+interface BillingProxyConfig extends Pick<ServerConfig, 'authSecret' | 'stacknetUrl' | 'stackId' | 'stacknetJwtSecret' | 'secureCookies' | 'cookieDomain' | 'sessionMaxAge' | 'jwtExpiry'> {
+    /** Rate limiter for mutations (default: 20/min per user) */
+    rateLimiter?: RateLimiter;
+    /**
+     * Canonical absolute origin (e.g. "https://app.example.com") used when
+     * constructing Stripe success/cancel URLs. STRONGLY RECOMMENDED.
+     *
+     * Without this, the origin is derived from the request URL — which is
+     * populated from the `Host` header. If the app is deployed behind a
+     * proxy that does not validate / rewrite `Host`, an attacker can send
+     * `Host: evil.example` and the post-checkout redirect will point there.
+     * Stripe's dashboard allowlist catches most cases, but we should not
+     * depend on that alone.
+     *
+     * Must be a full http(s) origin with no path. Factory throws on
+     * malformed input so misconfigurations surface at boot, not at runtime.
+     */
+    canonicalOrigin?: string;
+}
+type Handler = (request: Request) => Promise<Response>;
+/**
+ * Factory: creates all billing route handlers that proxy to StackNet.
+ *
+ * All POST handlers validate CSRF tokens. All handlers validate the JWT cookie
+ * and transparently refresh if close to expiry.
+ */
+declare function createBillingProxy(config: BillingProxyConfig): {
+    plans: {
+        GET: Handler;
+    };
+    subscription: {
+        GET: Handler;
+    };
+    subscribe: {
+        POST: Handler;
+    };
+    cancel: {
+        POST: Handler;
+    };
+    usage: {
+        GET: Handler;
+    };
+    history: {
+        GET: Handler;
+    };
+    prepaid: {
+        POST: Handler;
+    };
+    verifyPrepaid: {
+        POST: Handler;
+    };
+    verifySession: {
+        POST: Handler;
+    };
+    subscribeSol: {
+        POST: Handler;
+    };
+    prepaidSol: {
+        POST: Handler;
+    };
+    topup: {
+        POST: Handler;
+    };
+};
+
+/**
+ * Factory: POST handler for Stripe webhooks.
+ * Forwards raw body + stripe-signature to StackNet for verification and processing.
+ */
+declare function createWebhookHandler(config: Pick<ServerConfig, 'stacknetUrl' | 'stackId'>): (request: Request) => Promise<Response>;
+
+interface CSRFConfig {
+    /** Cookie name (default: '__csrf') */
+    cookieName?: string;
+    /** Header name (default: 'x-csrf-token') */
+    headerName?: string;
+    /** Token length in bytes (default: 32) */
+    tokenLength?: number;
+    /** Use Secure flag on cookie (default: true) */
+    secure?: boolean;
+}
+/**
+ * Create CSRF protection using the double-submit cookie pattern.
+ *
+ * 1. Server sets a non-HttpOnly cookie with a random token
+ * 2. Client reads the cookie and sends the token in a header on mutations
+ * 3. Server validates cookie === header (attacker can't read cookie cross-origin)
+ */
+declare function createCSRFProtection(config?: CSRFConfig): {
+    /**
+     * Generate a CSRF token and add Set-Cookie header to a response.
+     * Call this on auth callback (login) to establish the CSRF cookie.
+     */
+    generateToken(headers: Headers): string;
+    /**
+     * Validate a request's CSRF token (cookie vs header).
+     * Returns true if valid, false if not.
+     */
+    validateRequest(request: Request): {
+        valid: boolean;
+        error?: string;
+    };
+    /** Cookie name for client-side reading */
+    cookieName: string;
+    /** Header name for client-side sending */
+    headerName: string;
+};
+
+/** Standard security response headers */
+declare function securityHeaders(): Record<string, string>;
+/**
+ * Wrap a request handler to add security headers to the response.
+ */
+declare function withSecurityHeaders(handler: (request: Request) => Promise<Response> | Response): (request: Request) => Promise<Response>;
+/**
+ * Generate security headers config for Next.js next.config.ts.
+ *
+ * Usage in next.config.ts:
+ * ```ts
+ * import { nextSecurityHeaders } from '@stacknet/userutils/server';
+ * export default { headers: () => [{ source: '/(.*)', headers: nextSecurityHeaders() }] };
+ * ```
+ */
+declare function nextSecurityHeaders(): Array<{
+    key: string;
+    value: string;
+}>;
+
+/**
+ * Re-sign a JWT using StackNet's HMAC-SHA256 scheme.
+ *
+ * Geoff apps sign JWTs with AUTH_SECRET. StackNet validates with JWT_SECRET.
+ * This function re-signs using the StackNet secret so the backend resolves
+ * the correct per-user identity.
+ */
+declare function resignForStackNet(jwt: string, stacknetJwtSecret: string): string | null;
+/**
+ * Build headers for proxying a user-scoped request to StackNet.
+ * Re-signs the JWT so StackNet recognises the user's identity.
+ *
+ * Refuses to interpolate any value that doesn't match the compact JWT
+ * format (header.body.signature, base64url segments only) to prevent
+ * header injection.
+ */
+declare function buildStackNetHeaders(jwt: string, stacknetJwtSecret: string): Record<string, string>;
+/**
+ * Extract JWT from a request's cookies or Authorization header.
+ */
+declare function extractJwt(request: Request): string | null;
+
+/**
+ * Server-side proxy helpers for StackNet preview codes.
+ *
+ * Preview codes are admin-minted 6-digit access credentials with a
+ * per-code token budget. Only the pinned admin global id (enforced
+ * by StackNet's state machine) can mint / list / revoke codes.
+ *
+ * These helpers wrap `fetch` against the StackNet HTTP layer with
+ * re-signed JWT cookies (same pattern as `buildStackNetHeaders`).
+ * Admin-console API routes are expected to call them; the raw
+ * endpoints are NOT exposed in the client bundle.
+ */
+interface PreviewCode {
+    code: string;
+    createdBy: string;
+    tokenBudget: number;
+    tokensUsed: number;
+    tokensRemaining: number;
+    createdAt: number;
+    expiresAt: number | null;
+    revoked: boolean;
+    /** Optional human-readable label (e.g. "Tester: Alice"). Absent on
+     *  codes minted before the name field shipped. */
+    name?: string | null;
+}
+interface MintPreviewCodeOptions {
+    /** Token budget for the new code. Must be > 0. */
+    tokenBudget: number;
+    /** Optional explicit 6-digit code string. Server generates one
+     *  if omitted. */
+    code?: string;
+    /** Optional Unix-ms expiry. */
+    expiresAt?: number;
+    /** Optional human-readable label for the code. Shown in the admin
+     *  list so the operator can tell codes apart. */
+    name?: string;
+}
+interface PreviewCodesProxyConfig {
+    /** StackNet base URL (no trailing slash). */
+    stacknetBaseUrl: string;
+    /** Shared HMAC secret for re-signing the caller's JWT. */
+    stacknetJwtSecret: string;
+    /** Caller's StackAuth JWT (user identity). */
+    jwt: string;
+}
+/** Admin-only: mint a new preview code. Returns the new code row. */
+declare function mintPreviewCode(cfg: PreviewCodesProxyConfig, options: MintPreviewCodeOptions): Promise<{
+    minted: boolean;
+    code: PreviewCode;
+} | {
+    error: string;
+    status: number;
+}>;
+/** Admin-only: list every preview code in the system. */
+declare function listPreviewCodes(cfg: PreviewCodesProxyConfig): Promise<PreviewCode[] | {
+    error: string;
+    status: number;
+}>;
+/** Public: read a code's balance + status. Used by auth middleware. */
+declare function getPreviewCode(stacknetBaseUrl: string, code: string): Promise<PreviewCode | null>;
+/** Admin-only: revoke a preview code. */
+declare function revokePreviewCode(cfg: PreviewCodesProxyConfig, code: string): Promise<{
+    revoked: boolean;
+    code: PreviewCode;
+} | {
+    error: string;
+    status: number;
+}>;
+/** Internal: debit tokens from a preview code. Called by the metering
+ *  layer after inference completes. */
+declare function redeemPreviewCode(stacknetBaseUrl: string, code: string, tokens: number): Promise<{
+    redeemed: boolean;
+    code: string;
+    tokensUsed: number;
+    tokensRemaining: number;
+} | {
+    error: string;
+    status: number;
+}>;
+/** Allowlist of admin global ids that can mint / revoke preview
+ *  codes. Mirrors PREVIEW_CODE_ADMIN_GLOBAL_IDS in the Rust state
+ *  machine — must stay in sync. Admin-console UI and API route guards
+ *  should call `isPreviewCodeAdmin(currentUser.userId)` instead of
+ *  comparing against a single constant so every entry is accepted. */
+declare const PREVIEW_CODE_ADMIN_GLOBAL_IDS: readonly string[];
+/** Returns true if the given global id is in the preview-code admin
+ *  allowlist. */
+declare function isPreviewCodeAdmin(globalId: string | null | undefined): boolean;
+/** Back-compat alias for callers that only need a single canonical
+ *  admin id for display/logging. Don't use for gating — use
+ *  `isPreviewCodeAdmin()` to accept every entry in the allowlist. */
+declare const PREVIEW_CODE_ADMIN_GLOBAL_ID: string;
+
+export { type AuthCallbackOptions, type BillingProxyConfig, type CSRFConfig, type GoogleOneTapHandlerConfig, type IPExtractorConfig, type MintPreviewCodeOptions, type OAuthHandlerConfig, type OTPHandlerConfig, PREVIEW_CODE_ADMIN_GLOBAL_ID, PREVIEW_CODE_ADMIN_GLOBAL_IDS, type PreviewCode, type PreviewCodeHandlerOptions, type PreviewCodesProxyConfig, type RateLimiter, type ReplayStore, type ServerConfig, type ServerSession, buildStackNetHeaders, createAuthCallback, createBillingProxy, createCSRFProtection, createGoogleOneTapHandler, createInMemoryRateLimiter, createInMemoryReplayStore, createLogoutHandler, createOAuthHandlers, createOTPHandler, createPreviewCodeHandler, createSessionHandler, createWebhookHandler, decodeJWTPayload, extractIP, extractJwt, generateToken, getPreviewCode, isPreviewCodeAdmin, listPreviewCodes, maybeRefreshJWT, mintPreviewCode, nextSecurityHeaders, redeemPreviewCode, resignForStackNet, revokePreviewCode, securityHeaders, signJWT, verifyJWT, verifyJWTSignature, withSecurityHeaders };

package/dist/server/index.d.ts

@@ -0,0 +1,499 @@
+type Web3Chain = 'ethereum' | 'solana' | 'polygon' | 'arbitrum' | 'base';
+/**
+ * Client-safe session metadata. Does NOT contain the JWT.
+ * Use ServerSession (from @stacknet/userutils/server) for server-side code that needs the JWT.
+ */
+interface Session {
+    id: string;
+    app_identity_id: string;
+    global_identity_commitment: string;
+    expires_at: number;
+    created_at: number;
+    stack_id?: string;
+    signed_by: string[];
+    user_id?: string;
+    address?: string;
+    chain?: Web3Chain;
+    auth_method?: string;
+}
+
+/**
+ * Server-only session type that includes the JWT.
+ * NEVER export this from the client bundle.
+ */
+interface ServerSession extends Session {
+    jwt: string;
+}
+
+/** Decode JWT payload without verification (server-side helper) */
+declare function decodeJWTPayload(jwt: string): Record<string, any> | null;
+/** Sign a JWT with HMAC-SHA256 */
+declare function signJWT(payload: Record<string, any>, secret: string): string;
+/** Verify a JWT signature with HMAC-SHA256 (constant-time comparison) */
+declare function verifyJWTSignature(jwt: string, secret: string): boolean;
+/** Verify JWT and return payload if valid (checks signature + expiry) */
+declare function verifyJWT(jwt: string, secret: string): Record<string, any> | null;
+/**
+ * Check if JWT needs refresh and return a new one if so.
+ * Returns null if no refresh needed or JWT is invalid.
+ */
+declare function maybeRefreshJWT(jwt: string, secret: string, expirySeconds?: number, refreshWindowSeconds?: number): string | null;
+/** Generate a cryptographically secure random token */
+declare function generateToken(bytes?: number): string;
+/** Options controlling how the real client IP is extracted from a Request.
+ *
+ *  The previous implementation trusted `X-Forwarded-For[0]` unconditionally,
+ *  which lets any direct caller pin arbitrary values and bypass per-IP rate
+ *  limits. The correct read depends on how many reverse proxies sit between
+ *  the app and the real client: with N trusted hops, the real client IP is
+ *  at position `(length - N)` in the XFF list, because each trusted hop
+ *  appends its peer IP and the attacker-controlled prefix is pushed left. */
+interface IPExtractorConfig {
+    /** Number of trusted reverse-proxy hops between this app and the real client.
+     *  - `0`: do NOT trust X-Forwarded-For (app is directly internet-exposed).
+     *  - `1` (default): one trusted proxy (e.g. single LB, Vercel edge, Nginx).
+     *  - `N`: N trusted hops; the real client IP is `XFF[length - N]`.
+     *  If XFF has fewer entries than expected, the chain is misconfigured or
+     *  spoofed and the extractor falls through to the next source. */
+    trustedProxyCount?: number;
+    /** Trust the `X-Real-IP` header. Only enable if your proxy sets it AND
+     *  strips any inbound `X-Real-IP` from clients. Default: `false`. */
+    trustRealIpHeader?: boolean;
+    /** Override entirely — return the real client IP from a request however
+     *  you know best (e.g. a platform-specific header like `cf-connecting-ip`
+     *  or `x-vercel-forwarded-for`). If this returns a non-empty string it
+     *  wins; if it returns null/empty the other strategies run. */
+    customExtractor?: (request: Request) => string | null | undefined;
+}
+/** Extract the real client IP address from a request.
+ *
+ *  Default behavior (`trustedProxyCount: 1`) is safe for the common case of
+ *  one trusted reverse proxy. Consumers with no proxy must pass `0`, and
+ *  consumers behind multiple proxies must pass the exact hop count. */
+declare function extractIP(request: Request, config?: IPExtractorConfig): string;
+
+/** Server-side configuration for handler factories */
+interface ServerConfig {
+    /** HMAC-SHA256 secret for signing JWTs */
+    authSecret: string;
+    /** StackNet backend URL (always https://stacknet.magma-rpc.com) */
+    stacknetUrl: string;
+    /** StackNet stack identifier */
+    stackId: string;
+    /** JWT secret for re-signing to StackNet (defaults to authSecret) */
+    stacknetJwtSecret?: string;
+    /** Cookie domain for subdomain sharing (e.g. '.geoff.ai') */
+    cookieDomain?: string;
+    /** Use Secure flag on cookies (default: true) */
+    secureCookies?: boolean;
+    /** Session max age in seconds (default: 604800 = 7 days) */
+    sessionMaxAge?: number;
+    /** JWT expiry in seconds (default: 900 = 15 minutes) */
+    jwtExpiry?: number;
+    /**
+     * Google OAuth client ID (single). Used by createGoogleOneTapHandler to
+     * validate the `aud` claim on incoming Google ID tokens. Required for
+     * Google One Tap — without it, an ID token issued to any other Google
+     * application could be replayed against this endpoint.
+     */
+    googleClientId?: string;
+    /**
+     * Google OAuth client IDs (multiple). Use when the stack accepts tokens
+     * from more than one Google client (e.g. web + native).
+     */
+    googleClientIds?: string[];
+    /**
+     * How the handlers should derive the real client IP for rate-limit keys.
+     * Defaults to `{ trustedProxyCount: 1 }`. Set `trustedProxyCount: 0` if
+     * the app is exposed directly (no proxy) — otherwise any caller can pin
+     * their X-Forwarded-For and bypass rate limiting.
+     */
+    ipConfig?: IPExtractorConfig;
+}
+
+/** Rate limiter interface — implement with Redis, Upstash, or use the in-memory default */
+interface RateLimiter {
+    check(key: string): Promise<{
+        allowed: boolean;
+        remaining: number;
+        retryAfter?: number;
+    }>;
+}
+/** Replay store interface — for preventing JWT re-sign replay attacks */
+interface ReplayStore {
+    has(key: string): Promise<boolean>;
+    set(key: string, ttlSeconds: number): Promise<void>;
+}
+/**
+ * In-memory rate limiter with sliding window.
+ *
+ * Safe default for single-process deployments. For multi-process or
+ * distributed environments, provide a Redis-backed RateLimiter instead.
+ */
+declare function createInMemoryRateLimiter(opts: {
+    maxRequests: number;
+    windowMs: number;
+}): RateLimiter;
+/** In-memory replay store (single-process, entries auto-expire) */
+declare function createInMemoryReplayStore(): ReplayStore;
+
+interface AuthCallbackOptions {
+    rateLimiter?: RateLimiter;
+}
+/**
+ * Factory: POST handler for auth callback (login completion).
+ *
+ * Accepts wallet signature verification or OTP results from client,
+ * validates with StackNet, sets HttpOnly JWT cookie + public session cookie + CSRF cookie.
+ */
+declare function createAuthCallback(config: ServerConfig, opts?: AuthCallbackOptions): (request: Request) => Promise<Response>;
+
+/**
+ * Factory: POST handler for logout.
+ * Revokes session with StackNet and clears all auth cookies.
+ */
+declare function createLogoutHandler(config: Pick<ServerConfig, 'stacknetUrl' | 'secureCookies' | 'cookieDomain'> & {
+    /**
+     * HMAC secret used to verify the JWT signature before extracting the
+     * sessionId for upstream revocation. STRONGLY RECOMMENDED.
+     *
+     * Without this, the handler skips upstream revocation entirely and only
+     * clears cookies — because trusting an unverified JWT for the sessionId
+     * would let an attacker plant a forged cookie and trigger DELETE on
+     * another user's session.
+     */
+    authSecret?: string;
+}): (request: Request) => Promise<Response>;
+
+/**
+ * Factory: GET handler for session validation.
+ * Reads HttpOnly JWT cookie, validates, returns public session info.
+ * Transparently refreshes JWT if close to expiry.
+ */
+declare function createSessionHandler(config: Pick<ServerConfig, 'authSecret' | 'jwtExpiry' | 'secureCookies' | 'cookieDomain' | 'sessionMaxAge'>): (request: Request) => Promise<Response>;
+
+interface OTPHandlerConfig extends Pick<ServerConfig, 'authSecret' | 'secureCookies' | 'cookieDomain' | 'sessionMaxAge' | 'jwtExpiry'> {
+    /** The OTP secret to validate against */
+    otpSecret: string;
+    /** Rate limiter (default: 5 attempts per 5 min per IP) */
+    rateLimiter?: RateLimiter;
+    /** How to extract the real client IP for rate-limit keys. Defaults to
+     *  `{ trustedProxyCount: 1 }`. Set `trustedProxyCount: 0` if the handler
+     *  is exposed directly (no proxy in front). */
+    ipConfig?: IPExtractorConfig;
+}
+/**
+ * Factory: POST handler for OTP verification.
+ * Validates OTP code, creates session JWT, sets HttpOnly cookie.
+ */
+declare function createOTPHandler(config: OTPHandlerConfig): (request: Request) => Promise<Response>;
+
+interface OAuthHandlerConfig {
+    rateLimiter?: RateLimiter;
+}
+/**
+ * Factory: OAuth flow handlers.
+ *
+ * Returns two handlers:
+ * - GET  /api/auth/oauth/[provider] — Starts OAuth flow, returns redirect URL
+ * - POST /api/auth/oauth/[provider]/callback — Handles OAuth callback, sets cookies
+ */
+declare function createOAuthHandlers(config: ServerConfig, opts?: OAuthHandlerConfig): {
+    startFlow: (request: Request) => Promise<Response>;
+    handleCallback: (request: Request) => Promise<Response>;
+};
+
+interface GoogleOneTapHandlerConfig {
+    rateLimiter?: RateLimiter;
+}
+/**
+ * Factory: POST handler for Google One Tap credential verification.
+ *
+ * Receives the Google JWT credential from the client, verifies it with
+ * Google's tokeninfo endpoint, then creates a StackNet session.
+ */
+declare function createGoogleOneTapHandler(config: ServerConfig, opts?: GoogleOneTapHandlerConfig): (request: Request) => Promise<Response>;
+
+interface PreviewCodeHandlerOptions {
+    rateLimiter?: RateLimiter;
+    /** Maximum session length in seconds (default 3600 = 1h). Preview
+     *  codes are meant for short-lived demo access — keep this
+     *  meaningfully shorter than a normal wallet/OAuth session. */
+    sessionMaxAge?: number;
+}
+/**
+ * Factory: POST handler for preview-code login.
+ *
+ * Flow:
+ *   1. Client POSTs `{code: "692232"}` to this route.
+ *   2. Handler validates the code against
+ *      `${config.stacknetUrl}/v1/preview-codes/:code` (public read —
+ *      the 6-digit code is itself the bearer credential).
+ *   3. Rejects on not-found / revoked / expired / exhausted.
+ *   4. Mints a local JWT (signed with `config.authSecret`) with
+ *      `sub = global_id = "preview_<code>"` and `auth_method =
+ *      "preview_code"`. Sets it as the `stackauth_jwt` HttpOnly
+ *      cookie so `useSession` recognizes the user as authenticated.
+ *   5. Also sets the public `stackauth_session` cookie + CSRF cookie
+ *      to match the normal wallet / OAuth callback shape.
+ *
+ * The preview-code bearer (`pc_<code>`) is expected to already be in
+ * `localStorage['stacknet-api-key']` — the widget sets that
+ * client-side after a successful POST here. Together, the cookie
+ * drives same-origin `useSession` / server-rendered pages, and the
+ * bearer drives direct stacknet API calls from the browser.
+ *
+ * Security:
+ *   - Rate-limited per IP (10 attempts / minute by default).
+ *   - Format guard: only 6-digit numeric codes reach the upstream
+ *     validator so nothing weird hits stacknet.
+ *   - No upstream JWT is trusted — the stacknet response is a
+ *     read-only row and the session JWT is freshly signed locally
+ *     with the app's own `authSecret`.
+ */
+declare function createPreviewCodeHandler(config: ServerConfig, opts?: PreviewCodeHandlerOptions): (request: Request) => Promise<Response>;
+
+interface BillingProxyConfig extends Pick<ServerConfig, 'authSecret' | 'stacknetUrl' | 'stackId' | 'stacknetJwtSecret' | 'secureCookies' | 'cookieDomain' | 'sessionMaxAge' | 'jwtExpiry'> {
+    /** Rate limiter for mutations (default: 20/min per user) */
+    rateLimiter?: RateLimiter;
+    /**
+     * Canonical absolute origin (e.g. "https://app.example.com") used when
+     * constructing Stripe success/cancel URLs. STRONGLY RECOMMENDED.
+     *
+     * Without this, the origin is derived from the request URL — which is
+     * populated from the `Host` header. If the app is deployed behind a
+     * proxy that does not validate / rewrite `Host`, an attacker can send
+     * `Host: evil.example` and the post-checkout redirect will point there.
+     * Stripe's dashboard allowlist catches most cases, but we should not
+     * depend on that alone.
+     *
+     * Must be a full http(s) origin with no path. Factory throws on
+     * malformed input so misconfigurations surface at boot, not at runtime.
+     */
+    canonicalOrigin?: string;
+}
+type Handler = (request: Request) => Promise<Response>;
+/**
+ * Factory: creates all billing route handlers that proxy to StackNet.
+ *
+ * All POST handlers validate CSRF tokens. All handlers validate the JWT cookie
+ * and transparently refresh if close to expiry.
+ */
+declare function createBillingProxy(config: BillingProxyConfig): {
+    plans: {
+        GET: Handler;
+    };
+    subscription: {
+        GET: Handler;
+    };
+    subscribe: {
+        POST: Handler;
+    };
+    cancel: {
+        POST: Handler;
+    };
+    usage: {
+        GET: Handler;
+    };
+    history: {
+        GET: Handler;
+    };
+    prepaid: {
+        POST: Handler;
+    };
+    verifyPrepaid: {
+        POST: Handler;
+    };
+    verifySession: {
+        POST: Handler;
+    };
+    subscribeSol: {
+        POST: Handler;
+    };
+    prepaidSol: {
+        POST: Handler;
+    };
+    topup: {
+        POST: Handler;
+    };
+};
+
+/**
+ * Factory: POST handler for Stripe webhooks.
+ * Forwards raw body + stripe-signature to StackNet for verification and processing.
+ */
+declare function createWebhookHandler(config: Pick<ServerConfig, 'stacknetUrl' | 'stackId'>): (request: Request) => Promise<Response>;
+
+interface CSRFConfig {
+    /** Cookie name (default: '__csrf') */
+    cookieName?: string;
+    /** Header name (default: 'x-csrf-token') */
+    headerName?: string;
+    /** Token length in bytes (default: 32) */
+    tokenLength?: number;
+    /** Use Secure flag on cookie (default: true) */
+    secure?: boolean;
+}
+/**
+ * Create CSRF protection using the double-submit cookie pattern.
+ *
+ * 1. Server sets a non-HttpOnly cookie with a random token
+ * 2. Client reads the cookie and sends the token in a header on mutations
+ * 3. Server validates cookie === header (attacker can't read cookie cross-origin)
+ */
+declare function createCSRFProtection(config?: CSRFConfig): {
+    /**
+     * Generate a CSRF token and add Set-Cookie header to a response.
+     * Call this on auth callback (login) to establish the CSRF cookie.
+     */
+    generateToken(headers: Headers): string;
+    /**
+     * Validate a request's CSRF token (cookie vs header).
+     * Returns true if valid, false if not.
+     */
+    validateRequest(request: Request): {
+        valid: boolean;
+        error?: string;
+    };
+    /** Cookie name for client-side reading */
+    cookieName: string;
+    /** Header name for client-side sending */
+    headerName: string;
+};
+
+/** Standard security response headers */
+declare function securityHeaders(): Record<string, string>;
+/**
+ * Wrap a request handler to add security headers to the response.
+ */
+declare function withSecurityHeaders(handler: (request: Request) => Promise<Response> | Response): (request: Request) => Promise<Response>;
+/**
+ * Generate security headers config for Next.js next.config.ts.
+ *
+ * Usage in next.config.ts:
+ * ```ts
+ * import { nextSecurityHeaders } from '@stacknet/userutils/server';
+ * export default { headers: () => [{ source: '/(.*)', headers: nextSecurityHeaders() }] };
+ * ```
+ */
+declare function nextSecurityHeaders(): Array<{
+    key: string;
+    value: string;
+}>;
+
+/**
+ * Re-sign a JWT using StackNet's HMAC-SHA256 scheme.
+ *
+ * Geoff apps sign JWTs with AUTH_SECRET. StackNet validates with JWT_SECRET.
+ * This function re-signs using the StackNet secret so the backend resolves
+ * the correct per-user identity.
+ */
+declare function resignForStackNet(jwt: string, stacknetJwtSecret: string): string | null;
+/**
+ * Build headers for proxying a user-scoped request to StackNet.
+ * Re-signs the JWT so StackNet recognises the user's identity.
+ *
+ * Refuses to interpolate any value that doesn't match the compact JWT
+ * format (header.body.signature, base64url segments only) to prevent
+ * header injection.
+ */
+declare function buildStackNetHeaders(jwt: string, stacknetJwtSecret: string): Record<string, string>;
+/**
+ * Extract JWT from a request's cookies or Authorization header.
+ */
+declare function extractJwt(request: Request): string | null;
+
+/**
+ * Server-side proxy helpers for StackNet preview codes.
+ *
+ * Preview codes are admin-minted 6-digit access credentials with a
+ * per-code token budget. Only the pinned admin global id (enforced
+ * by StackNet's state machine) can mint / list / revoke codes.
+ *
+ * These helpers wrap `fetch` against the StackNet HTTP layer with
+ * re-signed JWT cookies (same pattern as `buildStackNetHeaders`).
+ * Admin-console API routes are expected to call them; the raw
+ * endpoints are NOT exposed in the client bundle.
+ */
+interface PreviewCode {
+    code: string;
+    createdBy: string;
+    tokenBudget: number;
+    tokensUsed: number;
+    tokensRemaining: number;
+    createdAt: number;
+    expiresAt: number | null;
+    revoked: boolean;
+    /** Optional human-readable label (e.g. "Tester: Alice"). Absent on
+     *  codes minted before the name field shipped. */
+    name?: string | null;
+}
+interface MintPreviewCodeOptions {
+    /** Token budget for the new code. Must be > 0. */
+    tokenBudget: number;
+    /** Optional explicit 6-digit code string. Server generates one
+     *  if omitted. */
+    code?: string;
+    /** Optional Unix-ms expiry. */
+    expiresAt?: number;
+    /** Optional human-readable label for the code. Shown in the admin
+     *  list so the operator can tell codes apart. */
+    name?: string;
+}
+interface PreviewCodesProxyConfig {
+    /** StackNet base URL (no trailing slash). */
+    stacknetBaseUrl: string;
+    /** Shared HMAC secret for re-signing the caller's JWT. */
+    stacknetJwtSecret: string;
+    /** Caller's StackAuth JWT (user identity). */
+    jwt: string;
+}
+/** Admin-only: mint a new preview code. Returns the new code row. */
+declare function mintPreviewCode(cfg: PreviewCodesProxyConfig, options: MintPreviewCodeOptions): Promise<{
+    minted: boolean;
+    code: PreviewCode;
+} | {
+    error: string;
+    status: number;
+}>;
+/** Admin-only: list every preview code in the system. */
+declare function listPreviewCodes(cfg: PreviewCodesProxyConfig): Promise<PreviewCode[] | {
+    error: string;
+    status: number;
+}>;
+/** Public: read a code's balance + status. Used by auth middleware. */
+declare function getPreviewCode(stacknetBaseUrl: string, code: string): Promise<PreviewCode | null>;
+/** Admin-only: revoke a preview code. */
+declare function revokePreviewCode(cfg: PreviewCodesProxyConfig, code: string): Promise<{
+    revoked: boolean;
+    code: PreviewCode;
+} | {
+    error: string;
+    status: number;
+}>;
+/** Internal: debit tokens from a preview code. Called by the metering
+ *  layer after inference completes. */
+declare function redeemPreviewCode(stacknetBaseUrl: string, code: string, tokens: number): Promise<{
+    redeemed: boolean;
+    code: string;
+    tokensUsed: number;
+    tokensRemaining: number;
+} | {
+    error: string;
+    status: number;
+}>;
+/** Allowlist of admin global ids that can mint / revoke preview
+ *  codes. Mirrors PREVIEW_CODE_ADMIN_GLOBAL_IDS in the Rust state
+ *  machine — must stay in sync. Admin-console UI and API route guards
+ *  should call `isPreviewCodeAdmin(currentUser.userId)` instead of
+ *  comparing against a single constant so every entry is accepted. */
+declare const PREVIEW_CODE_ADMIN_GLOBAL_IDS: readonly string[];
+/** Returns true if the given global id is in the preview-code admin
+ *  allowlist. */
+declare function isPreviewCodeAdmin(globalId: string | null | undefined): boolean;
+/** Back-compat alias for callers that only need a single canonical
+ *  admin id for display/logging. Don't use for gating — use
+ *  `isPreviewCodeAdmin()` to accept every entry in the allowlist. */
+declare const PREVIEW_CODE_ADMIN_GLOBAL_ID: string;
+
+export { type AuthCallbackOptions, type BillingProxyConfig, type CSRFConfig, type GoogleOneTapHandlerConfig, type IPExtractorConfig, type MintPreviewCodeOptions, type OAuthHandlerConfig, type OTPHandlerConfig, PREVIEW_CODE_ADMIN_GLOBAL_ID, PREVIEW_CODE_ADMIN_GLOBAL_IDS, type PreviewCode, type PreviewCodeHandlerOptions, type PreviewCodesProxyConfig, type RateLimiter, type ReplayStore, type ServerConfig, type ServerSession, buildStackNetHeaders, createAuthCallback, createBillingProxy, createCSRFProtection, createGoogleOneTapHandler, createInMemoryRateLimiter, createInMemoryReplayStore, createLogoutHandler, createOAuthHandlers, createOTPHandler, createPreviewCodeHandler, createSessionHandler, createWebhookHandler, decodeJWTPayload, extractIP, extractJwt, generateToken, getPreviewCode, isPreviewCodeAdmin, listPreviewCodes, maybeRefreshJWT, mintPreviewCode, nextSecurityHeaders, redeemPreviewCode, resignForStackNet, revokePreviewCode, securityHeaders, signJWT, verifyJWT, verifyJWTSignature, withSecurityHeaders };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stacknet/userutils",
-  "version": "0.6.4",
+  "version": "0.6.5",
   "description": "Reusable auth, billing, and security utilities for StackNet stacks and applications",
   "type": "module",
   "main": "./dist/index.cjs",