@scalemule/nextjs 0.0.39 → 0.0.41

package/dist/server/index.d.mts

@@ -1,7 +1,8 @@
-import { S as ServerConfig } from '../webhook-handler-Cz9jtet2.mjs';
-export { a as ScaleMuleServer, V as VideoFailedEvent, b as VideoReadyEvent, c as VideoTranscodedEvent, d as VideoUploadedEvent, W as WebhookEvent, e as WebhookRoutesConfig, f as createServerClient, g as createWebhookHandler, h as createWebhookRoutes, p as parseWebhookEvent, r as registerVideoWebhook, i as resolveGatewayUrl, v as verifyWebhookSignature } from '../webhook-handler-Cz9jtet2.mjs';
-import { p as ClientContext, A as ApiError } from '../index-BoENfro3.mjs';
+import { S as ServerConfig } from '../webhook-handler-BqzCYRNJ.mjs';
+export { a as ScaleMuleServer, V as VideoFailedEvent, b as VideoReadyEvent, c as VideoTranscodedEvent, d as VideoUploadedEvent, W as WebhookEvent, e as WebhookRoutesConfig, f as createServerClient, g as createWebhookHandler, h as createWebhookRoutes, p as parseWebhookEvent, r as registerVideoWebhook, i as resolveGatewayUrl, v as verifyWebhookSignature } from '../webhook-handler-BqzCYRNJ.mjs';
+import { p as ClientContext, A as ApiError } from '../index-BIIUrnPr.mjs';
 import { NextRequest, NextResponse } from 'next/server';
+import '@scalemule/money';
 
 /**
  * Client Context Extraction Utilities (Next.js)
@@ -110,6 +111,12 @@ declare function buildFlagContext(clientContext: Pick<ClientContext, 'ip'> | und
  */
 declare const SESSION_COOKIE_NAME = "sm_session";
 declare const USER_ID_COOKIE_NAME = "sm_user_id";
+/**
+ * Known accounts cookie — stores display metadata (email, name, avatar) for
+ * accounts that have logged in on this device. NOT httpOnly so client JS can
+ * read it to render the account switcher UI. Contains NO tokens or secrets.
+ */
+declare const KNOWN_ACCOUNTS_COOKIE_NAME = "sm_known_accounts";
 interface SessionCookieOptions {
     /** Cookie max age in seconds (default: 7 days) */
     maxAge?: number;
@@ -181,6 +188,51 @@ declare function getSession(): Promise<SessionData | null>;
  * Use this when you need to read cookies from a Request directly.
  */
 declare function getSessionFromRequest(request: Request): SessionData | null;
+/**
+ * Known account entry stored in cookie.
+ * Contains display metadata ONLY — no tokens, no secrets.
+ */
+interface KnownAccountEntry {
+    userId: string;
+    email?: string;
+    fullName?: string;
+    avatarUrl?: string;
+    provider?: string;
+    lastActiveAt: string;
+    displayLabel?: string;
+    colorIndex?: number;
+}
+type AccountSwitcherPrivacy = 'full' | 'masked' | 'minimal';
+/**
+ * Add an account to the known accounts cookie.
+ * Called after successful login. The cookie is NOT httpOnly so client JS
+ * can read it to render the account switcher UI.
+ *
+ * Appends Set-Cookie headers to an existing Headers object.
+ */
+declare function appendKnownAccountCookie(headers: Headers, account: KnownAccountEntry, existingCookie: string | null, options?: SessionCookieOptions, privacy?: AccountSwitcherPrivacy): void;
+/**
+ * Remove a specific account from the known accounts cookie.
+ */
+declare function removeKnownAccountFromCookie(headers: Headers, userId: string, existingCookie: string | null, options?: SessionCookieOptions): void;
+/**
+ * Clear the known accounts cookie entirely.
+ */
+declare function clearKnownAccountsCookie(headers: Headers, options?: SessionCookieOptions): void;
+/**
+ * Read known accounts from a Request's cookies.
+ */
+declare function getKnownAccountsFromRequest(request: Request): KnownAccountEntry[];
+/**
+ * Read the raw known accounts cookie value from a Request.
+ */
+declare function getKnownAccountsCookieRaw(request: Request): string | null;
+/**
+ * Normalize all entries in the known accounts cookie to the given privacy level.
+ * Returns a Set-Cookie header string if any entries changed, or null if nothing changed.
+ * Used on /me requests to migrate legacy full-PII cookies to the configured privacy level.
+ */
+declare function normalizeKnownAccountsCookie(request: Request, privacy: AccountSwitcherPrivacy | undefined, options?: SessionCookieOptions): string | null;
 /**
  * Require authentication - throws Response if not authenticated
  *
@@ -220,6 +272,19 @@ interface AuthRoutesConfig {
     cookies?: SessionCookieOptions;
     /** Enable CSRF validation on state-changing requests (POST/DELETE/PATCH) */
     csrf?: boolean;
+    /**
+     * Enable the account switcher — remembers which accounts have logged in on
+     * this device (metadata only, no tokens). Switching requires re-authentication.
+     * Adds routes: switch-account, forget-account, forget-all-accounts, known-accounts.
+     */
+    enableAccountSwitcher?: boolean;
+    /**
+     * Privacy level for account switcher display metadata.
+     * - 'full': Store email, name, avatar as-is (default)
+     * - 'masked': Mask email, truncate name to initial
+     * - 'minimal': No PII — just a colored "Account" label
+     */
+    accountSwitcherPrivacy?: 'full' | 'masked' | 'minimal';
     /** Callbacks */
     onLogin?: (user: {
         id: string;
@@ -1011,4 +1076,187 @@ declare function invalidateBundleCache(key?: string): void;
  */
 declare function prefetchBundles(keys: string[]): Promise<void>;
 
-export { type AnalyticsRoutesConfig, type AnalyticsTrackingGateConfig, type AuthMiddlewareConfig, type AuthRoutesConfig, CSRF_COOKIE_NAME, CSRF_HEADER_NAME, type HandlerContext, type HandlerOptions, type MySqlBundle, type NotificationRoutesConfig, OAUTH_STATE_COOKIE_NAME, type OAuthBundle, type PostgresBundle, type PushRoutesConfig, type RedisBundle, type S3Bundle, SESSION_COOKIE_NAME, ScaleMuleError, ServerConfig, type SessionCookieOptions, type SessionData, type SmtpBundle, USER_ID_COOKIE_NAME, apiHandler, buildClientContextHeaders, buildFlagContext, clearOAuthState, clearSession, configureBundles, configureSecrets, createAnalyticsRoutes, createAuthMiddleware, createAuthRoutes, createNotificationRoutes, createPushRoutes, errorCodeToStatus, extractClientContext, extractClientContextFromReq, generateCSRFToken, getAppSecret, getAppSecretOrDefault, getBootstrapFlags, getBundle, getCSRFToken, getMySqlBundle, getOAuthBundle, getPostgresBundle, getRedisBundle, getS3Bundle, getSession, getSessionFromRequest, getSmtpBundle, invalidateBundleCache, invalidateSecretCache, prefetchBundles, prefetchSecrets, requireAppSecret, requireBundle, requireSession, setOAuthState, unwrap, validateCSRFToken, validateCSRFTokenAsync, validateOAuthState, validateOAuthStateAsync, withAuth, withCSRFProtection, withCSRFToken, withSession };
+/**
+ * Safe-redirect validation for authentication callback URLs.
+ *
+ * Prevents open-redirect attacks on `returnTo` / `callbackUrl` / `next`
+ * params after login / registration / password-reset flows. An attacker
+ * who can inject a `?returnTo=https://evil.example` into your login
+ * form would otherwise redirect the freshly-authenticated user away
+ * from your origin — a classic phishing + credential-harvesting setup.
+ *
+ * Safe by default — unknown input returns the configured default
+ * path. Hosts opt in to external origins explicitly via
+ * `allowedOrigins`.
+ *
+ * Framework-agnostic: no imports from `next/*`. Safe in any
+ * Edge / Node / middleware runtime.
+ */
+interface SafeRedirectOptions {
+    /**
+     * Origins (schema + host + optional port) the redirect is allowed
+     * to land on. Default `[]` — only same-origin relative paths are
+     * allowed. Items are compared case-insensitively after normalizing
+     * the scheme and host.
+     *
+     * Good practice: list only origins that your organization controls
+     * and that are reachable over HTTPS.
+     *
+     * @example
+     * ['https://app.example.com', 'https://admin.example.com']
+     */
+    allowedOrigins?: string[];
+    /**
+     * Value returned when the input is missing, invalid, or points
+     * outside the allowlist. Default `'/'`.
+     */
+    defaultPath?: string;
+    /**
+     * Strip the scheme + host from same-origin absolute URLs and
+     * return only the path + query + fragment. Default `true` — keeps
+     * redirect targets as short relative URLs that route through
+     * client-side routing cleanly.
+     */
+    stripSameOriginHost?: boolean;
+}
+/**
+ * Returns a safe-to-use redirect path, falling back to
+ * `opts.defaultPath` (default `'/'`) when the input fails validation.
+ *
+ * Accepts:
+ *   - empty / nullish → default
+ *   - relative paths like `/foo/bar?x=1#frag` (leading `/` required)
+ *   - absolute URLs whose origin is in `allowedOrigins`
+ *
+ * Rejects everything else, including:
+ *   - schema-relative URLs (`//evil.example`)
+ *   - backslash-prefixed paths
+ *   - `javascript:`, `data:`, `mailto:`, `vbscript:` etc.
+ *   - bare hostnames (`example.com/path`)
+ *   - malformed URLs
+ */
+declare function validateSafeRedirect(input: string | null | undefined, opts?: SafeRedirectOptions): string;
+/**
+ * Boolean predicate form. Returns `true` when `input` would pass
+ * `validateSafeRedirect` with the same options.
+ */
+declare function isSafeRedirect(input: string | null | undefined, opts?: SafeRedirectOptions): boolean;
+
+/**
+ * Security-headers helper for Next.js hosts.
+ *
+ * Returns a shape that drops directly into the `headers()` entry in
+ * `next.config.ts` (or the `headers` field of a Route Handler
+ * `NextResponse`). Reasonable defaults for the top-of-OWASP headers
+ * — HSTS, X-Frame-Options, X-Content-Type-Options, Referrer-Policy,
+ * X-XSS-Protection, Permissions-Policy — with knobs for the fields
+ * that typically differ by app (HSTS duration, frame ancestors,
+ * camera/microphone policies).
+ *
+ * Framework-agnostic: no imports from `next/*` so the function works
+ * in Edge / Node / middleware and is trivially unit-testable.
+ */
+interface SecurityHeaderEntry {
+    key: string;
+    value: string;
+}
+interface BuildSecurityHeadersOptions {
+    /**
+     * HSTS max-age in seconds. Default `31536000` (1 year) — the value
+     * required for inclusion on the HSTS preload list. Set to `0` (or
+     * pass `includeHsts: false`) to opt out entirely.
+     */
+    hstsMaxAgeSeconds?: number;
+    /** Adds the `includeSubDomains` directive to HSTS. Default `true`. */
+    hstsIncludeSubDomains?: boolean;
+    /**
+     * Adds the `preload` directive to HSTS. Default `false` — only set
+     * to `true` after you've read https://hstspreload.org and are ready
+     * to commit; reversing it requires months of calendar time.
+     */
+    hstsPreload?: boolean;
+    /** Emit the HSTS header at all. Default `true`. */
+    includeHsts?: boolean;
+    /**
+     * Value for `X-Frame-Options`. Default `'DENY'`. Pass `'SAMEORIGIN'`
+     * if your app is framed by its own subdomain. Set to `null` to
+     * suppress (e.g. when you're already using `frame-ancestors` in
+     * CSP). `SAMEORIGIN` accepts no host parameter; use CSP's
+     * `frame-ancestors` for finer-grained framing policy.
+     */
+    frameOptions?: 'DENY' | 'SAMEORIGIN' | null;
+    /**
+     * Value for `Referrer-Policy`. Default `'strict-origin-when-cross-origin'`
+     * — same as Next.js's own default, balances analytics with privacy.
+     */
+    referrerPolicy?: 'no-referrer' | 'no-referrer-when-downgrade' | 'origin' | 'origin-when-cross-origin' | 'same-origin' | 'strict-origin' | 'strict-origin-when-cross-origin' | 'unsafe-url';
+    /**
+     * Permissions-Policy directives. Pass a map of `{ feature: allowlist }`
+     * where the allowlist is either an array of origins (string[]) or
+     * one of the well-known tokens `'self'` / `'*'` / `'()'` (deny).
+     *
+     * Default: camera + microphone allowed for `'self'` only (useful
+     * for the conference track); geolocation + payment denied; every
+     * other common feature left unset (browsers apply their own
+     * conservative defaults).
+     *
+     * Pass `{}` to emit an empty `Permissions-Policy: ` header (rarely
+     * useful). Pass `null` to suppress the header entirely.
+     */
+    permissionsPolicy?: PermissionsPolicyMap | null;
+    /**
+     * Value for `X-Content-Type-Options`. Default `'nosniff'` — do not
+     * override without a specific reason.
+     */
+    contentTypeOptions?: string | null;
+    /**
+     * Legacy `X-XSS-Protection`. Default `'0'` (disables the
+     * deprecated IE/Edge filter which had known bypass issues —
+     * recommended by OWASP + Next.js). Set to `'1; mode=block'` only
+     * if you have a specific compliance reason.
+     */
+    xssProtection?: string | null;
+    /**
+     * Extra headers to merge into the result. Takes precedence over
+     * the computed ones — useful for adding Content-Security-Policy or
+     * Cross-Origin-* headers without forcing a new option for each.
+     */
+    extraHeaders?: SecurityHeaderEntry[];
+}
+type PermissionsPolicyValue = readonly string[] | 'self' | '*' | '()';
+type PermissionsPolicyMap = Readonly<Record<string, PermissionsPolicyValue>>;
+declare const DEFAULT_PERMISSIONS_POLICY: PermissionsPolicyMap;
+/**
+ * Build a reasonable-default set of security response headers in the
+ * exact shape Next.js `headers()` expects.
+ *
+ * @example next.config.ts
+ * ```ts
+ * import { buildSecurityHeaders } from '@scalemule/nextjs/server'
+ *
+ * export default {
+ *   async headers() {
+ *     return [
+ *       { source: '/:path*', headers: buildSecurityHeaders() },
+ *     ]
+ *   },
+ * }
+ * ```
+ *
+ * @example custom overrides
+ * ```ts
+ * buildSecurityHeaders({
+ *   frameOptions: 'SAMEORIGIN',
+ *   permissionsPolicy: {
+ *     camera: ['https://trusted.example.com'],
+ *     microphone: ['https://trusted.example.com'],
+ *   },
+ *   extraHeaders: [
+ *     { key: 'Content-Security-Policy', value: "default-src 'self'" },
+ *   ],
+ * })
+ * ```
+ */
+declare function buildSecurityHeaders(opts?: BuildSecurityHeadersOptions): SecurityHeaderEntry[];
+
+export { type AnalyticsRoutesConfig, type AnalyticsTrackingGateConfig, type AuthMiddlewareConfig, type AuthRoutesConfig, type BuildSecurityHeadersOptions, CSRF_COOKIE_NAME, CSRF_HEADER_NAME, DEFAULT_PERMISSIONS_POLICY, type HandlerContext, type HandlerOptions, KNOWN_ACCOUNTS_COOKIE_NAME, type KnownAccountEntry, type MySqlBundle, type NotificationRoutesConfig, OAUTH_STATE_COOKIE_NAME, type OAuthBundle, type PermissionsPolicyMap, type PermissionsPolicyValue, type PostgresBundle, type PushRoutesConfig, type RedisBundle, type S3Bundle, SESSION_COOKIE_NAME, type SafeRedirectOptions, ScaleMuleError, type SecurityHeaderEntry, ServerConfig, type SessionCookieOptions, type SessionData, type SmtpBundle, USER_ID_COOKIE_NAME, apiHandler, appendKnownAccountCookie, buildClientContextHeaders, buildFlagContext, buildSecurityHeaders, clearKnownAccountsCookie, clearOAuthState, clearSession, configureBundles, configureSecrets, createAnalyticsRoutes, createAuthMiddleware, createAuthRoutes, createNotificationRoutes, createPushRoutes, errorCodeToStatus, extractClientContext, extractClientContextFromReq, generateCSRFToken, getAppSecret, getAppSecretOrDefault, getBootstrapFlags, getBundle, getCSRFToken, getKnownAccountsCookieRaw, getKnownAccountsFromRequest, getMySqlBundle, getOAuthBundle, getPostgresBundle, getRedisBundle, getS3Bundle, getSession, getSessionFromRequest, getSmtpBundle, invalidateBundleCache, invalidateSecretCache, isSafeRedirect, normalizeKnownAccountsCookie, prefetchBundles, prefetchSecrets, removeKnownAccountFromCookie, requireAppSecret, requireBundle, requireSession, setOAuthState, unwrap, validateCSRFToken, validateCSRFTokenAsync, validateOAuthState, validateOAuthStateAsync, validateSafeRedirect, withAuth, withCSRFProtection, withCSRFToken, withSession };

package/dist/server/index.d.ts

@@ -1,7 +1,8 @@
-import { S as ServerConfig } from '../webhook-handler-CjSSCdvI.js';
-export { a as ScaleMuleServer, V as VideoFailedEvent, b as VideoReadyEvent, c as VideoTranscodedEvent, d as VideoUploadedEvent, W as WebhookEvent, e as WebhookRoutesConfig, f as createServerClient, g as createWebhookHandler, h as createWebhookRoutes, p as parseWebhookEvent, r as registerVideoWebhook, i as resolveGatewayUrl, v as verifyWebhookSignature } from '../webhook-handler-CjSSCdvI.js';
-import { p as ClientContext, A as ApiError } from '../index-BoENfro3.js';
+import { S as ServerConfig } from '../webhook-handler-BjFbqZuq.js';
+export { a as ScaleMuleServer, V as VideoFailedEvent, b as VideoReadyEvent, c as VideoTranscodedEvent, d as VideoUploadedEvent, W as WebhookEvent, e as WebhookRoutesConfig, f as createServerClient, g as createWebhookHandler, h as createWebhookRoutes, p as parseWebhookEvent, r as registerVideoWebhook, i as resolveGatewayUrl, v as verifyWebhookSignature } from '../webhook-handler-BjFbqZuq.js';
+import { p as ClientContext, A as ApiError } from '../index-BIIUrnPr.js';
 import { NextRequest, NextResponse } from 'next/server';
+import '@scalemule/money';
 
 /**
  * Client Context Extraction Utilities (Next.js)
@@ -110,6 +111,12 @@ declare function buildFlagContext(clientContext: Pick<ClientContext, 'ip'> | und
  */
 declare const SESSION_COOKIE_NAME = "sm_session";
 declare const USER_ID_COOKIE_NAME = "sm_user_id";
+/**
+ * Known accounts cookie — stores display metadata (email, name, avatar) for
+ * accounts that have logged in on this device. NOT httpOnly so client JS can
+ * read it to render the account switcher UI. Contains NO tokens or secrets.
+ */
+declare const KNOWN_ACCOUNTS_COOKIE_NAME = "sm_known_accounts";
 interface SessionCookieOptions {
     /** Cookie max age in seconds (default: 7 days) */
     maxAge?: number;
@@ -181,6 +188,51 @@ declare function getSession(): Promise<SessionData | null>;
  * Use this when you need to read cookies from a Request directly.
  */
 declare function getSessionFromRequest(request: Request): SessionData | null;
+/**
+ * Known account entry stored in cookie.
+ * Contains display metadata ONLY — no tokens, no secrets.
+ */
+interface KnownAccountEntry {
+    userId: string;
+    email?: string;
+    fullName?: string;
+    avatarUrl?: string;
+    provider?: string;
+    lastActiveAt: string;
+    displayLabel?: string;
+    colorIndex?: number;
+}
+type AccountSwitcherPrivacy = 'full' | 'masked' | 'minimal';
+/**
+ * Add an account to the known accounts cookie.
+ * Called after successful login. The cookie is NOT httpOnly so client JS
+ * can read it to render the account switcher UI.
+ *
+ * Appends Set-Cookie headers to an existing Headers object.
+ */
+declare function appendKnownAccountCookie(headers: Headers, account: KnownAccountEntry, existingCookie: string | null, options?: SessionCookieOptions, privacy?: AccountSwitcherPrivacy): void;
+/**
+ * Remove a specific account from the known accounts cookie.
+ */
+declare function removeKnownAccountFromCookie(headers: Headers, userId: string, existingCookie: string | null, options?: SessionCookieOptions): void;
+/**
+ * Clear the known accounts cookie entirely.
+ */
+declare function clearKnownAccountsCookie(headers: Headers, options?: SessionCookieOptions): void;
+/**
+ * Read known accounts from a Request's cookies.
+ */
+declare function getKnownAccountsFromRequest(request: Request): KnownAccountEntry[];
+/**
+ * Read the raw known accounts cookie value from a Request.
+ */
+declare function getKnownAccountsCookieRaw(request: Request): string | null;
+/**
+ * Normalize all entries in the known accounts cookie to the given privacy level.
+ * Returns a Set-Cookie header string if any entries changed, or null if nothing changed.
+ * Used on /me requests to migrate legacy full-PII cookies to the configured privacy level.
+ */
+declare function normalizeKnownAccountsCookie(request: Request, privacy: AccountSwitcherPrivacy | undefined, options?: SessionCookieOptions): string | null;
 /**
  * Require authentication - throws Response if not authenticated
  *
@@ -220,6 +272,19 @@ interface AuthRoutesConfig {
     cookies?: SessionCookieOptions;
     /** Enable CSRF validation on state-changing requests (POST/DELETE/PATCH) */
     csrf?: boolean;
+    /**
+     * Enable the account switcher — remembers which accounts have logged in on
+     * this device (metadata only, no tokens). Switching requires re-authentication.
+     * Adds routes: switch-account, forget-account, forget-all-accounts, known-accounts.
+     */
+    enableAccountSwitcher?: boolean;
+    /**
+     * Privacy level for account switcher display metadata.
+     * - 'full': Store email, name, avatar as-is (default)
+     * - 'masked': Mask email, truncate name to initial
+     * - 'minimal': No PII — just a colored "Account" label
+     */
+    accountSwitcherPrivacy?: 'full' | 'masked' | 'minimal';
     /** Callbacks */
     onLogin?: (user: {
         id: string;
@@ -1011,4 +1076,187 @@ declare function invalidateBundleCache(key?: string): void;
  */
 declare function prefetchBundles(keys: string[]): Promise<void>;
 
-export { type AnalyticsRoutesConfig, type AnalyticsTrackingGateConfig, type AuthMiddlewareConfig, type AuthRoutesConfig, CSRF_COOKIE_NAME, CSRF_HEADER_NAME, type HandlerContext, type HandlerOptions, type MySqlBundle, type NotificationRoutesConfig, OAUTH_STATE_COOKIE_NAME, type OAuthBundle, type PostgresBundle, type PushRoutesConfig, type RedisBundle, type S3Bundle, SESSION_COOKIE_NAME, ScaleMuleError, ServerConfig, type SessionCookieOptions, type SessionData, type SmtpBundle, USER_ID_COOKIE_NAME, apiHandler, buildClientContextHeaders, buildFlagContext, clearOAuthState, clearSession, configureBundles, configureSecrets, createAnalyticsRoutes, createAuthMiddleware, createAuthRoutes, createNotificationRoutes, createPushRoutes, errorCodeToStatus, extractClientContext, extractClientContextFromReq, generateCSRFToken, getAppSecret, getAppSecretOrDefault, getBootstrapFlags, getBundle, getCSRFToken, getMySqlBundle, getOAuthBundle, getPostgresBundle, getRedisBundle, getS3Bundle, getSession, getSessionFromRequest, getSmtpBundle, invalidateBundleCache, invalidateSecretCache, prefetchBundles, prefetchSecrets, requireAppSecret, requireBundle, requireSession, setOAuthState, unwrap, validateCSRFToken, validateCSRFTokenAsync, validateOAuthState, validateOAuthStateAsync, withAuth, withCSRFProtection, withCSRFToken, withSession };
+/**
+ * Safe-redirect validation for authentication callback URLs.
+ *
+ * Prevents open-redirect attacks on `returnTo` / `callbackUrl` / `next`
+ * params after login / registration / password-reset flows. An attacker
+ * who can inject a `?returnTo=https://evil.example` into your login
+ * form would otherwise redirect the freshly-authenticated user away
+ * from your origin — a classic phishing + credential-harvesting setup.
+ *
+ * Safe by default — unknown input returns the configured default
+ * path. Hosts opt in to external origins explicitly via
+ * `allowedOrigins`.
+ *
+ * Framework-agnostic: no imports from `next/*`. Safe in any
+ * Edge / Node / middleware runtime.
+ */
+interface SafeRedirectOptions {
+    /**
+     * Origins (schema + host + optional port) the redirect is allowed
+     * to land on. Default `[]` — only same-origin relative paths are
+     * allowed. Items are compared case-insensitively after normalizing
+     * the scheme and host.
+     *
+     * Good practice: list only origins that your organization controls
+     * and that are reachable over HTTPS.
+     *
+     * @example
+     * ['https://app.example.com', 'https://admin.example.com']
+     */
+    allowedOrigins?: string[];
+    /**
+     * Value returned when the input is missing, invalid, or points
+     * outside the allowlist. Default `'/'`.
+     */
+    defaultPath?: string;
+    /**
+     * Strip the scheme + host from same-origin absolute URLs and
+     * return only the path + query + fragment. Default `true` — keeps
+     * redirect targets as short relative URLs that route through
+     * client-side routing cleanly.
+     */
+    stripSameOriginHost?: boolean;
+}
+/**
+ * Returns a safe-to-use redirect path, falling back to
+ * `opts.defaultPath` (default `'/'`) when the input fails validation.
+ *
+ * Accepts:
+ *   - empty / nullish → default
+ *   - relative paths like `/foo/bar?x=1#frag` (leading `/` required)
+ *   - absolute URLs whose origin is in `allowedOrigins`
+ *
+ * Rejects everything else, including:
+ *   - schema-relative URLs (`//evil.example`)
+ *   - backslash-prefixed paths
+ *   - `javascript:`, `data:`, `mailto:`, `vbscript:` etc.
+ *   - bare hostnames (`example.com/path`)
+ *   - malformed URLs
+ */
+declare function validateSafeRedirect(input: string | null | undefined, opts?: SafeRedirectOptions): string;
+/**
+ * Boolean predicate form. Returns `true` when `input` would pass
+ * `validateSafeRedirect` with the same options.
+ */
+declare function isSafeRedirect(input: string | null | undefined, opts?: SafeRedirectOptions): boolean;
+
+/**
+ * Security-headers helper for Next.js hosts.
+ *
+ * Returns a shape that drops directly into the `headers()` entry in
+ * `next.config.ts` (or the `headers` field of a Route Handler
+ * `NextResponse`). Reasonable defaults for the top-of-OWASP headers
+ * — HSTS, X-Frame-Options, X-Content-Type-Options, Referrer-Policy,
+ * X-XSS-Protection, Permissions-Policy — with knobs for the fields
+ * that typically differ by app (HSTS duration, frame ancestors,
+ * camera/microphone policies).
+ *
+ * Framework-agnostic: no imports from `next/*` so the function works
+ * in Edge / Node / middleware and is trivially unit-testable.
+ */
+interface SecurityHeaderEntry {
+    key: string;
+    value: string;
+}
+interface BuildSecurityHeadersOptions {
+    /**
+     * HSTS max-age in seconds. Default `31536000` (1 year) — the value
+     * required for inclusion on the HSTS preload list. Set to `0` (or
+     * pass `includeHsts: false`) to opt out entirely.
+     */
+    hstsMaxAgeSeconds?: number;
+    /** Adds the `includeSubDomains` directive to HSTS. Default `true`. */
+    hstsIncludeSubDomains?: boolean;
+    /**
+     * Adds the `preload` directive to HSTS. Default `false` — only set
+     * to `true` after you've read https://hstspreload.org and are ready
+     * to commit; reversing it requires months of calendar time.
+     */
+    hstsPreload?: boolean;
+    /** Emit the HSTS header at all. Default `true`. */
+    includeHsts?: boolean;
+    /**
+     * Value for `X-Frame-Options`. Default `'DENY'`. Pass `'SAMEORIGIN'`
+     * if your app is framed by its own subdomain. Set to `null` to
+     * suppress (e.g. when you're already using `frame-ancestors` in
+     * CSP). `SAMEORIGIN` accepts no host parameter; use CSP's
+     * `frame-ancestors` for finer-grained framing policy.
+     */
+    frameOptions?: 'DENY' | 'SAMEORIGIN' | null;
+    /**
+     * Value for `Referrer-Policy`. Default `'strict-origin-when-cross-origin'`
+     * — same as Next.js's own default, balances analytics with privacy.
+     */
+    referrerPolicy?: 'no-referrer' | 'no-referrer-when-downgrade' | 'origin' | 'origin-when-cross-origin' | 'same-origin' | 'strict-origin' | 'strict-origin-when-cross-origin' | 'unsafe-url';
+    /**
+     * Permissions-Policy directives. Pass a map of `{ feature: allowlist }`
+     * where the allowlist is either an array of origins (string[]) or
+     * one of the well-known tokens `'self'` / `'*'` / `'()'` (deny).
+     *
+     * Default: camera + microphone allowed for `'self'` only (useful
+     * for the conference track); geolocation + payment denied; every
+     * other common feature left unset (browsers apply their own
+     * conservative defaults).
+     *
+     * Pass `{}` to emit an empty `Permissions-Policy: ` header (rarely
+     * useful). Pass `null` to suppress the header entirely.
+     */
+    permissionsPolicy?: PermissionsPolicyMap | null;
+    /**
+     * Value for `X-Content-Type-Options`. Default `'nosniff'` — do not
+     * override without a specific reason.
+     */
+    contentTypeOptions?: string | null;
+    /**
+     * Legacy `X-XSS-Protection`. Default `'0'` (disables the
+     * deprecated IE/Edge filter which had known bypass issues —
+     * recommended by OWASP + Next.js). Set to `'1; mode=block'` only
+     * if you have a specific compliance reason.
+     */
+    xssProtection?: string | null;
+    /**
+     * Extra headers to merge into the result. Takes precedence over
+     * the computed ones — useful for adding Content-Security-Policy or
+     * Cross-Origin-* headers without forcing a new option for each.
+     */
+    extraHeaders?: SecurityHeaderEntry[];
+}
+type PermissionsPolicyValue = readonly string[] | 'self' | '*' | '()';
+type PermissionsPolicyMap = Readonly<Record<string, PermissionsPolicyValue>>;
+declare const DEFAULT_PERMISSIONS_POLICY: PermissionsPolicyMap;
+/**
+ * Build a reasonable-default set of security response headers in the
+ * exact shape Next.js `headers()` expects.
+ *
+ * @example next.config.ts
+ * ```ts
+ * import { buildSecurityHeaders } from '@scalemule/nextjs/server'
+ *
+ * export default {
+ *   async headers() {
+ *     return [
+ *       { source: '/:path*', headers: buildSecurityHeaders() },
+ *     ]
+ *   },
+ * }
+ * ```
+ *
+ * @example custom overrides
+ * ```ts
+ * buildSecurityHeaders({
+ *   frameOptions: 'SAMEORIGIN',
+ *   permissionsPolicy: {
+ *     camera: ['https://trusted.example.com'],
+ *     microphone: ['https://trusted.example.com'],
+ *   },
+ *   extraHeaders: [
+ *     { key: 'Content-Security-Policy', value: "default-src 'self'" },
+ *   ],
+ * })
+ * ```
+ */
+declare function buildSecurityHeaders(opts?: BuildSecurityHeadersOptions): SecurityHeaderEntry[];
+
+export { type AnalyticsRoutesConfig, type AnalyticsTrackingGateConfig, type AuthMiddlewareConfig, type AuthRoutesConfig, type BuildSecurityHeadersOptions, CSRF_COOKIE_NAME, CSRF_HEADER_NAME, DEFAULT_PERMISSIONS_POLICY, type HandlerContext, type HandlerOptions, KNOWN_ACCOUNTS_COOKIE_NAME, type KnownAccountEntry, type MySqlBundle, type NotificationRoutesConfig, OAUTH_STATE_COOKIE_NAME, type OAuthBundle, type PermissionsPolicyMap, type PermissionsPolicyValue, type PostgresBundle, type PushRoutesConfig, type RedisBundle, type S3Bundle, SESSION_COOKIE_NAME, type SafeRedirectOptions, ScaleMuleError, type SecurityHeaderEntry, ServerConfig, type SessionCookieOptions, type SessionData, type SmtpBundle, USER_ID_COOKIE_NAME, apiHandler, appendKnownAccountCookie, buildClientContextHeaders, buildFlagContext, buildSecurityHeaders, clearKnownAccountsCookie, clearOAuthState, clearSession, configureBundles, configureSecrets, createAnalyticsRoutes, createAuthMiddleware, createAuthRoutes, createNotificationRoutes, createPushRoutes, errorCodeToStatus, extractClientContext, extractClientContextFromReq, generateCSRFToken, getAppSecret, getAppSecretOrDefault, getBootstrapFlags, getBundle, getCSRFToken, getKnownAccountsCookieRaw, getKnownAccountsFromRequest, getMySqlBundle, getOAuthBundle, getPostgresBundle, getRedisBundle, getS3Bundle, getSession, getSessionFromRequest, getSmtpBundle, invalidateBundleCache, invalidateSecretCache, isSafeRedirect, normalizeKnownAccountsCookie, prefetchBundles, prefetchSecrets, removeKnownAccountFromCookie, requireAppSecret, requireBundle, requireSession, setOAuthState, unwrap, validateCSRFToken, validateCSRFTokenAsync, validateOAuthState, validateOAuthStateAsync, validateSafeRedirect, withAuth, withCSRFProtection, withCSRFToken, withSession };