@bajustone/fortress 1.0.0-rc.1

package/dist/auth-service-BcyQ2PuZ.d.cts

@@ -0,0 +1,307 @@
+import { S as Subject, P as PermissionContext, b as Permission, c as PermissionInput, d as Role, a as SubjectType, G as Group, e as RoleBinding, F as FortressUser, C as CreateServiceAccountInput, f as ServiceAccount, R as RequestMeta, A as AuthResult, g as AuthMethod, h as AuthTokenPair, i as CreateUserInput, T as TokenClaims, j as SessionInfo, L as LoginIdentifierType, k as LoginIdentifier, l as PendingReason } from './types-et0R8tsC.cjs';
+
+/**
+ * Structural logger contract. Shaped to be assignment-compatible with pino's
+ * `BaseLogger` and Fastify's `FastifyBaseLogger`, so consumers can drop a
+ * `pino()` instance or `fastify.log` in directly with zero adapter code.
+ *
+ * The default is {@link SILENT_LOGGER} — libraries that log to stderr by
+ * default are universally hated. Opt-in logging only.
+ */
+type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal';
+interface LogFn {
+    (msg: string): void;
+    (obj: Record<string, unknown>, msg?: string): void;
+    (msg: string, ...args: unknown[]): void;
+}
+interface FortressLogger {
+    level: LogLevel | 'silent' | string;
+    fatal: LogFn;
+    error: LogFn;
+    warn: LogFn;
+    info: LogFn;
+    debug: LogFn;
+    trace: LogFn;
+    silent: LogFn;
+    /** Optional on pino/Fastify; Fortress calls it defensively. */
+    child?: (bindings: Record<string, unknown>) => FortressLogger;
+    /** Optional guard for lazy evaluation of expensive log metadata. */
+    isLevelEnabled?: (level: LogLevel) => boolean;
+}
+
+/**
+ * Fortress-internal telemetry interfaces.
+ *
+ * Core code depends on these shapes, never on `@opentelemetry/api`. The OTel
+ * adapter in `src/otel/index.ts` is the only file in the repo that imports
+ * `@opentelemetry/api`; it returns a {@link TelemetryProvider} that satisfies
+ * these interfaces. This keeps `@opentelemetry/api` off the core critical
+ * path — runtimes like Cloudflare Workers and Deno never resolve it unless
+ * the user explicitly imports `@bajustone/fortress/otel`.
+ */
+type AttributeValue = string | number | boolean;
+type Attributes = Record<string, AttributeValue>;
+interface Span {
+    setAttribute: (key: string, value: AttributeValue) => void;
+    recordException: (error: unknown) => void;
+    setStatus: (status: {
+        code: 'ok' | 'error';
+        message?: string;
+    }) => void;
+    end: () => void;
+}
+interface Tracer {
+    startSpan: (name: string, attributes?: Attributes) => Span;
+    /** Run a callback with this span as the active parent for nested spans. */
+    startActiveSpan?: <T>(name: string, attributes: Attributes | undefined, callback: (span: Span) => T | Promise<T>) => Promise<T>;
+}
+interface Counter {
+    add: (value: number, attributes?: Attributes) => void;
+}
+interface Histogram {
+    record: (value: number, attributes?: Attributes) => void;
+}
+interface Meter {
+    createCounter: (name: string, options?: {
+        description?: string;
+        unit?: string;
+    }) => Counter;
+    createHistogram: (name: string, options?: {
+        description?: string;
+        unit?: string;
+        boundaries?: number[];
+    }) => Histogram;
+}
+interface TelemetryProvider {
+    tracer: Tracer;
+    meter: Meter;
+}
+
+type Unsubscribe = () => void;
+
+interface ResourceDefinition {
+    actions: string[];
+    description?: string;
+}
+interface ResourceFile {
+    resources: Record<string, ResourceDefinition>;
+}
+/** Validate and normalize the canonical map-shaped resource document. */
+declare function parseResourceFile(value: unknown): ResourceFile;
+
+interface IamEvent {
+    eventType: string;
+    actorId?: string | null;
+    targetId?: string | null;
+    targetType?: string | null;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Async IAM event listener. May return a Promise — if you `return` it, any
+ * rejection is routed to `config.logger.error`. Firing work via
+ * `void asyncWork()` inside a sync body is an explicit opt-out of that
+ * safety net; rejections will escape to the runtime's unhandled-rejection
+ * handler instead.
+ */
+type IamEventListener = (event: IamEvent) => void | Promise<void>;
+/**
+ * High-frequency event fired on every permission check. Emitted by a
+ * separate observer list from {@link IamEvent} so audit-log consumers
+ * (which subscribe to mutations) aren't spammed with per-check traffic.
+ *
+ * Listeners are invoked **synchronously**. The type signature intentionally
+ * returns `void` (not `Promise<void>`) to discourage awaiting expensive
+ * work on the hot path. If an observer needs async work it should fire
+ * and forget with `void asyncWork()`.
+ */
+interface PermissionCheckEvent {
+    subjectType: 'USER' | 'SERVICE_ACCOUNT' | 'GROUP';
+    subjectId: string;
+    resource: string;
+    action: string;
+    allowed: boolean;
+    cached: boolean;
+    /** Pre-divided monotonic duration in seconds; ready to feed into a histogram. */
+    durationSeconds: number;
+    tenantId?: string;
+}
+type PermissionCheckListener = (event: PermissionCheckEvent) => void;
+interface IamService {
+    checkPermission: (subject: Subject, resource: string, action: string, context?: PermissionContext) => Promise<boolean>;
+    getPermissionsForSubject: (subject: Subject, tenantId?: string) => Promise<Permission[]>;
+    createRole: (name: string, permissions: PermissionInput[], description?: string) => Promise<Role>;
+    deleteRole: (roleId: string) => Promise<void>;
+    bindRole: (subjectType: SubjectType, subjectId: string, roleId: string, tenantId?: string) => Promise<void>;
+    bindRoleToUser: (userId: string, roleId: string, tenantId?: string) => Promise<void>;
+    bindRoleToGroup: (groupId: string, roleId: string, tenantId?: string) => Promise<void>;
+    /** Omitted removes all scopes; null removes only the global binding; a string removes one tenant. */
+    unbindRole: (subjectType: SubjectType, subjectId: string, roleId: string, tenantId?: string | null) => Promise<void>;
+    bindPermissionToUser: (userId: string, permission: PermissionInput, tenantId?: string) => Promise<void>;
+    bindPermissionToGroup: (groupId: string, permission: PermissionInput, tenantId?: string) => Promise<void>;
+    unbindPermissionFromUser: (userId: string, permissionId: string, tenantId?: string | null) => Promise<void>;
+    unbindPermissionFromGroup: (groupId: string, permissionId: string, tenantId?: string | null) => Promise<void>;
+    createGroup: (name: string, description?: string) => Promise<Group>;
+    addUserToGroup: (groupId: string, userId: string) => Promise<void>;
+    removeUserFromGroup: (groupId: string, userId: string) => Promise<void>;
+    getResources: () => Promise<ResourceFile>;
+    getRoles: () => Promise<Role[]>;
+    /** Apply a resource map directly without filesystem access. */
+    pushResources: (resources: ResourceFile) => Promise<void>;
+    /** List role bindings: omitted scope means all, `null` means global only, string means one tenant. */
+    listRoleBindingsForSubject: (subject: Subject, tenantId?: string | null) => Promise<RoleBinding[]>;
+    syncResources: (direction: 'push' | 'pull', filePath?: string) => Promise<void>;
+    clearPermissionCache: () => void;
+    /**
+     * Register a listener for IAM mutation events. Multiple listeners are
+     * supported — each is invoked in registration order. Observer failures
+     * are routed to the configured logger at `error` level and never break
+     * IAM operations. Returns an unsubscribe function.
+     */
+    addIamObserver: (listener: IamEventListener) => Unsubscribe;
+    /**
+     * Register a listener for individual permission checks. Fires on every
+     * `checkPermission` call with latency and cache-hit information. The
+     * listener signature is synchronous — see {@link PermissionCheckEvent}
+     * for rationale. Returns an unsubscribe function.
+     */
+    addPermissionCheckObserver: (listener: PermissionCheckListener) => Unsubscribe;
+    getRole: (roleId: string) => Promise<Role & {
+        permissions: Permission[];
+    }>;
+    updateRole: (roleId: string, data: {
+        name?: string;
+        description?: string | null;
+    }) => Promise<Role>;
+    listGroups: (options?: {
+        limit?: number;
+        offset?: number;
+    }) => Promise<{
+        groups: Group[];
+        total: number;
+    }>;
+    getGroup: (groupId: string) => Promise<Group & {
+        users: FortressUser[];
+    }>;
+    updateGroup: (groupId: string, data: {
+        name?: string;
+        description?: string;
+    }) => Promise<Group>;
+    deleteGroup: (groupId: string) => Promise<void>;
+    getGroupUsers: (groupId: string) => Promise<FortressUser[]>;
+    listPermissions: (options?: {
+        resource?: string;
+    }) => Promise<Permission[]>;
+    createPermission: (permission: PermissionInput) => Promise<Permission>;
+    deletePermission: (permissionId: string) => Promise<void>;
+    addPermissionToRole: (roleId: string, permission: PermissionInput) => Promise<void>;
+    removePermissionFromRole: (roleId: string, permission: PermissionInput) => Promise<void>;
+    createServiceAccount: (input: CreateServiceAccountInput) => Promise<ServiceAccount>;
+    getServiceAccount: (id: string) => Promise<ServiceAccount>;
+    listServiceAccounts: (options?: {
+        limit?: number;
+        offset?: number;
+    }) => Promise<{
+        serviceAccounts: ServiceAccount[];
+        total: number;
+    }>;
+    updateServiceAccount: (id: string, data: {
+        displayName?: string | null;
+        description?: string | null;
+        isActive?: boolean;
+    }) => Promise<ServiceAccount>;
+    deleteServiceAccount: (id: string) => Promise<void>;
+    bindRoleToServiceAccount: (serviceAccountId: string, roleId: string, tenantId?: string) => Promise<void>;
+    /** Unbind across all scopes when omitted, global only for `null`, or one tenant for a string scope. */
+    unbindRoleFromServiceAccount: (serviceAccountId: string, roleId: string, tenantId?: string | null) => Promise<void>;
+    bindPermissionToServiceAccount: (serviceAccountId: string, permission: PermissionInput, tenantId?: string) => Promise<void>;
+    unbindPermissionFromServiceAccount: (serviceAccountId: string, permissionId: string, tenantId?: string | null) => Promise<void>;
+}
+
+/**
+ * Lifecycle event emitted by the auth service. Mirrors the IAM observer
+ * pattern (`addIamObserver`) so consumers — audit log, SIEM webhooks,
+ * telemetry plugins, Datadog adapters — can subscribe to auth events
+ * without reimplementing every hook individually.
+ */
+interface AuthEvent {
+    eventType: 'LOGIN_SUCCESS' | 'LOGIN_FAILURE' | 'LOGIN_PENDING' | 'LOGOUT' | 'REGISTER' | 'TOKEN_REFRESH' | 'TOKEN_REUSE_DETECTED' | 'TOKEN_REUSE_GRACED' | 'TOKEN_FINGERPRINT_MISMATCH' | 'MFA_VERIFY_SUCCESS' | 'MFA_VERIFY_FAILURE' | 'SESSION_EXPIRED_IDLE' | 'SESSION_EXPIRED_ABSOLUTE' | 'PASSWORD_BREACH_CHECK_DEGRADED' | 'IMPERSONATE';
+    actorId?: string;
+    identifier?: string;
+    method?: 'password' | 'oauth' | 'magic_link' | 'webauthn' | '2fa' | 'api_key';
+    ipAddress?: string;
+    userAgent?: string;
+    outcome?: 'success' | 'failure' | 'pending';
+    /** Set on `LOGIN_PENDING` — which additional step the sign-in is waiting on. */
+    pendingReason?: PendingReason;
+    /** Free-form sub-action label (e.g. the specific fingerprint/session action that fired the event). */
+    action?: string;
+    error?: {
+        message: string;
+        code?: string;
+    };
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Async auth event listener. May return a Promise — if you `return` it, any
+ * rejection is routed to `config.logger.error`. Firing work via
+ * `void asyncWork()` inside a sync body is an explicit opt-out of that
+ * safety net; rejections will escape to the runtime's unhandled-rejection
+ * handler instead.
+ */
+type AuthEventListener = (event: AuthEvent) => void | Promise<void>;
+interface AuthService {
+    login: (identifier: string, password: string, meta?: RequestMeta) => Promise<AuthResult>;
+    /** Consume a verified factor's continuation, rerun remaining gates, then issue tokens. */
+    completePendingAuth: (continuationToken: string, completion: unknown, meta?: RequestMeta) => Promise<AuthResult>;
+    /** Finish a trusted plugin-owned primary credential (for example a magic link). */
+    completePluginAuth: (userId: string, method: Exclude<AuthMethod, 'refresh' | 'impersonation'>, meta?: RequestMeta) => Promise<AuthResult>;
+    refresh: (refreshToken: string, meta?: RequestMeta) => Promise<AuthTokenPair>;
+    logout: (refreshToken: string) => Promise<void>;
+    me: (userId: string) => Promise<FortressUser>;
+    createUser: (data: CreateUserInput) => Promise<FortressUser>;
+    verifyToken: (token: string) => Promise<TokenClaims>;
+    signToken: (claims: Omit<TokenClaims, 'iat' | 'exp' | 'aud'>) => Promise<string>;
+    listSessions: (userId: string) => Promise<SessionInfo[]>;
+    revokeSession: (userId: string, tokenId: string) => Promise<void>;
+    revokeAllOtherSessions: (userId: string, currentTokenId: string) => Promise<void>;
+    addLoginIdentifier: (userId: string, type: LoginIdentifierType, value: string) => Promise<void>;
+    removeLoginIdentifier: (userId: string, type: LoginIdentifierType, value: string) => Promise<void>;
+    getLoginIdentifiers: (userId: string) => Promise<LoginIdentifier[]>;
+    /**
+     * Issue a short-lived, non-renewable access token that lets an admin act as another user.
+     * The token carries an RFC 8693 `act` claim identifying the real admin.
+     *
+     * Requires the admin user to hold `fortress:impersonate`. The built-in HTTP route also enforces this via endpoint metadata.
+     */
+    impersonate: (adminUserId: string, targetUserId: string, options?: {
+        reason?: string;
+        expirySeconds?: number;
+    }) => Promise<AuthResult>;
+    listUsers: (options: {
+        limit?: number;
+        offset?: number;
+        search?: string;
+        sortBy?: string;
+        sortDirection?: 'asc' | 'desc';
+    }) => Promise<{
+        users: FortressUser[];
+        total: number;
+    }>;
+    getUserById: (userId: string) => Promise<FortressUser>;
+    updateUser: (userId: string, data: {
+        name?: string;
+        email?: string;
+        isActive?: boolean;
+        password?: string;
+    }) => Promise<FortressUser>;
+    deleteUser: (userId: string) => Promise<void>;
+    /**
+     * Register a listener for auth lifecycle events. Multiple listeners are
+     * supported — each is invoked in registration order. Listener failures
+     * never break auth operations; they are routed to the configured logger
+     * at `error` level. Returns an unsubscribe function.
+     */
+    addAuthObserver: (listener: AuthEventListener) => Unsubscribe;
+}
+
+export { type AttributeValue as A, type Counter as C, type FortressLogger as F, type Histogram as H, type IamEvent as I, type Meter as M, type PermissionCheckEvent as P, type ResourceDefinition as R, type Span as S, type TelemetryProvider as T, type Unsubscribe as U, type Attributes as a, type AuthEvent as b, type AuthEventListener as c, type IamEventListener as d, type PermissionCheckListener as e, type Tracer as f, type IamService as g, type ResourceFile as h, type AuthService as i, parseResourceFile as p };

package/dist/auth-service-BkzZkWfH.d.ts

@@ -0,0 +1,307 @@
+import { S as Subject, P as PermissionContext, b as Permission, c as PermissionInput, d as Role, a as SubjectType, G as Group, e as RoleBinding, F as FortressUser, C as CreateServiceAccountInput, f as ServiceAccount, R as RequestMeta, A as AuthResult, g as AuthMethod, h as AuthTokenPair, i as CreateUserInput, T as TokenClaims, j as SessionInfo, L as LoginIdentifierType, k as LoginIdentifier, l as PendingReason } from './types-et0R8tsC.js';
+
+/**
+ * Structural logger contract. Shaped to be assignment-compatible with pino's
+ * `BaseLogger` and Fastify's `FastifyBaseLogger`, so consumers can drop a
+ * `pino()` instance or `fastify.log` in directly with zero adapter code.
+ *
+ * The default is {@link SILENT_LOGGER} — libraries that log to stderr by
+ * default are universally hated. Opt-in logging only.
+ */
+type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal';
+interface LogFn {
+    (msg: string): void;
+    (obj: Record<string, unknown>, msg?: string): void;
+    (msg: string, ...args: unknown[]): void;
+}
+interface FortressLogger {
+    level: LogLevel | 'silent' | string;
+    fatal: LogFn;
+    error: LogFn;
+    warn: LogFn;
+    info: LogFn;
+    debug: LogFn;
+    trace: LogFn;
+    silent: LogFn;
+    /** Optional on pino/Fastify; Fortress calls it defensively. */
+    child?: (bindings: Record<string, unknown>) => FortressLogger;
+    /** Optional guard for lazy evaluation of expensive log metadata. */
+    isLevelEnabled?: (level: LogLevel) => boolean;
+}
+
+/**
+ * Fortress-internal telemetry interfaces.
+ *
+ * Core code depends on these shapes, never on `@opentelemetry/api`. The OTel
+ * adapter in `src/otel/index.ts` is the only file in the repo that imports
+ * `@opentelemetry/api`; it returns a {@link TelemetryProvider} that satisfies
+ * these interfaces. This keeps `@opentelemetry/api` off the core critical
+ * path — runtimes like Cloudflare Workers and Deno never resolve it unless
+ * the user explicitly imports `@bajustone/fortress/otel`.
+ */
+type AttributeValue = string | number | boolean;
+type Attributes = Record<string, AttributeValue>;
+interface Span {
+    setAttribute: (key: string, value: AttributeValue) => void;
+    recordException: (error: unknown) => void;
+    setStatus: (status: {
+        code: 'ok' | 'error';
+        message?: string;
+    }) => void;
+    end: () => void;
+}
+interface Tracer {
+    startSpan: (name: string, attributes?: Attributes) => Span;
+    /** Run a callback with this span as the active parent for nested spans. */
+    startActiveSpan?: <T>(name: string, attributes: Attributes | undefined, callback: (span: Span) => T | Promise<T>) => Promise<T>;
+}
+interface Counter {
+    add: (value: number, attributes?: Attributes) => void;
+}
+interface Histogram {
+    record: (value: number, attributes?: Attributes) => void;
+}
+interface Meter {
+    createCounter: (name: string, options?: {
+        description?: string;
+        unit?: string;
+    }) => Counter;
+    createHistogram: (name: string, options?: {
+        description?: string;
+        unit?: string;
+        boundaries?: number[];
+    }) => Histogram;
+}
+interface TelemetryProvider {
+    tracer: Tracer;
+    meter: Meter;
+}
+
+type Unsubscribe = () => void;
+
+interface ResourceDefinition {
+    actions: string[];
+    description?: string;
+}
+interface ResourceFile {
+    resources: Record<string, ResourceDefinition>;
+}
+/** Validate and normalize the canonical map-shaped resource document. */
+declare function parseResourceFile(value: unknown): ResourceFile;
+
+interface IamEvent {
+    eventType: string;
+    actorId?: string | null;
+    targetId?: string | null;
+    targetType?: string | null;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Async IAM event listener. May return a Promise — if you `return` it, any
+ * rejection is routed to `config.logger.error`. Firing work via
+ * `void asyncWork()` inside a sync body is an explicit opt-out of that
+ * safety net; rejections will escape to the runtime's unhandled-rejection
+ * handler instead.
+ */
+type IamEventListener = (event: IamEvent) => void | Promise<void>;
+/**
+ * High-frequency event fired on every permission check. Emitted by a
+ * separate observer list from {@link IamEvent} so audit-log consumers
+ * (which subscribe to mutations) aren't spammed with per-check traffic.
+ *
+ * Listeners are invoked **synchronously**. The type signature intentionally
+ * returns `void` (not `Promise<void>`) to discourage awaiting expensive
+ * work on the hot path. If an observer needs async work it should fire
+ * and forget with `void asyncWork()`.
+ */
+interface PermissionCheckEvent {
+    subjectType: 'USER' | 'SERVICE_ACCOUNT' | 'GROUP';
+    subjectId: string;
+    resource: string;
+    action: string;
+    allowed: boolean;
+    cached: boolean;
+    /** Pre-divided monotonic duration in seconds; ready to feed into a histogram. */
+    durationSeconds: number;
+    tenantId?: string;
+}
+type PermissionCheckListener = (event: PermissionCheckEvent) => void;
+interface IamService {
+    checkPermission: (subject: Subject, resource: string, action: string, context?: PermissionContext) => Promise<boolean>;
+    getPermissionsForSubject: (subject: Subject, tenantId?: string) => Promise<Permission[]>;
+    createRole: (name: string, permissions: PermissionInput[], description?: string) => Promise<Role>;
+    deleteRole: (roleId: string) => Promise<void>;
+    bindRole: (subjectType: SubjectType, subjectId: string, roleId: string, tenantId?: string) => Promise<void>;
+    bindRoleToUser: (userId: string, roleId: string, tenantId?: string) => Promise<void>;
+    bindRoleToGroup: (groupId: string, roleId: string, tenantId?: string) => Promise<void>;
+    /** Omitted removes all scopes; null removes only the global binding; a string removes one tenant. */
+    unbindRole: (subjectType: SubjectType, subjectId: string, roleId: string, tenantId?: string | null) => Promise<void>;
+    bindPermissionToUser: (userId: string, permission: PermissionInput, tenantId?: string) => Promise<void>;
+    bindPermissionToGroup: (groupId: string, permission: PermissionInput, tenantId?: string) => Promise<void>;
+    unbindPermissionFromUser: (userId: string, permissionId: string, tenantId?: string | null) => Promise<void>;
+    unbindPermissionFromGroup: (groupId: string, permissionId: string, tenantId?: string | null) => Promise<void>;
+    createGroup: (name: string, description?: string) => Promise<Group>;
+    addUserToGroup: (groupId: string, userId: string) => Promise<void>;
+    removeUserFromGroup: (groupId: string, userId: string) => Promise<void>;
+    getResources: () => Promise<ResourceFile>;
+    getRoles: () => Promise<Role[]>;
+    /** Apply a resource map directly without filesystem access. */
+    pushResources: (resources: ResourceFile) => Promise<void>;
+    /** List role bindings: omitted scope means all, `null` means global only, string means one tenant. */
+    listRoleBindingsForSubject: (subject: Subject, tenantId?: string | null) => Promise<RoleBinding[]>;
+    syncResources: (direction: 'push' | 'pull', filePath?: string) => Promise<void>;
+    clearPermissionCache: () => void;
+    /**
+     * Register a listener for IAM mutation events. Multiple listeners are
+     * supported — each is invoked in registration order. Observer failures
+     * are routed to the configured logger at `error` level and never break
+     * IAM operations. Returns an unsubscribe function.
+     */
+    addIamObserver: (listener: IamEventListener) => Unsubscribe;
+    /**
+     * Register a listener for individual permission checks. Fires on every
+     * `checkPermission` call with latency and cache-hit information. The
+     * listener signature is synchronous — see {@link PermissionCheckEvent}
+     * for rationale. Returns an unsubscribe function.
+     */
+    addPermissionCheckObserver: (listener: PermissionCheckListener) => Unsubscribe;
+    getRole: (roleId: string) => Promise<Role & {
+        permissions: Permission[];
+    }>;
+    updateRole: (roleId: string, data: {
+        name?: string;
+        description?: string | null;
+    }) => Promise<Role>;
+    listGroups: (options?: {
+        limit?: number;
+        offset?: number;
+    }) => Promise<{
+        groups: Group[];
+        total: number;
+    }>;
+    getGroup: (groupId: string) => Promise<Group & {
+        users: FortressUser[];
+    }>;
+    updateGroup: (groupId: string, data: {
+        name?: string;
+        description?: string;
+    }) => Promise<Group>;
+    deleteGroup: (groupId: string) => Promise<void>;
+    getGroupUsers: (groupId: string) => Promise<FortressUser[]>;
+    listPermissions: (options?: {
+        resource?: string;
+    }) => Promise<Permission[]>;
+    createPermission: (permission: PermissionInput) => Promise<Permission>;
+    deletePermission: (permissionId: string) => Promise<void>;
+    addPermissionToRole: (roleId: string, permission: PermissionInput) => Promise<void>;
+    removePermissionFromRole: (roleId: string, permission: PermissionInput) => Promise<void>;
+    createServiceAccount: (input: CreateServiceAccountInput) => Promise<ServiceAccount>;
+    getServiceAccount: (id: string) => Promise<ServiceAccount>;
+    listServiceAccounts: (options?: {
+        limit?: number;
+        offset?: number;
+    }) => Promise<{
+        serviceAccounts: ServiceAccount[];
+        total: number;
+    }>;
+    updateServiceAccount: (id: string, data: {
+        displayName?: string | null;
+        description?: string | null;
+        isActive?: boolean;
+    }) => Promise<ServiceAccount>;
+    deleteServiceAccount: (id: string) => Promise<void>;
+    bindRoleToServiceAccount: (serviceAccountId: string, roleId: string, tenantId?: string) => Promise<void>;
+    /** Unbind across all scopes when omitted, global only for `null`, or one tenant for a string scope. */
+    unbindRoleFromServiceAccount: (serviceAccountId: string, roleId: string, tenantId?: string | null) => Promise<void>;
+    bindPermissionToServiceAccount: (serviceAccountId: string, permission: PermissionInput, tenantId?: string) => Promise<void>;
+    unbindPermissionFromServiceAccount: (serviceAccountId: string, permissionId: string, tenantId?: string | null) => Promise<void>;
+}
+
+/**
+ * Lifecycle event emitted by the auth service. Mirrors the IAM observer
+ * pattern (`addIamObserver`) so consumers — audit log, SIEM webhooks,
+ * telemetry plugins, Datadog adapters — can subscribe to auth events
+ * without reimplementing every hook individually.
+ */
+interface AuthEvent {
+    eventType: 'LOGIN_SUCCESS' | 'LOGIN_FAILURE' | 'LOGIN_PENDING' | 'LOGOUT' | 'REGISTER' | 'TOKEN_REFRESH' | 'TOKEN_REUSE_DETECTED' | 'TOKEN_REUSE_GRACED' | 'TOKEN_FINGERPRINT_MISMATCH' | 'MFA_VERIFY_SUCCESS' | 'MFA_VERIFY_FAILURE' | 'SESSION_EXPIRED_IDLE' | 'SESSION_EXPIRED_ABSOLUTE' | 'PASSWORD_BREACH_CHECK_DEGRADED' | 'IMPERSONATE';
+    actorId?: string;
+    identifier?: string;
+    method?: 'password' | 'oauth' | 'magic_link' | 'webauthn' | '2fa' | 'api_key';
+    ipAddress?: string;
+    userAgent?: string;
+    outcome?: 'success' | 'failure' | 'pending';
+    /** Set on `LOGIN_PENDING` — which additional step the sign-in is waiting on. */
+    pendingReason?: PendingReason;
+    /** Free-form sub-action label (e.g. the specific fingerprint/session action that fired the event). */
+    action?: string;
+    error?: {
+        message: string;
+        code?: string;
+    };
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Async auth event listener. May return a Promise — if you `return` it, any
+ * rejection is routed to `config.logger.error`. Firing work via
+ * `void asyncWork()` inside a sync body is an explicit opt-out of that
+ * safety net; rejections will escape to the runtime's unhandled-rejection
+ * handler instead.
+ */
+type AuthEventListener = (event: AuthEvent) => void | Promise<void>;
+interface AuthService {
+    login: (identifier: string, password: string, meta?: RequestMeta) => Promise<AuthResult>;
+    /** Consume a verified factor's continuation, rerun remaining gates, then issue tokens. */
+    completePendingAuth: (continuationToken: string, completion: unknown, meta?: RequestMeta) => Promise<AuthResult>;
+    /** Finish a trusted plugin-owned primary credential (for example a magic link). */
+    completePluginAuth: (userId: string, method: Exclude<AuthMethod, 'refresh' | 'impersonation'>, meta?: RequestMeta) => Promise<AuthResult>;
+    refresh: (refreshToken: string, meta?: RequestMeta) => Promise<AuthTokenPair>;
+    logout: (refreshToken: string) => Promise<void>;
+    me: (userId: string) => Promise<FortressUser>;
+    createUser: (data: CreateUserInput) => Promise<FortressUser>;
+    verifyToken: (token: string) => Promise<TokenClaims>;
+    signToken: (claims: Omit<TokenClaims, 'iat' | 'exp' | 'aud'>) => Promise<string>;
+    listSessions: (userId: string) => Promise<SessionInfo[]>;
+    revokeSession: (userId: string, tokenId: string) => Promise<void>;
+    revokeAllOtherSessions: (userId: string, currentTokenId: string) => Promise<void>;
+    addLoginIdentifier: (userId: string, type: LoginIdentifierType, value: string) => Promise<void>;
+    removeLoginIdentifier: (userId: string, type: LoginIdentifierType, value: string) => Promise<void>;
+    getLoginIdentifiers: (userId: string) => Promise<LoginIdentifier[]>;
+    /**
+     * Issue a short-lived, non-renewable access token that lets an admin act as another user.
+     * The token carries an RFC 8693 `act` claim identifying the real admin.
+     *
+     * Requires the admin user to hold `fortress:impersonate`. The built-in HTTP route also enforces this via endpoint metadata.
+     */
+    impersonate: (adminUserId: string, targetUserId: string, options?: {
+        reason?: string;
+        expirySeconds?: number;
+    }) => Promise<AuthResult>;
+    listUsers: (options: {
+        limit?: number;
+        offset?: number;
+        search?: string;
+        sortBy?: string;
+        sortDirection?: 'asc' | 'desc';
+    }) => Promise<{
+        users: FortressUser[];
+        total: number;
+    }>;
+    getUserById: (userId: string) => Promise<FortressUser>;
+    updateUser: (userId: string, data: {
+        name?: string;
+        email?: string;
+        isActive?: boolean;
+        password?: string;
+    }) => Promise<FortressUser>;
+    deleteUser: (userId: string) => Promise<void>;
+    /**
+     * Register a listener for auth lifecycle events. Multiple listeners are
+     * supported — each is invoked in registration order. Listener failures
+     * never break auth operations; they are routed to the configured logger
+     * at `error` level. Returns an unsubscribe function.
+     */
+    addAuthObserver: (listener: AuthEventListener) => Unsubscribe;
+}
+
+export { type AttributeValue as A, type Counter as C, type FortressLogger as F, type Histogram as H, type IamEvent as I, type Meter as M, type PermissionCheckEvent as P, type ResourceDefinition as R, type Span as S, type TelemetryProvider as T, type Unsubscribe as U, type Attributes as a, type AuthEvent as b, type AuthEventListener as c, type IamEventListener as d, type PermissionCheckListener as e, type Tracer as f, type IamService as g, type ResourceFile as h, type AuthService as i, parseResourceFile as p };