@tstdl/base 0.92.144 → 0.92.147

package/authentication/server/authentication.api-controller.js

@@ -17,11 +17,24 @@ import { AuthenticationService } from './authentication.service.js';
 import { tryGetAuthorizationTokenStringFromRequest } from './helper.js';
 const cookieBaseOptions = { path: '/', httpOnly: true, secure: true, sameSite: 'strict' };
 const deleteCookie = { value: '', ...cookieBaseOptions, maxAge: -1 };
+/**
+ * API controller for authentication.
+ *
+ * @template AdditionalTokenPayload Type of additional token payload
+ * @template AuthenticationData Type of additional authentication data
+ * @template AdditionalInitSecretResetData Type of additional secret reset data
+ */
 let AuthenticationApiController = class AuthenticationApiController {
     authenticationService;
     constructor(authenticationService) {
         this.authenticationService = authenticationService;
     }
+    /**
+     * Get a token for a subject and secret.
+     * @param parameters The parameters for the request.
+     * @returns The token result.
+     * @throws {InvalidCredentialsError} If the credentials are invalid.
+     */
     async getToken({ parameters }) {
         const authenticationResult = await this.authenticationService.authenticate(parameters.subject, parameters.secret);
         if (!authenticationResult.success) {
@@ -30,22 +43,45 @@ let AuthenticationApiController = class AuthenticationApiController {
         const result = await this.authenticationService.getToken(authenticationResult.subject, parameters.data);
         return this.getTokenResponse(result);
     }
+    /**
+     * Refresh a token.
+     * @param request The request context.
+     * @param parameters The parameters for the request.
+     * @returns The token result.
+     */
     async refresh({ request, parameters }) {
         const refreshTokenString = tryGetAuthorizationTokenStringFromRequest(request, 'refreshToken') ?? '';
         const result = await this.authenticationService.refresh(refreshTokenString, parameters.data);
         return this.getTokenResponse(result);
     }
+    /**
+     * Impersonate a subject.
+     * @param request The request context.
+     * @param parameters The parameters for the request.
+     * @returns The token result.
+     */
     async impersonate({ request, parameters }) {
         const tokenString = tryGetAuthorizationTokenStringFromRequest(request) ?? '';
         const refreshTokenString = tryGetAuthorizationTokenStringFromRequest(request, 'refreshToken') ?? '';
         const impersonatorResult = await this.authenticationService.impersonate(tokenString, refreshTokenString, parameters.subject, parameters.data);
         return this.getTokenResponse(impersonatorResult);
     }
+    /**
+     * Unimpersonate a subject.
+     * @param request The request context.
+     * @param parameters The parameters for the request.
+     * @returns The token result.
+     */
     async unimpersonate({ request, parameters }) {
         const impersonatorRefreshTokenString = tryGetAuthorizationTokenStringFromRequest(request, 'impersonatorRefreshToken') ?? '';
         const result = await this.authenticationService.refresh(impersonatorRefreshTokenString, parameters.data, { omitImpersonator: true });
         return this.getTokenResponse(result);
     }
+    /**
+     * End a session.
+     * @param request The request context.
+     * @returns 'ok' if the session was ended.
+     */
     async endSession({ request }) {
         let sessionId;
         try {
@@ -76,17 +112,36 @@ let AuthenticationApiController = class AuthenticationApiController {
             },
         });
     }
+    /**
+     * Initialize a secret reset.
+     * @param parameters The parameters for the request.
+     * @returns 'ok' if the secret reset was initialized.
+     */
     async initSecretReset({ parameters }) {
         await this.authenticationService.initSecretReset(parameters.subject, parameters.data);
         return 'ok';
     }
+    /**
+     * Reset a secret.
+     * @param parameters The parameters for the request.
+     * @returns 'ok' if the secret was reset.
+     */
     async resetSecret({ parameters }) {
         await this.authenticationService.resetSecret(parameters.token, parameters.newSecret);
         return 'ok';
     }
+    /**
+     * Check a secret.
+     * @param parameters The parameters for the request.
+     * @returns The result of the secret check.
+     */
     async checkSecret({ parameters }) {
         return await this.authenticationService.checkSecret(parameters.secret);
     }
+    /**
+     * Get the current server timestamp.
+     * @returns The current server timestamp.
+     */
     timestamp() {
         return currentTimestamp();
     }
@@ -127,6 +182,16 @@ AuthenticationApiController = __decorate([
     __metadata("design:paramtypes", [AuthenticationService])
 ], AuthenticationApiController);
 export { AuthenticationApiController };
+/**
+ * Get an authentication API controller.
+ * @param additionalTokenPayloadSchema Schema for additional token payload.
+ * @param authenticationDataSchema Schema for additional authentication data.
+ * @param additionalInitSecretResetData Schema for additional secret reset data.
+ * @returns An authentication API controller.
+ * @template AdditionalTokenPayload Type of additional token payload.
+ * @template AuthenticationData Type of additional authentication data.
+ * @template AdditionalInitSecretResetData Type of additional secret reset data.
+ */
 export function getAuthenticationApiController(// eslint-disable-line @typescript-eslint/explicit-function-return-type
 additionalTokenPayloadSchema, authenticationDataSchema, additionalInitSecretResetData) {
     const apiDefinition = getAuthenticationApiDefinition(additionalTokenPayloadSchema, authenticationDataSchema, additionalInitSecretResetData);

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

@@ -1,38 +1,72 @@
 import { type AfterResolve, afterResolve } from '../../injector/index.js';
-import type { BinaryData, Record } from '../../types.js';
+import type { BinaryData, Record } from '../../types/index.js';
 import { type RefreshToken, type SecretCheckResult, type SecretResetToken, type Token } from '../models/index.js';
 import { type SecretTestResult } from './authentication-secret-requirements.validator.js';
+/**
+ * Data for creating a token.
+ *
+ * @param AdditionalTokenPayload Type of additional token payload
+ */
 export type CreateTokenData<AdditionalTokenPayload extends Record> = {
+    /** Token version, forces refresh on mismatch (useful if payload changes) */
     tokenVersion?: number;
+    /** Custom token id */
     jwtId?: string;
+    /** Custom issued at timestamp */
     issuedAt?: number;
+    /** Custom expiration timestamp */
     expiration?: number;
+    /** Additional token payload */
     additionalTokenPayload: AdditionalTokenPayload;
+    /** Subject of the token */
     subject: string;
+    /** Session id */
     sessionId: string;
+    /** Impersonator subject */
     impersonator: string | undefined;
+    /** Refresh token expiration timestamp */
     refreshTokenExpiration: number;
+    /** Timestamp for issued at and expiration calculation */
     timestamp?: number;
 };
 export declare class AuthenticationServiceOptions {
     /**
-     * Secrets used for signing tokens and refreshTokens
-     * If single secret is provided, multiple secrets are derived internally
+     * Secrets used for signing tokens and refreshTokens.
+     * If single secret is provided, multiple secrets are derived internally.
      */
     secret: string | BinaryData | {
         tokenSigningSecret: Uint8Array;
         refreshTokenSigningSecret: Uint8Array;
         secretResetTokenSigningSecret: Uint8Array;
     };
-    /** Token version, forces refresh on mismatch (useful if payload changes) */
+    /**
+     * Token version, forces refresh on mismatch (useful if payload changes).
+     *
+     * @default 1
+     */
     version?: number;
-    /** How long a token is valid */
+    /**
+     * How long a token is valid in milliseconds.
+     *
+     * @default 5 minutes
+     */
     tokenTimeToLive?: number;
-    /** How long a refresh token is valid. Implies session time to live. */
+    /**
+     * How long a refresh token is valid in milliseconds. Implies session time to live.
+     *
+     * @default 5 days
+     */
     refreshTokenTimeToLive?: number;
-    /** How long a secret reset token is valid. */
+    /**
+     * How long a secret reset token is valid in milliseconds.
+     *
+     * @default 10 minutes
+     */
     secretResetTokenTimeToLive?: number;
 }
+/**
+ * Result of an authentication attempt.
+ */
 export type AuthenticationResult = {
     success: true;
     subject: string;
@@ -40,6 +74,11 @@ export type AuthenticationResult = {
     success: false;
     subject?: undefined;
 };
+/**
+ * Result of a token creation.
+ *
+ * @param AdditionalTokenPayload Type of additional token payload
+ */
 export type TokenResult<AdditionalTokenPayload extends Record> = {
     token: string;
     jsonToken: Token<AdditionalTokenPayload>;
@@ -49,9 +88,17 @@ export type TokenResult<AdditionalTokenPayload extends Record> = {
     impersonatorRefreshTokenExpiration?: number;
 };
 export type SetCredentialsOptions = {
-    /** skip validation for password strength */
+    /**
+     * Skip validation for password strength.
+     *
+     * @default false
+     */
     skipValidation?: boolean;
-    /** skip session invalidation */
+    /**
+     * Skip session invalidation.
+     *
+     * @default false
+     */
     skipSessionInvalidation?: boolean;
 };
 type CreateTokenResult<AdditionalTokenPayload extends Record> = {
@@ -64,6 +111,23 @@ type CreateRefreshTokenResult = {
     salt: Uint8Array;
     hash: Uint8Array;
 };
+/**
+ * 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
+ */
 export declare class AuthenticationService<AdditionalTokenPayload extends Record = Record<never>, AuthenticationData = void, AdditionalInitSecretResetData = void> implements AfterResolve {
     #private;
     private readonly tokenVersion;
@@ -73,27 +137,132 @@ export declare class AuthenticationService<AdditionalTokenPayload extends Record
     private derivedTokenSigningSecret;
     private derivedRefreshTokenSigningSecret;
     private derivedSecretResetTokenSigningSecret;
+    /** @internal */
     [afterResolve](): Promise<void>;
+    /**
+     * Initializes the service.
+     * Derives signing secrets if necessary.
+     *
+     * @internal
+     */
     initialize(): Promise<void>;
+    /**
+     * Sets the credentials for a subject.
+     * This method should not be exposed to the public API without a 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.
+     */
     setCredentials(subject: string, secret: string, options?: SetCredentialsOptions): Promise<void>;
+    /**
+     * Authenticates a subject with a secret.
+     * @param subject The subject to authenticate.
+     * @param secret The secret to authenticate with.
+     * @returns The result of the authentication.
+     */
     authenticate(subject: string, secret: string): Promise<AuthenticationResult>;
+    /**
+     * Gets a token for a subject.
+     * @param subject The subject to get the token for.
+     * @param authenticationData Additional authentication data.
+     * @param options Options for getting the token.
+     * @returns The token result.
+     */
     getToken(subject: string, authenticationData: AuthenticationData, { impersonator }?: {
         impersonator?: string;
     }): Promise<TokenResult<AdditionalTokenPayload>>;
+    /**
+     * Ends a session.
+     * @param sessionId The id of the session to end.
+     */
     endSession(sessionId: string): Promise<void>;
+    /**
+     * Refreshes a token.
+     * @param refreshToken The refresh token to use.
+     * @param authenticationData Additional authentication data.
+     * @param options Options for refreshing the token.
+     * @returns The token result.
+     * @throws {InvalidTokenError} If the refresh token is invalid.
+     */
     refresh(refreshToken: string, authenticationData: AuthenticationData, { omitImpersonator }?: {
         omitImpersonator?: boolean;
     }): Promise<TokenResult<AdditionalTokenPayload>>;
+    /**
+     * Impersonates a subject.
+     * @param impersonatorRoken The token of the impersonator.
+     * @param impersonatorRefreshToken The refresh token of the impersonator.
+     * @param subject The subject to impersonate.
+     * @param authenticationData Additional authentication data.
+     * @returns The token result.
+     * @throws {ForbiddenError} If impersonation is not allowed.
+     */
     impersonate(impersonatorRoken: string, impersonatorRefreshToken: string, subject: string, authenticationData: AuthenticationData): Promise<TokenResult<AdditionalTokenPayload>>;
+    /**
+     * Unimpersonates a subject.
+     * @param impersonatorRefreshToken The refresh token of the impersonator.
+     * @param authenticationData Additional authentication data.
+     * @returns The token result.
+     */
     unimpersonate(impersonatorRefreshToken: string, authenticationData: AuthenticationData): Promise<TokenResult<AdditionalTokenPayload>>;
+    /**
+     * Initializes a secret reset.
+     * @param subject The subject to reset the secret for.
+     * @param data Additional data for the secret reset.
+     * @throws {NotImplementedError} If no ancillary service is registered.
+     */
     initSecretReset(subject: string, data: AdditionalInitSecretResetData): Promise<void>;
+    /**
+     * Resets a secret.
+     * @param tokenString The secret reset token.
+     * @param newSecret The new secret.
+     * @throws {InvalidTokenError} If the token is invalid.
+     */
     resetSecret(tokenString: string, newSecret: string): Promise<void>;
+    /**
+     * Checks a secret against the requirements.
+     * @param secret The secret to check.
+     * @returns The result of the check.
+     */
     checkSecret(secret: string): Promise<SecretCheckResult>;
+    /**
+     * Tests a secret against the requirements.
+     * @param secret The secret to test.
+     * @returns The result of the test.
+     */
     testSecret(secret: string): Promise<SecretTestResult>;
+    /**
+     * 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.
+     */
     validateSecret(secret: string): Promise<void>;
+    /**
+     * Validates a token.
+     * @param token The token to validate.
+     * @returns The validated token.
+     * @throws {InvalidTokenError} If the token is invalid.
+     */
     validateToken(token: string): Promise<Token<AdditionalTokenPayload>>;
+    /**
+     * Validates a refresh token.
+     * @param token The refresh token to validate.
+     * @returns The validated refresh token.
+     * @throws {InvalidTokenError} If the refresh token is invalid.
+     */
     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.
+     */
     validateSecretResetToken(token: string): Promise<SecretResetToken>;
+    /**
+     * Tries to resolve a subject.
+     * This method is safe to use in public facing APIs as it does not leak information about the existence of a subject.
+     * @param subject The subject to resolve.
+     * @returns The resolved subject or undefined if the subject could not be resolved.
+     */
     tryResolveSubject(subject: string): Promise<string | undefined>;
     /**
      * Resolves the subject to the actual subject used for authentication.
@@ -103,9 +272,20 @@ export declare class AuthenticationService<AdditionalTokenPayload extends Record
      * @returns The resolved subject or the original subject if not found.
      */
     resolveSubject(subject: string): Promise<string>;
-    /** Creates a token without session or refresh token and is not saved in database */
+    /**
+     * Creates a token without session or refresh token and is not saved in database.
+     * @param data Data for creating the token.
+     * @returns The created token.
+     */
     createToken({ tokenVersion, jwtId, issuedAt, expiration, additionalTokenPayload, subject, sessionId, refreshTokenExpiration, impersonator: impersonatedBy, timestamp }: CreateTokenData<AdditionalTokenPayload>): Promise<CreateTokenResult<AdditionalTokenPayload>>;
-    /** Creates a refresh token without session or something else. */
+    /**
+     * Creates a refresh token without session and is not saved in database.
+     * @param subject The subject of the refresh token.
+     * @param sessionId The session id of the refresh token.
+     * @param expirationTimestamp The expiration timestamp of the refresh token.
+     * @param options Options for creating the refresh token.
+     * @returns The created refresh token.
+     */
     createRefreshToken(subject: string, sessionId: string, expirationTimestamp: number, options?: {
         impersonator?: string;
     }): Promise<CreateRefreshTokenResult>;

package/authentication/server/authentication.service.js

@@ -29,20 +29,53 @@ import { getRefreshTokenFromString, getSecretResetTokenFromString, getTokenFromS
 import { AuthenticationModuleConfig } from './module.js';
 export class AuthenticationServiceOptions {
     /**
-     * Secrets used for signing tokens and refreshTokens
-     * If single secret is provided, multiple secrets are derived internally
+     * Secrets used for signing tokens and refreshTokens.
+     * If single secret is provided, multiple secrets are derived internally.
      */
     secret;
-    /** Token version, forces refresh on mismatch (useful if payload changes) */
+    /**
+     * Token version, forces refresh on mismatch (useful if payload changes).
+     *
+     * @default 1
+     */
     version;
-    /** How long a token is valid */
+    /**
+     * How long a token is valid in milliseconds.
+     *
+     * @default 5 minutes
+     */
     tokenTimeToLive;
-    /** How long a refresh token is valid. Implies session time to live. */
+    /**
+     * How long a refresh token is valid in milliseconds. Implies session time to live.
+     *
+     * @default 5 days
+     */
     refreshTokenTimeToLive;
-    /** How long a secret reset token is valid. */
+    /**
+     * How long a secret reset token is valid in milliseconds.
+     *
+     * @default 10 minutes
+     */
     secretResetTokenTimeToLive;
 }
 const SIGNING_SECRETS_LENGTH = 64;
+/**
+ * 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
+ */
 let AuthenticationService = class AuthenticationService {
     #credentialsRepository = injectRepository(AuthenticationCredentials);
     #sessionRepository = injectRepository(AuthenticationSession);
@@ -58,9 +91,16 @@ let AuthenticationService = class AuthenticationService {
     derivedTokenSigningSecret;
     derivedRefreshTokenSigningSecret;
     derivedSecretResetTokenSigningSecret;
+    /** @internal */
     async [afterResolve]() {
         await this.initialize();
     }
+    /**
+     * Initializes the service.
+     * Derives signing secrets if necessary.
+     *
+     * @internal
+     */
     async initialize() {
         if (isString(this.#options.secret) || isBinaryData(this.#options.secret)) {
             await this.deriveSigningSecrets(this.#options.secret);
@@ -71,6 +111,13 @@ let AuthenticationService = class AuthenticationService {
             this.derivedSecretResetTokenSigningSecret = this.#options.secret.secretResetTokenSigningSecret;
         }
     }
+    /**
+     * Sets the credentials for a subject.
+     * This method should not be exposed to the public API without a 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.
+     */
     async setCredentials(subject, secret, options) {
         // We do not need to avoid information leakage here, as this is a non-public method that is only called by a public api if the secret reset token is valid.
         const actualSubject = await this.resolveSubject(subject);
@@ -91,6 +138,12 @@ let AuthenticationService = class AuthenticationService {
             }
         });
     }
+    /**
+     * Authenticates a subject with a secret.
+     * @param subject The subject to authenticate.
+     * @param secret The secret to authenticate with.
+     * @returns The result of the authentication.
+     */
     async authenticate(subject, secret) {
         const actualSubject = await this.tryResolveSubject(subject) ?? subject;
         // Always try to load credentials, even if the subject is not resolved, to avoid information leakage.
@@ -105,6 +158,13 @@ let AuthenticationService = class AuthenticationService {
         }
         return { success: false };
     }
+    /**
+     * Gets a token for a subject.
+     * @param subject The subject to get the token for.
+     * @param authenticationData Additional authentication data.
+     * @param options Options for getting the token.
+     * @returns The token result.
+     */
     async getToken(subject, authenticationData, { impersonator } = {}) {
         const actualSubject = await this.resolveSubject(subject);
         const now = currentTimestamp();
@@ -130,10 +190,22 @@ let AuthenticationService = class AuthenticationService {
             return { token, jsonToken, refreshToken: refreshToken.token };
         });
     }
+    /**
+     * Ends a session.
+     * @param sessionId The id of the session to end.
+     */
     async endSession(sessionId) {
         const now = currentTimestamp();
         await this.#sessionRepository.update(sessionId, { end: now });
     }
+    /**
+     * Refreshes a token.
+     * @param refreshToken The refresh token to use.
+     * @param authenticationData Additional authentication data.
+     * @param options Options for refreshing the token.
+     * @returns The token result.
+     * @throws {InvalidTokenError} If the refresh token is invalid.
+     */
     async refresh(refreshToken, authenticationData, { omitImpersonator = false } = {}) {
         const validatedRefreshToken = await this.validateRefreshToken(refreshToken);
         const sessionId = validatedRefreshToken.payload.sessionId;
@@ -159,6 +231,15 @@ let AuthenticationService = class AuthenticationService {
         });
         return { token, jsonToken, refreshToken: newRefreshToken.token, omitImpersonatorRefreshToken: omitImpersonator };
     }
+    /**
+     * Impersonates a subject.
+     * @param impersonatorRoken The token of the impersonator.
+     * @param impersonatorRefreshToken The refresh token of the impersonator.
+     * @param subject The subject to impersonate.
+     * @param authenticationData Additional authentication data.
+     * @returns The token result.
+     * @throws {ForbiddenError} If impersonation is not allowed.
+     */
     async impersonate(impersonatorRoken, impersonatorRefreshToken, subject, authenticationData) {
         const validatedImpersonatorRoken = await this.validateToken(impersonatorRoken);
         const validatedImpersonatorRefreshToken = await this.validateRefreshToken(impersonatorRefreshToken);
@@ -173,9 +254,21 @@ let AuthenticationService = class AuthenticationService {
             impersonatorRefreshTokenExpiration: validatedImpersonatorRefreshToken.payload.exp,
         };
     }
+    /**
+     * Unimpersonates a subject.
+     * @param impersonatorRefreshToken The refresh token of the impersonator.
+     * @param authenticationData Additional authentication data.
+     * @returns The token result.
+     */
     async unimpersonate(impersonatorRefreshToken, authenticationData) {
         return await this.refresh(impersonatorRefreshToken, authenticationData, { omitImpersonator: true });
     }
+    /**
+     * Initializes a secret reset.
+     * @param subject The subject to reset the secret for.
+     * @param data Additional data for the secret reset.
+     * @throws {NotImplementedError} If no ancillary service is registered.
+     */
     async initSecretReset(subject, data) {
         if (isUndefined(this.#authenticationAncillaryService)) {
             throw new NotImplementedError();
@@ -198,28 +291,73 @@ let AuthenticationService = class AuthenticationService {
         };
         await this.#authenticationAncillaryService.handleInitSecretReset(initSecretResetData);
     }
+    /**
+     * Resets a secret.
+     * @param tokenString The secret reset token.
+     * @param newSecret The new secret.
+     * @throws {InvalidTokenError} If the token is invalid.
+     */
     async resetSecret(tokenString, newSecret) {
         const token = await this.validateSecretResetToken(tokenString);
         await this.setCredentials(token.payload.subject, newSecret);
     }
+    /**
+     * Checks a secret against the requirements.
+     * @param secret The secret to check.
+     * @returns The result of the check.
+     */
     async checkSecret(secret) {
         return await this.#authenticationSecretRequirementsValidator.checkSecretRequirements(secret);
     }
+    /**
+     * Tests a secret against the requirements.
+     * @param secret The secret to test.
+     * @returns The result of the test.
+     */
     async testSecret(secret) {
         return await this.#authenticationSecretRequirementsValidator.testSecretRequirements(secret);
     }
+    /**
+     * 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.
+     */
     async validateSecret(secret) {
         await this.#authenticationSecretRequirementsValidator.validateSecretRequirements(secret);
     }
+    /**
+     * Validates a token.
+     * @param token The token to validate.
+     * @returns The validated token.
+     * @throws {InvalidTokenError} If the token is invalid.
+     */
     async validateToken(token) {
         return await getTokenFromString(token, this.tokenVersion, this.derivedTokenSigningSecret);
     }
+    /**
+     * Validates a refresh token.
+     * @param token The refresh token to validate.
+     * @returns The validated refresh token.
+     * @throws {InvalidTokenError} If the refresh token is invalid.
+     */
     async validateRefreshToken(token) {
         return await getRefreshTokenFromString(token, this.derivedRefreshTokenSigningSecret);
     }
+    /**
+     * 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.
+     */
     async validateSecretResetToken(token) {
         return await getSecretResetTokenFromString(token, this.derivedSecretResetTokenSigningSecret);
     }
+    /**
+     * Tries to resolve a subject.
+     * This method is safe to use in public facing APIs as it does not leak information about the existence of a subject.
+     * @param subject The subject to resolve.
+     * @returns The resolved subject or undefined if the subject could not be resolved.
+     */
     async tryResolveSubject(subject) {
         if (isUndefined(this.#authenticationAncillaryService)) {
             return subject;
@@ -247,7 +385,11 @@ let AuthenticationService = class AuthenticationService {
         }
         throw new NotFoundError(`Subject not found.`);
     }
-    /** Creates a token without session or refresh token and is not saved in database */
+    /**
+     * Creates a token without session or refresh token and is not saved in database.
+     * @param data Data for creating the token.
+     * @returns The created token.
+     */
     async createToken({ tokenVersion, jwtId, issuedAt, expiration, additionalTokenPayload, subject, sessionId, refreshTokenExpiration, impersonator: impersonatedBy, timestamp = currentTimestamp() }) {
         const header = {
             v: tokenVersion ?? this.tokenVersion,
@@ -271,7 +413,14 @@ let AuthenticationService = class AuthenticationService {
         const token = await createJwtTokenString(jsonToken, this.derivedTokenSigningSecret);
         return { token, jsonToken };
     }
-    /** Creates a refresh token without session or something else. */
+    /**
+     * Creates a refresh token without session and is not saved in database.
+     * @param subject The subject of the refresh token.
+     * @param sessionId The session id of the refresh token.
+     * @param expirationTimestamp The expiration timestamp of the refresh token.
+     * @param options Options for creating the refresh token.
+     * @returns The created refresh token.
+     */
     async createRefreshToken(subject, sessionId, expirationTimestamp, options) {
         const secret = getRandomString(64, Alphabet.LowerUpperCaseNumbers);
         const salt = getRandomBytes(32);