feat: add initAuthKit() for runtime config from secrets managers

[ShooTeX]

Closes #448

Summary

• Introduces initAuthKit(config: AuthKitConfig) exported from the package, letting users supply secrets from a vault or secrets manager instead of (or alongside) environment variables
• Replaces the static env-variables.ts module with a reactive config proxy — values set via initAuthKit take precedence; missing keys fall back to the corresponding process.env variable, so existing deployments need no changes
• Successive initAuthKit calls are merged, allowing partial/grouped overrides
• AuthKitConfig interface is also exported for typing

Usage

// e.g. in instrumentation.ts or a top-level server file
import { initAuthKit } from '@workos-inc/authkit-nextjs';

initAuthKit({
  apiKey: await secrets.get('WORKOS_API_KEY'),
  clientId: await secrets.get('WORKOS_CLIENT_ID'),
  cookiePassword: await secrets.get('WORKOS_COOKIE_PASSWORD'),
  redirectUri: 'https://myapp.com/callback',
});

Note: Call initAuthKit before any other AuthKit function. API connection settings (apiKey, apiHostname, apiHttps, apiPort) are applied once at WorkOS client creation and cannot be updated afterwards.

Caveats

Overrides are stored in a module-level singleton (globalThis[Symbol.for('workos.authkit.overrides')]), which means initAuthKit must be called once per runtime instance. In practice this is fine for long-lived Node.js servers, but worth noting for:

• Lambda / serverless functions — each cold start is a fresh runtime, so initAuthKit must run during the cold-start initialisation path (e.g. outside the handler, or in a top-level await before the handler is invoked).
• Edge / proxy runtimes (Vercel Edge, Cloudflare Workers, Next.js Middleware) — these may spin up many isolated micro-VMs; the same applies. If secret fetching adds latency, consider caching the resolved values and passing them in on each invocation.

A future improvement could expose a request-scoped or lazy-init variant to address these cases more ergonomically.

Test plan

• Unit tests added for config.ts covering env fallbacks, initAuthKit overrides, merging, and clearing back to env values
• Existing cookie, session, pkce, and workos test suites updated to use initAuthKit instead of Object.defineProperty hacks on the old env-variables module

[greptile-apps]

Greptile Summary

This PR adds runtime AuthKit configuration while keeping existing environment variable behavior. The main changes are:

• Adds initAuthKit() and the exported AuthKitConfig type.
• Replaces static env-variable imports with reactive config getters.
• Applies runtime config across auth, callback, middleware, session, cookie, PKCE, and WorkOS client paths.
• Adds tests for env fallbacks, override precedence, merging, clearing overrides, and parsed option types.

Confidence Score: 5/5

This PR is safe to merge with minimal risk.

The changed paths consistently use config getters while preserving existing fallbacks. Tests cover override precedence, merging, clearing, and parsed option values. No blocking correctness or security issues were identified.

No files require special attention.

T-Rex Logs

What T-Rex did

• Ran the Authkit Vitest test suite and confirmed all tests passed with exit code 0.
• Ran the Authkit TypeScript typecheck and confirmed it completed with exit code 0.

_{Ran code and verified through T-Rex}

Important Files Changed

Filename	Overview
src/config.ts	Adds the exported AuthKitConfig interface, global override store, initAuthKit merge API, and env-backed config getters.
src/workos.ts	Builds the lazy WorkOS client from runtime config so initAuthKit values are applied before first client creation.
src/session.ts	Replaces static env reads with config access for cookie names, cookie passwords, redirect URI, client ID, and JWKS setup.
src/get-authorization-url.ts	Uses runtime config for claim nonce exchange, state sealing, client ID, cookie password, and redirect URI selection.
src/cookie.ts	Reads cookie-related settings from the new config accessor while preserving validation, secure-cookie, max-age, and domain behavior.
src/index.ts	Exports initAuthKit and the AuthKitConfig type from the public package entry point.

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
participant App as User app startup
participant Config as initAuthKit/config
participant Env as process.env
participant Auth as AuthKit functions
participant WorkOS as Lazy WorkOS client

App->>Config: initAuthKit(runtime secrets)
Config->>Config: merge overrides globally
Auth->>Config: read config value
alt override exists
    Config-->>Auth: return override
else missing override
    Config->>Env: read matching env var
    Env-->>Config: env value or empty/default
    Config-->>Auth: fallback value
end
Auth->>WorkOS: getWorkOS()
WorkOS->>Config: read API settings once
WorkOS-->>Auth: cached WorkOS instance

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
participant App as User app startup
participant Config as initAuthKit/config
participant Env as process.env
participant Auth as AuthKit functions
participant WorkOS as Lazy WorkOS client

App->>Config: initAuthKit(runtime secrets)
Config->>Config: merge overrides globally
Auth->>Config: read config value
alt override exists
    Config-->>Auth: return override
else missing override
    Config->>Env: read matching env var
    Env-->>Config: env value or empty/default
    Config-->>Auth: fallback value
end
Auth->>WorkOS: getWorkOS()
WorkOS->>Config: read API settings once
WorkOS-->>Auth: cached WorkOS instance

Loading

_{Reviews (1): Last reviewed commit: "let user init authkit with secrets outsi..." | Re-trigger Greptile}