A local-first multi-agent app development platform, built on PenguinHarness
/**
* The auth flow through the routes: admin seeding, login, logout, password change, the session
* cookie, the initial Project and the account's UI preferences.
*
* - A protected API answers 401 without a session; registration does not exist.
* - The seeded admin owns default_project with its default Agent, carries the initial-password
* flag, and a second seed neither duplicates the account nor rerolls its password.
* - An admin-created account gets `<userId>-default_project`, named after the user, with the
* preset default model.
* - Login, /api/me and logout round-trip; a wrong password is 401.
* - Changing one's own password checks the old one and the policy, keeps the current session,
* clears the initial flag, and retires the old password.
* - The Secure cookie flag follows x-forwarded-proto only when the proxy is trusted.
* - A write with a non-JSON Content-Type is refused (CSRF defense).
* - A seed password below the policy is refused before any account is created.
* - Login failures back off per username, unknown usernames identically, and a success resets
* the counter; an unknown username, a wrong password and an uncheckable hash answer alike.
* - An unknown username is checked against one dummy hash, made once by the server's hasher.
* - The admin-password check reads the stored hash, not the configured pin.
* - Generated initial passwords are 24 base64url characters and never repeat.
* - Preferences start empty, and each PUT merges without clobbering another writer's fields.
*/
import fs from "node:fs/promises";
import path from "node:path";
import { afterEach, beforeEach, describe, expect, it } from "vitest";
import { wire } from "@adelie/core/kernel";
import type { MeResponse, ProjectsResponse } from "../src/api/types.js";
import { bootAppDeps } from "../src/app.js";
import { hashPassword, ScryptHasher } from "../src/auth/password.js";
import { generateInitialAdminPassword } from "../src/auth/service.js";
import { ProjectConfigService } from "../src/services/project-config-service.js";
import {
apiClient,
createTestApp,
loginAdmin,
loginUser,
makeTempRoot,
provisionUser,
TEST_ADMIN_PASSWORD,
testConfig,
flattenForTests,
replacementsFor,
} from "./helpers.js";
import type { TestApp } from "./helpers.js";
describe("auth", () => {
let t: TestApp;
beforeEach(async () => {
t = await createTestApp();
});
afterEach(async () => {
await t.cleanup();
});
it("accessing a protected API while not logged in returns 401", async () => {
const res = await t.app.request("/api/projects");
expect(res.status).toBe(401);
const body = (await res.json()) as { error: { code: string } };
expect(body.error.code).toBe("unauthorized");
});
it("registration is closed: no register endpoint", async () => {
// /api/auth is the runtime's own public namespace (the business platform declines it
// wholesale), so an unknown path in it is an honest 404, logged in or not.
const anon = await t.app.request("/api/auth/register", {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({ userId: "alice", password: "password-123" }),
});
expect(anon.status).toBe(404);
// Logged in: same 404, proving the route has indeed been removed.
const admin = await loginAdmin(t.app);
const res = await apiClient(t.app, admin.cookie).post("/api/auth/register", {
userId: "alice",
password: "password-123",
});
expect(res.status).toBe(404);
});
it("seeded admin manages default_project; initial password carries the flag", async () => {
const admin = await loginAdmin(t.app);
expect(admin.user.isAdmin).toBe(true);
expect(admin.user.passwordIsInitial).toBe(true);
const api = apiClient(t.app, admin.cookie);
const projects = (await (await api.get("/api/projects")).json()) as ProjectsResponse;
expect(projects.projects.map((p) => p.projectId)).toContain("default_project");
expect(projects.projects[0]!.role).toBe("owner");
// Adopted, not created: its directory predates the Web onboarding, so the name is
// backfilled — without it every surface shows the raw id as the Project's label.
expect(projects.projects[0]!.name).toBe("default");
await expect(
fs.readFile(path.join(t.root, "default_project", ".project_config.toml"), "utf8"),
).resolves.toContain('name = "default"');
// default_agent has been initialized (directory exists).
await expect(
fs.access(path.join(t.root, "default_project", "agents", "default_agent", "agent_state")),
).resolves.toBeUndefined();
// Seeding is idempotent: re-seeding neither duplicates the account nor rerolls its
// password — the original still signs in.
await t.deps.authService.seedAdmin();
expect(t.deps.db.prepare("SELECT COUNT(*) AS n FROM users").get()?.n).toBe(1);
await loginAdmin(t.app);
});
it("an adopted default_project keeps the name it already carries", async () => {
// The operator (or an older CLI) named it first; the backfill must not overwrite that.
t = await createTestApp({
beforeSeed: async (root) => {
await wire(ProjectConfigService, { paths: { root } }).writeRaw("default_project", {
name: "cli-work",
});
},
});
const { cookie } = await loginAdmin(t.app);
const api = apiClient(t.app, cookie);
const projects = (await (await api.get("/api/projects")).json()) as ProjectsResponse;
expect(projects.projects[0]!.name).toBe("cli-work");
});
it("names the shared default_project on a later boot, when adoption is long past", async () => {
const root = await makeTempRoot();
const boot = async () =>
flattenForTests(await bootAppDeps(testConfig(root), replacementsFor({ log: () => {} })));
const file = path.join(root, "default_project", ".project_config.toml");
// A boot over an empty root must not bring the Project into existence on its own.
const first = await boot();
await expect(fs.access(file)).rejects.toThrow();
await first.authService.seedAdmin();
expect(await fs.readFile(file, "utf8")).toContain('name = "default"');
first.channels.dispose();
first.db.close();
// As an install that adopted the Project before the backfill existed looks on disk, and
// with its admin already in place — so seeding early-returns and only the boot sweep runs.
const older = (await fs.readFile(file, "utf8"))
.split("\n")
.filter((line) => !line.startsWith("name = "))
.join("\n");
await fs.writeFile(file, older);
const second = await boot();
try {
expect(await fs.readFile(file, "utf8")).toContain('name = "default"');
expect(second.db.prepare("SELECT COUNT(*) AS n FROM users").get()?.n).toBe(0);
} finally {
second.channels.dispose();
second.db.close();
await fs.rm(root, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 });
}
});
it("admin-created: default Project is <userId>-default_project, name defaults", async () => {
const bob = await provisionUser(t.app, "bob");
expect(bob.user.isAdmin).toBe(false);
expect(bob.user.passwordIsInitial).toBe(true);
const api = apiClient(t.app, bob.cookie);
const projects = (await (await api.get("/api/projects")).json()) as ProjectsResponse;
expect(projects.projects).toHaveLength(1);
const p = projects.projects[0]!;
expect(p.projectId).toBe("bob-default_project");
expect(p.name).toBe("bob");
expect(p.role).toBe("owner");
expect(p.ownerUserId).toBe("bob");
// The initial Project's .project_config.toml carries the display name and preset model config (the default model is written along with it).
const toml = await fs.readFile(
path.join(t.root, "bob-default_project", ".project_config.toml"),
"utf8",
);
expect(toml).toContain('name = "bob"');
expect(toml).toContain(
'default_model = { provider = "deepseek", model_id = "deepseek-flash" }',
);
});
it("login / me / logout round trip; wrong password 401", async () => {
await provisionUser(t.app, "carol");
const wrong = await t.app.request("/api/auth/login", {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({ userId: "carol", password: "wrong-password" }),
});
expect(wrong.status).toBe(401);
const { cookie } = await loginUser(t.app, "carol", "password-123");
expect(cookie.startsWith("penguin_session=")).toBe(true);
const api = apiClient(t.app, cookie);
const me = (await (await api.get("/api/me")).json()) as MeResponse;
expect(me.user.userId).toBe("carol");
const logout = await api.post("/api/auth/logout");
expect(logout.status).toBe(204);
const after = await api.get("/api/me");
expect(after.status).toBe(401);
});
it("self password change: old checked, new takes effect, initial flag cleared", async () => {
const { cookie } = await provisionUser(t.app, "dave");
const api = apiClient(t.app, cookie);
const wrongOld = await api.put("/api/me/password", {
oldPassword: "not-the-password",
newPassword: "new-password-1",
});
expect(wrongOld.status).toBe(400);
const tooShort = await api.put("/api/me/password", {
oldPassword: "password-123",
newPassword: "short",
});
expect(tooShort.status).toBe(400);
const ok = await api.put("/api/me/password", {
oldPassword: "password-123",
newPassword: "new-password-1",
});
expect(ok.status).toBe(204);
// After the password change, the current session remains valid and the initial-password flag is cleared.
const me = (await (await api.get("/api/me")).json()) as MeResponse;
expect(me.user.passwordIsInitial).toBe(false);
// The old password is invalidated, and the new password can log in.
const oldLogin = await t.app.request("/api/auth/login", {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({ userId: "dave", password: "password-123" }),
});
expect(oldLogin.status).toBe(401);
await loginUser(t.app, "dave", "new-password-1");
});
it("ignores x-forwarded-proto for the Secure flag unless the proxy is trusted", async () => {
// Caller-supplied, and untrusted by default (the stance hmr/routes.ts states). Trusting
// it would let anyone who can reach a plain-HTTP port make the server hand out a Secure
// cookie the browser then refuses to send back over that same connection.
const login = await t.app.request("/api/auth/login", {
method: "POST",
headers: { "content-type": "application/json", "x-forwarded-proto": "https" },
body: JSON.stringify({ userId: "admin", password: TEST_ADMIN_PASSWORD }),
});
expect(login.status).toBe(200);
expect(login.headers.get("set-cookie")).not.toContain("Secure");
// With the deployment opting in, the same header is honored.
const trusting = await createTestApp({ config: { trustProxy: true } });
try {
const res = await trusting.app.request("/api/auth/login", {
method: "POST",
headers: { "content-type": "application/json", "x-forwarded-proto": "https" },
body: JSON.stringify({ userId: "admin", password: TEST_ADMIN_PASSWORD }),
});
expect(res.status).toBe(200);
expect(res.headers.get("set-cookie")).toContain("Secure");
} finally {
await trusting.cleanup();
}
});
it("write requests reject non-JSON Content-Type (CSRF defense)", async () => {
const res = await t.app.request("/api/auth/login", {
method: "POST",
headers: { "content-type": "application/x-www-form-urlencoded" },
body: "userId=a&password=b",
});
expect(res.status).toBe(415);
});
it("seedAdmin rejects an override below the password policy before creating the account", async () => {
const root = await makeTempRoot();
const deps = flattenForTests(
await bootAppDeps(
{ ...testConfig(root), seedAdminPassword: "x" },
replacementsFor({ log: () => {} }),
),
);
try {
await expect(deps.authService.seedAdmin()).rejects.toThrow(/at least 8 characters/);
// Rejected before any insert: no half-created privileged account to retry around.
expect(deps.db.prepare("SELECT COUNT(*) AS n FROM users").get()?.n).toBe(0);
} finally {
deps.channels.dispose();
deps.db.close();
await fs.rm(root, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 });
}
});
it("throttles login failures per username with exponential backoff and resets on success", async () => {
let clock = Date.parse("2026-08-03T00:00:00Z");
const fresh = await createTestApp({ now: () => new Date(clock) });
try {
const attempt = (password: string) =>
fresh.app.request("/api/auth/login", {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({ userId: "admin", password }),
});
// Five free failures, and the sixth still reaches verification (backoff starts after it).
for (let i = 0; i < 6; i++) expect((await attempt("wrong-password")).status).toBe(401);
// Inside the 1s window: rejected without touching credentials — even the CORRECT password.
const throttled = await attempt("wrong-password");
expect(throttled.status).toBe(429);
const body = (await throttled.json()) as { error: { code: string } };
expect(body.error.code).toBe("too_many_attempts");
expect((await attempt(TEST_ADMIN_PASSWORD)).status).toBe(429);
// Past the window, the correct password signs in and clears the counter…
clock += 1100;
await loginUser(fresh.app, "admin", TEST_ADMIN_PASSWORD);
// …so the next failure is an ordinary 401 again, not a 429.
expect((await attempt("wrong-password")).status).toBe(401);
} finally {
await fresh.cleanup();
}
});
it("throttles unknown usernames identically (no account-existence oracle)", async () => {
let clock = Date.parse("2026-08-03T00:00:00Z");
const fresh = await createTestApp({ now: () => new Date(clock) });
try {
const attempt = () =>
fresh.app.request("/api/auth/login", {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({ userId: "ghost", password: "whatever-123" }),
});
for (let i = 0; i < 6; i++) expect((await attempt()).status).toBe(401);
expect((await attempt()).status).toBe(429);
// The window expires on the same schedule as for real accounts.
clock += 1100;
expect((await attempt()).status).toBe(401);
} finally {
await fresh.cleanup();
}
});
it("answers an unknown username exactly as it answers a wrong password", async () => {
await provisionUser(t.app, "carol");
// An account whose stored hash cannot be checked is no different either.
await provisionUser(t.app, "grace");
t.deps.db.prepare("UPDATE users SET password_hash = ? WHERE user_id = ?").run("", "grace");
const attempt = async (userId: string, password: string) => {
const res = await t.app.request("/api/auth/login", {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({ userId, password }),
});
return {
status: res.status,
headers: Object.fromEntries(res.headers),
body: await res.text(),
};
};
const wrongPassword = await attempt("carol", "wrong-password");
expect(wrongPassword.status).toBe(401);
expect(JSON.parse(wrongPassword.body)).toEqual({
error: { code: "invalid_credentials", message: "Incorrect username or password." },
});
expect(wrongPassword.headers["set-cookie"]).toBeUndefined();
expect(await attempt("nobody", "wrong-password")).toEqual(wrongPassword);
expect(await attempt("grace", "password-123")).toEqual(wrongPassword);
});
it("checks an unknown username against a dummy hash made once, by the server's own hasher", async () => {
const root = await makeTempRoot();
const hashed: string[] = [];
const hasher = {
async hash(password: string): Promise<string> {
const stored = await hashPassword(password, 2);
hashed.push(stored);
return stored;
},
};
const deps = flattenForTests(
await bootAppDeps(testConfig(root), [
...replacementsFor({ log: () => {} }),
[ScryptHasher, hasher],
]),
);
const invalid = { status: 401, code: "invalid_credentials" };
try {
await deps.authService.seedAdmin();
expect(hashed).toHaveLength(1);
// A wrong password on a real account is checked against that account's hash: no dummy.
await expect(deps.authService.login("admin", "wrong-password")).rejects.toMatchObject(
invalid,
);
expect(hashed).toHaveLength(1);
// The first unknown username makes the dummy, and every later one reuses it.
await expect(deps.authService.login("ghost", "whatever-123")).rejects.toMatchObject(invalid);
expect(hashed).toHaveLength(2);
await expect(deps.authService.login("phantom", "whatever-123")).rejects.toMatchObject(
invalid,
);
expect(hashed).toHaveLength(2);
} finally {
deps.hmr.dispose();
deps.channels.dispose();
deps.db.close();
await fs.rm(root, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 });
}
});
it("adminPasswordIs verifies the pin against the hash, not the config", async () => {
// Sole consumer is the startup notice gate: a pinned seed normally silences the
// first-login link, but an offline reset makes the pin stale — the gate must notice.
expect(await t.deps.authService.adminPasswordIs(TEST_ADMIN_PASSWORD)).toBe(true);
expect(await t.deps.authService.adminPasswordIs("not-the-password")).toBe(false);
});
it("generateInitialAdminPassword is 24 base64url characters, and never repeats", () => {
const seen = new Set<string>();
for (let i = 0; i < 64; i++) {
const password = generateInitialAdminPassword();
expect(password).toMatch(/^[A-Za-z0-9_-]{24}$/);
seen.add(password);
}
// Drawn from randomBytes, not from a small printable space that a login endpoint could
// be walked through.
expect(seen.size).toBe(64);
});
it("starts preferences empty, and merges each PUT without clobbering other writers", async () => {
const { cookie } = await provisionUser(t.app, "fred");
const api = apiClient(t.app, cookie);
const prefs = async () =>
((await (await api.get("/api/me/prefs")).json()) as { prefs: unknown }).prefs;
expect(await prefs()).toEqual({});
// Two independent writers: switching Project writes lastProjectId, onboarding writes
// credentialGuideSeen. The second write must not erase the first's field (a full replace
// would drop lastProjectId and bring onboarding back again and again).
await api.put("/api/me/prefs", { lastProjectId: "p-1" });
await api.put("/api/me/prefs", { credentialGuideSeen: true });
expect(await prefs()).toEqual({ lastProjectId: "p-1", credentialGuideSeen: true });
await api.put("/api/me/prefs", { lastProjectId: "p-2" });
expect(await prefs()).toEqual({ lastProjectId: "p-2", credentialGuideSeen: true });
});
});