A local-first multi-agent app development platform, built on PenguinHarness
/**
* The first-login link: the claim route's proof for a server nobody has signed in to yet
* (auth/service.ts, routes/auth.ts). The desktop shell's token, the route's other proof, is
* covered in desktop.test.ts.
*
* The link CARRIES a session rather than a secret redeemed for one. That buys simplicity and
* costs a hazard the desktop token does not have: an endpoint that made a cookie out of any
* valid token would let one person sign another into their own account. So the printed value
* is compared, not merely verified, and it stops working the moment a password exists.
*
* - Given an unclaimed server, the printed link signs the browser in with a `setup` session
* that may set a password without an old one; once one is set, the link is refused.
* - Any token but the printed one is refused exactly as a spent link is.
* - The link is not single-use before the claim: opening it twice lands in one session.
* - A password set through the ordinary change-password door (a pinned seed) ends the link.
* - Claiming hands the claimer a working password session back, and the link's own cookie dies.
* - A setup session left over from an earlier boot dies with the claim too.
* - A rejected password keeps the link alive.
* - The claimer is signed in even while a guessing spree has the login throttled.
* - A link older than the session lifetime is re-minted rather than handed out dead.
* - A claimed server mints no link, so a restart offers none.
*/
import path from "node:path";
import { afterEach, beforeEach, describe, expect, it } from "vitest";
import { SESSION_COOKIE } from "../src/auth/middleware.js";
import { apiClient, cookieFrom, createTestApp, loginAdmin, makeTempRoot } from "./helpers.js";
import type { TestApp } from "./helpers.js";
describe("the first-login link", () => {
let t: TestApp;
/** The session the server would print — read from it, not injected, as a browser would get it. */
let link: string;
beforeEach(async () => {
t = await createTestApp();
link = t.deps.authService.mintFirstLogin()!;
});
afterEach(async () => {
await t.cleanup();
});
const redeem = (token: string) =>
t.app.request(`/api/auth/claim?token=${encodeURIComponent(token)}`, {
redirect: "manual",
});
/**
* What a browser gets for a link that no longer works: back to the login page, carrying the
* advice this deployment can give (no shell here, so a new link comes from whoever runs the
* server), and no session.
*/
function expectRefusal(res: Response): void {
expect(res.status).toBe(302);
expect(res.headers.get("location")).toBe("/login?claimFailed=server");
expect(res.headers.get("set-cookie")).toBeNull();
}
it("claims an unclaimed server, with a session that may set a password but is not desktop", async () => {
const res = await redeem(link);
expect(res.status).toBe(302);
expect(res.headers.get("location")).toBe("/");
const cookie = cookieFrom(res);
const me = (await (await apiClient(t.app, cookie).get("/api/me")).json()) as {
user: { userId: string };
sessionVia: string;
};
expect(me.user.userId).toBe("admin");
// "setup", never "desktop": reading a link proves someone read a link, not that they own
// the machine the shell runs on.
expect(me.sessionVia).toBe("setup");
// The one allowance it carries — and the account's password is a random value nobody has
// seen, so there is nothing to put in an old-password field.
const set = await apiClient(t.app, cookie).put("/api/me/password", {
newPassword: "claimed-password-1",
});
expect(set.status).toBe(204);
expect(t.deps.authService.adminPasswordIsInitial()).toBe(false);
// Claimed: a console scrollback is not a way in.
expectRefusal(await redeem(link));
});
it("refuses any token but the printed one, and says nothing about which it got", async () => {
// Otherwise this endpoint would make a cookie out of ANY valid token, and a link could
// sign its recipient into the SENDER's account. The two refusals are byte-identical, so
// a caller cannot tell "wrong token" from "already claimed".
const someoneElse = (await loginAdmin(t.app)).cookie.split("=").slice(1).join("=");
const other = await redeem(someoneElse);
const wrong = await redeem("not-the-token");
expectRefusal(other);
expectRefusal(wrong);
expect(other.headers.get("location")).toBe(wrong.headers.get("location"));
});
/**
* Not single-use, deliberately: a mail client or a browser that prefetches the link would
* spend a one-shot token before its reader ever clicked, and the window it stays open is
* exactly the window in which the account protects nothing yet. Opening it twice yields the
* same session rather than two, since the link IS the session.
*/
it("can be opened more than once, and both pages land in one session", async () => {
const a = await redeem(link);
const b = await redeem(link);
expect([a.status, b.status]).toEqual([302, 302]);
const cookieOf = (r: Response) => cookieFrom(r);
expect(cookieOf(a)).toBe(cookieOf(b));
expect(cookieOf(a)).not.toBe("");
// Still the same link afterwards: redemption spends nothing.
expect(t.deps.authService.mintFirstLogin()).toBe(link);
});
/**
* The one reachable way to set a password WITHOUT going through setInitialPassword's
* revocation: a pinned seed (ADELIE_SEED_ADMIN_PASSWORD, which every test app has) makes
* the current password knowable, so the ordinary change-password door opens. The link must
* die there too — the invariant is "any password set on the admin ends the link", not "the
* door we expected ends it".
*/
it("dies when the admin sets a password through the ordinary door (pinned seed)", async () => {
const { cookie } = await loginAdmin(t.app);
await apiClient(t.app, cookie).put("/api/me/password", {
oldPassword: t.adminPassword,
newPassword: "chosen-password-1",
});
expect(t.deps.authService.redeemFirstLogin(link)).toBeNull();
expectRefusal(await redeem(link));
});
/**
* Claiming deletes the very session making the request, so the response has to carry a
* replacement or the browser's next call 401s and a brand-new user lands back on a login
* screen seconds after choosing their password. The replacement is an ordinary login with
* the password just set — the old cookie is still dead.
*/
it("hands the claimer a working session back, while the link's own cookie dies", async () => {
const res = await redeem(link);
const claimCookie = cookieFrom(res);
const set = await apiClient(t.app, claimCookie).put("/api/me/password", {
newPassword: "claimed-password-1",
});
expect(set.status).toBe(204);
const replacement = cookieFrom(set);
expect(replacement).toMatch(new RegExp(`^${SESSION_COOKIE}=.+`));
expect(replacement).not.toBe(claimCookie);
// The replacement works…
const me = await apiClient(t.app, replacement).get("/api/me");
expect(me.status).toBe(200);
// …as an ordinary password session, not a setup one that could re-set the password.
expect(((await me.json()) as { sessionVia: string }).sessionVia).toBe("password");
// …and the claimed link is dead.
expect((await apiClient(t.app, claimCookie).get("/api/me")).status).toBe(401);
});
/**
* Setting a password must end EVERY first-login session for the account, not just the link
* the current process printed. An earlier boot's link stays live in a terminal scrollback,
* and a `setup` session may change the password without knowing the old one — so one left
* behind is an account takeover, not merely an extra session.
*/
it("kills a setup session left over from an earlier boot", async () => {
const root = await makeTempRoot();
const config = { root, dbPath: path.join(root, "web.db"), seedAdminPassword: null };
const boot1 = await createTestApp({ config });
const linkA = boot1.deps.authService.mintFirstLogin()!;
await boot1.cleanup();
// Still unclaimed, so this boot prints its OWN link; both rows are live setup sessions.
const boot2 = await createTestApp({ config });
try {
const linkB = boot2.deps.authService.mintFirstLogin()!;
expect(linkB).not.toBe(linkA);
const set = await apiClient(boot2.app, `${SESSION_COOKIE}=${linkB}`).put("/api/me/password", {
newPassword: "claimed-password-1",
});
expect(set.status).toBe(204);
// The older link is dead too — not merely unable to set a password, but unauthenticated.
expect((await apiClient(boot2.app, `${SESSION_COOKIE}=${linkA}`).get("/api/me")).status).toBe(
401,
);
} finally {
await boot2.cleanup();
}
});
/**
* The revocation fires only after the password actually updates: a rejected attempt must
* leave the link alive, or a typo (or anyone poking the endpoint with a bad value) burns
* the only way in until a restart.
*/
it("keeps the link alive when the chosen password is rejected", async () => {
const res = await redeem(link);
const cookie = cookieFrom(res);
const short = await apiClient(t.app, cookie).put("/api/me/password", {
newPassword: "short",
});
expect(short.status).toBe(400);
// The same printed link still redeems — nothing was spent on the failure.
expect((await redeem(link)).status).toBe(302);
expect(t.deps.authService.mintFirstLogin()).toBe(link);
});
/**
* The claim ends with its own sign-in (routes/me.ts hands the claimer a replacement
* session), and that sign-in must not be blockable from outside: anyone who can reach the
* port can spam POST /api/auth/login with wrong guesses and hold the per-user backoff
* window open. A successful password set resets the counter — it proves at least what the
* successful login that already resets it proves — so the claimer lands signed in instead
* of 429ing AFTER the password committed, with the setup session already deleted.
*/
it("signs the claimer in even while a guessing spree has the login throttled", async () => {
const nowMs = Date.now();
const clocked = await createTestApp({ now: () => new Date(nowMs) });
try {
const clockedLink = clocked.deps.authService.mintFirstLogin()!;
const guess = () =>
clocked.app.request("/api/auth/login", {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({ userId: "admin", password: "not-the-password" }),
});
// Six wrong guesses arm the backoff; the frozen clock keeps its window open.
for (let i = 0; i < 6; i++) expect((await guess()).status).toBe(401);
expect((await guess()).status).toBe(429);
const res = await clocked.app.request(
`/api/auth/claim?token=${encodeURIComponent(clockedLink)}`,
{ redirect: "manual" },
);
const set = await apiClient(clocked.app, cookieFrom(res)).put("/api/me/password", {
newPassword: "claimed-password-1",
});
expect(set.status).toBe(204);
// The replacement session works: the claim was not spent on somebody else's 429.
expect((await apiClient(clocked.app, cookieFrom(set)).get("/api/me")).status).toBe(200);
} finally {
await clocked.cleanup();
}
});
/**
* An unclaimed server outliving the session TTL (30 days without anyone setting a
* password) must not keep handing out the same dead link: the cached token no longer
* authenticates, so minting re-rolls it.
*/
it("re-mints the link once the cached one has aged out", async () => {
let nowMs = Date.now();
const clocked = await createTestApp({
config: { seedAdminPassword: null },
now: () => new Date(nowMs),
});
try {
const first = clocked.deps.authService.mintFirstLogin()!;
nowMs += 31 * 24 * 60 * 60 * 1000;
const second = clocked.deps.authService.mintFirstLogin();
expect(second).not.toBeNull();
expect(second).not.toBe(first);
expect(clocked.deps.authService.redeemFirstLogin(second!)).toBe(second);
} finally {
await clocked.cleanup();
}
});
/**
* A claimed server that restarts must not end up holding a usable setup session. Revocation
* cannot be what prevents that — a restart's token is new, and nothing revoked a token that
* did not exist yet — so the server declines to mint one at all.
*/
it("mints nothing once the server has been claimed, so a restart has no link", async () => {
const root = await makeTempRoot();
const dbPath = path.join(root, "web.db");
const first = await createTestApp({ config: { dbPath, seedAdminPassword: null } });
const claim = await first.app.request(
`/api/auth/claim?token=${encodeURIComponent(first.deps.authService.mintFirstLogin()!)}`,
{ redirect: "manual" },
);
const cookie = cookieFrom(claim);
await apiClient(first.app, cookie).put("/api/me/password", {
newPassword: "claimed-password-1",
});
await first.cleanup();
// Same database, new process: a new signing key, and a new setup session with it.
const second = await createTestApp({ config: { dbPath, seedAdminPassword: null } });
try {
expect(second.deps.authService.adminPasswordIsInitial()).toBe(false);
expect(second.deps.authService.mintFirstLogin()).toBeNull();
// Nothing to match, so the endpoint refuses whatever is presented.
const res = await second.app.request("/api/auth/claim?token=anything", {
redirect: "manual",
});
expectRefusal(res);
} finally {
await second.cleanup();
}
});
});