devlyn-cli 0.2.1 → 0.4.0

package/optional-skills/better-auth-setup/references/middleware.md

@@ -0,0 +1,409 @@
+# Auth & Tenant Context Middleware Reference
+
+Complete implementations for the dual-path auth middleware and tenant context middleware.
+
+## Table of Contents
+1. [Types](#types)
+2. [Auth Middleware](#auth-middleware)
+3. [Tenant Context Middleware](#tenant-context-middleware)
+4. [API Key Utilities](#api-key-utilities)
+5. [Error Types](#error-types)
+
+## Types
+
+Define these types in a shared `types.ts` file. They're used across middleware, routes, and tests.
+
+```typescript
+// src/types.ts
+
+// API key auth — resolved from Authorization: Bearer pyx_...
+export type ApiKeyAuthContext = {
+  type: "api_key";
+  apiKeyId: string;
+  projectId: string;
+  organizationId: string;
+};
+
+// Session auth — resolved from Better Auth session cookie
+export type SessionAuthContext = {
+  type: "session";
+  userId: string;
+  sessionId: string;
+};
+
+// Union type — the auth middleware sets one of these
+export type AuthContext = ApiKeyAuthContext | SessionAuthContext;
+
+// Tenant context — resolved after auth
+export type TenantContext = {
+  organizationId: string;
+  projectId: string | null;  // null for session auth (no project scope)
+  userId: string | null;     // null for API key auth (no user scope)
+  plan: string;              // e.g., "free", "pro", "team", "enterprise"
+};
+
+// Hono app environment — tells Hono what variables are available
+export type AppEnv = {
+  Variables: {
+    requestId: string;
+    auth: AuthContext;
+    tenant: TenantContext;
+  };
+};
+```
+
+## Auth Middleware
+
+The auth middleware supports two authentication paths in a single middleware function. This avoids route-level conditional logic and keeps auth centralized.
+
+```typescript
+// src/middleware/auth.ts
+import { eq } from "drizzle-orm";
+import { createMiddleware } from "hono/factory";
+import { db } from "../db";
+import { apiKeys, projects } from "../db/schema";
+import { API_KEY_PREFIX, hashKey } from "../lib/api-keys";
+import { auth } from "../lib/auth";
+import { AuthError } from "../lib/errors";
+import { logger } from "../lib/logger";
+import type { AuthContext } from "../types";
+
+export const authMiddleware = createMiddleware<{
+  Variables: { auth: AuthContext };
+}>(async (c, next) => {
+  const authHeader = c.req.header("Authorization");
+
+  // Path 1: API key authentication (Bearer pyx_...)
+  if (authHeader?.startsWith(`Bearer ${API_KEY_PREFIX}`)) {
+    const rawKey = authHeader.slice("Bearer ".length);
+    const authContext = await validateApiKey(rawKey);
+    c.set("auth", authContext);
+    return next();
+  }
+
+  // Path 2: Non-pyx Bearer token — reject with clear guidance
+  // Without this check, random Bearer tokens would fall through to session
+  // auth and silently fail, confusing the developer.
+  if (authHeader?.startsWith("Bearer ")) {
+    throw new AuthError("Invalid API key format. Keys must start with 'pyx_'.");
+  }
+
+  // Path 3: Session cookie (Better Auth)
+  // IMPORTANT: Pass c.req.raw.headers (the raw Request headers),
+  // NOT c.req.header() — Better Auth needs the full Headers object.
+  const session = await auth.api.getSession({ headers: c.req.raw.headers });
+
+  // GOTCHA: Better Auth returns null (not { session: null }) for invalid sessions.
+  // Always check session?.user, not session.user.
+  if (session?.user) {
+    c.set("auth", {
+      type: "session",
+      userId: session.user.id,
+      sessionId: session.session.id,
+    });
+    return next();
+  }
+
+  // No valid auth found
+  throw new AuthError();
+});
+
+async function validateApiKey(rawKey: string): Promise<AuthContext> {
+  const keyHash = await hashKey(rawKey);
+
+  // Single query: look up key + join project for org info
+  const result = await db
+    .select({
+      keyId: apiKeys.id,
+      projectId: apiKeys.projectId,
+      revokedAt: apiKeys.revokedAt,
+      expiresAt: apiKeys.expiresAt,
+      orgId: projects.organizationId,
+    })
+    .from(apiKeys)
+    .innerJoin(projects, eq(apiKeys.projectId, projects.id))
+    .where(eq(apiKeys.keyHash, keyHash))
+    .limit(1);
+
+  if (result.length === 0) {
+    // SECURITY: Generic error — don't reveal whether key exists.
+    // An attacker probing keys should see the same error for
+    // "key not found" and "key is revoked."
+    throw new AuthError();
+  }
+
+  const key = result[0];
+
+  // Check revocation
+  if (key.revokedAt) {
+    throw new AuthError();
+  }
+
+  // Check expiration
+  if (key.expiresAt && key.expiresAt < new Date()) {
+    throw new AuthError();
+  }
+
+  // Fire-and-forget: update lastUsedAt without blocking the request.
+  // If this fails, the request still succeeds — usage tracking is
+  // nice-to-have, not critical path.
+  db.update(apiKeys)
+    .set({ lastUsedAt: new Date() })
+    .where(eq(apiKeys.id, key.keyId))
+    .execute()
+    .catch((err) => {
+      logger.warn({ error: err, apiKeyId: key.keyId }, "Failed to update API key lastUsedAt");
+    });
+
+  return {
+    type: "api_key",
+    apiKeyId: key.keyId,
+    projectId: key.projectId,
+    organizationId: key.orgId,
+  };
+}
+```
+
+### Design Decisions
+
+1. **Single middleware, two paths** — Keeps auth logic centralized. Routes don't need to know which auth method was used.
+
+2. **Explicit non-pyx Bearer rejection** — Without this, a developer using a random JWT would get a generic "auth required" error after session validation fails. The explicit rejection saves debugging time.
+
+3. **Generic AuthError for all key failures** — Whether the key doesn't exist, is revoked, or is expired, the error is the same. This prevents key enumeration attacks.
+
+4. **Fire-and-forget `lastUsedAt`** — The `.catch()` prevents unhandled promise rejections. The request isn't delayed by a non-critical DB write.
+
+5. **Inner join for org resolution** — A single query fetches the key and its project's org. No second DB round-trip needed.
+
+## Tenant Context Middleware
+
+Runs after auth middleware. Resolves the organization, project (if applicable), and plan for the authenticated entity.
+
+```typescript
+// src/middleware/tenant-context.ts
+import { desc, eq } from "drizzle-orm";
+import { createMiddleware } from "hono/factory";
+import { db } from "../db";
+import { orgMemberships, organizations } from "../db/schema";
+import { AppError, AuthError, ForbiddenError } from "../lib/errors";
+import type { AuthContext, TenantContext } from "../types";
+
+export const tenantContextMiddleware = createMiddleware<{
+  Variables: { auth: AuthContext; tenant: TenantContext };
+}>(async (c, next) => {
+  const authCtx = c.get("auth");
+
+  if (!authCtx) {
+    throw new AuthError();
+  }
+
+  let tenant: TenantContext;
+
+  if (authCtx.type === "api_key") {
+    // API key auth: org already resolved in auth middleware, just fetch plan
+    const org = await db
+      .select({ plan: organizations.plan })
+      .from(organizations)
+      .where(eq(organizations.id, authCtx.organizationId))
+      .limit(1);
+
+    if (org.length === 0) {
+      throw new ForbiddenError();
+    }
+
+    tenant = {
+      organizationId: authCtx.organizationId,
+      projectId: authCtx.projectId,
+      userId: null,
+      plan: org[0].plan,
+    };
+  } else {
+    // Session auth: look up user's org membership
+    // For multi-org users, picks most recent membership.
+    // TODO: Support explicit org selection via X-Organization-Id header.
+    const membership = await db
+      .select({
+        orgId: orgMemberships.organizationId,
+        plan: organizations.plan,
+      })
+      .from(orgMemberships)
+      .innerJoin(organizations, eq(orgMemberships.organizationId, organizations.id))
+      .where(eq(orgMemberships.userId, authCtx.userId))
+      .orderBy(desc(orgMemberships.createdAt))
+      .limit(1);
+
+    if (membership.length === 0) {
+      // LESSON: Use a distinct error code, not a generic ForbiddenError.
+      // The frontend needs to differentiate "you don't have permission" from
+      // "you need to create/join an organization." With a generic 403, the
+      // frontend can't show helpful UX like "Create your first organization."
+      throw new AppError("no_organization", "No organization membership found", 403);
+    }
+
+    tenant = {
+      organizationId: membership[0].orgId,
+      projectId: null,
+      userId: authCtx.userId,
+      plan: membership[0].plan,
+    };
+  }
+
+  c.set("tenant", tenant);
+  return next();
+});
+```
+
+### Design Decisions
+
+1. **Separate from auth middleware** — Auth validates identity. Tenant context resolves authorization scope. Keeping them separate makes each testable independently.
+
+2. **API key already has org** — The auth middleware resolves projectId and organizationId during key validation (via the projects join). No extra DB query needed for the org ID — only one query to fetch the plan.
+
+3. **Most-recent membership for multi-org** — A temporary strategy until `X-Organization-Id` header support is added. Ordered by `createdAt DESC` so the auto-created personal org (from signup) is the default.
+
+4. **Distinct `no_organization` error code** — Enables the frontend to show contextual UX. A generic `forbidden` error gives no indication of what's wrong.
+
+## API Key Utilities
+
+Shared constants and functions for key generation and validation.
+
+```typescript
+// src/lib/api-keys.ts
+
+// All API keys start with this prefix. Used for:
+// 1. Quick identification in auth middleware
+// 2. User-visible hint in the dashboard
+// 3. Preventing confusion with other Bearer tokens
+export const API_KEY_PREFIX = "pyx_";
+
+// Base62 encoding (alphanumeric only, no special chars)
+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 — uses Web Crypto API (available in Bun 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");
+}
+```
+
+### Key Generation (in route handler)
+
+```typescript
+// Generate cryptographically secure key
+const randomBytes = crypto.getRandomValues(new Uint8Array(32));
+const rawKey = API_KEY_PREFIX + base62Encode(randomBytes);
+
+// Hash for storage — plaintext NEVER stored
+const keyHash = await hashKey(rawKey);
+const keyPrefix = rawKey.slice(0, 12); // Visible hint: "pyx_AbCdEfGh"
+
+// Store hash + prefix in database
+await db.insert(apiKeys).values({
+  projectId,
+  name,
+  keyHash,
+  keyPrefix,
+  expiresAt: expiresAt ? new Date(expiresAt) : null,
+});
+
+// Return plaintext to user — they'll never see it again
+return c.json({ key: rawKey, hint: `${keyPrefix}...` }, 201);
+```
+
+## Error Types
+
+```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 });
+  }
+}
+```
+
+### Error Handler Middleware
+
+```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
+  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);
+};
+```

package/optional-skills/better-auth-setup/references/schema.md

@@ -0,0 +1,224 @@
+# Database Schema Reference
+
+Complete Drizzle ORM schema for Better Auth with multi-tenant organization support, API keys, and usage tracking.
+
+## Table of Contents
+1. [Auth Tables](#auth-tables) — users, sessions, accounts, verifications
+2. [Organization Tables](#organization-tables) — organizations, memberships, invitations
+3. [Project & API Key Tables](#project--api-key-tables) — projects, api_keys
+4. [Supporting Tables](#supporting-tables) — usage, billing, webhooks
+
+## Auth Tables
+
+These tables are managed by Better Auth. Define them in Drizzle with the exact columns Better Auth expects, using your preferred table names (you'll map them in the adapter config).
+
+```typescript
+import {
+  boolean, index, pgTable, text, timestamp,
+  uniqueIndex, uuid, varchar,
+} from "drizzle-orm/pg-core";
+
+// Users — core identity table
+export const users = pgTable("users", {
+  id: uuid("id").primaryKey().defaultRandom(),
+  name: varchar("name", { length: 255 }),
+  email: varchar("email", { length: 255 }).notNull().unique(),
+  emailVerified: boolean("email_verified").notNull().default(false),
+  image: text("image"),
+  createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+  updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow(),
+});
+
+// Sessions — tracks active login sessions
+export const sessions = pgTable(
+  "sessions",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    userId: uuid("user_id")
+      .notNull()
+      .references(() => users.id, { onDelete: "cascade" }),
+    token: varchar("token", { length: 255 }).notNull().unique(),
+    expiresAt: timestamp("expires_at", { withTimezone: true }).notNull(),
+    ipAddress: varchar("ip_address", { length: 45 }),
+    userAgent: text("user_agent"),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => [index("idx_sessions_user_id").on(table.userId)],
+);
+
+// Accounts — OAuth and credential accounts linked to users
+export const accounts = pgTable(
+  "accounts",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    userId: uuid("user_id")
+      .notNull()
+      .references(() => users.id, { onDelete: "cascade" }),
+    accountId: varchar("account_id", { length: 255 }).notNull(),
+    providerId: varchar("provider_id", { length: 255 }).notNull(),
+    accessToken: text("access_token"),
+    refreshToken: text("refresh_token"),
+    accessTokenExpiresAt: timestamp("access_token_expires_at", { withTimezone: true }),
+    refreshTokenExpiresAt: timestamp("refresh_token_expires_at", { withTimezone: true }),
+    scope: text("scope"),
+    password: text("password"),
+    idToken: text("id_token"),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => [
+    index("idx_accounts_user_id").on(table.userId),
+    uniqueIndex("idx_accounts_provider").on(table.providerId, table.accountId),
+  ],
+);
+
+// Verifications — email verification and password reset tokens
+export const verifications = pgTable(
+  "verifications",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    identifier: text("identifier").notNull(),
+    value: text("value").notNull(),
+    expiresAt: timestamp("expires_at", { withTimezone: true }).notNull(),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => [index("idx_verifications_identifier").on(table.identifier)],
+);
+```
+
+### Key Design Decisions
+
+- **UUIDs everywhere** — Better Auth supports UUID primary keys via `defaultRandom()`. This avoids sequential ID enumeration attacks.
+- **Cascade deletes on sessions/accounts** — When a user is deleted, their sessions and OAuth accounts are automatically cleaned up.
+- **Unique constraint on (providerId, accountId)** — Prevents duplicate OAuth account links.
+- **Index on verifications.identifier** — Email lookups during verification need to be fast.
+- **`withTimezone: true`** — All timestamps stored in UTC. Prevents timezone bugs in multi-region deployments.
+
+## Organization Tables
+
+Multi-tenant support with role-based membership.
+
+```typescript
+export const organizations = pgTable(
+  "organizations",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    name: varchar("name", { length: 255 }).notNull(),
+    slug: varchar("slug", { length: 100 }).notNull().unique(),
+    logo: text("logo"),
+    metadata: text("metadata"),
+    plan: varchar("plan", { length: 50 }).notNull().default("free"),
+    // Billing provider fields (Stripe/Polar/etc.)
+    billingCustomerId: varchar("billing_customer_id", { length: 255 }),
+    billingSubscriptionId: varchar("billing_subscription_id", { length: 255 }),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => [index("idx_organizations_billing").on(table.billingCustomerId)],
+);
+
+export const orgMemberships = pgTable(
+  "org_memberships",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    organizationId: uuid("organization_id")
+      .notNull()
+      .references(() => organizations.id, { onDelete: "cascade" }),
+    userId: uuid("user_id")
+      .notNull()
+      .references(() => users.id, { onDelete: "cascade" }),
+    role: varchar("role", { length: 50 }).notNull().default("member"),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => [
+    uniqueIndex("idx_org_memberships_unique").on(table.organizationId, table.userId),
+    index("idx_org_memberships_user").on(table.userId),
+    index("idx_org_memberships_org").on(table.organizationId),
+  ],
+);
+
+export const invitations = pgTable(
+  "invitations",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    email: varchar("email", { length: 255 }).notNull(),
+    inviterId: uuid("inviter_id")
+      .notNull()
+      .references(() => users.id, { onDelete: "cascade" }),
+    organizationId: uuid("organization_id")
+      .notNull()
+      .references(() => organizations.id, { onDelete: "cascade" }),
+    role: varchar("role", { length: 50 }).notNull().default("member"),
+    status: varchar("status", { length: 50 }).notNull().default("pending"),
+    expiresAt: timestamp("expires_at", { withTimezone: true }).notNull(),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => [
+    index("idx_invitations_org").on(table.organizationId),
+    index("idx_invitations_email").on(table.email),
+  ],
+);
+```
+
+### Key Design Decisions
+
+- **Unique (org, user) membership** — A user can only have one role per org.
+- **Plan on organization** — Billing is org-level, not user-level. This simplifies plan enforcement.
+- **Slug is unique** — Used in URLs (`/orgs/my-org`). Auto-generated with UUID suffix to prevent collisions.
+
+## Project & API Key Tables
+
+Projects scope resources within an organization. API keys are scoped to projects.
+
+```typescript
+export const projects = pgTable(
+  "projects",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    organizationId: uuid("organization_id")
+      .notNull()
+      .references(() => organizations.id, { onDelete: "cascade" }),
+    name: varchar("name", { length: 255 }).notNull(),
+    slug: varchar("slug", { length: 100 }).notNull(),
+    description: text("description"),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => [
+    uniqueIndex("idx_projects_org_slug").on(table.organizationId, table.slug),
+    index("idx_projects_org").on(table.organizationId),
+  ],
+);
+
+export const apiKeys = pgTable(
+  "api_keys",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    projectId: uuid("project_id")
+      .notNull()
+      .references(() => projects.id, { onDelete: "cascade" }),
+    name: varchar("name", { length: 255 }).notNull(),
+    keyHash: varchar("key_hash", { length: 255 }).notNull(),
+    keyPrefix: varchar("key_prefix", { length: 12 }).notNull(),
+    lastUsedAt: timestamp("last_used_at", { withTimezone: true }),
+    expiresAt: timestamp("expires_at", { withTimezone: true }),
+    revokedAt: timestamp("revoked_at", { withTimezone: true }),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => [
+    index("idx_api_keys_project").on(table.projectId),
+    uniqueIndex("idx_api_keys_hash").on(table.keyHash),
+    index("idx_api_keys_prefix").on(table.keyPrefix),
+  ],
+);
+```
+
+### Key Design Decisions
+
+- **Project slug unique per org** — Not globally unique, scoped to organization via composite unique index.
+- **keyHash unique** — Enables O(1) lookup during API key validation.
+- **Soft-delete via `revokedAt`** — Revoked keys remain in the database for audit trail. The auth middleware checks `revokedAt !== null` to reject them.
+- **`lastUsedAt` nullable** — Updated fire-and-forget on each API key auth. Useful for usage analytics and stale key detection.
+- **No plaintext key column** — The plaintext is generated, returned to the user once, and only the SHA-256 hash is stored. This is a security requirement, not an optimization.