@db3.ai/app 0.1.0-beta.1

package/dist/auth/Auth.d.ts

@@ -0,0 +1,641 @@
+import { type Database } from '../db/index.js';
+import type { Config } from '../config/index.js';
+import { AuthProvider } from './AuthProvider.js';
+import { AuthToken, type AuthTokenUsage, type CreateAuthTokenOptions } from './AuthToken.js';
+import { PasswordResetToken } from './PasswordResetToken.js';
+import { type PasswordHash } from './passwordHash.js';
+import { UserIdentity, type UserIdentityModel } from './UserIdentity.js';
+import type * as auth from './contracts/index.js';
+/**
+ * Credentials accepted by the built-in password provider.
+ *
+ * Apps may include the configured identity field, usually `email`, alongside
+ * the password so the auth service can locate the provider row.
+ */
+export interface PasswordCredentials {
+    /**
+     * Plaintext password submitted by the user.
+     */
+    password: string;
+    /**
+     * Additional credential fields, including the configured identity value.
+     */
+    [fieldName: string]: unknown;
+}
+/**
+ * Input used when creating a user through the built-in password provider.
+ */
+export interface RegisterPasswordInput extends PasswordCredentials {
+    /**
+     * Additional user fields accepted by the configured identity model.
+     */
+    [fieldName: string]: unknown;
+}
+/**
+ * Backwards-compatible alias for password credentials.
+ */
+export type AuthCredentials = PasswordCredentials;
+/**
+ * Backwards-compatible alias for password registration input.
+ */
+export type RegisterIdentityInput = RegisterPasswordInput;
+/**
+ * Request payload used to redeem a password reset token.
+ *
+ * Additional fields allow apps to include the configured identity value, such
+ * as an email address, so token redemption can confirm the link belongs to the
+ * submitted identity.
+ */
+export interface ResetPasswordInput {
+    [fieldName: string]: unknown;
+    token: string;
+    password: string;
+}
+/**
+ * Bearer token issued for an authenticated user.
+ */
+export interface IssuedAuthToken<TIdentity extends UserIdentity = UserIdentity> {
+    /**
+     * Token type used in HTTP Authorization headers.
+     */
+    type: 'Bearer';
+    /**
+     * Plaintext bearer token shown once to the caller.
+     */
+    token: string;
+    /**
+     * Absolute expiry time, or null for a non-expiring token.
+     */
+    expiresAt: Date | null;
+    /**
+     * Authenticated identity the token belongs to.
+     */
+    user: TIdentity;
+}
+/**
+ * Password reset token issued for an identity.
+ */
+export interface IssuedPasswordResetToken<TIdentity extends UserIdentity = UserIdentity> {
+    /**
+     * Token purpose marker.
+     */
+    type: 'password_reset';
+    /**
+     * Plaintext reset token shown once to the caller.
+     */
+    token: string;
+    /**
+     * Absolute expiry time for the reset token.
+     */
+    expiresAt: Date;
+    /**
+     * Identity the reset token belongs to.
+     */
+    user: TIdentity;
+}
+/**
+ * Options used when issuing a bearer token.
+ */
+export interface AuthTokenOptions extends CreateAuthTokenOptions {
+    /**
+     * Relative token lifetime in milliseconds. Null disables token expiry.
+     */
+    expiresInMs?: number | null;
+}
+export interface PasswordResetTokenOptions {
+    /**
+     * Absolute timestamp when the token should stop being usable.
+     */
+    expiresAt?: Date;
+    /**
+     * Relative token lifetime in milliseconds when an absolute expiry is not supplied.
+     */
+    expiresInMs?: number;
+}
+/**
+ * Initial values accepted by an auth request context.
+ */
+export type AuthRequestContextValues = Map<string, unknown> | Record<string, unknown> | Iterable<readonly [string, unknown]>;
+/**
+ * Request-scoped storage used to isolate auth state between concurrent requests.
+ */
+export interface AuthRequestContext {
+    /**
+     * True when code is running inside an active request context.
+     */
+    active: boolean;
+    /**
+     * Runs a callback with optional initial request-scoped values.
+     *
+     * @param callback - Work to run inside the request context.
+     * @param initialValues - Optional values to seed into the context.
+     * @returns The callback result.
+     */
+    run<TResult>(callback: () => TResult, initialValues?: AuthRequestContextValues): TResult;
+    /**
+     * Reads a request-scoped value.
+     *
+     * @param key - Context key to read.
+     * @returns Stored value, or undefined when missing.
+     */
+    get<TValue = unknown>(key: string): TValue | undefined;
+    /**
+     * Stores a request-scoped value.
+     *
+     * @param key - Context key to write.
+     * @param value - Value to store.
+     * @returns The stored value.
+     */
+    set<TValue>(key: string, value: TValue): TValue;
+    /**
+     * Reads a value or stores the factory result when missing.
+     *
+     * @param key - Context key to read or populate.
+     * @param factory - Factory used when no value has been stored.
+     * @returns Existing or newly-created value.
+     */
+    remember<TValue>(key: string, factory: () => TValue): TValue;
+}
+/**
+ * Runtime options for the framework auth service.
+ */
+export interface AuthOptions<TIdentity extends UserIdentity = UserIdentity> {
+    /**
+     * Database wrapper used for auth persistence.
+     */
+    db: Database;
+    /**
+     * User identity model for the host app.
+     */
+    identityModel?: UserIdentityModel<TIdentity>;
+    /**
+     * Provider-link model. Override only when extending provider persistence.
+     */
+    providerModel?: typeof AuthProvider;
+    /**
+     * Authentication providers enabled for the app.
+     */
+    providers?: auth.AuthProviderRegistry<TIdentity>;
+    /**
+     * App config repository used to read `auth.providers` when explicit
+     * providers are not supplied.
+     */
+    config?: Config;
+    /**
+     * Password hashing service for password provider credentials.
+     */
+    passwordHash?: PasswordHash;
+    /**
+     * Bearer token model.
+     */
+    tokenModel?: typeof AuthToken;
+    /**
+     * Default bearer token lifetime in milliseconds. Null disables expiry.
+     */
+    tokenLifetimeMs?: number | null;
+    /**
+     * Password reset token model.
+     */
+    passwordResetTokenModel?: typeof PasswordResetToken;
+    /**
+     * Default password reset token lifetime in milliseconds.
+     */
+    passwordResetTokenLifetimeMs?: number;
+    /**
+     * Request context used to isolate current-user state.
+     */
+    requestContext?: AuthRequestContext;
+}
+/**
+ * Error thrown when registration would duplicate an existing identity.
+ */
+export declare class AuthIdentityExistsError extends Error {
+    readonly field: string;
+    readonly value: unknown;
+    /**
+     * Creates an identity duplication error.
+     *
+     * @param field - Logical identity field that collided.
+     * @param value - Submitted identity value.
+     */
+    constructor(field: string, value: unknown);
+}
+/**
+ * Error thrown when code attempts to use a disabled auth provider.
+ */
+export declare class AuthProviderNotConfiguredError extends Error {
+    readonly provider: string;
+    /**
+     * Creates a provider configuration error.
+     *
+     * @param provider - Provider name that is not enabled.
+     */
+    constructor(provider: string);
+}
+/**
+ * Error thrown when unlinking a provider would leave a user unable to log in.
+ */
+export declare class AuthLastProviderError extends Error {
+    /**
+     * Creates a last-provider removal error.
+     */
+    constructor();
+}
+export declare const AUTH_USER_CONTEXT_KEY = "auth.user";
+/**
+ * Authentication service for the current app/request scope.
+ */
+export declare class Auth<TIdentity extends UserIdentity = UserIdentity> {
+    private fallbackAuthenticatedUser;
+    private fallbackAuthenticatedToken;
+    private readonly db;
+    private readonly IdentityModel;
+    private readonly ProviderModel;
+    private readonly TokenModel;
+    private readonly PasswordResetTokenModel;
+    private readonly providerRegistry;
+    private readonly passwordHash;
+    private readonly tokenLifetimeMs;
+    private readonly passwordResetTokenLifetimeMs;
+    private readonly requestContext?;
+    /**
+     * Creates an auth service bound to a database and provider registry.
+     *
+     * @param options - Auth runtime options.
+     */
+    constructor(options: AuthOptions<TIdentity>);
+    /**
+     * Hashes a plaintext password using the configured auth password service.
+     *
+     * @param plainText - Plaintext password to hash.
+     * @returns Stored password hash.
+     */
+    hashPassword(plainText: string): Promise<string>;
+    /**
+     * Verifies a plaintext password against a stored password hash.
+     *
+     * @param plainText - Plaintext password supplied by the user.
+     * @param hash - Stored password hash.
+     * @returns True when the password matches.
+     */
+    verifyPassword(plainText: string, hash: string): Promise<boolean>;
+    /**
+     * Returns configured authentication provider names.
+     *
+     * @returns Enabled provider names.
+     */
+    configuredProviders(): string[];
+    /**
+     * True when a user is currently authenticated.
+     */
+    get check(): boolean;
+    /**
+     * The currently authenticated user, or null when no user is authenticated.
+     */
+    get user(): TIdentity | null;
+    /**
+     * Returns the bearer-token record authenticated for the current request.
+     */
+    get token(): AuthToken | null;
+    /**
+     * Runs work inside an isolated auth scope.
+     *
+     * HTTP routes should use this so `auth.user` cannot bleed between concurrent
+     * requests on the shared app singleton.
+     *
+     * @param user - User to expose as authenticated inside the callback.
+     * @param callback - Work to run inside the auth scope.
+     * @returns The callback result.
+     */
+    runWithUser<TResult>(user: TIdentity | null, callback: () => TResult): TResult;
+    /**
+     * Attempts to authenticate password credentials and stores the user on success.
+     *
+     * @param credentials - Password provider credentials.
+     * @returns True when credentials authenticated successfully.
+     */
+    attempt(credentials: PasswordCredentials): Promise<boolean>;
+    /**
+     * Authenticates password credentials and returns the user on success.
+     *
+     * @param credentials - Password provider credentials.
+     * @returns Authenticated user, or null when credentials fail.
+     */
+    authenticate(credentials: PasswordCredentials): Promise<TIdentity | null>;
+    /**
+     * Authenticates password credentials and returns the user on success.
+     *
+     * @param credentials - Password provider credentials.
+     * @returns Authenticated user, or null when credentials fail.
+     */
+    authenticatePassword(credentials: PasswordCredentials): Promise<TIdentity | null>;
+    /**
+     * Authenticates credentials and creates a bearer token on success.
+     *
+     * @param credentials - Password provider credentials.
+     * @param options - Token creation options.
+     * @returns Issued token, or null when credentials fail.
+     */
+    issueToken(credentials: PasswordCredentials, options?: AuthTokenOptions): Promise<IssuedAuthToken<TIdentity> | null>;
+    /**
+     * Authenticates password credentials and creates a bearer token on success.
+     *
+     * @param credentials - Password provider credentials.
+     * @param options - Token creation options.
+     * @returns Issued token, or null when credentials fail.
+     */
+    issueTokenForPassword(credentials: PasswordCredentials, options?: AuthTokenOptions): Promise<IssuedAuthToken<TIdentity> | null>;
+    /**
+     * Authenticates through a configured provider and creates a bearer token.
+     *
+     * @param provider - Configured provider name.
+     * @param input - Provider-specific credential payload.
+     * @param options - Token creation options.
+     * @returns Issued token, or null when provider verification fails.
+     */
+    issueTokenForProvider(provider: string, input: unknown, options?: AuthTokenOptions): Promise<IssuedAuthToken<TIdentity> | null>;
+    /**
+     * Creates a new password-backed identity and returns its first bearer token.
+     *
+     * @param input - User fields and password provider credential.
+     * @param options - Token creation options.
+     * @returns Issued token for the new user.
+     */
+    register(input: RegisterPasswordInput, options?: AuthTokenOptions): Promise<IssuedAuthToken<TIdentity>>;
+    /**
+     * Creates a new user and links the built-in password provider.
+     *
+     * @param input - User fields and password provider credential.
+     * @param options - Token creation options.
+     * @returns Issued token for the new user.
+     */
+    registerWithPassword(input: RegisterPasswordInput, options?: AuthTokenOptions): Promise<IssuedAuthToken<TIdentity>>;
+    /**
+     * Returns the authentication providers linked to a user.
+     *
+     * @param user - User whose providers should be loaded.
+     * @returns Provider rows linked to the user.
+     */
+    providersFor(user: TIdentity): Promise<AuthProvider[]>;
+    /**
+     * Links a configured provider to an existing user.
+     *
+     * @param user - User receiving the new provider link.
+     * @param provider - Configured provider name.
+     * @param input - Provider-specific credential payload.
+     * @returns Linked provider row, or null when verification fails.
+     */
+    linkProvider(user: TIdentity, provider: string, input: unknown): Promise<AuthProvider | null>;
+    /**
+     * Removes one provider from a user while preserving at least one login path.
+     *
+     * @param user - User whose provider should be removed.
+     * @param providerIdOrName - Provider row id or provider name to remove.
+     * @returns True when a provider row was deleted.
+     */
+    unlinkProvider(user: TIdentity, providerIdOrName: string): Promise<boolean>;
+    /**
+     * Creates or replaces the built-in password provider for a user.
+     *
+     * @param user - User who owns the password provider.
+     * @param password - New plaintext password to hash and store.
+     * @returns Saved password provider row.
+     */
+    setPasswordProvider(user: TIdentity, password: string): Promise<AuthProvider>;
+    /**
+     * Changes a user's password provider after verifying the current password.
+     *
+     * @param user - User whose password should change.
+     * @param currentPassword - Current plaintext password for verification.
+     * @param nextPassword - Replacement plaintext password.
+     * @returns True when the password was changed.
+     */
+    changePasswordProvider(user: TIdentity, currentPassword: string, nextPassword: string): Promise<boolean>;
+    /**
+     * Authenticates through a non-password provider and stores the user on success.
+     *
+     * @param provider - Configured provider name.
+     * @param input - Provider-specific credential payload.
+     * @returns Authenticated user, or null when verification fails.
+     */
+    authenticateProvider(provider: string, input: unknown): Promise<TIdentity | null>;
+    /**
+     * Creates a single-use password reset token for an already-loaded identity.
+     *
+     * Callers should find the identity at the request boundary and pass the
+     * loaded model here so token creation only owns token persistence.
+     *
+     * @param user - Identity receiving the reset token.
+     * @param options - Reset token creation options.
+     * @returns Issued password reset token.
+     */
+    createPasswordResetToken(user: TIdentity, options?: PasswordResetTokenOptions): Promise<IssuedPasswordResetToken<TIdentity>>;
+    /**
+     * Resets the password provider using a valid password reset token.
+     *
+     * @param input - Reset token, new password, and optional identity value.
+     * @returns Identity whose password changed, or null when redemption fails.
+     */
+    resetPassword(input: ResetPasswordInput): Promise<TIdentity | null>;
+    /**
+     * Creates a bearer token for an already-authenticated identity.
+     *
+     * @param user - Identity receiving the bearer token.
+     * @param options - Token creation options.
+     * @returns Issued bearer token.
+     */
+    createToken(user: TIdentity, options?: AuthTokenOptions): Promise<IssuedAuthToken<TIdentity>>;
+    /**
+     * Authenticates a bearer token and stores the matching identity on success.
+     *
+     * @param token - Plaintext bearer token.
+     * @param usage - Request metadata observed while authenticating the token.
+     * @returns Authenticated identity, or null when the token is invalid.
+     */
+    authenticateToken(token: string, usage?: AuthTokenUsage): Promise<TIdentity | null>;
+    /**
+     * Returns active bearer sessions belonging to a user.
+     *
+     * @param user - Account whose sessions should be listed.
+     * @returns Active, non-expired sessions ordered newest first.
+     */
+    tokensFor(user: TIdentity): Promise<AuthToken[]>;
+    /**
+     * Revokes one bearer session owned by a user.
+     *
+     * @param user - Account that owns the session.
+     * @param tokenId - Auth token primary key.
+     * @returns True when an active session was revoked.
+     */
+    revokeToken(user: TIdentity, tokenId: string): Promise<boolean>;
+    /**
+     * Revokes the bearer session authenticated for the current request.
+     *
+     * @returns True when the current session was revoked.
+     */
+    revokeCurrentToken(): Promise<boolean>;
+    /**
+     * Builds the request-context key used to memoize bearer-token authentication.
+     *
+     * @param tokenHash - Hashed bearer token.
+     * @returns Request-context cache key.
+     */
+    private tokenContextKey;
+    /**
+     * Authenticates a pre-hashed bearer token against persistent auth records.
+     *
+     * @param tokenHash - Hashed bearer token.
+     * @returns Authenticated identity, or null when the token is invalid.
+     */
+    private authenticateTokenHash;
+    /**
+     * Marks a user model as authenticated.
+     *
+     * @param user - User to mark as authenticated.
+     * @returns The saved authenticated user.
+     */
+    login(user: TIdentity): Promise<TIdentity>;
+    /**
+     * Clears the authenticated user.
+     */
+    logout(): void;
+    /**
+     * Returns the authenticated user or throws when auth is missing.
+     *
+     * @returns The current authenticated user.
+     */
+    requireUser(): TIdentity;
+    /**
+     * Verifies provider-specific input and normalizes the returned profile.
+     *
+     * @param provider - Configured provider name.
+     * @param input - Provider-specific credential payload.
+     * @param user - Current user when linking a provider.
+     * @returns Normalized provider profile, or null when verification fails.
+     */
+    private verifyProvider;
+    /**
+     * Resolves a configured provider or throws a configuration error.
+     *
+     * @param provider - Provider name to resolve.
+     * @returns Provider configuration.
+     */
+    private requireProvider;
+    /**
+     * Resolves the configured password provider.
+     *
+     * @returns Password provider driver with password mutation helpers.
+     */
+    private passwordProvider;
+    /**
+     * Saves a verified provider profile onto a user account.
+     *
+     * @param user - User receiving the provider link.
+     * @param profile - Verified provider profile.
+     * @returns Saved provider row.
+     */
+    private saveLinkedProvider;
+    /**
+     * Finds a provider row by provider-owned identity.
+     *
+     * @param provider - Provider name.
+     * @param providerUserId - Provider-owned account id.
+     * @returns Matching provider row, or null.
+     */
+    private findProvider;
+    /**
+     * Loads the user attached to a provider row.
+     *
+     * @param provider - Persisted provider row.
+     * @returns Linked identity, or null when missing.
+     */
+    private userForProvider;
+    /**
+     * Creates a user account from a verified external provider profile.
+     *
+     * @param profile - Verified provider profile.
+     * @returns Created identity, or null when no email is available.
+     */
+    private createIdentityForProvider;
+    /**
+     * Backfills account-owned profile fields from a verified provider profile.
+     *
+     * Provider values are defaults only. Existing account values are preserved
+     * so a later user-selected avatar is not overwritten during provider login.
+     * The normal login save persists any backfilled values.
+     *
+     * @param user - Authenticated account receiving missing defaults.
+     * @param profile - Verified provider profile.
+     */
+    private applyProviderProfileDefaults;
+    /**
+     * Stores the current authenticated user in request or fallback scope.
+     *
+     * @param user - User to expose as authenticated.
+     */
+    private setAuthenticatedUser;
+    /**
+     * Stores the authenticated token in request or fallback scope.
+     *
+     * @param token - Token record to expose for session management.
+     */
+    private setAuthenticatedToken;
+    /**
+     * Runs a callback with a temporary fallback user outside request scope.
+     *
+     * @param user - User to expose during the callback.
+     * @param callback - Work to run with the temporary user.
+     * @returns The callback result.
+     */
+    private runWithFallbackUser;
+    /**
+     * Finds an identity by the configured identity field.
+     *
+     * @param input - Payload containing the configured identity value.
+     * @returns Matching identity, or null.
+     */
+    private findIdentity;
+    /**
+     * Checks whether password reset input belongs to the loaded user.
+     *
+     * @param input - Reset password payload.
+     * @param user - User loaded from the reset token.
+     * @returns True when the submitted identity is absent or matches the token user.
+     */
+    private passwordResetIdentityMatches;
+    /**
+     * Reads a user primary key as a non-empty string.
+     *
+     * @param user - User model to inspect.
+     * @returns Primary key string, or null when missing.
+     */
+    private userPrimaryKey;
+    /**
+     * Reads the configured identity value from a user.
+     *
+     * @param user - User model to inspect.
+     * @returns Normalized identity value, or null when missing.
+     */
+    private userIdentityValue;
+    /**
+     * Reads the configured identity value from a payload.
+     *
+     * @param input - Payload to inspect.
+     * @returns Normalized identity value, or null when missing.
+     */
+    private normalizedIdentity;
+    /**
+     * Calculates the default bearer token expiry.
+     *
+     * @param expiresInMs - Optional token lifetime override.
+     * @returns Absolute expiry time, or null for a non-expiring token.
+     */
+    private defaultTokenExpiry;
+    /**
+     * Calculates the default password reset token expiry.
+     *
+     * @param expiresInMs - Optional reset token lifetime override.
+     * @returns Absolute expiry time.
+     */
+    private defaultPasswordResetTokenExpiry;
+}