@rebasepro/server-core 0.2.3 → 0.2.5

package/src/auth/jwt.ts

@@ -11,6 +11,8 @@ export interface AccessTokenPayload {
     userId: string;
     roles: string[];
     uid?: string;
+    /** Authentication Assurance Level: aal1 = password/oauth, aal2 = MFA verified */
+    aal?: "aal1" | "aal2";
 }
 
 let jwtConfig: JwtConfig = {
@@ -70,13 +72,22 @@ export function configureJwt(config: JwtConfig): void {
 /**
  * Generate an access token (short-lived, 1 hour by default)
  */
-export function generateAccessToken(userId: string, roles: string[]): string {
+export function generateAccessToken(
+    userId: string,
+    roles: string[],
+    aal: "aal1" | "aal2" = "aal1",
+    customClaims?: Record<string, unknown>
+): string {
     if (!jwtConfig.secret) {
         throw new Error("JWT secret not configured. Call configureJwt() first.");
     }
 
-    const payload: AccessTokenPayload = { userId,
-roles };
+    const payload: Record<string, unknown> = {
+        userId,
+        roles,
+        aal,
+        ...customClaims
+    };
 
     return jwt.sign(payload, jwtConfig.secret, {
         expiresIn: jwtConfig.accessExpiresIn as jwt.SignOptions["expiresIn"],
@@ -124,16 +135,19 @@ export function verifyAccessToken(token: string): AccessTokenPayload | null {
     }
 
     try {
-        const decoded = jwt.verify(token, jwtConfig.secret, { algorithms: ["HS256"] }) as { userId?: string; uid?: string; sub?: string; roles?: string[] };
+        const decoded = jwt.verify(token, jwtConfig.secret, { algorithms: ["HS256"] }) as { userId?: string; uid?: string; sub?: string; roles?: string[]; aal?: string };
         const id = decoded.userId || decoded.uid || decoded.sub;
         if (!id) {
             console.error("[JWT] Verification failed: missing id in payload", decoded);
             return null;
         }
 
+        const aal = (decoded.aal === "aal1" || decoded.aal === "aal2") ? decoded.aal : "aal1";
+
         return {
             userId: id,
-            roles: decoded.roles || []
+            roles: decoded.roles || [],
+            aal
         };
     } catch (error) {
         console.error("[JWT] Verification failed:", error, "Token start:", token.substring(0, 15));

package/src/auth/mfa.ts

@@ -0,0 +1,160 @@
+/**
+ * TOTP (Time-based One-Time Password) implementation.
+ *
+ * Pure Node.js crypto implementation — no external dependencies required.
+ * Implements RFC 6238 (TOTP) and RFC 4226 (HOTP).
+ */
+
+import { createHmac, randomBytes, createHash } from "crypto";
+
+// ─── Base32 Encoding/Decoding ────────────────────────────────────────────────
+
+const BASE32_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
+
+/**
+ * Encode a Buffer to Base32 string (RFC 4648)
+ */
+export function base32Encode(buffer: Buffer): string {
+    let bits = 0;
+    let value = 0;
+    let output = "";
+
+    for (let i = 0; i < buffer.length; i++) {
+        value = (value << 8) | buffer[i];
+        bits += 8;
+
+        while (bits >= 5) {
+            output += BASE32_ALPHABET[(value >>> (bits - 5)) & 31];
+            bits -= 5;
+        }
+    }
+
+    if (bits > 0) {
+        output += BASE32_ALPHABET[(value << (5 - bits)) & 31];
+    }
+
+    return output;
+}
+
+/**
+ * Decode a Base32 string to Buffer
+ */
+export function base32Decode(encoded: string): Buffer {
+    const cleanInput = encoded.replace(/=+$/, "").toUpperCase();
+    const bytes: number[] = [];
+    let bits = 0;
+    let value = 0;
+
+    for (let i = 0; i < cleanInput.length; i++) {
+        const index = BASE32_ALPHABET.indexOf(cleanInput[i]);
+        if (index === -1) continue;
+
+        value = (value << 5) | index;
+        bits += 5;
+
+        if (bits >= 8) {
+            bytes.push((value >>> (bits - 8)) & 255);
+            bits -= 8;
+        }
+    }
+
+    return Buffer.from(bytes);
+}
+
+// ─── HOTP/TOTP ───────────────────────────────────────────────────────────────
+
+/**
+ * Generate an HOTP value per RFC 4226
+ */
+function generateHotp(secret: Buffer, counter: bigint): string {
+    const hmac = createHmac("sha1", secret);
+    const counterBuffer = Buffer.alloc(8);
+    counterBuffer.writeBigInt64BE(counter);
+    hmac.update(counterBuffer);
+    const hash = hmac.digest();
+
+    const offset = hash[hash.length - 1] & 0x0f;
+    const code =
+        (((hash[offset] & 0x7f) << 24) |
+            (hash[offset + 1] << 16) |
+            (hash[offset + 2] << 8) |
+            hash[offset + 3]) %
+        1000000;
+
+    return code.toString().padStart(6, "0");
+}
+
+/**
+ * Generate a TOTP value for the current time step
+ */
+export function generateTotp(secret: Buffer, timeStep = 30): string {
+    const counter = BigInt(Math.floor(Date.now() / 1000 / timeStep));
+    return generateHotp(secret, counter);
+}
+
+/**
+ * Verify a TOTP token with a configurable time window
+ *
+ * @param secret - The shared secret as a Buffer
+ * @param token - The 6-digit TOTP code to verify
+ * @param window - Number of time steps to check on each side (default: 1)
+ * @returns true if the token is valid within the window
+ */
+export function verifyTotp(secret: Buffer, token: string, window = 1): boolean {
+    const timeStep = 30;
+    const counter = BigInt(Math.floor(Date.now() / 1000 / timeStep));
+    for (let i = -window; i <= window; i++) {
+        if (generateHotp(secret, counter + BigInt(i)) === token) {
+            return true;
+        }
+    }
+    return false;
+}
+
+// ─── Secret Generation ───────────────────────────────────────────────────────
+
+/**
+ * Generate a new TOTP secret and return the setup information
+ *
+ * @param issuer - The issuer name (app name) for the QR code
+ * @param accountName - The account identifier (usually email)
+ * @returns Object with base32 secret and otpauth URI
+ */
+export function generateTotpSecret(issuer: string, accountName: string): {
+    secret: string;
+    uri: string;
+} {
+    // Generate a 20-byte random secret (160 bits, recommended by RFC 4226)
+    const secretBuffer = randomBytes(20);
+    const secret = base32Encode(secretBuffer);
+
+    // Build otpauth:// URI for QR code generation
+    const encodedIssuer = encodeURIComponent(issuer);
+    const encodedAccount = encodeURIComponent(accountName);
+    const uri = `otpauth://totp/${encodedIssuer}:${encodedAccount}?secret=${secret}&issuer=${encodedIssuer}&algorithm=SHA1&digits=6&period=30`;
+
+    return { secret, uri };
+}
+
+// ─── Recovery Codes ──────────────────────────────────────────────────────────
+
+/**
+ * Generate a set of one-time recovery codes
+ *
+ * @param count - Number of recovery codes to generate (default: 10)
+ * @returns Array of formatted recovery code strings (e.g. "A1B2C-D3E4F")
+ */
+export function generateRecoveryCodes(count = 10): string[] {
+    return Array.from({ length: count }, () => {
+        const raw = randomBytes(5).toString("hex").toUpperCase();
+        const parts = raw.match(/.{1,5}/g);
+        return parts ? parts.join("-") : raw;
+    });
+}
+
+/**
+ * Hash a recovery code for storage
+ */
+export function hashRecoveryCode(code: string): string {
+    return createHash("sha256").update(code.replace(/-/g, "").toUpperCase()).digest("hex");
+}

package/src/auth/middleware.ts

@@ -4,6 +4,8 @@ import { verifyAccessToken, AccessTokenPayload } from "./jwt";
 import { HonoEnv } from "../api/types";
 import { scopeDataDriver } from "./rls-scope";
 import { safeCompare } from "./crypto-utils";
+import { isApiKeyToken, validateApiKey } from "./api-keys/api-key-middleware";
+import type { ApiKeyStore } from "./api-keys/api-key-store";
 
 /**
  * Result from a custom auth validator.
@@ -44,6 +46,12 @@ export interface AuthMiddlewareOptions {
      * timing attacks. The key must be at least 32 characters.
      */
     serviceKey?: string;
+    /**
+     * API key store for authenticating `rk_` prefixed tokens.
+     * When set, tokens starting with `rk_` are validated against the
+     * database instead of being treated as JWTs.
+     */
+    apiKeyStore?: ApiKeyStore;
 }
 
 /**
@@ -223,7 +231,7 @@ export function extractUserFromToken(token: string): AccessTokenPayload | null {
  */
 
 export function createAuthMiddleware(options: AuthMiddlewareOptions): MiddlewareHandler<HonoEnv> {
-    const { driver, requireAuth: enforceAuth = true, validator, serviceKey } = options;
+    const { driver, requireAuth: enforceAuth = true, validator, serviceKey, apiKeyStore } = options;
 
     return async (c, next) => {
         if (validator) {
@@ -291,6 +299,17 @@ code: "UNAUTHORIZED" } }, 401);
                         return c.json({ error: { message: "Internal authentication error",
 code: "INTERNAL_ERROR" } }, 500);
                     }
+                } else if (apiKeyStore && isApiKeyToken(token)) {
+                    // ── API Key verification ──────────────────────────────
+                    // Tokens starting with `rk_` are validated against the
+                    // api_keys table instead of JWT verification.
+                    const result = await validateApiKey(c, token, {
+                        store: apiKeyStore,
+                        driver,
+                    });
+                    if (result !== true) {
+                        return result;
+                    }
                 } else {
                     // ── JWT verification ───────────────────────────────────
                     const payload = extractUserFromToken(token);

package/src/auth/rate-limiter.ts

@@ -131,3 +131,95 @@ export const strictAuthLimiter = createRateLimiter({
     limit: 50,
     message: "Too many requests to this sensitive endpoint, please try again later."
 });
+
+/**
+ * Key generator for API-key-based rate limiting.
+ *
+ * Uses the API key ID (from `c.get("apiKey")`) as the rate limit key.
+ * Falls back to IP-based keying when the request is not authenticated
+ * via an API key.
+ */
+export function apiKeyKeyGenerator(c: Parameters<MiddlewareHandler<HonoEnv>>[0]): string {
+    const apiKey = c.get("apiKey") as { id: string } | undefined;
+    if (apiKey) {
+        return `api-key:${apiKey.id}`;
+    }
+    return defaultKeyGenerator(c);
+}
+
+/**
+ * Create a rate limiter specifically for API key requests.
+ *
+ * When a request is authenticated via an API key that has a `rate_limit`
+ * configured, this limiter enforces per-key limits using the key's ID
+ * as the rate limit bucket.
+ *
+ * @param defaultLimit - Fallback limit when the key has no `rate_limit` set.
+ * @param windowMs     - Time window in milliseconds (default: 15 minutes).
+ */
+export function createApiKeyRateLimiter(
+    defaultLimit = 1000,
+    windowMs = 15 * 60 * 1000,
+): MiddlewareHandler<HonoEnv> {
+    // We maintain a single shared store keyed by API key ID.
+    // The actual limit is resolved per-request from the key's metadata.
+    const store = new Map<string, { timestamps: number[] }>();
+
+    const cleanupInterval = setInterval(() => {
+        const now = Date.now();
+        for (const [key, entry] of store.entries()) {
+            entry.timestamps = entry.timestamps.filter(t => now - t < windowMs);
+            if (entry.timestamps.length === 0) {
+                store.delete(key);
+            }
+        }
+    }, windowMs);
+
+    if (cleanupInterval.unref) {
+        cleanupInterval.unref();
+    }
+
+    return async (c, next) => {
+        const apiKey = c.get("apiKey") as { id: string; rate_limit: number | null } | undefined;
+        if (!apiKey) {
+            // Not an API key request — skip this limiter
+            return next();
+        }
+
+        const limit = apiKey.rate_limit ?? defaultLimit;
+        const key = `api-key:${apiKey.id}`;
+        const now = Date.now();
+
+        let entry = store.get(key);
+        if (!entry) {
+            entry = { timestamps: [] };
+            store.set(key, entry);
+        }
+
+        entry.timestamps = entry.timestamps.filter(t => now - t < windowMs);
+
+        if (entry.timestamps.length >= limit) {
+            const retryAfterMs = entry.timestamps[0] + windowMs - now;
+            const retryAfterSec = Math.ceil(retryAfterMs / 1000);
+
+            c.header("Retry-After", String(retryAfterSec));
+            c.header("X-RateLimit-Limit", String(limit));
+            c.header("X-RateLimit-Remaining", "0");
+            c.header("X-RateLimit-Reset", String(Math.ceil((now + retryAfterMs) / 1000)));
+
+            return c.json({
+                error: {
+                    message: "API key rate limit exceeded, please try again later.",
+                    code: "RATE_LIMITED"
+                }
+            }, 429);
+        }
+
+        entry.timestamps.push(now);
+
+        c.header("X-RateLimit-Limit", String(limit));
+        c.header("X-RateLimit-Remaining", String(limit - entry.timestamps.length));
+
+        return next();
+    };
+}