@ultimat3/auth 1.0.0

package/src/oauth.ts

@@ -0,0 +1,168 @@
+// Single responsibility: the OAuth2/OIDC handshake. PKCE is mandatory rather than
+// provider-dependent — an authorization code with no proof-of-possession is stealable from a
+// redirect, and "this provider does not need it" is how that becomes a real incident. Provider
+// configs are pure data: importing this file performs no network I/O and reads no env.
+
+import { oauthStateInvalid } from './errors';
+import { base64Url, randomToken, sha256Bytes, timingSafeEqual } from './tokens';
+
+export interface OAuthProvider {
+  readonly id: string;
+  readonly authorizeUrl: string;
+  readonly tokenUrl: string;
+  readonly userInfoUrl: string | null;
+  /** A second call, only where the primary address is not on the profile (GitHub). */
+  readonly userEmailsUrl: string | null;
+  /**
+   * Every `iss` this provider is allowed to claim. Empty for a provider that issues no id
+   * token. A list rather than one string because Google has issued both forms for years.
+   */
+  readonly issuers: readonly string[];
+  readonly scopes: readonly string[];
+  readonly usesPkce: boolean;
+  /** OIDC providers echo `nonce` in the id token; it binds the token to this browser. */
+  readonly usesNonce: boolean;
+  readonly clientIdEnv: string;
+  readonly clientSecretEnv: string;
+}
+
+export const OAUTH_PROVIDERS = {
+  github: {
+    id: 'github',
+    authorizeUrl: 'https://github.com/login/oauth/authorize',
+    tokenUrl: 'https://github.com/login/oauth/access_token',
+    userInfoUrl: 'https://api.github.com/user',
+    // GitHub omits a private address from the profile; the identity is still incomplete
+    // without it, so the flow asks for the verified list rather than guessing.
+    userEmailsUrl: 'https://api.github.com/user/emails',
+    issuers: [],
+    scopes: ['read:user', 'user:email'],
+    usesPkce: true,
+    usesNonce: false,
+    clientIdEnv: 'GITHUB_CLIENT_ID',
+    clientSecretEnv: 'GITHUB_CLIENT_SECRET',
+  },
+  google: {
+    id: 'google',
+    authorizeUrl: 'https://accounts.google.com/o/oauth2/v2/auth',
+    tokenUrl: 'https://oauth2.googleapis.com/token',
+    // Reached only when a narrowed `scopes` leaves the id token without an email claim.
+    userInfoUrl: 'https://openidconnect.googleapis.com/v1/userinfo',
+    userEmailsUrl: null,
+    issuers: ['https://accounts.google.com', 'accounts.google.com'],
+    scopes: ['openid', 'email', 'profile'],
+    usesPkce: true,
+    usesNonce: true,
+    clientIdEnv: 'GOOGLE_CLIENT_ID',
+    clientSecretEnv: 'GOOGLE_CLIENT_SECRET',
+  },
+  apple: {
+    id: 'apple',
+    authorizeUrl: 'https://appleid.apple.com/auth/authorize',
+    tokenUrl: 'https://appleid.apple.com/auth/token',
+    // Apple returns claims in the id token only; there is no userinfo endpoint to call.
+    userInfoUrl: null,
+    userEmailsUrl: null,
+    issuers: ['https://appleid.apple.com'],
+    scopes: ['name', 'email'],
+    usesPkce: true,
+    usesNonce: true,
+    clientIdEnv: 'APPLE_CLIENT_ID',
+    // Apple alone does not accept a static secret: `APPLE_CLIENT_SECRET` must hold the ES256
+    // client-secret JWT signed with the .p8 key, which Apple expires every six months.
+    clientSecretEnv: 'APPLE_CLIENT_SECRET',
+  },
+} as const satisfies Readonly<Record<string, OAuthProvider>>;
+
+export type OAuthProviderId = keyof typeof OAUTH_PROVIDERS;
+
+export const OAUTH_PROVIDER_IDS: readonly OAuthProviderId[] = Object.freeze(
+  Object.keys(OAUTH_PROVIDERS) as OAuthProviderId[],
+);
+
+export interface PkcePair {
+  readonly verifier: string;
+  readonly challenge: string;
+  readonly method: 'S256';
+}
+
+/** RFC 7636 S256: `BASE64URL(SHA256(ASCII(verifier)))`. `plain` is not offered, ever. */
+export function pkceChallenge(verifier: string): string {
+  return base64Url(sha256Bytes(verifier));
+}
+
+export function createPkce(): PkcePair {
+  // 32 random bytes -> 43 base64url chars, the RFC's minimum verifier length.
+  const verifier = randomToken(32);
+  return { verifier, challenge: pkceChallenge(verifier), method: 'S256' };
+}
+
+/** Everything the server must remember between the redirect and the callback. */
+export interface OAuthHandshake {
+  readonly provider: OAuthProviderId;
+  readonly state: string;
+  readonly nonce: string;
+  readonly verifier: string;
+  readonly redirectUri: string;
+  readonly authorizeUrl: string;
+}
+
+export interface BeginOAuthInput {
+  readonly provider: OAuthProviderId;
+  readonly clientId: string;
+  readonly redirectUri: string;
+  readonly scopes?: readonly string[] | undefined;
+}
+
+export function beginOAuth(input: BeginOAuthInput): OAuthHandshake {
+  const provider = OAUTH_PROVIDERS[input.provider];
+  const pkce = createPkce();
+  const state = randomToken(16);
+  const nonce = randomToken(16);
+  const url = new URL(provider.authorizeUrl);
+  url.searchParams.set('response_type', 'code');
+  url.searchParams.set('client_id', input.clientId);
+  url.searchParams.set('redirect_uri', input.redirectUri);
+  url.searchParams.set('scope', (input.scopes ?? provider.scopes).join(' '));
+  url.searchParams.set('state', state);
+  url.searchParams.set('code_challenge', pkce.challenge);
+  url.searchParams.set('code_challenge_method', pkce.method);
+  if (provider.usesNonce) url.searchParams.set('nonce', nonce);
+  return {
+    provider: input.provider,
+    state,
+    nonce,
+    verifier: pkce.verifier,
+    redirectUri: input.redirectUri,
+    authorizeUrl: url.toString(),
+  };
+}
+
+export interface OAuthCallback {
+  readonly state: string;
+  readonly code: string;
+  /**
+   * Only a `form_post` response carries a nonce back on the redirect itself. In the plain code
+   * flow the nonce is a claim inside the id token, and `verifyIdToken` is what checks it — so
+   * this is verified when present and never required, or an OIDC login could not complete.
+   */
+  readonly nonce?: string | undefined;
+}
+
+/**
+ * The only gate between a redirect and a token exchange. Every rejection is
+ * `X_OAUTH_STATE_INVALID` — the callback is one handshake, and naming which half failed
+ * tells an attacker which half to keep guessing at.
+ */
+export function assertOAuthCallback(handshake: OAuthHandshake, callback: OAuthCallback): void {
+  const provider = OAUTH_PROVIDERS[handshake.provider];
+  if (!timingSafeEqual(handshake.state, callback.state)) {
+    throw oauthStateInvalid(provider.id, 'state did not match the stored handshake');
+  }
+  if (provider.usesPkce && handshake.verifier.length < 43) {
+    throw oauthStateInvalid(provider.id, 'no PKCE verifier was stored for this handshake');
+  }
+  if (callback.nonce !== undefined && !timingSafeEqual(handshake.nonce, callback.nonce)) {
+    throw oauthStateInvalid(provider.id, 'nonce did not match the stored handshake');
+  }
+}

package/src/password.ts

@@ -0,0 +1,136 @@
+// Single responsibility: password hashing, verification and strength. Parameters are explicit
+// and stored inside the PHC string, so raising them later is a rehash-on-next-login instead of
+// a migration. Verification always burns a full KDF even when the user does not exist —
+// otherwise response time answers "is this email registered?" for free.
+
+import { passwordWeak } from './errors';
+
+export interface PasswordParams {
+  readonly algorithm: 'argon2id';
+  /** KiB. OWASP's 2024 floor for argon2id at t=2, p=1. */
+  readonly memoryCost: number;
+  readonly timeCost: number;
+}
+
+export const DEFAULT_PASSWORD_PARAMS: PasswordParams = Object.freeze({
+  algorithm: 'argon2id',
+  memoryCost: 19_456,
+  timeCost: 2,
+});
+
+export interface PasswordPolicy {
+  readonly minLength: number;
+  readonly params: PasswordParams;
+}
+
+export const DEFAULT_PASSWORD_POLICY: PasswordPolicy = Object.freeze({
+  minLength: 12,
+  params: DEFAULT_PASSWORD_PARAMS,
+});
+
+export interface PasswordVerification {
+  readonly ok: boolean;
+  /** True when the stored hash used weaker parameters than the current policy. */
+  readonly needsRehash: boolean;
+}
+
+/** The one shape a failed verification takes. Identical for a wrong password and no user. */
+const FAILED: PasswordVerification = Object.freeze({ ok: false, needsRehash: false });
+
+const PHC_RE = /^\$argon2(id|i|d)\$v=\d+\$m=(\d+),t=(\d+)/;
+
+/**
+ * Passwords that survive any length rule but are the first thing a credential-stuffing list
+ * tries. Deliberately tiny: a real deployment layers a breach corpus on top via `extraDenyList`.
+ */
+const COMMON_PASSWORDS: ReadonlySet<string> = new Set([
+  'password',
+  'password1',
+  'password123',
+  'qwertyuiop',
+  '1234567890',
+  '123456789012',
+  'letmein12345',
+  'iloveyou1234',
+  'administrator',
+  'welcome12345',
+  'correcthorse',
+]);
+
+export async function hashPassword(
+  password: string,
+  params: PasswordParams = DEFAULT_PASSWORD_PARAMS,
+): Promise<string> {
+  return await Bun.password.hash(password, {
+    algorithm: params.algorithm,
+    memoryCost: params.memoryCost,
+    timeCost: params.timeCost,
+  });
+}
+
+/** Reads the parameters back out of a PHC string. `null` means "not a hash we recognise". */
+export function parseHashParams(hash: string): PasswordParams | null {
+  const match = PHC_RE.exec(hash);
+  if (match === null) return null;
+  const variant = match[1];
+  const memoryCost = Number.parseInt(match[2] ?? '', 10);
+  const timeCost = Number.parseInt(match[3] ?? '', 10);
+  if (variant !== 'id' || !Number.isFinite(memoryCost) || !Number.isFinite(timeCost)) return null;
+  return { algorithm: 'argon2id', memoryCost, timeCost };
+}
+
+/** An unreadable hash, a different algorithm or weaker cost all mean "rehash on next login". */
+export function needsRehash(
+  hash: string,
+  params: PasswordParams = DEFAULT_PASSWORD_PARAMS,
+): boolean {
+  const stored = parseHashParams(hash);
+  if (stored === null) return true;
+  return stored.memoryCost < params.memoryCost || stored.timeCost < params.timeCost;
+}
+
+export interface VerifyPasswordInput {
+  /** `null` when no user matched. The KDF still runs, on a throwaway hash. */
+  readonly hash: string | null;
+  readonly password: string;
+  readonly params?: PasswordParams | undefined;
+}
+
+/**
+ * Never short-circuits on a missing user: the `hashPassword` call in the `null` branch costs
+ * the same order of magnitude as the verify in the happy branch, so the two are not separable
+ * by a stopwatch. Callers must map `ok: false` to `loginFailed()` and nothing more specific.
+ */
+export async function verifyPassword(input: VerifyPasswordInput): Promise<PasswordVerification> {
+  const params = input.params ?? DEFAULT_PASSWORD_PARAMS;
+  if (input.hash === null) {
+    await hashPassword(input.password, params);
+    return FAILED;
+  }
+  const ok = await Bun.password.verify(input.password, input.hash);
+  if (!ok) return FAILED;
+  return { ok: true, needsRehash: needsRehash(input.hash, params) };
+}
+
+export interface StrengthOptions {
+  readonly policy?: PasswordPolicy | undefined;
+  readonly extraDenyList?: ReadonlySet<string> | undefined;
+}
+
+/** Throws `X_PASSWORD_WEAK` listing every reason at once — one round trip, not a guessing game. */
+export function checkPasswordStrength(password: string, options?: StrengthOptions): void {
+  const policy = options?.policy ?? DEFAULT_PASSWORD_POLICY;
+  const normalised = password.trim().toLowerCase();
+  const reasons: string[] = [];
+
+  if (password.length < policy.minLength) {
+    reasons.push(`it is ${password.length} characters, the policy requires ${policy.minLength}`);
+  }
+  if (COMMON_PASSWORDS.has(normalised) || options?.extraDenyList?.has(normalised) === true) {
+    reasons.push('it appears in the known-password deny list');
+  }
+  if (password.length > 0 && new Set(password).size <= 2) {
+    reasons.push('it uses two or fewer distinct characters');
+  }
+  if (reasons.length > 0) throw passwordWeak(reasons);
+}

package/src/policy-bridge.ts

@@ -0,0 +1,105 @@
+// Single responsibility: turn an authenticated identity into core's `Actor`. There is exactly
+// one authz system in Ultimate — `@ultimat3/policy` — and auth's only job is producing the actor
+// it evaluates. Nothing downstream ever authorizes on a session row, a user row or an api key.
+// `PolicyActorFields` mirrors `@ultimat3/policy`'s shape structurally so this package does not
+// import a same-tier package; policy binds to it by structure, in whichever order they land.
+
+import type { Actor } from '@ultimat3/core';
+import { agentActor, anonymousActor, assertNever, serviceActor, userActor } from '@ultimat3/core';
+import type { AuthApiKeyRecord, AuthSession, AuthUser } from './adapter';
+
+/** Structural mirror of `@ultimat3/policy`'s `PolicyActorFields`. Kept in sync by hand. */
+export interface PolicyActorFields {
+  readonly id: string;
+  readonly roles?: readonly string[] | undefined;
+  /** Direct grants that bypass roles. Service tokens and break-glass accounts only. */
+  readonly permissions?: readonly string[] | undefined;
+  readonly orgId?: string | null | undefined;
+}
+
+export type PolicyActor = Actor & PolicyActorFields;
+
+export interface ServiceIdentity {
+  readonly id: string;
+  readonly orgId?: string | null | undefined;
+  readonly scopes: readonly string[];
+}
+
+/** The four `ActorKind`s, as the four things that can be holding a credential. */
+export type AuthIdentity =
+  | { readonly kind: 'user'; readonly user: AuthUser; readonly session: AuthSession }
+  | { readonly kind: 'agent'; readonly apiKey: AuthApiKeyRecord }
+  | { readonly kind: 'service'; readonly service: ServiceIdentity }
+  | { readonly kind: 'anonymous' };
+
+const withPermissions = (actor: Actor, permissions: readonly string[]): PolicyActor => ({
+  ...actor,
+  permissions,
+});
+
+/**
+ * A human. Roles come from the row and are expanded to permissions by policy; scopes stay
+ * empty because a browser session is not scope-limited — the role set is the limit.
+ *
+ * A session that has not satisfied an enrolled second factor resolves to an actor with no
+ * roles and no permissions rather than an error, so a half-authenticated request can still
+ * reach the "finish MFA" route and nothing else. Login throws `X_MFA_REQUIRED` separately.
+ */
+export function actorFromUser(user: AuthUser, session: AuthSession): PolicyActor {
+  const mfaPending = user.mfaSecret !== null && !session.mfaSatisfied;
+  return withPermissions(
+    userActor({
+      id: user.id,
+      orgId: user.orgId ?? undefined,
+      roles: mfaPending ? [] : user.roles,
+      scopes: [],
+    }),
+    mfaPending ? [] : user.permissions,
+  );
+}
+
+/**
+ * An MCP/LLM caller. The actor's scopes are **exactly** the key's scopes — never the owning
+ * user's roles, never a default set. An agent that can do more than its key says is the whole
+ * failure mode this bridge exists to prevent.
+ */
+export function actorFromApiKey(key: AuthApiKeyRecord): PolicyActor {
+  return withPermissions(
+    agentActor({
+      id: key.id,
+      orgId: key.orgId ?? undefined,
+      roles: [],
+      scopes: key.scopes,
+    }),
+    key.scopes,
+  );
+}
+
+/** Machine-to-machine inside the deployment. Scopes are the grant; there are no roles. */
+export function actorFromService(service: ServiceIdentity): PolicyActor {
+  return withPermissions(
+    serviceActor({
+      id: service.id,
+      orgId: service.orgId ?? undefined,
+      roles: [],
+      scopes: service.scopes,
+    }),
+    service.scopes,
+  );
+}
+
+/** The single funnel. Every surface resolves its caller through this and nothing else. */
+export function resolveActor(identity: AuthIdentity): PolicyActor {
+  switch (identity.kind) {
+    case 'user':
+      return actorFromUser(identity.user, identity.session);
+    case 'agent':
+      return actorFromApiKey(identity.apiKey);
+    case 'service':
+      return actorFromService(identity.service);
+    case 'anonymous':
+      return anonymousActor();
+    default:
+      return assertNever(identity);
+  }
+}

package/src/rate-limit.ts

@@ -0,0 +1,104 @@
+// Single responsibility: throttling and lockout for credential paths, plus the one generic
+// failure every login path must throw. Two independent buckets — per IP (stops a spray across
+// many accounts) and per account (stops a spray against one) — because either alone is
+// bypassable. `loginFailed()` lives here so the throttle and the message can never drift apart.
+
+import type { Clock } from '@ultimat3/core';
+import { AuthError, accountLocked } from './errors';
+
+export interface AuthRateLimitPolicy {
+  /** Failures inside `windowMs` before the key is locked. */
+  readonly maxAttempts: number;
+  readonly windowMs: number;
+  readonly lockoutMs: number;
+}
+
+export const DEFAULT_AUTH_RATE_LIMIT: AuthRateLimitPolicy = Object.freeze({
+  maxAttempts: 5,
+  windowMs: 15 * 60 * 1000,
+  lockoutMs: 15 * 60 * 1000,
+});
+
+export interface AuthLimiter {
+  /** Throws `X_ACCOUNT_LOCKED` if the key is inside a lockout. Call before any KDF work. */
+  assertAllowed(key: string): void;
+  recordFailure(key: string): void;
+  /** A success clears the window: a legitimate user is not punished for a typo yesterday. */
+  recordSuccess(key: string): void;
+  lockedUntil(key: string): Date | null;
+  reset(): void;
+}
+
+export const accountKey = (email: string): string => `account:${email.trim().toLowerCase()}`;
+
+export const ipKey = (ip: string): string => `ip:${ip}`;
+
+interface Bucket {
+  failures: number[];
+  lockedUntilMs: number;
+}
+
+/**
+ * Sliding window over an injected `Clock` — never `Date.now()`, so a lockout test is
+ * deterministic instead of a sleep. In-memory per process; a multi-process deployment passes
+ * a shared implementation of the same interface.
+ */
+export function createAuthLimiter(
+  clock: Clock,
+  policy: AuthRateLimitPolicy = DEFAULT_AUTH_RATE_LIMIT,
+): AuthLimiter {
+  const buckets = new Map<string, Bucket>();
+
+  const bucketFor = (key: string): Bucket => {
+    const existing = buckets.get(key);
+    if (existing !== undefined) return existing;
+    const fresh: Bucket = { failures: [], lockedUntilMs: 0 };
+    buckets.set(key, fresh);
+    return fresh;
+  };
+
+  return {
+    assertAllowed(key) {
+      const bucket = buckets.get(key);
+      if (bucket === undefined) return;
+      const nowMs = clock.now().getTime();
+      if (bucket.lockedUntilMs <= nowMs) return;
+      throw accountLocked(key, Math.ceil((bucket.lockedUntilMs - nowMs) / 1000));
+    },
+    recordFailure(key) {
+      const nowMs = clock.now().getTime();
+      const bucket = bucketFor(key);
+      bucket.failures = bucket.failures.filter((at) => at > nowMs - policy.windowMs);
+      bucket.failures.push(nowMs);
+      if (bucket.failures.length >= policy.maxAttempts) {
+        bucket.lockedUntilMs = nowMs + policy.lockoutMs;
+      }
+    },
+    recordSuccess(key) {
+      buckets.delete(key);
+    },
+    lockedUntil(key) {
+      const bucket = buckets.get(key);
+      if (bucket === undefined || bucket.lockedUntilMs <= clock.now().getTime()) return null;
+      return new Date(bucket.lockedUntilMs);
+    },
+    reset() {
+      buckets.clear();
+    },
+  };
+}
+
+/**
+ * The single generic failure. Every credential path — unknown email, wrong password, disabled
+ * account, unverified address — throws exactly this object shape, so the rendered error is
+ * byte-identical and account existence is unobservable. Do not add a parameter to it.
+ */
+export function loginFailed(): AuthError {
+  return new AuthError({
+    code: 'X_UNAUTHENTICATED',
+    cause:
+      'the email and password combination did not match an account — re-enter them before ' +
+      'issuing the reset below, which mails a single-use token',
+    fix: "issueVerification(runtime, { purpose: 'password-reset', identifier: email, locale })",
+  });
+}