najm-auth 2.0.11 → 2.0.12

package/README.md

@@ -45,7 +45,7 @@ export const products = sqliteTable('products', {
 
 // Combined schema (always include authSchema)
 export const schema = {
-  ...authSchema,  // users, roles, permissions, tokens, rolePermissions
+  ...authSchema,  // includes users, tokens, and credentialSetupSessions
   products,
 };
 
@@ -727,7 +727,46 @@ async resetPassword(token: string, newPassword: string) {
 }
 ```
 
-### Session Management
+### Purpose-Bound Credential Setup
+
+Use `CredentialSetupService` when valid credentials should open only a
+short-lived setup flow, not a complete application session. The default auth
+schema includes the durable `credential_setup_sessions` table for PostgreSQL
+and SQLite; generate and apply a consumer migration after upgrading.
+
+```typescript
+import { AuthService, CredentialSetupService } from 'najm-auth';
+
+const options = {
+  purpose: 'password-setup',
+  cookieName: 'my-app.password-setup',
+  ttlMs: 10 * 60 * 1000,
+};
+
+// Verify the password without minting access/refresh tokens.
+const user = await authService.verifyCredentials({ identifier, password });
+
+if (await appRequiresPasswordSetup(user.id)) {
+  // Revokes normal sessions and writes only an HttpOnly, SameSite=Strict,
+  // browser-session cookie. The database stores only its SHA-256 hash.
+  return credentialSetup.begin(user.id, options);
+}
+
+return authService.establishSession(user);
+
+// Complete an app-owned mutation in the same transaction as one-time
+// consumption. If the callback fails, token consumption rolls back.
+await credentialSetup.consume(options, async ({ userId }) => {
+  await replaceApplicationCredential(userId, newCredential);
+});
+```
+
+Setup tokens are bound to a server-owned purpose, expire automatically, are
+replaced when the same user starts that purpose again, and can be cancelled or
+consumed exactly once. `require()` validates the current setup cookie without
+consuming it; `cancel()` revokes it and clears the cookie.
+
+### Session Management
 
 - Sessions are multi-device: the token table stores one refresh row per login session (keyed by a unique `tokenFamily`), so a user can stay logged in on several devices at once. Logout and rotation are scoped to the current session; password change/reset revoke every session
 - A stale refresh token presented after the 120-second rotation grace window revokes only that session's family as reuse protection

package/dist/index.d.ts

@@ -6,11 +6,12 @@ import { EmailPluginConfig, EmailService } from 'najm-email';
 import { I18nService } from 'najm-i18n';
 import { TDb, SeedEntry } from 'najm-database';
 import { User, NewUser, RoleEntity, NewRoleEntity, Permission, NewPermission, RolePermission } from './schema/pg.js';
-export { NewOAuthAccount, NewRolePermission, NewToken, OAuthAccount, Token, authSchema, baseFields, oauthAccountsTable, permissionsTable, rolePermissionsTable, rolesTable, tokenStatusEnum, tokenTypeEnum, tokensTable, userStatusEnum, usersTable } 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';
 import { CacheService } from 'najm-cache';
 import { z } from 'zod';
 import { Context } from 'hono';
 import { GuardResult } from 'najm-guard';
+import { CookieService } from 'najm-cookies';
 import 'drizzle-orm';
 import 'drizzle-orm/pg-core';
 
@@ -130,6 +131,8 @@ interface AuthConfig {
 interface AuthSchema {
     users: any;
     tokens: any;
+    /** Durable one-time browser sessions used by CredentialSetupService. */
+    credentialSetupSessions?: any;
     roles: any;
     permissions: any;
     rolePermissions: any;
@@ -1263,6 +1266,16 @@ declare class AuthService {
     loginUser(body: LoginDto): Promise<TokenPair & {
         user: SanitizedUser;
     }>;
+    /**
+     * Verify credentials and account policy without minting access/refresh
+     * tokens or writing normal auth cookies. Sensitive onboarding flows can use
+     * this before issuing a purpose-bound CredentialSetupService session.
+     */
+    verifyCredentials(body: LoginDto): Promise<SanitizedUser>;
+    /** Establish a complete normal auth session for an already verified user. */
+    establishSession(user: SanitizedUser): Promise<TokenPair & {
+        user: SanitizedUser;
+    }>;
     refreshTokens(): Promise<TokenPair>;
     /**
      * Reissue the short-lived signed session snapshot from a fully validated
@@ -2195,6 +2208,74 @@ 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;
+}
+
+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<{
+        cancelled: true;
+    }>;
+    pruneExpired(): Promise<void>;
+    private resolveOptions;
+    private hashToken;
+    private setCookie;
+    private clearCookie;
+}
+
+declare const CREDENTIAL_SETUP_MODULE: readonly [typeof CredentialSetupRepository, typeof CredentialSetupService];
+
 declare const USER_STATUS: readonly ["active", "inactive", "pending"];
 declare const TOKEN_STATUS: readonly ["active", "revoked", "expired"];
 declare const TOKEN_TYPE: readonly ["access", "refresh"];
@@ -2336,4 +2417,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, 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 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_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 };

package/dist/index.js

@@ -6,7 +6,7 @@ var __export = (target, all) => {
 };
 
 // src/AuthPlugin.ts
-import { Err as Err11, plugin } from "najm-core";
+import { Err as Err13, plugin } from "najm-core";
 import { cache } from "najm-cache";
 
 // src/auth.tokens.ts
@@ -90,6 +90,18 @@ var tokensTable = pgTable("tokens", {
   userIdIdx: index("tokens_user_id_idx").on(table.userId),
   expiresAtIdx: index("tokens_expires_at_idx").on(table.expiresAt)
 }));
+var credentialSetupSessionsTable = pgTable("credential_setup_sessions", {
+  ...baseFields(16),
+  userId: text("user_id").references(() => usersTable.id, { onDelete: "cascade" }).notNull(),
+  purpose: text("purpose").notNull(),
+  tokenHash: text("token_hash").notNull().unique(),
+  expiresAt: timestamp("expires_at", { mode: "string" }).notNull(),
+  consumedAt: timestamp("consumed_at", { mode: "string" }),
+  revokedAt: timestamp("revoked_at", { mode: "string" })
+}, (table) => ({
+  userPurposeIdx: index("credential_setup_sessions_user_purpose_idx").on(table.userId, table.purpose),
+  expiresAtIdx: index("credential_setup_sessions_expires_at_idx").on(table.expiresAt)
+}));
 var rolePermissionsTable = pgTable("role_permissions", {
   roleId: text("role_id").notNull().references(() => rolesTable.id, { onDelete: "cascade" }),
   permissionId: text("permission_id").notNull().references(() => permissionsTable.id, { onDelete: "cascade" }),
@@ -101,6 +113,7 @@ var authSchema = {
   users: usersTable,
   oauthAccounts: oauthAccountsTable,
   tokens: tokensTable,
+  credentialSetupSessions: credentialSetupSessionsTable,
   roles: rolesTable,
   permissions: permissionsTable,
   rolePermissions: rolePermissionsTable
@@ -169,6 +182,18 @@ var tokensTable2 = sqliteTable("tokens", {
   userIdIdx: index2("tokens_user_id_idx").on(table.userId),
   expiresAtIdx: index2("tokens_expires_at_idx").on(table.expiresAt)
 }));
+var credentialSetupSessionsTable2 = sqliteTable("credential_setup_sessions", {
+  ...baseFields2(16),
+  userId: text2("user_id").references(() => usersTable2.id, { onDelete: "cascade" }).notNull(),
+  purpose: text2("purpose").notNull(),
+  tokenHash: text2("token_hash").notNull().unique(),
+  expiresAt: text2("expires_at").notNull(),
+  consumedAt: text2("consumed_at"),
+  revokedAt: text2("revoked_at")
+}, (table) => ({
+  userPurposeIdx: index2("credential_setup_sessions_user_purpose_idx").on(table.userId, table.purpose),
+  expiresAtIdx: index2("credential_setup_sessions_expires_at_idx").on(table.expiresAt)
+}));
 var rolePermissionsTable2 = sqliteTable("role_permissions", {
   ...baseFields2(10),
   roleId: text2("role_id").notNull().references(() => rolesTable2.id, { onDelete: "cascade" }),
@@ -180,6 +205,7 @@ var authSchema2 = {
   users: usersTable2,
   oauthAccounts: oauthAccountsTable2,
   tokens: tokensTable2,
+  credentialSetupSessions: credentialSetupSessionsTable2,
   roles: rolesTable2,
   permissions: permissionsTable2,
   rolePermissions: rolePermissionsTable2
@@ -2288,6 +2314,15 @@ var AuthService = class AuthService2 {
     return this.inviteUser(body);
   }
   async loginUser(body) {
+    const user = await this.verifyCredentials(body);
+    return this.establishSession(user);
+  }
+  /**
+   * Verify credentials and account policy without minting access/refresh
+   * tokens or writing normal auth cookies. Sensitive onboarding flows can use
+   * this before issuing a purpose-bound CredentialSetupService session.
+   */
+  async verifyCredentials(body) {
     const password = body.password;
     const rawIdentifier = "identifier" in body ? body.identifier : body.email;
     const identifier = normalizeAuthIdentifier(rawIdentifier);
@@ -2328,8 +2363,12 @@ var AuthService = class AuthService2 {
       await this.userService.resetFailedAttempts(user.id);
     }
     const { password: _, failedLoginAttempts: __, lockoutUntil: ___, ...sanitized } = user;
+    return sanitized;
+  }
+  /** Establish a complete normal auth session for an already verified user. */
+  async establishSession(user) {
     this.authSessionService ??= new AuthSessionService(this.tokenService, this.userService, this.cookieManager);
-    return this.authSessionService.establish(sanitized);
+    return this.authSessionService.establish(user);
   }
   async refreshTokens() {
     const generated = await this.tokenService.refreshTokens();
@@ -4215,7 +4254,7 @@ function toSingular(plural) {
 }
 __name(toSingular, "toSingular");
 function createResourceGuards(ownershipClass, resourceType, resource, options) {
-  var _a22, _b12;
+  var _a23, _b13;
   const writeGuard = options?.adminGuard ?? isAdmin;
   let AccessGuard = class AccessGuard {
     static {
@@ -4236,7 +4275,7 @@ function createResourceGuards(ownershipClass, resourceType, resource, options) {
     __param10(1, Params4("id")),
     __metadata24("design:type", Function),
     __metadata24("design:paramtypes", [Object, String]),
-    __metadata24("design:returntype", typeof (_a22 = typeof Promise !== "undefined" && Promise) === "function" ? _a22 : Object)
+    __metadata24("design:returntype", typeof (_a23 = typeof Promise !== "undefined" && Promise) === "function" ? _a23 : Object)
   ], AccessGuard.prototype, "canActivate", null);
   AccessGuard = __decorate24([
     Injectable12()
@@ -4259,7 +4298,7 @@ function createResourceGuards(ownershipClass, resourceType, resource, options) {
     __param10(0, User4()),
     __metadata24("design:type", Function),
     __metadata24("design:paramtypes", [Object]),
-    __metadata24("design:returntype", typeof (_b12 = typeof Promise !== "undefined" && Promise) === "function" ? _b12 : Object)
+    __metadata24("design:returntype", typeof (_b13 = typeof Promise !== "undefined" && Promise) === "function" ? _b13 : Object)
   ], ListGuard.prototype, "canActivate", null);
   ListGuard = __decorate24([
     Injectable12()
@@ -4397,7 +4436,7 @@ function configureOwnership(config) {
     Injectable12()
   ], GeneratedOwnershipService);
   function bodyGuard(resourceType, bodyField, optional = false) {
-    var _a22;
+    var _a23;
     let BodyAccessGuard = class BodyAccessGuard {
       static {
         __name(this, "BodyAccessGuard");
@@ -4419,7 +4458,7 @@ function configureOwnership(config) {
       __param10(1, Body5()),
       __metadata24("design:type", Function),
       __metadata24("design:paramtypes", [Object, Object]),
-      __metadata24("design:returntype", typeof (_a22 = typeof Promise !== "undefined" && Promise) === "function" ? _a22 : Object)
+      __metadata24("design:returntype", typeof (_a23 = typeof Promise !== "undefined" && Promise) === "function" ? _a23 : Object)
     ], BodyAccessGuard.prototype, "canActivate", null);
     BodyAccessGuard = __decorate24([
       Injectable12()
@@ -5456,6 +5495,252 @@ var OAUTH_MODULE = [
   OAuthController
 ];
 
+// src/credentialSetup/CredentialSetupRepository.ts
+import { and as and5, eq as eq8, gt, isNull as isNull2, lt as lt2 } from "drizzle-orm";
+import { Err as Err11, Inject as Inject18, Repository as Repository6 } from "najm-core";
+import { DB as DB6 } from "najm-database";
+var __decorate33 = function(decorators, target, key, desc) {
+  var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+  if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+  else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+  return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata33 = function(k, v) {
+  if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var CredentialSetupRepository = class CredentialSetupRepository2 {
+  static {
+    __name(this, "CredentialSetupRepository");
+  }
+  db;
+  schema;
+  get sessions() {
+    const sessions = this.schema.credentialSetupSessions;
+    if (!sessions) {
+      Err11.invalidOperation("auth.schema.credentialSetupSessions is required to use CredentialSetupService");
+    }
+    return sessions;
+  }
+  async replaceActive(data) {
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    await this.db.update(this.sessions).set({ revokedAt: now, updatedAt: now }).where(and5(eq8(this.sessions.userId, data.userId), eq8(this.sessions.purpose, data.purpose), isNull2(this.sessions.consumedAt), isNull2(this.sessions.revokedAt)));
+    const [session] = await this.db.insert(this.sessions).values(data).returning({
+      userId: this.sessions.userId,
+      purpose: this.sessions.purpose,
+      expiresAt: this.sessions.expiresAt
+    });
+    return session;
+  }
+  async findActive(tokenHash, purpose) {
+    const [session] = await this.db.select({
+      userId: this.sessions.userId,
+      purpose: this.sessions.purpose,
+      expiresAt: this.sessions.expiresAt
+    }).from(this.sessions).where(and5(eq8(this.sessions.tokenHash, tokenHash), eq8(this.sessions.purpose, purpose), isNull2(this.sessions.consumedAt), isNull2(this.sessions.revokedAt), gt(this.sessions.expiresAt, (/* @__PURE__ */ new Date()).toISOString()))).limit(1);
+    return session;
+  }
+  async consume(tokenHash, purpose) {
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const [session] = await this.db.update(this.sessions).set({ consumedAt: now, updatedAt: now }).where(and5(eq8(this.sessions.tokenHash, tokenHash), eq8(this.sessions.purpose, purpose), isNull2(this.sessions.consumedAt), isNull2(this.sessions.revokedAt), gt(this.sessions.expiresAt, now))).returning({
+      userId: this.sessions.userId,
+      purpose: this.sessions.purpose,
+      expiresAt: this.sessions.expiresAt
+    });
+    return session;
+  }
+  async revoke(tokenHash, purpose) {
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const [session] = await this.db.update(this.sessions).set({ revokedAt: now, updatedAt: now }).where(and5(eq8(this.sessions.tokenHash, tokenHash), eq8(this.sessions.purpose, purpose), isNull2(this.sessions.consumedAt), isNull2(this.sessions.revokedAt))).returning({ userId: this.sessions.userId });
+    return session;
+  }
+  async deleteExpired() {
+    return this.db.delete(this.sessions).where(lt2(this.sessions.expiresAt, (/* @__PURE__ */ new Date()).toISOString())).returning({ userId: this.sessions.userId });
+  }
+};
+__decorate33([
+  DB6(),
+  __metadata33("design:type", Object)
+], CredentialSetupRepository.prototype, "db", void 0);
+__decorate33([
+  Inject18(AUTH_SCHEMA),
+  __metadata33("design:type", Object)
+], CredentialSetupRepository.prototype, "schema", void 0);
+CredentialSetupRepository = __decorate33([
+  Repository6()
+], CredentialSetupRepository);
+
+// src/credentialSetup/CredentialSetupService.ts
+import { createHash as createHash5, randomBytes as randomBytes4 } from "crypto";
+import { CookieService as CookieService3 } from "najm-cookies";
+import { Err as Err12, Injectable as Injectable19 } from "najm-core";
+import { Transaction as Transaction3 } from "najm-database";
+var __decorate34 = function(decorators, target, key, desc) {
+  var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+  if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+  else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+  return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata34 = function(k, v) {
+  if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var _a22;
+var _b12;
+var _c8;
+var _d5;
+var _e4;
+var _f4;
+var _g3;
+var DEFAULT_COOKIE_NAME = "najm.credential-setup";
+var DEFAULT_TTL_MS = 10 * 60 * 1e3;
+var MAX_TTL_MS = 24 * 60 * 60 * 1e3;
+var PURPOSE_PATTERN = /^[a-z0-9](?:[a-z0-9:_-]{0,62}[a-z0-9])?$/;
+var COOKIE_NAME_PATTERN = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
+var CredentialSetupService = class CredentialSetupService2 {
+  static {
+    __name(this, "CredentialSetupService");
+  }
+  repository;
+  tokens;
+  authCookies;
+  cookies;
+  constructor(repository, tokens, authCookies, cookies2) {
+    this.repository = repository;
+    this.tokens = tokens;
+    this.authCookies = authCookies;
+    this.cookies = cookies2;
+  }
+  /**
+   * Revoke normal auth sessions and issue a single-purpose, short-lived,
+   * browser-session cookie. No access or refresh token is minted.
+   */
+  async begin(userId, options) {
+    const resolved = this.resolveOptions(options);
+    const token = randomBytes4(32).toString("base64url");
+    const expiresAt = new Date(Date.now() + resolved.ttlMs).toISOString();
+    await this.repository.deleteExpired();
+    await this.repository.replaceActive({
+      userId,
+      purpose: resolved.purpose,
+      tokenHash: this.hashToken(token),
+      expiresAt
+    });
+    await this.tokens.invalidateUserAccessTokens(userId);
+    await this.tokens.revokeAllForUser(userId);
+    this.authCookies.clearRefreshToken();
+    this.authCookies.clearSessionCookie();
+    this.setCookie(token, resolved);
+    return { purpose: resolved.purpose, expiresAt };
+  }
+  /** Validate and return the current active setup session without consuming it. */
+  async require(options) {
+    const resolved = this.resolveOptions(options);
+    const token = this.cookies.get(resolved.cookieName);
+    if (!token)
+      Err12("Credential setup session is required", 401);
+    const session = await this.repository.findActive(this.hashToken(token), resolved.purpose);
+    if (!session) {
+      this.clearCookie(resolved);
+      Err12("Credential setup session is invalid or expired", 401);
+    }
+    return session;
+  }
+  /**
+   * 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.
+   */
+  async consume(options, complete) {
+    const resolved = this.resolveOptions(options);
+    const token = this.cookies.get(resolved.cookieName);
+    if (!token)
+      Err12("Credential setup session is required", 401);
+    const session = await this.repository.consume(this.hashToken(token), resolved.purpose);
+    if (!session) {
+      this.clearCookie(resolved);
+      Err12("Credential setup session is invalid or expired", 401);
+    }
+    const result = await complete(session);
+    this.clearCookie(resolved);
+    return result;
+  }
+  async cancel(options) {
+    const resolved = this.resolveOptions(options);
+    const token = this.cookies.get(resolved.cookieName);
+    if (token) {
+      await this.repository.revoke(this.hashToken(token), resolved.purpose);
+    }
+    this.clearCookie(resolved);
+    return { cancelled: true };
+  }
+  async pruneExpired() {
+    await this.repository.deleteExpired();
+  }
+  resolveOptions(options) {
+    const purpose = options.purpose?.trim().toLowerCase();
+    const cookieName = options.cookieName?.trim() || DEFAULT_COOKIE_NAME;
+    const ttlMs = options.ttlMs ?? DEFAULT_TTL_MS;
+    const cookiePath = options.cookiePath ?? "/";
+    if (!purpose || !PURPOSE_PATTERN.test(purpose)) {
+      Err12("Credential setup purpose must be 1-64 lowercase letters, numbers, colon, underscore, or hyphen", 500);
+    }
+    if (!COOKIE_NAME_PATTERN.test(cookieName) || cookieName.length > 128) {
+      Err12("Credential setup cookie name is invalid", 500);
+    }
+    if (!Number.isInteger(ttlMs) || ttlMs < 1e3 || ttlMs > MAX_TTL_MS) {
+      Err12("Credential setup ttlMs must be an integer between 1000 and 86400000", 500);
+    }
+    if (!cookiePath.startsWith("/") || cookiePath.includes(";") || cookiePath.includes("\\")) {
+      Err12("Credential setup cookiePath must be a same-origin path", 500);
+    }
+    return { purpose, cookieName, ttlMs, cookiePath };
+  }
+  hashToken(token) {
+    return createHash5("sha256").update(token).digest("hex");
+  }
+  setCookie(token, options) {
+    this.cookies.setSession(options.cookieName, token, {
+      httpOnly: true,
+      path: options.cookiePath,
+      sameSite: "Strict",
+      secure: process.env.NODE_ENV === "production"
+    });
+  }
+  clearCookie(options) {
+    this.cookies.delete(options.cookieName, {
+      path: options.cookiePath,
+      secure: process.env.NODE_ENV === "production"
+    });
+  }
+};
+__decorate34([
+  Transaction3({ retries: 2 }),
+  __metadata34("design:type", Function),
+  __metadata34("design:paramtypes", [String, Object]),
+  __metadata34("design:returntype", typeof (_e4 = typeof Promise !== "undefined" && Promise) === "function" ? _e4 : Object)
+], CredentialSetupService.prototype, "begin", null);
+__decorate34([
+  Transaction3({ retries: 2 }),
+  __metadata34("design:type", Function),
+  __metadata34("design:paramtypes", [Object, Function]),
+  __metadata34("design:returntype", typeof (_f4 = typeof Promise !== "undefined" && Promise) === "function" ? _f4 : Object)
+], CredentialSetupService.prototype, "consume", null);
+__decorate34([
+  Transaction3({ retries: 2 }),
+  __metadata34("design:type", Function),
+  __metadata34("design:paramtypes", [Object]),
+  __metadata34("design:returntype", typeof (_g3 = typeof Promise !== "undefined" && Promise) === "function" ? _g3 : Object)
+], CredentialSetupService.prototype, "cancel", null);
+CredentialSetupService = __decorate34([
+  Injectable19(),
+  __metadata34("design:paramtypes", [typeof (_a22 = typeof CredentialSetupRepository !== "undefined" && CredentialSetupRepository) === "function" ? _a22 : Object, typeof (_b12 = typeof TokenService !== "undefined" && TokenService) === "function" ? _b12 : Object, typeof (_c8 = typeof CookieManager !== "undefined" && CookieManager) === "function" ? _c8 : Object, typeof (_d5 = typeof CookieService3 !== "undefined" && CookieService3) === "function" ? _d5 : Object])
+], CredentialSetupService);
+
+// src/credentialSetup/index.ts
+var CREDENTIAL_SETUP_MODULE = [
+  CredentialSetupRepository,
+  CredentialSetupService
+];
+
 // src/AuthPlugin.ts
 var DEFAULT_JWT = {
   accessSecret: process.env.JWT_ACCESS_SECRET || "",
@@ -5477,9 +5762,9 @@ var resolveGoogleConfig = /* @__PURE__ */ __name((config) => {
   const clientId = google.clientId ?? process.env.GOOGLE_CLIENT_ID ?? "";
   const clientSecret = google.clientSecret ?? process.env.GOOGLE_CLIENT_SECRET ?? "";
   if (!clientId)
-    throw Err11.configRequired("auth.oauth.google", "GOOGLE_CLIENT_ID");
+    throw Err13.configRequired("auth.oauth.google", "GOOGLE_CLIENT_ID");
   if (!clientSecret)
-    throw Err11.configRequired("auth.oauth.google", "GOOGLE_CLIENT_SECRET");
+    throw Err13.configRequired("auth.oauth.google", "GOOGLE_CLIENT_SECRET");
   const frontendUrl = config?.frontendUrl ?? process.env.FRONTEND_URL ?? "http://localhost:3000";
   const callbackUrl = google.callbackUrl ?? process.env.GOOGLE_CALLBACK_URL ?? `${frontendUrl.replace(/\/$/, "")}/api/auth/oauth/google/callback`;
   let callback;
@@ -5538,10 +5823,10 @@ var resolveAuthConfig = /* @__PURE__ */ __name((config) => {
     }
   };
   if (!finalConfig.jwt.accessSecret) {
-    throw Err11.configRequired("auth", "JWT_ACCESS_SECRET");
+    throw Err13.configRequired("auth", "JWT_ACCESS_SECRET");
   }
   if (!finalConfig.jwt.refreshSecret) {
-    throw Err11.configRequired("auth", "JWT_REFRESH_SECRET");
+    throw Err13.configRequired("auth", "JWT_REFRESH_SECRET");
   }
   return finalConfig;
 }, "resolveAuthConfig");
@@ -5561,7 +5846,7 @@ var selectAuthSchema = /* @__PURE__ */ __name((config) => {
       return authSchema;
   }
 }, "selectAuthSchema");
-var auth = /* @__PURE__ */ __name((config) => plugin("auth").version("1.0.0").depends(cache(), cookies(), i18n(), guards(), validation(config?.validation), rateLimit(config?.rateLimit), email(config?.email)).requires("database").contributes(I18N_CONTRIBUTIONS, AUTH_LOCALES).services(AUTH_MODULE, OAUTH_MODULE, users_exports, roles_exports, permissions_exports, tokens_exports, ScopeContext).config(AUTH_CONFIG, resolveAuthConfig(config)).set(AUTH_SCHEMA, selectAuthSchema(config)).set(AUTH_ENCRYPTION_KEY, config?.encryptionKey ?? null).build(), "auth");
+var auth = /* @__PURE__ */ __name((config) => plugin("auth").version("1.0.0").depends(cache(), cookies(), i18n(), guards(), validation(config?.validation), rateLimit(config?.rateLimit), email(config?.email)).requires("database").contributes(I18N_CONTRIBUTIONS, AUTH_LOCALES).services(AUTH_MODULE, OAUTH_MODULE, users_exports, roles_exports, permissions_exports, tokens_exports, CREDENTIAL_SETUP_MODULE, ScopeContext).config(AUTH_CONFIG, resolveAuthConfig(config)).set(AUTH_SCHEMA, selectAuthSchema(config)).set(AUTH_ENCRYPTION_KEY, config?.encryptionKey ?? null).build(), "auth");
 
 // src/seed.ts
 var toSeedId = /* @__PURE__ */ __name((prefix, value) => {
@@ -5708,6 +5993,7 @@ export {
   AuthResolver,
   AuthService,
   AuthSessionService,
+  CREDENTIAL_SETUP_MODULE,
   Can,
   CanCreate,
   CanDelete,
@@ -5715,6 +6001,8 @@ export {
   CanRead,
   CanUpdate,
   CookieManager,
+  CredentialSetupRepository,
+  CredentialSetupService,
   EncryptionService,
   Owned,
   OwnershipToken,
@@ -5762,6 +6050,7 @@ export {
   createRoleDto,
   createTokenDto,
   createUserDto,
+  credentialSetupSessionsTable,
   defineRoles,
   emailParam,
   formatDate,