najm-auth 2.0.11 → 2.0.13

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,52 @@ 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 });
+
+// Or narrowly accept only an unverified pending account with one exact role.
+const pendingSponsor = await authService.verifyPendingCredentials(
+  { identifier, password },
+  'sponsor',
+);
+
+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,23 @@ 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>;
+    /**
+     * Verify a pending, unverified account for one exact application role.
+     * This deliberately does not establish a normal auth session. Applications
+     * should exchange the result for a short-lived, purpose-bound setup session.
+     */
+    verifyPendingCredentials(body: LoginDto, expectedRole: string): Promise<SanitizedUser>;
+    private verifyCredentialsForPolicy;
+    /** 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 +2215,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 +2424,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 };