najm-auth 2.0.14 → 3.0.0

package/dist/index.d.ts

@@ -3,18 +3,80 @@ import { Container } from 'najm-core';
 import { ValidationPluginConfig } from 'najm-validation';
 import { RateLimitPluginConfig } from 'najm-rate';
 import { EmailPluginConfig, EmailService } from 'najm-email';
+import { R as ResolvedIdentityConfig, I as IdentityConfig, T as TemporaryCredentialInput } from './ma-sNHnUGLO.js';
+export { D as DEFAULT_IDENTITY_PRESET, E as EXACT_TEMPORARY_CREDENTIAL_KIND, a as IDENTITY_PRESETS, b as IdentityNormalizer, c as IdentityPreset, d as IdentityPresetName, M as MOROCCAN_CIN_TEMPORARY_CREDENTIAL_KIND, e as TemporaryCredential, f as TemporaryCredentialKind, g as compactPhone, i as isMoroccanCin, h as isTemporaryCredentialKind, m as moroccanCinTemporaryCredential, j as moroccoIdentityPreset, n as normalizeMoroccanCin, k as normalizeMoroccanPhone, l as normalizeTunisianPhone, r as resolveTemporaryCredentialKind, t as toTemporaryCredential, o as tunisiaIdentityPreset } from './ma-sNHnUGLO.js';
+import { ZodType, z } from 'zod';
 import { I18nService } from 'najm-i18n';
 import { TDb, SeedEntry } from 'najm-database';
 import { User, NewUser, RoleEntity, NewRoleEntity, Permission, NewPermission, RolePermission } from './schema/pg.js';
-export { CredentialSetupSession, NewCredentialSetupSession, NewOAuthAccount, NewRolePermission, NewToken, OAuthAccount, Token, authSchema, baseFields, credentialSetupSessionsTable, oauthAccountsTable, permissionsTable, rolePermissionsTable, rolesTable, tokenStatusEnum, tokenTypeEnum, tokensTable, userStatusEnum, usersTable } from './schema/pg.js';
+export { CredentialSetupRequirement, CredentialSetupSession, NewCredentialSetupRequirement, NewCredentialSetupSession, NewOAuthAccount, NewRolePermission, NewToken, OAuthAccount, Token, authSchema, baseFields, credentialSetupRequirementsTable, credentialSetupSessionsTable, oauthAccountsTable, permissionsTable, rolePermissionsTable, rolesTable, tokenStatusEnum, tokenTypeEnum, tokensTable, userStatusEnum, usersTable } from './schema/pg.js';
 import { CacheService } from 'najm-cache';
-import { z } from 'zod';
+import { CookieService } from 'najm-cookies';
 import { Context } from 'hono';
 import { GuardResult } from 'najm-guard';
-import { CookieService } from 'najm-cookies';
 import 'drizzle-orm';
 import 'drizzle-orm/pg-core';
 
+interface CredentialSetupOptions {
+    /** Stable server-owned purpose, for example `password`. */
+    purpose: string;
+    /** HttpOnly browser-session cookie name (default: `najm.credential-setup`). */
+    cookieName?: string;
+    /** Session lifetime in milliseconds (default: 10 minutes, maximum: 24 hours). */
+    ttlMs?: number;
+    /** Cookie path (default: `/`). */
+    cookiePath?: string;
+}
+interface CredentialSetupSessionInfo {
+    userId: string;
+    purpose: string;
+    expiresAt: string;
+}
+interface CredentialSetupStarted {
+    purpose: string;
+    expiresAt: string;
+}
+/** The built-in setup purpose Najm mounts endpoints for. */
+declare const PASSWORD_SETUP_PURPOSE = "password";
+/** Durable "this user still owes a setup purpose" row. */
+interface CredentialSetupRequirementRow {
+    userId: string;
+    purpose: string;
+    temporaryCredentialKind: string | null;
+    required: boolean;
+    completedAt: string | null;
+}
+/**
+ * Login answer when the account may not have a normal session yet. Carries no
+ * access or refresh token — only the fact that setup is pending and until when.
+ */
+interface CredentialSetupPending {
+    nextStep: 'credential_setup';
+    setupRequired: true;
+    purpose: string;
+    expiresAt: string;
+}
+interface CredentialSetupPasswordOptions {
+    /**
+     * Replacement-password schema. Default: 8–72 bytes with at least one letter
+     * and one digit — deliberately case-agnostic, because a first-login
+     * replacement is typed by someone who just proved they own the account.
+     */
+    passwordSchema?: ZodType<string>;
+    /** Setup-session lifetime in milliseconds (default: 10 minutes). */
+    ttlMs?: number;
+    /** Setup cookie name (default: `najm.credential-setup`). */
+    cookieName?: string;
+}
+interface CredentialSetupConfig {
+    password?: CredentialSetupPasswordOptions;
+}
+interface ResolvedCredentialSetupConfig {
+    password: Required<Pick<CredentialSetupPasswordOptions, 'ttlMs' | 'cookieName'>> & {
+        passwordSchema: ZodType<string>;
+    };
+}
+
 /**
  * JWT configuration for token generation and verification
  */
@@ -115,8 +177,12 @@ interface AuthConfig {
     lockout: LockoutConfig;
     /** Bcrypt work factor (default: 10) */
     bcryptRounds: number;
+    /** Server-scoped login and phone identity policy. */
+    identity: ResolvedIdentityConfig;
     /** Session cookie cache settings */
     session: SessionCookieConfig;
+    /** Resolved credential-setup policy for the built-in `password` flow. */
+    credentialSetup: ResolvedCredentialSetupConfig;
     /** Resolved external identity-provider configuration. */
     oauth?: ResolvedOAuthConfig;
 }
@@ -133,6 +199,8 @@ interface AuthSchema {
     tokens: any;
     /** Durable one-time browser sessions used by CredentialSetupService. */
     credentialSetupSessions?: any;
+    /** Durable "this user still owes a setup purpose" rows. */
+    credentialSetupRequirements?: any;
     roles: any;
     permissions: any;
     rolePermissions: any;
@@ -176,6 +244,18 @@ type AuthPluginConfig = {
     bcryptRounds?: number;
     /** Session cookie cache settings (optional — sensible defaults applied) */
     session?: Partial<SessionCookieConfig>;
+    /**
+     * Login identifier normalization. Defaults to the Moroccan preset; pass
+     * another preset to replace it, or `extend` for project-specific
+     * identifiers.
+     */
+    identity?: IdentityConfig;
+    /**
+     * Policy overrides for the built-in credential-setup flow. The flow itself
+     * is always mounted — there is no activation switch — and does nothing until
+     * a user has a durable setup requirement.
+     */
+    credentialSetup?: CredentialSetupConfig;
     /** Optional config forwarded to validation() dependency */
     validation?: ValidationPluginConfig;
     /** Optional config forwarded to rateLimit() dependency */
@@ -272,7 +352,15 @@ var auth = {
 		oauthProviderAccountLinked: "This Google account is already linked.",
 		oauthSignupDisabled: "Registration with Google is disabled.",
 		oauthHostedDomainDenied: "This Google Workspace domain is not allowed.",
-		oauthLinkSessionExpired: "Your session changed before Google could be linked. Please try again."
+		oauthLinkSessionExpired: "Your session changed before Google could be linked. Please try again.",
+		oauthCredentialSetupRequired: "Set a new password before signing in with Google.",
+		credentialSetupRequired: "Set a new password before continuing.",
+		credentialSetupSessionRequired: "Credential setup session is required.",
+		credentialSetupSessionInvalid: "Credential setup session is invalid or expired.",
+		credentialSetupAlreadyCompleted: "The password was already replaced. Please sign in again.",
+		credentialSetupPasswordRejected: "Choose a different password.",
+		credentialSetupTemporaryShape: "Choose a password that is not your temporary credential.",
+		credentialSetupSamePassword: "Choose a password different from your current one."
 	},
 	success: {
 		login: "Login successful",
@@ -285,7 +373,10 @@ var auth = {
 		tokenRefreshed: "Token refreshed successfully",
 		sessionRecovered: "Session recovered successfully",
 		oauthLogin: "Google sign-in successful",
-		oauthLinked: "Google account linked successfully"
+		oauthLinked: "Google account linked successfully",
+		credentialSetupPending: "Password setup is required",
+		credentialSetupPasswordReplaced: "Password set successfully",
+		credentialSetupCancelled: "Password setup cancelled"
 	},
 	emails: {
 		passwordReset: {
@@ -301,6 +392,7 @@ var users = {
 		notFound: "User not found",
 		idExists: "User ID already exists",
 		emailRequired: "Email is required",
+		phoneExists: "Phone number already registered",
 		passwordRequired: "Password is required",
 		invalidEmail: "Invalid email format",
 		weakPassword: "Password is too weak",
@@ -391,6 +483,14 @@ declare const AUTH_LOCALES: {
                 oauthSignupDisabled: string;
                 oauthHostedDomainDenied: string;
                 oauthLinkSessionExpired: string;
+                oauthCredentialSetupRequired: string;
+                credentialSetupRequired: string;
+                credentialSetupSessionRequired: string;
+                credentialSetupSessionInvalid: string;
+                credentialSetupAlreadyCompleted: string;
+                credentialSetupPasswordRejected: string;
+                credentialSetupTemporaryShape: string;
+                credentialSetupSamePassword: string;
             };
             success: {
                 login: string;
@@ -404,6 +504,9 @@ declare const AUTH_LOCALES: {
                 sessionRecovered: string;
                 oauthLogin: string;
                 oauthLinked: string;
+                credentialSetupPending: string;
+                credentialSetupPasswordReplaced: string;
+                credentialSetupCancelled: string;
             };
             emails: {
                 passwordReset: {
@@ -419,6 +522,7 @@ declare const AUTH_LOCALES: {
                 notFound: string;
                 idExists: string;
                 emailRequired: string;
+                phoneExists: string;
                 passwordRequired: string;
                 invalidEmail: string;
                 weakPassword: string;
@@ -589,6 +693,10 @@ declare class UserValidator {
      * Check if email already exists in database
      */
     checkEmailUnique(email: string, excludeId?: string): Promise<void>;
+    /**
+     * Check that a normalized phone number is not already taken.
+     */
+    checkPhoneUnique(phone: string, excludeId?: string): Promise<void>;
     /**
      * Check if user exists by ID
      */
@@ -597,6 +705,7 @@ declare class UserValidator {
      * Check if user exists by email
      */
     checkUserExistsByEmail(email: string): Promise<{
+        password: string;
         id: string;
         name: string;
         createdAt: string;
@@ -605,7 +714,6 @@ declare class UserValidator {
         emailVerified: boolean;
         phone: string;
         phoneVerified: boolean;
-        password: string;
         image: string;
         status: "active" | "pending" | "inactive";
         roleId: string;
@@ -619,6 +727,7 @@ declare class UserValidator {
      * Check if email exists in database
      */
     checkEmailExists(email: string): Promise<{
+        password: string;
         id: string;
         name: string;
         createdAt: string;
@@ -627,7 +736,6 @@ declare class UserValidator {
         emailVerified: boolean;
         phone: string;
         phoneVerified: boolean;
-        password: string;
         image: string;
         status: "active" | "pending" | "inactive";
         roleId: string;
@@ -663,6 +771,8 @@ declare class UserValidator {
      * - At least one number
      */
     validatePasswordStrength(password: string): void;
+    /** Keep every byte passed to bcrypt significant. */
+    validatePasswordLength(password: string): void;
 }
 
 declare class RoleRepository {
@@ -825,7 +935,9 @@ declare class UserService {
     }) | undefined>;
     findByPhone(phone: string): Promise<UserWithPermissions>;
     getAuthRecordById(id: string): Promise<User | undefined>;
-    create(data: Record<string, any>): Promise<SanitizedUser>;
+    create(data: Record<string, any>, options?: {
+        validatePasswordStrength?: boolean;
+    }): Promise<SanitizedUser>;
     update(id: string, data: Record<string, any>): Promise<SanitizedUser>;
     delete(id: string): Promise<SanitizedUser>;
     deleteAll(): Promise<SanitizedUser[]>;
@@ -899,13 +1011,26 @@ declare class TokenRepository {
     getUser(userId: string): Promise<any>;
 }
 
+declare class CredentialSetupRequirementRepository {
+    private db;
+    private schema;
+    private get requirements();
+    private get columns();
+    markRequired(userId: string, purpose: string, temporaryCredentialKind: string | null): Promise<CredentialSetupRequirementRow>;
+    find(userId: string, purpose: string): Promise<CredentialSetupRequirementRow | undefined>;
+    listRequired(userId: string): Promise<CredentialSetupRequirementRow[]>;
+    /** Only a still-required row completes, so a replayed completion is a no-op. */
+    complete(userId: string, purpose: string): Promise<CredentialSetupRequirementRow | undefined>;
+}
+
 declare class TokenService {
     private tokenRepository;
     private cookieManager;
     private cache;
+    private credentialSetupRequirements?;
     private config;
     private t;
-    constructor(tokenRepository: TokenRepository, cookieManager: CookieManager, cache: CacheService);
+    constructor(tokenRepository: TokenRepository, cookieManager: CookieManager, cache: CacheService, credentialSetupRequirements?: CredentialSetupRequirementRepository);
     /**
      * Get blacklist key prefix
      */
@@ -1151,9 +1276,11 @@ declare const userIdParam: z.ZodObject<{
 declare const loginDto: z.ZodUnion<readonly [z.ZodObject<{
     identifier: z.ZodString;
     password: z.ZodString;
+    rememberMe: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>, z.ZodObject<{
     email: z.ZodString;
     password: z.ZodString;
+    rememberMe: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>]>;
 declare const changePasswordDto: z.ZodObject<{
     currentPassword: z.ZodString;
@@ -1198,16 +1325,143 @@ type UserIdInParam = z.infer<typeof userIdInParam>;
 type AssignRoleParams = z.infer<typeof assignRoleParams>;
 type UserListQuery = z.infer<typeof userListQuery>;
 
+/**
+ * The durable half of credential setup: what a user still owes, independent of
+ * any browser. `CredentialSetupService` owns the other half — the short-lived
+ * cookie session that lets one browser satisfy it.
+ */
+declare class CredentialSetupRequirementService {
+    private readonly repository;
+    private readonly tokens;
+    constructor(repository: CredentialSetupRequirementRepository, tokens: TokenService);
+    /**
+     * Idempotent. Re-marking clears a previous completion, and revokes the
+     * user's current sessions so an already signed-in browser cannot skip it.
+     */
+    markRequired(userId: string, purpose: string, options?: {
+        temporaryCredentialKind?: string | null;
+    }): Promise<CredentialSetupRequirementRow>;
+    find(userId: string, purpose: string): Promise<CredentialSetupRequirementRow | undefined>;
+    isRequired(userId: string, purpose: string): Promise<boolean>;
+    listRequired(userId: string): Promise<CredentialSetupRequirementRow[]>;
+    /** Returns the completed row, or `undefined` when nothing was still required. */
+    completeRequirement(userId: string, purpose: string): Promise<CredentialSetupRequirementRow | undefined>;
+}
+
 declare class AuthSessionService {
     private tokenService;
     private userService;
     private cookieManager;
-    constructor(tokenService: TokenService, userService: UserService, cookieManager: CookieManager);
+    private credentialSetupRequirements?;
+    constructor(tokenService: TokenService, userService: UserService, cookieManager: CookieManager, credentialSetupRequirements?: CredentialSetupRequirementService);
     establish(user: SanitizedUser): Promise<TokenPair & {
         user: SanitizedUser;
     }>;
 }
 
+type NewSetupSession = {
+    userId: string;
+    purpose: string;
+    tokenHash: string;
+    expiresAt: string;
+};
+declare class CredentialSetupRepository {
+    private db;
+    private schema;
+    private get sessions();
+    replaceActive(data: NewSetupSession): Promise<any>;
+    findActive(tokenHash: string, purpose: string): Promise<any>;
+    consume(tokenHash: string, purpose: string): Promise<any>;
+    revoke(tokenHash: string, purpose: string): Promise<any>;
+    deleteExpired(): Promise<any>;
+}
+
+declare const DEFAULT_CREDENTIAL_SETUP_COOKIE_NAME = "najm.credential-setup";
+declare const DEFAULT_CREDENTIAL_SETUP_TTL_MS: number;
+declare class CredentialSetupService {
+    private readonly repository;
+    private readonly tokens;
+    private readonly authCookies;
+    private readonly cookies;
+    private t?;
+    constructor(repository: CredentialSetupRepository, tokens: TokenService, authCookies: CookieManager, cookies: CookieService);
+    /**
+     * Revoke normal auth sessions and issue a single-purpose, short-lived,
+     * browser-session cookie. No access or refresh token is minted.
+     */
+    begin(userId: string, options: CredentialSetupOptions): Promise<CredentialSetupStarted>;
+    /** Validate and return the current active setup session without consuming it. */
+    require(options: CredentialSetupOptions): Promise<CredentialSetupSessionInfo>;
+    /**
+     * Atomically consume the setup session and execute the application-owned
+     * credential mutation in the same database transaction. If the callback
+     * fails, consumption rolls back and the browser may safely retry.
+     */
+    consume<T>(options: CredentialSetupOptions, complete: (session: CredentialSetupSessionInfo) => Promise<T> | T): Promise<T>;
+    cancel(options: CredentialSetupOptions): Promise<{
+        cancelled: true;
+    }>;
+    pruneExpired(): Promise<void>;
+    /** Tolerates direct construction outside DI, where `t` is not injected. */
+    private message;
+    private sessionRequired;
+    private sessionInvalid;
+    private resolveOptions;
+    private hashToken;
+    private setCookie;
+    private clearCookie;
+}
+
+/**
+ * The built-in `password` setup flow. Always mounted by `auth()`; inert until a
+ * user actually owes the `password` purpose.
+ */
+declare class PasswordSetupService {
+    private readonly setup;
+    private readonly requirements;
+    private readonly users;
+    private readonly userRecords;
+    private readonly validator;
+    private readonly encryption;
+    private config;
+    private t?;
+    constructor(setup: CredentialSetupService, requirements: CredentialSetupRequirementService, users: UserService, userRecords: UserRepository, validator: UserValidator, encryption: EncryptionService);
+    /** Tolerates direct construction outside DI, where `t` is not injected. */
+    private message;
+    private get options();
+    private pending;
+    /** Revoke normal sessions and hand the browser a short-lived setup cookie. */
+    begin(userId: string): Promise<CredentialSetupPending>;
+    /** Read the active setup session without consuming it. */
+    status(): Promise<CredentialSetupPending>;
+    /**
+     * Everything that can fail on the user's input is checked against the
+     * *unconsumed* session, so a mistyped replacement leaves the browser able to
+     * retry. Only the two writes that must agree — the password and the
+     * requirement — happen inside the one-time consumption.
+     */
+    change(newPassword: string): Promise<{
+        changed: true;
+        signInAgain: true;
+    }>;
+    cancel(): Promise<{
+        cancelled: true;
+    }>;
+    private validateReplacement;
+    /**
+     * Runs inside the setup-session consumption transaction, so the password
+     * update, the requirement completion, and the one-time session all commit or
+     * roll back together.
+     */
+    private persist;
+    private validatePolicy;
+    /**
+     * The stored hash is of the *normalized* temporary credential, so a
+     * differently-cased retype has to be compared in both forms.
+     */
+    private isCurrentPassword;
+}
+
 /**
  * Identity fields for creating a user behind a person record (parent, student,
  * teacher, staff…). Role can be given by name (`role`) or id (`roleId`).
@@ -1216,11 +1470,35 @@ type ProvisionUserInput = {
     id?: string;
     name?: string;
     email: string;
+    /** Normalized through the configured identity preset before it is stored. */
+    phone?: string;
     role?: string;
     roleId?: string;
     image?: string | null;
     status?: 'active' | 'inactive' | 'pending';
 };
+/**
+ * Provisioning that hands the user a temporary credential and durably requires
+ * them to replace it at first login.
+ *
+ * Modelled as a union rather than optional fields on purpose: a caller must not
+ * be able to set a permanent password and mark it temporary in the same call.
+ */
+type ProvisionUserWithSetupInput = ProvisionUserInput & {
+    temporaryCredential: TemporaryCredentialInput;
+    requireCredentialSetup: typeof PASSWORD_SETUP_PURPOSE;
+    password?: never;
+};
+type ProvisionUserWithPasswordInput = ProvisionUserInput & {
+    password?: string | null;
+    temporaryCredential?: never;
+    requireCredentialSetup?: never;
+};
+/** Login answer: either a complete session, or a pending credential setup. */
+type LoginResult = (TokenPair & {
+    nextStep: 'authenticated';
+    user: SanitizedUser;
+}) | CredentialSetupPending;
 declare class AuthService {
     private tokenService;
     private userService;
@@ -1230,11 +1508,13 @@ declare class AuthService {
     private i18nService;
     private emailService;
     private authSessionService?;
+    private credentialSetupRequirements?;
+    private passwordSetup?;
     private config;
     private t;
     private logger;
     private dummyHash?;
-    constructor(tokenService: TokenService, userService: UserService, userValidator: UserValidator, encryptionService: EncryptionService, cookieManager: CookieManager, i18nService: I18nService, emailService: EmailService, authSessionService?: AuthSessionService);
+    constructor(tokenService: TokenService, userService: UserService, userValidator: UserValidator, encryptionService: EncryptionService, cookieManager: CookieManager, i18nService: I18nService, emailService: EmailService, authSessionService?: AuthSessionService, credentialSetupRequirements?: CredentialSetupRequirementService, passwordSetup?: PasswordSetupService);
     private isLockoutActive;
     private nextLockoutUntil;
     private getDummyHash;
@@ -1260,12 +1540,14 @@ declare class AuthService {
      *
      * Returns the created (sanitized) user so the caller can link `userId`.
      */
-    provisionUser(body: ProvisionUserInput & {
-        password?: string | null;
-    }): Promise<SanitizedUser>;
-    loginUser(body: LoginDto): Promise<TokenPair & {
-        user: SanitizedUser;
-    }>;
+    provisionUser(body: ProvisionUserWithPasswordInput | ProvisionUserWithSetupInput): Promise<SanitizedUser>;
+    /**
+     * Create the account and mark the durable requirement in one transaction, so
+     * a user never exists holding a temporary credential that nothing forces
+     * them to replace. No session is issued here.
+     */
+    private provisionWithCredentialSetup;
+    loginUser(body: LoginDto): Promise<LoginResult>;
     /**
      * Verify credentials and account policy without minting access/refresh
      * tokens or writing normal auth cookies. Sensitive onboarding flows can use
@@ -1278,7 +1560,19 @@ declare class AuthService {
      * should exchange the result for a short-lived, purpose-bound setup session.
      */
     verifyPendingCredentials(body: LoginDto, expectedRole: string): Promise<SanitizedUser>;
-    private verifyCredentialsForPolicy;
+    /**
+     * The one credential path. Resolves identity, the durable setup requirement,
+     * and the credential normalization that requirement implies — in that order —
+     * before a single hash comparison decides the outcome. Nothing about the
+     * requirement is revealed until credentials and account policy have passed.
+     */
+    private authenticate;
+    /**
+     * A user-chosen password is compared byte-for-byte. Only an active
+     * requirement, and only its own stored kind, can transform the submitted
+     * value — so lowercasing a CIN never leaks into normal logins.
+     */
+    private resolveLoginCredential;
     /** Establish a complete normal auth session for an already verified user. */
     establishSession(user: SanitizedUser): Promise<TokenPair & {
         user: SanitizedUser;
@@ -1340,10 +1634,9 @@ declare class AuthController {
     private authService;
     constructor(authService: AuthService);
     registerUser(body: RegisterDto): Promise<SanitizedUser>;
-    loginUser(body: LoginDto): Promise<TokenPair & {
-        user: SanitizedUser;
-    }>;
+    loginUser(body: LoginDto): Promise<LoginResult>;
     inviteUser(body: InviteUserDto): Promise<Omit<{
+        password: string;
         id: string;
         name: string;
         createdAt: string;
@@ -1352,7 +1645,6 @@ declare class AuthController {
         emailVerified: boolean;
         phone: string;
         phoneVerified: boolean;
-        password: string;
         image: string;
         status: "active" | "pending" | "inactive";
         roleId: string;
@@ -1377,6 +1669,7 @@ declare class AuthController {
         message: string;
     }>;
     userProfile(authorization?: string): Promise<Omit<{
+        password: string;
         id: string;
         name: string;
         createdAt: string;
@@ -1385,7 +1678,6 @@ declare class AuthController {
         emailVerified: boolean;
         phone: string;
         phoneVerified: boolean;
-        password: string;
         image: string;
         status: "active" | "pending" | "inactive";
         roleId: string;
@@ -1450,10 +1742,27 @@ declare class AuthResolver {
 }
 
 /**
- * Normalize an authentication identifier for both login resolution and
- * rate-limit bucketing. Email comparison is case-insensitive. Phone login uses
- * an E.164-compatible value and accepts common visual separators plus a `00`
- * international prefix.
+ * Publishes this server's identity resolver to request-local state before rate
+ * limiting. Isolated Najm servers own separate service/config instances, so one
+ * `auth()` call cannot replace another server's country preset.
+ */
+declare class AuthIdentityContextService {
+    private config;
+    private container;
+    constructor(config: AuthConfig);
+    configure(): Promise<void>;
+}
+
+type IdentityResolver = (value: unknown) => string | null;
+/**
+ * Build the identifier pipeline used by login lookup, lockout accounting, and
+ * rate-limit bucketing alike. Order is fixed: email, then project extensions,
+ * then the selected country preset, then generic E.164.
+ */
+declare function createIdentityResolver(config?: IdentityConfig): IdentityResolver;
+/**
+ * Normalize with Najm's default identity policy. Server-owned login, phone,
+ * lockout, and rate-limit paths use their own `AuthConfig.identity.resolve`.
  */
 declare function normalizeAuthIdentifier(value: unknown): string | null;
 declare function isEmailIdentifier(value: string): boolean;
@@ -1465,7 +1774,7 @@ interface RunAsUser {
 }
 declare function runAsUser<T>(container: Container, user: RunAsUser, fn: () => Promise<T> | T): Promise<T>;
 
-declare const AUTH_MODULE: readonly [typeof AuthService, typeof AuthSessionService, typeof CookieManager, typeof EncryptionService, typeof AuthGuard, typeof AuthController, typeof AuthResolver];
+declare const AUTH_MODULE: readonly [typeof AuthService, typeof AuthSessionService, typeof CookieManager, typeof EncryptionService, typeof AuthGuard, typeof AuthController, typeof AuthResolver, typeof AuthIdentityContextService];
 
 declare class PermissionRepository {
     db: TDb;
@@ -2215,73 +2524,68 @@ declare class UserController {
     removeRole(params: UserIdInParam): Promise<SanitizedUser>;
 }
 
-type NewSetupSession = {
-    userId: string;
-    purpose: string;
-    tokenHash: string;
-    expiresAt: string;
-};
-declare class CredentialSetupRepository {
-    private db;
-    private schema;
-    private get sessions();
-    replaceActive(data: NewSetupSession): Promise<any>;
-    findActive(tokenHash: string, purpose: string): Promise<any>;
-    consume(tokenHash: string, purpose: string): Promise<any>;
-    revoke(tokenHash: string, purpose: string): Promise<any>;
-    deleteExpired(): Promise<any>;
-}
-
-interface CredentialSetupOptions {
-    /** Stable server-owned purpose, for example `password-setup`. */
-    purpose: string;
-    /** HttpOnly browser-session cookie name (default: `najm.credential-setup`). */
-    cookieName?: string;
-    /** Session lifetime in milliseconds (default: 10 minutes, maximum: 24 hours). */
-    ttlMs?: number;
-    /** Cookie path (default: `/`). */
-    cookiePath?: string;
-}
-interface CredentialSetupSessionInfo {
-    userId: string;
-    purpose: string;
-    expiresAt: string;
-}
-interface CredentialSetupStarted {
-    purpose: string;
-    expiresAt: string;
-}
+/**
+ * Default replacement-password policy for the built-in `password` setup flow.
+ *
+ * Deliberately looser than `passwordField` on one axis: no uppercase
+ * requirement. A first-login replacement is typed by someone who just proved
+ * they hold the temporary credential, often on a phone keyboard, and forcing a
+ * shift key there buys nothing that length and a digit do not.
+ */
+declare const defaultCredentialSetupPasswordSchema: z.ZodString;
+/**
+ * Edge shape only — bounds, not policy. The configured policy schema is applied
+ * in the service, because it comes from `auth({ credentialSetup })`.
+ */
+declare const credentialSetupChangeDto: z.ZodObject<{
+    newPassword: z.ZodString;
+}, z.core.$strip>;
+type CredentialSetupChangeDto = z.infer<typeof credentialSetupChangeDto>;
 
-declare class CredentialSetupService {
-    private readonly repository;
-    private readonly tokens;
-    private readonly authCookies;
-    private readonly cookies;
-    constructor(repository: CredentialSetupRepository, tokens: TokenService, authCookies: CookieManager, cookies: CookieService);
-    /**
-     * Revoke normal auth sessions and issue a single-purpose, short-lived,
-     * browser-session cookie. No access or refresh token is minted.
-     */
-    begin(userId: string, options: CredentialSetupOptions): Promise<CredentialSetupStarted>;
-    /** Validate and return the current active setup session without consuming it. */
-    require(options: CredentialSetupOptions): Promise<CredentialSetupSessionInfo>;
-    /**
-     * Atomically consume the setup session and execute the application-owned
-     * credential mutation in the same database transaction. If the callback
-     * fails, consumption rolls back and the browser may safely retry.
-     */
-    consume<T>(options: CredentialSetupOptions, complete: (session: CredentialSetupSessionInfo) => Promise<T> | T): Promise<T>;
-    cancel(options: CredentialSetupOptions): Promise<{
+/**
+ * Standard endpoints for the built-in `password` setup flow. Authorization is
+ * the opaque setup cookie, not a normal session — a user in setup has none.
+ */
+declare class CredentialSetupController {
+    private passwords;
+    constructor(passwords: PasswordSetupService);
+    status(): Promise<CredentialSetupPending>;
+    change(body: CredentialSetupChangeDto): Promise<{
+        changed: true;
+        signInAgain: true;
+    }>;
+    cancel(): Promise<{
         cancelled: true;
     }>;
-    pruneExpired(): Promise<void>;
-    private resolveOptions;
-    private hashToken;
-    private setCookie;
-    private clearCookie;
 }
 
-declare const CREDENTIAL_SETUP_MODULE: readonly [typeof CredentialSetupRepository, typeof CredentialSetupService];
+/**
+ * Stable machine-readable codes for the credential-setup flow. Clients branch
+ * on these; the accompanying message is localized and may change.
+ */
+declare const CREDENTIAL_SETUP_CODES: {
+    /** Login succeeded but the account must replace its credential first. */
+    readonly REQUIRED: "AUTH_CREDENTIAL_SETUP_REQUIRED";
+    /** No setup cookie was presented. */
+    readonly SESSION_REQUIRED: "AUTH_CREDENTIAL_SETUP_SESSION_REQUIRED";
+    /** The setup cookie is unknown, already used, or expired. */
+    readonly SESSION_INVALID: "AUTH_CREDENTIAL_SETUP_SESSION_INVALID";
+    /** Nothing was still required for this user and purpose. */
+    readonly ALREADY_COMPLETED: "AUTH_CREDENTIAL_SETUP_ALREADY_COMPLETED";
+    /** The replacement failed the configured policy. */
+    readonly PASSWORD_REJECTED: "AUTH_CREDENTIAL_SETUP_PASSWORD_REJECTED";
+    /** The replacement is the credential being replaced. */
+    readonly SAME_PASSWORD: "AUTH_CREDENTIAL_SETUP_SAME_PASSWORD";
+    /** OAuth cannot mint a session while a requirement is outstanding. */
+    readonly OAUTH_BLOCKED: "oauth_credential_setup_required";
+};
+type CredentialSetupCode = (typeof CREDENTIAL_SETUP_CODES)[keyof typeof CREDENTIAL_SETUP_CODES];
+declare const credentialSetupError: (code: CredentialSetupCode, message: string, status?: number) => never;
+
+/** Purposes are server-owned identifiers, never user input. */
+declare function normalizeSetupPurpose(purpose: string): string;
+
+declare const CREDENTIAL_SETUP_MODULE: readonly [typeof CredentialSetupRepository, typeof CredentialSetupRequirementRepository, typeof CredentialSetupService, typeof CredentialSetupRequirementService, typeof PasswordSetupService, typeof CredentialSetupController];
 
 declare const USER_STATUS: readonly ["active", "inactive", "pending"];
 declare const TOKEN_STATUS: readonly ["active", "revoked", "expired"];
@@ -2424,4 +2728,4 @@ declare const authSeed: (config: AuthSeedConfig) => Record<string, SeedEntry>;
  */
 declare function seedAuthData(config: SeedAuthDataConfig): Promise<SeedAuthDataResult>;
 
-export { AUTH_CONFIG, en as AUTH_EN, AUTH_LOCALES, AUTH_MODULE, AUTH_PERMISSIONS, AUTH_ROLE, AUTH_SCHEMA, AUTH_SUPPORTED_LANGUAGES, AUTH_USER, type AssignPermissionDto, type AssignRoleDto, type AssignRoleParams, type AuthConfig, AuthController, AuthGuard, type AuthPluginConfig, AuthQueries, AuthResolver, type AuthSchema, type AuthSeedConfig, AuthService, AuthSessionService, type AuthUser, CREDENTIAL_SETUP_MODULE, Can, CanCreate, CanDelete, CanList, CanRead, CanUpdate, type ChainableGuard, type ChangePasswordDto, type CheckPermissionDto, type ConfiguredOwnership, type ConfirmResetPasswordDto, CookieManager, type CreatePermissionDto, type CreateRoleDto, type CreateTokenDto, type CreateUserDto, type CredentialSetupOptions, CredentialSetupRepository, CredentialSetupService, type CredentialSetupSessionInfo, type CredentialSetupStarted, type DefineRolesOptions, type EmailParam, EncryptionService, type GoogleOAuthConfig, type InviteUserDto, type JwtConfig, type JwtPayload, type LanguageParam, type LoginDto, NewPermission, NewRoleEntity, NewUser, type OAuthConfig, type OAuthProvider, Owned, type OwnedMethods, type OwnershipConfig, type OwnershipProvider, type OwnershipRule, OwnershipToken, type OwnershipTokenOptions, Permission, PermissionController, PermissionGuard, type PermissionIdParam, PermissionRepository, PermissionService, PermissionValidator, Policy, type ProvisionUserInput, ROLES, ROLE_GROUPS, type RefreshTokenDto, type RegisterDto, type ResetPasswordDto, type ResourceAccessor, type ResourceGuards, type ResourceGuardsOptions, type RevokeTokenDto, Role, RoleController, RoleEntity, RoleGuard, type RoleIdParam, type RoleInput, RolePermission, RoleRepository, RoleService, type RoleType, RoleValidator, type RunAsUser, type SanitizedUser, ScopeContext, type ScopeResult, type SeedAuthDataConfig, type SeedAuthDataResult, type SeedUserConfig, type SessionCookieData, TOKEN_STATUS, TOKEN_TYPE, type TokenIdParam, type TokenPair, TokenRepository, TokenService, USER_STATUS, type UpdatePermissionDto, type UpdateRoleDto, type UpdateTokenDto, type UpdateUserDto, User, UserController, type UserIdInParam, type UserIdParam, type UserListQuery, UserRepository, UserService, UserValidator, type UserWithPermissions, type VerifyTokenDto, assignPermissionDto, assignRoleDto, assignRoleParams, auth$1 as auth, authIdentityRateLimitKey, authSeed, avatarsPath, calculateAge, calculateYearsOfExperience, changePasswordDto, checkPermissionDto, clean, configureOwnership, confirmResetPasswordDto, createPermissionDto, createRoleDto, createTokenDto, createUserDto, defineRoles, emailParam, formatDate, getAuthLocale, getAvatarFile, inviteUserDto, isAdmin, isAdministrator, isAuth, isEmailIdentifier, isEmpty, isFile, isPath, join, languageParam, loginDto, normalizeAuthIdentifier, own, parseSchema, permissionIdParam, pickProps, refreshTokenDto, registerDto, resetPasswordDto, revokeTokenDto, roleIdParam, runAsUser, seedAuthData, tokenIdParam, updatePermissionDto, updateRoleDto, updateTokenDto, updateUserDto, userIdInParam, userIdParam, userListQuery, verifyTokenDto, where };
+export { AUTH_CONFIG, en as AUTH_EN, AUTH_LOCALES, AUTH_MODULE, AUTH_PERMISSIONS, AUTH_ROLE, AUTH_SCHEMA, AUTH_SUPPORTED_LANGUAGES, AUTH_USER, type AssignPermissionDto, type AssignRoleDto, type AssignRoleParams, type AuthConfig, AuthController, AuthGuard, type AuthPluginConfig, AuthQueries, AuthResolver, type AuthSchema, type AuthSeedConfig, AuthService, AuthSessionService, type AuthUser, CREDENTIAL_SETUP_CODES, CREDENTIAL_SETUP_MODULE, Can, CanCreate, CanDelete, CanList, CanRead, CanUpdate, type ChainableGuard, type ChangePasswordDto, type CheckPermissionDto, type ConfiguredOwnership, type ConfirmResetPasswordDto, CookieManager, type CreatePermissionDto, type CreateRoleDto, type CreateTokenDto, type CreateUserDto, type CredentialSetupChangeDto, type CredentialSetupCode, type CredentialSetupConfig, CredentialSetupController, type CredentialSetupOptions, type CredentialSetupPasswordOptions, type CredentialSetupPending, CredentialSetupRepository, CredentialSetupRequirementRepository, type CredentialSetupRequirementRow, CredentialSetupRequirementService, CredentialSetupService, type CredentialSetupSessionInfo, type CredentialSetupStarted, DEFAULT_CREDENTIAL_SETUP_COOKIE_NAME, DEFAULT_CREDENTIAL_SETUP_TTL_MS, type DefineRolesOptions, type EmailParam, EncryptionService, type GoogleOAuthConfig, IdentityConfig, type IdentityResolver, type InviteUserDto, type JwtConfig, type JwtPayload, type LanguageParam, type LoginDto, type LoginResult, NewPermission, NewRoleEntity, NewUser, type OAuthConfig, type OAuthProvider, Owned, type OwnedMethods, type OwnershipConfig, type OwnershipProvider, type OwnershipRule, OwnershipToken, type OwnershipTokenOptions, PASSWORD_SETUP_PURPOSE, PasswordSetupService, Permission, PermissionController, PermissionGuard, type PermissionIdParam, PermissionRepository, PermissionService, PermissionValidator, Policy, type ProvisionUserInput, type ProvisionUserWithPasswordInput, type ProvisionUserWithSetupInput, ROLES, ROLE_GROUPS, type RefreshTokenDto, type RegisterDto, type ResetPasswordDto, type ResolvedCredentialSetupConfig, ResolvedIdentityConfig, type ResourceAccessor, type ResourceGuards, type ResourceGuardsOptions, type RevokeTokenDto, Role, RoleController, RoleEntity, RoleGuard, type RoleIdParam, type RoleInput, RolePermission, RoleRepository, RoleService, type RoleType, RoleValidator, type RunAsUser, type SanitizedUser, ScopeContext, type ScopeResult, type SeedAuthDataConfig, type SeedAuthDataResult, type SeedUserConfig, type SessionCookieData, TOKEN_STATUS, TOKEN_TYPE, TemporaryCredentialInput, type TokenIdParam, type TokenPair, TokenRepository, TokenService, USER_STATUS, type UpdatePermissionDto, type UpdateRoleDto, type UpdateTokenDto, type UpdateUserDto, User, UserController, type UserIdInParam, type UserIdParam, type UserListQuery, UserRepository, UserService, UserValidator, type UserWithPermissions, type VerifyTokenDto, assignPermissionDto, assignRoleDto, assignRoleParams, auth$1 as auth, authIdentityRateLimitKey, authSeed, avatarsPath, calculateAge, calculateYearsOfExperience, changePasswordDto, checkPermissionDto, clean, configureOwnership, confirmResetPasswordDto, createIdentityResolver, createPermissionDto, createRoleDto, createTokenDto, createUserDto, credentialSetupChangeDto, credentialSetupError, defaultCredentialSetupPasswordSchema, defineRoles, emailParam, formatDate, getAuthLocale, getAvatarFile, inviteUserDto, isAdmin, isAdministrator, isAuth, isEmailIdentifier, isEmpty, isFile, isPath, join, languageParam, loginDto, normalizeAuthIdentifier, normalizeSetupPurpose, own, parseSchema, permissionIdParam, pickProps, refreshTokenDto, registerDto, resetPasswordDto, revokeTokenDto, roleIdParam, runAsUser, seedAuthData, tokenIdParam, updatePermissionDto, updateRoleDto, updateTokenDto, updateUserDto, userIdInParam, userIdParam, userListQuery, verifyTokenDto, where };