@puzzle-ui/auth 0.0.0-stage → 0.5.0

package/dist/utils/totp.utils.cjs.map

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

package/dist/utils/totp.utils.d.cts

@@ -0,0 +1,26 @@
+type TotpOptions = {
+  readonly digits: number;
+  readonly periodSeconds: number;
+};
+type TotpVerificationOptions = TotpOptions & {
+  readonly window: number;
+};
+export declare const encodeBase32: (input: Uint8Array) => string;
+export declare const decodeBase32: (input: string) => Uint8Array;
+export declare const generateTotpSecret: () => string;
+export declare const generateTotpCode: (secret: string, timestamp: number, options: TotpOptions) => Promise<string>;
+/**
+ * Returns the matching time step, or null.
+ *
+ * The caller must persist the accepted step and reject a step that
+ * has already been consumed.
+ */
+export declare const verifyTotpCode: (secret: string, code: string, timestamp: number, options: TotpVerificationOptions) => Promise<number | null>;
+export declare const createTotpUri: (input: {
+  readonly issuer: string;
+  readonly account: string;
+  readonly secret: string;
+  readonly digits: number;
+  readonly periodSeconds: number;
+}) => string;
+export {};

package/dist/utils/totp.utils.d.ts

@@ -0,0 +1,26 @@
+type TotpOptions = {
+  readonly digits: number;
+  readonly periodSeconds: number;
+};
+type TotpVerificationOptions = TotpOptions & {
+  readonly window: number;
+};
+export declare const encodeBase32: (input: Uint8Array) => string;
+export declare const decodeBase32: (input: string) => Uint8Array;
+export declare const generateTotpSecret: () => string;
+export declare const generateTotpCode: (secret: string, timestamp: number, options: TotpOptions) => Promise<string>;
+/**
+ * Returns the matching time step, or null.
+ *
+ * The caller must persist the accepted step and reject a step that
+ * has already been consumed.
+ */
+export declare const verifyTotpCode: (secret: string, code: string, timestamp: number, options: TotpVerificationOptions) => Promise<number | null>;
+export declare const createTotpUri: (input: {
+  readonly issuer: string;
+  readonly account: string;
+  readonly secret: string;
+  readonly digits: number;
+  readonly periodSeconds: number;
+}) => string;
+export {};

package/dist/utils/totp.utils.js

@@ -0,0 +1,140 @@
+import { AuthConfigurationError, AuthValidationError } from "../errors/auth.errors.js";
+// src/utils/totp.utils.ts
+const BASE32_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
+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 validateTotpOptions = (options) => {
+	if (!Number.isInteger(options.digits) || options.digits < 6 || options.digits > 8) throw new AuthValidationError("TOTP digits must be between 6 and 8.");
+	if (!Number.isInteger(options.periodSeconds) || options.periodSeconds < 15 || options.periodSeconds > 120) throw new AuthValidationError("The TOTP period must be between 15 and 120 seconds.");
+};
+const getTimeStep = (timestamp, periodSeconds) => {
+	if (!Number.isFinite(timestamp) || timestamp < 0) throw new AuthValidationError("A valid TOTP timestamp is required.");
+	const step = Math.floor(timestamp / 1e3 / periodSeconds);
+	if (!Number.isSafeInteger(step)) throw new 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 AuthValidationError("A valid TOTP secret is required.");
+	const normalized = input.toUpperCase().replace(/[\s=-]/g, "");
+	if (normalized.length === 0) throw new 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 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 AuthValidationError("The TOTP secret is invalid.");
+	if (output.length === 0) throw new 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 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 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 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()}`;
+};
+export { createTotpUri, decodeBase32, encodeBase32, generateTotpCode, generateTotpSecret, verifyTotpCode };
+
+//# sourceMappingURL=totp.utils.js.map

package/dist/utils/totp.utils.js.map

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

package/package.json

@@ -1,6 +1,47 @@
 {
   "name": "@puzzle-ui/auth",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.5.0",
+  "description": "Framework-independent authentication core for Puzzle.",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit -p .",
+    "test": "node --test",
+    "vitest": "node --test",
+    "clean": "rm -rf dist",
+    "prepack": "tsdown"
+  },
+  "devDependencies": {
+    "tsdown": "^0.23.1",
+    "typescript": "^7.0.2"
+  },
+  "dependencies": {
+    "@puzzle-ui/storage": "^0.5.0",
+    "@puzzle-ui/session": "^0.5.0",
+    "@simplewebauthn/server": "^14.1.0"
+  }
+}