@db3.ai/app 0.1.0-beta.1 → 0.1.0

package/dist/apps/validateAppDefinitions.js

@@ -0,0 +1,65 @@
+import { normalizeAppNavigation } from './normalizeAppNavigation.js';
+import { isQueueableJobClass, queueableJobName } from '../queue/index.js';
+/** Validates names, contribution ownership and dependency order before any app code is started. */
+export function validateAppDefinitions(definitions, reserved) {
+    const ids = Object.keys(definitions);
+    const tables = new Set();
+    for (const id of ids) {
+        const definition = definitions[id];
+        const manifest = definition.manifest;
+        if (!/^[a-z][a-z0-9_]{0,39}$/.test(id) || /^db3(?:_|$)/.test(id) || reserved.includes(id) || manifest.id !== id)
+            throw new Error(`Invalid or reserved app identifier "${id}".`);
+        if (!manifest.name?.trim() || !/^\d+\.\d+\.\d+$/.test(manifest.version) || !Number.isSafeInteger(manifest.apiVersion ?? 1) || (manifest.apiVersion ?? 1) < 1)
+            throw new Error(`Invalid app manifest for "${id}"; use a stable x.y.z release and a positive API generation.`);
+        if (typeof definition.create !== 'function')
+            throw new Error(`App "${id}" must create a public service.`);
+        const jobs = new Set();
+        for (const Job of definition.jobs ?? []) {
+            if (!isQueueableJobClass(Job) || !Job.jobName?.startsWith(`${id}.`) || jobs.has(queueableJobName(Job)))
+                throw new Error(`Invalid or duplicate job in "${id}"; declare a stable ${id}. jobName.`);
+            jobs.add(queueableJobName(Job));
+        }
+        for (const Model of definition.database?.models ?? []) {
+            if (!Model.table.startsWith(`${id}_`) || tables.has(Model.table))
+                throw new Error(`App "${id}" cannot own table "${Model.table}".`);
+            tables.add(Model.table);
+        }
+        const paths = new Set();
+        for (const route of definition.routes ?? []) {
+            const key = `${route.method} ${route.path}`;
+            if (!['GET', 'POST', 'PUT', 'PATCH', 'DELETE'].includes(route.method) || !/^\/(?:[a-zA-Z0-9_:-]+(?:\/[a-zA-Z0-9_:-]+)*)?$/.test(route.path) || paths.has(key) || typeof route.handle !== 'function')
+                throw new Error(`Invalid or duplicate route "${key}" in "${id}".`);
+            paths.add(key);
+        }
+        try {
+            normalizeAppNavigation({ items: manifest.navigation ?? [] });
+        }
+        catch {
+            throw new Error(`Invalid navigation in "${id}".`);
+        }
+        for (const [dependency, generation] of Object.entries({ ...manifest.requires, ...manifest.optional })) {
+            if (!/^[a-z][a-z0-9_]{0,39}$/.test(dependency) || reserved.includes(dependency) || dependency === id || !Number.isSafeInteger(generation) || generation < 1)
+                throw new Error(`Invalid dependency "${dependency}" in "${id}".`);
+            if (manifest.requires?.[dependency] !== undefined && manifest.optional?.[dependency] !== undefined)
+                throw new Error(`Dependency "${dependency}" is both required and optional in "${id}".`);
+        }
+    }
+    const visiting = new Set();
+    const ordered = new Set();
+    /** Topologically orders available dependencies and rejects composition cycles. */
+    function visit(id) {
+        if (ordered.has(id))
+            return;
+        if (visiting.has(id))
+            throw new Error(`App dependency cycle at "${id}".`);
+        visiting.add(id);
+        for (const dependency of Object.keys({ ...definitions[id].manifest.requires, ...definitions[id].manifest.optional })) {
+            if (definitions[dependency])
+                visit(dependency);
+        }
+        visiting.delete(id);
+        ordered.add(id);
+    }
+    ids.forEach(visit);
+    return [...ordered];
+}

package/dist/apps/vite.d.ts

@@ -0,0 +1 @@
+export { appsPlugin } from './appsPlugin.js';

package/dist/apps/vite.js

@@ -0,0 +1 @@
+export { appsPlugin } from './appsPlugin.js';

package/dist/apps/writeAppTypes.d.ts

@@ -0,0 +1,2 @@
+/** Regenerates optional app().social types from discovery during development and builds, without loading server code. */
+export declare function writeAppTypes(directory: string): Promise<void>;

package/dist/apps/writeAppTypes.js

@@ -0,0 +1,13 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { dirname, join, relative } from 'node:path';
+import { discoverApps } from './discoverApps.js';
+/** Regenerates optional app().social types from discovery during development and builds, without loading server code. */
+export async function writeAppTypes(directory) {
+    const target = join(directory, '.db3/apps.d.ts');
+    const properties = discoverApps(directory).map(app => {
+        const specifier = app.packageName ?? `./${relative(dirname(target), app.entry).replaceAll('\\', '/').replace(/\.ts$/, '.js')}`;
+        return `\t\treadonly ${app.manifest.id}?: InstanceType<typeof import(${JSON.stringify(specifier)}).default>;`;
+    });
+    await mkdir(dirname(target), { recursive: true });
+    await writeFile(target, `// Generated by DB3 app discovery. Do not edit.\nimport '@db3.ai/app/apps/contracts';\ndeclare module '@db3.ai/app/apps/contracts' {\n\tinterface InstalledApps {\n${properties.join('\n')}\n\t}\n}\n`);
+}

package/dist/auth/Auth.d.ts

@@ -246,6 +246,7 @@ 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;
     private fallbackAuthenticatedUser;
     private fallbackAuthenticatedToken;
     private readonly db;
@@ -404,6 +405,8 @@ export declare class Auth<TIdentity extends UserIdentity = UserIdentity> {
     setPasswordProvider(user: TIdentity, password: string): Promise<AuthProvider>;
     /**
      * Changes a user's password provider after verifying the current password.
+     * Password replacement, recovery-link invalidation and revocation of every
+     * bearer session (including the current session) commit together.
      *
      * @param user - User whose password should change.
      * @param currentPassword - Current plaintext password for verification.
@@ -432,6 +435,8 @@ export declare class Auth<TIdentity extends UserIdentity = UserIdentity> {
     createPasswordResetToken(user: TIdentity, options?: PasswordResetTokenOptions): Promise<IssuedPasswordResetToken<TIdentity>>;
     /**
      * Resets the password provider using a valid password reset token.
+     * Serializes recovery for an account and atomically invalidates every existing
+     * session and recovery link. Failed validation leaves credentials unchanged.
      *
      * @param input - Reset token, new password, and optional identity value.
      * @returns Identity whose password changed, or null when redemption fails.
@@ -460,6 +465,19 @@ export declare class Auth<TIdentity extends UserIdentity = UserIdentity> {
      * @returns Active, non-expired sessions ordered newest first.
      */
     tokensFor(user: TIdentity): Promise<AuthToken[]>;
+    /**
+     * Revokes all bearer sessions for an account, including the current device.
+     *
+     * Apps must authorize the supplied account before calling this method. Tokens
+     * are rejected on subsequent requests; already-running requests can finish.
+     * Revoked rows are retained for audit. New sign-ins remain possible.
+     *
+     * @param user - Authorized account whose sessions should end.
+     * @returns Number of previously unrevoked token rows changed, including expired rows.
+     * @example
+     * await app.auth.revokeAllTokens(authenticatedUser);
+     */
+    revokeAllTokens(user: TIdentity): Promise<number>;
     /**
      * Revokes one bearer session owned by a user.
      *

package/dist/auth/Auth.js

@@ -334,6 +334,8 @@ export class Auth {
     }
     /**
      * Changes a user's password provider after verifying the current password.
+     * Password replacement, recovery-link invalidation and revocation of every
+     * bearer session (including the current session) commit together.
      *
      * @param user - User whose password should change.
      * @param currentPassword - Current plaintext password for verification.
@@ -341,9 +343,21 @@ export class Auth {
      * @returns True when the password was changed.
      */
     async changePasswordProvider(user, currentPassword, nextPassword) {
-        return ActiveRecord.withDb(this.db.knex, () => {
-            return this.passwordProvider().changePassword(user, currentPassword, nextPassword);
-        });
+        const userId = this.userPrimaryKey(user);
+        if (!userId)
+            return false;
+        const changed = await this.db.knex.transaction(transaction => ActiveRecord.withDb(transaction, async () => {
+            const lockedUser = await this.#lockIdentity(userId, transaction);
+            if (!lockedUser)
+                return false;
+            if (!await this.passwordProvider().changePassword(lockedUser, currentPassword, nextPassword))
+                return false;
+            await this.#invalidatePasswordRecovery(userId, transaction);
+            return true;
+        }));
+        if (changed)
+            this.#forgetRevokedUser(userId);
+        return changed;
     }
     /**
      * Authenticates through a non-password provider and stores the user on success.
@@ -417,6 +431,8 @@ export class Auth {
     }
     /**
      * Resets the password provider using a valid password reset token.
+     * Serializes recovery for an account and atomically invalidates every existing
+     * session and recovery link. Failed validation leaves credentials unchanged.
      *
      * @param input - Reset token, new password, and optional identity value.
      * @returns Identity whose password changed, or null when redemption fails.
@@ -433,18 +449,55 @@ export class Auth {
         if (!tokenRecord || !tokenRecord.isUsable()) {
             return null;
         }
-        const user = await this.IdentityModel.findByPk(tokenRecord.userId, this.db.knex);
-        if (!user) {
-            return null;
-        }
-        if (!await this.passwordResetIdentityMatches(input, user)) {
+        if (!tokenRecord.userId)
             return null;
+        const user = await this.db.knex.transaction(transaction => ActiveRecord.withDb(transaction, async () => {
+            const lockedUser = await this.#lockIdentity(tokenRecord.userId, transaction);
+            if (!lockedUser)
+                return null;
+            // A locking read sees a competing redemption's committed state after
+            // waiting for the account lock, including under repeatable-read SQL.
+            const row = await this.PasswordResetTokenModel.query(transaction)
+                .where('id', tokenRecord.id).toKnex().forUpdate().first();
+            const current = row ? this.PasswordResetTokenModel.fromDb(row, transaction) : null;
+            if (!current?.isUsable() || !await this.passwordResetIdentityMatches(input, lockedUser))
+                return null;
+            await this.passwordProvider().recoverPassword(lockedUser, input.password);
+            await this.#invalidatePasswordRecovery(tokenRecord.userId, transaction);
+            return lockedUser;
+        }));
+        if (user) {
+            user.setDb(this.db.knex);
+            this.#forgetRevokedUser(this.userPrimaryKey(user));
         }
-        await this.setPasswordProvider(user, input.password);
-        tokenRecord.markUsed();
-        await tokenRecord.save();
         return user;
     }
+    /** Locks the account row to serialize concurrent password replacements. */
+    async #lockIdentity(userId, transaction) {
+        const row = await this.IdentityModel.query(transaction)
+            .where(this.IdentityModel.primaryKey, userId).toKnex().forUpdate().first();
+        return row ? this.IdentityModel.fromDb(row, transaction) : null;
+    }
+    /** Invalidates recovery links and sessions within the password transaction. */
+    async #invalidatePasswordRecovery(userId, transaction) {
+        await this.PasswordResetTokenModel.query(transaction)
+            .where('userId', userId).whereNull('usedAt').patch({ usedAt: new Date() });
+        await this.#revokeTokens(userId, transaction);
+    }
+    /** Applies session revocation on the owning connection or password transaction. */
+    async #revokeTokens(userId, connection) {
+        return this.TokenModel.query(connection)
+            .where('userId', userId).whereNull('revokedAt').patch({ revokedAt: new Date() });
+    }
+    /** Discards cached bearer authentication after committed account revocation. */
+    #forgetRevokedUser(userId) {
+        if (this.requestContext?.active) {
+            const key = `${AUTH_TOKEN_CONTEXT_KEY_PREFIX}.${this.TokenModel.table}.revision`;
+            this.requestContext.set(key, (this.requestContext.get(key) ?? 0) + 1);
+        }
+        if (this.user && this.userPrimaryKey(this.user) === userId)
+            this.logout();
+    }
     /**
      * Creates a bearer token for an already-authenticated identity.
      *
@@ -521,6 +574,26 @@ export class Auth {
             .all();
         return tokens.filter(token => token.isActive());
     }
+    /**
+     * Revokes all bearer sessions for an account, including the current device.
+     *
+     * Apps must authorize the supplied account before calling this method. Tokens
+     * are rejected on subsequent requests; already-running requests can finish.
+     * Revoked rows are retained for audit. New sign-ins remain possible.
+     *
+     * @param user - Authorized account whose sessions should end.
+     * @returns Number of previously unrevoked token rows changed, including expired rows.
+     * @example
+     * await app.auth.revokeAllTokens(authenticatedUser);
+     */
+    async revokeAllTokens(user) {
+        const userId = this.userPrimaryKey(user);
+        if (!userId)
+            return 0;
+        const count = await this.#revokeTokens(userId, this.db.knex);
+        this.#forgetRevokedUser(userId);
+        return count;
+    }
     /**
      * Revokes one bearer session owned by a user.
      *
@@ -564,7 +637,9 @@ export class Auth {
      * @returns Request-context cache key.
      */
     tokenContextKey(tokenHash) {
-        return `${AUTH_TOKEN_CONTEXT_KEY_PREFIX}.${this.TokenModel.table}.${tokenHash}`;
+        const prefix = `${AUTH_TOKEN_CONTEXT_KEY_PREFIX}.${this.TokenModel.table}`;
+        const revision = this.requestContext?.get(`${prefix}.revision`) ?? 0;
+        return `${prefix}.${revision}.${tokenHash}`;
     }
     /**
      * Authenticates a pre-hashed bearer token against persistent auth records.
@@ -838,7 +913,8 @@ export class Auth {
         if (inputIdentity === undefined || inputIdentity === null || inputIdentity === '') {
             return true;
         }
-        const inputUser = await this.findIdentity(input);
+        const inputUser = await this.IdentityModel.query()
+            .where(identityField, inputIdentity).first();
         return inputUser?.get(this.IdentityModel.primaryKey) === user.get(this.IdentityModel.primaryKey);
     }
     /**

package/dist/auth/PasswordLoginAttempt.d.ts

@@ -0,0 +1,50 @@
+import { ActiveRecord, type FieldBuilder } from '../db/index.js';
+/**
+ * Durable failed-password state for any submitted identity, known or unknown.
+ *
+ * The unique normalized identity digest provides a database-wide serialization
+ * point without requiring an account. The normalized submitted email is also
+ * retained so operators can investigate attempts against known or unknown users.
+ * This table is intentionally independent of users and authentication providers.
+ */
+export declare class PasswordLoginAttempt extends ActiveRecord {
+    static table: string;
+    /** Defines the identity key, failure counter and persistent suspension. */
+    static fields(field: FieldBuilder): {
+        id: import("../db/index.js").UlidField;
+        identityHash: import("../db/index.js").StringField;
+        identity: import("../db/index.js").StringField;
+        failedAttempts: import("../db/index.js").IntegerField;
+        suspendedAt: import("../db/index.js").TimestampField;
+        suspensionId: import("../db/index.js").StringField;
+        createdAt: import("../db/index.js").TimestampField;
+        updatedAt: import("../db/index.js").TimestampField;
+    };
+    id: string | null;
+    identityHash: string;
+    /** Readable submitted identity, populated on the next attempt for legacy rows. */
+    identity: string | null;
+    failedAttempts: number;
+    suspendedAt: Date | null;
+    /** Unique occurrence identifier, cleared only by verified password recovery. */
+    suspensionId: string | null;
+    /**
+     * Derives an exact stable key unaffected by the database's email collation.
+     * @param identity - Submitted email or configured password identity.
+     * @returns SHA-256 of the trimmed, lowercase identity.
+     */
+    static identityKey(identity: string): string;
+    /**
+     * Serializes one verification or recovery with every operation for this identity.
+     *
+     * The unique-key upsert handles concurrent first attempts. Locking reads see
+     * the latest committed state, including under repeatable-read isolation.
+     * Nested use during recovery participates through a transaction savepoint.
+     *
+     * Records the normalized identity and latest activity even when already suspended.
+     * @param identity - Password identity, whether or not registered.
+     * @param callback - Operation that may update and save the locked attempt row.
+     * @returns Callback result after its state commits.
+     */
+    static withIdentityLock<TResult>(identity: string, callback: (attempt: PasswordLoginAttempt) => Promise<TResult>): Promise<TResult>;
+}

package/dist/auth/PasswordLoginAttempt.js

@@ -0,0 +1,60 @@
+import { createHash } from 'node:crypto';
+import { ActiveRecord } from '../db/index.js';
+/**
+ * Durable failed-password state for any submitted identity, known or unknown.
+ *
+ * The unique normalized identity digest provides a database-wide serialization
+ * point without requiring an account. The normalized submitted email is also
+ * retained so operators can investigate attempts against known or unknown users.
+ * This table is intentionally independent of users and authentication providers.
+ */
+export class PasswordLoginAttempt extends ActiveRecord {
+    static table = 'auth_password_login_attempts';
+    /** Defines the identity key, failure counter and persistent suspension. */
+    static fields(field) {
+        return {
+            id: field.ulid(),
+            identityHash: field.string({ column: 'identity_hash', required: true, unique: true, length: 64, maxLength: 64, comment: 'SHA-256 of the normalized submitted identity; not tied to account existence.' }),
+            identity: field.string({ length: 255, maxLength: 255, comment: 'Normalized submitted email or configured identity; null for legacy digest-only rows until their next attempt.' }),
+            failedAttempts: field.integer({ column: 'failed_attempts', required: true, unsigned: true, min: 0, default: 0, comment: 'Consecutive wrong passwords for this identity.' }),
+            suspendedAt: field.timestamp({ column: 'suspended_at', comment: 'When password recovery became required; no automatic expiry.' }),
+            suspensionId: field.string({ column: 'suspension_id', length: 36, maxLength: 36, comment: 'Unique suspension occurrence; prevents delayed recovery notices from referring to a later suspension.' }),
+            createdAt: field.timestamp({ column: 'created_at', auto: 'create' }),
+            updatedAt: field.timestamp({ column: 'updated_at', auto: 'both', index: true, comment: 'Latest password sign-in or recovery activity, including refused suspended attempts.' }),
+        };
+    }
+    /**
+     * Derives an exact stable key unaffected by the database's email collation.
+     * @param identity - Submitted email or configured password identity.
+     * @returns SHA-256 of the trimmed, lowercase identity.
+     */
+    static identityKey(identity) {
+        return createHash('sha256').update(identity.trim().toLowerCase()).digest('hex');
+    }
+    /**
+     * Serializes one verification or recovery with every operation for this identity.
+     *
+     * The unique-key upsert handles concurrent first attempts. Locking reads see
+     * the latest committed state, including under repeatable-read isolation.
+     * Nested use during recovery participates through a transaction savepoint.
+     *
+     * Records the normalized identity and latest activity even when already suspended.
+     * @param identity - Password identity, whether or not registered.
+     * @param callback - Operation that may update and save the locked attempt row.
+     * @returns Callback result after its state commits.
+     */
+    static async withIdentityLock(identity, callback) {
+        return this.getDb().transaction(transaction => ActiveRecord.withDb(transaction, async () => {
+            const identityHash = this.identityKey(identity);
+            const candidate = this.create({ identityHash, identity: identity.trim().toLowerCase() });
+            // Framework-level upsert requires Knex; the fields still own every value
+            // and column conversion. Updating activity takes an exclusive key lock;
+            // INSERT IGNORE would take shared locks and can deadlock on FOR UPDATE.
+            await transaction(this.table).insert(await candidate.getDataForDb()).onConflict(this.getFields().identityHash.column).merge([this.getFields().identity.column, this.getFields().updatedAt.column]);
+            const attempt = await this.where('identityHash', identityHash).forUpdate().first();
+            if (!attempt)
+                throw new Error('Unable to lock password login state.');
+            return callback(attempt);
+        }));
+    }
+}

package/dist/auth/PasswordSuspendedError.d.ts

@@ -0,0 +1,10 @@
+import type { PasswordSuspension } from './contracts/index.js';
+/**
+ * Password sign-in for the submitted identity requires email recovery.
+ * The same error is used for existing and unknown emails, with no account data.
+ */
+export declare class PasswordSuspendedError extends Error {
+    readonly suspension: PasswordSuspension | null;
+    /** Creates a generic refusal, optionally carrying a newly committed transition for server use. */
+    constructor(suspension?: PasswordSuspension | null);
+}

package/dist/auth/PasswordSuspendedError.js

@@ -0,0 +1,13 @@
+/**
+ * Password sign-in for the submitted identity requires email recovery.
+ * The same error is used for existing and unknown emails, with no account data.
+ */
+export class PasswordSuspendedError extends Error {
+    suspension;
+    /** Creates a generic refusal, optionally carrying a newly committed transition for server use. */
+    constructor(suspension = null) {
+        super('Too many sign-in attempts. Use password recovery to continue.');
+        this.suspension = suspension;
+        this.name = 'PasswordSuspendedError';
+    }
+}

package/dist/auth/contracts/PasswordAuthProviderOptions.d.ts

@@ -0,0 +1,26 @@
+import type { AuthProvider } from '../AuthProvider.js';
+import type { UserIdentity, UserIdentityModel } from '../UserIdentity.js';
+import type { PasswordHash } from '../passwordHash.js';
+import type { PasswordSuspensionOptions } from './PasswordSuspensionOptions.js';
+/**
+ * Construction options for the password auth provider.
+ */
+export interface PasswordAuthProviderOptions<TIdentity extends UserIdentity = UserIdentity> {
+    /**
+     * User identity model configured for the host app.
+     */
+    identityModel: UserIdentityModel<TIdentity>;
+    /**
+     * Provider-link model configured for the auth service.
+     */
+    providerModel?: typeof AuthProvider;
+    /**
+     * Password hashing service used to verify stored hashes.
+     */
+    passwordHash?: PasswordHash;
+    /**
+     * Failed-password suspension by normalized identity, including unknown identities.
+     * Enabled after 20 attempts by default; `false` disables it.
+     */
+    suspension?: PasswordSuspensionOptions | false;
+}

package/dist/auth/contracts/PasswordAuthProviderOptions.js

@@ -0,0 +1 @@
+export {};

package/dist/auth/contracts/PasswordSuspension.d.ts

@@ -0,0 +1,7 @@
+/** Identifies a newly committed suspension so an application can enqueue recovery notices. */
+export interface PasswordSuspension {
+    /** Attempt-state record, equally available for registered and unknown identities. */
+    attemptId: string;
+    /** Unique suspension occurrence; changes after recovery and a later suspension. */
+    suspensionId: string;
+}

package/dist/auth/contracts/PasswordSuspension.js

@@ -0,0 +1 @@
+export {};

package/dist/auth/contracts/PasswordSuspensionOptions.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Persistent suspension policy for submitted password identities.
+ *
+ * Known and unknown emails share the same threshold. Only completed password
+ * recovery clears suspension; this policy deliberately has no timed unlock.
+ */
+export interface PasswordSuspensionOptions {
+    /** Consecutive failures before recovery is required. Defaults to 20. */
+    maxFailedAttempts?: number;
+}

package/dist/auth/contracts/PasswordSuspensionOptions.js

@@ -0,0 +1 @@
+export {};

package/dist/auth/contracts/index.d.ts

@@ -1 +1,4 @@
 export * from './AuthProviderDriver.js';
+export * from './PasswordSuspensionOptions.js';
+export * from './PasswordSuspension.js';
+export * from './PasswordAuthProviderOptions.js';

package/dist/auth/contracts/index.js

@@ -1 +1,4 @@
 export * from './AuthProviderDriver.js';
+export * from './PasswordSuspensionOptions.js';
+export * from './PasswordSuspension.js';
+export * from './PasswordAuthProviderOptions.js';

package/dist/auth/index.d.ts

@@ -2,6 +2,8 @@ export * from './Auth.js';
 export * from './AuthProvider.js';
 export * from './AuthToken.js';
 export * from './contracts/index.js';
+export * from './PasswordSuspendedError.js';
+export * from './PasswordLoginAttempt.js';
 export * from './PasswordResetToken.js';
 export * from './passwordHash.js';
 export * from './providers/index.js';

package/dist/auth/index.js

@@ -2,6 +2,8 @@ export * from './Auth.js';
 export * from './AuthProvider.js';
 export * from './AuthToken.js';
 export * from './contracts/index.js';
+export * from './PasswordSuspendedError.js';
+export * from './PasswordLoginAttempt.js';
 export * from './PasswordResetToken.js';
 export * from './passwordHash.js';
 export * from './providers/index.js';

package/dist/auth/providers/PasswordAuthProvider.d.ts

@@ -1,25 +1,7 @@
 import { AuthProvider } from '../AuthProvider.js';
 import type * as auth from '../contracts/index.js';
 import type { PasswordCredentials } from '../Auth.js';
-import type { UserIdentity, UserIdentityModel } from '../UserIdentity.js';
-import { type PasswordHash } from '../passwordHash.js';
-/**
- * Construction options for the password auth provider.
- */
-export interface PasswordAuthProviderOptions<TIdentity extends UserIdentity = UserIdentity> {
-    /**
-     * User identity model configured for the host app.
-     */
-    identityModel: UserIdentityModel<TIdentity>;
-    /**
-     * Provider-link model configured for the auth service.
-     */
-    providerModel?: typeof AuthProvider;
-    /**
-     * Password hashing service used to verify stored hashes.
-     */
-    passwordHash?: PasswordHash;
-}
+import type { UserIdentity } from '../UserIdentity.js';
 /**
  * Provider driver for first-party email and password authentication.
  *
@@ -28,6 +10,7 @@ export interface PasswordAuthProviderOptions<TIdentity extends UserIdentity = Us
  * plus a valid password hash stored on `auth_providers`.
  */
 export declare class PasswordAuthProvider<TIdentity extends UserIdentity = UserIdentity> implements auth.AuthProviderDriver<PasswordCredentials, TIdentity> {
+    #private;
     readonly provider = "password";
     private readonly IdentityModel;
     private readonly ProviderModel;
@@ -37,14 +20,27 @@ export declare class PasswordAuthProvider<TIdentity extends UserIdentity = UserI
      *
      * @param options - Password provider dependencies configured at app startup.
      */
-    constructor(options: PasswordAuthProviderOptions<TIdentity>);
+    constructor(options: auth.PasswordAuthProviderOptions<TIdentity>);
     /**
-     * Verifies submitted password credentials against the stored provider row.
+     * Verifies credentials under the identity's durable attempt lock.
      *
-     * @param input - Submitted password credential payload.
-     * @returns Normalized password provider profile, or null when verification fails.
+     * Unknown identities receive the same failed-attempt accounting and password
+     * hashing work as existing accounts. Suspension persists until verified
+     * password recovery; a correct password cannot clear a suspended identity.
+     *
+     * @param input - Submitted password credentials.
+     * @returns Verified provider profile, or null for an invalid password.
+     * @throws {PasswordSuspendedError} When this identity needs password recovery.
      */
     verify(input: PasswordCredentials): Promise<auth.AuthProviderProfile | null>;
+    /**
+     * Replaces a verified owner's password and clears suspension atomically.
+     * Called by Auth only after a usable, identity-matched recovery token is locked.
+     * @param user - Account whose email recovery proof was verified.
+     * @param password - Replacement plaintext password.
+     * @returns Saved password provider.
+     */
+    recoverPassword(user: TIdentity, password: string): Promise<AuthProvider>;
     /**
      * Creates or replaces the password provider for a user.
      *