@useatlas/create 0.0.1

package/templates/nextjs-standalone/src/lib/auth/migrate.ts

@@ -0,0 +1,111 @@
+/**
+ * Better Auth table migration — runs once at server boot.
+ *
+ * Extracted from validateEnvironment() so the startup diagnostics
+ * function stays pure (diagnose-only, never mutate). The Hono server
+ * entry point (server.ts) calls migrateAuthTables() once on startup.
+ */
+
+import { detectAuthMode } from "@atlas/api/lib/auth/detect";
+import { hasInternalDB, internalQuery } from "@atlas/api/lib/db/internal";
+import { createLogger } from "@atlas/api/lib/logger";
+
+const log = createLogger("auth-migrate");
+
+let _migrated = false;
+let _migrationError: string | null = null;
+
+/** Return the last migration error message, or null if migrations succeeded (or haven't run). */
+export function getMigrationError(): string | null {
+  return _migrationError;
+}
+
+/**
+ * Run Better Auth table migrations (user, session, account, etc.)
+ * if managed auth mode is active and DATABASE_URL is configured.
+ *
+ * Safe to call multiple times — only runs once (idempotent guard).
+ * Also runs the internal DB migration (audit_log table).
+ */
+export async function migrateAuthTables(): Promise<void> {
+  if (_migrated) return;
+
+  // Internal DB migration (audit_log) — runs regardless of auth mode
+  if (hasInternalDB()) {
+    try {
+      const { migrateInternalDB } = await import("@atlas/api/lib/db/internal");
+      await migrateInternalDB();
+    } catch (err) {
+      log.error({ err }, "Internal DB migration failed");
+      _migrationError = "Connected to the internal database but migration failed. Check database permissions (CREATE TABLE, CREATE INDEX).";
+      // Don't block server start — audit will fall back to pino-only
+    }
+  }
+
+  // Better Auth migration — only in managed mode
+  const authMode = detectAuthMode();
+  if (authMode !== "managed") {
+    _migrated = true;
+    return;
+  }
+
+  if (!hasInternalDB()) {
+    log.error(
+      "Managed auth mode requires DATABASE_URL for session storage. Skipping auth migration.",
+    );
+    _migrated = true;
+    return;
+  }
+
+  try {
+    const { getAuthInstance } = await import("@atlas/api/lib/auth/server");
+    const auth = getAuthInstance();
+    const ctx = await auth.$context;
+    await ctx.runMigrations();
+    log.info("Better Auth migration complete");
+    await bootstrapAdminUser();
+  } catch (err) {
+    log.error({ err }, "Better Auth migration failed — managed auth may not work");
+    _migrationError = "Connected to the internal database but Better Auth migration failed. Managed auth may not work. Check database permissions (CREATE TABLE).";
+  }
+
+  _migrated = true;
+}
+
+/**
+ * Promote an existing user to admin on upgrade if ATLAS_ADMIN_EMAIL is set
+ * and no admin exists yet. Handles the case where users were created before
+ * the admin plugin added the `role` column.
+ */
+async function bootstrapAdminUser(): Promise<void> {
+  const adminEmail = process.env.ATLAS_ADMIN_EMAIL?.toLowerCase().trim();
+  if (!adminEmail) return;
+
+  try {
+    const existing = await internalQuery<{ count: string }>(
+      `SELECT COUNT(*) as count FROM "user" WHERE role = 'admin'`,
+    );
+    if (parseInt(String(existing[0]?.count ?? "0"), 10) > 0) {
+      log.debug("Bootstrap: admin user already exists — skipping promotion");
+      return;
+    }
+
+    const result = await internalQuery<{ id: string; email: string }>(
+      `UPDATE "user" SET role = 'admin' WHERE LOWER(email) = $1 RETURNING id, email`,
+      [adminEmail],
+    );
+    if (result.length > 0) {
+      log.info({ email: result[0].email, id: result[0].id }, "Bootstrap: existing user promoted to admin via ATLAS_ADMIN_EMAIL");
+    } else {
+      log.warn({ adminEmail }, "Bootstrap: ATLAS_ADMIN_EMAIL is set but no user with that email exists yet — role will be assigned on first signup");
+    }
+  } catch (err) {
+    log.error({ err }, "Bootstrap admin promotion failed — admin console may be inaccessible");
+  }
+}
+
+/** Reset migration state. For testing only. */
+export function resetMigrationState(): void {
+  _migrated = false;
+  _migrationError = null;
+}

package/templates/nextjs-standalone/src/lib/auth/permissions.ts

@@ -0,0 +1,156 @@
+/**
+ * Role-based action permissions.
+ *
+ * Determines whether a user can approve an action based on their role
+ * and the action's approval mode. Roles are extracted from the authenticated
+ * user, with defaults that vary by auth mode.
+ *
+ * Role hierarchy: admin > analyst > viewer
+ *
+ * | Approval mode | viewer | analyst | admin |
+ * |---------------|--------|---------|-------|
+ * | auto          | yes*   | yes*    | yes*  |
+ * | manual        | no     | yes     | yes   |
+ * | admin-only    | no     | no      | yes   |
+ *
+ * * Auto-approved actions are executed immediately in handleAction and never
+ *   reach the approval endpoint. canApprove returns true for any authenticated
+ *   user when mode is "auto".
+ */
+
+import type { AtlasUser, AtlasRole } from "@atlas/api/lib/auth/types";
+import type { ActionApprovalMode } from "@atlas/api/lib/action-types";
+import { ATLAS_ROLES } from "@atlas/api/lib/auth/types";
+import { createLogger } from "@atlas/api/lib/logger";
+
+const log = createLogger("auth:permissions");
+
+// ---------------------------------------------------------------------------
+// Role hierarchy
+// ---------------------------------------------------------------------------
+
+const ROLE_LEVEL: Record<AtlasRole, number> = {
+  viewer: 0,
+  analyst: 1,
+  admin: 2,
+};
+
+// ---------------------------------------------------------------------------
+// Role extraction
+// ---------------------------------------------------------------------------
+
+/**
+ * Default role for each auth mode when the user object does not carry
+ * an explicit role.
+ * - simple-key: analyst (overridable via ATLAS_API_KEY_ROLE)
+ * - managed: viewer (role comes from Better Auth organization plugin)
+ * - byot: viewer (role comes from JWT claim)
+ */
+const AUTH_MODE_DEFAULT_ROLE: Record<string, AtlasRole> = {
+  "simple-key": "analyst",
+  managed: "viewer",
+  byot: "viewer",
+};
+
+/**
+ * Get the effective role for a user. Falls back to auth-mode defaults
+ * when the user has no explicit role set.
+ */
+export function getUserRole(user: AtlasUser): AtlasRole {
+  if (user.role) return user.role;
+  return AUTH_MODE_DEFAULT_ROLE[user.mode] ?? "viewer";
+}
+
+/**
+ * Parse and validate a role string. Returns the role if valid, undefined otherwise.
+ */
+export function parseRole(value: string | undefined): AtlasRole | undefined {
+  if (!value) return undefined;
+  const lower = value.toLowerCase().trim();
+  if ((ATLAS_ROLES as readonly string[]).includes(lower)) {
+    return lower as AtlasRole;
+  }
+  return undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Permission check
+// ---------------------------------------------------------------------------
+
+/**
+ * Minimum role required for each approval mode.
+ * Auto-approved actions bypass this check entirely (no human approval needed).
+ */
+const APPROVAL_MODE_MIN_ROLE: Record<ActionApprovalMode, AtlasRole> = {
+  auto: "viewer", // Not actually checked — auto actions don't need approval
+  manual: "analyst",
+  "admin-only": "admin",
+};
+
+/**
+ * Check whether a user can approve an action given its approval configuration.
+ *
+ * @param user - The authenticated user attempting to approve. If undefined
+ *   (no-auth mode), approval is always denied.
+ * @param approvalMode - The action's effective approval mode (auto/manual/admin-only).
+ * @param requiredRole - Optional per-action role override from config. When set,
+ *   this takes precedence over the approval mode's default role requirement.
+ * @returns true if the user has sufficient permissions to approve.
+ */
+export function canApprove(
+  user: AtlasUser | undefined,
+  approvalMode: ActionApprovalMode,
+  requiredRole?: AtlasRole,
+): boolean {
+  // No user = no-auth mode. Actions require identity.
+  if (!user) {
+    log.debug("canApprove: denied — no authenticated user");
+    return false;
+  }
+
+  // Auto-approved actions don't need human approval
+  if (approvalMode === "auto") {
+    return true;
+  }
+
+  const userRole = getUserRole(user);
+  const userLevel = ROLE_LEVEL[userRole];
+
+  // If a per-action requiredRole is set, use it as the minimum
+  if (requiredRole) {
+    const requiredLevel = ROLE_LEVEL[requiredRole];
+    const modeMinRole = APPROVAL_MODE_MIN_ROLE[approvalMode];
+    const modeMinLevel = ROLE_LEVEL[modeMinRole];
+    if (requiredLevel < modeMinLevel) {
+      log.warn(
+        { approvalMode, requiredRole, modeMinRole },
+        "Per-action requiredRole (%s) is lower than approval mode default (%s) — this weakens the '%s' mode for this action",
+        requiredRole,
+        modeMinRole,
+        approvalMode,
+      );
+    }
+    const allowed = userLevel >= requiredLevel;
+    if (!allowed) {
+      log.debug(
+        { userId: user.id, userRole, requiredRole, approvalMode },
+        "canApprove: denied — user role below per-action requiredRole",
+      );
+    }
+    return allowed;
+  }
+
+  // Otherwise, use the approval mode's default minimum role
+  const minRole = APPROVAL_MODE_MIN_ROLE[approvalMode];
+  const minLevel = ROLE_LEVEL[minRole];
+  const allowed = userLevel >= minLevel;
+
+  if (!allowed) {
+    log.debug(
+      { userId: user.id, userRole, minRole, approvalMode },
+      "canApprove: denied — user role below approval mode minimum",
+    );
+  }
+
+  return allowed;
+}

package/templates/nextjs-standalone/src/lib/auth/server.ts

@@ -0,0 +1,142 @@
+/**
+ * Better Auth server instance — lazy singleton.
+ *
+ * The betterAuth() instance is created on first call to getAuthInstance(),
+ * so no Better Auth initialization (database connections, table migrations)
+ * happens unless managed mode is actively used. Although this module is
+ * loaded into the module graph via static imports (managed.ts → middleware.ts),
+ * the actual betterAuth() constructor is deferred until the first managed-mode
+ * request invokes getAuthInstance(). The catch-all route additionally uses
+ * dynamic import() for the better-auth/next-js adapter, keeping that
+ * subpackage out of the bundle for non-managed deployments.
+ */
+
+import { betterAuth } from "better-auth";
+import { bearer, admin } from "better-auth/plugins";
+// @better-auth/api-key must match the better-auth core version.
+// Both are pinned to ^1.5.1 in package.json — update together.
+import { apiKey } from "@better-auth/api-key";
+import { getInternalDB, hasInternalDB, internalQuery } from "@atlas/api/lib/db/internal";
+import { createLogger } from "@atlas/api/lib/logger";
+
+const log = createLogger("auth:server");
+
+/**
+ * Intentionally typed as the base Auth type (without plugin extensions).
+ * The codebase only uses .handler, .api.getSession, and .$context — all of
+ * which exist on the base type. Plugin-specific API methods (e.g.
+ * createApiKey) are handled through Better Auth's HTTP handler, not called
+ * directly on this instance.
+ *
+ * The `as unknown as AuthInstance` cast below exists because
+ * @better-auth/api-key and the admin plugin return plugin types that make
+ * the concrete Auth<Options> nominally incompatible with
+ * Auth<BetterAuthOptions>. This is safe because the base type is a
+ * structural subset of the actual instance.
+ */
+type AuthInstance = ReturnType<typeof betterAuth>;
+
+let _instance: AuthInstance | null = null;
+
+export function getAuthInstance(): AuthInstance {
+  if (_instance) return _instance;
+
+  const secret = process.env.BETTER_AUTH_SECRET;
+  if (!secret) {
+    throw new Error(
+      "BETTER_AUTH_SECRET is not set. Managed auth mode requires this environment variable.",
+    );
+  }
+  if (secret.length < 32) {
+    throw new Error(
+      `BETTER_AUTH_SECRET must be at least 32 characters (got ${secret.length}). Use a cryptographically random string.`,
+    );
+  }
+
+  const adminEmail = process.env.ATLAS_ADMIN_EMAIL?.toLowerCase().trim();
+
+  // Derive parent domain for cross-subdomain cookies (e.g. "useatlas.dev" from
+  // BETTER_AUTH_URL="https://api.useatlas.dev"). Only enabled when CORS origin
+  // is set (i.e. cross-origin deployment). Without this, cookies are scoped to
+  // the API subdomain and won't be sent from the frontend subdomain.
+  const corsOrigin = process.env.ATLAS_CORS_ORIGIN;
+  let cookieDomain: string | undefined;
+  if (corsOrigin && process.env.BETTER_AUTH_URL) {
+    try {
+      const host = new URL(process.env.BETTER_AUTH_URL).hostname;
+      const parts = host.split(".");
+      if (parts.length >= 2) {
+        cookieDomain = parts.slice(-2).join(".");
+      }
+    } catch { /* ignore malformed URL */ }
+  }
+
+  const instance = betterAuth({
+    // getInternalDB() returns a pg.Pool typed as InternalPool.
+    // Cast needed because Better Auth expects its own pool/adapter type.
+    database: getInternalDB() as unknown as Parameters<typeof betterAuth>[0]["database"],
+    secret,
+    baseURL: process.env.BETTER_AUTH_URL,
+    emailAndPassword: {
+      enabled: true,
+      requireEmailVerification: false,
+      autoSignIn: true,
+    },
+    session: {
+      expiresIn: 60 * 60 * 24 * 7,
+      updateAge: 60 * 60 * 24,
+      cookieCache: { enabled: true, maxAge: 5 * 60 },
+    },
+    plugins: [bearer(), apiKey(), admin({ defaultRole: "analyst", adminRoles: ["admin"] })],
+    trustedOrigins:
+      process.env.BETTER_AUTH_TRUSTED_ORIGINS?.split(",")
+        .map((s) => s.trim())
+        .filter(Boolean) || [],
+    advanced: cookieDomain ? {
+      defaultCookieAttributes: {
+        domain: `.${cookieDomain}`,
+      },
+    } : undefined,
+    databaseHooks: {
+      user: {
+        create: {
+          before: async (user) => {
+            try {
+              if (adminEmail && user.email?.toLowerCase().trim() === adminEmail) {
+                log.info({ email: user.email }, "Bootstrap: promoting signup to admin (ATLAS_ADMIN_EMAIL match)");
+                return { data: { ...user, role: "admin" } };
+              }
+
+              if (!adminEmail) {
+                if (!hasInternalDB()) return;
+                const rows = await internalQuery<{ id: string }>(
+                  `SELECT id FROM "user" WHERE role = 'admin' LIMIT 1`,
+                );
+                if (rows.length === 0) {
+                  log.info({ email: user.email }, "Bootstrap: no admin exists — promoting first signup to admin");
+                  return { data: { ...user, role: "admin" } };
+                }
+              }
+            } catch (err) {
+              log.error({ err }, "Bootstrap admin check failed — defaulting to normal role assignment");
+            }
+          },
+        },
+      },
+    },
+  }) as unknown as AuthInstance;
+
+  _instance = instance;
+  return instance;
+}
+
+export function resetAuthInstance(): void {
+  _instance = null;
+}
+
+/** @internal — test-only. Inject a mock auth instance. */
+export function _setAuthInstance(mock: AuthInstance | null): void {
+  _instance = mock;
+}
+
+export type Auth = AuthInstance;

package/templates/nextjs-standalone/src/lib/auth/simple-key.ts

@@ -0,0 +1,92 @@
+/**
+ * Simple API key authentication.
+ *
+ * Validates requests against ATLAS_API_KEY using constant-time comparison.
+ * Extracts key from Authorization: Bearer <key> or X-API-Key: <key> header.
+ */
+
+import { createHash, timingSafeEqual } from "crypto";
+import type { AuthResult } from "@atlas/api/lib/auth/types";
+import { createAtlasUser } from "@atlas/api/lib/auth/types";
+import { parseRole } from "@atlas/api/lib/auth/permissions";
+import { createLogger } from "@atlas/api/lib/logger";
+
+const log = createLogger("auth");
+
+/** Extract API key from request headers. Authorization header takes precedence. */
+function extractKey(req: Request): string | null {
+  const authHeader = req.headers.get("authorization");
+  if (authHeader) {
+    const match = authHeader.match(/^Bearer\s+(.+)$/i);
+    if (match) return match[1];
+    log.warn(
+      { scheme: authHeader.split(" ")[0] },
+      "Authorization header present but not in 'Bearer <key>' format",
+    );
+  }
+
+  const xApiKey = req.headers.get("x-api-key");
+  if (xApiKey) return xApiKey;
+
+  return null;
+}
+
+/** SHA-256 hash of a string, returned as hex. */
+function sha256(input: string): string {
+  return createHash("sha256").update(input).digest("hex");
+}
+
+/** Validate a request against ATLAS_API_KEY. */
+export function validateApiKey(req: Request): AuthResult {
+  const expected = process.env.ATLAS_API_KEY;
+  if (!expected) {
+    log.warn("ATLAS_API_KEY not configured but simple-key auth attempted");
+    return { authenticated: false, mode: "simple-key", status: 401, error: "API key not configured" };
+  }
+
+  const key = extractKey(req);
+  if (!key) {
+    return { authenticated: false, mode: "simple-key", status: 401, error: "API key required" };
+  }
+
+  // Hash both to fixed-length digests so timingSafeEqual never leaks key length
+  const keyHash = createHash("sha256").update(key).digest();
+  const expectedHash = createHash("sha256").update(expected).digest();
+
+  if (!timingSafeEqual(keyHash, expectedHash)) {
+    log.warn("API key validation failed");
+    return { authenticated: false, mode: "simple-key", status: 401, error: "Invalid API key" };
+  }
+
+  const id = `api-key-${sha256(key).slice(0, 8)}`;
+  const label = `api-key-${key.slice(0, 4)}`;
+
+  // Role override via ATLAS_API_KEY_ROLE (default: analyst — see permissions.ts)
+  const rawRole = process.env.ATLAS_API_KEY_ROLE;
+  const role = parseRole(rawRole);
+  if (rawRole && !role) {
+    log.warn({ value: rawRole, validRoles: ["viewer", "analyst", "admin"] }, "ATLAS_API_KEY_ROLE is set to an invalid value — defaulting to 'analyst'. Valid values: viewer, analyst, admin.");
+  }
+
+  // Parse optional claims from env var for RLS policy evaluation
+  let claims: Record<string, unknown> | undefined;
+  const rawClaims = process.env.ATLAS_RLS_CLAIMS;
+  if (rawClaims) {
+    try {
+      const parsed = JSON.parse(rawClaims);
+      if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
+        claims = parsed;
+      } else {
+        log.warn("ATLAS_RLS_CLAIMS must be a JSON object — ignoring");
+      }
+    } catch {
+      log.warn({ value: rawClaims.slice(0, 50) }, "ATLAS_RLS_CLAIMS is not valid JSON — ignoring");
+    }
+  }
+
+  return {
+    authenticated: true,
+    mode: "simple-key",
+    user: createAtlasUser(id, "simple-key", label, role, claims),
+  };
+}

package/templates/nextjs-standalone/src/lib/auth/types.ts

@@ -0,0 +1,49 @@
+/**
+ * Auth types for Atlas.
+ *
+ * AuthMode determines how requests are authenticated.
+ * AtlasRole determines the user's permission level for action approval.
+ * AtlasUser represents a verified identity attached to a request.
+ * AuthResult is the return type from all auth validators.
+ */
+
+export const AUTH_MODES = ["none", "simple-key", "managed", "byot"] as const;
+export type AuthMode = (typeof AUTH_MODES)[number];
+
+export const ATLAS_ROLES = ["viewer", "analyst", "admin"] as const;
+export type AtlasRole = (typeof ATLAS_ROLES)[number];
+
+export interface AtlasUser {
+  id: string;
+  mode: Exclude<AuthMode, "none">;
+  label: string;
+  /** Permission role for action approval. Defaults based on auth mode when not set. */
+  role?: AtlasRole;
+  /** Auth-source claims for RLS policy evaluation (JWT payload, session user, or env-derived). */
+  claims?: Readonly<Record<string, unknown>>;
+}
+
+export type AuthResult =
+  | { authenticated: true; mode: Exclude<AuthMode, "none">; user: AtlasUser }
+  | { authenticated: true; mode: "none"; user: undefined }
+  | { authenticated: false; mode: AuthMode; status: 401 | 500; error: string };
+
+/** Create a frozen AtlasUser with non-empty id/label validation. */
+export function createAtlasUser(
+  id: string,
+  mode: Exclude<AuthMode, "none">,
+  label: string,
+  role?: AtlasRole,
+  claims?: Record<string, unknown>,
+): AtlasUser {
+  if (!id) throw new Error("AtlasUser id must be non-empty");
+  if (!label) throw new Error("AtlasUser label must be non-empty");
+  const frozenClaims = claims ? Object.freeze({ ...claims }) : undefined;
+  return Object.freeze({
+    id,
+    mode,
+    label,
+    ...(role ? { role } : {}),
+    ...(frozenClaims ? { claims: frozenClaims } : {}),
+  });
+}