@ultimat3/auth 1.2.0 → 3.0.0

package/src/oauth-login-fixture.ts

@@ -0,0 +1,53 @@
+// The fixtures the three `oauth-login` suites share: the frozen instant, a fresh
+// `MemoryAdapter`-backed `Auth`, the two request bodies, the code of a rejection and a JSON
+// `Response`. Shared rather than copied — three suites building their own `Auth` would be three
+// flows that agree only by construction, the same reason `backfill-pass-fixture.ts` exists.
+
+import { frozenClock, isUltimateError } from '@ultimat3/core';
+import { type Auth, defineAuth } from './auth';
+import { MemoryAdapter } from './memory-adapter';
+import type { OAuthTokens } from './oauth-exchange';
+import type { OAuthProfile } from './oauth-profile';
+
+export const NOW = new Date('2026-08-09T12:00:00.000Z');
+
+export const credentials = { clientId: 'client-id', clientSecret: 'client-secret' };
+
+/** One adapter and the `Auth` over it, minted per `beforeEach` — never shared between tests. */
+export const freshAuth = (): { adapter: MemoryAdapter; auth: Auth } => {
+  const adapter = new MemoryAdapter();
+  return {
+    adapter,
+    auth: defineAuth({ adapter, clock: frozenClock(NOW), providers: ['github', 'google'] }),
+  };
+};
+
+export const profile = (overrides: Partial<OAuthProfile> = {}): OAuthProfile => ({
+  provider: 'github',
+  providerAccountId: '583231',
+  email: 'ada@example.com',
+  emailVerified: true,
+  name: 'Ada Lovelace',
+  ...overrides,
+});
+
+export const tokens = (overrides: Partial<OAuthTokens> = {}): OAuthTokens => ({
+  accessToken: 'gho_first',
+  refreshToken: null,
+  expiresAt: null,
+  idToken: null,
+  claims: null,
+  ...overrides,
+});
+
+export const codeOf = async (call: Promise<unknown>): Promise<string> => {
+  try {
+    await call;
+  } catch (error) {
+    return isUltimateError(error) ? error.code : `not-an-UltimateError: ${String(error)}`;
+  }
+  return 'did-not-throw';
+};
+
+export const json = (body: unknown): Response =>
+  new Response(JSON.stringify(body), { headers: { 'content-type': 'application/json' } });

package/src/oauth-login.ts

@@ -3,14 +3,18 @@
 // matter which door the user came through. `completeOAuthLogin` is the blessed entry point;
 // the three steps under it are exported because a custom flow needs the seams, not a second path.
 
-import { ConfigInvalidError, uuid } from '@ultimat3/core';
+import { ConfigInvalidError, logger, uuid } from '@ultimat3/core';
 import type { AuthAccount, AuthUser } from './adapter';
 import type { Auth, LoginResult } from './auth';
+import { normaliseEmail } from './email';
 import {
+  authWriteFailed,
   emailVerifiedNotStored,
   mfaRequired,
   oauthAccountNotLinked,
   oauthExchangeFailed,
+  oauthLinkingDisabled,
+  restartAt,
 } from './errors';
 import type { OAuthCallback, OAuthHandshake } from './oauth';
 import {
@@ -25,14 +29,43 @@ import { resolveActor } from './policy-bridge';
 import { loginFailed } from './rate-limit';
 import { createSession, sessionCookie } from './session';
 
+/**
+ * What the IdP's answer entitles this identity to, in the app's own vocabulary. Which group maps
+ * to which role is business convention and never ships (axiom 8) — this is the seam it arrives
+ * through, and every field is independently optional so a seam that only knows the org says only
+ * that.
+ */
+export interface OAuthGrants {
+  readonly orgId?: string | null | undefined;
+  readonly roles?: readonly string[] | undefined;
+  readonly scopes?: readonly string[] | undefined;
+  /**
+   * The IdP's own stable id for this person, if the app has one. Deliberately NOT derived from
+   * `profile.providerAccountId`: `x_users.external_id` is unique across the table, and two
+   * different OPs are free to issue the same `sub`, so auto-filling it would make one tenant's
+   * google login collide with another's okta login. The app knows which id its provisioning
+   * system uses; the framework does not.
+   */
+  readonly externalId?: string | null | undefined;
+}
+
+/** Called once per callback, after the profile is proven and before the session is minted. */
+export type ResolveOAuthGrants = (profile: OAuthProfile) => Promise<OAuthGrants> | OAuthGrants;
+
 export interface OAuthSignInInput {
   readonly profile: OAuthProfile;
   readonly tokens: OAuthTokens;
   readonly ip?: string | null | undefined;
   readonly userAgent?: string | null | undefined;
-  /** Granted to a user this flow creates. An existing user's roles are never rewritten here. */
-  readonly roles?: readonly string[] | undefined;
-  readonly orgId?: string | null | undefined;
+  /**
+   * Authoritative on EVERY login, not only the first. The IdP is the source of truth for who is
+   * in which group, so a member removed from a group there has to lose the role here on their
+   * next sign-in — an apply-once-at-creation rule made "revoke in the IdP" a no-op, and left the
+   * first-time user with `roles: []`, `orgId: null` and an actor every `can()` denies.
+   *
+   * Absent means "the app has no opinion": the stored row is left exactly as it is.
+   */
+  readonly grants?: OAuthGrants | undefined;
 }
 
 async function userForAccount(auth: Auth, account: AuthAccount): Promise<AuthUser> {
@@ -41,8 +74,48 @@ async function userForAccount(auth: Auth, account: AuthAccount): Promise<AuthUse
   return user;
 }
 
+/**
+ * The grant seam applied to a row that already exists. Only the fields the seam actually returned
+ * are written, and only when they differ — an unconditional `updateUser` would make every SSO
+ * login a write, which is the same mistake `verifySession` used to make on every request.
+ */
+async function applyGrants(auth: Auth, user: AuthUser, grants: OAuthGrants): Promise<AuthUser> {
+  const same = (a: readonly string[] | undefined, b: readonly string[]): boolean =>
+    a === undefined || (a.length === b.length && a.every((one, index) => one === b[index]));
+  const unchanged = (declared: string | null | undefined, stored: string | null): boolean =>
+    declared === undefined || (declared ?? null) === stored;
+  if (
+    unchanged(grants.orgId, user.orgId) &&
+    unchanged(grants.externalId, user.externalId) &&
+    same(grants.roles, user.roles) &&
+    same(grants.scopes, user.scopes)
+  ) {
+    return user;
+  }
+  const patched = await auth.adapter.updateUser(user.id, {
+    ...(grants.orgId === undefined ? {} : { orgId: grants.orgId ?? null }),
+    ...(grants.roles === undefined ? {} : { roles: grants.roles }),
+    ...(grants.scopes === undefined ? {} : { scopes: grants.scopes }),
+    ...(grants.externalId === undefined ? {} : { externalId: grants.externalId ?? null }),
+  });
+  // Failing closed rather than signing in with the stale row: the whole point of the seam is that
+  // the session about to be minted carries what the IdP says today.
+  if (patched === null) throw authWriteFailed('updateUser', 'x_users');
+  return patched;
+}
+
+/**
+ * The provider's address, put through the one normalisation every other door uses. Providers send
+ * display casing (`Ada@Example.com`) and change it between logins, and `x_users.email` is a plain
+ * case-sensitive `unique` column — so unnormalised, the lookup below missed the account the user
+ * registered and `createUserFor` minted a second one at the same address, which `login()` could
+ * then never reach. `MemoryAdapter` used to fold case itself, which is why no test saw it.
+ */
+const profileEmail = (profile: OAuthProfile): string | null =>
+  profile.email === null ? null : normaliseEmail(profile.email);
+
 async function createUserFor(auth: Auth, input: OAuthSignInInput): Promise<AuthUser> {
-  const email = input.profile.email;
+  const email = profileEmail(input.profile);
   // The provider authenticated somebody and told us no address. There is nothing to create an
   // account from, and saying "wrong password" here would send the developer hunting the wrong bug.
   if (email === null) {
@@ -50,7 +123,17 @@ async function createUserFor(auth: Auth, input: OAuthSignInInput): Promise<AuthU
       provider: input.profile.provider,
       stage: 'userinfo',
       detail: 'the provider returned an identity with no email address',
-      fix: `request the email scope for ${input.profile.provider} in beginOAuth(), then restart the flow`,
+      fix: `request the email scope for ${input.profile.provider} in beginOAuth(), then ${restartAt(input.profile.provider)}`,
+    });
+  }
+  const grants = input.grants ?? {};
+  if ((grants.roles ?? []).length === 0 && (grants.orgId ?? null) === null) {
+    // Not an error — an app may genuinely want a roleless account until somebody approves it —
+    // but silent is how "SSO works and the user can do nothing" survives to production. Every
+    // `can()` denies a roleless actor, and a tenant-scoped read throws before the query is built.
+    logger.warn('auth.oauth.user_created_without_grants', {
+      provider: input.profile.provider,
+      seam: 'oauthLogin(auth, { resolveGrants })',
     });
   }
   const created = await auth.adapter.createUser({
@@ -59,8 +142,10 @@ async function createUserFor(auth: Auth, input: OAuthSignInInput): Promise<AuthU
     // An OAuth-only account has no password to store, and must never be given a random one:
     // a hash nobody knows the input to is still a credential a reset flow could hand over.
     passwordHash: null,
-    orgId: input.orgId ?? null,
-    roles: input.roles ?? [],
+    orgId: grants.orgId ?? null,
+    roles: grants.roles ?? [],
+    scopes: grants.scopes ?? [],
+    externalId: grants.externalId ?? null,
     createdAt: auth.clock.now(),
   });
   if (!input.profile.emailVerified) return created;
@@ -79,13 +164,17 @@ async function createUserFor(auth: Auth, input: OAuthSignInInput): Promise<AuthU
  * An address alone is not proof of ownership on either side. Attaching a provider identity to a
  * local account that never verified its own email hands the login to whoever registered that
  * address first, so both halves must have proven it before they are treated as one person.
+ *
+ * `auth.link` is the app's one say in that. `'never'` skips the address step entirely and refuses
+ * a collision; `'verified-email'` — the default — is the both-halves-proven rule below.
  */
 async function resolveUser(
   auth: Auth,
   input: OAuthSignInInput,
   linked: AuthAccount | null,
 ): Promise<AuthUser> {
-  const { provider, email, emailVerified } = input.profile;
+  const { provider, emailVerified } = input.profile;
+  const email = profileEmail(input.profile);
   if (linked !== null) return await userForAccount(auth, linked);
 
   if (email === null) return await createUserFor(auth, input);
@@ -94,6 +183,12 @@ async function resolveUser(
   if (existing.disabledAt !== null) throw loginFailed();
   // The provider did not vouch for the address, so nothing here proves the two are one person.
   if (!emailVerified) throw loginFailed();
+  // Only past that line is the caller known to own the address, which is what makes naming the
+  // collision safe. Refusing `'never'` any earlier answered an UNVERIFIED provider address with a
+  // distinct code and a `meta.email` where `'verified-email'` answers `loginFailed()` — so the
+  // strict policy confirmed an account exists at an address its caller never proved. `disabledAt`
+  // above is generic and reveals nothing, which is why it can be asked first.
+  if (auth.link === 'never') throw oauthLinkingDisabled(provider, email);
   // It did vouch, and the local account never did: say so, because this caller owns the address.
   if (existing.emailVerifiedAt === null) throw oauthAccountNotLinked(provider, email);
   return existing;
@@ -127,7 +222,9 @@ export async function signInWithOAuth(auth: Auth, input: OAuthSignInInput): Prom
   }
 
   const linked = await auth.adapter.findAccount(provider, input.profile.providerAccountId);
-  const user = await resolveUser(auth, input, linked);
+  const resolved = await resolveUser(auth, input, linked);
+  const user =
+    input.grants === undefined ? resolved : await applyGrants(auth, resolved, input.grants);
   // Linked before the MFA gate on purpose: the second factor is finished on another request,
   // and that request must find the identity already attached. A re-link refreshes the tokens
   // and keeps the row's own identity — the provider account never changes hands.
@@ -162,8 +259,8 @@ export interface CompleteOAuthLoginInput {
   readonly timeoutMs?: number | undefined;
   readonly ip?: string | null | undefined;
   readonly userAgent?: string | null | undefined;
-  readonly roles?: readonly string[] | undefined;
-  readonly orgId?: string | null | undefined;
+  /** The app's grant seam. Called once, after the profile is proven. */
+  readonly resolveGrants?: ResolveOAuthGrants | undefined;
 }
 
 /** Callback → session, in one call: exchange, identify, sign in. */
@@ -182,12 +279,12 @@ export async function completeOAuthLogin(
     fetch: input.fetch,
     timeoutMs: input.timeoutMs,
   });
+  const grants = input.resolveGrants === undefined ? undefined : await input.resolveGrants(profile);
   return await signInWithOAuth(auth, {
     profile,
     tokens,
     ip: input.ip,
     userAgent: input.userAgent,
-    roles: input.roles,
-    orgId: input.orgId,
+    ...(grants === undefined ? {} : { grants }),
   });
 }

package/src/oauth-paths.ts

@@ -0,0 +1,20 @@
+// Single responsibility: the one declaration of where the OAuth login routes live. It imports
+// nothing so that `errors.ts` and `oauth-route.ts` can both read it without a cycle — which is
+// the point: three shipped `fix:` lines told the caller to restart at `GET /auth/oauth/<provider>`
+// while no route was mounted anywhere. Deriving both the mount and the fix from here makes a fix
+// line that names a route nothing serves impossible rather than merely discouraged.
+
+/** Not configurable, on purpose: a movable base path is a `fix:` line that can go stale again. */
+export const OAUTH_BASE_PATH = '/auth/oauth';
+
+/** The pattern a router mounts. `:provider` is the segment `oauthStartPath` fills in. */
+export const OAUTH_START_ROUTE_PATH = `${OAUTH_BASE_PATH}/:provider` as const;
+
+export const OAUTH_CALLBACK_ROUTE_PATH = `${OAUTH_BASE_PATH}/:provider/callback` as const;
+
+/** Where a browser starts a login. This exact string is what the `fix:` lines quote. */
+export const oauthStartPath = (provider: string): string => `${OAUTH_BASE_PATH}/${provider}`;
+
+/** Where the provider sends it back. Registered with the provider as the `redirect_uri`. */
+export const oauthCallbackPath = (provider: string): string =>
+  `${OAUTH_BASE_PATH}/${provider}/callback`;

package/src/oauth-profile.ts

@@ -4,15 +4,17 @@
 // decides whether this login may attach itself to an existing account by address.
 
 import { logger } from '@ultimat3/core';
-import { oauthExchangeFailed } from './errors';
+import { oauthExchangeFailed, restartAt } from './errors';
 import { idTokenEmailVerified, isVerifiedFlag } from './id-token';
-import { OAUTH_PROVIDERS, type OAuthProviderId } from './oauth';
+import { isRecord } from './json';
+import type { OAuthProviderId } from './oauth';
 import {
   OAUTH_USER_AGENT,
   type OAuthFetch,
   type OAuthTokens,
   providerDetail,
 } from './oauth-exchange';
+import { providerFor } from './oauth-registry';
 
 const DEFAULT_TIMEOUT_MS = 10_000;
 
@@ -37,9 +39,6 @@ interface GithubEmail {
   readonly verified: boolean;
 }
 
-const isRecord = (value: unknown): value is Record<string, unknown> =>
-  typeof value === 'object' && value !== null && !Array.isArray(value);
-
 const stringOrNull = (value: unknown): string | null =>
   typeof value === 'string' && value !== '' ? value : null;
 
@@ -108,14 +107,14 @@ async function fromUserInfo(
   tokens: OAuthTokens,
   options: OAuthProfileOptions,
 ): Promise<OAuthProfile> {
-  const config = OAUTH_PROVIDERS[provider];
+  const config = providerFor(provider);
   const url = config.userInfoUrl;
   if (url === null) {
     throw oauthExchangeFailed({
       provider,
       stage: 'userinfo',
       detail: `${provider} publishes no userinfo endpoint and its id token carried no identity`,
-      fix: `request the "email" scope for ${provider} in beginOAuth(), then restart the flow`,
+      fix: `request the "email" scope for ${provider} in beginOAuth(), then ${restartAt(provider)}`,
     });
   }
 
@@ -126,7 +125,7 @@ async function fromUserInfo(
       stage: 'userinfo',
       detail: result.detail,
       status: result.status,
-      fix: `confirm the ${provider} app still grants ${config.scopes.join(' ')}, then restart the flow`,
+      fix: `confirm the ${provider} app still grants ${config.scopes.join(' ')}, then ${restartAt(provider)}`,
     });
   }
   if (!isRecord(result.body)) {
@@ -148,7 +147,7 @@ async function fromUserInfo(
       provider,
       stage: 'userinfo',
       detail: 'the profile carried no stable account id',
-      fix: `confirm the ${provider} app requests ${config.scopes.join(' ')} and restart the flow`,
+      fix: `confirm the ${provider} app requests ${config.scopes.join(' ')}, then ${restartAt(provider)}`,
     });
   }
 
@@ -186,7 +185,7 @@ export async function oauthProfile(
   if (claims === null) return await fromUserInfo(provider, tokens, options);
 
   const email = stringOrNull(claims.email);
-  const userInfoUrl = OAUTH_PROVIDERS[provider].userInfoUrl;
+  const userInfoUrl = providerFor(provider).userInfoUrl;
   if (email === null && userInfoUrl !== null) {
     const profile = await fromUserInfo(provider, tokens, options);
     // Two surfaces, one identity — or this is not that identity. Overwriting the subject and

package/src/oauth-registry.ts

@@ -0,0 +1,65 @@
+// Single responsibility: which OAuth providers this process knows about. A closed union of three
+// consumer IdPs made an enterprise OP — Okta, Entra, Ping, an in-house OP — *unrepresentable*: the
+// constraint was a type, so there was no runtime escape and the only ways out were forking the
+// package or bypassing the whole subsystem, losing PKCE, the sealed handshake, issuer pinning and
+// account linking with it. The three built-ins register through the same call an app uses, so the
+// opening does not create a second path.
+
+import { oauthProviderDuplicate, oauthProviderUnknown } from './errors';
+import type { OAuthProvider } from './oauth';
+import { BUILTIN_OAUTH_PROVIDERS } from './oauth-builtins';
+
+const registry = new Map<string, OAuthProvider>();
+
+/**
+ * Frozen on the way in, arrays included: a registered provider is read on every login of its
+ * kind, and a caller that kept a reference to the object it passed could otherwise repoint
+ * `tokenUrl` or widen `issuers` after boot.
+ */
+const seal = (provider: OAuthProvider): OAuthProvider =>
+  Object.freeze({
+    ...provider,
+    issuers: Object.freeze([...provider.issuers]),
+    scopes: Object.freeze([...provider.scopes]),
+  });
+
+/**
+ * Add an IdP. The one extension point, and the same one `oauth-builtins.ts` goes through.
+ *
+ * `usesPkce` stays the literal `true` on `OAuthProvider`, so this opening cannot be used to
+ * register a PKCE-less provider: the mechanism the package exists to own survives the widening.
+ *
+ * A duplicate id is `X_OAUTH_PROVIDER_DUPLICATE` rather than a silent replacement — two modules
+ * each registering `'okta'` is one of them quietly deciding where every okta login goes.
+ */
+export function registerOAuthProvider(provider: OAuthProvider): OAuthProvider {
+  if (registry.has(provider.id)) throw oauthProviderDuplicate(provider.id);
+  const sealed = seal(provider);
+  registry.set(sealed.id, sealed);
+  return sealed;
+}
+
+for (const provider of BUILTIN_OAUTH_PROVIDERS) registerOAuthProvider(provider);
+
+export function hasOAuthProvider(id: string): boolean {
+  return registry.has(id);
+}
+
+/**
+ * The one lookup. Throws rather than answering `undefined`, because every caller in this package
+ * would otherwise have to decide what an unknown provider means — and one of them would decide
+ * wrong. `X_OAUTH_PROVIDER_UNKNOWN` already existed for exactly this.
+ */
+export function providerFor(id: string): OAuthProvider {
+  const provider = registry.get(id);
+  if (provider === undefined) throw oauthProviderUnknown(id, oauthProviderIds());
+  return provider;
+}
+
+/**
+ * Live, never a snapshot taken at import: `defineAuth({ providers })` defaults to this, and a
+ * frozen copy would leave an IdP registered after this module loaded enabled nowhere.
+ */
+export function oauthProviderIds(): readonly string[] {
+  return [...registry.keys()];
+}