@uln/auth 0.2.0 → 0.4.0

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.2.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 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.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",
+    "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,7 +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 { getAuthUser, redirectToLogin, getClientIP, checkBearerToken } from "./middleware.ts";
+export { getAuthUser, redirectToLogin, handleCallback, getClientIP, checkBearerToken } from "./middleware.ts";
 
 import { importPublicKey } from "./token.ts";
 import type { PublicKeyEntry } from "./types.ts";

package/src/hono.ts

@@ -28,6 +28,9 @@ interface AuthOptions {
 
   /** Cookie/token max age in seconds. Defaults to 86400 (24h). */
   maxAge?: number;
+
+  /** Redirect callback mode. "code" avoids putting signed tokens in URLs. Defaults to "code". */
+  responseType?: "code" | "token";
 }
 
 const DEFAULT_AUTH_URL = "https://auth.uln.industries";
@@ -107,6 +110,32 @@ 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:
  *
@@ -135,6 +164,7 @@ export function auth(options?: AuthOptions): MiddlewareHandler {
   const authUrl = options?.authUrl ?? DEFAULT_AUTH_URL;
   const cookieName = options?.cookie ?? DEFAULT_COOKIE;
   const maxAge = options?.maxAge ?? DEFAULT_MAX_AGE;
+  const responseType = options?.responseType ?? "code";
   const publicPaths = options?.public ?? [];
   const bindingName = options?.binding;
 
@@ -149,6 +179,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,7 +200,29 @@ export function auth(options?: AuthOptions): MiddlewareHandler {
       return next();
     }
 
-    // Step 1: Handle ?token= callback (login redirect landing)
+    // Step 1: Handle ?code= callback (preferred 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);
+      }
+
+      url.searchParams.delete("code");
+      return new Response(null, {
+        status: 302,
+        headers: {
+          Location: url.toString(),
+          "Set-Cookie": makeSessionCookie(cookieConf, token),
+        },
+      });
+    }
+
+    // Step 2: Handle legacy ?token= callback
     const incomingToken = url.searchParams.get("token");
     if (incomingToken) {
       const payload = await validate(incomingToken, c.env as Record<string, unknown>);
@@ -176,7 +241,7 @@ export function auth(options?: AuthOptions): MiddlewareHandler {
       });
     }
 
-    // Step 2: Check session cookie
+    // Step 3: Check session cookie
     const cookieHeader = c.req.header("Cookie");
     if (cookieHeader) {
       const token = extractCookie(cookieHeader, cookieName);
@@ -189,7 +254,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 +266,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);
+    if (responseType === "code") 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

@@ -1,7 +1,11 @@
-import { extractCookie } from "./cookie.ts";
+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") ??
@@ -29,7 +33,75 @@ export async function getAuthUser(
   return validateToken(verifyConfig, token);
 }
 
-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(
+  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 `?code=` or legacy `?token=` param, sets a session cookie,
+ * and redirects to the same URL without the token 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 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, "code");
+
+    const payload = await validateToken(verifyConfig, 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 validateToken(verifyConfig, token);
+  if (!payload) {
+    return redirectToLogin(url.origin);
+  }
+
+  url.searchParams.delete("token");
+  return new Response(null, {
+    status: 302,
+    headers: {
+      Location: url.toString(),
+      "Set-Cookie": makeSessionCookie(cookieConfig, token),
+    },
+  });
 }

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;