@useatlas/create 0.0.1

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

@@ -0,0 +1,201 @@
+import { describe, it, expect, beforeEach, afterEach } from "bun:test";
+import { resetAuthModeCache } from "@atlas/api/lib/auth/detect";
+import { _resetPool } from "@atlas/api/lib/db/internal";
+import { _setAuthInstance } from "@atlas/api/lib/auth/server";
+import {
+  migrateAuthTables,
+  resetMigrationState,
+  getMigrationError,
+} from "@atlas/api/lib/auth/migrate";
+
+// ---------------------------------------------------------------------------
+// Mock pool for internal DB migration tracking
+// ---------------------------------------------------------------------------
+
+function createTrackingPool(opts: { shouldThrow?: boolean } = {}) {
+  const queries: string[] = [];
+  return {
+    pool: {
+      async query(sql: string) {
+        if (opts.shouldThrow) throw new Error("permission denied for CREATE TABLE");
+        queries.push(sql);
+        return { rows: [] };
+      },
+      async end() {},
+      on() {},
+    },
+    queries,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Mock auth instance for Better Auth migration tracking
+// ---------------------------------------------------------------------------
+
+function createTrackingAuth(opts: { shouldThrow?: boolean } = {}) {
+  let migrationCount = 0;
+  return {
+    instance: {
+      $context: Promise.resolve({
+        runMigrations: async () => {
+          if (opts.shouldThrow) throw new Error("Better Auth migration error");
+          migrationCount++;
+        },
+      }),
+    },
+    getMigrationCount: () => migrationCount,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Env snapshot
+// ---------------------------------------------------------------------------
+
+const MANAGED_VARS = [
+  "DATABASE_URL",
+  "BETTER_AUTH_SECRET",
+  "ATLAS_AUTH_JWKS_URL",
+  "ATLAS_API_KEY",
+] as const;
+
+const saved: Record<string, string | undefined> = {};
+
+beforeEach(() => {
+  for (const key of MANAGED_VARS) {
+    saved[key] = process.env[key];
+  }
+  resetMigrationState();
+  resetAuthModeCache();
+  _resetPool();
+  _setAuthInstance(null);
+
+  // Default: no auth env vars
+  delete process.env.DATABASE_URL;
+  delete process.env.BETTER_AUTH_SECRET;
+  delete process.env.ATLAS_AUTH_JWKS_URL;
+  delete process.env.ATLAS_API_KEY;
+});
+
+afterEach(() => {
+  for (const key of MANAGED_VARS) {
+    if (saved[key] !== undefined) process.env[key] = saved[key];
+    else delete process.env[key];
+  }
+  resetMigrationState();
+  resetAuthModeCache();
+  _resetPool();
+  _setAuthInstance(null);
+});
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("migrateAuthTables", () => {
+  it("runs internal DB migration when DATABASE_URL is set", async () => {
+    process.env.DATABASE_URL = "postgresql://user:pass@localhost:5432/atlas";
+    const { pool, queries } = createTrackingPool();
+    _resetPool(pool);
+
+    await migrateAuthTables();
+
+    // migrateInternalDB: 3 audit_log + 4 conversations/messages + 2 starred column + 3 slack + 5 action_log + 2 source tracking = 19 queries
+    expect(queries.length).toBe(26);
+    expect(queries[0]).toContain("CREATE TABLE IF NOT EXISTS audit_log");
+  });
+
+  it("skips internal DB migration when DATABASE_URL is not set", async () => {
+    delete process.env.DATABASE_URL;
+    const { queries } = createTrackingPool();
+    // Don't inject pool — hasInternalDB() returns false, no pool needed
+
+    await migrateAuthTables();
+
+    expect(queries.length).toBe(0);
+  });
+
+  it("runs Better Auth migration in managed mode", async () => {
+    process.env.DATABASE_URL = "postgresql://user:pass@localhost:5432/atlas";
+    process.env.BETTER_AUTH_SECRET = "a".repeat(32);
+    const { pool } = createTrackingPool();
+    _resetPool(pool);
+    const { instance, getMigrationCount } = createTrackingAuth();
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    _setAuthInstance(instance as any);
+
+    await migrateAuthTables();
+
+    expect(getMigrationCount()).toBe(1);
+  });
+
+  it("only runs once (idempotent guard)", async () => {
+    process.env.DATABASE_URL = "postgresql://user:pass@localhost:5432/atlas";
+    process.env.BETTER_AUTH_SECRET = "a".repeat(32);
+    const { pool, queries } = createTrackingPool();
+    _resetPool(pool);
+    const { instance, getMigrationCount } = createTrackingAuth();
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    _setAuthInstance(instance as any);
+
+    await migrateAuthTables();
+    await migrateAuthTables();
+    await migrateAuthTables();
+
+    // Internal DB migration runs once (26 queries: audit_log + conversations/messages + starred column + slack + action_log + source tracking + scheduled_tasks/runs)
+    expect(queries.length).toBe(26);
+    // Better Auth migration runs once
+    expect(getMigrationCount()).toBe(1);
+  });
+
+  it("skips Better Auth migration when not in managed mode", async () => {
+    process.env.DATABASE_URL = "postgresql://user:pass@localhost:5432/atlas";
+    // No BETTER_AUTH_SECRET → auth mode is "none"
+    const { pool } = createTrackingPool();
+    _resetPool(pool);
+    const { getMigrationCount } = createTrackingAuth();
+
+    await migrateAuthTables();
+
+    expect(getMigrationCount()).toBe(0);
+  });
+
+  it("skips Better Auth migration when no internal DB (managed mode)", async () => {
+    delete process.env.DATABASE_URL;
+    process.env.BETTER_AUTH_SECRET = "a".repeat(32);
+
+    await migrateAuthTables();
+
+    // No pool injected, no queries possible — migration was skipped
+  });
+
+  it("does not throw when internal DB migration fails", async () => {
+    process.env.DATABASE_URL = "postgresql://user:pass@localhost:5432/atlas";
+    const { pool } = createTrackingPool({ shouldThrow: true });
+    _resetPool(pool);
+
+    // Should resolve without throwing
+    await expect(migrateAuthTables()).resolves.toBeUndefined();
+  });
+
+  it("getMigrationError returns error message after internal DB failure", async () => {
+    process.env.DATABASE_URL = "postgresql://user:pass@localhost:5432/atlas";
+    const { pool } = createTrackingPool({ shouldThrow: true });
+    _resetPool(pool);
+
+    await migrateAuthTables();
+
+    const err = getMigrationError();
+    expect(err).toBeString();
+    expect(err).toContain("migration failed");
+  });
+
+  it("getMigrationError returns null on success", async () => {
+    process.env.DATABASE_URL = "postgresql://user:pass@localhost:5432/atlas";
+    const { pool } = createTrackingPool();
+    _resetPool(pool);
+
+    await migrateAuthTables();
+
+    expect(getMigrationError()).toBeNull();
+  });
+});

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

@@ -0,0 +1,225 @@
+/**
+ * Unit tests for role-based action permissions.
+ *
+ * Covers:
+ * - getUserRole() defaults per auth mode
+ * - getUserRole() with explicit role
+ * - parseRole() validation
+ * - canApprove() across all role x approval mode combinations
+ * - canApprove() with per-action requiredRole override
+ * - Edge cases: undefined user, auto approval mode
+ */
+
+import { describe, it, expect } from "bun:test";
+import { canApprove, getUserRole, parseRole } from "../permissions";
+import { createAtlasUser } from "../types";
+import type { AtlasRole } from "../types";
+import type { ActionApprovalMode } from "@atlas/api/lib/action-types";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function makeUser(mode: "simple-key" | "managed" | "byot", role?: AtlasRole) {
+  return createAtlasUser(`user-${mode}`, mode, `${mode}-label`, role);
+}
+
+// ---------------------------------------------------------------------------
+// getUserRole()
+// ---------------------------------------------------------------------------
+
+describe("getUserRole()", () => {
+  it("returns explicit role when set", () => {
+    expect(getUserRole(makeUser("simple-key", "admin"))).toBe("admin");
+    expect(getUserRole(makeUser("managed", "analyst"))).toBe("analyst");
+    expect(getUserRole(makeUser("byot", "viewer"))).toBe("viewer");
+  });
+
+  it("defaults to analyst for simple-key mode", () => {
+    expect(getUserRole(makeUser("simple-key"))).toBe("analyst");
+  });
+
+  it("defaults to viewer for managed mode", () => {
+    expect(getUserRole(makeUser("managed"))).toBe("viewer");
+  });
+
+  it("defaults to viewer for byot mode", () => {
+    expect(getUserRole(makeUser("byot"))).toBe("viewer");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// parseRole()
+// ---------------------------------------------------------------------------
+
+describe("parseRole()", () => {
+  it("returns valid roles", () => {
+    expect(parseRole("viewer")).toBe("viewer");
+    expect(parseRole("analyst")).toBe("analyst");
+    expect(parseRole("admin")).toBe("admin");
+  });
+
+  it("is case-insensitive", () => {
+    expect(parseRole("ADMIN")).toBe("admin");
+    expect(parseRole("Analyst")).toBe("analyst");
+    expect(parseRole("VIEWER")).toBe("viewer");
+  });
+
+  it("trims whitespace", () => {
+    expect(parseRole("  admin  ")).toBe("admin");
+  });
+
+  it("returns undefined for invalid values", () => {
+    expect(parseRole("superadmin")).toBeUndefined();
+    expect(parseRole("")).toBeUndefined();
+    expect(parseRole(undefined)).toBeUndefined();
+    expect(parseRole("root")).toBeUndefined();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// canApprove() — core matrix
+// ---------------------------------------------------------------------------
+
+describe("canApprove()", () => {
+  describe("with undefined user (no-auth mode)", () => {
+    it("denies all approval modes (no user = no approval ability)", () => {
+      // Even auto is denied because canApprove only runs on manual approval endpoints.
+      // Auto-approved actions are auto-executed by handleAction — they never reach canApprove.
+      expect(canApprove(undefined, "auto")).toBe(false);
+      expect(canApprove(undefined, "manual")).toBe(false);
+      expect(canApprove(undefined, "admin-only")).toBe(false);
+    });
+  });
+
+  describe("auto approval mode", () => {
+    it("allows all roles (no human approval needed)", () => {
+      expect(canApprove(makeUser("managed", "viewer"), "auto")).toBe(true);
+      expect(canApprove(makeUser("simple-key", "analyst"), "auto")).toBe(true);
+      expect(canApprove(makeUser("byot", "admin"), "auto")).toBe(true);
+    });
+  });
+
+  describe("manual approval mode", () => {
+    it("denies viewer", () => {
+      expect(canApprove(makeUser("managed", "viewer"), "manual")).toBe(false);
+      expect(canApprove(makeUser("byot", "viewer"), "manual")).toBe(false);
+    });
+
+    it("allows analyst", () => {
+      expect(canApprove(makeUser("simple-key", "analyst"), "manual")).toBe(true);
+      expect(canApprove(makeUser("managed", "analyst"), "manual")).toBe(true);
+      expect(canApprove(makeUser("byot", "analyst"), "manual")).toBe(true);
+    });
+
+    it("allows admin", () => {
+      expect(canApprove(makeUser("simple-key", "admin"), "manual")).toBe(true);
+      expect(canApprove(makeUser("managed", "admin"), "manual")).toBe(true);
+      expect(canApprove(makeUser("byot", "admin"), "manual")).toBe(true);
+    });
+  });
+
+  describe("admin-only approval mode", () => {
+    it("denies viewer", () => {
+      expect(canApprove(makeUser("managed", "viewer"), "admin-only")).toBe(false);
+      expect(canApprove(makeUser("byot", "viewer"), "admin-only")).toBe(false);
+    });
+
+    it("denies analyst", () => {
+      expect(canApprove(makeUser("simple-key", "analyst"), "admin-only")).toBe(false);
+      expect(canApprove(makeUser("managed", "analyst"), "admin-only")).toBe(false);
+      expect(canApprove(makeUser("byot", "analyst"), "admin-only")).toBe(false);
+    });
+
+    it("allows admin", () => {
+      expect(canApprove(makeUser("simple-key", "admin"), "admin-only")).toBe(true);
+      expect(canApprove(makeUser("managed", "admin"), "admin-only")).toBe(true);
+      expect(canApprove(makeUser("byot", "admin"), "admin-only")).toBe(true);
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // Per-action requiredRole override
+  // -------------------------------------------------------------------------
+
+  describe("with requiredRole override", () => {
+    it("overrides manual default — requires admin", () => {
+      // manual normally allows analyst, but requiredRole=admin blocks them
+      expect(canApprove(makeUser("simple-key", "analyst"), "manual", "admin")).toBe(false);
+      expect(canApprove(makeUser("simple-key", "admin"), "manual", "admin")).toBe(true);
+    });
+
+    it("overrides admin-only default — requires analyst", () => {
+      // admin-only normally requires admin, but requiredRole=analyst lowers the bar
+      expect(canApprove(makeUser("managed", "analyst"), "admin-only", "analyst")).toBe(true);
+      expect(canApprove(makeUser("managed", "viewer"), "admin-only", "analyst")).toBe(false);
+    });
+
+    it("viewer requiredRole allows all authenticated users", () => {
+      expect(canApprove(makeUser("managed", "viewer"), "manual", "viewer")).toBe(true);
+      expect(canApprove(makeUser("simple-key", "analyst"), "manual", "viewer")).toBe(true);
+      expect(canApprove(makeUser("byot", "admin"), "manual", "viewer")).toBe(true);
+    });
+
+    it("still denies undefined user even with viewer requiredRole", () => {
+      expect(canApprove(undefined, "manual", "viewer")).toBe(false);
+    });
+
+    it("does not apply to auto mode", () => {
+      // Auto mode always returns true regardless of requiredRole
+      expect(canApprove(makeUser("managed", "viewer"), "auto", "admin")).toBe(true);
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // Auth mode default roles (no explicit role set)
+  // -------------------------------------------------------------------------
+
+  describe("with auth mode default roles (no explicit role)", () => {
+    it("simple-key defaults to analyst — can approve manual, blocked from admin-only", () => {
+      const user = makeUser("simple-key"); // defaults to analyst
+      expect(canApprove(user, "manual")).toBe(true);
+      expect(canApprove(user, "admin-only")).toBe(false);
+    });
+
+    it("managed defaults to viewer — blocked from manual and admin-only", () => {
+      const user = makeUser("managed"); // defaults to viewer
+      expect(canApprove(user, "manual")).toBe(false);
+      expect(canApprove(user, "admin-only")).toBe(false);
+    });
+
+    it("byot defaults to viewer — blocked from manual and admin-only", () => {
+      const user = makeUser("byot"); // defaults to viewer
+      expect(canApprove(user, "manual")).toBe(false);
+      expect(canApprove(user, "admin-only")).toBe(false);
+    });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Full auth mode x role x approval mode matrix
+// ---------------------------------------------------------------------------
+
+describe("full permission matrix", () => {
+  const modes = ["simple-key", "managed", "byot"] as const;
+  const roles: AtlasRole[] = ["viewer", "analyst", "admin"];
+  const approvalModes: ActionApprovalMode[] = ["auto", "manual", "admin-only"];
+
+  // Expected results: [role][approvalMode] => boolean
+  const expected: Record<AtlasRole, Record<ActionApprovalMode, boolean>> = {
+    viewer: { auto: true, manual: false, "admin-only": false },
+    analyst: { auto: true, manual: true, "admin-only": false },
+    admin: { auto: true, manual: true, "admin-only": true },
+  };
+
+  for (const mode of modes) {
+    for (const role of roles) {
+      for (const approval of approvalModes) {
+        it(`${mode}/${role} + ${approval} => ${expected[role][approval]}`, () => {
+          const user = makeUser(mode, role);
+          expect(canApprove(user, approval)).toBe(expected[role][approval]);
+        });
+      }
+    }
+  }
+});

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

@@ -0,0 +1,34 @@
+import { describe, it, expect, afterEach } from "bun:test";
+import { betterAuth } from "better-auth";
+import { bearer } from "better-auth/plugins";
+import { apiKey } from "@better-auth/api-key";
+import { resetAuthInstance } from "../server";
+
+describe("Better Auth instance shape", () => {
+  afterEach(() => {
+    resetAuthInstance();
+  });
+
+  it("betterAuth() with @better-auth/api-key returns expected shape", async () => {
+    // Verify the `as unknown as AuthInstance` cast in server.ts doesn't
+    // hide a missing property. This uses the real betterAuth() constructor
+    // with the same plugins as production.
+    const instance = betterAuth({
+      // Minimal adapter stub — enough for construction, never queried.
+      database: {
+        db: null,
+        type: "sqlite",
+      } as unknown as Parameters<typeof betterAuth>[0]["database"],
+      secret: "test-secret-at-least-32-characters-long",
+      plugins: [bearer(), apiKey()],
+    });
+
+    expect(typeof instance.handler).toBe("function");
+    expect(typeof instance.api.getSession).toBe("function");
+    expect(instance.$context).toBeInstanceOf(Promise);
+
+    // Drain the $context promise so the async DB adapter init error
+    // doesn't surface as an unhandled rejection after the test ends.
+    await instance.$context.catch(() => {});
+  });
+});

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

@@ -0,0 +1,176 @@
+import { describe, it, expect, beforeEach, afterEach } from "bun:test";
+import { validateApiKey } from "../simple-key";
+
+function makeReq(headers?: Record<string, string>): Request {
+  return new Request("http://localhost/api/chat", { headers });
+}
+
+describe("validateApiKey()", () => {
+  const origApiKey = process.env.ATLAS_API_KEY;
+  const origApiKeyRole = process.env.ATLAS_API_KEY_ROLE;
+
+  beforeEach(() => {
+    process.env.ATLAS_API_KEY = "sk-test-abcdef1234567890";
+    delete process.env.ATLAS_API_KEY_ROLE;
+  });
+
+  afterEach(() => {
+    if (origApiKey !== undefined) process.env.ATLAS_API_KEY = origApiKey;
+    else delete process.env.ATLAS_API_KEY;
+    if (origApiKeyRole !== undefined) process.env.ATLAS_API_KEY_ROLE = origApiKeyRole;
+    else delete process.env.ATLAS_API_KEY_ROLE;
+  });
+
+  it("authenticates with correct Authorization: Bearer header", () => {
+    const req = makeReq({ Authorization: "Bearer sk-test-abcdef1234567890" });
+    const result = validateApiKey(req);
+    expect(result.authenticated).toBe(true);
+    if (result.authenticated) {
+      expect(result.user).toBeDefined();
+      expect(result.user!.mode).toBe("simple-key");
+    }
+  });
+
+  it("authenticates with correct X-API-Key header", () => {
+    const req = makeReq({ "X-API-Key": "sk-test-abcdef1234567890" });
+    const result = validateApiKey(req);
+    expect(result.authenticated).toBe(true);
+    if (result.authenticated) {
+      expect(result.user).toBeDefined();
+      expect(result.user!.mode).toBe("simple-key");
+    }
+  });
+
+  it("rejects mismatched key", () => {
+    const req = makeReq({ Authorization: "Bearer wrong-key" });
+    const result = validateApiKey(req);
+    expect(result.authenticated).toBe(false);
+    if (!result.authenticated) {
+      expect(result.status).toBe(401);
+      expect(result.error).toBe("Invalid API key");
+    }
+  });
+
+  it("rejects when no key header is present", () => {
+    const req = makeReq();
+    const result = validateApiKey(req);
+    expect(result.authenticated).toBe(false);
+    if (!result.authenticated) {
+      expect(result.status).toBe(401);
+      expect(result.error).toBe("API key required");
+    }
+  });
+
+  it("rejects when ATLAS_API_KEY is not configured", () => {
+    delete process.env.ATLAS_API_KEY;
+    const req = makeReq({ Authorization: "Bearer some-key" });
+    const result = validateApiKey(req);
+    expect(result.authenticated).toBe(false);
+    if (!result.authenticated) {
+      expect(result.status).toBe(401);
+      expect(result.error).toBe("API key not configured");
+    }
+  });
+
+  it("produces a stable user ID (same key → same hash)", () => {
+    const req1 = makeReq({ Authorization: "Bearer sk-test-abcdef1234567890" });
+    const req2 = makeReq({ "X-API-Key": "sk-test-abcdef1234567890" });
+    const r1 = validateApiKey(req1);
+    const r2 = validateApiKey(req2);
+    expect(r1.authenticated).toBe(true);
+    expect(r2.authenticated).toBe(true);
+    if (r1.authenticated && r1.user && r2.authenticated && r2.user) {
+      expect(r1.user.id).toBe(r2.user.id);
+      expect(r1.user.id).toMatch(/^api-key-[0-9a-f]{8}$/);
+    }
+  });
+
+  it("user label contains key prefix (first 4 chars)", () => {
+    const req = makeReq({ Authorization: "Bearer sk-test-abcdef1234567890" });
+    const result = validateApiKey(req);
+    expect(result.authenticated).toBe(true);
+    if (result.authenticated && result.user) {
+      expect(result.user.label).toBe("api-key-sk-t");
+    }
+  });
+
+  it("Authorization header takes precedence over X-API-Key", () => {
+    const req = makeReq({
+      Authorization: "Bearer sk-test-abcdef1234567890",
+      "X-API-Key": "wrong-key",
+    });
+    const result = validateApiKey(req);
+    // Should succeed because Authorization header has the correct key
+    expect(result.authenticated).toBe(true);
+  });
+
+  it("rejects Authorization header without Bearer prefix", () => {
+    const req = makeReq({ Authorization: "sk-test-abcdef1234567890" });
+    // No "Bearer " prefix → extractKey falls through to X-API-Key (not present) → null
+    const result = validateApiKey(req);
+    expect(result.authenticated).toBe(false);
+    if (!result.authenticated) {
+      expect(result.error).toBe("API key required");
+    }
+  });
+
+  it("rejects very short key without throwing", () => {
+    const req = makeReq({ Authorization: "Bearer a" });
+    const result = validateApiKey(req);
+    expect(result.authenticated).toBe(false);
+    if (!result.authenticated) {
+      expect(result.status).toBe(401);
+    }
+  });
+
+  it("rejects very long key without throwing", () => {
+    const req = makeReq({ Authorization: "Bearer " + "x".repeat(1000) });
+    const result = validateApiKey(req);
+    expect(result.authenticated).toBe(false);
+    if (!result.authenticated) {
+      expect(result.status).toBe(401);
+    }
+  });
+
+  describe("role extraction via ATLAS_API_KEY_ROLE", () => {
+    it("ATLAS_API_KEY_ROLE=admin produces user with role 'admin'", () => {
+      process.env.ATLAS_API_KEY_ROLE = "admin";
+      const req = makeReq({ Authorization: "Bearer sk-test-abcdef1234567890" });
+      const result = validateApiKey(req);
+      expect(result.authenticated).toBe(true);
+      if (result.authenticated && result.user) {
+        expect(result.user.role).toBe("admin");
+      }
+    });
+
+    it("ATLAS_API_KEY_ROLE=invalid falls back (no role on user)", () => {
+      process.env.ATLAS_API_KEY_ROLE = "invalid";
+      const req = makeReq({ Authorization: "Bearer sk-test-abcdef1234567890" });
+      const result = validateApiKey(req);
+      expect(result.authenticated).toBe(true);
+      if (result.authenticated && result.user) {
+        expect(result.user.role).toBeUndefined();
+      }
+    });
+
+    it("ATLAS_API_KEY_ROLE=ADMIN (case insensitive) works", () => {
+      process.env.ATLAS_API_KEY_ROLE = "ADMIN";
+      const req = makeReq({ Authorization: "Bearer sk-test-abcdef1234567890" });
+      const result = validateApiKey(req);
+      expect(result.authenticated).toBe(true);
+      if (result.authenticated && result.user) {
+        expect(result.user.role).toBe("admin");
+      }
+    });
+
+    it("no ATLAS_API_KEY_ROLE set — user has no explicit role", () => {
+      delete process.env.ATLAS_API_KEY_ROLE;
+      const req = makeReq({ Authorization: "Bearer sk-test-abcdef1234567890" });
+      const result = validateApiKey(req);
+      expect(result.authenticated).toBe(true);
+      if (result.authenticated && result.user) {
+        expect(result.user.role).toBeUndefined();
+      }
+    });
+  });
+});

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

@@ -0,0 +1,44 @@
+/**
+ * Tests for createAtlasUser validation and AUTH_MODES constant.
+ */
+
+import { describe, it, expect } from "bun:test";
+import { createAtlasUser, AUTH_MODES } from "../types";
+
+describe("createAtlasUser()", () => {
+  it("throws when id is empty string", () => {
+    expect(() => createAtlasUser("", "simple-key", "label")).toThrow(
+      "AtlasUser id must be non-empty",
+    );
+  });
+
+  it("throws when label is empty string", () => {
+    expect(() => createAtlasUser("usr_1", "managed", "")).toThrow(
+      "AtlasUser label must be non-empty",
+    );
+  });
+
+  it("returns an object with correct id, mode, and label", () => {
+    const user = createAtlasUser("usr_1", "byot", "alice@example.com");
+    expect(user.id).toBe("usr_1");
+    expect(user.mode).toBe("byot");
+    expect(user.label).toBe("alice@example.com");
+  });
+
+  it("returns a frozen object", () => {
+    const user = createAtlasUser("usr_1", "simple-key", "api-key-sk-t");
+    expect(Object.isFrozen(user)).toBe(true);
+  });
+});
+
+describe("AUTH_MODES", () => {
+  it("contains all four auth modes", () => {
+    expect(AUTH_MODES).toEqual(["none", "simple-key", "managed", "byot"]);
+  });
+
+  it("is a readonly tuple at the type level", () => {
+    // `as const` makes the array readonly at compile time; at runtime it's a plain array
+    expect(Array.isArray(AUTH_MODES)).toBe(true);
+    expect(AUTH_MODES.length).toBe(4);
+  });
+});