@bajustone/fortress 1.0.0-rc.1

package/dist/index.d.ts

@@ -0,0 +1,717 @@
+import { D as DatabaseAdapter } from './index-CxEkfCA0.js';
+export { C as CoreOperator, S as ScopeRule, W as WhereClause } from './index-CxEkfCA0.js';
+export { A as AuthChallengeWire, c as AuthImpersonationWire, d as AuthPendingWire, e as AuthResultWire, f as AuthSuccessWire, C as CallOptions, g as CallableForEndpoints, h as FORTRESS_TABLES, F as Fortress, i as FortressMigration, j as FortressToOpenAPIOptions, I as InferPluginCallMap, k as InferPlugins, l as MigrateOptions, m as MigrateResult, n as MigrationApplyResult, M as MigrationDialect, o as MigrationDownResult, b as MigrationDrift, p as MigrationStatus, P as PermissionSyncOptions, q as PermissionSyncResult, r as PluginMethodsMap, a as RouteClassification, R as RouteManifestEntry, T as ToOpenAPIOptions, s as TypedCall, t as authComponentSchemas, u as authEndpoints, v as buildCall, w as buildRouteManifest, x as createFortress, y as detectMigrationDrift, z as fortressMigrations, B as getExpectedColumns, D as getFortressMigrations, E as getLatestMigrationVersion, G as getMigrationStatus, H as getMigrationUpSql, J as getPluginMethods, K as hasMigrationDrift, L as iamComponentSchemas, N as iamEndpoints, O as migrateDown, Q as migrateUp, S as runPermissionSync, U as toOpenAPI } from './fortress-uA-_cheR.js';
+import { g as IamService } from './auth-service-BkzZkWfH.js';
+export { A as AttributeValue, a as Attributes, b as AuthEvent, c as AuthEventListener, C as Counter, F as FortressLogger, H as Histogram, I as IamEvent, d as IamEventListener, M as Meter, P as PermissionCheckEvent, e as PermissionCheckListener, R as ResourceDefinition, h as ResourceFile, S as Span, T as TelemetryProvider, f as Tracer, U as Unsubscribe, p as parseResourceFile } from './auth-service-BkzZkWfH.js';
+export { JwtKeyMaterial } from './jwt.js';
+import { H as HttpMethod, g as SecurityRequirement, S as StandardSchemaV1, h as FortressSchema, E as EndpointDefinition, i as Infer, J as JSONSchema, j as Simplify, k as EndpointInput } from './config-B2366s_G.js';
+export { A as AfterHookContext, C as ComponentSchemas, l as EndpointMeta, m as EndpointResponse, n as FieldDefinition, o as FortressConfig, F as FortressPlugin, p as HookContext, q as HookResult, b as InferEndpointBody, c as InferEndpointCallInput, I as InferEndpointParams, a as InferEndpointQuery, d as InferEndpointResponses, r as InferEndpointSuccessResponse, M as MiddlewareDefinition, s as ModelConstraint, t as ModelDefinition, u as PasswordBreachCheckOptions, v as PasswordBreachDegradedEvent, w as PasswordBreachFailureMode, P as PasswordHasher, x as PasswordPolicyConfig, y as PasswordPolicyObserver, e as PluginContext, z as PluginHooks, B as PluginRequestContext, D as PostAuthGateContext, G as PostAuthGateDecision, K as PostAuthGateProvider, L as PostAuthGateVerificationContext, N as SessionConfig } from './config-B2366s_G.js';
+export { a as ProtectOptions, P as ProtectedRouteContext, c as ProtectedRouteHandler, b as ProtectedRouteTarget, d as describeProtectedTarget, p as protect, r as resolveProtectedEndpoint } from './protect-DsxV_-dJ.js';
+import { S as Subject, b as Permission, P as PermissionContext } from './types-et0R8tsC.js';
+export { m as AuthChallenge, n as AuthImpersonation, g as AuthMethod, o as AuthPending, A as AuthResult, p as AuthSuccess, h as AuthTokenPair, q as ConditionRef, r as ConditionValue, i as CreateUserInput, F as FortressUser, G as Group, k as LoginIdentifier, L as LoginIdentifierType, l as PendingReason, s as PermissionCondition, c as PermissionInput, R as RequestMeta, d as Role, e as RoleBinding, a as SubjectType, T as TokenClaims, t as assertSuccess, u as isImpersonation, v as isPending, w as isSuccess } from './types-et0R8tsC.js';
+export { D as DetectRouteManifestDriftOptions, R as RouteManifestDrift, d as detectRouteManifestDrift, h as hasRouteManifestDrift } from './drift-k9LiYpRP.js';
+export { ApiKeyMethods } from './plugins/api-key.js';
+export { AuditLogMethods } from './plugins/audit-log.js';
+export { DataIsolationMethods } from './plugins/data-isolation.js';
+export { EmailVerificationMethods } from './plugins/email-verification.js';
+export { MagicLinkMethods } from './plugins/magic-link.js';
+export { AuthorizeRequestParams, ClientAuth, OAuthMethods, PendingFlowRecord, TokenRequestBody } from './plugins/oauth.js';
+export { O as OpenAPISpec, S as SpecBuilderOptions } from './index-jAMbbUAY.js';
+export { SocialLoginMethods } from './plugins/social-login.js';
+export { TenancyMethods } from './plugins/tenancy.js';
+export { TwoFactorMethods } from './plugins/two-factor.js';
+export { WebAuthnMethods } from './plugins/webauthn.js';
+import '@simplewebauthn/server';
+
+/** Discriminated string union of every error code fortress can throw. Maps 1:1 to an HTTP status. */
+type FortressErrorCode = 'UNAUTHORIZED' | 'TOKEN_REUSE' | 'SESSION_IDLE_TIMEOUT' | 'SESSION_ABSOLUTE_TIMEOUT' | 'FORBIDDEN' | 'BAD_REQUEST' | 'NOT_FOUND' | 'CONFLICT' | 'UNPROCESSABLE_ENTITY' | 'RATE_LIMITED' | 'DATABASE_ERROR' | 'VALIDATION_ERROR' | 'SERVICE_UNAVAILABLE';
+/**
+ * Machine-readable error codes defined by RFC 6749 §5.2 (token endpoint) and
+ * §4.1.2.1 (authorization endpoint). The OAuth plugin uses these as the
+ * `error` field in token-endpoint failure responses; the HTTP error mapper
+ * detects {@link FortressError.oauthError} and emits the
+ * `{ error, error_description }` shape required by the spec.
+ */
+type OAuthErrorCode = 'invalid_request' | 'invalid_client' | 'invalid_grant' | 'unauthorized_client' | 'unsupported_grant_type' | 'invalid_scope' | 'access_denied' | 'unsupported_response_type' | 'server_error' | 'temporarily_unavailable';
+/** The single error class fortress throws. Carries an error code, HTTP status, and structured details. */
+declare class FortressError extends Error {
+    readonly code: FortressErrorCode;
+    readonly statusCode: number;
+    readonly retryAfter?: number;
+    readonly details?: unknown;
+    /** RFC 6749 §5.2 / §4.1.2.1 machine code. Set by `Errors.oauth()`. */
+    readonly oauthError?: OAuthErrorCode;
+    /** Human-readable description for the OAuth `error_description` field. */
+    readonly oauthDescription?: string;
+    /** Optional URI for the OAuth `error_uri` field (§5.2). */
+    readonly oauthErrorUri?: string;
+    constructor(code: FortressErrorCode, message: string, statusCode: number, options?: {
+        cause?: unknown;
+        retryAfter?: number;
+        details?: unknown;
+        oauthError?: OAuthErrorCode;
+        oauthDescription?: string;
+        oauthErrorUri?: string;
+    });
+    toJSON(): {
+        code: FortressErrorCode;
+        message: string;
+        statusCode: number;
+        details?: unknown;
+    };
+}
+/** Typed factory of {@link FortressError} constructors — one helper per error code. */
+declare const Errors: {
+    readonly unauthorized: (message?: string) => FortressError;
+    readonly tokenReuse: () => FortressError;
+    readonly sessionIdleTimeout: () => FortressError;
+    readonly sessionAbsoluteTimeout: () => FortressError;
+    readonly forbidden: (message?: string) => FortressError;
+    readonly badRequest: (message?: string) => FortressError;
+    readonly notFound: (message?: string) => FortressError;
+    readonly conflict: (message?: string, options?: {
+        cause?: unknown;
+        details?: unknown;
+    }) => FortressError;
+    readonly unprocessable: (message?: string, options?: {
+        cause?: unknown;
+        details?: unknown;
+    }) => FortressError;
+    readonly rateLimited: (retryAfter: number) => FortressError;
+    readonly database: (message?: string, cause?: unknown) => FortressError;
+    readonly serviceUnavailable: (message?: string, options?: {
+        cause?: unknown;
+        retryAfter?: number;
+    }) => FortressError;
+    readonly validationError: (issues: Array<{
+        path?: unknown;
+        message: string;
+    }>) => FortressError;
+    /**
+     * RFC 6749 §5.2 / §4.1.2.1 OAuth error.
+     *
+     * The HTTP error mapper detects `oauthError` and emits the OAuth-spec
+     * JSON body `{ error, error_description, error_uri? }` instead of the
+     * default fortress `{ code, message }` shape, so strict OAuth clients
+     * (Moodle, openid-client, Spring Security, etc.) can switch behaviour
+     * on the machine-readable `error` field.
+     *
+     * Status is inferred from the OAuth code per the spec table:
+     * - `invalid_client` → 401
+     * - everything else → 400
+     */
+    readonly oauth: (error: OAuthErrorCode, description?: string, options?: {
+        status?: number;
+        errorUri?: string;
+        cause?: unknown;
+    }) => FortressError;
+    /**
+     * Reconstruct a {@link FortressError} from a JSON error body emitted by
+     * `errorToResponse`. Used by the in-process `fortress.call.*` client to
+     * convert non-2xx responses into typed throws that mirror what a direct
+     * service-method call would produce.
+     *
+     * Maps by HTTP status when the body doesn't carry a recognizable
+     * `{ code, message }` payload, so network errors and opaque upstream
+     * failures still become structured `FortressError`s.
+     */
+    readonly fromHttpResponse: (status: number, body: unknown) => FortressError;
+};
+
+/**
+ * Permission debugging helper (P1-8).
+ *
+ * Answers the operator-console question "why does subject X have (or not
+ * have) permission `resource:action`?" by walking the same data the
+ * permission evaluator uses — direct bindings, role bindings, group
+ * memberships (for USER subjects) — and emitting a structured
+ * explanation listing every grant + its source.
+ *
+ * Designed as a free function rather than a new {@link IamService} method
+ * to keep the surface narrow and the DB queries explicit.
+ *
+ * @module
+ */
+
+interface PermissionExplanationSource {
+    /** Where the grant came from. */
+    via: 'direct-user' | 'direct-group' | 'direct-service-account' | 'role';
+    /** Role name when `via === 'role'`. */
+    role?: string;
+    /** Group id/name when the grant flows through a group (USER subjects only). */
+    group?: {
+        id: string;
+        name: string;
+    };
+    /** The matching permission row. */
+    permission: Permission;
+}
+interface PermissionExplanation {
+    subject: Subject;
+    resource: string;
+    action: string;
+    /** Final verdict from the configured IAM evaluation mode and condition context. */
+    allowed: boolean;
+    /** Every grant source that matched, including DENYs. */
+    sources: PermissionExplanationSource[];
+    /** Roles the subject is bound to (whether or not their permissions matched). */
+    roleBindings: Array<{
+        role: string;
+        tenantId?: string | null;
+    }>;
+    /** Groups the subject belongs to (USER only). */
+    groupMemberships: Array<{
+        id: string;
+        name: string;
+    }>;
+}
+/**
+ * Explain why a subject does (or does not) have a permission. Walks
+ * direct bindings, role bindings, and group memberships (USER only) and
+ * lists every matching grant with its source so operators can debug
+ * unexpected allow/deny results.
+ *
+ * @param db - Database adapter (typically `fortress.config.database`).
+ * @param iam - IAM service used for the authoritative verdict, including
+ *   configured evaluation mode, conditions, cache semantics, and inactive
+ *   service-account handling.
+ */
+declare function explainPermission(db: DatabaseAdapter, iam: IamService, subject: Subject, resource: string, action: string, context?: PermissionContext): Promise<PermissionExplanation>;
+
+/**
+ * Declarative policy types for policy-as-code (P1-7).
+ *
+ * A policy file declares the desired state of Fortress-owned IAM
+ * resources: resources/actions, roles + permissions, groups, and
+ * service accounts (with their role bindings). The diff/apply pipeline
+ * computes the operations needed to reconcile the live database with the
+ * declared state.
+ *
+ * What's covered:
+ * - Resources + actions (extends today's `fortress.resources.json`).
+ * - Roles with permission lists.
+ * - Groups (declared shells; user memberships managed via runtime APIs).
+ * - Service accounts with role bindings.
+ *
+ * What's intentionally NOT covered:
+ * - OAuth clients (have secrets; manage via admin endpoints).
+ * - User accounts / user-group memberships (user data, not policy).
+ * - Tenant data and per-tenant role bindings (large scale; declare in
+ *   per-tenant policy files if needed).
+ *
+ * @module
+ */
+/** Resource definition (action list shared with the existing `fortress.resources.json` shape). */
+interface PolicyResource {
+    name: string;
+    actions: string[];
+    description?: string;
+}
+/** Permission entry inside a role declaration. `effect` defaults to ALLOW. */
+interface PolicyPermission {
+    resource: string;
+    action: string;
+    effect?: 'ALLOW' | 'DENY';
+}
+/** Role declaration. Permissions are the *complete* desired set for the role; extras are removed on apply. */
+interface PolicyRole {
+    name: string;
+    description?: string;
+    permissions: PolicyPermission[];
+}
+/** Group declaration. User memberships are intentionally not managed via policy files. */
+interface PolicyGroup {
+    name: string;
+    description?: string;
+}
+/** Service-account declaration. Roles list is the complete desired binding set; extras are unbound on apply. */
+interface PolicyServiceAccount {
+    name: string;
+    displayName?: string;
+    description?: string;
+    isActive?: boolean;
+    /** Role names to bind to this service account. Bindings outside this list are removed on apply. */
+    roles?: string[];
+}
+/** Top-level policy document. */
+interface PolicyDocument {
+    resources?: PolicyResource[];
+    roles?: PolicyRole[];
+    groups?: PolicyGroup[];
+    serviceAccounts?: PolicyServiceAccount[];
+}
+/** Single op produced by `diffPolicy`. Tag is human-readable; `description` flattens for logs. */
+type PolicyOp = {
+    kind: 'create-resource';
+    resource: PolicyResource;
+    description: string;
+} | {
+    kind: 'add-resource-action';
+    resource: string;
+    action: string;
+    description: string;
+} | {
+    kind: 'create-role';
+    role: PolicyRole;
+    description: string;
+} | {
+    kind: 'update-role-description';
+    role: string;
+    from?: string;
+    to?: string;
+    description: string;
+} | {
+    kind: 'add-role-permission';
+    role: string;
+    permission: PolicyPermission;
+    description: string;
+} | {
+    kind: 'remove-role-permission';
+    role: string;
+    permission: PolicyPermission;
+    description: string;
+} | {
+    kind: 'delete-role';
+    role: string;
+    description: string;
+} | {
+    kind: 'create-group';
+    group: PolicyGroup;
+    description: string;
+} | {
+    kind: 'update-group-description';
+    group: string;
+    from?: string;
+    to?: string;
+    description: string;
+} | {
+    kind: 'delete-group';
+    group: string;
+    description: string;
+} | {
+    kind: 'create-service-account';
+    serviceAccount: PolicyServiceAccount;
+    description: string;
+} | {
+    kind: 'update-service-account';
+    serviceAccount: string;
+    changes: Record<string, unknown>;
+    description: string;
+} | {
+    kind: 'bind-service-account-role';
+    serviceAccount: string;
+    role: string;
+    description: string;
+} | {
+    kind: 'unbind-service-account-role';
+    serviceAccount: string;
+    role: string;
+    description: string;
+} | {
+    kind: 'delete-service-account';
+    serviceAccount: string;
+    description: string;
+};
+/** Diff result returned by `diffPolicy`. */
+interface PolicyPlan {
+    ops: PolicyOp[];
+    /** `true` when there is nothing to reconcile. */
+    inSync: boolean;
+}
+/** Options for `diffPolicy`. */
+interface DiffPolicyOptions {
+    /**
+     * Prune resources/roles/groups/service-accounts present in the database
+     * but absent from the policy file. Default `false` — apply only adds
+     * and updates unless the operator opts in to deletions.
+     */
+    prune?: boolean;
+    /** Explicitly acknowledge that pruning with no declared entities deletes all managed IAM state. */
+    allowEmptyPrune?: boolean;
+}
+
+/**
+ * Execute a {@link PolicyPlan} against an {@link IamService}.
+ *
+ * Ops are applied in dependency-safe order (resources before roles before
+ * service accounts) so a single `applyPolicyPlan` call can bring a fresh
+ * database to the declared state in one shot.
+ *
+ * @module
+ */
+
+/** Result of {@link applyPolicyPlan}. */
+interface ApplyPolicyResult {
+    applied: PolicyOp[];
+    skipped: PolicyOp[];
+    errors: {
+        op: PolicyOp;
+        message: string;
+    }[];
+}
+/**
+ * Apply every op in the plan, sorted by op kind so dependencies are
+ * satisfied (resources before roles, roles before service-account
+ * bindings). Returns a structured result so the caller can log success
+ * vs. failure per op.
+ */
+declare function applyPolicyPlan(plan: PolicyPlan, iam: IamService): Promise<ApplyPolicyResult>;
+/**
+ * Compatibility helper that applies only the resource operations in a plan.
+ * The file-path argument is retained for source compatibility but no file is
+ * written; resource updates are applied directly through the IAM service.
+ */
+declare function applyResourceOps(plan: PolicyPlan, iam: IamService, _syncResourceFile: string): Promise<void>;
+
+/**
+ * Compute the {@link PolicyPlan} that reconciles the live IAM state with
+ * a declarative {@link PolicyDocument}.
+ *
+ * The diff is intentionally additive-by-default: missing resources,
+ * actions, roles, permissions, groups, and service accounts produce
+ * `create-*` / `add-*` ops. Deletions only appear when `prune: true` is
+ * passed — most operators want their first apply to be safe.
+ *
+ * @module
+ */
+
+/**
+ * Compute the diff between a {@link PolicyDocument} (desired state) and
+ * the live IAM state. Pass the returned {@link PolicyPlan} to
+ * {@link applyPolicyPlan} to reconcile.
+ */
+declare function diffPolicy(policy: PolicyDocument, iam: IamService, options?: DiffPolicyOptions): Promise<PolicyPlan>;
+
+/**
+ * Load a {@link PolicyDocument} from disk with optional env-specific
+ * override. Node filesystem/path modules are imported only when these
+ * file-oriented helpers run, keeping the package root import runtime-neutral.
+ *
+ * @module
+ */
+
+interface LoadPolicyOptions {
+    /** Override the default `fortress.policy.json` path. */
+    filePath?: string;
+    /** Pick an env-specific file (`fortress.policy.<env>.json`). Defaults to `process.env.FORTRESS_ENV`. */
+    env?: string;
+    /** Working directory when resolving the default file paths. Defaults to `process.cwd()`. */
+    cwd?: string;
+}
+/** Default base file name. */
+declare const DEFAULT_POLICY_FILE = "fortress.policy.json";
+/** Validate and normalize an untrusted policy JSON value. */
+declare function parsePolicyDocument(value: unknown): PolicyDocument;
+/** Return the resolved policy-file path for an environment, or `null` if no file exists. */
+declare function resolvePolicyPath(options?: LoadPolicyOptions): Promise<string | null>;
+/** Load and parse a policy document. Throws when the file is missing or unparseable. */
+declare function loadPolicy(options?: LoadPolicyOptions): Promise<{
+    policy: PolicyDocument;
+    filePath: string;
+}>;
+
+/** Shorthand for the Standard Schema inferred output type. */
+type InferSchema<T extends StandardSchemaV1> = StandardSchemaV1.InferOutput<T>;
+/** Distribute a union into an intersection — `A | B` → `A & B`. Used by {@link intersect}. */
+type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
+/** Options accepted by the {@link str} builder (string constraints + annotations). */
+interface StringOptions {
+    description?: string;
+    /** Minimum length (`minLength`), enforced at runtime. */
+    min?: number;
+    /** Maximum length (`maxLength`), enforced at runtime. */
+    max?: number;
+    /** Regular-expression source (`pattern`), enforced at runtime. */
+    pattern?: string;
+    /** OpenAPI `format` annotation (e.g. `email`, `uuid`). Annotation-only unless paired with `pattern`. */
+    format?: string;
+}
+/** Options accepted by the {@link num}/{@link int} builders (numeric bounds + annotations). */
+interface NumberOptions {
+    description?: string;
+    /** Inclusive minimum (`minimum`), enforced at runtime. */
+    min?: number;
+    /** Inclusive maximum (`maximum`), enforced at runtime. */
+    max?: number;
+}
+/**
+ * Build a string {@link FortressSchema}.
+ *
+ * Pass a string for just a description, or an options object to set
+ * `minLength`/`maxLength`/`pattern`/`format` — the length and pattern
+ * constraints are enforced at runtime by the validator.
+ */
+declare function str(opts?: string | StringOptions): FortressSchema<string>;
+/**
+ * Build a number {@link FortressSchema} (any numeric, integer or float).
+ *
+ * Pass a string for just a description, or an options object to set
+ * `minimum`/`maximum` — both are enforced at runtime by the validator.
+ */
+declare function num(opts?: string | NumberOptions): FortressSchema<number>;
+/**
+ * Build an integer {@link FortressSchema}.
+ *
+ * Pass a string for just a description, or an options object to set
+ * `minimum`/`maximum` — both are enforced at runtime by the validator.
+ */
+declare function int(opts?: string | NumberOptions): FortressSchema<number>;
+/**
+ * Build a subject-id {@link FortressSchema}.
+ *
+ * IDs are opaque strings at the fortress API surface (RFC 7519 §4.1.2 for
+ * JWT `sub`). Numeric-keyed adapters stringify on read and parse on write
+ * at the adapter boundary; consumers never see the underlying representation.
+ */
+declare function id(description?: string): FortressSchema<string>;
+/** Build a boolean {@link FortressSchema}. */
+declare function bool(description?: string): FortressSchema<boolean>;
+/** Build an array {@link FortressSchema} whose items match the supplied schema. */
+declare function arr<T>(items: FortressSchema<T>, description?: string): FortressSchema<T[]>;
+/**
+ * Build an object {@link FortressSchema}. Pass property names after `properties`
+ * to mark them as required — they become non-optional in the inferred type.
+ */
+declare function obj<P extends Record<string, FortressSchema<any>>, K extends (keyof P & string)[] = []>(properties: P, ...required: K): FortressSchema<Simplify<{
+    [Key in K[number]]: Infer<P[Key]>;
+} & {
+    [Key in Exclude<keyof P & string, K[number]>]?: Infer<P[Key]>;
+}>>;
+/** Wrap a schema so it also accepts `null`. */
+declare function nullable<T>(schema: FortressSchema<T>): FortressSchema<T | null>;
+/** Build a discriminated-union schema (exactly one variant must match). */
+declare function oneOf<S extends FortressSchema<any>[]>(...schemas: S): FortressSchema<Infer<S[number]>>;
+/** Build a union schema (any one variant may match). */
+declare function anyOf<S extends FortressSchema<any>[]>(...schemas: S): FortressSchema<Infer<S[number]>>;
+/**
+ * Build a `$ref` schema pointing at an OpenAPI component schema by name.
+ *
+ * Two forms:
+ * - `ref(name)` — untyped `$ref`, returns `FortressSchema<unknown>`. Use when
+ *   the referenced component hasn't been declared yet (e.g. self-references
+ *   inside a components literal).
+ * - `ref(name, schema)` — typed and runtime-bound `$ref`. The supplied schema
+ *   provides both the inferred TypeScript type and the component definition
+ *   used for runtime validation. Use when you already have the component
+ *   schema and want downstream types and validation to flow through.
+ *
+ * For the common case (typed refs against a known components map), prefer
+ * {@link defineComponents} — it returns a bound `ref` that only needs a name.
+ */
+declare function ref<T>(name: string, schema: FortressSchema<T>): FortressSchema<T>;
+declare function ref(name: string): FortressSchema<unknown>;
+/**
+ * Declare a typed registry of OpenAPI component schemas and return a bound
+ * `ref` function that preserves each component's inferred TypeScript type.
+ *
+ * ```ts
+ * const User = obj({ id: int(), email: str() }, 'id', 'email');
+ * const { components, ref } = defineComponents({ User });
+ *
+ * const ep = endpoint('GET', '/me')
+ *   .response(200, 'Current user', ref('User'))
+ *   //                             ^ FortressSchema<{ id: string; email: string }>
+ *   .handler('me')
+ *   .build();
+ * ```
+ *
+ * The returned `components` is the same object you passed in (useful for
+ * OpenAPI spec emission). The returned `ref` is a generic function that
+ * looks up each key in `T` and returns a `$ref` schema carrying the
+ * inferred type of the referenced component.
+ */
+declare function defineComponents<T extends Record<string, FortressSchema<any>>>(components: T): {
+    components: T;
+    ref: <K extends keyof T & string>(name: K) => FortressSchema<Infer<T[K]>>;
+};
+/** Build an enum {@link FortressSchema} from a fixed set of string or number literal values. */
+declare function enums<T extends string | number>(...values: T[]): FortressSchema<T>;
+/** Build a string {@link FortressSchema} with an OpenAPI `format` annotation (e.g. `email`, `uri`, `uuid`). */
+declare function strFormat(format: string, description?: string): FortressSchema<string>;
+/** Build a {@link FortressSchema} that only accepts the literal `null`. */
+declare function nullType(): FortressSchema<null>;
+/** An object {@link FortressSchema} with unknown additional properties (e.g. plugin data, metadata). */
+declare function record(description?: string): FortressSchema<Record<string, unknown>>;
+/** An object {@link FortressSchema} where every property value matches the supplied schema. */
+declare function recordOf<T>(valueSchema: FortressSchema<T>, description?: string): FortressSchema<Record<string, T>>;
+/**
+ * Build a literal {@link FortressSchema} accepting exactly one constant value
+ * (`const`). The value is enforced at runtime and the inferred type narrows to
+ * the literal (e.g. `literal('admin')` infers `'admin'`).
+ */
+declare function literal<const V extends string | number | boolean>(value: V, description?: string): FortressSchema<V>;
+/**
+ * Build an intersection {@link FortressSchema} (`allOf`) — a value must satisfy
+ * every supplied schema. The inferred type is the intersection of each schema's
+ * inferred type.
+ */
+declare function intersect<S extends FortressSchema<any>[]>(...schemas: S): FortressSchema<UnionToIntersection<Infer<S[number]>>>;
+/**
+ * Close an object {@link FortressSchema} — sets `additionalProperties: false`,
+ * so the validator rejects any key not declared in `properties`. Use to harden
+ * request bodies against over-posting (mass assignment).
+ */
+declare function strict<T>(schema: FortressSchema<T>): FortressSchema<T>;
+/**
+ * Build a discriminated-union {@link FortressSchema}. Emits `oneOf` plus an
+ * OpenAPI `discriminator`, which the validator uses to dispatch on
+ * `propertyName` (faster, with precise per-variant errors) instead of trying
+ * every branch.
+ */
+declare function discriminatedUnion<S extends FortressSchema<any>[]>(propertyName: string, ...variants: S): FortressSchema<Infer<S[number]>>;
+/** Email string schema (`format: 'email'`) — enforces the WHATWG HTML5 email grammar at runtime. */
+declare const email: (description?: string) => FortressSchema<string>;
+/** UUID string schema (`format: 'uuid'`) — enforces RFC 9562 versions 1–8 plus nil/max at runtime. */
+declare const uuid: (description?: string) => FortressSchema<string>;
+/** URL string schema (`format: 'uri'`) — enforces an explicit `scheme://` authority at runtime. */
+declare const url: (description?: string) => FortressSchema<string>;
+/** RFC 3339 date-time string schema (`format: 'date-time'`) — field ranges enforced at runtime. */
+declare const datetime: (description?: string) => FortressSchema<string>;
+/** RFC 3339 full-date string schema (`format: 'date'`) — field ranges enforced at runtime. */
+declare const date: (description?: string) => FortressSchema<string>;
+/** RFC 3339 time string schema (`format: 'time'`) — field ranges enforced at runtime. */
+declare const time: (description?: string) => FortressSchema<string>;
+/** Type guard — `true` if the value implements Standard Schema V1. */
+declare function isStandardSchema(value: unknown): value is StandardSchemaV1;
+/** Type guard — `true` if the value is a {@link FortressSchema} (has both JSON Schema fields and Standard Schema wiring). */
+declare function isFortressSchema(value: unknown): value is FortressSchema;
+/**
+ * Extract a {@link JSONSchema} from any schema input.
+ *
+ * - {@link FortressSchema}: returned as-is (it already _is_ JSON Schema).
+ * - External Standard Schema with a `~standard.jsonSchema.input()` adapter
+ *   (Zod, Valibot, ArkType, etc.): extracted via the adapter.
+ * - External Standard Schema that already IS a JSON Schema object (fetcher,
+ *   etc.): returned as-is.
+ * - Anything else: empty object fallback.
+ */
+declare function extractJsonSchema(schema: FortressSchema<any> | StandardSchemaV1<any>): JSONSchema;
+/** Schema input accepted by `EndpointBuilder.body/query/params` — a fortress schema or any Standard Schema V1 implementation. */
+type SchemaInput = FortressSchema<any> | StandardSchemaV1<any>;
+/**
+ * Canonical fortress error response body — the exact wire shape emitted by
+ * {@link import('./errors').FortressError.toJSON}. Reference this from
+ * endpoint `.response(4xx|5xx, ...)` declarations so host APIs document the
+ * same error contract Fortress's own routes produce, and so clients can use
+ * a single error parser everywhere.
+ *
+ * Shape:
+ * ```ts
+ * {
+ *   code: string,       // FortressErrorCode
+ *   message: string,    // human-readable
+ *   statusCode: number, // HTTP status
+ *   details?: unknown,  // optional structured payload (e.g. validation issues)
+ * }
+ * ```
+ *
+ * See {@link EndpointBuilder.errorResponse} for a shorthand that wires this
+ * schema into a status declaration in one call.
+ */
+interface ErrorEnvelopeBody {
+    code: string;
+    message: string;
+    statusCode: number;
+    details?: unknown;
+}
+declare const ErrorEnvelope: FortressSchema<ErrorEnvelopeBody>;
+/**
+ * Fluent builder for {@link EndpointDefinition} objects. Construct via the
+ * {@link endpoint} factory and chain `summary`, `body`, `response`, etc.
+ * before calling `build()`.
+ *
+ * The four type parameters accumulate as schemas are declared: each call to
+ * `.body()`, `.query()`, `.params()`, and `.response()` returns a new
+ * builder type with the inferred schema baked in. By the time `.build()` is
+ * called, the returned {@link EndpointDefinition} carries complete phantom
+ * type information about its request/response shape, which the
+ * `InferEndpoint*` helpers and the `fortress.call.*` proxy read at the call
+ * site.
+ */
+declare class EndpointBuilder<TBody = {}, TQuery = {}, TParams = {}, TResponses extends Record<number, unknown> = {}> {
+    private _method;
+    private _path;
+    private _handler;
+    private _summary;
+    private _description?;
+    private _tags;
+    private _security;
+    private _deprecated;
+    private _permission?;
+    private _body?;
+    private _query?;
+    private _params?;
+    private _responses;
+    constructor(method: HttpMethod, path: string);
+    summary(s: string): this;
+    description(s: string): this;
+    tags(...t: string[]): this;
+    security(...s: SecurityRequirement[]): this;
+    deprecated(): this;
+    permission(resource: string, action: string): this;
+    body<T extends StandardSchemaV1>(schema: T): EndpointBuilder<InferSchema<T>, TQuery, TParams, TResponses>;
+    query<T extends StandardSchemaV1>(schema: T): EndpointBuilder<TBody, InferSchema<T>, TParams, TResponses>;
+    params<T extends StandardSchemaV1>(schema: T): EndpointBuilder<TBody, TQuery, InferSchema<T>, TResponses>;
+    /**
+     * Declare a response for a given status code. Three call shapes:
+     *
+     * - `.response(200, 'Ok', schema)` — typed. The inferred output type of
+     *   `schema` becomes the response body at that status.
+     * - `.response(401, 'Unauthorized', schema)` — also typed. Error bodies
+     *   are inferred the same way as success bodies; the `fortress.call.*`
+     *   proxy treats non-2xx as throws and only exposes 2xx responses.
+     * - `.response(204, 'No content')` — untyped. Use when there's no body.
+     */
+    response<S extends number, T extends StandardSchemaV1>(status: S, description: string, schema: T): EndpointBuilder<TBody, TQuery, TParams, TResponses & {
+        [K in S]: InferSchema<T>;
+    }>;
+    response<S extends number>(status: S, description: string): EndpointBuilder<TBody, TQuery, TParams, TResponses & {
+        [K in S]: unknown;
+    }>;
+    /**
+     * Declare an error response that returns the canonical {@link ErrorEnvelope}
+     * body. Shorthand for `.response(status, description, ErrorEnvelope)`.
+     *
+     * Aligns host endpoint error responses with what Fortress's own routes
+     * emit, so a single client-side error parser works everywhere.
+     *
+     * ```ts
+     * endpoint('GET', '/schools/:id')
+     *   .summary('Get a school')
+     *   .params(obj({ id: str() }, 'id'))
+     *   .response(200, 'OK', SchoolEnvelope)
+     *   .errorResponse(404, 'School not found')
+     *   .errorResponse(403, 'Forbidden')
+     *   .build();
+     * ```
+     */
+    errorResponse<S extends number>(status: S, description: string): EndpointBuilder<TBody, TQuery, TParams, TResponses & {
+        [K in S]: InferSchema<typeof ErrorEnvelope>;
+    }>;
+    handler(name: string): this;
+    build(): EndpointDefinition<TBody, TQuery, TParams, TResponses>;
+}
+/** Start building a new {@link EndpointDefinition} for the given HTTP method and path. */
+declare function endpoint(method: HttpMethod, path: string): EndpointBuilder<{}, {}, {}, {}>;
+
+/**
+ * Runtime request validation using Standard Schema.
+ *
+ * Validates body/query/params against schemas stored in EndpointInput.
+ * Works with any Standard Schema provider (fortress, Zod, Valibot, ArkType).
+ */
+
+/**
+ * Validate request data against endpoint input schemas.
+ * Throws FortressError('VALIDATION_ERROR') on failure.
+ *
+ * Uses `~standard.validate()` from whichever schema is attached
+ * (fortress built-in or external Standard Schema).
+ */
+declare function validateRequest(input: EndpointInput | undefined, data: {
+    body?: unknown;
+    query?: unknown;
+    params?: unknown;
+}): Promise<void>;
+
+export { type ApplyPolicyResult, DEFAULT_POLICY_FILE, DatabaseAdapter, type DiffPolicyOptions, EndpointBuilder, EndpointDefinition, EndpointInput, ErrorEnvelope, Errors, FortressError, type FortressErrorCode, FortressSchema, HttpMethod, IamService, Infer, JSONSchema, type LoadPolicyOptions, type NumberOptions, type OAuthErrorCode, Permission, PermissionContext, type PermissionExplanation, type PermissionExplanationSource, type PolicyDocument, type PolicyGroup, type PolicyOp, type PolicyPermission, type PolicyPlan, type PolicyResource, type PolicyRole, type PolicyServiceAccount, type SchemaInput, SecurityRequirement, Simplify, StandardSchemaV1, type StringOptions, anyOf, applyPolicyPlan, applyResourceOps, arr, bool, date, datetime, defineComponents, diffPolicy, discriminatedUnion, email, endpoint, enums, explainPermission, extractJsonSchema, id, int, intersect, isFortressSchema, isStandardSchema, literal, loadPolicy, nullType, nullable, num, obj, oneOf, parsePolicyDocument, record, recordOf, ref, resolvePolicyPath, str, strFormat, strict, time, url, uuid, validateRequest };