@cordfuse/crosstalk 7.0.0-alpha.9 → 7.0.0-beta.1

package/src/auth/enforce.ts

@@ -0,0 +1,68 @@
+// API-level identity enforcement helpers for v2 endpoints.
+//
+// Per the v2 design, every orch action carries a `from:` / `alias` field
+// that names the user it's being performed AS. The authenticated user
+// (resolved by middleware.ts) MUST match this field — Alice can't post
+// as Bob, even if she has a valid token.
+//
+// Admins do NOT bypass this — admin status lets you create/delete users
+// and mint tokens for them, but it does NOT let you pose as them on the
+// orch channel. That's a deliberate design choice (anti-impersonation).
+//
+// Trust context: SERVICE — called per request after authenticate().
+//
+// References:
+//   V2-SYSTEM-AUTH-DESIGN.md § "Identity-bound tokens" — no impersonation
+//   V2-SYSTEM-AUTH-DESIGN.md § "Build plan" — Phase 7
+
+import type { User } from './users.js';
+import type { HttpResult, ErrorBody } from './handlers.js';
+
+export type EnforceOk = { ok: true };
+export type EnforceFail = HttpResult<ErrorBody> & { ok: false };
+export type EnforceResult = EnforceOk | EnforceFail;
+
+const FORBIDDEN = (msg: string): EnforceFail => ({
+  ok: false,
+  status: 403,
+  body: { error: msg },
+});
+
+/**
+ * Per v2 design, the user's `username` IS their orch alias. Requests
+ * that target a specific alias (orch send `from:`, claim release `by:`,
+ * etc.) MUST match the authenticated user. Admin status confers NO
+ * bypass — admins cannot pose as other users on orch.
+ *
+ * Returns `{ ok: true }` if the alias matches. Otherwise an EnforceFail
+ * the HTTP layer can pass through directly.
+ *
+ * Pass `requestedAlias = undefined` if the endpoint doesn't take an
+ * explicit alias — this returns ok and the handler should use
+ * `user.username` as the implicit alias.
+ */
+export function requireOwnAlias(user: User, requestedAlias: string | undefined): EnforceResult {
+  if (requestedAlias === undefined || requestedAlias === user.username) {
+    return { ok: true };
+  }
+  return FORBIDDEN(`alias '${requestedAlias}' does not belong to authenticated user '${user.username}'`);
+}
+
+/**
+ * Admin-gated endpoints (create/delete users, mint tokens for others,
+ * reset passphrases). Use this AFTER authenticate() succeeds.
+ */
+export function requireAdmin(user: User): EnforceResult {
+  if (user.admin) return { ok: true };
+  return FORBIDDEN('admin only');
+}
+
+/**
+ * Endpoints that allow either the user themselves OR an admin (e.g.,
+ * viewing tokens, rotating own passphrase). The targetUsername is the
+ * resource owner the request is acting on.
+ */
+export function requireSelfOrAdmin(user: User, targetUsername: string): EnforceResult {
+  if (user.username === targetUsername || user.admin) return { ok: true };
+  return FORBIDDEN(`access denied: not '${targetUsername}' and not admin`);
+}

package/src/auth/handlers.ts

@@ -0,0 +1,266 @@
+// /api/auth/login + /api/auth/logout endpoint logic.
+//
+// Framework-agnostic — handlers take parsed input + stores, return
+// { status, body } that the HTTP layer maps to its response shape. The
+// HTTP layer is responsible for: extracting the request body, calling
+// the handler, writing the status + JSON response.
+//
+// Trust context: SERVICE.
+//
+// References:
+//   V2-SYSTEM-AUTH-DESIGN.md § "Auth flow (v2 client side)" — server side
+//   V2-SYSTEM-AUTH-DESIGN.md § "Build plan" — Phase 7
+
+import type { UserStore, User, CreateUserInput } from './users.js';
+import { UserValidationError } from './users.js';
+import type { TokenStore, IdentityToken } from './tokens.js';
+
+export interface HttpResult<TBody = unknown> {
+  status: number;
+  body: TBody;
+}
+
+export interface LoginRequest {
+  username: unknown;
+  passphrase: unknown;
+  deviceName?: unknown;
+}
+
+export interface LoginResponseOk {
+  token: string;       // wire format: sas_<id>.<secret>
+  tokenName: string;
+  username: string;
+}
+
+export interface ErrorBody { error: string; }
+
+/**
+ * POST /api/auth/login
+ *
+ * Validates username + passphrase against the user store, mints a fresh
+ * identity-bound token, returns the wire-form plaintext (ONCE).
+ *
+ * Status codes:
+ *   400 — request body missing required fields or wrong types
+ *   401 — username unknown OR passphrase wrong (returned same way to
+ *         prevent username enumeration)
+ *   200 — { token, tokenName, username }
+ *
+ * Side effects: tokens.json gets one new row on success.
+ */
+export async function handleLogin(
+  input: LoginRequest,
+  userStore: UserStore,
+  tokenStore: TokenStore,
+): Promise<HttpResult<LoginResponseOk | ErrorBody>> {
+  if (typeof input.username !== 'string' || typeof input.passphrase !== 'string') {
+    return { status: 400, body: { error: 'username and passphrase required' } };
+  }
+  const username = input.username;
+  const passphrase = input.passphrase;
+  const deviceName = typeof input.deviceName === 'string' && input.deviceName.trim().length > 0
+    ? input.deviceName.trim()
+    : `${username} device`;
+
+  // Constant-time-ish: verifyPassphrase returns false for unknown users
+  // (no separate exists check that would leak existence via response time).
+  const ok = await userStore.verifyPassphrase(username, passphrase);
+  if (!ok) {
+    return { status: 401, body: { error: 'invalid credentials' } };
+  }
+
+  const minted = await tokenStore.mint({ username, name: deviceName });
+  return {
+    status: 200,
+    body: {
+      token: minted.plaintextSecret,
+      tokenName: minted.token.name,
+      username,
+    },
+  };
+}
+
+/**
+ * POST /api/auth/logout
+ *
+ * Revokes the bearer token the caller authenticated with. Must be called
+ * AFTER the auth middleware so we already have the validated token row.
+ * Idempotent — re-logout on an already-revoked token still returns 200
+ * (the token can't be reused anyway).
+ *
+ * Note: revoke is per-token, not per-user. To log out everywhere, the
+ * caller iterates list({ username }) + revoke individually, or calls the
+ * admin revokeAllForUser path.
+ */
+export async function handleLogout(
+  callerToken: IdentityToken,
+  tokenStore: TokenStore,
+): Promise<HttpResult<{ ok: true } | ErrorBody>> {
+  await tokenStore.revoke(callerToken.tokenId);
+  return { status: 200, body: { ok: true } };
+}
+
+// ── Account self-service handlers ──────────────────────────────────────────
+
+export interface ProfileUpdateRequest { name: unknown; }
+
+export async function handleProfileUpdate(
+  input: ProfileUpdateRequest,
+  caller: User,
+  userStore: UserStore,
+): Promise<HttpResult<{ ok: true; user: User } | ErrorBody>> {
+  if (typeof input.name !== 'string' || input.name.trim().length === 0) {
+    return { status: 400, body: { error: 'name required' } };
+  }
+  try {
+    await userStore.updateName(caller.username, input.name);
+  } catch (err) {
+    return wrapValidation(err);
+  }
+  const updated = await userStore.getUser(caller.username);
+  return { status: 200, body: { ok: true, user: updated! } };
+}
+
+export interface PassphraseChangeRequest {
+  oldPassphrase: unknown;
+  newPassphrase: unknown;
+}
+
+/**
+ * Change own passphrase. Verifies the old one (no admin bypass) — even
+ * the user themselves must prove the current one. Revokes ALL of the
+ * caller's tokens on success so any other devices have to re-login,
+ * which is the expected behavior after a passphrase rotation.
+ */
+export async function handlePassphraseChange(
+  input: PassphraseChangeRequest,
+  caller: User,
+  userStore: UserStore,
+  tokenStore: TokenStore,
+): Promise<HttpResult<{ ok: true; revokedTokens: number } | ErrorBody>> {
+  if (typeof input.oldPassphrase !== 'string' || typeof input.newPassphrase !== 'string') {
+    return { status: 400, body: { error: 'oldPassphrase and newPassphrase required' } };
+  }
+  const ok = await userStore.verifyPassphrase(caller.username, input.oldPassphrase);
+  if (!ok) return { status: 401, body: { error: 'current passphrase incorrect' } };
+  try {
+    await userStore.setPassphrase(caller.username, input.newPassphrase);
+  } catch (err) {
+    return wrapValidation(err);
+  }
+  const revoked = await tokenStore.revokeAllForUser(caller.username);
+  return { status: 200, body: { ok: true, revokedTokens: revoked } };
+}
+
+/**
+ * Revoke a token by id. Caller must own the token OR be admin. Returns
+ * 404 if no such token; 403 if owner mismatch + caller not admin.
+ */
+export async function handleRevokeToken(
+  tokenId: string,
+  caller: User,
+  tokenStore: TokenStore,
+): Promise<HttpResult<{ ok: true } | ErrorBody>> {
+  const row = await tokenStore.get(tokenId);
+  if (!row) return { status: 404, body: { error: 'token not found' } };
+  if (row.username !== caller.username && !caller.admin) {
+    return { status: 403, body: { error: 'cannot revoke tokens owned by another user' } };
+  }
+  await tokenStore.revoke(tokenId);
+  return { status: 200, body: { ok: true } };
+}
+
+// ── Admin user CRUD ────────────────────────────────────────────────────────
+
+export interface AdminCreateUserRequest {
+  username: unknown;
+  name: unknown;
+  passphrase: unknown;
+  admin?: unknown;
+}
+
+export async function handleAdminCreateUser(
+  input: AdminCreateUserRequest,
+  userStore: UserStore,
+): Promise<HttpResult<{ ok: true; user: User } | ErrorBody>> {
+  if (typeof input.username !== 'string' || typeof input.name !== 'string' || typeof input.passphrase !== 'string') {
+    return { status: 400, body: { error: 'username, name, passphrase required' } };
+  }
+  const payload: CreateUserInput = {
+    username: input.username,
+    name: input.name,
+    passphrase: input.passphrase,
+    admin: input.admin === true,
+  };
+  try {
+    const user = await userStore.createUser(payload);
+    return { status: 200, body: { ok: true, user } };
+  } catch (err) {
+    return wrapValidation(err);
+  }
+}
+
+/**
+ * Delete a user. Refuses to delete the caller (no foot-shooting) and the
+ * last admin (no lockout). Cascades to token revocation.
+ */
+export async function handleAdminDeleteUser(
+  targetUsername: string,
+  caller: User,
+  userStore: UserStore,
+  tokenStore: TokenStore,
+): Promise<HttpResult<{ ok: true; revokedTokens: number } | ErrorBody>> {
+  if (targetUsername === caller.username) {
+    return { status: 400, body: { error: 'cannot delete your own account' } };
+  }
+  const target = await userStore.getUser(targetUsername);
+  if (!target) return { status: 404, body: { error: 'user not found' } };
+  if (target.admin) {
+    const all = await userStore.listUsers();
+    const adminCount = all.filter(u => u.admin).length;
+    if (adminCount <= 1) {
+      return { status: 400, body: { error: 'cannot delete the last admin' } };
+    }
+  }
+  try {
+    await userStore.deleteUser(targetUsername);
+  } catch (err) {
+    return wrapValidation(err);
+  }
+  const revoked = await tokenStore.revokeAllForUser(targetUsername);
+  return { status: 200, body: { ok: true, revokedTokens: revoked } };
+}
+
+export interface AdminResetPassphraseRequest { newPassphrase: unknown; }
+
+/**
+ * Admin override — set another user's passphrase WITHOUT proving the old
+ * one. Revokes all of the target's tokens so they have to re-login with
+ * the new passphrase.
+ */
+export async function handleAdminResetPassphrase(
+  targetUsername: string,
+  input: AdminResetPassphraseRequest,
+  userStore: UserStore,
+  tokenStore: TokenStore,
+): Promise<HttpResult<{ ok: true; revokedTokens: number } | ErrorBody>> {
+  if (typeof input.newPassphrase !== 'string') {
+    return { status: 400, body: { error: 'newPassphrase required' } };
+  }
+  const target = await userStore.getUser(targetUsername);
+  if (!target) return { status: 404, body: { error: 'user not found' } };
+  try {
+    await userStore.setPassphrase(targetUsername, input.newPassphrase);
+  } catch (err) {
+    return wrapValidation(err);
+  }
+  const revoked = await tokenStore.revokeAllForUser(targetUsername);
+  return { status: 200, body: { ok: true, revokedTokens: revoked } };
+}
+
+function wrapValidation(err: unknown): HttpResult<ErrorBody> {
+  if (err instanceof UserValidationError) {
+    return { status: 400, body: { error: err.message } };
+  }
+  return { status: 500, body: { error: `internal: ${(err as Error).message}` } };
+}

package/src/auth/middleware.ts

@@ -0,0 +1,132 @@
+// HTTP-framework-agnostic auth middleware for v2.
+//
+// Inputs are parsed primitives (bearer token string) so the same logic
+// works behind raw http, fastify, hono, koa, etc. Outputs are structured
+// results the HTTP layer maps to its response shape.
+//
+// Trust context: SERVICE.
+//
+// References:
+//   V2-SYSTEM-AUTH-DESIGN.md § "Per-request auth gate"
+//   V2-SYSTEM-AUTH-DESIGN.md § "Build plan" — Phase 7
+
+import type { TokenStore, IdentityToken } from './tokens.js';
+import type { UserStore, User } from './users.js';
+
+export interface AuthContext {
+  tokenStore: TokenStore;
+  userStore: UserStore;
+}
+
+export interface AuthSuccess {
+  ok: true;
+  user: User;
+  token: IdentityToken;
+}
+
+export interface AuthFailure {
+  ok: false;
+  status: number;
+  body: { error: string };
+}
+
+export type AuthResult = AuthSuccess | AuthFailure;
+
+const UNAUTHORIZED = (msg: string): AuthFailure => ({
+  ok: false,
+  status: 401,
+  body: { error: msg },
+});
+
+/**
+ * Extract `Bearer <token>` from an Authorization header value. Returns
+ * undefined if the header is missing or not in bearer form. Tolerant of
+ * case ('bearer', 'Bearer', 'BEARER') and extra whitespace.
+ */
+export function extractBearer(authorizationHeader: string | undefined): string | undefined {
+  if (!authorizationHeader || typeof authorizationHeader !== 'string') return undefined;
+  const match = authorizationHeader.match(/^\s*bearer\s+(.+?)\s*$/i);
+  return match ? match[1] : undefined;
+}
+
+/**
+ * Authenticate a request given its bearer token. Validates the token,
+ * resolves the owning user, returns both. Failure modes:
+ *   - no bearer → 401 missing
+ *   - malformed wire / bad signature / not found → 401 invalid
+ *   - expired → 401 expired
+ *   - user behind token has been deleted → 401 stale + best-effort revoke
+ *
+ * Stale-token cleanup: if a token validates but its owning user is gone,
+ * the token row is orphaned (deleteUser doesn't reach into tokens to
+ * preserve store decoupling). We revoke it inline so the orphan doesn't
+ * linger; treat as 401.
+ */
+export async function authenticate(
+  bearerToken: string | undefined,
+  ctx: AuthContext,
+): Promise<AuthResult> {
+  if (!bearerToken) return UNAUTHORIZED('missing bearer token');
+
+  const validation = await ctx.tokenStore.validate(bearerToken);
+  if (!validation.ok || !validation.token) {
+    if (validation.reason === 'expired') return UNAUTHORIZED('token expired');
+    return UNAUTHORIZED('invalid token');
+  }
+
+  const user = await ctx.userStore.getUser(validation.token.username);
+  if (!user) {
+    void ctx.tokenStore.revoke(validation.token.tokenId);
+    return UNAUTHORIZED('token owner no longer exists');
+  }
+
+  return { ok: true, user, token: validation.token };
+}
+
+/**
+ * Convenience: pull the Authorization header off a Node http IncomingMessage
+ * (or any object with a headers map) and authenticate. Saves callers from
+ * doing the header-name dance themselves. Also falls back to the
+ * `crosstalk_session` cookie so browser sessions work without JS having to
+ * juggle Authorization on every request.
+ */
+export async function authenticateRequest(
+  req: { headers: Record<string, string | string[] | undefined> },
+  ctx: AuthContext,
+): Promise<AuthResult> {
+  const raw = req.headers['authorization'] ?? req.headers['Authorization'];
+  const header = Array.isArray(raw) ? raw[0] : raw;
+  const fromHeader = extractBearer(header);
+  if (fromHeader) return authenticate(fromHeader, ctx);
+
+  const cookieRaw = req.headers['cookie'];
+  const cookieHeader = Array.isArray(cookieRaw) ? cookieRaw.join('; ') : cookieRaw;
+  const fromCookie = extractSessionCookie(cookieHeader);
+  return authenticate(fromCookie, ctx);
+}
+
+/** Parse the `crosstalk_session` value out of a Cookie header. */
+export function extractSessionCookie(cookieHeader: string | undefined): string | undefined {
+  if (!cookieHeader || typeof cookieHeader !== 'string') return undefined;
+  for (const part of cookieHeader.split(';')) {
+    const eq = part.indexOf('=');
+    if (eq < 0) continue;
+    const name = part.slice(0, eq).trim();
+    if (name === 'crosstalk_session') return decodeURIComponent(part.slice(eq + 1).trim());
+  }
+  return undefined;
+}
+
+/** Set-Cookie value for a freshly issued session token. HttpOnly + SameSite=Lax. */
+export function sessionCookieFor(wireToken: string, opts?: { secure?: boolean }): string {
+  const flags = ['Path=/', 'HttpOnly', 'SameSite=Lax'];
+  if (opts?.secure) flags.push('Secure');
+  return `crosstalk_session=${encodeURIComponent(wireToken)}; ${flags.join('; ')}`;
+}
+
+/** Set-Cookie value that clears the session. */
+export function clearSessionCookie(opts?: { secure?: boolean }): string {
+  const flags = ['Path=/', 'HttpOnly', 'SameSite=Lax', 'Max-Age=0'];
+  if (opts?.secure) flags.push('Secure');
+  return `crosstalk_session=; ${flags.join('; ')}`;
+}