A local-first multi-agent app development platform, built on PenguinHarness
/**
* Auth service: admin seeding / login / logout / password change / session validation.
*
* No open registration: an empty users table seeds `admin` with a random password hashed and
* discarded unseen, claimed through the first-login link; every other user is created by an
* admin. Sessions are rows in auth_sessions (cookie holds the token, the row its sha256), so
* they outlive a restart and renew in place.
*/
import { randomBytes } from "node:crypto";
import { tokensEqual } from "./api-token.js";
import type { UserInfo } from "../api/types.js";
import { HttpError } from "../http/errors.js";
import type { UserRow } from "../db/repos/users.js";
import { sessionTokenHash } from "../db/repos/auth-sessions.js";
import type { SessionViaValue, AuthSessionsRepo } from "../db/repos/auth-sessions.js";
import type { AuthRuntimeState } from "./runtime-state.js";
import { verifyAccountPassword, verifyPassword } from "./password.js";
import type { PasswordHasher } from "./password.js";
import { Component, Use, Interface } from "@adelie/core/kernel";
import type { AuthState, Clock, Config } from "../hmr/capabilities.js";
import type { Auth, AuthSessions, Users } from "../mechanisms/identity.js";
export const MIN_PASSWORD_LENGTH = 8;
/** Built-in admin user_id. */
export const ADMIN_USER_ID = "admin";
/**
* Login throttling, per userId. After LOGIN_FREE_ATTEMPTS failures each attempt waits an
* exponentially growing delay (1s doubling to a 60s cap), settling at a guess per minute.
* Kept for nonexistent userIds too, so it is not an account-existence oracle — and neither is
* the time a failure takes: a nonexistent userId is checked against a dummy hash (loginDummyHash).
* Deliberately NOT covered: a concurrent burst before the first failure lands, and guesses
* spread across many accounts.
*/
const LOGIN_FREE_ATTEMPTS = 5;
const LOGIN_BACKOFF_START_MS = 1000;
const LOGIN_BACKOFF_CAP_MS = 60_000;
/** Failure entries idle longer than this are swept (bounds the map; far above the cap). */
const LOGIN_FAILURE_IDLE_MS = 15 * 60_000;
/** Characters of base64url in a seeded password — 18 random bytes, 144 bits. */
const SEED_PASSWORD_CHARS = 24;
/**
* Never read or typed — hashed at once and discarded — which is what lets it be long enough
* that the login endpoint, reachable the moment the account exists, has no search space.
*/
export function generateInitialAdminPassword(): string {
return randomBytes(SEED_PASSWORD_CHARS).toString("base64url").slice(0, SEED_PASSWORD_CHARS);
}
/**
* "desktop" and "setup" may set a password without the old one (theirs is random and was never
* shown); desktop-only routes open to "desktop" alone. "token" is the local API token's Bearer
* header — per request, never a stored row. Anything else reads as "password".
*/
export type SessionVia = "password" | "desktop" | "setup" | "token";
/** Row -> DTO. The three optional profile/sign-in columns are omitted rather than sent as null when unset. */
export function toUserInfo(row: UserRow): UserInfo {
return {
userId: row.userId,
isAdmin: row.isAdmin,
passwordIsInitial: row.passwordIsInitial,
...(row.displayName !== null ? { displayName: row.displayName } : {}),
...(row.avatar !== null ? { avatar: row.avatar } : {}),
...(row.lastLoginAt !== null ? { lastLoginAt: row.lastLoginAt } : {}),
createdAt: row.createdAt,
};
}
@Component()
export class AuthService implements Auth {
@Use() private readonly users!: Users;
@Use() private readonly authSessions!: AuthSessions;
/**
* Process-scoped auth values (runtime-state.ts). Held by the RUNTIME so the link a boot
* printed survives a platform push; everything else about auth is rebuilt with the App.
*/
@Use() private readonly state!: AuthState;
/** Provisions the initial Project at signup — declared at the consumer, below. */
@Use() private readonly provisioner!: InitialProjectProvisioner;
@Use() private readonly config!: Config;
@Use() private readonly clock!: Clock;
@Use() private readonly hasher!: PasswordHasher;
/** Session lifetime, for the cookie that must expire WITH the session, not before it. */
get sessionTtlMs(): number {
return this.config.authSessionTtlMs;
}
private get sessionRenewMs(): number {
return this.config.authSessionRenewMs;
}
/** Fixed initial password for the seeded admin; null generates a random one at seed time. */
private get seedAdminPassword(): string | null {
return this.config.seedAdminPassword;
}
setup(): void {
this.authSessions.deleteExpired(this.clock.now().toISOString());
}
/**
* Null once the server is claimed, so the only setup session that exists is a printed one.
* On demand rather than in the constructor: seedAdmin() runs after it, so "claimed?" has no
* answer there. A cached link whose row is gone is re-minted, not handed out dead.
*/
mintFirstLogin(): string | null {
if (!this.adminPasswordIsInitial()) return null;
if (
this.state.firstLoginToken !== null &&
this.authenticateWithMeta(this.state.firstLoginToken) === null
) {
this.state.firstLoginToken = null;
}
this.state.firstLoginToken ??= this.issueSession(ADMIN_USER_ID, "setup");
return this.state.firstLoginToken;
}
/**
* For the startup notice's pinned-seed gate (index.ts): a pin usually means the operator
* knows the password, but an offline reset makes it stale, and the gate must see through
* that or the rescue link stays suppressed.
*/
async adminPasswordIs(password: string): Promise<boolean> {
const row = this.users.findById(ADMIN_USER_ID);
return row !== null && (await verifyPassword(password, row.passwordHash));
}
/**
* Startup seeding (idempotent): creates the built-in admin and adopts default_project when
* the users table is empty; if the initial Project fails, the user row is rolled back and
* the server retries on next startup.
*/
async seedAdmin(): Promise<void> {
if (this.users.count() > 0) return;
const password = this.seedAdminPassword ?? generateInitialAdminPassword();
// A pinned override must meet the same policy as every other password — rejected before
// any insert, so a configuration typo cannot create a trivially weak privileged account.
if (password.length < MIN_PASSWORD_LENGTH) {
throw new Error(
`ADELIE_SEED_ADMIN_PASSWORD must be at least ${MIN_PASSWORD_LENGTH} characters.`,
);
}
const user: UserRow = {
userId: ADMIN_USER_ID,
passwordHash: await this.hasher.hash(password),
isAdmin: true,
passwordIsInitial: true,
displayName: null,
avatar: null,
lastLoginAt: null,
createdAt: this.clock.now().toISOString(),
};
this.users.insert(user);
try {
await this.provisioner.provisionInitialProject(user, true);
} catch (err) {
this.users.delete(user.userId);
throw err;
}
}
/**
* Compared against the printed value, not merely verified: a cookie made out of ANY valid
* token would let one person hand another a link into the sender's account. Not single-use,
* because a prefetching browser would burn it before its reader clicked.
*/
redeemFirstLogin(given: string): string | null {
const expected = this.state.firstLoginToken;
if (expected === null || given === "" || !tokensEqual(given, expected)) return null;
return this.authenticateWithMeta(expected) === null ? null : expected;
}
/** Whether the built-in admin still runs on its initial password (gates the first-login link). */
adminPasswordIsInitial(): boolean {
return this.users.findById(ADMIN_USER_ID)?.passwordIsInitial === true;
}
/** Consecutive login failures per userId (see the throttling comment on the constants). */
private readonly loginFailures = new Map<string, { failures: number; lastFailureAt: number }>();
/** Cache for loginDummyHash. */
private dummyHash: string | null = null;
/**
* The hash a sign-in with no account to check is verified against (verifyAccountPassword), so
* it costs what a wrong password costs. Made by this server's own hasher, hence at the cost its
* real hashes carry, from a random password nobody holds; computed on the first such sign-in
* and kept.
*/
private async loginDummyHash(): Promise<string> {
this.dummyHash ??= await this.hasher.hash(randomBytes(18).toString("base64url"));
return this.dummyHash;
}
/** The wait imposed after `failures` consecutive failures (0 while within the free attempts). */
private loginDelayMs(failures: number): number {
const excess = failures - LOGIN_FREE_ATTEMPTS;
if (excess <= 0) return 0;
return Math.min(LOGIN_BACKOFF_START_MS * 2 ** (excess - 1), LOGIN_BACKOFF_CAP_MS);
}
async login(userId: string, password: string): Promise<{ user: UserInfo; token: string }> {
const nowMs = this.clock.now().getTime();
for (const [key, entry] of this.loginFailures) {
if (nowMs - entry.lastFailureAt > LOGIN_FAILURE_IDLE_MS) this.loginFailures.delete(key);
}
const failed = this.loginFailures.get(userId);
if (failed) {
const readyAt = failed.lastFailureAt + this.loginDelayMs(failed.failures);
if (nowMs < readyAt) {
throw new HttpError(
429,
"too_many_attempts",
`Too many failed sign-in attempts. Try again in ${Math.ceil((readyAt - nowMs) / 1000)}s.`,
);
}
}
const row = this.users.findById(userId);
// A missing account, or one whose hash cannot be checked, still costs one scrypt
// derivation, and fails with the same 401 as a wrong password.
const ok = await verifyAccountPassword(password, row?.passwordHash ?? null, () =>
this.loginDummyHash(),
);
if (!row || !ok) {
this.loginFailures.set(userId, {
failures: (failed?.failures ?? 0) + 1,
lastFailureAt: this.clock.now().getTime(),
});
throw new HttpError(401, "invalid_credentials", "Incorrect username or password.");
}
this.loginFailures.delete(userId);
this.authSessions.deleteExpired(this.clock.now().toISOString());
// The account's last sign-in, stamped on the one path that verified a password. Written
// before the DTO is built, so the response's own user carries the value this call set.
const at = this.clock.now().toISOString();
this.users.touchLastLogin(row.userId, at);
return {
user: toUserInfo({ ...row, lastLoginAt: at }),
token: this.issueSession(row.userId, "password"),
};
}
/**
* Whether a user is an admin, by id — for a caller that has a user's NAME rather than an
* authenticated request: the terminal relay reads the owner out of a pty reference the
* runtime has already matched against the signed-in user (machines/terminal-relay.ts), and
* what is left to decide is whether that user may reach machines at all. Unknown users are
* not admins.
*/
isAdmin(userId: string): boolean {
return this.users.findById(userId)?.isAdmin === true;
}
/**
* Desktop-mode sign-in: an admin session with no password check — the claim route already
* redeemed the shell's one-shot token, which is the credential here. Throws only on a
* broken deployment (seeding runs before the route exists).
*/
loginDesktop(): { user: UserInfo; token: string } {
const row = this.users.findById(ADMIN_USER_ID);
if (!row) {
throw new HttpError(500, "internal", "Built-in admin has not been seeded.");
}
return { user: toUserInfo(row), token: this.issueSession(row.userId, "desktop") };
}
/** Self password change (user settings): validates the old password first; the current session stays valid. */
async changePassword(userId: string, oldPassword: string, newPassword: string): Promise<void> {
const row = this.users.findById(userId);
if (!row || !(await verifyPassword(oldPassword, row.passwordHash))) {
throw new HttpError(400, "password_mismatch", "Current password is incorrect.");
}
await this.setPassword(userId, newPassword);
}
/** No old-password check; the me route gates which sessions may call this. */
async setInitialPassword(userId: string, newPassword: string): Promise<void> {
await this.setPassword(userId, newPassword);
}
/**
* Validation comes FIRST, so a rejected password leaves the first-login link alive: burning
* it on a typo would strand the claimer until a restart.
*/
private async setPassword(userId: string, newPassword: string): Promise<void> {
if (newPassword.length < MIN_PASSWORD_LENGTH) {
throw new HttpError(400, "invalid_password", "Password must be at least 8 characters.");
}
this.users.updatePassword(userId, await this.hasher.hash(newPassword), false);
// A successful set proves at least what the successful login that resets the counter
// proves (the old password, or a desktop/setup session), so it resets it too. Without
// this, anyone spamming the login endpoint holds the backoff window open, and the sign-in
// that follows a first-login claim (routes/me.ts) would 429 AFTER the password committed —
// reporting failure for a change that took, with the claimer's setup session already gone.
this.loginFailures.delete(userId);
// EVERY first-login session for this account, not just the link this process printed: an
// earlier boot's link can still be live in a terminal scrollback, and a `setup` session is
// allowed to change the password without knowing the old one — so one left behind is an
// account takeover waiting to happen.
if (userId === ADMIN_USER_ID) {
this.authSessions.deleteByUserAndVia(userId, "setup");
this.state.firstLoginToken = null;
}
}
/** Ends a session: the row is the session, so logout deletes it. Unknown token is a no-op. */
logout(token: string): void {
this.authSessions.delete(sessionTokenHash(token));
}
/**
* The current boot's local API token (what control-env injection hands to tool
* subprocesses); null when none was minted. It lives on the runtime state, not on this
* service: the token was written to `<root>/api-token` by the process, so it must
* outlive the App a push replaces (auth/runtime-state.ts).
*/
localApiToken(): string | null {
return this.state.apiToken;
}
/**
* Validates a Bearer token against the boot's local API token (constant-time compare):
* a match authenticates as the built-in admin — holding the token proves filesystem
* access to the data root, which is admin authority (see auth/api-token.ts). Returns
* null on mismatch, when no token was minted, or when the admin row is missing.
*/
authenticateApiToken(token: string): { user: UserRow; via: SessionVia } | null {
const apiToken = this.state.apiToken;
if (apiToken === null || token.length === 0) return null;
if (!tokensEqual(token, apiToken)) return null;
const user = this.users.findById(ADMIN_USER_ID);
return user === null ? null : { user, via: "token" };
}
/**
* Validates the cookie token. Sliding renewal tops the expiry up IN PLACE, so the cookie
* value never changes and there is no second identity to revoke. Only a session whose own
* span reaches the renewal window slides — a one-hour minted token must expire at its hour,
* not stretch by being used.
*/
authenticateWithMeta(token: string): { user: UserRow; via: SessionVia; renewed: boolean } | null {
const tokenHash = sessionTokenHash(token);
const session = this.authSessions.findByTokenHash(tokenHash);
if (!session) return null;
const now = this.clock.now();
const expiresAt = Date.parse(session.expiresAt);
if (expiresAt <= now.getTime()) {
this.authSessions.delete(tokenHash);
return null;
}
const user = this.users.findById(session.userId);
if (!user) return null;
const renewable = expiresAt - Date.parse(session.createdAt) >= this.sessionRenewMs;
let renewed = false;
if (renewable && expiresAt - now.getTime() < this.sessionRenewMs) {
this.authSessions.touch(tokenHash, new Date(now.getTime() + this.sessionTtlMs).toISOString());
renewed = true;
}
const via: SessionVia =
session.via === "desktop" ? "desktop" : session.via === "setup" ? "setup" : "password";
return { user, via, renewed };
}
/**
* Whether the session behind a cookie token still exists and has not expired — the same
* two facts {@link authenticateWithMeta} establishes, without its sliding renewal or its
* user lookup. A connection that outlives the request that opened it has to re-ask
* periodically (the SSE heartbeat does, once per beat), and asking through the renewing
* path would top the expiry up every time: a window nobody has touched since last week
* would stay signed in purely because it is still connected.
*/
sessionIsLive(token: string): boolean {
const session = this.authSessions.findByTokenHash(sessionTokenHash(token));
if (!session) return false;
return Date.parse(session.expiresAt) > this.clock.now().getTime();
}
private issueSession(userId: string, via: SessionViaValue): string {
return this.authSessions.issue({
userId,
via,
now: this.clock.now(),
ttlMs: this.sessionTtlMs,
}).token;
}
}
/** What signing a new user in needs of project administration — declared at the consumer. */
@Interface()
export abstract class InitialProjectProvisioner {
abstract provisionInitialProject(user: UserRow, isAdmin: boolean): Promise<void>;
}