devlyn-cli 0.2.1 → 0.4.0

package/optional-skills/better-auth-setup/references/api-keys.md

@@ -0,0 +1,236 @@
+# API Key System Reference
+
+Complete implementation for a custom API key system alongside Better Auth session cookies.
+
+## Why Custom API Keys Instead of Better Auth's Plugin
+
+Better Auth has an API key plugin, but building your own gives you:
+- Full control over key format and prefix (e.g., `pyx_` for easy identification)
+- Project-scoped keys (Better Auth's plugin scopes to users)
+- Soft-delete with revocation timestamps (audit trail)
+- Fire-and-forget usage tracking (`lastUsedAt`)
+- Custom expiration logic
+
+If your needs are simpler (user-scoped keys, no project hierarchy), Better Auth's built-in plugin works fine.
+
+## Key Generation Utilities
+
+```typescript
+// src/lib/api-keys.ts
+
+// Prefix makes keys instantly recognizable and enables fast auth middleware routing.
+// Choose something unique to your product (e.g., "sk_", "pk_", "myapp_").
+export const API_KEY_PREFIX = "pyx_";
+
+// Base62: alphanumeric only, no special chars.
+// Safe in URLs, headers, and JSON without encoding.
+const BASE62_CHARS = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
+
+export function base62Encode(bytes: Uint8Array): string {
+  let result = "";
+  for (const byte of bytes) {
+    result += BASE62_CHARS[byte % 62];
+  }
+  return result;
+}
+
+// SHA-256 hash for storage.
+// Web Crypto API is available in Bun, Deno, Cloudflare Workers, and browsers.
+const encoder = new TextEncoder();
+
+export async function hashKey(rawKey: string): Promise<string> {
+  const data = encoder.encode(rawKey);
+  const hashBuffer = await crypto.subtle.digest("SHA-256", data);
+  return Buffer.from(hashBuffer).toString("hex");
+}
+```
+
+## API Key Routes
+
+Three endpoints: create, list, and revoke.
+
+```typescript
+// src/routes/api-keys.ts
+import { and, count, eq } from "drizzle-orm";
+import { Hono } from "hono";
+import { z } from "zod";
+import { db } from "../db";
+import { apiKeys, projects } from "../db/schema";
+import { API_KEY_PREFIX, base62Encode, hashKey } from "../lib/api-keys";
+import { ForbiddenError, NotFoundError } from "../lib/errors";
+import type { AppEnv } from "../types";
+
+const apiKeyRoutes = new Hono<AppEnv>();
+
+// How many chars of the key to show in listings (e.g., "pyx_AbCdEfGh...")
+const API_KEY_PREFIX_LENGTH = 12;
+
+const createKeySchema = z.object({
+  name: z.string().min(1).max(255),
+  projectId: z.string().uuid(),
+  expiresAt: z
+    .string()
+    .datetime()
+    .refine((date) => new Date(date) > new Date(), "Expiration date must be in the future")
+    .nullable()
+    .optional(),
+});
+
+// ─── CREATE ──────────────────────────────────────────────
+// POST /v1/api-keys
+// Returns the plaintext key ONLY in this response.
+apiKeyRoutes.post("/", async (c) => {
+  const tenant = c.get("tenant");
+  const body = await c.req.json();
+  const { name, projectId, expiresAt } = createKeySchema.parse(body);
+
+  // Verify project belongs to the tenant's organization.
+  // This prevents a user in Org A from creating a key for a project in Org B.
+  const project = await db
+    .select({ id: projects.id, organizationId: projects.organizationId })
+    .from(projects)
+    .where(eq(projects.id, projectId))
+    .limit(1);
+
+  if (project.length === 0) {
+    throw new NotFoundError("Project not found");
+  }
+
+  if (project[0].organizationId !== tenant.organizationId) {
+    throw new ForbiddenError();
+  }
+
+  // Generate cryptographically secure key
+  const randomBytes = crypto.getRandomValues(new Uint8Array(32));
+  const rawKey = API_KEY_PREFIX + base62Encode(randomBytes);
+
+  // Hash for storage — plaintext NEVER persisted
+  const keyHash = await hashKey(rawKey);
+  const keyPrefix = rawKey.slice(0, API_KEY_PREFIX_LENGTH);
+
+  const [inserted] = await db
+    .insert(apiKeys)
+    .values({
+      projectId,
+      name,
+      keyHash,
+      keyPrefix,
+      expiresAt: expiresAt ? new Date(expiresAt) : null,
+    })
+    .returning({
+      id: apiKeys.id,
+      createdAt: apiKeys.createdAt,
+    });
+
+  return c.json(
+    {
+      id: inserted.id,
+      key: rawKey, // Plaintext — shown once, never again
+      name,
+      projectId,
+      keyPrefix,
+      createdAt: inserted.createdAt,
+      expiresAt: expiresAt ?? null,
+    },
+    201,
+  );
+});
+
+// ─── LIST ────────────────────────────────────────────────
+// GET /v1/api-keys?projectId=...&limit=20&offset=0
+// Keys are masked — only prefix shown.
+apiKeyRoutes.get("/", async (c) => {
+  const tenant = c.get("tenant");
+  const projectId = c.req.query("projectId");
+  const limit = Math.min(Number(c.req.query("limit") || 20), 100);
+  const offset = Math.max(Number(c.req.query("offset") || 0), 0);
+
+  const conditions = [eq(projects.organizationId, tenant.organizationId)];
+  if (projectId) {
+    conditions.push(eq(apiKeys.projectId, projectId));
+  }
+
+  const whereClause = and(...conditions);
+
+  const [items, [{ total }]] = await Promise.all([
+    db
+      .select({
+        id: apiKeys.id,
+        name: apiKeys.name,
+        keyPrefix: apiKeys.keyPrefix,
+        projectId: apiKeys.projectId,
+        lastUsedAt: apiKeys.lastUsedAt,
+        expiresAt: apiKeys.expiresAt,
+        revokedAt: apiKeys.revokedAt,
+        createdAt: apiKeys.createdAt,
+      })
+      .from(apiKeys)
+      .innerJoin(projects, eq(apiKeys.projectId, projects.id))
+      .where(whereClause)
+      .limit(limit)
+      .offset(offset),
+    db
+      .select({ total: count() })
+      .from(apiKeys)
+      .innerJoin(projects, eq(apiKeys.projectId, projects.id))
+      .where(whereClause),
+  ]);
+
+  return c.json({
+    keys: items.map((k) => ({
+      id: k.id,
+      name: k.name,
+      hint: `${k.keyPrefix}...`,
+      projectId: k.projectId,
+      createdAt: k.createdAt,
+      expiresAt: k.expiresAt,
+      lastUsedAt: k.lastUsedAt,
+      revoked: k.revokedAt !== null,
+    })),
+    total,
+    hasMore: offset + items.length < total,
+  });
+});
+
+// ─── REVOKE ──────────────────────────────────────────────
+// DELETE /v1/api-keys/:id
+// Soft delete via revokedAt timestamp.
+apiKeyRoutes.delete("/:id", async (c) => {
+  const tenant = c.get("tenant");
+  const keyId = c.req.param("id");
+
+  // Verify key exists AND belongs to tenant's org (single query).
+  // This prevents ID enumeration — an attacker can't tell whether
+  // a key exists in another org or doesn't exist at all.
+  const key = await db
+    .select({ id: apiKeys.id })
+    .from(apiKeys)
+    .innerJoin(projects, eq(apiKeys.projectId, projects.id))
+    .where(and(eq(apiKeys.id, keyId), eq(projects.organizationId, tenant.organizationId)))
+    .limit(1);
+
+  if (key.length === 0) {
+    throw new NotFoundError("API key not found");
+  }
+
+  await db.update(apiKeys).set({ revokedAt: new Date() }).where(eq(apiKeys.id, keyId));
+
+  return c.body(null, 204);
+});
+
+export { apiKeyRoutes };
+```
+
+## Security Considerations
+
+1. **Hash-only storage** — The plaintext key is never written to the database. If the DB is compromised, the hashes are useless without the original keys.
+
+2. **Generic errors** — Auth failures for non-existent, revoked, and expired keys all return the same 401 error. This prevents an attacker from distinguishing between these states.
+
+3. **Tenant isolation on revoke** — The DELETE query joins through projects to verify org ownership. Without this, a user could revoke keys in other organizations by guessing UUIDs.
+
+4. **No plaintext in logs** — The key is returned in the HTTP response body but never logged. The `keyPrefix` (first 12 chars) is safe to log and display.
+
+5. **Base62 encoding** — Produces URL-safe keys without special characters. No need for URL encoding in headers or query params.
+
+6. **32 bytes of randomness** — Produces ~190 bits of entropy. Brute-forcing is computationally infeasible.

package/optional-skills/better-auth-setup/references/config-and-entry.md

@@ -0,0 +1,239 @@
+# Config, Error Types, and Entry Point Reference
+
+Environment configuration, error hierarchy, and Hono entry point wiring for Better Auth.
+
+## Table of Contents
+1. [Environment Config](#environment-config)
+2. [Error Types](#error-types)
+3. [Error Handler Middleware](#error-handler-middleware)
+4. [Entry Point](#entry-point)
+5. [Middleware Order](#middleware-order)
+
+## Environment Config
+
+Validate all auth-related environment variables at startup using Zod. Fail fast on missing or invalid values — never let the app start with bad config.
+
+```typescript
+// src/config.ts
+import { z } from "zod";
+
+// Treat empty strings as undefined so optional fields work with .env files
+const optionalString = z.preprocess(
+  (val) => (val === "" ? undefined : val),
+  z.string().optional()
+);
+
+const configSchema = z.object({
+  // Auth (required)
+  BETTER_AUTH_SECRET: z.string().min(32, "Auth secret must be at least 32 characters"),
+  BETTER_AUTH_URL: z.string().url().default("http://localhost:3000"),
+
+  // OAuth (optional — enables Google login when both present)
+  GOOGLE_CLIENT_ID: optionalString,
+  GOOGLE_CLIENT_SECRET: optionalString,
+
+  // Email
+  RESEND_API_KEY: optionalString,
+  EMAIL_FROM: z.string().default("noreply@example.com"),
+
+  // CORS
+  CORS_ORIGIN: z.string().default("*"),
+  TRUSTED_ORIGINS: optionalString,
+
+  // Database
+  DATABASE_URL: z.string().url(),
+
+  // Node env
+  NODE_ENV: z.enum(["development", "test", "production"]).default("development"),
+});
+
+export type Config = z.infer<typeof configSchema>;
+export const config = configSchema.parse(process.env);
+
+// Reject dev-like secrets in production
+if (config.NODE_ENV === "production") {
+  const devSecrets = ["super-secret-dev-key", "development-secret", "change-me"];
+  if (devSecrets.some((s) => config.BETTER_AUTH_SECRET.includes(s))) {
+    console.error("FATAL: Development auth secret detected in production");
+    process.exit(1);
+  }
+}
+```
+
+**Why this matters:** A missing `BETTER_AUTH_SECRET` causes silent auth failures. A too-short secret weakens token signing. Catching these at startup prevents debugging phantom 401s in production.
+
+## Error Types
+
+A consistent error hierarchy where every auth/tenant error has a distinct code. This lets the frontend differentiate between "wrong password", "no organization", and "rate limited."
+
+```typescript
+// src/lib/errors.ts
+export class AppError extends Error {
+  constructor(
+    public code: string,
+    message: string,
+    public statusCode: number = 500,
+    public details?: Record<string, unknown>
+  ) {
+    super(message);
+  }
+}
+
+export class AuthError extends AppError {
+  constructor(message = "Authentication required") {
+    super("auth_required", message, 401);
+  }
+}
+
+export class ForbiddenError extends AppError {
+  constructor(message = "Insufficient permissions") {
+    super("forbidden", message, 403);
+  }
+}
+
+export class NotFoundError extends AppError {
+  constructor(message = "Resource not found") {
+    super("not_found", message, 404);
+  }
+}
+
+export class ValidationError extends AppError {
+  constructor(message: string, details?: Record<string, unknown>) {
+    super("validation_error", message, 422, details);
+  }
+}
+
+export class RateLimitError extends AppError {
+  constructor(retryAfter: number) {
+    super("rate_limited", "Too many requests", 429, { retryAfter });
+  }
+}
+```
+
+**Response envelope** (consistent across all endpoints):
+```json
+{
+  "error": {
+    "code": "auth_required",
+    "message": "Authentication required"
+  },
+  "requestId": "uuid"
+}
+```
+
+## Error Handler Middleware
+
+Catches all errors and returns the consistent envelope. Masks unhandled errors in production.
+
+```typescript
+// src/middleware/error-handler.ts
+import type { ErrorHandler } from "hono";
+import { AppError } from "../lib/errors";
+import { config } from "../config";
+
+export const errorHandler: ErrorHandler = (err, c) => {
+  const requestId = c.get("requestId") ?? "unknown";
+
+  if (err instanceof AppError) {
+    return c.json({
+      error: {
+        code: err.code,
+        message: err.message,
+        ...(err.details && { details: err.details }),
+      },
+      requestId,
+    }, err.statusCode as any);
+  }
+
+  // Unhandled error — mask in production to prevent information leakage
+  const message = config.NODE_ENV === "production"
+    ? "Internal server error"
+    : err.message;
+
+  console.error("Unhandled error:", err);
+
+  return c.json({
+    error: { code: "internal_error", message },
+    requestId,
+  }, 500);
+};
+```
+
+## Entry Point
+
+The order middleware is registered determines whether auth works. Get this wrong and you get silent CORS failures or missing request IDs in error responses.
+
+```typescript
+// src/index.ts
+import { Hono } from "hono";
+import { cors } from "hono/cors";
+import { config } from "./config";
+import { authRoutes } from "./routes/auth";
+import { authMiddleware } from "./middleware/auth";
+import { tenantContextMiddleware } from "./middleware/tenant-context";
+import { errorHandler } from "./middleware/error-handler";
+
+const app = new Hono();
+
+// === GLOBAL MIDDLEWARE (order is critical) ===
+
+// 1. Request ID — must be first so error handler can include it
+app.use("*", async (c, next) => {
+  c.set("requestId", crypto.randomUUID());
+  await next();
+});
+
+// 2. Security headers
+app.use("*", async (c, next) => {
+  if (config.NODE_ENV === "production") {
+    c.header("Strict-Transport-Security", "max-age=31536000; includeSubDomains");
+  }
+  c.header("X-Frame-Options", "DENY");
+  await next();
+});
+
+// 3. CORS — comes before auth routes because if CORS is registered after,
+//    preflight OPTIONS requests fail and cross-origin auth breaks completely.
+const origins = config.CORS_ORIGIN.split(",").map((o) => o.trim()).filter(Boolean);
+app.use("*", cors({
+  origin: origins.length === 1 && origins[0] === "*" ? "*" : origins,
+  allowMethods: ["GET", "POST", "PUT", "DELETE", "PATCH", "OPTIONS"],
+  allowHeaders: ["Content-Type", "Authorization"],
+  exposeHeaders: ["X-RateLimit-Limit", "X-RateLimit-Remaining", "X-RateLimit-Reset", "Retry-After"],
+  credentials: origins[0] !== "*", // credentials: true only with specific origins
+}));
+
+// 4. Request logging (add pino or your preferred logger here)
+// 5. Error handler (catches AppError and returns envelope)
+app.onError(errorHandler);
+
+// === PUBLIC ROUTES ===
+app.route("/auth", authRoutes);
+
+// === PROTECTED ROUTES ===
+// Auth → Tenant Context → Rate Limit → Route handlers
+const protectedRoutes = new Hono();
+protectedRoutes.use("*", authMiddleware);
+protectedRoutes.use("*", tenantContextMiddleware);
+// protectedRoutes.use("*", rateLimitMiddleware); // Add when ready
+app.route("/v1", protectedRoutes);
+
+// Mount your protected route handlers on protectedRoutes:
+// protectedRoutes.route("/projects", projectRoutes);
+// protectedRoutes.route("/api-keys", apiKeyRoutes);
+
+export default app;
+```
+
+## Middleware Order
+
+| Order | Middleware | Why This Position |
+|-------|-----------|-------------------|
+| 1 | Request ID | Error handler needs it for the response envelope |
+| 2 | Security Headers | Applied to all responses including errors |
+| 3 | CORS | Handles OPTIONS preflight before auth rejects them |
+| 4 | Logging | Tracks all requests including auth failures |
+| 5 | Error Handler | Catch-all for consistent error envelope |
+| 6 | Auth (protected only) | Validates credentials |
+| 7 | Tenant Context (protected only) | Resolves org from auth |
+| 8 | Rate Limit (protected only) | Plan-aware throttling |