@bajustone/fortress 1.0.0-rc.1

package/dist/fortress-BmSvFfqK.d.cts

@@ -0,0 +1,1089 @@
+import { S as SpecBuilderOptions, O as OpenAPISpec, a as OpenAPIMethods } from './index-D054pcb-.cjs';
+import { g as IamService, i as AuthService, F as FortressLogger, T as TelemetryProvider } from './auth-service-BcyQ2PuZ.cjs';
+import { E as EndpointDefinition, h as FortressSchema, H as HttpMethod, O as EndpointPermission, g as SecurityRequirement, C as ComponentSchemas, c as InferEndpointCallInput, r as InferEndpointSuccessResponse, F as FortressPlugin, o as FortressConfig, R as ResolvedCookieConfig, M as MiddlewareDefinition, B as PluginRequestContext } from './config-GtlVt6ZD.cjs';
+import { l as PendingReason, g as AuthMethod, S as Subject, T as TokenClaims } from './types-et0R8tsC.cjs';
+import { D as DatabaseAdapter } from './index-CxEkfCA0.cjs';
+import { ApiKeyMethods } from './plugins/api-key.cjs';
+import { AuditLogMethods } from './plugins/audit-log.cjs';
+import { DataIsolationMethods } from './plugins/data-isolation.cjs';
+import { EmailVerificationMethods } from './plugins/email-verification.cjs';
+import { MagicLinkMethods } from './plugins/magic-link.cjs';
+import { OAuthMethods } from './plugins/oauth.cjs';
+import { SocialLoginMethods } from './plugins/social-login.cjs';
+import { TenancyMethods } from './plugins/tenancy.cjs';
+import { TwoFactorMethods } from './plugins/two-factor.cjs';
+import { WebAuthnMethods } from './plugins/webauthn.cjs';
+
+interface EmptyInput$1 {
+}
+/** Wire shape of a fortress user — domain `Date` fields are ISO strings on the wire. */
+interface UserWire {
+    id: string;
+    email: string;
+    name: string;
+    isActive: boolean;
+    emailVerified?: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+/** Wire shape of a pending post-auth challenge. */
+interface AuthChallengeWire {
+    reason: PendingReason;
+    continuationToken: string;
+}
+/** Wire shape of a successful sign-in. */
+interface AuthSuccessWire {
+    status: 'success';
+    user: UserWire;
+    method: AuthMethod;
+    accessToken: string;
+    refreshToken: string;
+    pluginData?: Record<string, unknown>;
+}
+/** Wire shape of a pending sign-in (2FA, email verification, etc.). */
+interface AuthPendingWire {
+    status: 'pending';
+    user: UserWire;
+    pending: AuthChallengeWire;
+    pluginData?: Record<string, unknown>;
+}
+/** Wire shape of an impersonation sign-in (no refresh token). */
+interface AuthImpersonationWire {
+    status: 'impersonation';
+    user: UserWire;
+    accessToken: string;
+    refreshToken: null;
+    pluginData?: Record<string, unknown>;
+}
+/** Discriminated union of every auth-flow wire outcome. */
+type AuthResultWire = AuthSuccessWire | AuthPendingWire | AuthImpersonationWire;
+/** Wire shape of a refreshed access/refresh token pair. */
+interface AuthTokenPairWire {
+    accessToken: string;
+    refreshToken: string;
+}
+/** Wire shape of a persisted refresh-token session. */
+interface SessionInfoWire {
+    id: string;
+    ipAddress?: string | null;
+    userAgent?: string | null;
+    deviceName?: string | null;
+    createdAt: string;
+    lastActiveAt?: string | null;
+}
+/** Wire shape of the create-user input body. */
+interface CreateUserInputWire {
+    email: string;
+    name: string;
+    password?: string;
+    isActive?: boolean;
+}
+/** Wire shape of a structured error response. */
+interface ErrorResponseWire {
+    code: string;
+    message: string;
+    statusCode: number;
+}
+/** Wire shape of a login identifier. */
+interface LoginIdentifierWire {
+    id: string;
+    userId: string;
+    type: 'email' | 'phone' | 'username';
+    value: string;
+}
+/** Empty `{ ok: boolean }` ack. */
+interface OkResponseWire {
+    ok: boolean;
+}
+/** Explicit registry type so JSR's fast-check doesn't walk into the deeply-inferred `defineComponents` return. */
+interface AuthComponents {
+    readonly components: {
+        readonly User: FortressSchema<UserWire>;
+        readonly AuthChallenge: FortressSchema<AuthChallengeWire>;
+        readonly AuthResult: FortressSchema<AuthResultWire>;
+        readonly AuthTokenPair: FortressSchema<AuthTokenPairWire>;
+        readonly SessionInfo: FortressSchema<SessionInfoWire>;
+        readonly CreateUserInput: FortressSchema<CreateUserInputWire>;
+        readonly ErrorResponse: FortressSchema<ErrorResponseWire>;
+        readonly LoginIdentifier: FortressSchema<LoginIdentifierWire>;
+    };
+    readonly ref: <K extends keyof AuthComponents['components']>(name: K) => FortressSchema<AuthComponents['components'][K] extends FortressSchema<infer U> ? U : never>;
+}
+/** Reusable OpenAPI component schemas referenced by the core auth endpoints. */
+declare const authComponentSchemas: AuthComponents['components'];
+/**
+ * Typed record of every core auth endpoint. Declared explicitly (not
+ * inferred from the builder) so JSR's fast-check passes without
+ * `--allow-slow-types`, while `InferEndpointCallInput<typeof authEndpoints.login>`
+ * and friends still resolve to the precise per-endpoint shapes.
+ */
+interface AuthEndpointsMap {
+    login: EndpointDefinition<{
+        identifier: string;
+        password: string;
+        trustedDeviceToken?: string;
+    }, EmptyInput$1, EmptyInput$1, {
+        200: AuthResultWire;
+        401: ErrorResponseWire;
+    }>;
+    verifyTwoFactor: EndpointDefinition<{
+        continuationToken: string;
+        code: string;
+        rememberDevice?: boolean;
+    }, EmptyInput$1, EmptyInput$1, {
+        200: AuthResultWire;
+        400: ErrorResponseWire;
+        401: ErrorResponseWire;
+    }>;
+    verifyMagicLink: EndpointDefinition<{
+        token: string;
+    }, EmptyInput$1, EmptyInput$1, {
+        200: AuthResultWire;
+        400: ErrorResponseWire;
+        404: ErrorResponseWire;
+    }>;
+    createUser: EndpointDefinition<CreateUserInputWire, EmptyInput$1, EmptyInput$1, {
+        201: UserWire;
+        409: ErrorResponseWire;
+    }>;
+    refresh: EndpointDefinition<{
+        refreshToken: string;
+    }, EmptyInput$1, EmptyInput$1, {
+        200: AuthTokenPairWire;
+        401: ErrorResponseWire;
+    }>;
+    logout: EndpointDefinition<{
+        refreshToken: string;
+    }, EmptyInput$1, EmptyInput$1, {
+        200: OkResponseWire;
+    }>;
+    me: EndpointDefinition<EmptyInput$1, EmptyInput$1, EmptyInput$1, {
+        200: UserWire;
+        401: ErrorResponseWire;
+    }>;
+    listSessions: EndpointDefinition<EmptyInput$1, EmptyInput$1, EmptyInput$1, {
+        200: SessionInfoWire[];
+        401: ErrorResponseWire;
+    }>;
+    revokeSession: EndpointDefinition<EmptyInput$1, EmptyInput$1, {
+        id: string;
+    }, {
+        200: OkResponseWire;
+        401: ErrorResponseWire;
+    }>;
+    revokeAllOtherSessions: EndpointDefinition<{
+        currentTokenId: string;
+    }, EmptyInput$1, EmptyInput$1, {
+        200: OkResponseWire;
+        401: ErrorResponseWire;
+    }>;
+    addLoginIdentifier: EndpointDefinition<{
+        type: 'email' | 'phone' | 'username';
+        value: string;
+    }, EmptyInput$1, EmptyInput$1, {
+        200: OkResponseWire;
+        401: ErrorResponseWire;
+    }>;
+    removeLoginIdentifier: EndpointDefinition<{
+        type: 'email' | 'phone' | 'username';
+        value: string;
+    }, EmptyInput$1, EmptyInput$1, {
+        200: OkResponseWire;
+        401: ErrorResponseWire;
+    }>;
+    getLoginIdentifiers: EndpointDefinition<EmptyInput$1, EmptyInput$1, EmptyInput$1, {
+        200: LoginIdentifierWire[];
+        401: ErrorResponseWire;
+    }>;
+    impersonate: EndpointDefinition<{
+        targetUserId: string;
+        reason?: string;
+        expirySeconds?: number;
+    }, EmptyInput$1, EmptyInput$1, {
+        200: AuthResultWire;
+        401: ErrorResponseWire;
+        404: ErrorResponseWire;
+    }>;
+}
+/**
+ * Declarative endpoint definitions for fortress's built-in auth routes
+ * (sign in, refresh, sessions, impersonation).
+ *
+ * The explicit `AuthEndpointsMap` annotation is what keeps JSR fast-check
+ * happy — each entry's `EndpointDefinition<TBody, TQuery, TParams, TResponses>`
+ * generics are stated declaratively, not inferred from the builder chain.
+ * `fortress.call.*` type inference still resolves because `typeof
+ * authEndpoints.login` picks up the exact generics declared on the map.
+ */
+declare const authEndpoints: AuthEndpointsMap;
+
+/**
+ * Cookie serialization for fortress auth tokens.
+ *
+ * Produces and parses cookie strings for the access/refresh token pair using
+ * the resolved {@link ResolvedCookieConfig} (which already accounts for
+ * `__Host-` prefix rules and dev-vs-prod relaxation).
+ *
+ * Returns raw `Set-Cookie` header values so any framework adapter can append
+ * them to a `Response` directly without depending on a framework cookie API.
+ */
+
+/** Result of an auth flow that may set cookies on a Response. */
+interface AuthCookiePayload {
+    accessToken: string;
+    refreshToken?: string | null;
+}
+
+/**
+ * Shared principal resolution for `fortress.handleRequest` and user-route
+ * adapters (Hono / Express / SvelteKit).
+ *
+ * Plugins that register a `resolvePrincipal` capability (e.g. `api-key`) are
+ * tried in registration order; the first non-null result wins. If no plugin
+ * resolves the request, a JWT bearer token is attempted as a fallback.
+ *
+ * Two variants are exported:
+ *
+ * - {@link tryPluginPrincipal} — only walks the plugin chain. Used by
+ *   `handle-request.ts`, which needs to decide whether to enforce the JWT
+ *   fallback based on the endpoint's `security` metadata.
+ * - {@link resolveRequestPrincipal} — plugin chain + non-throwing JWT
+ *   fallback. Used by adapter user-route middleware so that API keys and
+ *   cookies/bearer tokens authenticate uniformly on *any* route, not just
+ *   Fortress-owned routes.
+ */
+
+/** Result of a successful principal resolution. */
+interface ResolvedPrincipal {
+    subject: Subject;
+    claims?: TokenClaims;
+    /** Credential-level narrowing scopes (e.g. API-key scopes). null/undefined = unscoped. */
+    scopes?: string[] | null;
+}
+
+/**
+ * Manifest-driven permission seeding.
+ *
+ * `endpoint().permission(resource, action)` declares the permission an
+ * endpoint needs, but a freshly migrated database has no `Permission` row
+ * for it. Every consumer used to write the same seed script: walk
+ * `fortress.endpoints`, dedupe `(resource, action)` pairs, call
+ * `iam.createPermission(...)` for each, optionally bind defaults onto a
+ * couple of well-known roles.
+ *
+ * This module replaces that script. It's idempotent (re-runs safely on a
+ * partially seeded DB) and exposed on the {@link Fortress} instance as
+ * `fortress.syncPermissionsFromManifest()`.
+ */
+
+/** Options accepted by {@link runPermissionSync}. */
+interface PermissionSyncOptions {
+    /**
+     * Endpoints to scan for `meta.permission` declarations. Defaults to the
+     * full set registered on the Fortress instance when called via
+     * {@link import('../fortress').Fortress.syncPermissionsFromManifest}.
+     */
+    endpoints?: EndpointDefinition[];
+    /**
+     * Optional role-name → permissions map. For each role:
+     *
+     * - `'*'` binds every permission discovered in `endpoints` to the role.
+     * - `['resource:action', ...]` binds only the named permissions (one
+     *   string per `(resource, action)` pair, colon-separated).
+     *
+     * Roles are created on demand; existing roles get any missing
+     * permissions added. Permissions on a role that aren't requested here
+     * are left in place \u2014 this only grants, never revokes.
+     *
+     * ```ts
+     * await fortress.syncPermissionsFromManifest({\n   *   defaultRoles: {\n   *     admin: '*',\n   *     member: ['school:read', 'school:list'],\n   *   },\n   * });\n   * ```
+     */
+    defaultRoles?: Record<string, '*' | readonly string[]>;
+}
+/** Result returned by {@link runPermissionSync}. */
+interface PermissionSyncResult {
+    /** Number of unique `(resource, action)` pairs discovered. */
+    discovered: number;
+    /**
+     * Number of permissions that already existed in the database before
+     * the sync started. (The adapter's `findOrCreatePermission` doesn't
+     * distinguish, so this is computed by counting pre-existing
+     * permissions; new inserts = `discovered - existing`.)
+     */
+    existing: number;
+    /** Number of new permission rows inserted by this sync run. */
+    created: number;
+    /**
+     * Roles touched by `defaultRoles`, keyed by role name. `bound` is the
+     * number of permission bindings newly added during this sync run.
+     * Already-bound permissions do not double-count.
+     */
+    roles: Record<string, {
+        created: boolean;
+        bound: number;
+    }>;
+}
+/**
+ * Seed permissions from a set of endpoints and (optionally) bind them onto
+ * default roles. Safe to call repeatedly. See {@link PermissionSyncOptions}
+ * for shape.
+ */
+declare function runPermissionSync(iam: IamService, endpoints: EndpointDefinition[], opts?: PermissionSyncOptions): Promise<PermissionSyncResult>;
+
+type RouteClassification = 'public' | 'authenticated' | 'rbac' | 'oauth-protocol' | 'default-deny';
+interface RouteManifestEntry {
+    method: HttpMethod;
+    path: string;
+    handler: string;
+    plugin: string | null;
+    classification: RouteClassification;
+    permission?: EndpointPermission;
+    security: SecurityRequirement[];
+    bearerKind?: 'jwt' | 'oauth';
+    csrfApplicable: boolean;
+    rateLimited: boolean;
+    mounted: boolean;
+}
+declare function buildRouteManifest(fortress: Pick<Fortress, 'endpoints' | 'config'>): RouteManifestEntry[];
+
+type MigrationDialect = 'sqlite' | 'pg';
+interface FortressMigration {
+    version: number;
+    name: string;
+    dialect: MigrationDialect;
+    up: string;
+    down: string;
+    /** SQL used only when provisioning an empty database from concatenated DDL. */
+    freshUp?: string;
+    /** Stable identity included in the migration checksum for a JS data step. */
+    dataStep?: string;
+    /** Runs immediately before `up` while the migration lock/transaction is held. */
+    beforeUp?: (db: DatabaseAdapter) => Promise<void>;
+}
+declare const fortressMigrations: Record<MigrationDialect, FortressMigration[]>;
+declare function getFortressMigrations(dialect: MigrationDialect): FortressMigration[];
+declare function getLatestMigrationVersion(dialect: MigrationDialect): number;
+/**
+ * Concatenated forward SQL for every bundled migration of a dialect, in
+ * version order. `src/testing/index.ts` provisions its in-memory schema
+ * from this so the test adapter and production migrations can never drift.
+ */
+declare function getMigrationUpSql(dialect: MigrationDialect): string;
+/**
+ * Canonical list of every Fortress-owned table. Used by
+ * {@link detectMigrationDrift} to surface live-DB drift beyond just the
+ * `fortress_schema_version` checkpoint — any of these tables missing in
+ * the target database signals an incomplete or stale migration state.
+ *
+ * Keep in sync with `src/drizzle/{schema,pg/schema}.ts` and the bundled
+ * migrations. The list is asserted by `src/core/migrations/engine.test.ts`
+ * against the test adapter so an accidental drop/add is caught at test time.
+ */
+declare const FORTRESS_TABLES: readonly string[];
+/**
+ * Parse the expected column set of every Fortress table directly out of the
+ * bundled migration DDL. Because the migrations are the SQL-first source of
+ * truth, this needs no schema description maintained on the side and no
+ * Drizzle-specific tooling — it works for any adapter. Powers the
+ * column-level half of {@link detectMigrationDrift}.
+ *
+ * The parser is intentionally narrow: it understands the controlled DDL
+ * Fortress emits (`CREATE TABLE [IF NOT EXISTS] name ( ... );` with
+ * comma-separated definitions, plus the controlled `ALTER TABLE` add-column
+ * and rename forms used by incremental migrations). Constraint-only lines
+ * (PRIMARY KEY (...), UNIQUE (...), etc.) and
+ * standalone CREATE INDEX statements are skipped.
+ */
+declare function getExpectedColumns(dialect: MigrationDialect): Record<string, string[]>;
+
+interface MigrationStatus {
+    dialect: MigrationDialect;
+    currentVersion: number;
+    latestVersion: number;
+    pending: FortressMigration[];
+    applied: FortressMigration[];
+    upToDate: boolean;
+    hasVersionTable: boolean;
+}
+interface MigrationApplyResult {
+    dialect: MigrationDialect;
+    fromVersion: number;
+    toVersion: number;
+    applied: FortressMigration[];
+}
+interface MigrationDownResult {
+    dialect: MigrationDialect;
+    fromVersion: number;
+    toVersion: number;
+    rolledBack: FortressMigration[];
+}
+interface MigrationDrift {
+    dialect: MigrationDialect;
+    currentVersion: number;
+    latestVersion: number;
+    missingVersionTable: boolean;
+    unknownFutureVersion: boolean;
+    pendingVersions: number[];
+    /**
+     * Fortress-owned tables expected by the runtime but missing from the
+     * live database. A non-empty list almost always means an upgrade was
+     * skipped or the database was provisioned from an out-of-date schema
+     * dump. Compared against {@link FORTRESS_TABLES}.
+     */
+    missingTables: string[];
+    /**
+     * Per-table columns that the bundled migration DDL defines but the live
+     * database is missing. Surfaces a partially-applied or hand-patched
+     * schema where the table exists but is missing a column added by a later
+     * migration. Expected columns are parsed from the migration SQL itself
+     * (see `getExpectedColumns`), so this works for any adapter. Only tables
+     * that are present in the live DB are inspected — fully missing tables are
+     * reported via {@link missingTables} instead.
+     */
+    missingColumns: {
+        table: string;
+        columns: string[];
+    }[];
+    /** Required hot-path indexes absent from the live database. */
+    missingIndexes: string[];
+}
+declare function getMigrationStatus(db: DatabaseAdapter, dialect?: MigrationDialect): Promise<MigrationStatus>;
+declare function migrateUp(db: DatabaseAdapter, dialect?: MigrationDialect, targetVersion?: number): Promise<MigrationApplyResult>;
+declare function migrateDown(db: DatabaseAdapter, dialect?: MigrationDialect, targetVersion?: number): Promise<MigrationDownResult>;
+declare function detectMigrationDrift(db: DatabaseAdapter, dialect?: MigrationDialect): Promise<MigrationDrift>;
+declare function hasMigrationDrift(drift: MigrationDrift): boolean;
+
+/** Options accepted by {@link toOpenAPI}. */
+interface ToOpenAPIOptions extends Partial<SpecBuilderOptions> {
+    /** Additional reusable schemas to place under `components.schemas`. */
+    schemas?: ComponentSchemas;
+}
+/**
+ * Emit an OpenAPI 3.1 spec from a set of Fortress endpoint definitions.
+ *
+ * This is the env/DB-free helper for build scripts and codegen pipelines.
+ * If you already have a configured Fortress instance, prefer
+ * `fortress.toOpenAPI()` so the endpoint list defaults to everything that
+ * instance knows about.
+ *
+ * ```ts
+ * import { toOpenAPI } from '@bajustone/fortress';
+ * import { appEndpointList } from './routes/v1/endpoints';
+ *
+ * export const OPENAPI_SPEC = toOpenAPI(appEndpointList, {
+ *   title: 'My API',
+ *   version: '0.0.0',
+ *   servers: [{ url: 'http://localhost:3001' }],
+ *   tags: [{ name: 'Schools' }],
+ * });
+ * ```
+ *
+ * Defaults to endpoint `handler` values for `operationId`, matching host
+ * route-contract names. Pass `operationId: 'methodPath'` for Fortress's
+ * historical generated IDs.
+ */
+declare function toOpenAPI(endpoints: readonly EndpointDefinition[], opts?: ToOpenAPIOptions): OpenAPISpec;
+
+/**
+ * Typed in-process client for fortress endpoints.
+ *
+ * `buildCall` takes a flat map of `EndpointDefinition`s (keyed by handler
+ * name) and returns an object with one callable per entry. Each callable:
+ *
+ * 1. Splits the flat input object into `body`, `query`, and `params` based
+ *    on the endpoint's declared schemas.
+ * 2. Substitutes `:param` placeholders in the path.
+ * 3. Serializes the query string.
+ * 4. Builds a web-standard `Request` with a JSON body (when applicable).
+ * 5. Delegates to `fortress.handleRequest`, exercising the full pipeline
+ *    (plugin middleware → token verification → RBAC → validation →
+ *    dispatch → cookie attachment).
+ * 6. Parses the JSON response body. On non-2xx, throws a structured
+ *    `FortressError` reconstructed via `Errors.fromHttpResponse`.
+ *
+ * This is the foundation of the typed client SDK: the same code works
+ * in-process today and will work over the network tomorrow by swapping
+ * `handleRequest` for `fetch`. All of the type machinery lives on the
+ * `EndpointDefinition` generic parameters and the `InferEndpoint*` helpers
+ * in `src/core/endpoint.ts`.
+ *
+ * **Authentication.** Protected endpoints expect a bearer token. Callers
+ * pass it via the optional second argument: `call.me({}, { headers:
+ * { authorization: 'Bearer …' } })`. The in-process client does not share
+ * state with any active session; it is purely a typed wire formatter.
+ *
+ * **Runs the full pipeline.** Because each call lands in
+ * `fortress.handleRequest`, the following all fire: plugin middleware (incl.
+ * rate limits), principal resolution, RBAC, JSON Schema / Standard Schema
+ * validation, auth observers, IAM observers, OpenTelemetry spans, and any
+ * `wrapAdapter` hooks. This is intentional — it's the same code path a
+ * network client would hit, so tests that exercise `fortress.call.*` give
+ * the same behavioral guarantees as production traffic.
+ *
+ * **Bypassing hooks in tests.** If a test fixture needs to create users or
+ * log in *without* tripping rate limits, emitting audit entries, or running
+ * observers, call the service layer directly — `fortress.auth.createUser`,
+ * `fortress.auth.login`, `fortress.iam.createRole` — instead of the typed
+ * call surface. The service layer still validates inputs but skips the
+ * middleware chain.
+ */
+
+/** Optional per-call options. */
+interface CallOptions {
+    /** Extra headers to attach to the synthesized request (e.g. bearer auth). */
+    headers?: Record<string, string>;
+}
+/**
+ * Build an object of typed callables from a keyed {@link EndpointDefinition}
+ * map. Each callable invokes `fortress.handleRequest` with a synthesized
+ * `Request` and returns the parsed JSON body on success.
+ *
+ * The returned type is intentionally loose (`Record<string, ...>`). The
+ * strong typing happens at the call site via the `TypedCall` helper in
+ * `src/core/fortress.ts`, which layers a mapped type over the runtime
+ * callable map to expose per-handler inferred I/O.
+ */
+declare function buildCall(fortress: Fortress, endpoints: Record<string, EndpointDefinition>): Record<string, (input?: Record<string, unknown>, options?: CallOptions) => Promise<unknown>>;
+
+/**
+ * Type-level map of every built-in plugin name to its method-surface
+ * interface. {@link InferPlugins} uses this to expose typed plugin methods
+ * on the fortress instance.
+ */
+interface PluginMethodsMap {
+    'api-key': ApiKeyMethods;
+    'audit-log': AuditLogMethods;
+    'data-isolation': DataIsolationMethods;
+    'email-verification': EmailVerificationMethods;
+    'magic-link': MagicLinkMethods;
+    'oauth': OAuthMethods;
+    'openapi': OpenAPIMethods;
+    'social-login': SocialLoginMethods;
+    'tenancy': TenancyMethods;
+    'two-factor': TwoFactorMethods;
+    'webauthn': WebAuthnMethods;
+}
+/** Infer the typed plugin-methods record from a `plugins` tuple passed to {@link createFortress}. */
+type InferPlugins<T extends readonly FortressPlugin[]> = {
+    [P in T[number] as P['name']]: P['name'] extends keyof PluginMethodsMap ? PluginMethodsMap[P['name']] : Record<string, (...args: any[]) => any>;
+};
+/** Distributes a union into an intersection — the classic TS trick. Used by {@link InferPluginCallMap}. */
+type UnionToIntersection<U> = (U extends any ? (x: U) => void : never) extends ((x: infer I) => void) ? I : never;
+/**
+ * Turn a record of {@link EndpointDefinition}s into a record of typed
+ * callables: each key becomes a function whose input is the endpoint's
+ * inferred body+query+params intersection and whose output is the inferred
+ * success-response body.
+ */
+type CallableForEndpoints<E> = E extends Record<string, EndpointDefinition<any, any, any, any>> ? {
+    [K in keyof E]: (input: InferEndpointCallInput<E[K]>, options?: CallOptions) => Promise<InferEndpointSuccessResponse<E[K]>>;
+} : Record<string, never>;
+/**
+ * Infer the typed call surface contributed by a plugins tuple. Walks every
+ * plugin's `routes` record (if present) and unions the callables into one
+ * flat object keyed by handler name.
+ */
+type InferPluginCallMap<T extends readonly FortressPlugin[]> = UnionToIntersection<T[number] extends infer P ? P extends {
+    routes?: infer R;
+} ? R extends Record<string, EndpointDefinition<any, any, any, any>> ? CallableForEndpoints<R> : Record<string, never> : Record<string, never> : Record<string, never>>;
+
+interface EmptyInput {
+}
+/** Wire shape of a persisted role. `description` and `isSystem` are optional nullable on the wire. */
+interface RoleWire {
+    id: string;
+    name: string;
+    description?: string | null;
+    isSystem?: boolean;
+}
+/** Wire shape of a persisted group. */
+interface GroupWire {
+    id: string;
+    name: string;
+    description?: string | null;
+}
+/** Wire shape of a permission condition. `operator` is restricted to the supported set. */
+interface PermissionConditionWire {
+    field: string;
+    operator: 'eq' | 'neq' | 'in' | 'startsWith';
+    value: string;
+}
+/** Wire shape of a persisted permission. */
+interface PermissionWire {
+    id: string;
+    resource: string;
+    action: string;
+    effect: 'ALLOW' | 'DENY';
+    conditions?: PermissionConditionWire[];
+    description?: string | null;
+}
+/** Wire shape of a permission-creation input. */
+interface PermissionInputWire {
+    resource: string;
+    action: string;
+    effect?: 'ALLOW' | 'DENY';
+    conditions?: PermissionConditionWire[];
+}
+/** Wire shape of a persisted service account. Date fields are ISO strings on the wire. */
+interface ServiceAccountWire {
+    id: string;
+    name: string;
+    displayName?: string | null;
+    description?: string | null;
+    isActive: boolean;
+    createdAt?: string;
+    updatedAt?: string;
+}
+/** Explicit registry type so JSR's fast-check doesn't walk into the deeply-inferred `defineComponents` return. */
+interface IamComponents {
+    readonly components: {
+        readonly Role: FortressSchema<RoleWire>;
+        readonly Group: FortressSchema<GroupWire>;
+        readonly Permission: FortressSchema<PermissionWire>;
+        readonly PermissionInput: FortressSchema<PermissionInputWire>;
+        readonly ServiceAccount: FortressSchema<ServiceAccountWire>;
+    };
+    readonly ref: <K extends keyof IamComponents['components']>(name: K) => FortressSchema<IamComponents['components'][K] extends FortressSchema<infer U> ? U : never>;
+}
+/** Reusable OpenAPI component schemas referenced by the core IAM endpoints. */
+declare const iamComponentSchemas: IamComponents['components'];
+/** Resource catalog response shape. */
+interface ResourceCatalogWire {
+    resources: Record<string, {
+        actions: string[];
+        description?: string;
+    }>;
+}
+/** Paged service-account list response shape. */
+interface ServiceAccountsListWire {
+    serviceAccounts: ServiceAccountWire[];
+    total: number;
+}
+/**
+ * Typed record of every core IAM endpoint. Declared explicitly so JSR's
+ * fast-check passes without `--allow-slow-types`, while
+ * `InferEndpointCallInput<typeof iamEndpoints.X>` still resolves per-handler.
+ */
+interface IamEndpointsMap {
+    getResources: EndpointDefinition<EmptyInput, EmptyInput, EmptyInput, {
+        200: ResourceCatalogWire;
+        401: ErrorResponseWire;
+    }>;
+    getRoles: EndpointDefinition<EmptyInput, EmptyInput, EmptyInput, {
+        200: RoleWire[];
+        401: ErrorResponseWire;
+    }>;
+    createRole: EndpointDefinition<{
+        name: string;
+        permissions: PermissionInputWire[];
+        description?: string;
+    }, EmptyInput, EmptyInput, {
+        201: RoleWire;
+        401: ErrorResponseWire;
+    }>;
+    deleteRole: EndpointDefinition<EmptyInput, EmptyInput, {
+        id: string;
+    }, {
+        200: OkResponseWire;
+        400: ErrorResponseWire;
+        401: ErrorResponseWire;
+    }>;
+    bindRoleToUser: EndpointDefinition<{
+        userId: string;
+        tenantId?: string;
+    }, EmptyInput, {
+        id: string;
+    }, {
+        200: OkResponseWire;
+        401: ErrorResponseWire;
+    }>;
+    bindRoleToGroup: EndpointDefinition<{
+        groupId: string;
+        tenantId?: string;
+    }, EmptyInput, {
+        id: string;
+    }, {
+        200: OkResponseWire;
+        401: ErrorResponseWire;
+    }>;
+    unbindRole: EndpointDefinition<{
+        subjectType: 'USER' | 'GROUP' | 'SERVICE_ACCOUNT';
+        subjectId: string;
+        tenantId?: string;
+    }, EmptyInput, {
+        id: string;
+    }, {
+        200: OkResponseWire;
+        401: ErrorResponseWire;
+    }>;
+    createGroup: EndpointDefinition<{
+        name: string;
+        description?: string;
+    }, EmptyInput, EmptyInput, {
+        201: GroupWire;
+        401: ErrorResponseWire;
+    }>;
+    addUserToGroup: EndpointDefinition<{
+        userId: string;
+    }, EmptyInput, {
+        id: string;
+    }, {
+        200: OkResponseWire;
+        401: ErrorResponseWire;
+    }>;
+    removeUserFromGroup: EndpointDefinition<EmptyInput, EmptyInput, {
+        id: string;
+        userId: string;
+    }, {
+        200: OkResponseWire;
+        401: ErrorResponseWire;
+    }>;
+    getUserPermissions: EndpointDefinition<EmptyInput, {
+        tenantId?: string;
+    }, {
+        id: string;
+    }, {
+        200: PermissionWire[];
+        401: ErrorResponseWire;
+    }>;
+    checkPermission: EndpointDefinition<{
+        userId: string;
+        resource: string;
+        action: string;
+        context?: Record<string, unknown>;
+    }, EmptyInput, EmptyInput, {
+        200: {
+            allowed: boolean;
+        };
+        401: ErrorResponseWire;
+    }>;
+    bindPermissionToUser: EndpointDefinition<{
+        userId: string;
+        permission: PermissionInputWire;
+        tenantId?: string;
+    }, EmptyInput, EmptyInput, {
+        200: OkResponseWire;
+        401: ErrorResponseWire;
+    }>;
+    bindPermissionToGroup: EndpointDefinition<{
+        groupId: string;
+        permission: PermissionInputWire;
+        tenantId?: string;
+    }, EmptyInput, EmptyInput, {
+        200: OkResponseWire;
+        401: ErrorResponseWire;
+    }>;
+    unbindPermissionFromUser: EndpointDefinition<{
+        userId: string;
+        permissionId: string;
+        tenantId?: string;
+    }, EmptyInput, EmptyInput, {
+        200: OkResponseWire;
+        401: ErrorResponseWire;
+    }>;
+    unbindPermissionFromGroup: EndpointDefinition<{
+        groupId: string;
+        permissionId: string;
+        tenantId?: string;
+    }, EmptyInput, EmptyInput, {
+        200: OkResponseWire;
+        401: ErrorResponseWire;
+    }>;
+    createServiceAccount: EndpointDefinition<{
+        name: string;
+        displayName?: string;
+        description?: string;
+    }, EmptyInput, EmptyInput, {
+        201: ServiceAccountWire;
+        400: ErrorResponseWire;
+        401: ErrorResponseWire;
+    }>;
+    listServiceAccounts: EndpointDefinition<EmptyInput, {
+        limit?: number;
+        offset?: number;
+    }, EmptyInput, {
+        200: ServiceAccountsListWire;
+        401: ErrorResponseWire;
+    }>;
+    getServiceAccount: EndpointDefinition<EmptyInput, EmptyInput, {
+        id: string;
+    }, {
+        200: ServiceAccountWire;
+        401: ErrorResponseWire;
+        404: ErrorResponseWire;
+    }>;
+    updateServiceAccount: EndpointDefinition<{
+        displayName?: string | null;
+        description?: string | null;
+        isActive?: boolean;
+    }, EmptyInput, {
+        id: string;
+    }, {
+        200: ServiceAccountWire;
+        401: ErrorResponseWire;
+        404: ErrorResponseWire;
+    }>;
+    deleteServiceAccount: EndpointDefinition<EmptyInput, EmptyInput, {
+        id: string;
+    }, {
+        200: OkResponseWire;
+        401: ErrorResponseWire;
+        404: ErrorResponseWire;
+    }>;
+    getServiceAccountPermissions: EndpointDefinition<EmptyInput, {
+        tenantId?: string;
+    }, {
+        id: string;
+    }, {
+        200: PermissionWire[];
+        401: ErrorResponseWire;
+    }>;
+    bindRoleToServiceAccount: EndpointDefinition<{
+        serviceAccountId: string;
+        tenantId?: string;
+    }, EmptyInput, {
+        id: string;
+    }, {
+        200: OkResponseWire;
+        401: ErrorResponseWire;
+    }>;
+    unbindRoleFromServiceAccount: EndpointDefinition<{
+        serviceAccountId: string;
+        tenantId?: string;
+    }, EmptyInput, {
+        id: string;
+    }, {
+        200: OkResponseWire;
+        401: ErrorResponseWire;
+    }>;
+    bindPermissionToServiceAccount: EndpointDefinition<{
+        serviceAccountId: string;
+        permission: PermissionInputWire;
+        tenantId?: string;
+    }, EmptyInput, EmptyInput, {
+        200: OkResponseWire;
+        401: ErrorResponseWire;
+    }>;
+    unbindPermissionFromServiceAccount: EndpointDefinition<{
+        serviceAccountId: string;
+        permissionId: string;
+        tenantId?: string;
+    }, EmptyInput, EmptyInput, {
+        200: OkResponseWire;
+        401: ErrorResponseWire;
+    }>;
+}
+/**
+ * Declarative endpoint definitions for fortress's built-in IAM admin routes.
+ * The explicit `IamEndpointsMap` annotation keeps JSR fast-check happy
+ * without sacrificing per-handler inference for `fortress.call.*`.
+ */
+declare const iamEndpoints: IamEndpointsMap;
+
+/**
+ * Typed in-process call surface. Composes auth + IAM endpoint callables
+ * with any plugin-contributed routes (derived from the plugins tuple).
+ *
+ * Each handler becomes a `(input, options?) => Promise<successBody>` where
+ * the input shape is the inferred intersection of the endpoint's body,
+ * query, and params schemas, and the output is the inferred 2xx response
+ * type. Non-2xx responses throw a `FortressError`.
+ */
+type TypedCall<T extends readonly FortressPlugin[]> = CallableForEndpoints<typeof authEndpoints> & CallableForEndpoints<typeof iamEndpoints> & InferPluginCallMap<T>;
+/**
+ * Configured fortress instance returned by {@link createFortress}. Holds the
+ * core auth and IAM services, the resolved config, every endpoint definition
+ * (auth + IAM + plugin routes), and the typed plugin method surface.
+ *
+ * Also exposes the framework-agnostic HTTP entry points
+ * ({@link Fortress.handleRequest}, {@link Fortress.runPluginMiddleware},
+ * {@link Fortress.extractAccessToken}, {@link Fortress.serializeAuthCookies})
+ * that adapters delegate to. See `src/core/http/`.
+ */
+interface Fortress<TPlugins = Record<string, Record<string, Function>>, TCall = Record<string, (input?: any, options?: any) => Promise<any>>> {
+    auth: AuthService;
+    iam: IamService;
+    plugins: TPlugins;
+    /**
+     * Typed in-process client. Each key is a handler name (from the core
+     * auth/IAM endpoint records or a plugin's `routes` record); each value is
+     * an async function whose input/output types are inferred from the
+     * endpoint's declared body/query/params/response schemas.
+     *
+     * Under the hood, each callable serializes its input to a `Request` and
+     * delegates to `fortress.handleRequest`, so middleware, token
+     * verification, RBAC, and validation all run — the same path a network
+     * client would eventually hit. See `src/core/http/call.ts`.
+     */
+    call: TCall;
+    config: Readonly<FortressConfig>;
+    /** All endpoint definitions (auth + IAM + plugins) with JSON Schema metadata. */
+    endpoints: EndpointDefinition[];
+    /** Canonical generated route-security manifest derived from endpoint metadata. */
+    manifest: RouteManifestEntry[];
+    /** Resolved auth-cookie names and attributes (NODE_ENV-aware). */
+    cookies: ResolvedCookieConfig;
+    /** Resolved logger (defaults to a silent no-op when `config.logger` is unset). */
+    logger: FortressLogger;
+    /** Resolved telemetry provider (defaults to a no-op when `config.observability` is unset). */
+    telemetry: TelemetryProvider;
+    /**
+     * Handle a Fortress-managed request and return a web-standard `Response`.
+     * Composes plugin middleware, token verification, default-deny RBAC,
+     * validation, and dispatch.
+     *
+     * Adapters call this for paths owned by Fortress (e.g. `/auth/*`,
+     * `/iam/*`, plugin-registered routes). See `src/core/http/handle-request.ts`.
+     */
+    handleRequest: (request: Request) => Promise<Response>;
+    /**
+     * Run plugin middleware at a given lifecycle phase, passing a duck-typed
+     * request context. Adapters call this on user-owned routes so plugins
+     * like rate-limit and audit-log still apply outside Fortress paths.
+     */
+    runPluginMiddleware: (phase: MiddlewareDefinition['position'], ctx: PluginRequestContext) => Promise<void>;
+    /**
+     * Extract the access token from a request, preferring the configured
+     * cookie and falling back to `Authorization: Bearer`.
+     */
+    extractAccessToken: (request: Request) => string | null;
+    /**
+     * Resolve the request principal by trying plugin `resolvePrincipal`
+     * hooks (e.g. `api-key`) first, then falling back to the configured JWT
+     * bearer token. Non-throwing — returns `null` when no credential is
+     * present or the JWT fails to verify.
+     *
+     * Adapter user-route middleware calls this so api-keys, cookies, and
+     * bearer tokens authenticate uniformly on user-owned routes — not just
+     * Fortress-owned routes dispatched through `handleRequest`.
+     */
+    resolvePrincipal: (request: Request) => Promise<ResolvedPrincipal | null>;
+    /**
+     * Serialize an auth result (or pair of tokens) into one or two
+     * `Set-Cookie` header values using the resolved cookie config and the
+     * configured token expiries.
+     */
+    serializeAuthCookies: (payload: AuthCookiePayload) => string[];
+    /**
+     * Run Fortress's pending schema migrations against the configured database
+     * and, optionally, an application-supplied migration step afterwards.
+     *
+     * Fortress migrations always run first because app schemas commonly
+     * reference fortress tables (foreign keys to `user.id`, etc.). The
+     * `migrateApp` callback (when provided) is awaited after Fortress
+     * migrations complete, so a host can do something like:
+     *
+     * ```ts
+     * await fortress.migrate({
+     *   migrateApp: () => migrate(db, { migrationsFolder: './drizzle' }),
+     * });
+     * ```
+     *
+     * Eliminates the two-step "forget to call `migrateUp` and silently
+     * have no auth tables" footgun.
+     */
+    migrate: (opts?: MigrateOptions) => Promise<MigrateResult>;
+    /**
+     * Seed permissions discovered on registered endpoints (`fortress.endpoints`)
+     * into the IAM database and, optionally, bind them onto a set of default
+     * roles. Idempotent — re-running adds only what's missing and never
+     * revokes anything that was already there.
+     *
+     * Typical bootstrap sequence:
+     *
+     * ```ts
+     * await fortress.migrate({ migrateApp: () => migrate(db, '...') });
+     * await fortress.syncPermissionsFromManifest({
+     *   defaultRoles: { admin: '*', member: ['school:read', 'school:list'] },
+     * });
+     * ```
+     *
+     * Replaces the seed script every consumer used to write that walked
+     * `fortress.endpoints`, deduped `(resource, action)` pairs, and called
+     * `iam.createPermission(...)` for each.
+     */
+    syncPermissionsFromManifest: (opts?: PermissionSyncOptions) => Promise<PermissionSyncResult>;
+    /**
+     * Emit a complete OpenAPI 3.1 spec from the endpoint definitions Fortress
+     * knows about: core auth/IAM routes, plugin routes, and any top-level
+     * host `routes` registered on {@link FortressConfig}.
+     *
+     * This is the programmatic companion to the OpenAPI plugin. Use it when
+     * you already own the docs route or when a build script needs to write
+     * `openapi.json` for client codegen:
+     *
+     * ```ts
+     * const spec = fortress.toOpenAPI({
+     *   title: 'My API',
+     *   version: '0.0.0',
+     *   servers: [{ url: 'http://localhost:3001', description: 'Local' }],
+     *   tags: [{ name: 'Schools' }],
+     * });
+     * ```
+     *
+     * Defaults to endpoint `handler` names for `operationId`, matching most
+     * host route-contract files. Pass `operationId: 'methodPath'` to keep the
+     * historical OpenAPI-plugin ID style.
+     */
+    toOpenAPI: (opts?: FortressToOpenAPIOptions) => OpenAPISpec;
+}
+/** Options accepted by {@link Fortress.toOpenAPI}. */
+interface FortressToOpenAPIOptions extends ToOpenAPIOptions {
+    /** Override the endpoints to emit. Defaults to `fortress.endpoints`. */
+    endpoints?: EndpointDefinition[];
+}
+/** Options accepted by {@link Fortress.migrate}. */
+interface MigrateOptions {
+    /**
+     * Optional host-app migration step. Runs after Fortress migrations
+     * complete; any thrown error propagates after Fortress migrations have
+     * already been applied. Library-agnostic: pass any `() => Promise<void>`
+     * — e.g. drizzle's `migrate(db, { migrationsFolder })`, Knex's
+     * `db.migrate.latest()`, a hand-rolled SQL runner.
+     */
+    migrateApp?: () => Promise<void>;
+    /**
+     * Override the migration dialect. Defaults to the adapter's `dialect`
+     * property (matches the behavior of {@link migrateUp}).
+     */
+    dialect?: 'sqlite' | 'pg';
+    /** Stop applying Fortress migrations after this version. Defaults to the latest. */
+    targetVersion?: number;
+}
+/** Result returned by {@link Fortress.migrate}. */
+interface MigrateResult {
+    /** Result of the Fortress-managed migration step. */
+    fortress: MigrationApplyResult;
+    /** `true` if `migrateApp` was supplied and ran to completion. */
+    appRan: boolean;
+}
+/**
+ * Type-safe helper to retrieve a plugin's methods from a Fortress instance.
+ *
+ * Since plugin methods are dynamically typed at runtime, this helper lets
+ * consumers provide a known interface for type-safe access without casting.
+ *
+ * @example
+ * ```ts
+ * interface TwoFactorMethods {
+ *   setup: (userId: string) => Promise<{ secret: string; qrCode: string }>;
+ *   verify: (userId: string, code: string) => Promise<boolean>;
+ * }
+ *
+ * const twoFactor = getPluginMethods<TwoFactorMethods>(fortress, 'two-factor');
+ * const result = await twoFactor.setup(userId); // fully typed
+ * ```
+ */
+declare function getPluginMethods<T>(fortress: Fortress, pluginName: string): T;
+/**
+ * Build a configured {@link Fortress} instance from a {@link FortressConfig}.
+ *
+ * Validates the JWT secret strength, deduplicates and processes the plugin
+ * list, wires up auth/IAM services, and returns the assembled instance with
+ * type-safe plugin method access for any plugins listed in the config.
+ */
+declare function createFortress<const T extends readonly FortressPlugin[]>(config: FortressConfig & {
+    plugins?: T;
+}): Fortress<InferPlugins<T>, TypedCall<T>>;
+
+export { type AuthChallengeWire as A, getExpectedColumns as B, type CallOptions as C, getFortressMigrations as D, getLatestMigrationVersion as E, type Fortress as F, getMigrationStatus as G, getMigrationUpSql as H, type InferPluginCallMap as I, getPluginMethods as J, hasMigrationDrift as K, iamComponentSchemas as L, type MigrationDialect as M, iamEndpoints as N, migrateDown as O, type PermissionSyncOptions as P, migrateUp as Q, type RouteManifestEntry as R, runPermissionSync as S, type ToOpenAPIOptions as T, toOpenAPI as U, type AuthCookiePayload as V, type RouteClassification as a, type MigrationDrift as b, type AuthImpersonationWire as c, type AuthPendingWire as d, type AuthResultWire as e, type AuthSuccessWire as f, type CallableForEndpoints as g, FORTRESS_TABLES as h, type FortressMigration as i, type FortressToOpenAPIOptions as j, type InferPlugins as k, type MigrateOptions as l, type MigrateResult as m, type MigrationApplyResult as n, type MigrationDownResult as o, type MigrationStatus as p, type PermissionSyncResult as q, type PluginMethodsMap as r, type TypedCall as s, authComponentSchemas as t, authEndpoints as u, buildCall as v, buildRouteManifest as w, createFortress as x, detectMigrationDrift as y, fortressMigrations as z };