@uln/auth 0.2.0 → 0.4.0

package/dist/client.d.ts

@@ -1,6 +1,6 @@
 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 type { PublicKeyEntry } from "./types.ts";
 export declare function fetchPublicKeys(baseUrl: string): Promise<PublicKeyEntry[]>;

package/dist/client.js

@@ -130,9 +130,60 @@ async function getAuthUser(request, verifyConfig, cookieConfig) {
     return null;
   return validateToken(verifyConfig, token);
 }
-function redirectToLogin(currentUrl) {
-  const loginUrl = `https://auth.uln.industries/login?redirect=${encodeURIComponent(currentUrl)}`;
-  return Response.redirect(loginUrl, 302);
+function redirectToLogin(currentUrl, responseType = "code") {
+  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, redirectOrigin, config) {
+  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();
+  return typeof data.token === "string" ? data.token : null;
+}
+async function handleCallback(request, verifyConfig, cookieConfig, exchangeConfig) {
+  const url = new URL(request.url);
+  const code = url.searchParams.get("code");
+  if (code) {
+    if (!exchangeConfig)
+      return redirectToLogin(url.origin);
+    const token2 = await exchangeCode(code, url.origin, exchangeConfig);
+    if (!token2)
+      return redirectToLogin(url.origin, "code");
+    const payload2 = await validateToken(verifyConfig, token2);
+    if (!payload2)
+      return redirectToLogin(url.origin, "code");
+    url.searchParams.delete("code");
+    return new Response(null, {
+      status: 302,
+      headers: {
+        Location: url.toString(),
+        "Set-Cookie": makeSessionCookie(cookieConfig, token2)
+      }
+    });
+  }
+  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)
+    }
+  });
 }
 // src/client.ts
 async function fetchPublicKeys(baseUrl) {
@@ -151,6 +202,7 @@ export {
   makeSessionCookie,
   makeClearCookie,
   importPublicKey,
+  handleCallback,
   getClientIP,
   getAuthUser,
   fetchPublicKeys,

package/dist/hono.d.ts

@@ -19,6 +19,8 @@ interface AuthOptions {
     cookie?: string;
     /** 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";
 }
 /**
  * Hono middleware that handles the full auth flow:

package/dist/hono.js

@@ -172,10 +172,33 @@ async function validateWithBinding(token, binding) {
     exp: 0
   };
 }
+async function exchangeCodeWithPublicEndpoint(code, redirectOrigin, authUrl) {
+  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();
+  return typeof data.token === "string" ? data.token : null;
+}
+async function exchangeCodeWithBinding(code, redirectOrigin, binding) {
+  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();
+  return typeof data.token === "string" ? data.token : null;
+}
 function auth(options) {
   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;
   const cookieConf = { name: cookieName, maxAgeSeconds: maxAge, secure: true };
@@ -188,11 +211,39 @@ function auth(options) {
     }
     return validateWithPublicKeys(token, authUrl, maxAge);
   }
+  async function exchangeCode(code, redirectOrigin, env) {
+    if (bindingName) {
+      const binding = env[bindingName];
+      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);
     if (isPublicPath(url.pathname, publicPaths)) {
       return next();
     }
+    const incomingCode = url.searchParams.get("code");
+    if (incomingCode) {
+      const token = await exchangeCode(incomingCode, url.origin, c.env);
+      if (!token) {
+        return c.text("Invalid code", 401);
+      }
+      const payload = await validate(token, c.env);
+      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)
+        }
+      });
+    }
     const incomingToken = url.searchParams.get("token");
     if (incomingToken) {
       const payload = await validate(incomingToken, c.env);
@@ -229,8 +280,11 @@ function auth(options) {
       }
       return c.json({ error: "Invalid token" }, 401);
     }
-    const loginUrl = `${authUrl}/login?redirect=${encodeURIComponent(c.req.url)}`;
-    return c.redirect(loginUrl, 302);
+    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);
   };
 }
 function getUser(c) {

package/dist/index.d.ts

@@ -6,4 +6,5 @@ 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/dist/index.js

@@ -130,9 +130,60 @@ async function getAuthUser(request, verifyConfig, cookieConfig) {
     return null;
   return validateToken(verifyConfig, token);
 }
-function redirectToLogin(currentUrl) {
-  const loginUrl = `https://auth.uln.industries/login?redirect=${encodeURIComponent(currentUrl)}`;
-  return Response.redirect(loginUrl, 302);
+function redirectToLogin(currentUrl, responseType = "code") {
+  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, redirectOrigin, config) {
+  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();
+  return typeof data.token === "string" ? data.token : null;
+}
+async function handleCallback(request, verifyConfig, cookieConfig, exchangeConfig) {
+  const url = new URL(request.url);
+  const code = url.searchParams.get("code");
+  if (code) {
+    if (!exchangeConfig)
+      return redirectToLogin(url.origin);
+    const token2 = await exchangeCode(code, url.origin, exchangeConfig);
+    if (!token2)
+      return redirectToLogin(url.origin, "code");
+    const payload2 = await validateToken(verifyConfig, token2);
+    if (!payload2)
+      return redirectToLogin(url.origin, "code");
+    url.searchParams.delete("code");
+    return new Response(null, {
+      status: 302,
+      headers: {
+        Location: url.toString(),
+        "Set-Cookie": makeSessionCookie(cookieConfig, token2)
+      }
+    });
+  }
+  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)
+    }
+  });
 }
 
 // src/password.ts
@@ -183,7 +234,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`);
@@ -196,6 +253,8 @@ async function createUser(store, input) {
     passwordHash,
     isAdmin: input.isAdmin ?? false,
     emailVerified: input.isAdmin ?? false,
+    totpSecret: null,
+    totpEnabled: false,
     createdAt: now,
     updatedAt: now
   };
@@ -209,6 +268,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)
@@ -247,25 +317,152 @@ async function recordFailedAttempt(store, key, config) {
 async function clearRateLimit(store, key) {
   await store.delete(key);
 }
+
+// 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 {
   verifyUserCredentials,
+  verifyTotpCode,
   verifyPassword,
   validateToken,
   redirectToLogin,
   recordFailedAttempt,
   makeSessionCookie,
   makeClearCookie,
+  isValidEmail,
   importPublicKey,
   importPrivateKey,
   hashPassword,
+  hashBackupCode,
+  getTotpUri,
   getClientIP,
   getAuthUser,
+  generateTotpSecret,
   generateKeyPair,
+  generateBackupCodes,
   extractCookie,
   createUser,
   createToken,
   clearRateLimit,
   checkRateLimit,
   checkBearerToken,
-  changePassword
+  changePassword,
+  base32Encode
 };

package/dist/middleware.d.ts

@@ -1,5 +1,15 @@
 import type { CookieConfig, TokenPayload, VerifyConfig } from "./types.ts";
+export interface AuthCodeExchangeConfig {
+    authUrl: string;
+}
 export declare function getClientIP(request: Request): string;
 export declare function checkBearerToken(request: Request, expectedToken: string): boolean;
 export declare function getAuthUser(request: Request, verifyConfig: VerifyConfig, cookieConfig: CookieConfig): Promise<TokenPayload | null>;
-export declare function redirectToLogin(currentUrl: string): Response;
+export declare function redirectToLogin(currentUrl: string, responseType?: "code" | "token"): Response;
+/**
+ * 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 declare function handleCallback(request: Request, verifyConfig: VerifyConfig, cookieConfig: CookieConfig, exchangeConfig?: AuthCodeExchangeConfig): Promise<Response | null>;

package/dist/middleware.js

@@ -130,12 +130,64 @@ async function getAuthUser(request, verifyConfig, cookieConfig) {
     return null;
   return validateToken(verifyConfig, token);
 }
-function redirectToLogin(currentUrl) {
-  const loginUrl = `https://auth.uln.industries/login?redirect=${encodeURIComponent(currentUrl)}`;
-  return Response.redirect(loginUrl, 302);
+function redirectToLogin(currentUrl, responseType = "code") {
+  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, redirectOrigin, config) {
+  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();
+  return typeof data.token === "string" ? data.token : null;
+}
+async function handleCallback(request, verifyConfig, cookieConfig, exchangeConfig) {
+  const url = new URL(request.url);
+  const code = url.searchParams.get("code");
+  if (code) {
+    if (!exchangeConfig)
+      return redirectToLogin(url.origin);
+    const token2 = await exchangeCode(code, url.origin, exchangeConfig);
+    if (!token2)
+      return redirectToLogin(url.origin, "code");
+    const payload2 = await validateToken(verifyConfig, token2);
+    if (!payload2)
+      return redirectToLogin(url.origin, "code");
+    url.searchParams.delete("code");
+    return new Response(null, {
+      status: 302,
+      headers: {
+        Location: url.toString(),
+        "Set-Cookie": makeSessionCookie(cookieConfig, token2)
+      }
+    });
+  }
+  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)
+    }
+  });
 }
 export {
   redirectToLogin,
+  handleCallback,
   getClientIP,
   getAuthUser,
   checkBearerToken

package/dist/password.d.ts

@@ -1,2 +1,4 @@
+/** Hash a password with PBKDF2-SHA256 (100k iterations, 32-byte salt, 64-byte key). Returns `hex(salt):hex(key)`. */
 export declare function hashPassword(password: string): Promise<string>;
+/** Verify a password against a stored `hex(salt):hex(key)` hash. Uses constant-time comparison. */
 export declare function verifyPassword(password: string, storedHash: string): Promise<boolean>;

package/dist/service.d.ts

@@ -13,5 +13,13 @@ export declare function verifyToken(authService: Fetcher, token: string): Promis
 export declare function getAuthUser(request: Request, authService: Fetcher, cookieConfig: CookieConfig): Promise<TokenPayload | null>;
 /**
  * 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 declare function redirectToLogin(currentUrl: string): Response;
+export declare function redirectToLogin(currentUrl: string, responseType?: "code" | "token"): Response;
+/**
+ * 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 declare function handleCallback(request: Request, authService: Fetcher, cookieConfig: CookieConfig): Promise<Response | null>;

package/dist/service.js

@@ -54,14 +54,63 @@ async function getAuthUser(request, authService, cookieConfig) {
     return null;
   return verifyToken(authService, token);
 }
-function redirectToLogin(currentUrl) {
-  const loginUrl = `https://auth.uln.industries/login?redirect=${encodeURIComponent(currentUrl)}`;
-  return Response.redirect(loginUrl, 302);
+function redirectToLogin(currentUrl, responseType = "code") {
+  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, code, redirectOrigin) {
+  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();
+  return typeof data.token === "string" ? data.token : null;
+}
+async function handleCallback(request, authService, cookieConfig) {
+  const url = new URL(request.url);
+  const code = url.searchParams.get("code");
+  if (code) {
+    const token2 = await exchangeCode(authService, code, url.origin);
+    if (!token2)
+      return redirectToLogin(url.origin, "code");
+    const payload2 = await verifyToken(authService, token2);
+    if (!payload2)
+      return redirectToLogin(url.origin, "code");
+    url.searchParams.delete("code");
+    return new Response(null, {
+      status: 302,
+      headers: {
+        Location: url.toString(),
+        "Set-Cookie": makeSessionCookie(cookieConfig, token2)
+      }
+    });
+  }
+  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)
+    }
+  });
 }
 export {
   verifyToken,
   redirectToLogin,
   makeSessionCookie,
   makeClearCookie,
+  handleCallback,
   getAuthUser
 };

package/dist/token.d.ts

@@ -1,10 +1,13 @@
 import type { SigningConfig, TokenPayload, VerifyConfig } from "./types.ts";
+/** Generate an ECDSA P-256 key pair for token signing. Returns a short `kid` and both JWK exports. */
 export declare function generateKeyPair(): Promise<{
     kid: string;
     privateKeyJwk: JsonWebKey;
     publicKeyJwk: JsonWebKey;
 }>;
+/** Import an ECDSA P-256 private key from JWK for signing. */
 export declare function importPrivateKey(jwk: JsonWebKey): Promise<CryptoKey>;
+/** Import an ECDSA P-256 public key from JWK for verification. */
 export declare function importPublicKey(jwk: JsonWebKey): Promise<CryptoKey>;
 export interface CreateTokenInput {
     id: string;
@@ -14,5 +17,7 @@ export interface CreateTokenInput {
     scopes: string[];
     flags: Record<string, string[]>;
 }
+/** Create a signed token: `base64url(JSON payload).base64url(ECDSA-SHA256 signature)`. */
 export declare function createToken(config: SigningConfig, user: CreateTokenInput): Promise<string>;
+/** Validate a signed token. Returns the payload if valid and not expired, or null. Matches `kid` to find the correct public key. */
 export declare function validateToken(config: VerifyConfig, token: string): Promise<TokenPayload | null>;

package/dist/totp.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 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.
+ */
+export declare function base32Encode(data: Uint8Array): string;
+/** Generate a 20-byte random TOTP secret, returned as base32. */
+export declare function generateTotpSecret(): string;
+/** Build an otpauth:// URI for authenticator apps. */
+export declare function getTotpUri(secret: string, email: string, issuer: string): string;
+/** Six-digit code for the current 30-second step (deterministic counterpart to verifyTotpCode in tests). */
+export declare function currentTotpCode(secret: string, nowMs?: number): Promise<string>;
+/** Verify a TOTP code against the secret. Allows ±1 time step for clock drift. */
+export declare function verifyTotpCode(secret: string, code: string): Promise<boolean>;
+/** Generate a set of one-time backup codes for 2FA recovery. Returns plain-text codes. */
+export declare function generateBackupCodes(): string[];
+/** Hash a backup code for storage. Uses SHA-256 (no salt needed — codes are high-entropy). */
+export declare function hashBackupCode(code: string): Promise<string>;