@lastshotlabs/bunshot 0.0.1

package/src/cli.ts

@@ -0,0 +1,265 @@
+#!/usr/bin/env bun
+import { existsSync, mkdirSync, writeFileSync, readSync, rmSync } from "fs";
+import { join } from "path";
+import { spawnSync } from "child_process";
+
+function ask(question: string): string {
+  process.stdout.write(question);
+  const buf = Buffer.alloc(1024);
+  const n = readSync(0, buf, 0, buf.length, null);
+  return buf.subarray(0, n).toString().trim().replace(/\r/g, "");
+}
+
+// --- prompts (or argv) ---
+// Usage: bunshot "App Name" [dir-name]
+const argTitle = process.argv[2];
+const argDir   = process.argv[3];
+
+const appTitle = argTitle || ask("App name: ");
+if (!appTitle) {
+  console.error("App name is required.");
+  process.exit(1);
+}
+
+const dirDefault = appTitle.toLowerCase().replace(/\s+/g, "-").replace(/[^a-z0-9-]/g, "");
+const dirName    = argDir || (argTitle ? dirDefault : ask(`Directory (${dirDefault}): `)) || dirDefault;
+
+// --- paths ---
+const projectDir = join(process.cwd(), dirName);
+const srcDir     = join(projectDir, "src");
+const routesDir  = join(srcDir, "routes");
+const workersDir = join(srcDir, "workers");
+const queuesDir  = join(srcDir, "queues");
+const wsDir      = join(srcDir, "ws");
+const servicesDir = join(srcDir, "services");
+
+
+if (existsSync(projectDir)) {
+  console.error(`Directory "${dirName}" already exists.`);
+  process.exit(1);
+}
+
+// --- templates ---
+const indexContent = `import { createServer, type CreateServerConfig } from "@lastshotlabs/bunshot";
+
+const roles = {
+  admin: "admin",
+  user: "user",
+};
+
+const config: CreateServerConfig = {
+  routesDir: import.meta.dir + "/routes",
+  workersDir: import.meta.dir + "/workers",
+  app: {
+    name: "${appTitle}",
+    version: "1.0.0",
+  },
+  auth: {
+    roles: Object.values(roles),
+    defaultRole: roles.user,
+  },
+  security: {
+    cors: ["*"],
+  },
+  db: {
+    mongo: "single",
+  },
+  port: process.env.PORT ? parseInt(process.env.PORT) : 3000,
+};
+
+await createServer(config);
+`;
+
+const readmeContent = `# ${appTitle}
+
+Built with [@lastshotlabs/bunshot](https://github.com/Last-Shot-Labs/bunshot).
+
+## Getting started
+
+\`\`\`bash
+# fill in .env with your values
+bun dev
+\`\`\`
+
+| Endpoint | Description |
+|---|---|
+| \`POST /auth/register\` | Create account |
+| \`POST /auth/login\` | Sign in, returns JWT |
+| \`GET  /docs\` | OpenAPI docs (Scalar) |
+| \`GET  /health\` | Health check |
+
+## Project structure
+
+\`\`\`
+src/
+  index.ts        # server entry point
+  routes/         # file-based routing (each file = a router)
+  workers/        # BullMQ workers (auto-imported on start)
+\`\`\`
+
+## Adding routes
+
+Create a file in \`src/routes/\`:
+
+\`\`\`ts
+// src/routes/products.ts
+import { createRouter } from "@lastshotlabs/bunshot";
+import { z } from "zod";
+
+export const router = createRouter();
+
+router.get("/products", (c) => c.json({ products: [] }));
+\`\`\`
+
+## Adding models
+
+\`\`\`ts
+// src/models/Product.ts
+import { appConnection, mongoose } from "@lastshotlabs/bunshot";
+
+const ProductSchema = new mongoose.Schema({
+  name: { type: String, required: true },
+  price: { type: Number, required: true },
+}, { timestamps: true });
+
+export const Product = appConnection.model("Product", ProductSchema);
+\`\`\`
+
+## Environment variables
+
+See \`.env\` — fill in MongoDB, Redis, JWT, Bearer token, and OAuth provider values before running.
+`;
+
+const envContent = `NODE_ENV=development
+PORT=3000
+
+# MongoDB (single connection)
+MONGO_USER_DEV=
+MONGO_PW_DEV=
+MONGO_HOST_DEV=
+MONGO_DB_DEV=
+MONGO_USER_PROD=
+MONGO_PW_PROD=
+MONGO_HOST_PROD=
+MONGO_DB_PROD=
+
+# MongoDB auth connection (only needed if mongo: "separate")
+MONGO_AUTH_USER_DEV=
+MONGO_AUTH_PW_DEV=
+MONGO_AUTH_HOST_DEV=
+MONGO_AUTH_DB_DEV=
+MONGO_AUTH_USER_PROD=
+MONGO_AUTH_PW_PROD=
+MONGO_AUTH_HOST_PROD=
+MONGO_AUTH_DB_PROD=
+
+# Redis
+REDIS_HOST_DEV=
+REDIS_USER_DEV=
+REDIS_PW_DEV=
+REDIS_HOST_PROD=
+REDIS_USER_PROD=
+REDIS_PW_PROD=
+
+# JWT
+JWT_SECRET_DEV=
+JWT_SECRET_PROD=
+
+# Bearer API key
+BEARER_TOKEN_DEV=
+BEARER_TOKEN_PROD=
+
+# OAuth — Google (optional)
+GOOGLE_CLIENT_ID=
+GOOGLE_CLIENT_SECRET=
+GOOGLE_REDIRECT_URI=
+
+# OAuth — Apple (optional)
+APPLE_CLIENT_ID=
+APPLE_TEAM_ID=
+APPLE_KEY_ID=
+APPLE_PRIVATE_KEY=
+APPLE_REDIRECT_URI=
+`;
+
+// --- scaffold ---
+console.log(`\n@lastshotlabs/bunshot — creating ${dirName}\n`);
+
+mkdirSync(projectDir, { recursive: true });
+
+// bun init -y (handles package.json, tsconfig.json, .gitignore)
+console.log("  Running bun init...");
+spawnSync("bun", ["init", "-y"], { cwd: projectDir, stdio: "inherit" });
+
+// Remove the root index.ts bun init creates — we use src/index.ts
+const rootIndex = join(projectDir, "index.ts");
+if (existsSync(rootIndex)) rmSync(rootIndex);
+
+// Patch package.json: add dependency + fix scripts + module entry
+const pkgPath = join(projectDir, "package.json");
+const pkg = JSON.parse(require("fs").readFileSync(pkgPath, "utf-8"));
+pkg.module = "src/index.ts";
+pkg.scripts = { dev: "bun --watch src/index.ts", start: "bun src/index.ts" };
+pkg.dependencies = { ...pkg.dependencies, "@lastshotlabs/bunshot": "*" };
+writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n", "utf-8");
+
+// Patch tsconfig.json: add path aliases
+const tsconfigPath = join(projectDir, "tsconfig.json");
+const tsconfig = JSON.parse(require("fs").readFileSync(tsconfigPath, "utf-8"));
+tsconfig.compilerOptions = {
+  ...tsconfig.compilerOptions,
+  "paths": {
+    "@lib/*":        ["./src/lib/*"],
+    "@middleware/*": ["./src/middleware/*"],
+    "@models/*":     ["./src/models/*"],
+    "@queues/*":     ["./src/queues/*"],
+    "@routes/*":     ["./src/routes/*"],
+    "@scripts/*":    ["./src/scripts/*"],
+    "@services/*":   ["./src/services/*"],
+    "@workers/*":    ["./src/workers/*"],
+    "@queues":       ["./src/queues/index.ts"],
+    "@jobs":         ["./src/queues/jobs.ts"],
+    "@ws":           ["./src/ws/index.ts"],
+  },
+};
+writeFileSync(tsconfigPath, JSON.stringify(tsconfig, null, 2) + "\n", "utf-8");
+
+// Create src structure
+mkdirSync(routesDir, { recursive: true });
+mkdirSync(workersDir, { recursive: true });
+mkdirSync(queuesDir, { recursive: true });
+mkdirSync(wsDir, { recursive: true });
+mkdirSync(servicesDir, { recursive: true });
+writeFileSync(join(srcDir, "index.ts"), indexContent, "utf-8");
+writeFileSync(join(projectDir, ".env"), envContent, "utf-8");
+writeFileSync(join(projectDir, "README.md"), readmeContent, "utf-8");
+
+console.log("  Created:");
+console.log(`    + ${dirName}/src/index.ts`);
+console.log(`    + ${dirName}/src/routes/`);
+console.log(`    + ${dirName}/src/workers/`);
+console.log(`    + ${dirName}/src/queues/`);
+console.log(`    + ${dirName}/src/ws/`);
+console.log(`    + ${dirName}/src/services/`);
+console.log(`    + ${dirName}/.env`);
+console.log(`    + ${dirName}/README.md`);
+
+// --- git init ---
+console.log("\n  Initializing git...");
+const git = spawnSync("git", ["init"], { cwd: projectDir, stdio: "inherit" });
+if (git.status !== 0) {
+  console.error("  git init failed — skipping.");
+}
+
+// --- bun install ---
+console.log("\n  Installing dependencies...");
+const install = spawnSync("bun", ["install"], { cwd: projectDir, stdio: "inherit" });
+if (install.status !== 0) {
+  console.error("\n  bun install failed. Run it manually inside the directory.");
+  process.exit(1);
+}
+
+console.log(`\nDone! Next steps:\n`);
+console.log(`  cd ${dirName}`);
+console.log(`  # fill in .env`);
+console.log(`  bun dev\n`);

package/src/index.ts

@@ -0,0 +1,52 @@
+// App factory
+export { createApp } from "./app";
+export { createServer } from "./server";
+export type { CreateAppConfig, DbConfig, AppMeta, AuthConfig, AuthRateLimitConfig, OAuthConfig, SecurityConfig, BotProtectionConfig, PrimaryField, EmailVerificationConfig } from "./app";
+export type { CreateServerConfig, WsConfig } from "./server";
+
+// Lib utilities
+export { getAppRoles } from "@lib/appConfig";
+export { HttpError } from "@lib/HttpError";
+export { COOKIE_TOKEN, HEADER_USER_TOKEN } from "@lib/constants";
+export { createRouter } from "@lib/context";
+export type { AppEnv, AppVariables } from "@lib/context";
+export { signToken, verifyToken } from "@lib/jwt";
+export { log } from "@lib/logger";
+export { connectMongo, connectAuthMongo, connectAppMongo, authConnection, appConnection, mongoose } from "@lib/mongo";
+export { connectRedis, getRedis } from "@lib/redis";
+export { createQueue, createWorker } from "@lib/queue";
+export type { Job } from "@lib/queue";
+export { createSession, getSession, deleteSession, setSessionStore } from "@lib/session";
+export { createVerificationToken, getVerificationToken, deleteVerificationToken } from "@lib/emailVerification";
+export { bustAuthLimit, trackAttempt, isLimited } from "@lib/authRateLimit";
+export type { LimitOpts } from "@lib/authRateLimit";
+export { validate } from "@lib/validate";
+
+// Middleware
+export { bearerAuth } from "@middleware/bearerAuth";
+export { botProtection } from "@middleware/botProtection";
+export type { BotProtectionOptions } from "@middleware/botProtection";
+export { identify } from "@middleware/identify";
+export { rateLimit } from "@middleware/rateLimit";
+export type { RateLimitOptions } from "@middleware/rateLimit";
+export { userAuth } from "@middleware/userAuth";
+export { requireRole } from "@middleware/requireRole";
+export { requireVerifiedEmail } from "@middleware/requireVerifiedEmail";
+export { cacheResponse, bustCache, bustCachePattern, setCacheStore } from "@middleware/cacheResponse";
+
+// Lib utilities (bot protection)
+export { buildFingerprint } from "@lib/fingerprint";
+
+// Models
+export { AuthUser } from "@models/AuthUser";
+export { mongoAuthAdapter } from "./adapters/mongoAuth";
+export { sqliteAuthAdapter, setSqliteDb, startSqliteCleanup } from "./adapters/sqliteAuth";
+export { memoryAuthAdapter, clearMemoryStore } from "./adapters/memoryAuth";
+export { setUserRoles, addUserRole, removeUserRole } from "@lib/roles";
+export type { AuthAdapter, OAuthProfile } from "@lib/authAdapter";
+export type { OAuthProviderConfig } from "@lib/oauth";
+
+// WebSocket
+export { websocket, createWsUpgradeHandler } from "@ws/index";
+export type { SocketData } from "@ws/index";
+export { publish, subscribe, unsubscribe, getSubscriptions, handleRoomActions, getRooms, getRoomSubscribers } from "@lib/ws";

package/src/lib/HttpError.ts

@@ -0,0 +1,5 @@
+export class HttpError extends Error {
+  constructor(public status: number, message: string) {
+    super(message);
+  }
+}

package/src/lib/appConfig.ts

@@ -0,0 +1,29 @@
+export type PrimaryField = "email" | "username" | "phone";
+
+export interface EmailVerificationConfig {
+  /** Block login until email is verified. Defaults to false (soft gate — emailVerified returned in login response). */
+  required?: boolean;
+  /** Called after registration with the identifier and verification token. Use to send the email. */
+  onSend: (email: string, token: string) => Promise<void>;
+}
+
+let appName = "Core API";
+let appRoles: string[] = [];
+let defaultRole: string | null = null;
+let _primaryField: PrimaryField = "email";
+let _emailVerificationConfig: EmailVerificationConfig | null = null;
+
+export const setAppName = (name: string) => { appName = name; };
+export const getAppName = () => appName;
+
+export const setAppRoles = (roles: string[]) => { appRoles = roles; };
+export const getAppRoles = () => appRoles;
+
+export const setDefaultRole = (role: string | null) => { defaultRole = role; };
+export const getDefaultRole = () => defaultRole;
+
+export const setPrimaryField = (field: PrimaryField) => { _primaryField = field; };
+export const getPrimaryField = () => _primaryField;
+
+export const setEmailVerificationConfig = (config: EmailVerificationConfig | null) => { _emailVerificationConfig = config; };
+export const getEmailVerificationConfig = () => _emailVerificationConfig;

package/src/lib/authAdapter.ts

@@ -0,0 +1,46 @@
+export interface OAuthProfile {
+  email?: string;
+  name?: string;
+  avatarUrl?: string;
+}
+
+export interface AuthAdapter {
+  findByEmail(email: string): Promise<{ id: string; passwordHash: string } | null>;
+  create(email: string, passwordHash: string): Promise<{ id: string }>;
+  /** Required when using OAuth providers. Find or create a user by provider + provider user ID. */
+  findOrCreateByProvider?(provider: string, providerId: string, profile: OAuthProfile): Promise<{ id: string; created: boolean }>;
+  /** Optional. Set or update the password hash for a user (used by /auth/set-password). */
+  setPassword?(userId: string, passwordHash: string): Promise<void>;
+  /** Optional. Link a provider identity to an existing user (used by /auth/:provider/link). */
+  linkProvider?(userId: string, provider: string, providerId: string): Promise<void>;
+  /** Optional. Return the roles assigned to a user (used by requireRole middleware). */
+  getRoles?(userId: string): Promise<string[]>;
+  /** Optional. Set the roles for a user, replacing any existing roles. */
+  setRoles?(userId: string, roles: string[]): Promise<void>;
+  /** Optional. Add a single role to a user without affecting their other roles. */
+  addRole?(userId: string, role: string): Promise<void>;
+  /** Optional. Remove a single role from a user without affecting their other roles. */
+  removeRole?(userId: string, role: string): Promise<void>;
+  /** Optional. Return basic profile info for a user by ID (used by GET /auth/me). */
+  getUser?(userId: string): Promise<{ email?: string; providerIds?: string[]; emailVerified?: boolean } | null>;
+  /** Optional. Unlink a provider identity from a user (used by DELETE /auth/:provider/link). */
+  unlinkProvider?(userId: string, provider: string): Promise<void>;
+  /**
+   * Optional. Look up a user by their primary identifier (email, username, or phone depending on config).
+   * When provided, used instead of findByEmail for credential login/register flows.
+   */
+  findByIdentifier?(value: string): Promise<{ id: string; passwordHash: string } | null>;
+  /** Optional. Mark a user's email address as verified (used by POST /auth/verify-email). */
+  setEmailVerified?(userId: string, verified: boolean): Promise<void>;
+  /** Optional. Return whether a user's email address has been verified. */
+  getEmailVerified?(userId: string): Promise<boolean>;
+}
+
+let _adapter: AuthAdapter | null = null;
+
+export const setAuthAdapter = (adapter: AuthAdapter) => { _adapter = adapter; };
+
+export const getAuthAdapter = (): AuthAdapter => {
+  if (!_adapter) throw new Error("No auth adapter set — pass authAdapter to createApp/createServer, or call setAuthAdapter()");
+  return _adapter;
+};

package/src/lib/authRateLimit.ts

@@ -0,0 +1,104 @@
+import { getAppName } from "@lib/appConfig";
+
+interface AuthRateLimitEntry {
+  count: number;
+  resetAt: number; // epoch ms
+}
+
+interface AuthRateLimitStore {
+  get(key: string): Promise<AuthRateLimitEntry | null>;
+  set(key: string, entry: AuthRateLimitEntry, ttlMs: number): Promise<void>;
+  delete(key: string): Promise<void>;
+}
+
+// ---------------------------------------------------------------------------
+// Memory implementation
+// ---------------------------------------------------------------------------
+
+const _memoryStore = new Map<string, AuthRateLimitEntry>();
+
+const memoryStore: AuthRateLimitStore = {
+  async get(key) {
+    const entry = _memoryStore.get(key);
+    if (!entry) return null;
+    if (entry.resetAt <= Date.now()) {
+      _memoryStore.delete(key);
+      return null;
+    }
+    return entry;
+  },
+  async set(key, entry) {
+    _memoryStore.set(key, entry);
+  },
+  async delete(key) {
+    _memoryStore.delete(key);
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Redis implementation
+// ---------------------------------------------------------------------------
+
+const redisStore: AuthRateLimitStore = {
+  async get(key) {
+    const { getRedis } = await import("@lib/redis");
+    const raw = await getRedis().get(`rl:${getAppName()}:${key}`);
+    if (!raw) return null;
+    const entry: AuthRateLimitEntry = JSON.parse(raw);
+    if (entry.resetAt <= Date.now()) return null;
+    return entry;
+  },
+  async set(key, entry, ttlMs) {
+    const { getRedis } = await import("@lib/redis");
+    await getRedis().set(`rl:${getAppName()}:${key}`, JSON.stringify(entry), "PX", ttlMs);
+  },
+  async delete(key) {
+    const { getRedis } = await import("@lib/redis");
+    await getRedis().del(`rl:${getAppName()}:${key}`);
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Active store + setter
+// ---------------------------------------------------------------------------
+
+let _store: AuthRateLimitStore = memoryStore;
+
+export const setAuthRateLimitStore = (store: "memory" | "redis"): void => {
+  _store = store === "redis" ? redisStore : memoryStore;
+};
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export interface LimitOpts {
+  windowMs: number;
+  max: number;
+}
+
+/** Returns true if the key is currently over the limit (read-only, no increment). */
+export const isLimited = async (key: string, opts: LimitOpts): Promise<boolean> => {
+  const entry = await _store.get(key);
+  if (!entry) return false;
+  return entry.count >= opts.max;
+};
+
+/** Increments the counter and returns true if now over the limit. */
+export const trackAttempt = async (key: string, opts: LimitOpts): Promise<boolean> => {
+  const now = Date.now();
+  const existing = await _store.get(key);
+  if (!existing) {
+    await _store.set(key, { count: 1, resetAt: now + opts.windowMs }, opts.windowMs);
+    return 1 >= opts.max;
+  }
+  const updated: AuthRateLimitEntry = { count: existing.count + 1, resetAt: existing.resetAt };
+  const remaining = Math.max(1, existing.resetAt - now);
+  await _store.set(key, updated, remaining);
+  return updated.count >= opts.max;
+};
+
+/** Resets a rate limit key. Use on login success or for admin unlock. */
+export const bustAuthLimit = async (key: string): Promise<void> => {
+  await _store.delete(key);
+};

package/src/lib/constants.ts

@@ -0,0 +1,2 @@
+export const COOKIE_TOKEN = "token";
+export const HEADER_USER_TOKEN = "x-user-token";

package/src/lib/context.ts

@@ -0,0 +1,17 @@
+import { OpenAPIHono, type Hook } from "@hono/zod-openapi";
+
+export type AppVariables = {
+  authUserId: string | null;
+  roles: string[] | null;
+};
+
+export type AppEnv = { Variables: AppVariables };
+
+const defaultHook: Hook<any, AppEnv, any, any> = (result, c) => {
+  if (!result.success) {
+    const message = result.error.issues.map((i: { message: string }) => i.message).join(", ");
+    return c.json({ error: message }, 400);
+  }
+};
+
+export const createRouter = () => new OpenAPIHono<AppEnv>({ defaultHook });

package/src/lib/emailVerification.ts

@@ -0,0 +1,105 @@
+import { getRedis } from "./redis";
+import { appConnection } from "./mongo";
+import { getAppName } from "./appConfig";
+import { Schema } from "mongoose";
+import {
+  sqliteCreateVerificationToken,
+  sqliteGetVerificationToken,
+  sqliteDeleteVerificationToken,
+} from "../adapters/sqliteAuth";
+import {
+  memoryCreateVerificationToken,
+  memoryGetVerificationToken,
+  memoryDeleteVerificationToken,
+} from "../adapters/memoryAuth";
+
+// ---------------------------------------------------------------------------
+// Mongo model
+// ---------------------------------------------------------------------------
+
+interface VerificationDoc {
+  token: string;
+  userId: string;
+  email: string;
+  expiresAt: Date;
+}
+
+const verificationSchema = new Schema<VerificationDoc>(
+  {
+    token:     { type: String, required: true, unique: true },
+    userId:    { type: String, required: true },
+    email:     { type: String, required: true },
+    expiresAt: { type: Date,   required: true, index: { expireAfterSeconds: 0 } },
+  },
+  { collection: "email_verifications" }
+);
+
+function getVerificationModel() {
+  return appConnection.models["EmailVerification"] ??
+    appConnection.model<VerificationDoc>("EmailVerification", verificationSchema);
+}
+
+// ---------------------------------------------------------------------------
+// Store configuration
+// ---------------------------------------------------------------------------
+
+type VerificationStore = "redis" | "mongo" | "sqlite" | "memory";
+let _store: VerificationStore = "redis";
+export const setEmailVerificationStore = (store: VerificationStore) => { _store = store; };
+
+// ---------------------------------------------------------------------------
+// TTL
+// ---------------------------------------------------------------------------
+
+const TTL_SECONDS = 60 * 60 * 24; // 24 hours
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export const createVerificationToken = async (userId: string, email: string): Promise<string> => {
+  const token = crypto.randomUUID();
+  if (_store === "memory") { memoryCreateVerificationToken(token, userId, email); return token; }
+  if (_store === "sqlite") { sqliteCreateVerificationToken(token, userId, email); return token; }
+  if (_store === "mongo") {
+    await getVerificationModel().create({
+      token,
+      userId,
+      email,
+      expiresAt: new Date(Date.now() + TTL_SECONDS * 1000),
+    });
+    return token;
+  }
+  await getRedis().set(
+    `verify:${getAppName()}:${token}`,
+    JSON.stringify({ userId, email }),
+    "EX",
+    TTL_SECONDS
+  );
+  return token;
+};
+
+export const getVerificationToken = async (token: string): Promise<{ userId: string; email: string } | null> => {
+  if (_store === "memory") return memoryGetVerificationToken(token);
+  if (_store === "sqlite") return sqliteGetVerificationToken(token);
+  if (_store === "mongo") {
+    const doc = await getVerificationModel()
+      .findOne({ token, expiresAt: { $gt: new Date() } })
+      .lean();
+    if (!doc) return null;
+    return { userId: doc.userId, email: doc.email };
+  }
+  const raw = await getRedis().get(`verify:${getAppName()}:${token}`);
+  if (!raw) return null;
+  return JSON.parse(raw) as { userId: string; email: string };
+};
+
+export const deleteVerificationToken = async (token: string): Promise<void> => {
+  if (_store === "memory") { memoryDeleteVerificationToken(token); return; }
+  if (_store === "sqlite") { sqliteDeleteVerificationToken(token); return; }
+  if (_store === "mongo") {
+    await getVerificationModel().deleteOne({ token });
+    return;
+  }
+  await getRedis().del(`verify:${getAppName()}:${token}`);
+};

package/src/lib/fingerprint.ts

@@ -0,0 +1,43 @@
+const BROWSER_HEADERS = [
+  "sec-fetch-site",
+  "sec-fetch-mode",
+  "sec-fetch-dest",
+  "sec-ch-ua",
+  "sec-ch-ua-mobile",
+  "sec-ch-ua-platform",
+  "origin",
+  "referer",
+  "x-requested-with",
+] as const;
+
+const encoder = new TextEncoder();
+
+/**
+ * Builds a 12-hex-char fingerprint from stable HTTP headers.
+ * IP-independent: bots that rotate IPs but use the same HTTP client
+ * will produce the same fingerprint and share a rate-limit bucket.
+ */
+export async function buildFingerprint(req: Request): Promise<string> {
+  const h = (name: string) => req.headers.get(name) ?? "";
+
+  // Encode which browser-only headers are present as a bitmask string.
+  // Real browsers send most of these; raw HTTP clients send none.
+  const bitmap = BROWSER_HEADERS.map((name) =>
+    req.headers.has(name) ? "1" : "0"
+  ).join("");
+
+  const raw = [
+    h("user-agent"),
+    h("accept"),
+    h("accept-language"),
+    h("accept-encoding"),
+    h("connection"),
+    bitmap,
+  ].join("|");
+
+  const buf = await crypto.subtle.digest("SHA-256", encoder.encode(raw));
+  const bytes = new Uint8Array(buf).slice(0, 6);
+  return Array.from(bytes)
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("");
+}