@puzzle-ui/auth 0.0.0-stage → 0.5.0

package/dist/types/mfa.types.d.ts

@@ -0,0 +1,244 @@
+import { AuthResult } from "./auth-manager.types.js";
+import { ProtectedAuthSecret } from "../providers/mfa-provider.types.js";
+import { AuthState } from "./state.types.js";
+import { StorageRecord } from "@puzzle-ui/storage";
+export type AuthMfaFactorType = "totp" | "passkey";
+export type AuthMfaFactorStatus = "pending" | "active";
+export type AuthMfaAvailableFactor = "totp" | "passkey" | "recovery-code";
+export type AuthMfaEnrollmentFactor = "totp" | "passkey";
+export type AuthMfaEnrollmentPendingResult = {
+  readonly status: "mfa-enrollment-pending";
+  readonly challengeId: string;
+  /**
+   * Server-only temporary credential.
+   *
+   * Deliver exclusively through a short-lived HttpOnly cookie.
+   * Never serialize this token into browser JSON or browser storage.
+   */
+  readonly challengeToken: string;
+  readonly expiresAt: Date;
+  readonly availableFactors: readonly AuthMfaEnrollmentFactor[];
+};
+export type AuthMfaEnrollmentCompleted = {
+  /**
+   * The authenticated result is only created after the first factor
+   * has been successfully verified and the enrollment transaction commits.
+   */
+  readonly auth: AuthResult;
+  readonly factor: AuthMfaFactor;
+  readonly recoveryCodes: readonly string[];
+};
+export type BeginRequiredMfaEnrollmentInput = {
+  readonly challengeToken: string;
+  readonly ipAddress: string;
+  readonly label?: string;
+};
+export type VerifyRequiredTotpEnrollmentInput = {
+  readonly challengeToken: string;
+  readonly factorId: string;
+  readonly code: string;
+  readonly ipAddress: string;
+};
+export type FinishRequiredPasskeyEnrollmentInput = {
+  readonly challengeToken: string;
+  readonly response: unknown;
+  readonly ipAddress: string;
+};
+export type AuthMfaFactor = {
+  readonly id: string;
+  readonly type: AuthMfaFactorType;
+  readonly status: AuthMfaFactorStatus;
+  readonly label: string;
+  readonly createdAt: Date;
+  readonly lastUsedAt: Date | null;
+};
+export type AuthMfaFactorStorageRecord = StorageRecord & {
+  readonly userId: string;
+  /**
+   * Globally unique key.
+   * TOTP: totp:<factor-id>
+   * Passkey: passkey:<credential-id>
+   */
+  readonly factorKey: string;
+  readonly type: AuthMfaFactorType;
+  readonly status: AuthMfaFactorStatus;
+  readonly label: string;
+  /** Encrypted TOTP secret; never populated for passkeys. */
+  readonly secret: ProtectedAuthSecret | null;
+  /** WebAuthn credential data; never populated for TOTP. */
+  readonly credentialId: string | null;
+  readonly publicKey: string | null;
+  readonly counter: number;
+  readonly transports: readonly string[];
+  /** Prevents reuse of an accepted TOTP time step. */
+  readonly lastUsedStep: number | null;
+  readonly lastUsedAt: Date | null;
+  /** Pending enrollments expire automatically at the domain level. */
+  readonly expiresAt: Date | null;
+};
+export type AuthMfaChallengePurpose = "sign-in" | "enrollment" | "passkey-registration" | "passkey-sign-in";
+export type AuthMfaChallengeStorageRecord = StorageRecord & {
+  readonly purpose: AuthMfaChallengePurpose;
+  /** SHA-256 hash of the temporary challenge token. */
+  readonly tokenHash: string;
+  /** Null for discoverable passkey sign-in. */
+  readonly userId: string | null;
+  /** Factors accepted by the current MFA challenge. */
+  readonly factorIds: readonly string[];
+  /** Passkeys allowed for an in-progress WebAuthn ceremony. */
+  readonly webAuthnFactorIds: readonly string[];
+  /** WebAuthn challenge, bound to this temporary record. */
+  readonly webAuthnChallenge: string | null;
+  /** Label selected when a passkey registration was initiated. */
+  readonly factorLabel: string | null;
+  /**
+   * Account-state snapshot for password-backed sign-in challenges.
+   * A challenge becomes invalid if either record changes.
+   */
+  readonly userRevision: number | null;
+  readonly credentialRevision: number | null;
+  readonly attemptCount: number;
+  readonly maximumAttempts: number;
+  readonly expiresAt: Date;
+  readonly consumedAt: Date | null;
+};
+export type AuthRecoveryCodeStorageRecord = StorageRecord & {
+  readonly userId: string;
+  readonly factorId: string;
+  readonly codeHash: string;
+  readonly consumedAt: Date | null;
+};
+export type AuthMfaPendingResult = {
+  readonly status: "mfa-pending";
+  readonly challengeId: string;
+  /**
+   * Server-only temporary credential.
+   *
+   * Deliver this through a short-lived HttpOnly cookie.
+   * Never serialize it into browser JSON or browser storage.
+   */
+  readonly challengeToken: string;
+  readonly expiresAt: Date;
+  readonly availableFactors: readonly AuthMfaAvailableFactor[];
+};
+export type AuthMfaGateway = {
+  initialize(): Promise<void>;
+  createSignInChallenge(input: {
+    readonly userId: string;
+    readonly ipAddress: string;
+  }): Promise<AuthMfaPendingResult | null>;
+  createEnrollmentChallenge(input: {
+    readonly userId: string;
+    readonly ipAddress: string;
+  }): Promise<AuthMfaEnrollmentPendingResult>;
+  /**
+   * Returns whether the user currently has at least one active MFA factor.
+   * Used by AuthManager to enforce policy against existing sessions.
+   */
+  hasActiveFactor(userId: string): Promise<boolean>;
+  getPendingAuthState(token: string): Promise<AuthState | null>;
+  revokeChallenges(userId: string): Promise<void>;
+};
+export type AuthMfaTotpOptions = {
+  readonly digits: number;
+  readonly periodSeconds: number;
+  /** Number of adjacent time steps accepted on either side. */
+  readonly window: number;
+};
+export type AuthMfaWebAuthnOptions = {
+  readonly rpId: string;
+  readonly rpName: string;
+  /** Exact expected browser origin, including scheme and port. */
+  readonly origin: string;
+};
+export type AuthMfaManagerOptions = {
+  readonly rateLimitKeySecret: string;
+  readonly usersCollection?: string;
+  readonly credentialsCollection?: string;
+  readonly auditCollection?: string;
+  readonly factorsCollection?: string;
+  readonly challengesCollection?: string;
+  readonly recoveryCodesCollection?: string;
+  readonly challengeLifetimeSeconds?: number;
+  readonly recoveryCodeCount?: number;
+  readonly issuer?: string;
+  readonly totp?: Partial<AuthMfaTotpOptions>;
+  readonly webAuthn?: AuthMfaWebAuthnOptions;
+  /** Keep this aligned with AuthManagerOptions.requireVerifiedEmail. */
+  readonly requireVerifiedEmail?: boolean;
+  readonly clock?: () => Date;
+};
+export type BeginTotpEnrollmentInput = {
+  readonly sessionToken: string;
+  readonly currentPassword: string;
+  readonly ipAddress: string;
+  readonly label?: string;
+};
+export type TotpEnrollmentStarted = {
+  readonly factorId: string;
+  readonly secret: string;
+  readonly otpauthUrl: string;
+  readonly expiresAt: Date;
+};
+export type VerifyTotpEnrollmentInput = {
+  readonly sessionToken: string;
+  readonly factorId: string;
+  readonly code: string;
+  readonly ipAddress: string;
+};
+export type MfaEnrollmentCompleted = {
+  readonly factor: AuthMfaFactor;
+  readonly recoveryCodes: readonly string[];
+};
+export type BeginPasskeyRegistrationInput = {
+  readonly sessionToken: string;
+  readonly currentPassword: string;
+  readonly ipAddress: string;
+  readonly label?: string;
+};
+export type PasskeyRegistrationStarted = {
+  readonly challengeId: string;
+  readonly challengeToken: string;
+  readonly options: Readonly<Record<string, unknown>>;
+  readonly expiresAt: Date;
+};
+export type FinishPasskeyRegistrationInput = {
+  readonly sessionToken: string;
+  readonly challengeToken: string;
+  readonly response: unknown;
+  readonly ipAddress: string;
+};
+export type BeginPasskeySignInInput = {
+  readonly ipAddress: string;
+};
+export type PasskeySignInStarted = {
+  readonly challengeId: string;
+  readonly challengeToken: string;
+  readonly options: Readonly<Record<string, unknown>>;
+  readonly expiresAt: Date;
+};
+export type CompleteMfaSignInInput = {
+  readonly challengeToken: string;
+  readonly code: string;
+  readonly ipAddress: string;
+};
+export type PasskeyMfaStarted = {
+  readonly options: Readonly<Record<string, unknown>>;
+  readonly expiresAt: Date;
+};
+export type PasskeyMfaCompletedInput = {
+  readonly challengeToken: string;
+  readonly response: unknown;
+  readonly ipAddress: string;
+};
+export type RemoveMfaFactorInput = {
+  readonly sessionToken: string;
+  readonly factorId: string;
+  readonly currentPassword: string;
+  readonly ipAddress: string;
+};
+export type RegenerateRecoveryCodesInput = {
+  readonly sessionToken: string;
+  readonly currentPassword: string;
+  readonly ipAddress: string;
+};

package/dist/types/state.types.d.cts

@@ -0,0 +1,33 @@
+export type AuthState = {
+  readonly status: "unauthenticated";
+} | {
+  readonly status: "primary-authenticated";
+  readonly userId: string;
+} | {
+  readonly status: "mfa-pending";
+  readonly userId: string;
+  readonly challengeId: string;
+  readonly expiresAt: Date;
+} | {
+  readonly status: "mfa-enrollment-pending";
+  readonly userId: string;
+  readonly challengeId: string;
+  readonly expiresAt: Date;
+  readonly availableFactors: readonly ("totp" | "passkey")[];
+} | {
+  /**
+   * The session is valid, but the current MFA policy requires an
+   * active factor. This state is restricted: it is not authenticated
+   * application access.
+   *
+   * The user may use the enrollment endpoints, which require password
+   * confirmation, to add the first required factor.
+   */
+  readonly status: "mfa-enrollment-required";
+  readonly userId: string;
+  readonly sessionId: string;
+} | {
+  readonly status: "authenticated";
+  readonly userId: string;
+  readonly sessionId: string;
+};

package/dist/types/state.types.d.ts

@@ -0,0 +1,33 @@
+export type AuthState = {
+  readonly status: "unauthenticated";
+} | {
+  readonly status: "primary-authenticated";
+  readonly userId: string;
+} | {
+  readonly status: "mfa-pending";
+  readonly userId: string;
+  readonly challengeId: string;
+  readonly expiresAt: Date;
+} | {
+  readonly status: "mfa-enrollment-pending";
+  readonly userId: string;
+  readonly challengeId: string;
+  readonly expiresAt: Date;
+  readonly availableFactors: readonly ("totp" | "passkey")[];
+} | {
+  /**
+   * The session is valid, but the current MFA policy requires an
+   * active factor. This state is restricted: it is not authenticated
+   * application access.
+   *
+   * The user may use the enrollment endpoints, which require password
+   * confirmation, to add the first required factor.
+   */
+  readonly status: "mfa-enrollment-required";
+  readonly userId: string;
+  readonly sessionId: string;
+} | {
+  readonly status: "authenticated";
+  readonly userId: string;
+  readonly sessionId: string;
+};

package/dist/types/user.types.d.cts

@@ -0,0 +1,9 @@
+export type AuthUser = {
+  readonly id: string;
+  readonly email: string;
+  readonly emailVerifiedAt: Date | null;
+  readonly name: string | null;
+  readonly image: string | null;
+  readonly createdAt: Date;
+  readonly updatedAt: Date;
+};

package/dist/types/user.types.d.ts

@@ -0,0 +1,9 @@
+export type AuthUser = {
+  readonly id: string;
+  readonly email: string;
+  readonly emailVerifiedAt: Date | null;
+  readonly name: string | null;
+  readonly image: string | null;
+  readonly createdAt: Date;
+  readonly updatedAt: Date;
+};

package/dist/utils/auth-crypto.utils.cjs

@@ -0,0 +1,38 @@
+const require_auth_errors = require("../errors/auth.errors.cjs");
+// src/utils/auth-crypto.utils.ts
+const getCrypto = () => {
+	const cryptoApi = globalThis.crypto;
+	if (!cryptoApi?.getRandomValues || !cryptoApi.subtle) throw new require_auth_errors.AuthConfigurationError("This runtime does not provide the required Web Crypto APIs.");
+	return cryptoApi;
+};
+const generateAuthId = (prefix) => {
+	const bytes = /* @__PURE__ */ new Uint8Array(16);
+	getCrypto().getRandomValues(bytes);
+	return `${prefix}_${Array.from(bytes).map((byte) => byte.toString(16).padStart(2, "0")).join("")}`;
+};
+const createRateLimitKey = async (secret, value) => {
+	const cryptoApi = getCrypto();
+	const key = await cryptoApi.subtle.importKey("raw", new TextEncoder().encode(secret), {
+		name: "HMAC",
+		hash: "SHA-256"
+	}, false, ["sign"]);
+	const signature = await cryptoApi.subtle.sign("HMAC", key, new TextEncoder().encode(value));
+	const bytes = new Uint8Array(signature);
+	return `hmac-sha256:${Array.from(bytes).map((byte) => byte.toString(16).padStart(2, "0")).join("")}`;
+};
+const generateSecureAuthToken = () => {
+	const bytes = /* @__PURE__ */ new Uint8Array(32);
+	getCrypto().getRandomValues(bytes);
+	return Array.from(bytes).map((byte) => byte.toString(16).padStart(2, "0")).join("");
+};
+const hashAuthToken = async (token) => {
+	if (typeof token !== "string" || token.length === 0) throw new require_auth_errors.AuthConfigurationError("A valid token is required.");
+	const digest = await getCrypto().subtle.digest("SHA-256", new TextEncoder().encode(token));
+	return Array.from(new Uint8Array(digest)).map((byte) => byte.toString(16).padStart(2, "0")).join("");
+};
+exports.createRateLimitKey = createRateLimitKey;
+exports.generateAuthId = generateAuthId;
+exports.generateSecureAuthToken = generateSecureAuthToken;
+exports.hashAuthToken = hashAuthToken;
+
+//# sourceMappingURL=auth-crypto.utils.cjs.map

package/dist/utils/auth-crypto.utils.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-crypto.utils.cjs","names":["AuthConfigurationError"],"sources":["../../src/utils/auth-crypto.utils.ts"],"sourcesContent":["import { AuthConfigurationError } from \"../errors/auth.errors\";\n\nconst getCrypto = (): Crypto => {\n  const cryptoApi = globalThis.crypto;\n\n  if (!cryptoApi?.getRandomValues || !cryptoApi.subtle) {\n    throw new AuthConfigurationError(\n      \"This runtime does not provide the required Web Crypto APIs.\",\n    );\n  }\n\n  return cryptoApi;\n};\n\nexport const generateAuthId = (prefix: string): string => {\n  const bytes = new Uint8Array(16);\n\n  getCrypto().getRandomValues(bytes);\n\n  const value = Array.from(bytes)\n    .map((byte) => byte.toString(16).padStart(2, \"0\"))\n    .join(\"\");\n\n  return `${prefix}_${value}`;\n};\n\nexport const createRateLimitKey = async (\n  secret: string,\n  value: string,\n): Promise<string> => {\n  const cryptoApi = getCrypto();\n\n  const key = await cryptoApi.subtle.importKey(\n    \"raw\",\n    new TextEncoder().encode(secret),\n    {\n      name: \"HMAC\",\n      hash: \"SHA-256\",\n    },\n    false,\n    [\"sign\"],\n  );\n\n  const signature = await cryptoApi.subtle.sign(\n    \"HMAC\",\n    key,\n    new TextEncoder().encode(value),\n  );\n\n  const bytes = new Uint8Array(signature);\n\n  const hash = Array.from(bytes)\n    .map((byte) => byte.toString(16).padStart(2, \"0\"))\n    .join(\"\");\n\n  return `hmac-sha256:${hash}`;\n};\n\nexport const generateSecureAuthToken = (): string => {\n  const bytes = new Uint8Array(32);\n\n  getCrypto().getRandomValues(bytes);\n\n  return Array.from(bytes)\n    .map((byte) => byte.toString(16).padStart(2, \"0\"))\n    .join(\"\");\n};\n\nexport const hashAuthToken = async (token: string): Promise<string> => {\n  if (typeof token !== \"string\" || token.length === 0) {\n    throw new AuthConfigurationError(\"A valid token is required.\");\n  }\n\n  const digest = await getCrypto().subtle.digest(\n    \"SHA-256\",\n    new TextEncoder().encode(token),\n  );\n\n  return Array.from(new Uint8Array(digest))\n    .map((byte) => byte.toString(16).padStart(2, \"0\"))\n    .join(\"\");\n};\n"],"mappings":";;AAEA,MAAM,kBAA0B;CAC9B,MAAM,YAAY,WAAW;CAE7B,IAAI,CAAC,WAAW,mBAAmB,CAAC,UAAU,QAC5C,MAAM,IAAIA,oBAAAA,uBACR,6DACF;CAGF,OAAO;AACT;AAEA,MAAa,kBAAkB,WAA2B;CACxD,MAAM,wBAAQ,IAAI,WAAW,EAAE;CAE/B,UAAU,CAAC,CAAC,gBAAgB,KAAK;CAMjC,OAAO,GAAG,OAAO,GAJH,MAAM,KAAK,KAAK,CAAC,CAC5B,KAAK,SAAS,KAAK,SAAS,EAAE,CAAC,CAAC,SAAS,GAAG,GAAG,CAAC,CAAC,CACjD,KAAK,EAEgB;AAC1B;AAEA,MAAa,qBAAqB,OAChC,QACA,UACoB;CACpB,MAAM,YAAY,UAAU;CAE5B,MAAM,MAAM,MAAM,UAAU,OAAO,UACjC,OACA,IAAI,YAAY,CAAC,CAAC,OAAO,MAAM,GAC/B;EACE,MAAM;EACN,MAAM;CACR,GACA,OACA,CAAC,MAAM,CACT;CAEA,MAAM,YAAY,MAAM,UAAU,OAAO,KACvC,QACA,KACA,IAAI,YAAY,CAAC,CAAC,OAAO,KAAK,CAChC;CAEA,MAAM,QAAQ,IAAI,WAAW,SAAS;CAMtC,OAAO,eAJM,MAAM,KAAK,KAAK,CAAC,CAC3B,KAAK,SAAS,KAAK,SAAS,EAAE,CAAC,CAAC,SAAS,GAAG,GAAG,CAAC,CAAC,CACjD,KAAK,EAEiB;AAC3B;AAEA,MAAa,gCAAwC;CACnD,MAAM,wBAAQ,IAAI,WAAW,EAAE;CAE/B,UAAU,CAAC,CAAC,gBAAgB,KAAK;CAEjC,OAAO,MAAM,KAAK,KAAK,CAAC,CACrB,KAAK,SAAS,KAAK,SAAS,EAAE,CAAC,CAAC,SAAS,GAAG,GAAG,CAAC,CAAC,CACjD,KAAK,EAAE;AACZ;AAEA,MAAa,gBAAgB,OAAO,UAAmC;CACrE,IAAI,OAAO,UAAU,YAAY,MAAM,WAAW,GAChD,MAAM,IAAIA,oBAAAA,uBAAuB,4BAA4B;CAG/D,MAAM,SAAS,MAAM,UAAU,CAAC,CAAC,OAAO,OACtC,WACA,IAAI,YAAY,CAAC,CAAC,OAAO,KAAK,CAChC;CAEA,OAAO,MAAM,KAAK,IAAI,WAAW,MAAM,CAAC,CAAC,CACtC,KAAK,SAAS,KAAK,SAAS,EAAE,CAAC,CAAC,SAAS,GAAG,GAAG,CAAC,CAAC,CACjD,KAAK,EAAE;AACZ"}

package/dist/utils/auth-crypto.utils.d.cts

@@ -0,0 +1,4 @@
+export declare const generateAuthId: (prefix: string) => string;
+export declare const createRateLimitKey: (secret: string, value: string) => Promise<string>;
+export declare const generateSecureAuthToken: () => string;
+export declare const hashAuthToken: (token: string) => Promise<string>;

package/dist/utils/auth-crypto.utils.d.ts

@@ -0,0 +1,4 @@
+export declare const generateAuthId: (prefix: string) => string;
+export declare const createRateLimitKey: (secret: string, value: string) => Promise<string>;
+export declare const generateSecureAuthToken: () => string;
+export declare const hashAuthToken: (token: string) => Promise<string>;

package/dist/utils/auth-crypto.utils.js

@@ -0,0 +1,35 @@
+import { AuthConfigurationError } from "../errors/auth.errors.js";
+// src/utils/auth-crypto.utils.ts
+const getCrypto = () => {
+	const cryptoApi = globalThis.crypto;
+	if (!cryptoApi?.getRandomValues || !cryptoApi.subtle) throw new AuthConfigurationError("This runtime does not provide the required Web Crypto APIs.");
+	return cryptoApi;
+};
+const generateAuthId = (prefix) => {
+	const bytes = /* @__PURE__ */ new Uint8Array(16);
+	getCrypto().getRandomValues(bytes);
+	return `${prefix}_${Array.from(bytes).map((byte) => byte.toString(16).padStart(2, "0")).join("")}`;
+};
+const createRateLimitKey = async (secret, value) => {
+	const cryptoApi = getCrypto();
+	const key = await cryptoApi.subtle.importKey("raw", new TextEncoder().encode(secret), {
+		name: "HMAC",
+		hash: "SHA-256"
+	}, false, ["sign"]);
+	const signature = await cryptoApi.subtle.sign("HMAC", key, new TextEncoder().encode(value));
+	const bytes = new Uint8Array(signature);
+	return `hmac-sha256:${Array.from(bytes).map((byte) => byte.toString(16).padStart(2, "0")).join("")}`;
+};
+const generateSecureAuthToken = () => {
+	const bytes = /* @__PURE__ */ new Uint8Array(32);
+	getCrypto().getRandomValues(bytes);
+	return Array.from(bytes).map((byte) => byte.toString(16).padStart(2, "0")).join("");
+};
+const hashAuthToken = async (token) => {
+	if (typeof token !== "string" || token.length === 0) throw new AuthConfigurationError("A valid token is required.");
+	const digest = await getCrypto().subtle.digest("SHA-256", new TextEncoder().encode(token));
+	return Array.from(new Uint8Array(digest)).map((byte) => byte.toString(16).padStart(2, "0")).join("");
+};
+export { createRateLimitKey, generateAuthId, generateSecureAuthToken, hashAuthToken };
+
+//# sourceMappingURL=auth-crypto.utils.js.map

package/dist/utils/auth-crypto.utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-crypto.utils.js","names":[],"sources":["../../src/utils/auth-crypto.utils.ts"],"sourcesContent":["import { AuthConfigurationError } from \"../errors/auth.errors\";\n\nconst getCrypto = (): Crypto => {\n  const cryptoApi = globalThis.crypto;\n\n  if (!cryptoApi?.getRandomValues || !cryptoApi.subtle) {\n    throw new AuthConfigurationError(\n      \"This runtime does not provide the required Web Crypto APIs.\",\n    );\n  }\n\n  return cryptoApi;\n};\n\nexport const generateAuthId = (prefix: string): string => {\n  const bytes = new Uint8Array(16);\n\n  getCrypto().getRandomValues(bytes);\n\n  const value = Array.from(bytes)\n    .map((byte) => byte.toString(16).padStart(2, \"0\"))\n    .join(\"\");\n\n  return `${prefix}_${value}`;\n};\n\nexport const createRateLimitKey = async (\n  secret: string,\n  value: string,\n): Promise<string> => {\n  const cryptoApi = getCrypto();\n\n  const key = await cryptoApi.subtle.importKey(\n    \"raw\",\n    new TextEncoder().encode(secret),\n    {\n      name: \"HMAC\",\n      hash: \"SHA-256\",\n    },\n    false,\n    [\"sign\"],\n  );\n\n  const signature = await cryptoApi.subtle.sign(\n    \"HMAC\",\n    key,\n    new TextEncoder().encode(value),\n  );\n\n  const bytes = new Uint8Array(signature);\n\n  const hash = Array.from(bytes)\n    .map((byte) => byte.toString(16).padStart(2, \"0\"))\n    .join(\"\");\n\n  return `hmac-sha256:${hash}`;\n};\n\nexport const generateSecureAuthToken = (): string => {\n  const bytes = new Uint8Array(32);\n\n  getCrypto().getRandomValues(bytes);\n\n  return Array.from(bytes)\n    .map((byte) => byte.toString(16).padStart(2, \"0\"))\n    .join(\"\");\n};\n\nexport const hashAuthToken = async (token: string): Promise<string> => {\n  if (typeof token !== \"string\" || token.length === 0) {\n    throw new AuthConfigurationError(\"A valid token is required.\");\n  }\n\n  const digest = await getCrypto().subtle.digest(\n    \"SHA-256\",\n    new TextEncoder().encode(token),\n  );\n\n  return Array.from(new Uint8Array(digest))\n    .map((byte) => byte.toString(16).padStart(2, \"0\"))\n    .join(\"\");\n};\n"],"mappings":";;AAEA,MAAM,kBAA0B;CAC9B,MAAM,YAAY,WAAW;CAE7B,IAAI,CAAC,WAAW,mBAAmB,CAAC,UAAU,QAC5C,MAAM,IAAI,uBACR,6DACF;CAGF,OAAO;AACT;AAEA,MAAa,kBAAkB,WAA2B;CACxD,MAAM,wBAAQ,IAAI,WAAW,EAAE;CAE/B,UAAU,CAAC,CAAC,gBAAgB,KAAK;CAMjC,OAAO,GAAG,OAAO,GAJH,MAAM,KAAK,KAAK,CAAC,CAC5B,KAAK,SAAS,KAAK,SAAS,EAAE,CAAC,CAAC,SAAS,GAAG,GAAG,CAAC,CAAC,CACjD,KAAK,EAEgB;AAC1B;AAEA,MAAa,qBAAqB,OAChC,QACA,UACoB;CACpB,MAAM,YAAY,UAAU;CAE5B,MAAM,MAAM,MAAM,UAAU,OAAO,UACjC,OACA,IAAI,YAAY,CAAC,CAAC,OAAO,MAAM,GAC/B;EACE,MAAM;EACN,MAAM;CACR,GACA,OACA,CAAC,MAAM,CACT;CAEA,MAAM,YAAY,MAAM,UAAU,OAAO,KACvC,QACA,KACA,IAAI,YAAY,CAAC,CAAC,OAAO,KAAK,CAChC;CAEA,MAAM,QAAQ,IAAI,WAAW,SAAS;CAMtC,OAAO,eAJM,MAAM,KAAK,KAAK,CAAC,CAC3B,KAAK,SAAS,KAAK,SAAS,EAAE,CAAC,CAAC,SAAS,GAAG,GAAG,CAAC,CAAC,CACjD,KAAK,EAEiB;AAC3B;AAEA,MAAa,gCAAwC;CACnD,MAAM,wBAAQ,IAAI,WAAW,EAAE;CAE/B,UAAU,CAAC,CAAC,gBAAgB,KAAK;CAEjC,OAAO,MAAM,KAAK,KAAK,CAAC,CACrB,KAAK,SAAS,KAAK,SAAS,EAAE,CAAC,CAAC,SAAS,GAAG,GAAG,CAAC,CAAC,CACjD,KAAK,EAAE;AACZ;AAEA,MAAa,gBAAgB,OAAO,UAAmC;CACrE,IAAI,OAAO,UAAU,YAAY,MAAM,WAAW,GAChD,MAAM,IAAI,uBAAuB,4BAA4B;CAG/D,MAAM,SAAS,MAAM,UAAU,CAAC,CAAC,OAAO,OACtC,WACA,IAAI,YAAY,CAAC,CAAC,OAAO,KAAK,CAChC;CAEA,OAAO,MAAM,KAAK,IAAI,WAAW,MAAM,CAAC,CAAC,CACtC,KAAK,SAAS,KAAK,SAAS,EAAE,CAAC,CAAC,SAAS,GAAG,GAAG,CAAC,CAAC,CACjD,KAAK,EAAE;AACZ"}

package/dist/utils/email.utils.cjs

@@ -0,0 +1,20 @@
+const require_auth_errors = require("../errors/auth.errors.cjs");
+// src/utils/email.utils.ts
+const EMAIL_PATTERN = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+const normalizeEmail = (email) => {
+	if (typeof email !== "string") throw new require_auth_errors.AuthValidationError("A valid email address is required.");
+	const normalized = email.trim().toLowerCase();
+	if (normalized.length === 0 || normalized.length > 254 || !EMAIL_PATTERN.test(normalized)) throw new require_auth_errors.AuthValidationError("A valid email address is required.");
+	return normalized;
+};
+const normalizeDisplayName = (name) => {
+	if (name === void 0 || name === null) return null;
+	if (typeof name !== "string") throw new require_auth_errors.AuthValidationError("Name must be a string.");
+	const normalized = name.trim();
+	if (normalized.length > 100) throw new require_auth_errors.AuthValidationError("Name must be 100 characters or fewer.");
+	return normalized || null;
+};
+exports.normalizeDisplayName = normalizeDisplayName;
+exports.normalizeEmail = normalizeEmail;
+
+//# sourceMappingURL=email.utils.cjs.map

package/dist/utils/email.utils.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"email.utils.cjs","names":["AuthValidationError"],"sources":["../../src/utils/email.utils.ts"],"sourcesContent":["import { AuthValidationError } from \"../errors/auth.errors\";\n\nconst EMAIL_PATTERN = /^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$/;\n\nexport const normalizeEmail = (email: string): string => {\n  if (typeof email !== \"string\") {\n    throw new AuthValidationError(\"A valid email address is required.\");\n  }\n\n  const normalized = email.trim().toLowerCase();\n\n  if (\n    normalized.length === 0 ||\n    normalized.length > 254 ||\n    !EMAIL_PATTERN.test(normalized)\n  ) {\n    throw new AuthValidationError(\"A valid email address is required.\");\n  }\n\n  return normalized;\n};\n\nexport const normalizeDisplayName = (\n  name: string | null | undefined,\n): string | null => {\n  if (name === undefined || name === null) {\n    return null;\n  }\n\n  if (typeof name !== \"string\") {\n    throw new AuthValidationError(\"Name must be a string.\");\n  }\n\n  const normalized = name.trim();\n\n  if (normalized.length > 100) {\n    throw new AuthValidationError(\"Name must be 100 characters or fewer.\");\n  }\n\n  return normalized || null;\n};\n"],"mappings":";;AAEA,MAAM,gBAAgB;AAEtB,MAAa,kBAAkB,UAA0B;CACvD,IAAI,OAAO,UAAU,UACnB,MAAM,IAAIA,oBAAAA,oBAAoB,oCAAoC;CAGpE,MAAM,aAAa,MAAM,KAAK,CAAC,CAAC,YAAY;CAE5C,IACE,WAAW,WAAW,KACtB,WAAW,SAAS,OACpB,CAAC,cAAc,KAAK,UAAU,GAE9B,MAAM,IAAIA,oBAAAA,oBAAoB,oCAAoC;CAGpE,OAAO;AACT;AAEA,MAAa,wBACX,SACkB;CAClB,IAAI,SAAS,KAAA,KAAa,SAAS,MACjC,OAAO;CAGT,IAAI,OAAO,SAAS,UAClB,MAAM,IAAIA,oBAAAA,oBAAoB,wBAAwB;CAGxD,MAAM,aAAa,KAAK,KAAK;CAE7B,IAAI,WAAW,SAAS,KACtB,MAAM,IAAIA,oBAAAA,oBAAoB,uCAAuC;CAGvE,OAAO,cAAc;AACvB"}

package/dist/utils/email.utils.d.cts

@@ -0,0 +1,2 @@
+export declare const normalizeEmail: (email: string) => string;
+export declare const normalizeDisplayName: (name: string | null | undefined) => string | null;

package/dist/utils/email.utils.d.ts

@@ -0,0 +1,2 @@
+export declare const normalizeEmail: (email: string) => string;
+export declare const normalizeDisplayName: (name: string | null | undefined) => string | null;

package/dist/utils/email.utils.js

@@ -0,0 +1,19 @@
+import { AuthValidationError } from "../errors/auth.errors.js";
+// src/utils/email.utils.ts
+const EMAIL_PATTERN = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+const normalizeEmail = (email) => {
+	if (typeof email !== "string") throw new AuthValidationError("A valid email address is required.");
+	const normalized = email.trim().toLowerCase();
+	if (normalized.length === 0 || normalized.length > 254 || !EMAIL_PATTERN.test(normalized)) throw new AuthValidationError("A valid email address is required.");
+	return normalized;
+};
+const normalizeDisplayName = (name) => {
+	if (name === void 0 || name === null) return null;
+	if (typeof name !== "string") throw new AuthValidationError("Name must be a string.");
+	const normalized = name.trim();
+	if (normalized.length > 100) throw new AuthValidationError("Name must be 100 characters or fewer.");
+	return normalized || null;
+};
+export { normalizeDisplayName, normalizeEmail };
+
+//# sourceMappingURL=email.utils.js.map

package/dist/utils/email.utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"email.utils.js","names":[],"sources":["../../src/utils/email.utils.ts"],"sourcesContent":["import { AuthValidationError } from \"../errors/auth.errors\";\n\nconst EMAIL_PATTERN = /^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$/;\n\nexport const normalizeEmail = (email: string): string => {\n  if (typeof email !== \"string\") {\n    throw new AuthValidationError(\"A valid email address is required.\");\n  }\n\n  const normalized = email.trim().toLowerCase();\n\n  if (\n    normalized.length === 0 ||\n    normalized.length > 254 ||\n    !EMAIL_PATTERN.test(normalized)\n  ) {\n    throw new AuthValidationError(\"A valid email address is required.\");\n  }\n\n  return normalized;\n};\n\nexport const normalizeDisplayName = (\n  name: string | null | undefined,\n): string | null => {\n  if (name === undefined || name === null) {\n    return null;\n  }\n\n  if (typeof name !== \"string\") {\n    throw new AuthValidationError(\"Name must be a string.\");\n  }\n\n  const normalized = name.trim();\n\n  if (normalized.length > 100) {\n    throw new AuthValidationError(\"Name must be 100 characters or fewer.\");\n  }\n\n  return normalized || null;\n};\n"],"mappings":";;AAEA,MAAM,gBAAgB;AAEtB,MAAa,kBAAkB,UAA0B;CACvD,IAAI,OAAO,UAAU,UACnB,MAAM,IAAI,oBAAoB,oCAAoC;CAGpE,MAAM,aAAa,MAAM,KAAK,CAAC,CAAC,YAAY;CAE5C,IACE,WAAW,WAAW,KACtB,WAAW,SAAS,OACpB,CAAC,cAAc,KAAK,UAAU,GAE9B,MAAM,IAAI,oBAAoB,oCAAoC;CAGpE,OAAO;AACT;AAEA,MAAa,wBACX,SACkB;CAClB,IAAI,SAAS,KAAA,KAAa,SAAS,MACjC,OAAO;CAGT,IAAI,OAAO,SAAS,UAClB,MAAM,IAAI,oBAAoB,wBAAwB;CAGxD,MAAM,aAAa,KAAK,KAAK;CAE7B,IAAI,WAAW,SAAS,KACtB,MAAM,IAAI,oBAAoB,uCAAuC;CAGvE,OAAO,cAAc;AACvB"}

package/dist/utils/totp.utils.cjs

@@ -0,0 +1,145 @@
+const require_auth_errors = require("../errors/auth.errors.cjs");
+// src/utils/totp.utils.ts
+const BASE32_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
+const getCrypto = () => {
+	const cryptoApi = globalThis.crypto;
+	if (!cryptoApi?.getRandomValues || !cryptoApi.subtle) throw new require_auth_errors.AuthConfigurationError("This runtime does not provide the required Web Crypto APIs.");
+	return cryptoApi;
+};
+const validateTotpOptions = (options) => {
+	if (!Number.isInteger(options.digits) || options.digits < 6 || options.digits > 8) throw new require_auth_errors.AuthValidationError("TOTP digits must be between 6 and 8.");
+	if (!Number.isInteger(options.periodSeconds) || options.periodSeconds < 15 || options.periodSeconds > 120) throw new require_auth_errors.AuthValidationError("The TOTP period must be between 15 and 120 seconds.");
+};
+const getTimeStep = (timestamp, periodSeconds) => {
+	if (!Number.isFinite(timestamp) || timestamp < 0) throw new require_auth_errors.AuthValidationError("A valid TOTP timestamp is required.");
+	const step = Math.floor(timestamp / 1e3 / periodSeconds);
+	if (!Number.isSafeInteger(step)) throw new require_auth_errors.AuthValidationError("The TOTP timestamp is out of range.");
+	return step;
+};
+/**
+* Copies bytes into an ArrayBuffer.
+*
+* Web Crypto APIs accept BufferSource values backed by ArrayBuffer.
+* This avoids ArrayBufferLike incompatibilities with newer TypeScript
+* typed-array definitions.
+*/
+const toArrayBuffer = (bytes) => {
+	const buffer = new ArrayBuffer(bytes.byteLength);
+	const target = new Uint8Array(buffer);
+	for (let index = 0; index < bytes.length; index++) target[index] = bytes[index];
+	return buffer;
+};
+const constantTimeEqual = (left, right) => {
+	if (left.length !== right.length) return false;
+	let difference = 0;
+	for (let index = 0; index < left.length; index++) difference |= left.charCodeAt(index) ^ right.charCodeAt(index);
+	return difference === 0;
+};
+const encodeBase32 = (input) => {
+	let output = "";
+	let buffer = 0;
+	let bits = 0;
+	for (const byte of input) {
+		buffer = buffer << 8 | byte;
+		bits += 8;
+		while (bits >= 5) {
+			bits -= 5;
+			output += BASE32_ALPHABET.charAt(buffer >>> bits & 31);
+		}
+	}
+	if (bits > 0) output += BASE32_ALPHABET.charAt(buffer << 5 - bits & 31);
+	return output;
+};
+const decodeBase32 = (input) => {
+	if (typeof input !== "string" || input.length === 0) throw new require_auth_errors.AuthValidationError("A valid TOTP secret is required.");
+	const normalized = input.toUpperCase().replace(/[\s=-]/g, "");
+	if (normalized.length === 0) throw new require_auth_errors.AuthValidationError("The TOTP secret is invalid.");
+	const output = [];
+	let buffer = 0;
+	let bits = 0;
+	for (const character of normalized) {
+		const value = BASE32_ALPHABET.indexOf(character);
+		if (value < 0) throw new require_auth_errors.AuthValidationError("The TOTP secret is invalid.");
+		buffer = buffer << 5 | value;
+		bits += 5;
+		if (bits >= 8) {
+			bits -= 8;
+			output.push(buffer >>> bits & 255);
+		}
+	}
+	if (bits > 0 && (buffer & (1 << bits) - 1) !== 0) throw new require_auth_errors.AuthValidationError("The TOTP secret is invalid.");
+	if (output.length === 0) throw new require_auth_errors.AuthValidationError("The TOTP secret is invalid.");
+	return new Uint8Array(output);
+};
+const generateTotpSecret = () => {
+	const bytes = /* @__PURE__ */ new Uint8Array(20);
+	getCrypto().getRandomValues(bytes);
+	return encodeBase32(bytes);
+};
+const generateTotpCode = async (secret, timestamp, options) => {
+	validateTotpOptions(options);
+	const counter = BigInt(getTimeStep(timestamp, options.periodSeconds));
+	const counterBuffer = /* @__PURE__ */ new ArrayBuffer(8);
+	const counterView = new DataView(counterBuffer);
+	let remaining = counter;
+	for (let index = 7; index >= 0; index--) {
+		counterView.setUint8(index, Number(remaining & 255n));
+		remaining >>= 8n;
+	}
+	const cryptoApi = getCrypto();
+	const secretBytes = decodeBase32(secret);
+	const key = await cryptoApi.subtle.importKey("raw", toArrayBuffer(secretBytes), {
+		name: "HMAC",
+		hash: "SHA-1"
+	}, false, ["sign"]);
+	const signature = await cryptoApi.subtle.sign("HMAC", key, counterBuffer);
+	const hash = new Uint8Array(signature);
+	if (hash.length < 20) throw new require_auth_errors.AuthConfigurationError("The runtime returned an invalid HMAC signature.");
+	const offset = hash[hash.length - 1] & 15;
+	const binary = (hash[offset] & 127) << 24 | hash[offset + 1] << 16 | hash[offset + 2] << 8 | hash[offset + 3];
+	const modulus = 10 ** options.digits;
+	const value = (binary >>> 0) % modulus;
+	return String(value).padStart(options.digits, "0");
+};
+/**
+* Returns the matching time step, or null.
+*
+* The caller must persist the accepted step and reject a step that
+* has already been consumed.
+*/
+const verifyTotpCode = async (secret, code, timestamp, options) => {
+	validateTotpOptions(options);
+	if (!Number.isInteger(options.window) || options.window < 0 || options.window > 2) throw new require_auth_errors.AuthValidationError("The TOTP validation window must be between 0 and 2.");
+	if (typeof code !== "string" || !new RegExp(`^\\d{${options.digits}}$`).test(code)) return null;
+	const currentStep = getTimeStep(timestamp, options.periodSeconds);
+	let matchedStep = null;
+	for (let step = currentStep - options.window; step <= currentStep + options.window; step++) {
+		if (step < 0) continue;
+		const expected = await generateTotpCode(secret, step * options.periodSeconds * 1e3, options);
+		if (constantTimeEqual(expected, code)) matchedStep = step;
+	}
+	return matchedStep;
+};
+const createTotpUri = (input) => {
+	validateTotpOptions({
+		digits: input.digits,
+		periodSeconds: input.periodSeconds
+	});
+	if (typeof input.issuer !== "string" || input.issuer.trim().length === 0 || typeof input.account !== "string" || input.account.trim().length === 0) throw new require_auth_errors.AuthValidationError("A TOTP issuer and account name are required.");
+	decodeBase32(input.secret);
+	return `otpauth://totp/${encodeURIComponent(`${input.issuer.trim()}:${input.account.trim()}`)}?${new URLSearchParams({
+		secret: input.secret,
+		issuer: input.issuer.trim(),
+		algorithm: "SHA1",
+		digits: String(input.digits),
+		period: String(input.periodSeconds)
+	}).toString()}`;
+};
+exports.createTotpUri = createTotpUri;
+exports.decodeBase32 = decodeBase32;
+exports.encodeBase32 = encodeBase32;
+exports.generateTotpCode = generateTotpCode;
+exports.generateTotpSecret = generateTotpSecret;
+exports.verifyTotpCode = verifyTotpCode;
+
+//# sourceMappingURL=totp.utils.cjs.map