@uln/auth 0.3.0 → 0.4.1

package/dist/totp.js

@@ -0,0 +1,129 @@
+// @bun
+// src/totp.ts
+var TOTP_PERIOD = 30;
+var TOTP_DIGITS = 6;
+var TOTP_WINDOW = 1;
+var BASE32_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
+function base32Encode(data) {
+  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 & 31];
+    }
+  }
+  if (bits > 0) {
+    output += BASE32_ALPHABET[value << 5 - bits & 31];
+  }
+  return output;
+}
+function base32Decode(encoded) {
+  const cleaned = encoded.replace(/[=\s]/g, "").toUpperCase();
+  const output = [];
+  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 & 255);
+    }
+  }
+  return new Uint8Array(output);
+}
+function generateTotpSecret() {
+  const bytes = new Uint8Array(20);
+  crypto.getRandomValues(bytes);
+  return base32Encode(bytes);
+}
+function getTotpUri(secret, email, issuer) {
+  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()}`;
+}
+async function generateCode(secret, counter) {
+  const keyBytes = base32Decode(secret);
+  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"]);
+  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));
+  const offset = (hmac[hmac.length - 1] ?? 0) & 15;
+  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 & 127) << 24 | (b1 & 255) << 16 | (b2 & 255) << 8 | b3 & 255;
+  return String(code % 10 ** TOTP_DIGITS).padStart(TOTP_DIGITS, "0");
+}
+async function currentTotpCode(secret, nowMs = Date.now()) {
+  const step = Math.floor(nowMs / 1000 / TOTP_PERIOD);
+  return generateCode(secret, step);
+}
+async function verifyTotpCode(secret, code) {
+  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;
+}
+var BACKUP_CODE_COUNT = 10;
+var BACKUP_CODE_LENGTH = 8;
+var BACKUP_CODE_CHARS = "abcdefghijklmnopqrstuvwxyz0123456789";
+function generateBackupCodes() {
+  const codes = [];
+  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;
+}
+async function hashBackupCode(code) {
+  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("");
+}
+function timingSafeEqual(a, b) {
+  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;
+}
+export {
+  verifyTotpCode,
+  hashBackupCode,
+  getTotpUri,
+  generateTotpSecret,
+  generateBackupCodes,
+  currentTotpCode,
+  base32Encode
+};

package/dist/types.d.ts

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

package/dist/users.d.ts

@@ -1,4 +1,6 @@
 import type { User, UserStore } from "./types.ts";
+/** Validate email format. Rejects missing local/domain parts, whitespace, and emails over 254 chars. */
+export declare function isValidEmail(email: string): boolean;
 export declare function createUser(store: UserStore, input: {
     email: string;
     name: string;
@@ -6,4 +8,5 @@ export declare function createUser(store: UserStore, input: {
     isAdmin?: boolean;
 }): Promise<User>;
 export declare function verifyUserCredentials(store: UserStore, email: string, password: string): Promise<User | null>;
+export declare function updateName(store: UserStore, userId: string, name: string): Promise<void>;
 export declare function changePassword(store: UserStore, userId: string, newPassword: string): Promise<void>;

package/dist/users.js

@@ -47,7 +47,13 @@ async function verifyPassword(password, storedHash) {
 }
 
 // src/users.ts
+var EMAIL_REGEX = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+function isValidEmail(email) {
+  return email.length <= 254 && EMAIL_REGEX.test(email);
+}
 async function createUser(store, input) {
+  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`);
@@ -60,6 +66,8 @@ async function createUser(store, input) {
     passwordHash,
     isAdmin: input.isAdmin ?? false,
     emailVerified: input.isAdmin ?? false,
+    totpSecret: null,
+    totpEnabled: false,
     createdAt: now,
     updatedAt: now
   };
@@ -73,6 +81,17 @@ async function verifyUserCredentials(store, email, password) {
   const valid = await verifyPassword(password, user.passwordHash);
   return valid ? user : null;
 }
+async function updateName(store, userId, name) {
+  const user = await store.getUser(userId);
+  if (!user)
+    throw new Error(`User ${userId} not found`);
+  const updated = {
+    ...user,
+    name,
+    updatedAt: new Date().toISOString()
+  };
+  await store.saveUser(updated);
+}
 async function changePassword(store, userId, newPassword) {
   const user = await store.getUser(userId);
   if (!user)
@@ -86,6 +105,8 @@ async function changePassword(store, userId, newPassword) {
 }
 export {
   verifyUserCredentials,
+  updateName,
+  isValidEmail,
   createUser,
   changePassword
 };

package/package.json

@@ -1,64 +1,68 @@
 {
-	"name": "@uln/auth",
-	"version": "0.3.0",
-	"type": "module",
-	"exports": {
-		".": {
-			"bun": "./src/index.ts",
-			"import": "./dist/index.js",
-			"types": "./dist/index.d.ts"
-		},
-		"./client": {
-			"bun": "./src/client.ts",
-			"import": "./dist/client.js",
-			"types": "./dist/client.d.ts"
-		},
-		"./service": {
-			"bun": "./src/service.ts",
-			"import": "./dist/service.js",
-			"types": "./dist/service.d.ts"
-		},
-		"./hono": {
-			"bun": "./src/hono.ts",
-			"import": "./dist/hono.js",
-			"types": "./dist/hono.d.ts"
-		}
-	},
-	"files": [
-		"dist",
-		"src",
-		"!src/**/*.test.ts"
-	],
-	"scripts": {
-		"dev": "bunx vite",
-		"dev:worker": "bunx wrangler dev",
-		"build": "bun run scripts/build.ts",
-		"check": "biome check --write .",
-		"test": "bun test",
-		"deploy": "bunx wrangler d1 migrations apply uln-auth --remote && bunx wrangler deploy",
-		"publish:check": "bun run scripts/publish.ts check",
-		"publish:release": "bun run scripts/publish.ts release"
-	},
-	"devDependencies": {
-		"@biomejs/biome": "^1.9.4",
-		"@cloudflare/workers-types": "^4.20260317.1",
-		"@types/bun": "latest",
-		"@types/react": "^19.2.14",
-		"@types/react-dom": "^19.2.3",
-		"@vitejs/plugin-react": "^6.0.1",
-		"hono": "^4.12.8",
-		"react": "^19.2.4",
-		"react-dom": "^19.2.4",
-		"react-router": "^7.13.1",
-		"vite": "^8.0.1"
-	},
-	"peerDependencies": {
-		"hono": "^4",
-		"typescript": "^5"
-	},
-	"peerDependenciesMeta": {
-		"hono": {
-			"optional": true
-		}
-	}
+  "name": "@uln/auth",
+  "version": "0.4.1",
+  "type": "module",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./client": {
+      "bun": "./src/client.ts",
+      "import": "./dist/client.js",
+      "types": "./dist/client.d.ts"
+    },
+    "./service": {
+      "bun": "./src/service.ts",
+      "import": "./dist/service.js",
+      "types": "./dist/service.d.ts"
+    },
+    "./hono": {
+      "bun": "./src/hono.ts",
+      "import": "./dist/hono.js",
+      "types": "./dist/hono.d.ts"
+    }
+  },
+  "files": ["dist", "src", "!src/**/*.test.ts"],
+  "scripts": {
+    "dev": "bunx vite",
+    "dev:worker": "bunx wrangler dev",
+    "build": "bun run scripts/build.ts",
+    "check": "biome check --write .",
+    "test": "bun test",
+    "ci": "biome check . && bun test --coverage",
+    "migrate:local": "bunx wrangler d1 migrations apply uln-auth --local",
+    "migrate:remote": "bunx wrangler d1 migrations apply uln-auth --remote",
+    "deploy": "bun run migrate:remote && bunx wrangler deploy",
+    "publish:check": "bun run scripts/publish.ts check",
+    "publish:release": "bun run scripts/publish.ts release"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^1.9.4",
+    "@uln/ui": "^0.2.0",
+    "@cloudflare/workers-types": "^4.20260317.1",
+    "@types/bun": "latest",
+    "@types/qrcode": "^1.5.6",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "@uln/log": "^0.3.0",
+    "@vitejs/plugin-react": "^6.0.1",
+    "hono": "^4.12.8",
+    "qrcode": "^1.5.4",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
+    "react-router": "^7.13.1",
+    "vite": "^8.0.1"
+  },
+  "peerDependencies": {
+    "hono": "^4",
+    "typescript": "^5"
+  },
+  "peerDependenciesMeta": {
+    "hono": {
+      "optional": true
+    }
+  },
+  "dependencies": {}
 }

package/src/client.ts

@@ -1,6 +1,7 @@
 export type { TokenPayload, VerifyConfig, PublicKeyEntry, CookieConfig } from "./types.ts";
 export { validateToken, importPublicKey } from "./token.ts";
 export { makeSessionCookie, makeClearCookie, extractCookie } from "./cookie.ts";
+export type { AuthCodeExchangeConfig } from "./middleware.ts";
 export { getAuthUser, redirectToLogin, handleCallback, getClientIP, checkBearerToken } from "./middleware.ts";
 
 import { importPublicKey } from "./token.ts";

package/src/hono.ts

@@ -107,10 +107,36 @@ async function validateWithBinding(token: string, binding: Fetcher): Promise<Tok
   };
 }
 
+async function exchangeCodeWithPublicEndpoint(
+  code: string,
+  redirectOrigin: string,
+  authUrl: string,
+): Promise<string | null> {
+  const res = await fetch(`${authUrl}/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;
+}
+
+async function exchangeCodeWithBinding(code: string, redirectOrigin: string, binding: Fetcher): Promise<string | null> {
+  const res = await binding.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;
+}
+
 /**
  * Hono middleware that handles the full auth flow:
  *
- * 1. If `?token=` in URL → validate, set cookie, redirect to clean URL
+ * 1. If `?code=` in URL → exchange for token, set cookie, redirect to clean URL
  * 2. If session cookie present → validate, set `c.get("user")`
  * 3. If unauthenticated → redirect to auth.uln.industries/login
  *
@@ -149,6 +175,19 @@ export function auth(options?: AuthOptions): MiddlewareHandler {
     return validateWithPublicKeys(token, authUrl, maxAge);
   }
 
+  async function exchangeCode(
+    code: string,
+    redirectOrigin: string,
+    env: Record<string, unknown>,
+  ): Promise<string | null> {
+    if (bindingName) {
+      const binding = env[bindingName] as Fetcher | undefined;
+      if (!binding) throw new Error(`Service binding "${bindingName}" not found in env`);
+      return exchangeCodeWithBinding(code, redirectOrigin, binding);
+    }
+    return exchangeCodeWithPublicEndpoint(code, redirectOrigin, authUrl);
+  }
+
   return async (c, next) => {
     const url = new URL(c.req.url);
 
@@ -157,21 +196,24 @@ export function auth(options?: AuthOptions): MiddlewareHandler {
       return next();
     }
 
-    // Step 1: Handle ?token= callback (login redirect landing)
-    const incomingToken = url.searchParams.get("token");
-    if (incomingToken) {
-      const payload = await validate(incomingToken, c.env as Record<string, unknown>);
+    // Step 1: Handle ?code= callback (login redirect landing)
+    const incomingCode = url.searchParams.get("code");
+    if (incomingCode) {
+      const token = await exchangeCode(incomingCode, url.origin, c.env as Record<string, unknown>);
+      if (!token) {
+        return c.text("Invalid code", 401);
+      }
+      const payload = await validate(token, c.env as Record<string, unknown>);
       if (!payload) {
         return c.text("Invalid token", 401);
       }
 
-      // Set cookie and redirect to clean URL (strip token param)
-      url.searchParams.delete("token");
+      url.searchParams.delete("code");
       return new Response(null, {
         status: 302,
         headers: {
           Location: url.toString(),
-          "Set-Cookie": makeSessionCookie(cookieConf, incomingToken),
+          "Set-Cookie": makeSessionCookie(cookieConf, token),
         },
       });
     }
@@ -189,7 +231,7 @@ export function auth(options?: AuthOptions): MiddlewareHandler {
       }
     }
 
-    // Step 3: Check Authorization header
+    // Step 4: Check Authorization header
     const authHeader = c.req.header("Authorization");
     if (authHeader?.startsWith("Bearer ")) {
       const token = authHeader.substring(7);
@@ -201,9 +243,11 @@ export function auth(options?: AuthOptions): MiddlewareHandler {
       return c.json({ error: "Invalid token" }, 401);
     }
 
-    // Step 4: Redirect to login
-    const loginUrl = `${authUrl}/login?redirect=${encodeURIComponent(c.req.url)}`;
-    return c.redirect(loginUrl, 302);
+    // Step 5: Redirect to login
+    const loginUrl = new URL("/login", authUrl);
+    loginUrl.searchParams.set("redirect", c.req.url);
+    loginUrl.searchParams.set("response_type", "code");
+    return c.redirect(loginUrl.toString(), 302);
   };
 }
 

package/src/index.ts

@@ -18,4 +18,12 @@ export { makeSessionCookie, makeClearCookie, extractCookie } from "./cookie.ts";
 export { checkRateLimit, recordFailedAttempt, clearRateLimit } from "./rate-limit.ts";
 export type { RateLimitResult } from "./rate-limit.ts";
 export { getClientIP, checkBearerToken, getAuthUser, redirectToLogin } from "./middleware.ts";
-export { createUser, verifyUserCredentials, changePassword } from "./users.ts";
+export { createUser, verifyUserCredentials, changePassword, isValidEmail } from "./users.ts";
+export {
+  generateTotpSecret,
+  getTotpUri,
+  verifyTotpCode,
+  base32Encode,
+  generateBackupCodes,
+  hashBackupCode,
+} from "./totp.ts";

package/src/middleware.ts

@@ -2,6 +2,10 @@ import { extractCookie, makeSessionCookie } from "./cookie.ts";
 import { validateToken } from "./token.ts";
 import type { CookieConfig, TokenPayload, VerifyConfig } from "./types.ts";
 
+export interface AuthCodeExchangeConfig {
+  authUrl: string;
+}
+
 export function getClientIP(request: Request): string {
   return (
     request.headers.get("cf-connecting-ip") ??
@@ -30,36 +34,59 @@ export async function getAuthUser(
 }
 
 export function redirectToLogin(currentUrl: string): Response {
-  const loginUrl = `https://auth.uln.industries/login?redirect=${encodeURIComponent(currentUrl)}`;
-  return Response.redirect(loginUrl, 302);
+  const loginUrl = new URL("/login", "https://auth.uln.industries");
+  loginUrl.searchParams.set("redirect", currentUrl);
+  loginUrl.searchParams.set("response_type", "code");
+  return Response.redirect(loginUrl.toString(), 302);
+}
+
+async function exchangeCode(
+  code: string,
+  redirectOrigin: string,
+  config: AuthCodeExchangeConfig,
+): Promise<string | null> {
+  const res = await fetch(`${config.authUrl}/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 the auth callback on consuming sites.
- * If the request URL has a `?token=` param, validates it, sets a session cookie,
- * and redirects to the same URL without the token param.
- * Returns null if there's no token param (not a callback request).
+ * If the request URL has a `?code=` param, exchanges it for a token,
+ * sets a session cookie, and redirects to the same URL without the code param.
+ * Returns null if there's no callback param.
  */
 export async function handleCallback(
   request: Request,
   verifyConfig: VerifyConfig,
   cookieConfig: CookieConfig,
+  exchangeConfig?: AuthCodeExchangeConfig,
 ): Promise<Response | null> {
   const url = new URL(request.url);
-  const token = url.searchParams.get("token");
-  if (!token) return null;
+  const code = url.searchParams.get("code");
+  if (code) {
+    if (!exchangeConfig) return redirectToLogin(url.origin);
+
+    const token = await exchangeCode(code, url.origin, exchangeConfig);
+    if (!token) return redirectToLogin(url.origin);
 
-  const payload = await validateToken(verifyConfig, token);
-  if (!payload) {
-    return redirectToLogin(url.origin);
+    const payload = await validateToken(verifyConfig, token);
+    if (!payload) return redirectToLogin(url.origin);
+
+    url.searchParams.delete("code");
+    return new Response(null, {
+      status: 302,
+      headers: {
+        Location: url.toString(),
+        "Set-Cookie": makeSessionCookie(cookieConfig, token),
+      },
+    });
   }
 
-  url.searchParams.delete("token");
-  return new Response(null, {
-    status: 302,
-    headers: {
-      Location: url.toString(),
-      "Set-Cookie": makeSessionCookie(cookieConfig, token),
-    },
-  });
+  return null;
 }

package/src/password.ts

@@ -31,12 +31,14 @@ async function deriveKey(password: string, salt: Uint8Array<ArrayBuffer>): Promi
   );
 }
 
+/** Hash a password with PBKDF2-SHA256 (100k iterations, 32-byte salt, 64-byte key). Returns `hex(salt):hex(key)`. */
 export async function hashPassword(password: string): Promise<string> {
   const salt = crypto.getRandomValues(new Uint8Array(SALT_LENGTH));
   const derived = await deriveKey(password, salt);
   return `${toHex(salt.buffer)}:${toHex(derived)}`;
 }
 
+/** Verify a password against a stored `hex(salt):hex(key)` hash. Uses constant-time comparison. */
 export async function verifyPassword(password: string, storedHash: string): Promise<boolean> {
   const separatorIndex = storedHash.indexOf(":");
   if (separatorIndex === -1) return false;

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,55 @@ export async function getAuthUser(
 
 /**
  * Redirect to the centralized login page at auth.uln.industries.
+ * Requests one-time auth-code callbacks 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);
+  const loginUrl = new URL("/login", "https://auth.uln.industries");
+  loginUrl.searchParams.set("redirect", currentUrl);
+  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.
+ * 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);
+
+    const payload = await verifyToken(authService, token);
+    if (!payload) return redirectToLogin(url.origin);
+
+    url.searchParams.delete("code");
+    return new Response(null, {
+      status: 302,
+      headers: {
+        Location: url.toString(),
+        "Set-Cookie": makeSessionCookie(cookieConfig, token),
+      },
+    });
+  }
+
+  return null;
 }