@uln/auth 0.2.0 → 0.4.0

package/src/service.ts

@@ -1,4 +1,4 @@
-import { extractCookie } from "./cookie.ts";
+import { extractCookie, makeSessionCookie } from "./cookie.ts";
 import type { CookieConfig, TokenPayload } from "./types.ts";
 export { makeSessionCookie, makeClearCookie } from "./cookie.ts";
 export type { TokenPayload, CookieConfig } from "./types.ts";
@@ -58,8 +58,69 @@ export async function getAuthUser(
 
 /**
  * Redirect to the centralized login page at auth.uln.industries.
+ * Requests one-time auth-code callbacks by default so signed tokens are not sent through URLs.
  */
-export function redirectToLogin(currentUrl: string): Response {
-  const loginUrl = `https://auth.uln.industries/login?redirect=${encodeURIComponent(currentUrl)}`;
-  return Response.redirect(loginUrl, 302);
+export function redirectToLogin(currentUrl: string, responseType: "code" | "token" = "code"): Response {
+  const loginUrl = new URL("/login", "https://auth.uln.industries");
+  loginUrl.searchParams.set("redirect", currentUrl);
+  if (responseType === "code") loginUrl.searchParams.set("response_type", "code");
+  return Response.redirect(loginUrl.toString(), 302);
+}
+
+async function exchangeCode(authService: Fetcher, code: string, redirectOrigin: string): Promise<string | null> {
+  const res = await authService.fetch("https://auth/api/exchange-code", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ code, redirectOrigin }),
+  });
+  if (!res.ok) return null;
+  const data = (await res.json()) as { token?: string };
+  return typeof data.token === "string" ? data.token : null;
+}
+
+/**
+ * Handle an auth callback on a consuming Worker using the auth service binding.
+ * Preferred `?code=` callbacks are exchanged for signed tokens before setting the local cookie.
+ * Legacy `?token=` callbacks are still accepted during migration and are stripped immediately.
+ * Returns null if the request has no auth callback parameters.
+ */
+export async function handleCallback(
+  request: Request,
+  authService: Fetcher,
+  cookieConfig: CookieConfig,
+): Promise<Response | null> {
+  const url = new URL(request.url);
+
+  const code = url.searchParams.get("code");
+  if (code) {
+    const token = await exchangeCode(authService, code, url.origin);
+    if (!token) return redirectToLogin(url.origin, "code");
+
+    const payload = await verifyToken(authService, token);
+    if (!payload) return redirectToLogin(url.origin, "code");
+
+    url.searchParams.delete("code");
+    return new Response(null, {
+      status: 302,
+      headers: {
+        Location: url.toString(),
+        "Set-Cookie": makeSessionCookie(cookieConfig, token),
+      },
+    });
+  }
+
+  const token = url.searchParams.get("token");
+  if (!token) return null;
+
+  const payload = await verifyToken(authService, token);
+  if (!payload) return redirectToLogin(url.origin, "code");
+
+  url.searchParams.delete("token");
+  return new Response(null, {
+    status: 302,
+    headers: {
+      Location: url.toString(),
+      "Set-Cookie": makeSessionCookie(cookieConfig, token),
+    },
+  });
 }

package/src/token.ts

@@ -23,6 +23,7 @@ function base64urlDecode(str: string): Uint8Array {
 const ECDSA_PARAMS = { name: "ECDSA", namedCurve: "P-256" } as const;
 const SIGN_PARAMS = { name: "ECDSA", hash: "SHA-256" } as const;
 
+/** Generate an ECDSA P-256 key pair for token signing. Returns a short `kid` and both JWK exports. */
 export async function generateKeyPair(): Promise<{ kid: string; privateKeyJwk: JsonWebKey; publicKeyJwk: JsonWebKey }> {
   const kid = crypto.randomUUID().slice(0, 8);
   const keyPair = await crypto.subtle.generateKey(ECDSA_PARAMS, true, ["sign", "verify"]);
@@ -34,10 +35,12 @@ export async function generateKeyPair(): Promise<{ kid: string; privateKeyJwk: J
   return { kid, privateKeyJwk: privateExport, publicKeyJwk: publicExport };
 }
 
+/** Import an ECDSA P-256 private key from JWK for signing. */
 export async function importPrivateKey(jwk: JsonWebKey): Promise<CryptoKey> {
   return crypto.subtle.importKey("jwk", jwk, ECDSA_PARAMS, false, ["sign"]);
 }
 
+/** Import an ECDSA P-256 public key from JWK for verification. */
 export async function importPublicKey(jwk: JsonWebKey): Promise<CryptoKey> {
   return crypto.subtle.importKey("jwk", jwk, ECDSA_PARAMS, false, ["verify"]);
 }
@@ -51,6 +54,7 @@ export interface CreateTokenInput {
   flags: Record<string, string[]>;
 }
 
+/** Create a signed token: `base64url(JSON payload).base64url(ECDSA-SHA256 signature)`. */
 export async function createToken(config: SigningConfig, user: CreateTokenInput): Promise<string> {
   const now = Math.floor(Date.now() / 1000);
   const payload: TokenPayload = {
@@ -71,6 +75,7 @@ export async function createToken(config: SigningConfig, user: CreateTokenInput)
   return `${payloadB64}.${sigB64}`;
 }
 
+/** Validate a signed token. Returns the payload if valid and not expired, or null. Matches `kid` to find the correct public key. */
 export async function validateToken(config: VerifyConfig, token: string): Promise<TokenPayload | null> {
   const dotIndex = token.indexOf(".");
   if (dotIndex === -1) return null;

package/src/totp.ts

@@ -0,0 +1,165 @@
+/**
+ * TOTP (Time-based One-Time Password) implementation per RFC 6238.
+ * Uses Web Crypto API only — no node:crypto imports.
+ *
+ * Algorithm: HMAC-SHA1, 6 digits, 30-second period, ±1 step window.
+ */
+
+const TOTP_PERIOD = 30;
+const TOTP_DIGITS = 6;
+const TOTP_WINDOW = 1; // allow ±1 step for clock drift
+
+// ── Base32 encoding/decoding (RFC 4648) ──
+
+const BASE32_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
+
+export function base32Encode(data: Uint8Array): string {
+  let bits = 0;
+  let value = 0;
+  let output = "";
+
+  for (const byte of data) {
+    value = (value << 8) | byte;
+    bits += 8;
+
+    while (bits >= 5) {
+      bits -= 5;
+      output += BASE32_ALPHABET[(value >>> bits) & 0x1f];
+    }
+  }
+
+  if (bits > 0) {
+    output += BASE32_ALPHABET[(value << (5 - bits)) & 0x1f];
+  }
+
+  return output;
+}
+
+function base32Decode(encoded: string): Uint8Array {
+  const cleaned = encoded.replace(/[=\s]/g, "").toUpperCase();
+  const output: number[] = [];
+  let bits = 0;
+  let value = 0;
+
+  for (const char of cleaned) {
+    const idx = BASE32_ALPHABET.indexOf(char);
+    if (idx === -1) throw new Error(`Invalid base32 character: ${char}`);
+    value = (value << 5) | idx;
+    bits += 5;
+
+    if (bits >= 8) {
+      bits -= 8;
+      output.push((value >>> bits) & 0xff);
+    }
+  }
+
+  return new Uint8Array(output);
+}
+
+// ── Core TOTP functions ──
+
+/** Generate a 20-byte random TOTP secret, returned as base32. */
+export function generateTotpSecret(): string {
+  const bytes = new Uint8Array(20);
+  crypto.getRandomValues(bytes);
+  return base32Encode(bytes);
+}
+
+/** Build an otpauth:// URI for authenticator apps. */
+export function getTotpUri(secret: string, email: string, issuer: string): string {
+  const label = `${encodeURIComponent(issuer)}:${encodeURIComponent(email)}`;
+  const params = new URLSearchParams({
+    secret,
+    issuer,
+    algorithm: "SHA1",
+    digits: String(TOTP_DIGITS),
+    period: String(TOTP_PERIOD),
+  });
+  return `otpauth://totp/${label}?${params.toString()}`;
+}
+
+/** Generate a TOTP code for the given secret and time step. */
+async function generateCode(secret: string, counter: number): Promise<string> {
+  const keyBytes = base32Decode(secret);
+  // Copy into a fresh ArrayBuffer to satisfy the BufferSource type
+  const keyBuffer = new ArrayBuffer(keyBytes.byteLength);
+  new Uint8Array(keyBuffer).set(keyBytes);
+  const key = await crypto.subtle.importKey("raw", keyBuffer, { name: "HMAC", hash: "SHA-1" }, false, ["sign"]);
+
+  // Counter as big-endian 8-byte buffer
+  const counterBuf = new ArrayBuffer(8);
+  const view = new DataView(counterBuf);
+  view.setUint32(4, counter);
+
+  const hmac = new Uint8Array(await crypto.subtle.sign("HMAC", key, counterBuf));
+
+  // Dynamic truncation (RFC 4226 §5.4)
+  // HMAC-SHA1 always produces 20 bytes, so all indices are safe
+  const offset = (hmac[hmac.length - 1] ?? 0) & 0x0f;
+  const b0 = hmac[offset] ?? 0;
+  const b1 = hmac[offset + 1] ?? 0;
+  const b2 = hmac[offset + 2] ?? 0;
+  const b3 = hmac[offset + 3] ?? 0;
+  const code = ((b0 & 0x7f) << 24) | ((b1 & 0xff) << 16) | ((b2 & 0xff) << 8) | (b3 & 0xff);
+
+  return String(code % 10 ** TOTP_DIGITS).padStart(TOTP_DIGITS, "0");
+}
+
+/** Six-digit code for the current 30-second step (deterministic counterpart to verifyTotpCode in tests). */
+export async function currentTotpCode(secret: string, nowMs = Date.now()): Promise<string> {
+  const step = Math.floor(nowMs / 1000 / TOTP_PERIOD);
+  return generateCode(secret, step);
+}
+
+/** Verify a TOTP code against the secret. Allows ±1 time step for clock drift. */
+export async function verifyTotpCode(secret: string, code: string): Promise<boolean> {
+  if (code.length !== TOTP_DIGITS) return false;
+
+  const now = Math.floor(Date.now() / 1000);
+  const currentStep = Math.floor(now / TOTP_PERIOD);
+
+  for (let offset = -TOTP_WINDOW; offset <= TOTP_WINDOW; offset++) {
+    const expected = await generateCode(secret, currentStep + offset);
+    if (timingSafeEqual(code, expected)) return true;
+  }
+
+  return false;
+}
+
+const BACKUP_CODE_COUNT = 10;
+const BACKUP_CODE_LENGTH = 8;
+const BACKUP_CODE_CHARS = "abcdefghijklmnopqrstuvwxyz0123456789";
+
+/** Generate a set of one-time backup codes for 2FA recovery. Returns plain-text codes. */
+export function generateBackupCodes(): string[] {
+  const codes: string[] = [];
+  for (let i = 0; i < BACKUP_CODE_COUNT; i++) {
+    const bytes = new Uint8Array(BACKUP_CODE_LENGTH);
+    crypto.getRandomValues(bytes);
+    let code = "";
+    for (const byte of bytes) {
+      code += BACKUP_CODE_CHARS[byte % BACKUP_CODE_CHARS.length];
+    }
+    codes.push(code);
+  }
+  return codes;
+}
+
+/** Hash a backup code for storage. Uses SHA-256 (no salt needed — codes are high-entropy). */
+export async function hashBackupCode(code: string): Promise<string> {
+  const data = new TextEncoder().encode(code.toLowerCase());
+  const hash = await crypto.subtle.digest("SHA-256", data);
+  return Array.from(new Uint8Array(hash))
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("");
+}
+
+/** Constant-time string comparison to prevent timing attacks. */
+function timingSafeEqual(a: string, b: string): boolean {
+  if (a.length !== b.length) return false;
+  let result = 0;
+  for (let i = 0; i < a.length; i++) {
+    result |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  }
+  return result === 0;
+}

package/src/types.ts

@@ -5,6 +5,8 @@ export interface User {
   passwordHash: string;
   isAdmin: boolean;
   emailVerified: boolean;
+  totpSecret: string | null;
+  totpEnabled: boolean;
   createdAt: string;
   updatedAt: string;
 }

package/src/users.ts

@@ -1,10 +1,18 @@
 import { hashPassword, verifyPassword } from "./password.ts";
 import type { User, UserStore } from "./types.ts";
 
+const EMAIL_REGEX = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+
+/** Validate email format. Rejects missing local/domain parts, whitespace, and emails over 254 chars. */
+export function isValidEmail(email: string): boolean {
+  return email.length <= 254 && EMAIL_REGEX.test(email);
+}
+
 export async function createUser(
   store: UserStore,
   input: { email: string; name: string; password?: string; isAdmin?: boolean },
 ): Promise<User> {
+  if (!isValidEmail(input.email)) throw new Error("Invalid email address");
   const existing = await store.getUserByEmail(input.email);
   if (existing) throw new Error(`User with email ${input.email} already exists`);
 
@@ -17,6 +25,8 @@ export async function createUser(
     passwordHash,
     isAdmin: input.isAdmin ?? false,
     emailVerified: input.isAdmin ?? false,
+    totpSecret: null,
+    totpEnabled: false,
     createdAt: now,
     updatedAt: now,
   };
@@ -33,6 +43,18 @@ export async function verifyUserCredentials(store: UserStore, email: string, pas
   return valid ? user : null;
 }
 
+export async function updateName(store: UserStore, userId: string, name: string): Promise<void> {
+  const user = await store.getUser(userId);
+  if (!user) throw new Error(`User ${userId} not found`);
+
+  const updated: User = {
+    ...user,
+    name,
+    updatedAt: new Date().toISOString(),
+  };
+  await store.saveUser(updated);
+}
+
 export async function changePassword(store: UserStore, userId: string, newPassword: string): Promise<void> {
   const user = await store.getUser(userId);
   if (!user) throw new Error(`User ${userId} not found`);