@tstdl/base 0.93.178 → 0.93.180

package/authentication/server/authentication.audit.d.ts

@@ -26,15 +26,52 @@ export type AuthenticationAuditEvents = {
         impersonatedSubjectId: string;
     };
     'unimpersonate-success': {};
-    'change-secret-success': {};
-    'change-secret-failure': {
+    'change-password-success': {};
+    'change-password-failure': {
         subjectInput: SubjectInput;
         resolvedSubjectId: string | null;
     };
-    'init-secret-reset': {};
-    'reset-secret-success': {};
-    'reset-secret-failure': {
+    'init-password-reset': {};
+    'reset-password-success': {};
+    'reset-password-failure': {
         reason: string;
     };
+    'rate-limit-exceeded': {
+        type: 'ip' | 'subject';
+        resource: string;
+        action: string;
+    };
     'invalidate-all-sessions': {};
+    'invalidate-all-other-sessions': {
+        currentSessionId: string;
+    };
+    'totp-enroll-init': {
+        subjectId: string;
+    };
+    'totp-enroll-success': {};
+    'totp-enroll-failure': {
+        reason: string;
+    };
+    'totp-disable-success': {};
+    'totp-disable-failure': {
+        reason: string;
+    };
+    'totp-verify-failure': {
+        reason: string;
+    };
+    'totp-token-reused': {
+        token: string;
+    };
+    'totp-recovery-code-used': {};
+    'recovery-codes-regenerated': {
+        count: number;
+    };
+    'recovery-login-success': {
+        sessionId: string;
+        remember: boolean;
+    };
+    'recovery-login-failure': {
+        subjectInput: SubjectInput;
+        resolvedSubjectId: string | null;
+    };
 };

package/authentication/server/authentication.service.d.ts

@@ -1,10 +1,10 @@
 /** biome-ignore-all lint/nursery/noExcessiveClassesPerFile: <explanation> */
 import { Auditor } from '../../audit/index.js';
-import { afterResolve, type AfterResolve } from '../../injector/index.js';
-import type { BinaryData, Record } from '../../types/index.js';
-import { AuthenticationSession, Subject, type RefreshToken, type SecretCheckResult, type SecretResetToken, type Token } from '../models/index.js';
+import { type Argon2Params, type TotpHashAlgorithm } from '../../cryptography/index.js';
+import type { Record, TypedOmit } from '../../types/index.js';
+import { AuthenticationSession, AuthenticationTotp, Subject, type PasswordCheckResult, type PasswordResetToken, type RefreshToken, type Token, type TotpChallengeToken } from '../models/index.js';
 import type { SubjectInput } from '../types.js';
-import { type SecretTestResult } from './authentication-secret-requirements.validator.js';
+import { type PasswordTestResult } from './authentication-password-requirements.validator.js';
 /**
  * Data for creating a token.
  *
@@ -33,15 +33,6 @@ export type CreateTokenData<AdditionalTokenPayload extends Record> = {
     timestamp?: number;
 };
 export declare class AuthenticationServiceOptions {
-    /**
-     * Secrets used for signing tokens and refreshTokens.
-     * If single secret is provided, multiple secrets are derived internally.
-     */
-    secret: string | BinaryData<ArrayBuffer> | {
-        tokenSigningSecret: Uint8Array<ArrayBuffer>;
-        refreshTokenSigningSecret: Uint8Array<ArrayBuffer>;
-        secretResetTokenSigningSecret: Uint8Array<ArrayBuffer>;
-    };
     /**
      * Token version, forces refresh on mismatch (useful if payload changes).
      *
@@ -67,24 +58,79 @@ export declare class AuthenticationServiceOptions {
      */
     rememberRefreshTokenTimeToLive?: number;
     /**
-     * How long a secret reset token is valid in milliseconds.
+     * How long a password reset token is valid in milliseconds.
      *
      * @default 10 minutes
      */
-    secretResetTokenTimeToLive?: number;
+    passwordResetTokenTimeToLive?: number;
     /**
-     * Number of iterations for password hashing.
+     * How long a TOTP challenge token is valid in milliseconds.
      *
-     * @default 250000
+     * @default 5 minutes
      */
-    hashIterations?: number;
+    totpChallengeTokenTimeToLive?: number;
     /**
-     * Number of iterations for signing secrets derivation.
-     *
-     * @default 500000
+     * Options for brute force protection.
+     */
+    bruteForceProtection?: BruteForceProtectionOptions;
+    /**
+     * TOTP issuer name.
      */
-    signingSecretsDerivationIterations?: number;
+    totpIssuer?: string;
+    /**
+     * Options for password hashing.
+     */
+    passwordHashing?: PasswordHashingOptions;
+    /**
+     * Options for TOTP.
+     */
+    totp?: TotpHashingOptions;
 }
+/**
+ * Options for password hashing.
+ */
+export type PasswordHashingOptions = {
+    algorithm: TypedOmit<Argon2Params, 'nonce'>;
+};
+/**
+ * Options for TOTP.
+ */
+export type TotpHashingOptions = {
+    codeHashAlgorithm: TotpHashAlgorithm;
+    recoveryCodeHashOptions: {
+        algorithm: TypedOmit<Argon2Params, 'nonce'>;
+        length: number;
+    };
+};
+/**
+ * Options for brute force protection.
+ */
+export type BruteForceProtectionOptions = {
+    /**
+     * Burst capacity for subject rate limit.
+     *
+     * @default 10
+     */
+    subjectBurstCapacity?: number;
+    /**
+     * Refill interval for subject rate limit in milliseconds.
+     *
+     * @default 1800000 (30 minutes)
+     */
+    subjectRefillInterval?: number;
+    /**
+     * Burst capacity for ip rate limit.
+     *
+     * @default 20
+     */
+    ipBurstCapacity?: number;
+    /**
+     * Refill interval for ip rate limit in milliseconds.
+     *
+     * @default 300000 (5 minutes)
+     */
+    ipRefillInterval?: number;
+};
 /**
  * Result of an authentication attempt.
  */
@@ -109,7 +155,17 @@ export type TokenResult<AdditionalTokenPayload extends Record> = {
     impersonatorRefreshToken?: string;
     impersonatorRefreshTokenExpiration?: number;
 };
-export type SetCredentialsOptions = {
+export type LoginSuccessResult<AdditionalTokenPayload extends Record> = {
+    type: 'success';
+    result: TokenResult<AdditionalTokenPayload>;
+    lowRecoveryCodesWarning?: boolean;
+};
+export type LoginTotpResult = {
+    type: 'totp';
+    challengeToken: string;
+};
+export type LoginResult<AdditionalTokenPayload extends Record> = LoginSuccessResult<AdditionalTokenPayload> | LoginTotpResult;
+export type SetPasswordOptions = {
     /**
      * Skip validation for password strength.
      *
@@ -133,24 +189,15 @@ type CreateRefreshTokenResult = {
     salt: Uint8Array<ArrayBuffer>;
     hash: Uint8Array<ArrayBuffer>;
 };
+export declare const DEFAULT_TOTP_OPTIONS: TotpHashingOptions;
 /**
  * Handles authentication on server side.
  *
- * Can be used to:
- * - Set credentials
- * - Authenticate
- * - Get token
- * - End session
- * - Refresh token
- * - Impersonate/unimpersonate
- * - Reset secret
- * - Check secret
- *
  * @template AdditionalTokenPayload Type of additional token payload
  * @template AuthenticationData Type of additional authentication data
- * @template AdditionalInitSecretResetData Type of additional secret reset data
+ * @template AdditionalInitPasswordResetData Type of additional password reset data
  */
-export declare class AuthenticationService<AdditionalTokenPayload extends Record = Record<never>, AuthenticationData = void, AdditionalInitSecretResetData = void> implements AfterResolve {
+export declare class AuthenticationService<AdditionalTokenPayload extends Record = Record<never>, AuthenticationData = void, AdditionalInitPasswordResetData = void> {
     #private;
     readonly hooks: {
         beforeLogin: import("../../utils/async-hook/async-hook.js").AsyncHook<{
@@ -159,10 +206,10 @@ export declare class AuthenticationService<AdditionalTokenPayload extends Record
         afterLogin: import("../../utils/async-hook/async-hook.js").AsyncHook<{
             subject: Subject;
         }, never, unknown>;
-        beforeChangeSecret: import("../../utils/async-hook/async-hook.js").AsyncHook<{
+        beforeChangePassword: import("../../utils/async-hook/async-hook.js").AsyncHook<{
             subject: Subject;
         }, never, unknown>;
-        afterChangeSecret: import("../../utils/async-hook/async-hook.js").AsyncHook<{
+        afterChangePassword: import("../../utils/async-hook/async-hook.js").AsyncHook<{
             subject: Subject;
         }, never, unknown>;
     };
@@ -170,34 +217,31 @@ export declare class AuthenticationService<AdditionalTokenPayload extends Record
     private readonly tokenTimeToLive;
     private readonly refreshTokenTimeToLive;
     private readonly rememberRefreshTokenTimeToLive;
-    private readonly secretResetTokenTimeToLive;
-    private derivedTokenSigningSecret;
-    private derivedRefreshTokenSigningSecret;
-    private derivedSecretResetTokenSigningSecret;
-    /** @internal */
-    [afterResolve](): Promise<void>;
-    /**
-     * Initializes the service.
-     * Derives signing secrets if necessary.
-     *
-     * @internal
-     */
-    initialize(): Promise<void>;
+    private readonly passwordResetTokenTimeToLive;
+    private readonly totpOptions;
+    private readonly hashDeriveOptions;
+    getTotpOptions(): TotpHashingOptions;
     /**
-     * Sets the credentials for a subject.
-     * This method should not be exposed to the public API without an authenticated current password or secret reset token check.
-     * @param subject The subject to set the credentials for.
-     * @param secret The secret to set.
-     * @param options Options for setting the credentials.
+     * Sets the password for a subject.
+     * This method should not be exposed to the public API without an authenticated current password or password reset token check.
+     * @param subject The subject to set the password for.
+     * @param password The password to set.
+     * @param options Options for setting the password.
      */
-    setCredentials(subject: Subject, secret: string, options?: SetCredentialsOptions): Promise<void>;
+    setPassword(subject: Subject, password: string, options?: SetPasswordOptions): Promise<void>;
     /**
-     * Authenticates a subject with a secret.
+     * Authenticates a subject with a password.
      * @param subject The subject to authenticate.
-     * @param secret The secret to authenticate with.
+     * @param password The password to authenticate with.
      * @returns The result of the authentication.
      */
-    authenticate(subject: SubjectInput, secret: string): Promise<AuthenticationResult>;
+    authenticateWithPassword(subject: SubjectInput, password: string): Promise<AuthenticationResult>;
+    /**
+     * Ensures that a subject is not suspended.
+     * @param subject The subject to check.
+     * @throws {ForbiddenError} If the subject is suspended.
+     */
+    ensureNotSuspended(subject: Subject): void;
     /**
      * Gets a token for a subject.
      * @param subject The subject to get the token for.
@@ -212,13 +256,14 @@ export declare class AuthenticationService<AdditionalTokenPayload extends Record
     /**
      * Logs in a subject.
      * @param subjectInput The subject to log in.
-     * @param secret The secret to log in with.
+     * @param password The password to log in with.
      * @param data Additional authentication data.
      * @param auditor Auditor for auditing.
      * @param remember Whether to remember the session.
-     * @returns Token
+     * @returns Token or TOTP challenge.
      */
-    login(subjectInput: SubjectInput, secret: string, data: AuthenticationData, auditor: Auditor, remember?: boolean): Promise<TokenResult<AdditionalTokenPayload>>;
+    login(subjectInput: SubjectInput, password: string, data: AuthenticationData, auditor: Auditor, remember?: boolean): Promise<LoginResult<AdditionalTokenPayload>>;
+    loginAlreadyValidatedSubject(subject: Subject, data: AuthenticationData, auditor: Auditor, remember: boolean): Promise<LoginSuccessResult<AdditionalTokenPayload>>;
     /**
      * Ends a session.
      * @param sessionId The id of the session to end.
@@ -232,6 +277,14 @@ export declare class AuthenticationService<AdditionalTokenPayload extends Record
      * @param auditor Auditor for auditing.
      */
     invalidateAllSessions(tenantId: string, subjectId: string, auditor: Auditor): Promise<void>;
+    /**
+     * Invalidates all sessions for a subject except the current one.
+     * @param tenantId The tenant id of the subject.
+     * @param subjectId The id of the subject.
+     * @param currentSessionId The id of the current session to keep.
+     * @param auditor Auditor for auditing.
+     */
+    invalidateAllOtherSessions(tenantId: string, subjectId: string, currentSessionId: string, auditor: Auditor): Promise<void>;
     /**
      * Lists all sessions for a subject.
      * @param tenantId The tenant id of the subject.
@@ -263,6 +316,18 @@ export declare class AuthenticationService<AdditionalTokenPayload extends Record
     refresh(refreshToken: string, authenticationData: AuthenticationData, options: {
         omitImpersonator?: boolean;
     } | undefined, auditor: Auditor): Promise<TokenResult<AdditionalTokenPayload>>;
+    /**
+     * Refreshes a token.
+     * @param refreshToken The refresh token to use.
+     * @param authenticationData Additional authentication data.
+     * @param options Options for refreshing the token.
+     * @param auditor Auditor for auditing.
+     * @returns The token result.
+     * @throws {InvalidTokenError} If the refresh token is invalid.
+     */
+    refreshAlreadyValidatedToken(validatedRefreshToken: RefreshToken, authenticationData: AuthenticationData, options: {
+        omitImpersonator?: boolean;
+    } | undefined, auditor: Auditor): Promise<TokenResult<AdditionalTokenPayload>>;
     /**
      * Impersonates a subject.
      * @param impersonatorToken The token of the impersonator.
@@ -277,53 +342,54 @@ export declare class AuthenticationService<AdditionalTokenPayload extends Record
     /**
      * Unimpersonates a subject.
      * @param impersonatorRefreshToken The refresh token of the impersonator.
+     * @param tokenString The token of the impersonated subject to end the session.
      * @param authenticationData Additional authentication data.
      * @param auditor Auditor for auditing.
      * @returns The token result.
      */
-    unimpersonate(impersonatorRefreshToken: string, authenticationData: AuthenticationData, auditor: Auditor): Promise<TokenResult<AdditionalTokenPayload>>;
+    unimpersonate(impersonatorRefreshToken: string, tokenString: string, authenticationData: AuthenticationData, auditor: Auditor): Promise<TokenResult<AdditionalTokenPayload>>;
     /**
-     * Initializes a secret reset. This usually involves sending an email for verification.
-     * @param subject The subject to reset the secret for.
-     * @param data Additional data for the secret reset.
+     * Initializes a password reset. This usually involves sending an email for verification.
+     * @param subject The subject to reset the password for.
+     * @param data Additional data for the password reset.
      * @param auditor Auditor for auditing.
      * @throws {NotImplementedError} If no ancillary service is registered.
      */
-    initSecretReset(subject: SubjectInput, data: AdditionalInitSecretResetData, auditor: Auditor): Promise<void>;
+    initPasswordReset(subject: SubjectInput, data: AdditionalInitPasswordResetData, auditor: Auditor): Promise<void>;
     /**
-     * Changes a subject's secret.
-     * @param subjectInput The subject to change the secret for.
-     * @param currentSecret The current secret.
-     * @param newSecret The new secret.
+     * Changes a subject's password.
+     * @param subjectInput The subject to change the password for.
+     * @param currentPassword The current password.
+     * @param newPassword The new password.
      * @param auditor Auditor for auditing.
      */
-    changeSecret(subjectInput: SubjectInput, currentSecret: string, newSecret: string, auditor: Auditor): Promise<void>;
+    changePassword(subjectInput: SubjectInput, currentPassword: string, newPassword: string, auditor: Auditor): Promise<void>;
     /**
-     * Resets a secret.
-     * @param tokenString The secret reset token.
-     * @param newSecret The new secret.
+     * Resets a password.
+     * @param tokenString The password reset token.
+     * @param newPassword The new password.
      * @param auditor Auditor for auditing.
      * @throws {InvalidTokenError} If the token is invalid.
      */
-    resetSecret(tokenString: string, newSecret: string, auditor: Auditor): Promise<void>;
+    resetPassword(tokenString: string, newPassword: string, auditor: Auditor): Promise<void>;
     /**
-     * Checks a secret against the requirements.
-     * @param secret The secret to check.
+     * Checks a password against the requirements.
+     * @param password The password to check.
      * @returns The result of the check.
      */
-    checkSecret(secret: string): Promise<SecretCheckResult>;
+    checkPassword(password: string): Promise<PasswordCheckResult>;
     /**
-     * Tests a secret against the requirements.
-     * @param secret The secret to test.
+     * Tests a password against the requirements.
+     * @param password The password to test.
      * @returns The result of the test.
      */
-    testSecret(secret: string): Promise<SecretTestResult>;
+    testPassword(password: string): Promise<PasswordTestResult>;
     /**
-     * Validates a secret against the requirements. Throws an error if the requirements are not met.
-     * @param secret The secret to validate.
-     * @throws {SecretRequirementsError} If the secret does not meet the requirements.
+     * Validates a password against the requirements. Throws an error if the requirements are not met.
+     * @param password The password to validate.
+     * @throws {PasswordRequirementsError} If the password does not meet the requirements.
      */
-    validateSecret(secret: string): Promise<void>;
+    validatePassword(password: string): Promise<void>;
     /**
      * Validates a token.
      * @param token The token to validate.
@@ -339,12 +405,12 @@ export declare class AuthenticationService<AdditionalTokenPayload extends Record
      */
     validateRefreshToken(token: string): Promise<RefreshToken>;
     /**
-     * Validates a secret reset token.
-     * @param token The secret reset token to validate.
-     * @returns The validated secret reset token.
-     * @throws {InvalidTokenError} If the secret reset token is invalid.
+     * Validates a password reset token.
+     * @param token The password reset token to validate.
+     * @returns The validated password reset token.
+     * @throws {InvalidTokenError} If the password reset token is invalid.
      */
-    validateSecretResetToken(token: string): Promise<SecretResetToken>;
+    validatePasswordResetToken(token: string): Promise<PasswordResetToken>;
     /**
      * Tries to resolve a subject.
      * @param subject The subject to resolve.
@@ -387,8 +453,31 @@ export declare class AuthenticationService<AdditionalTokenPayload extends Record
         tenantId?: string;
         subject: string;
     }): Promise<Subject>;
-    private createSecretResetToken;
-    private deriveSigningSecrets;
+    private createPasswordResetToken;
     private getHash;
+    tryGetTotp(tenantId: string, subjectId: string): Promise<AuthenticationTotp | undefined>;
+    getTotpStatus(tenantId: string, subjectId: string): Promise<{
+        active: boolean;
+    }>;
+    initEnrollTotp(tenantId: string, subjectId: string, auditor: Auditor): Promise<{
+        secret: string;
+        uri: string;
+    }>;
+    completeEnrollTotp(tenantId: string, subjectId: string, token: string, auditor: Auditor): Promise<{
+        recoveryCodes: string[];
+    }>;
+    disableTotp(tenantId: string, subjectId: string, token: string, auditor: Auditor): Promise<void>;
+    disableTotpWithRecoveryCode(tenantId: string, subjectId: string, recoveryCode: string, auditor: Auditor): Promise<void>;
+    regenerateRecoveryCodes(tenantId: string, subjectId: string, token: string, auditor: Auditor, options?: {
+        invalidateOtherSessions?: boolean;
+    }): Promise<{
+        recoveryCodes: string[];
+    }>;
+    loginVerifyTotp(challengeTokenString: string, token: string, auditor: Auditor): Promise<LoginSuccessResult<AdditionalTokenPayload>>;
+    loginRecovery(challengeTokenString: string, recoveryCode: string, auditor: Auditor): Promise<LoginSuccessResult<AdditionalTokenPayload>>;
+    validateTotpChallengeToken(tokenString: string): Promise<TotpChallengeToken<AuthenticationData>>;
+    private createTotpChallengeToken;
+    private verifyAndUseRecoveryCode;
+    private verifyAndRecordTotpToken;
 }
 export {};