@bajustone/fortress 1.0.0-rc.1

package/dist/config-B2366s_G.d.ts

@@ -0,0 +1,665 @@
+import { D as DatabaseAdapter, S as ScopeRule } from './index-CxEkfCA0.js';
+import { JwtKeyMaterial } from './jwt.js';
+import { i as AuthService, g as IamService, F as FortressLogger, T as TelemetryProvider } from './auth-service-BkzZkWfH.js';
+import { S as Subject, T as TokenClaims, i as CreateUserInput, l as PendingReason, F as FortressUser, p as AuthSuccess, h as AuthTokenPair, R as RequestMeta } from './types-et0R8tsC.js';
+
+/**
+ * Standard Schema V1 interfaces — inlined from the spec.
+ * No `@standard-schema/spec` dependency needed.
+ *
+ * @see https://standardschema.dev
+ * @see https://github.com/standard-schema/standard-schema
+ */
+declare namespace StandardSchemaV1 {
+    interface Props<Input = unknown, Output = Input> {
+        readonly version: 1;
+        readonly vendor: string;
+        readonly validate: (value: unknown) => Result<Output> | Promise<Result<Output>>;
+        readonly types?: Types<Input, Output> | undefined;
+    }
+    type Result<Output> = SuccessResult<Output> | FailureResult;
+    interface SuccessResult<Output> {
+        readonly value: Output;
+        readonly issues?: undefined;
+    }
+    interface FailureResult {
+        readonly issues: ReadonlyArray<Issue>;
+    }
+    interface Issue {
+        readonly message: string;
+        readonly path?: ReadonlyArray<PropertyKey | PathSegment> | undefined;
+    }
+    interface PathSegment {
+        readonly key: PropertyKey;
+    }
+    interface Types<Input = unknown, Output = Input> {
+        readonly input: Input;
+        readonly output: Output;
+    }
+    type InferInput<Schema extends StandardSchemaV1> = NonNullable<Schema['~standard']['types']>['input'];
+    type InferOutput<Schema extends StandardSchemaV1> = NonNullable<Schema['~standard']['types']>['output'];
+}
+interface StandardSchemaV1<Input = unknown, Output = Input> {
+    readonly '~standard': StandardSchemaV1.Props<Input, Output>;
+}
+
+/**
+ * JSON Schema types (draft 2020-12 subset) + FortressSchema.
+ *
+ * FortressSchema<T> extends JSONSchema with Standard Schema V1 support,
+ * giving each schema: JSON Schema fields (OpenAPI), runtime validation,
+ * and TypeScript type inference — all from one object.
+ */
+
+/** A subset of JSON Schema (draft 2020-12) sufficient for fortress endpoint definitions and OpenAPI generation. */
+interface JSONSchema {
+    type?: 'string' | 'number' | 'integer' | 'boolean' | 'array' | 'object' | 'null';
+    properties?: Record<string, JSONSchema>;
+    required?: string[];
+    items?: JSONSchema;
+    enum?: (string | number | boolean | null)[];
+    const?: string | number | boolean | null;
+    format?: string;
+    description?: string;
+    default?: unknown;
+    nullable?: boolean;
+    oneOf?: JSONSchema[];
+    anyOf?: JSONSchema[];
+    allOf?: JSONSchema[];
+    $ref?: string;
+    discriminator?: {
+        propertyName: string;
+        mapping?: Record<string, string>;
+    };
+    additionalProperties?: boolean | JSONSchema;
+    minimum?: number;
+    maximum?: number;
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+    title?: string;
+}
+/**
+ * A JSON Schema object that also implements Standard Schema V1.
+ *
+ * - JSON Schema fields → OpenAPI 3.1 spec generation
+ * - `~standard.validate()` → runtime validation
+ * - `StandardSchemaV1.InferOutput<typeof schema>` → TypeScript type inference
+ */
+type FortressSchema<T = unknown> = JSONSchema & StandardSchemaV1<T, T>;
+/** Extract the TypeScript type from a FortressSchema or StandardSchemaV1. */
+type Infer<T> = T extends StandardSchemaV1<any, infer O> ? O : unknown;
+/** Flatten intersection types for clean IDE tooltips. */
+type Simplify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+
+/** HTTP method an {@link EndpointDefinition} can declare. */
+type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+/** Authentication scheme required to call an endpoint. */
+type SecurityRequirement = 'bearer' | 'basic' | 'apiKey' | 'none';
+/** A required IAM permission, expressed as a `(resource, action)` pair. */
+interface EndpointPermission {
+    resource: string;
+    action: string;
+}
+/** OpenAPI / IAM metadata attached to an {@link EndpointDefinition}. */
+interface EndpointMeta {
+    summary: string;
+    description?: string;
+    tags?: string[];
+    security?: SecurityRequirement[];
+    deprecated?: boolean;
+    /** IAM permission required to access this endpoint. Enforced by RBAC middleware. */
+    permission?: EndpointPermission;
+    /**
+     * What kind of bearer token this route accepts.
+     *
+     * - `'jwt'` (default) — the route expects a Fortress session JWT in
+     *   `Authorization: Bearer <jwt>` (or the cookie). The dispatcher runs
+     *   the plugin principal chain, JWT verification, and RBAC enforcement
+     *   automatically before invoking the handler.
+     * - `'oauth'` — the route's bearer is an OAuth 2.0 access token (or no
+     *   token at all, e.g. `/oauth/authorize`). The dispatcher skips its
+     *   auth pipeline entirely and the handler self-parses the bearer
+     *   (typical for `/oauth/userinfo`, `/oauth/token`, etc.). Body parsing
+     *   and validation are also skipped, since OAuth bodies are
+     *   `application/x-www-form-urlencoded` per RFC 6749.
+     *
+     * Routes that don't set this field default to `'jwt'`. Without this
+     * marker, the OAuth plugin's consent-flow endpoints
+     * (`/oauth/flows/:flowId{,/approve,/deny}`) — which are SPA-driven and
+     * require a Fortress JWT — used to be silently unauthenticated due to
+     * a path-based `startsWith('/oauth/')` short-circuit in the dispatcher,
+     * forcing every host app to ship a workaround shim. Setting
+     * `bearerKind: 'oauth'` only on the actual protocol routes lets the
+     * dispatcher honour `security: ['bearer']` everywhere else.
+     */
+    bearerKind?: 'jwt' | 'oauth';
+}
+/** Request input declarations for an endpoint — JSON Schemas for OpenAPI plus Standard Schemas for runtime validation. */
+interface EndpointInput {
+    /** JSON Schema for OpenAPI spec generation. */
+    body?: JSONSchema;
+    query?: JSONSchema;
+    params?: JSONSchema;
+    /** Standard Schema references for runtime validation (set by endpoint builder). */
+    bodySchema?: StandardSchemaV1;
+    querySchema?: StandardSchemaV1;
+    paramsSchema?: StandardSchemaV1;
+}
+/** A single OpenAPI response definition (description plus optional JSON Schema). */
+interface EndpointResponse {
+    description: string;
+    schema?: JSONSchema;
+}
+/**
+ * Declarative description of one HTTP endpoint.
+ *
+ * The four generic parameters are **phantom types** — they're populated by
+ * the fluent {@link EndpointBuilder} as schemas are declared via `.body()`,
+ * `.query()`, `.params()`, and `.response()`, and then extracted at the call
+ * site by the `InferEndpoint*` helpers (and by the typed `fortress.call.*`
+ * proxy). None of them exist at runtime.
+ *
+ * The defaults are `{}` (empty object), not `unknown`, so that the
+ * intersection-based `InferEndpointCallInput` collapses cleanly for
+ * endpoints that only declare one of the three input slots.
+ */
+interface EndpointDefinition<TBody = {}, TQuery = {}, TParams = {}, TResponses extends Record<number, unknown> = {}> {
+    method: HttpMethod;
+    path: string;
+    handler: string;
+    meta?: EndpointMeta;
+    input?: EndpointInput;
+    responses?: Record<number, EndpointResponse>;
+    /** Phantom — never present at runtime. Consumed by `InferEndpoint*` helpers. */
+    __types?: {
+        body: TBody;
+        query: TQuery;
+        params: TParams;
+        responses: TResponses;
+    };
+}
+/** Extract the request-body type from an {@link EndpointDefinition}. */
+type InferEndpointBody<E> = E extends EndpointDefinition<infer B, any, any, any> ? B : never;
+/** Extract the query-string type from an {@link EndpointDefinition}. */
+type InferEndpointQuery<E> = E extends EndpointDefinition<any, infer Q, any, any> ? Q : never;
+/** Extract the path-params type from an {@link EndpointDefinition}. */
+type InferEndpointParams<E> = E extends EndpointDefinition<any, any, infer P, any> ? P : never;
+/** Extract the full `Record<status, body>` response map from an {@link EndpointDefinition}. */
+type InferEndpointResponses<E> = E extends EndpointDefinition<any, any, any, infer R> ? R : never;
+/**
+ * Extract the success-response body from an {@link EndpointDefinition}.
+ *
+ * Tries `200`, then `201`, then `204`, then falls back to `unknown`.
+ * This matches the behavior of the `fortress.call.*` proxy, which always
+ * resolves to the first successful status declared.
+ */
+type InferEndpointSuccessResponse<E> = InferEndpointResponses<E> extends infer R ? R extends {
+    200: infer T;
+} ? T : R extends {
+    201: infer T;
+} ? T : R extends {
+    204: infer T;
+} ? T : unknown : never;
+/**
+ * The flat input shape accepted by the typed `fortress.call.<handler>(input)`
+ * proxy — the intersection of body, query, and params. For endpoints that
+ * only declare one of the three, the other slots are `{}` and disappear from
+ * the intersection.
+ */
+type InferEndpointCallInput<E> = Simplify<InferEndpointBody<E> & InferEndpointQuery<E> & InferEndpointParams<E>>;
+/**
+ * Component schemas are reusable JSON Schema definitions
+ * that endpoints reference via $ref (e.g., '#/components/schemas/User').
+ */
+interface ComponentSchemas {
+    [name: string]: JSONSchema;
+}
+
+type PasswordBreachFailureMode = 'open' | 'closed';
+interface PasswordBreachDegradedEvent {
+    failureMode: PasswordBreachFailureMode;
+    status?: number;
+    error?: unknown;
+}
+/** Called whenever the HIBP control is unavailable, regardless of failure mode. */
+type PasswordPolicyObserver = (event: PasswordBreachDegradedEvent) => void;
+interface PasswordPolicyConfig {
+    /** Minimum password length. Default: 15 (NIST 800-63B). */
+    minLength?: number;
+    /** Maximum password length. Default: 128 (NIST 800-63B). */
+    maxLength?: number;
+    /** Check password against HIBP breached password database via k-anonymity API. Default: false. */
+    checkBreached?: boolean;
+    /** Cache TTL for HIBP range responses in milliseconds. Default: 86400000 (24h). */
+    breachedCacheTtlMs?: number;
+    /** Maximum cached HIBP range responses. Default: 1000. Set to 0 to disable caching. */
+    breachedCacheMaxEntries?: number;
+    /** Whether HIBP unavailability permits password writes. Default: 'open'. */
+    breachedFailureMode?: PasswordBreachFailureMode;
+}
+type HibpCache = Map<string, {
+    data: string;
+    expiresAt: number;
+}>;
+interface PasswordBreachCheckOptions {
+    cacheTtlMs?: number;
+    cacheMaxEntries?: number;
+    failureMode?: PasswordBreachFailureMode;
+    observer?: PasswordPolicyObserver;
+    /** Internal per-Fortress-instance cache supplied by validatePassword. */
+    cache?: HibpCache;
+}
+
+/**
+ * Pipeline-level CSRF protection.
+ *
+ * Activated by default for unsafe HTTP methods (`POST/PUT/PATCH/DELETE`)
+ * when the request authenticated via a Fortress auth cookie. Bearer-only
+ * and API-key requests are CSRF-immune by construction (no ambient
+ * credential the browser would auto-attach) and are skipped.
+ *
+ * The check is intentionally narrow:
+ *
+ * 1. Reject when `Sec-Fetch-Site: cross-site`. Modern browsers send this
+ *    header on every fetch — its presence + value is a reliable signal.
+ * 2. Reject when the required custom header (`X-Fortress-CSRF` by default)
+ *    is absent. Custom-header CSRF leverages the browser preflight rule:
+ *    a cross-origin request can't set the header without an explicit
+ *    server-side CORS allowance.
+ *
+ * Closes H5 — before this, `mountFortress` / `createSvelteKitHandle`
+ * dispatched straight to `handleRequest` with no CSRF check. This check now
+ * runs inside `handleRequest`, so every Fortress-managed route is covered
+ * regardless of adapter (Hono, Express, SvelteKit). The SvelteKit adapter's
+ * user-route silent token refresh — the one remaining Fortress state-change
+ * outside this pipeline — is independently gated to safe HTTP methods.
+ */
+
+/** User-facing CSRF configuration (all fields optional). */
+interface CsrfConfig {
+    /**
+     * Set to `false` to disable the pipeline CSRF check entirely. Useful for
+     * pure bearer-only API deployments where no Fortress route is reachable
+     * with ambient credentials. Default: `true`.
+     */
+    enabled?: boolean;
+    /** Required header name. Default: `'X-Fortress-CSRF'`. */
+    headerName?: string;
+    /**
+     * Exact-path allow-list of routes the check should skip. Matched at
+     * segment boundaries (i.e. `'/foo'` matches `/foo` and `/foo/bar` but
+     * not `/foobar`).
+     */
+    skipPaths?: string[];
+    /**
+     * Additionally reject `Sec-Fetch-Site: same-site` requests. Single-host
+     * deployments (web app + Fortress on the same origin) can opt in to the
+     * stricter posture; multi-host (`api.example.com` + `app.example.com`)
+     * deployments leave this `false` so the legit app traffic passes.
+     * Default: `false`.
+     */
+    rejectSameSite?: boolean;
+}
+
+/**
+ * Framework-agnostic plugin middleware execution for `fortress.handleRequest`
+ * and adapter handles.
+ *
+ * Wraps {@link executePluginMiddleware} from `plugin-runner.ts` so the
+ * caller can hand it a {@link PluginRequestContext} (a duck-typed object with
+ * `fortressUserId` and friends) instead of a framework-specific Hono context
+ * or Express request.
+ *
+ * Plugins that short-circuit do so by throwing a {@link FortressError}; the
+ * caller is expected to wrap this in a try/catch and translate via
+ * `errorToResponse`.
+ */
+
+/**
+ * Object passed to plugin middleware as the "request" argument when running
+ * inside `fortress.handleRequest` or any framework adapter that delegates to
+ * core. Carries the web-standard `Request` plus the resolved auth context.
+ *
+ * The shape is intentionally compatible with the existing admin-plugin
+ * `extractUserId` helper, which checks `'fortressUserId' in request`.
+ */
+interface PluginRequestContext {
+    request: Request;
+    /**
+     * The resolved principal for this request, if any. Populated from a
+     * plugin `resolvePrincipal` hit or the JWT fallback. Plugins preferring
+     * subject-level identity (non-USER principals) should read this instead
+     * of `fortressUserId`.
+     */
+    fortressSubject?: Subject;
+    /**
+     * Convenience alias — set only when the resolved subject is a `USER`.
+     * Non-USER principals (e.g. `SERVICE_ACCOUNT` via api-key) leave this
+     * field undefined; consumers should fall back to `fortressSubject`.
+     */
+    fortressUserId?: string;
+    fortressClaims?: TokenClaims;
+    /** Credential-level narrowing scopes (for example API-key scopes), if any. */
+    fortressScopes?: string[] | null;
+}
+
+interface FortressPlugin {
+    /** Unique plugin identifier */
+    name: string;
+    /** DB models this plugin needs */
+    models?: ModelDefinition[];
+    /** Hooks into auth lifecycle (executed in plugin registration order) */
+    hooks?: PluginHooks;
+    /** Extra methods exposed on fortress.plugins.<name> */
+    methods?: (ctx: PluginContext) => Record<string, Function>;
+    /**
+     * HTTP routes this plugin adds, keyed by handler name.
+     *
+     * A keyed record (not an array) so each entry's full
+     * `EndpointDefinition<TBody, TQuery, TParams, TResponses>` type is
+     * preserved for the typed `fortress.call.*` proxy. The dispatcher looks
+     * plugin route handlers up by name (`fortress.plugins[pluginName][handlerName]`),
+     * so the keyed shape is already the natural fit at dispatch time — the
+     * key just needs to match the `EndpointDefinition.handler` string.
+     */
+    routes?: Record<string, EndpointDefinition>;
+    /** Middleware to inject into the request pipeline */
+    middleware?: MiddlewareDefinition[];
+    /** Wrap the DatabaseAdapter per-request */
+    wrapAdapter?: (adapter: DatabaseAdapter, requestContext: Record<string, unknown>) => DatabaseAdapter;
+    /** Extend JWT token claims */
+    enrichTokenClaims?: (userId: string, ctx: PluginContext) => Promise<Record<string, unknown>>;
+    /** Scope data access by user context (row-level data isolation) */
+    scopeRules?: (userId: string, model: string, ctx: PluginContext) => Promise<ScopeRule | null>;
+    /**
+     * Resolve a request principal from a non-JWT credential — API key,
+     * OAuth bearer, mTLS client cert, signed JWT assertion, etc.
+     *
+     * Called by `fortress.handleRequest` **before** the JWT fallback. Plugins
+     * are tried in registration order; the first to return a non-null result
+     * wins, and its subject (plus optional claims) become the request
+     * principal for downstream RBAC. Returning `null` means "defer" — the
+     * next plugin is tried, and if none resolve, the core JWT path runs.
+     *
+     * This is the extension point for any future credential mechanism. The
+     * api-key plugin implements it to turn `Authorization: ApiKey <key>` /
+     * `X-API-Key: <key>` headers into a `USER` or `SERVICE_ACCOUNT`
+     * principal.
+     */
+    resolvePrincipal?: (request: Request, ctx: PluginContext) => Promise<{
+        subject: Subject;
+        claims?: TokenClaims;
+        scopes?: string[] | null;
+    } | null>;
+}
+interface PluginHooks {
+    beforeLogin?: (ctx: HookContext & {
+        email: string;
+    }) => Promise<HookResult | void>;
+    beforeRegister?: (ctx: HookContext & {
+        data: CreateUserInput;
+    }) => Promise<HookResult | void>;
+    beforeTokenRefresh?: (ctx: HookContext & {
+        token: string;
+    }) => Promise<HookResult | void>;
+    beforeLogout?: (ctx: HookContext & {
+        token: string;
+    }) => Promise<void>;
+    onLoginFailure?: (ctx: HookContext & {
+        identifier: string;
+        error: Error;
+    }) => Promise<void>;
+    /** Runs after primary credentials succeed but before any token is issued. */
+    postAuthGate?: PostAuthGateProvider;
+    afterLogin?: (ctx: AfterHookContext, result: AuthSuccess) => Promise<AuthSuccess>;
+    afterRegister?: (ctx: AfterHookContext, user: FortressUser) => Promise<void>;
+    afterTokenRefresh?: (ctx: AfterHookContext, result: AuthTokenPair) => Promise<AuthTokenPair>;
+}
+interface HookContext {
+    db: DatabaseAdapter;
+    config: FortressConfig;
+    meta?: RequestMeta;
+}
+interface AfterHookContext extends HookContext {
+    responseHeaders: Headers;
+    /** Normalized login identifier used for this auth flow, when applicable. */
+    identifier?: string;
+}
+interface HookResult {
+    stop: true;
+    response: Record<string, unknown>;
+}
+interface PostAuthGateContext extends HookContext {
+    user: FortressUser;
+    /** Reasons already satisfied by the continuation currently being completed. */
+    completedReasons: readonly PendingReason[];
+}
+interface PostAuthGateDecision {
+    pluginData?: Record<string, unknown>;
+}
+interface PostAuthGateVerificationContext extends HookContext {
+    user: FortressUser;
+    continuation: {
+        id: string;
+        reason: PendingReason;
+        expiresAt: Date;
+    };
+}
+interface PostAuthGateProvider {
+    reason: PendingReason;
+    /** Durable failed-proof policy stored on each continuation. */
+    maxAttempts?: number;
+    cooldownSeconds?: number;
+    evaluate: (ctx: PostAuthGateContext) => Promise<PostAuthGateDecision | void>;
+    /** Return optional plugin data to include in the final AuthResult. */
+    verify: (ctx: PostAuthGateVerificationContext, completion: unknown) => Promise<Record<string, unknown> | void>;
+}
+type ModelConstraint = {
+    type: 'unique';
+    fields: string[];
+} | {
+    type: 'index';
+    fields: string[];
+    name?: string;
+};
+interface ModelDefinition {
+    name: string;
+    fields: Record<string, FieldDefinition>;
+    constraints?: ModelConstraint[];
+}
+interface FieldDefinition {
+    type: 'string' | 'number' | 'boolean' | 'date';
+    required?: boolean;
+    unique?: boolean;
+    references?: {
+        model: string;
+        field: string;
+    };
+}
+interface PluginContext {
+    db: DatabaseAdapter;
+    config: FortressConfig;
+    /** Auth service reference. Optional at init time; available at runtime (enrichTokenClaims, scopeRules). */
+    auth?: AuthService;
+    /** IAM service reference. Optional at init time; available at runtime. */
+    iam?: IamService;
+    /** Resolved logger (silent no-op if `config.logger` is unset). */
+    logger?: FortressLogger;
+}
+/**
+ * Second argument passed to plugin HTTP route handlers by the dispatcher.
+ * Carries the verified caller identity and the raw Request so handlers can
+ * make authorization decisions, stamp audit entries, or read headers/cookies
+ * without trusting client-supplied body fields.
+ *
+ * `subject` / `claims` are populated whenever the endpoint's `meta.security`
+ * declared bearer auth (the dispatcher resolves principals first). `userId`
+ * is a convenience — it's present iff `subject?.type === 'USER'`, matching
+ * the pre-SERVICE_ACCOUNT shape. For public endpoints all three are
+ * `undefined`.
+ */
+interface PluginRouteContext {
+    /** Resolved request principal — USER or SERVICE_ACCOUNT. */
+    subject?: Subject;
+    /** Convenience alias for `subject?.id` when the subject is a USER. */
+    userId?: string;
+    claims?: TokenClaims;
+    /** Credential-level narrowing scopes from principal resolution, if any. */
+    scopes?: string[] | null;
+    meta?: RequestMeta;
+    request: Request;
+}
+interface MiddlewareDefinition {
+    path: string;
+    position: 'before-auth' | 'after-auth' | 'after-rbac';
+    handler: (ctx: PluginContext, request: PluginRequestContext, next: () => Promise<void>) => Promise<void>;
+}
+
+/** Pluggable password hashing contract — implement to swap fortress's default Argon2id WASM hasher. */
+interface PasswordHasher {
+    hash: (password: string) => Promise<string>;
+    verify: (hash: string, password: string) => Promise<boolean>;
+}
+/**
+ * Cookie configuration consumed by `fortress.handleRequest` and any framework
+ * adapter that wants to serialize auth tokens to `Set-Cookie` headers.
+ *
+ * Defaults are environment-independent and production-safe: `__Host-`
+ * prefixed names, `httpOnly`, `secure`, `sameSite: 'lax'`, `path: '/'`.
+ * Plain-HTTP local development must explicitly set `secure: false`, which
+ * also selects non-`__Host-` default names.
+ */
+interface CookieConfig {
+    /** Override the access-token cookie name. Default: `__Host-fortress_access` when host-prefix constraints permit. */
+    accessName?: string;
+    /** Override the refresh-token cookie name. Default: `__Host-fortress_refresh` when host-prefix constraints permit. */
+    refreshName?: string;
+    /** SameSite attribute. Default: `'lax'`. */
+    sameSite?: 'lax' | 'strict' | 'none';
+    /** Force the `Secure` attribute on or off. Default: `true` in every environment. */
+    secure?: boolean;
+    /** Optional `Domain` attribute. Defaults to host-only when omitted. */
+    domain?: string;
+    /** `Path` attribute. Default: `'/'`. */
+    path?: string;
+}
+/** Opt-in refresh-session controls. Omitted fields preserve existing behavior. */
+interface SessionConfig {
+    /** Accept the immediately previous refresh token for this many seconds. */
+    refreshGraceSeconds?: number;
+    /** Reject a session after this many seconds without refresh activity. */
+    idleTimeoutSeconds?: number;
+    /** Reject a refresh family after this many seconds, regardless of activity. */
+    absoluteTimeoutSeconds?: number;
+    /** Maximum active refresh families per user; oldest sessions are revoked first. */
+    maxSessionsPerUser?: number;
+}
+/** Top-level fortress configuration accepted by {@link createFortress}. */
+interface FortressConfig {
+    jwt: {
+        /**
+         * Signing/verification key material. Today: an HS256 shared secret
+         * (string) or a rotation array of shared secrets (first signs, all
+         * verify). See {@link JwtKeyMaterial} for the planned expansion to
+         * asymmetric keys / JWKS.
+         */
+        key: JwtKeyMaterial;
+        issuer?: string;
+        /** Optional audience included in and required for access tokens. */
+        audience?: string | string[];
+        accessTokenExpirySeconds?: number;
+        refreshTokenExpirySeconds?: number;
+        /**
+         * Compare a domain-separated keyed fingerprint of User-Agent + source IP
+         * across refreshes. This is an anomaly signal, not proof of device identity;
+         * enable hard rejection only where client IP stability is acceptable.
+         */
+        validateRefreshFingerprint?: boolean | 'warn';
+        /** Optional session rotation/cap controls. No caps or grace apply when omitted. */
+        session?: SessionConfig;
+    };
+    rbac?: {
+        evaluationMode?: 'allow-only' | 'deny-overrides';
+        resourceFile?: string;
+        cache?: {
+            ttlSeconds?: number;
+            maxEntries?: number;
+        };
+    };
+    database: DatabaseAdapter;
+    passwordHasher?: PasswordHasher;
+    passwordPolicy?: PasswordPolicyConfig;
+    /**
+     * Impersonation hardening (RFC 8693 `act` tokens). All fields optional;
+     * defaults to a 1-hour ceiling on caller-supplied `expirySeconds`.
+     */
+    impersonation?: {
+        /**
+         * Hard ceiling on the impersonation access-token lifetime in seconds.
+         * `auth.impersonate({ expirySeconds })` is clamped to this. Default: 3600.
+         */
+        maxTtlSeconds?: number;
+    };
+    plugins?: readonly FortressPlugin[];
+    /**
+     * Host-application endpoint definitions to register with the manifest,
+     * OpenAPI generation, and `protect()` / adapter `protectedRoute()` helpers
+     * without authoring a plugin. Fortress tracks them internally under the
+     * reserved name `__host`.
+     *
+     * Top-level `routes` are metadata-only: adapters leave them to the host
+     * router and they do not add `fortress.call.*` entries because no handler
+     * methods are registered. If you need Fortress-mounted routes or typed
+     * in-process callables for custom routes, declare a real plugin with both
+     * `routes` and matching `methods`.
+     *
+     * Keyed by handler name, matching {@link FortressPlugin.routes}:
+     *
+     * ```ts
+     * createFortress({
+     *   database, jwt, cookies,
+     *   routes: appEndpoints,
+     * });
+     * ```
+     *
+     * The name `__host` is reserved — declaring a plugin called `__host`
+     * alongside `routes` is a configuration error.
+     */
+    routes?: Record<string, EndpointDefinition>;
+    /** Auth-cookie naming and attributes used by `fortress.handleRequest` and framework adapters. */
+    cookies?: CookieConfig;
+    /**
+     * Pipeline CSRF protection (H5). Defaults to `{ enabled: true }`.
+     * Bearer/API-key requests are exempt automatically — only cookie-auth
+     * traffic is checked. See {@link CsrfConfig}.
+     */
+    csrf?: CsrfConfig;
+    /**
+     * Optional pluggable logger. Accepts any object that conforms structurally
+     * to {@link FortressLogger} — a `pino()` instance, Fastify's `app.log`,
+     * or a hand-rolled `console` wrapper. Defaults to a silent no-op so
+     * Fortress never writes to stderr unless the caller opts in.
+     */
+    logger?: FortressLogger;
+    /**
+     * Optional telemetry provider (tracer + meter). Wire this to the
+     * OpenTelemetry adapter with `createOtelTelemetry` from the
+     * `@bajustone/fortress/otel` sub-path, or provide any custom
+     * implementation. Defaults to a zero-alloc no-op provider.
+     */
+    observability?: TelemetryProvider;
+}
+/** Validated cookie attributes resolved independently of `NODE_ENV`. */
+interface ResolvedCookieConfig {
+    accessName: string;
+    refreshName: string;
+    sameSite: 'lax' | 'strict' | 'none';
+    secure: boolean;
+    domain?: string;
+    path: string;
+}
+
+export { type AfterHookContext as A, type PluginRequestContext as B, type ComponentSchemas as C, type PostAuthGateContext as D, type EndpointDefinition as E, type FortressPlugin as F, type PostAuthGateDecision as G, type HttpMethod as H, type InferEndpointParams as I, type JSONSchema as J, type PostAuthGateProvider as K, type PostAuthGateVerificationContext as L, type MiddlewareDefinition as M, type SessionConfig as N, type EndpointPermission as O, type PasswordHasher as P, type ResolvedCookieConfig as R, StandardSchemaV1 as S, type InferEndpointQuery as a, type InferEndpointBody as b, type InferEndpointCallInput as c, type InferEndpointResponses as d, type PluginContext as e, type PluginRouteContext as f, type SecurityRequirement as g, type FortressSchema as h, type Infer as i, type Simplify as j, type EndpointInput as k, type EndpointMeta as l, type EndpointResponse as m, type FieldDefinition as n, type FortressConfig as o, type HookContext as p, type HookResult as q, type InferEndpointSuccessResponse as r, type ModelConstraint as s, type ModelDefinition as t, type PasswordBreachCheckOptions as u, type PasswordBreachDegradedEvent as v, type PasswordBreachFailureMode as w, type PasswordPolicyConfig as x, type PasswordPolicyObserver as y, type PluginHooks as z };