@stacknet/userutils 0.6.0 → 0.6.2

package/dist/server/index.d.cts

@@ -1,359 +0,0 @@
-import { S as Session } from '../auth-c1d7Eji2.cjs';
-import { e as ServerConfig, I as IPExtractorConfig } from '../config-CLzVWDrU.cjs';
-export { f as decodeJWTPayload, g as extractIP, h as generateToken, m as maybeRefreshJWT, s as signJWT, v as verifyJWT, i as verifyJWTSignature } from '../config-CLzVWDrU.cjs';
-
-/**
- * Server-only session type that includes the JWT.
- * NEVER export this from the client bundle.
- */
-interface ServerSession extends Session {
-    jwt: string;
-}
-
-/** 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 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, IPExtractorConfig, type MintPreviewCodeOptions, type OAuthHandlerConfig, type OTPHandlerConfig, PREVIEW_CODE_ADMIN_GLOBAL_ID, PREVIEW_CODE_ADMIN_GLOBAL_IDS, type PreviewCode, type PreviewCodesProxyConfig, type RateLimiter, type ReplayStore, ServerConfig, type ServerSession, buildStackNetHeaders, createAuthCallback, createBillingProxy, createCSRFProtection, createGoogleOneTapHandler, createInMemoryRateLimiter, createInMemoryReplayStore, createLogoutHandler, createOAuthHandlers, createOTPHandler, createSessionHandler, createWebhookHandler, extractJwt, getPreviewCode, isPreviewCodeAdmin, listPreviewCodes, mintPreviewCode, nextSecurityHeaders, redeemPreviewCode, resignForStackNet, revokePreviewCode, securityHeaders, withSecurityHeaders };