@reactionary/oidc 0.0.0-stage → 0.0.1

package/README.md

@@ -1,3 +1,19 @@
-# Temporary Holding Version
+# @reactionary/oidc
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Shared OpenID Connect relying party for backends that cannot run an external login themselves.
+
+A backend that **hosts** the redirect (for example Medusa) implements `startExternalLogin` and `completeExternalLogin` directly. A backend that does not extends `OidcIdentityCapability` instead: this package runs discovery, authorization code with PKCE, nonce and ID-token validation, and the backend implements one method, `exchangeExternalIdentity`, which turns the verified identity into a backend session.
+
+The storefront sees the same three calls either way: `listProviders`, `startExternalLogin`, `completeExternalLogin`.
+
+## Configuring providers
+
+Backends that use this package take an `externalIdentityProviders` list in their configuration. See `ExternalIdentityProviderSchema`.
+
+## Testing
+
+`@reactionary/oidc/testing` exports a fake identity provider (a local HTTP server with discovery, JWKS, token endpoint and signed ID tokens) and `runExternalLoginConformance`, which every backend's spec should run.
+
+## Building and testing
+
+Run `nx build oidc` and `nx test oidc`.

package/capabilities/oidc-identity.capability.js

@@ -0,0 +1,113 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __decorateClass = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc(target, key) : target;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = (kind ? decorator(target, key, result) : decorator(result)) || result;
+  if (kind && result) __defProp(target, key, result);
+  return result;
+};
+import {
+  ExternalLoginRedirectSchema,
+  IdentityCapability,
+  IdentityMutationCompleteExternalLoginSchema,
+  IdentityMutationStartExternalLoginSchema,
+  IdentityProviderSchema,
+  IdentityQueryProvidersSchema,
+  IdentitySchema,
+  PASSWORD_IDENTITY_PROVIDER,
+  Reactionary,
+  error,
+  success
+} from "@reactionary/core";
+import { codeChallenge, randomToken } from "../client/pkce.js";
+import { resolveMetadata } from "../client/discovery.js";
+import { buildAuthorizationUrl, exchangeCode, verifyIdToken } from "../client/relying-party.js";
+class OidcIdentityCapability extends IdentityCapability {
+  externalProviders;
+  constructor(cache, context, externalProviders) {
+    super(cache, context);
+    this.externalProviders = externalProviders ?? [];
+  }
+  async listProviders() {
+    return success([
+      PASSWORD_IDENTITY_PROVIDER,
+      ...this.externalProviders.map((provider) => ({
+        identifier: { key: provider.key },
+        displayName: provider.displayName,
+        flow: "redirect",
+        ...provider.brand ? { brand: provider.brand } : {}
+      }))
+    ]);
+  }
+  async startExternalLogin(payload) {
+    const provider = this.externalProviders.find((candidate) => candidate.key === payload.provider.key);
+    if (!provider) {
+      return error({ type: "InvalidInput", error: `Unknown identity provider ${payload.provider.key}` });
+    }
+    const metadata = await resolveMetadata(provider);
+    const state = randomToken();
+    const nonce = randomToken();
+    const codeVerifier = randomToken(48);
+    const location = buildAuthorizationUrl(provider, metadata, {
+      callbackUrl: payload.callbackUrl,
+      state,
+      nonce,
+      codeChallenge: await codeChallenge(codeVerifier)
+    });
+    this.setPendingExternalLogin(provider.key, state, { nonce, codeVerifier });
+    return success({ location });
+  }
+  async completeExternalLogin(payload) {
+    const provider = this.externalProviders.find((candidate) => candidate.key === payload.provider.key);
+    if (!provider) {
+      return error({ type: "InvalidInput", error: `Unknown identity provider ${payload.provider.key}` });
+    }
+    const params = payload.callbackParameters;
+    const pending = this.takePendingExternalLogin(provider.key, params["state"]);
+    if (!pending) {
+      return error({ type: "InvalidInput", error: "The login was not started in this session, or has expired" });
+    }
+    if (params["error"]) {
+      return error({ type: "InvalidInput", error: `The identity provider refused the login: ${params["error"]}` });
+    }
+    const code = params["code"];
+    const { nonce, codeVerifier } = pending.data;
+    if (!code || !nonce || !codeVerifier) {
+      return error({ type: "InvalidInput", error: "The login response has no authorization code" });
+    }
+    const metadata = await resolveMetadata(provider);
+    const tokens = await exchangeCode(provider, metadata, { code, callbackUrl: payload.callbackUrl, codeVerifier });
+    const claims = await verifyIdToken(provider, metadata, tokens.idToken, nonce);
+    if (provider.requireVerifiedEmail !== false && claims["email_verified"] !== true) {
+      return error({ type: "InvalidInput", error: "The identity provider did not confirm a verified email address" });
+    }
+    const result = await this.exchangeExternalIdentity({ provider, claims, tokens });
+    if (result.success) {
+      this.updateIdentityContext(result.value);
+    }
+    return result;
+  }
+}
+__decorateClass([
+  Reactionary({
+    inputSchema: IdentityQueryProvidersSchema,
+    outputSchema: IdentityProviderSchema.array()
+  })
+], OidcIdentityCapability.prototype, "listProviders", 1);
+__decorateClass([
+  Reactionary({
+    inputSchema: IdentityMutationStartExternalLoginSchema,
+    outputSchema: ExternalLoginRedirectSchema
+  })
+], OidcIdentityCapability.prototype, "startExternalLogin", 1);
+__decorateClass([
+  Reactionary({
+    inputSchema: IdentityMutationCompleteExternalLoginSchema,
+    outputSchema: IdentitySchema
+  })
+], OidcIdentityCapability.prototype, "completeExternalLogin", 1);
+export {
+  OidcIdentityCapability
+};

package/client/discovery.js

@@ -0,0 +1,56 @@
+import * as z from "zod";
+const DISCOVERY_TTL_MS = 60 * 60 * 1e3;
+const DiscoveryDocumentSchema = z.looseObject({
+  issuer: z.string(),
+  authorization_endpoint: z.string(),
+  token_endpoint: z.string(),
+  jwks_uri: z.string(),
+  end_session_endpoint: z.string().optional()
+});
+const cache = /* @__PURE__ */ new Map();
+function clearDiscoveryCache() {
+  cache.clear();
+}
+async function resolveMetadata(provider) {
+  if (provider.authorizationEndpoint && provider.tokenEndpoint && provider.jwksUri) {
+    return {
+      issuer: provider.issuer,
+      authorizationEndpoint: provider.authorizationEndpoint,
+      tokenEndpoint: provider.tokenEndpoint,
+      jwksUri: provider.jwksUri
+    };
+  }
+  let discovered = cache.get(provider.issuer);
+  if (!discovered || discovered.expires < Date.now()) {
+    const url = `${provider.issuer.replace(/\/$/, "")}/.well-known/openid-configuration`;
+    const response = await fetch(url, { headers: { accept: "application/json" } });
+    if (!response.ok) {
+      throw new Error(`Discovery failed for ${provider.key}: HTTP ${response.status}`);
+    }
+    const document = DiscoveryDocumentSchema.parse(await response.json());
+    if (document.issuer !== provider.issuer) {
+      throw new Error(`Discovery document of ${provider.key} names a different issuer than configured`);
+    }
+    discovered = {
+      expires: Date.now() + DISCOVERY_TTL_MS,
+      metadata: {
+        issuer: document.issuer,
+        authorizationEndpoint: document.authorization_endpoint,
+        tokenEndpoint: document.token_endpoint,
+        jwksUri: document.jwks_uri,
+        ...document.end_session_endpoint ? { endSessionEndpoint: document.end_session_endpoint } : {}
+      }
+    };
+    cache.set(provider.issuer, discovered);
+  }
+  return {
+    ...discovered.metadata,
+    authorizationEndpoint: provider.authorizationEndpoint ?? discovered.metadata.authorizationEndpoint,
+    tokenEndpoint: provider.tokenEndpoint ?? discovered.metadata.tokenEndpoint,
+    jwksUri: provider.jwksUri ?? discovered.metadata.jwksUri
+  };
+}
+export {
+  clearDiscoveryCache,
+  resolveMetadata
+};

package/client/pkce.js

@@ -0,0 +1,20 @@
+function base64Url(bytes) {
+  let binary = "";
+  bytes.forEach((byte) => {
+    binary += String.fromCharCode(byte);
+  });
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function randomToken(byteLength = 32) {
+  const bytes = new Uint8Array(byteLength);
+  crypto.getRandomValues(bytes);
+  return base64Url(bytes);
+}
+async function codeChallenge(verifier) {
+  const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(verifier));
+  return base64Url(new Uint8Array(digest));
+}
+export {
+  codeChallenge,
+  randomToken
+};

package/client/relying-party.js

@@ -0,0 +1,111 @@
+import * as z from "zod";
+import { createRemoteJWKSet, jwtVerify } from "jose";
+import { DEFAULT_SCOPES } from "../schema/external-identity-provider.schema.js";
+const ALLOWED_ALGORITHMS = ["RS256", "RS384", "RS512", "PS256", "ES256", "ES384"];
+const CLOCK_TOLERANCE_SECONDS = 30;
+const RefreshResponseSchema = z.looseObject({
+  access_token: z.string(),
+  refresh_token: z.string().optional(),
+  id_token: z.string().optional(),
+  expires_in: z.number().optional()
+});
+const TokenResponseSchema = z.looseObject({
+  id_token: z.string(),
+  access_token: z.string().optional(),
+  refresh_token: z.string().optional(),
+  expires_in: z.number().optional()
+});
+function buildAuthorizationUrl(provider, metadata, request) {
+  const url = new URL(metadata.authorizationEndpoint);
+  url.searchParams.set("response_type", "code");
+  url.searchParams.set("client_id", provider.clientId);
+  url.searchParams.set("redirect_uri", request.callbackUrl);
+  url.searchParams.set("scope", (provider.scopes ?? DEFAULT_SCOPES).join(" "));
+  url.searchParams.set("state", request.state);
+  url.searchParams.set("nonce", request.nonce);
+  url.searchParams.set("code_challenge", request.codeChallenge);
+  url.searchParams.set("code_challenge_method", "S256");
+  for (const [key, value] of Object.entries(provider.authorizationParams ?? {})) {
+    url.searchParams.set(key, value);
+  }
+  return url.toString();
+}
+async function exchangeCode(provider, metadata, request) {
+  const body = new URLSearchParams({
+    grant_type: "authorization_code",
+    code: request.code,
+    redirect_uri: request.callbackUrl,
+    client_id: provider.clientId,
+    code_verifier: request.codeVerifier
+  });
+  if (provider.clientSecret) {
+    body.set("client_secret", provider.clientSecret);
+  }
+  const response = await fetch(metadata.tokenEndpoint, {
+    method: "POST",
+    headers: { "content-type": "application/x-www-form-urlencoded", accept: "application/json" },
+    body
+  });
+  if (!response.ok) {
+    throw new Error(`The identity provider refused the authorization code: HTTP ${response.status}`);
+  }
+  const tokens = TokenResponseSchema.parse(await response.json());
+  return {
+    idToken: tokens.id_token,
+    ...tokens.access_token ? { accessToken: tokens.access_token } : {},
+    ...tokens.refresh_token ? { refreshToken: tokens.refresh_token } : {},
+    ...tokens.expires_in !== void 0 ? { expiresIn: tokens.expires_in } : {}
+  };
+}
+async function refreshTokens(provider, metadata, refreshToken) {
+  const body = new URLSearchParams({
+    grant_type: "refresh_token",
+    refresh_token: refreshToken,
+    client_id: provider.clientId
+  });
+  if (provider.clientSecret) {
+    body.set("client_secret", provider.clientSecret);
+  }
+  const response = await fetch(metadata.tokenEndpoint, {
+    method: "POST",
+    headers: { "content-type": "application/x-www-form-urlencoded", accept: "application/json" },
+    body
+  });
+  if (!response.ok) {
+    throw new Error(`The identity provider refused the refresh token: HTTP ${response.status}`);
+  }
+  const tokens = RefreshResponseSchema.parse(await response.json());
+  return {
+    accessToken: tokens.access_token,
+    ...tokens.refresh_token ? { refreshToken: tokens.refresh_token } : {},
+    ...tokens.id_token ? { idToken: tokens.id_token } : {},
+    ...tokens.expires_in !== void 0 ? { expiresIn: tokens.expires_in } : {}
+  };
+}
+const jwksByUri = /* @__PURE__ */ new Map();
+function keysFor(jwksUri) {
+  let keys = jwksByUri.get(jwksUri);
+  if (!keys) {
+    keys = createRemoteJWKSet(new URL(jwksUri));
+    jwksByUri.set(jwksUri, keys);
+  }
+  return keys;
+}
+async function verifyIdToken(provider, metadata, idToken, expectedNonce) {
+  const { payload } = await jwtVerify(idToken, keysFor(metadata.jwksUri), {
+    issuer: metadata.issuer,
+    audience: provider.clientId,
+    algorithms: ALLOWED_ALGORITHMS,
+    clockTolerance: CLOCK_TOLERANCE_SECONDS
+  });
+  if (payload["nonce"] !== expectedNonce) {
+    throw new Error("The ID token nonce does not match this login");
+  }
+  return payload;
+}
+export {
+  buildAuthorizationUrl,
+  exchangeCode,
+  refreshTokens,
+  verifyIdToken
+};

package/index.js

@@ -0,0 +1,5 @@
+export * from "./capabilities/oidc-identity.capability.js";
+export * from "./client/discovery.js";
+export * from "./client/pkce.js";
+export * from "./client/relying-party.js";
+export * from "./schema/external-identity-provider.schema.js";

package/package.json

@@ -1,6 +1,38 @@
 {
   "name": "@reactionary/oidc",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.1",
+  "type": "module",
+  "main": "./index.js",
+  "types": "./src/index.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Solteq/reactionary.git"
+  },
+  "dependencies": {
+    "@reactionary/core": "0.0.1",
+    "zod": "4.1.9",
+    "jose": "^6.1.0"
+  },
+  "devDependencies": {
+    "vitest": "^4.0.9"
+  },
+  "sideEffects": false,
+  "peerDependencies": {
+    "vitest": "^4.0.9"
+  },
+  "peerDependenciesMeta": {
+    "vitest": {
+      "optional": true
+    }
+  },
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./index.js"
+    },
+    "./testing": {
+      "types": "./src/testing/index.d.ts",
+      "default": "./testing/index.js"
+    }
+  }
+}

package/schema/external-identity-provider.schema.js

@@ -0,0 +1,38 @@
+import * as z from "zod";
+const RESERVED_AUTHORIZATION_PARAMS = [
+  "client_id",
+  "response_type",
+  "redirect_uri",
+  "scope",
+  "state",
+  "nonce",
+  "code_challenge",
+  "code_challenge_method"
+];
+const DEFAULT_SCOPES = ["openid", "email", "profile"];
+function isSecureUrl(value) {
+  const url = new URL(value);
+  return url.protocol === "https:" || ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname);
+}
+const secureUrlSchema = z.url().refine(isSecureUrl, { error: "Must be an https URL (http is only allowed for localhost)" });
+const ExternalIdentityProviderSchema = z.looseObject({
+  key: z.string().min(1).meta({ description: "Stable identifier the storefront passes back to startExternalLogin." }),
+  displayName: z.string().min(1),
+  brand: z.string().optional().meta({ description: "Neutral brand slug (google, apple, ...) so a storefront can choose its own icon." }),
+  issuer: secureUrlSchema.meta({ description: "The issuer URL. Used for discovery and as the expected iss claim." }),
+  clientId: z.string().min(1),
+  clientSecret: z.string().optional().meta({ description: "Without a secret the client is public and relies on PKCE alone." }),
+  scopes: z.array(z.string()).optional().meta({ description: `Defaults to ${DEFAULT_SCOPES.join(" ")}.` }),
+  authorizationParams: z.record(z.string(), z.string()).refine((params) => Object.keys(params).every((key) => !RESERVED_AUTHORIZATION_PARAMS.includes(key)), {
+    error: `authorizationParams cannot set ${RESERVED_AUTHORIZATION_PARAMS.join(", ")}`
+  }).optional().meta({ description: 'Fixed extra authorize parameters, e.g. { prompt: "login" } or { connection: "apple" } for Auth0.' }),
+  requireVerifiedEmail: z.boolean().optional().meta({ description: "Require email_verified to be true. Defaults to true; some providers (Azure B2C) never send the claim." }),
+  authorizationEndpoint: secureUrlSchema.optional(),
+  tokenEndpoint: secureUrlSchema.optional(),
+  jwksUri: secureUrlSchema.optional()
+});
+export {
+  DEFAULT_SCOPES,
+  ExternalIdentityProviderSchema,
+  RESERVED_AUTHORIZATION_PARAMS
+};

package/src/capabilities/oidc-identity.capability.d.ts

@@ -0,0 +1,28 @@
+import { type Cache, type ExternalLoginRedirect, type Identity, type IdentityConflictError, IdentityCapability, type IdentityMutationCompleteExternalLogin, type IdentityMutationStartExternalLogin, type IdentityProvider, type RequestContext, type Result } from '@reactionary/core';
+import type { JWTPayload } from 'jose';
+import { type OidcTokens } from '../client/relying-party.js';
+import type { ExternalIdentityProvider } from '../schema/external-identity-provider.schema.js';
+export type ExchangeExternalIdentityInput = {
+    provider: ExternalIdentityProvider;
+    /** The verified ID token claims. */
+    claims: JWTPayload;
+    tokens: OidcTokens;
+};
+/**
+ * Base class for backends that cannot run an external login themselves. This class runs the OpenID Connect part
+ * (discovery, authorization code with PKCE, nonce, ID-token validation, binding the callback to the browser that
+ * started it); the backend implements exchangeExternalIdentity to turn the verified identity into a backend session.
+ */
+export declare abstract class OidcIdentityCapability<TIdentity extends Identity = Identity> extends IdentityCapability<TIdentity> {
+    protected readonly externalProviders: ExternalIdentityProvider[];
+    constructor(cache: Cache, context: RequestContext, externalProviders: ExternalIdentityProvider[] | undefined);
+    /**
+     * Creates (or finds) the backend customer for a verified external identity and establishes the backend session,
+     * including whatever the backend needs so a guest cart carries over. Returns IdentityConflict when the backend
+     * refuses to link the identity to an existing account.
+     */
+    protected abstract exchangeExternalIdentity(input: ExchangeExternalIdentityInput): Promise<Result<TIdentity, IdentityConflictError>>;
+    listProviders(): Promise<Result<IdentityProvider[]>>;
+    startExternalLogin(payload: IdentityMutationStartExternalLogin): Promise<Result<ExternalLoginRedirect>>;
+    completeExternalLogin(payload: IdentityMutationCompleteExternalLogin): Promise<Result<TIdentity, IdentityConflictError>>;
+}

package/src/client/discovery.d.ts

@@ -0,0 +1,16 @@
+import type { ExternalIdentityProvider } from '../schema/external-identity-provider.schema.js';
+export type OidcMetadata = {
+    /** The value ID tokens must carry in their iss claim. */
+    issuer: string;
+    authorizationEndpoint: string;
+    tokenEndpoint: string;
+    jwksUri: string;
+    endSessionEndpoint?: string;
+};
+export declare function clearDiscoveryCache(): void;
+/**
+ * The endpoints of a provider, from its discovery document. When all three endpoints are configured discovery is
+ * skipped, which is how providers whose discovery URL differs from their issuer (Azure B2C) are supported.
+ * Configured endpoints win over discovered ones; the configured issuer is always the expected iss.
+ */
+export declare function resolveMetadata(provider: ExternalIdentityProvider): Promise<OidcMetadata>;

package/src/client/pkce.d.ts

@@ -0,0 +1,4 @@
+/** A URL-safe random value, used for state, nonce and the PKCE code verifier. */
+export declare function randomToken(byteLength?: number): string;
+/** The S256 code challenge for a code verifier. */
+export declare function codeChallenge(verifier: string): Promise<string>;

package/src/client/relying-party.d.ts

@@ -0,0 +1,31 @@
+import { type JWTPayload } from 'jose';
+import { type ExternalIdentityProvider } from '../schema/external-identity-provider.schema.js';
+import type { OidcMetadata } from './discovery.js';
+export type OidcTokens = {
+    idToken: string;
+    accessToken?: string;
+    refreshToken?: string;
+    expiresIn?: number;
+};
+export type OidcRefreshedTokens = {
+    accessToken: string;
+    /** The identity provider rotates refresh tokens only sometimes; when it does not, the old one stays valid. */
+    refreshToken?: string;
+    idToken?: string;
+    expiresIn?: number;
+};
+export declare function buildAuthorizationUrl(provider: ExternalIdentityProvider, metadata: OidcMetadata, request: {
+    callbackUrl: string;
+    state: string;
+    nonce: string;
+    codeChallenge: string;
+}): string;
+export declare function exchangeCode(provider: ExternalIdentityProvider, metadata: OidcMetadata, request: {
+    code: string;
+    callbackUrl: string;
+    codeVerifier: string;
+}): Promise<OidcTokens>;
+/** Trades a refresh token for a new access token, authenticating the client the same way exchangeCode does. */
+export declare function refreshTokens(provider: ExternalIdentityProvider, metadata: OidcMetadata, refreshToken: string): Promise<OidcRefreshedTokens>;
+/** Verifies signature, issuer, audience, expiry and the nonce, and returns the claims. */
+export declare function verifyIdToken(provider: ExternalIdentityProvider, metadata: OidcMetadata, idToken: string, expectedNonce: string): Promise<JWTPayload>;

package/src/index.d.ts

@@ -0,0 +1,5 @@
+export * from './capabilities/oidc-identity.capability.js';
+export * from './client/discovery.js';
+export * from './client/pkce.js';
+export * from './client/relying-party.js';
+export * from './schema/external-identity-provider.schema.js';

package/src/schema/external-identity-provider.schema.d.ts

@@ -0,0 +1,24 @@
+import * as z from 'zod';
+/** Authorization request parameters that carry the security of the flow or its shape; configuration must not replace them. */
+export declare const RESERVED_AUTHORIZATION_PARAMS: string[];
+export declare const DEFAULT_SCOPES: string[];
+/**
+ * An OpenID Connect identity provider a backend accepts logins from, for backends that cannot list their own.
+ * Defaults (scopes, requireVerifiedEmail) are applied where they are used rather than here, so that this type
+ * can be written as a plain object in a backend's configuration.
+ */
+export declare const ExternalIdentityProviderSchema: z.ZodObject<{
+    key: z.ZodString;
+    displayName: z.ZodString;
+    brand: z.ZodOptional<z.ZodString>;
+    issuer: z.ZodURL;
+    clientId: z.ZodString;
+    clientSecret: z.ZodOptional<z.ZodString>;
+    scopes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    authorizationParams: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    requireVerifiedEmail: z.ZodOptional<z.ZodBoolean>;
+    authorizationEndpoint: z.ZodOptional<z.ZodURL>;
+    tokenEndpoint: z.ZodOptional<z.ZodURL>;
+    jwksUri: z.ZodOptional<z.ZodURL>;
+}, z.core.$loose>;
+export type ExternalIdentityProvider = z.infer<typeof ExternalIdentityProviderSchema>;

package/src/testing/conformance.d.ts

@@ -0,0 +1,16 @@
+import { type IdentityCapability, type RequestContext } from '@reactionary/core';
+import type { ExternalIdentityProvider } from '../schema/external-identity-provider.schema.js';
+export type ExternalLoginConformanceOptions = {
+    /** Name of the backend, for the test titles. */
+    name: string;
+    /**
+     * Builds the backend's identity capability with the given providers, set up so that a verified identity from
+     * the fake provider can be exchanged for a Registered session.
+     */
+    createCapability: (providers: ExternalIdentityProvider[], context: RequestContext) => IdentityCapability;
+};
+/**
+ * The scenarios every backend that uses the shared OpenID Connect client must pass, written against the public
+ * IdentityCapability contract only, so the storefront can rely on identical behaviour.
+ */
+export declare function runExternalLoginConformance(options: ExternalLoginConformanceOptions): void;

package/src/testing/fake-idp.d.ts

@@ -0,0 +1,36 @@
+import { type JWTPayload } from 'jose';
+export type FakeIdTokenTamper = 'signature' | 'audience' | 'issuer' | 'nonce' | 'expired';
+export type FakeApproval = {
+    claims?: JWTPayload;
+    /** Makes the issued ID token invalid in one specific way. */
+    tamper?: FakeIdTokenTamper;
+};
+/**
+ * A local OpenID Connect provider for tests: discovery, JWKS, token endpoint, and signed ID tokens. The shopper's
+ * trip through the provider is simulated by approve(), which returns the callback URL the browser would be sent to.
+ */
+export declare class FakeOidcProvider {
+    private readonly server;
+    private readonly signingKey;
+    private readonly otherKey;
+    private readonly jwk;
+    readonly issuer: string;
+    readonly clientId = "test-client";
+    readonly clientSecret = "test-secret";
+    failTokenEndpoint: boolean;
+    omitAccessToken: boolean;
+    /** Refresh tokens the provider has issued and not yet seen refused. */
+    refreshCalls: number;
+    rotateRefreshToken: boolean;
+    private readonly codes;
+    private constructor();
+    static start(): Promise<FakeOidcProvider>;
+    close(): Promise<void>;
+    /**
+     * What the identity provider does when the shopper opens the authorization URL and signs in: remember the
+     * request and return the callback URL, with code and state, the browser is redirected to.
+     */
+    approve(authorizationUrl: string, approval?: FakeApproval): string;
+    private idToken;
+    private handle;
+}

package/src/testing/index.d.ts

@@ -0,0 +1,2 @@
+export * from './conformance.js';
+export * from './fake-idp.js';

package/testing/conformance.js

@@ -0,0 +1,132 @@
+import { createInitialRequestContext } from "@reactionary/core";
+import { afterAll, assert, beforeAll, beforeEach, describe, expect, it } from "vitest";
+import { clearDiscoveryCache } from "../client/discovery.js";
+import { FakeOidcProvider } from "./fake-idp.js";
+const CALLBACK_URL = "https://shop.example/auth/callback/fake";
+function runExternalLoginConformance(options) {
+  describe(`External login conformance: ${options.name}`, () => {
+    let idp;
+    let provider;
+    let context;
+    let identity;
+    beforeAll(async () => {
+      idp = await FakeOidcProvider.start();
+      provider = {
+        key: "fake",
+        displayName: "Fake IdP",
+        brand: "google",
+        issuer: idp.issuer,
+        clientId: idp.clientId,
+        clientSecret: idp.clientSecret
+      };
+    });
+    afterAll(async () => {
+      await idp.close();
+    });
+    beforeEach(() => {
+      clearDiscoveryCache();
+      idp.failTokenEndpoint = false;
+      context = createInitialRequestContext();
+      identity = options.createCapability([provider], context);
+    });
+    async function start() {
+      const started = await identity.startExternalLogin({ provider: { key: "fake" }, callbackUrl: CALLBACK_URL });
+      assert(started.success);
+      return started.value.location;
+    }
+    function callbackParameters(callbackUrl) {
+      return Object.fromEntries(new URL(callbackUrl).searchParams);
+    }
+    it("offers password login and the configured provider, with its brand", async () => {
+      const providers = await identity.listProviders({});
+      assert(providers.success);
+      expect(providers.value.map((p) => [p.identifier.key, p.flow, p.brand])).toEqual([
+        ["password", "credentials", "email"],
+        ["fake", "redirect", "google"]
+      ]);
+    });
+    it("starts at the identity provider with PKCE and binds the login to the session", async () => {
+      const location = new URL(await start());
+      expect(location.origin).toBe(idp.issuer);
+      expect(location.searchParams.get("code_challenge_method")).toBe("S256");
+      expect(location.searchParams.get("redirect_uri")).toBe(CALLBACK_URL);
+      expect(context.session.identityContext.pendingExternalLogin?.provider).toBe("fake");
+    });
+    it("completes a login and returns a registered identity", async () => {
+      const callback = idp.approve(await start());
+      const completed = await identity.completeExternalLogin({
+        provider: { key: "fake" },
+        callbackUrl: CALLBACK_URL,
+        callbackParameters: callbackParameters(callback)
+      });
+      assert(completed.success);
+      expect(completed.value.type).toBe("Registered");
+      expect(context.session.identityContext.identity.type).toBe("Registered");
+      expect(context.session.identityContext.pendingExternalLogin).toBeUndefined();
+    });
+    it("rejects a callback whose state this session did not issue", async () => {
+      const callback = idp.approve(await start());
+      const completed = await identity.completeExternalLogin({
+        provider: { key: "fake" },
+        callbackUrl: CALLBACK_URL,
+        callbackParameters: { ...callbackParameters(callback), state: "forged" }
+      });
+      assert(!completed.success);
+      expect(completed.error.type).toBe("InvalidInput");
+    });
+    it("rejects a callback that is replayed", async () => {
+      const callback = idp.approve(await start());
+      const parameters = callbackParameters(callback);
+      await identity.completeExternalLogin({ provider: { key: "fake" }, callbackUrl: CALLBACK_URL, callbackParameters: parameters });
+      const replay = await identity.completeExternalLogin({ provider: { key: "fake" }, callbackUrl: CALLBACK_URL, callbackParameters: parameters });
+      assert(!replay.success);
+    });
+    it("rejects a login the shopper abandoned at the identity provider", async () => {
+      const callback = new URL(idp.approve(await start()));
+      const completed = await identity.completeExternalLogin({
+        provider: { key: "fake" },
+        callbackUrl: CALLBACK_URL,
+        callbackParameters: { state: callback.searchParams.get("state") ?? "", error: "access_denied" }
+      });
+      assert(!completed.success);
+      expect(completed.error.type).toBe("InvalidInput");
+    });
+    it("rejects an unknown provider", async () => {
+      const started = await identity.startExternalLogin({ provider: { key: "nope" }, callbackUrl: CALLBACK_URL });
+      assert(!started.success);
+      expect(started.error.type).toBe("InvalidInput");
+    });
+    it.each(["signature", "audience", "issuer", "nonce", "expired"])("rejects an ID token with a bad %s", async (tamper) => {
+      const callback = idp.approve(await start(), { tamper });
+      const completed = await identity.completeExternalLogin({
+        provider: { key: "fake" },
+        callbackUrl: CALLBACK_URL,
+        callbackParameters: callbackParameters(callback)
+      });
+      assert(!completed.success);
+      expect(context.session.identityContext.identity.type).not.toBe("Registered");
+    });
+    it("rejects an unverified email", async () => {
+      const callback = idp.approve(await start(), { claims: { email_verified: false } });
+      const completed = await identity.completeExternalLogin({
+        provider: { key: "fake" },
+        callbackUrl: CALLBACK_URL,
+        callbackParameters: callbackParameters(callback)
+      });
+      assert(!completed.success);
+    });
+    it("fails when the identity provider refuses the authorization code", async () => {
+      const callback = idp.approve(await start());
+      idp.failTokenEndpoint = true;
+      const completed = await identity.completeExternalLogin({
+        provider: { key: "fake" },
+        callbackUrl: CALLBACK_URL,
+        callbackParameters: callbackParameters(callback)
+      });
+      assert(!completed.success);
+    });
+  });
+}
+export {
+  runExternalLoginConformance
+};

package/testing/fake-idp.js

@@ -0,0 +1,138 @@
+import { createServer } from "node:http";
+import { createHash } from "node:crypto";
+import { SignJWT, exportJWK, generateKeyPair } from "jose";
+const KEY_ID = "fake-idp-key";
+class FakeOidcProvider {
+  constructor(server, signingKey, otherKey, jwk, issuer) {
+    this.server = server;
+    this.signingKey = signingKey;
+    this.otherKey = otherKey;
+    this.jwk = jwk;
+    this.issuer = issuer;
+  }
+  server;
+  signingKey;
+  otherKey;
+  jwk;
+  issuer;
+  clientId = "test-client";
+  clientSecret = "test-secret";
+  failTokenEndpoint = false;
+  omitAccessToken = false;
+  /** Refresh tokens the provider has issued and not yet seen refused. */
+  refreshCalls = 0;
+  rotateRefreshToken = false;
+  codes = /* @__PURE__ */ new Map();
+  static async start() {
+    const { publicKey, privateKey } = await generateKeyPair("RS256");
+    const other = await generateKeyPair("RS256");
+    const jwk = { ...await exportJWK(publicKey), kid: KEY_ID, alg: "RS256", use: "sig" };
+    const server = createServer();
+    await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
+    const { port } = server.address();
+    const provider = new FakeOidcProvider(server, privateKey, other.privateKey, jwk, `http://127.0.0.1:${port}`);
+    server.on("request", (req, res) => {
+      void provider.handle(req.method ?? "GET", req.url ?? "/", req, res);
+    });
+    return provider;
+  }
+  async close() {
+    await new Promise((resolve) => this.server.close(() => resolve()));
+  }
+  /**
+   * What the identity provider does when the shopper opens the authorization URL and signs in: remember the
+   * request and return the callback URL, with code and state, the browser is redirected to.
+   */
+  approve(authorizationUrl, approval = {}) {
+    const url = new URL(authorizationUrl);
+    const params = url.searchParams;
+    if (url.origin !== this.issuer || url.pathname !== "/authorize") {
+      throw new Error(`Not an authorization URL of this provider: ${authorizationUrl}`);
+    }
+    if (params.get("code_challenge_method") !== "S256" || params.get("response_type") !== "code") {
+      throw new Error("The authorization request must use the code flow with PKCE S256");
+    }
+    const code = `code-${this.codes.size + 1}`;
+    this.codes.set(code, {
+      clientId: params.get("client_id") ?? "",
+      redirectUri: params.get("redirect_uri") ?? "",
+      codeChallenge: params.get("code_challenge") ?? "",
+      nonce: params.get("nonce") ?? "",
+      approval: { claims: approval.claims ?? {}, ...approval.tamper ? { tamper: approval.tamper } : {} }
+    });
+    const callback = new URL(params.get("redirect_uri") ?? "");
+    callback.searchParams.set("code", code);
+    callback.searchParams.set("state", params.get("state") ?? "");
+    return callback.toString();
+  }
+  async idToken(issued) {
+    const tamper = issued.approval.tamper;
+    const now = Math.floor(Date.now() / 1e3);
+    const claims = {
+      sub: "user-1",
+      email: "ada@example.com",
+      email_verified: true,
+      name: "Ada Lovelace",
+      given_name: "Ada",
+      family_name: "Lovelace",
+      ...issued.approval.claims,
+      nonce: tamper === "nonce" ? "someone-elses-nonce" : issued.nonce
+    };
+    return new SignJWT(claims).setProtectedHeader({ alg: "RS256", kid: KEY_ID }).setIssuer(tamper === "issuer" ? "https://evil.example" : this.issuer).setAudience(tamper === "audience" ? "another-client" : issued.clientId).setIssuedAt(tamper === "expired" ? now - 7200 : now).setExpirationTime(tamper === "expired" ? now - 3600 : now + 300).sign(tamper === "signature" ? this.otherKey : this.signingKey);
+  }
+  async handle(method, path, req, res) {
+    const send = (status, body) => {
+      res.statusCode = status;
+      res.setHeader("content-type", "application/json");
+      res.end(JSON.stringify(body));
+    };
+    if (path === "/.well-known/openid-configuration") {
+      return send(200, {
+        issuer: this.issuer,
+        authorization_endpoint: `${this.issuer}/authorize`,
+        token_endpoint: `${this.issuer}/token`,
+        jwks_uri: `${this.issuer}/jwks`,
+        end_session_endpoint: `${this.issuer}/logout`
+      });
+    }
+    if (path === "/jwks") {
+      return send(200, { keys: [this.jwk] });
+    }
+    if (path === "/token" && method === "POST") {
+      const chunks = [];
+      for await (const chunk of req) {
+        chunks.push(chunk);
+      }
+      const form = new URLSearchParams(Buffer.concat(chunks).toString("utf8"));
+      if (form.get("grant_type") === "refresh_token") {
+        this.refreshCalls += 1;
+        if (this.failTokenEndpoint || form.get("refresh_token") !== "refresh-token" || form.get("client_id") !== this.clientId) {
+          return send(400, { error: "invalid_grant" });
+        }
+        return send(200, {
+          token_type: "Bearer",
+          access_token: `access-token-${this.refreshCalls + 1}`,
+          expires_in: 300,
+          ...this.rotateRefreshToken ? { refresh_token: "refresh-token" } : {}
+        });
+      }
+      const issued = this.codes.get(form.get("code") ?? "");
+      this.codes.delete(form.get("code") ?? "");
+      const challenge = createHash("sha256").update(form.get("code_verifier") ?? "").digest("base64url");
+      if (this.failTokenEndpoint || !issued || form.get("client_id") !== issued.clientId || form.get("redirect_uri") !== issued.redirectUri || challenge !== issued.codeChallenge || form.has("client_secret") && form.get("client_secret") !== this.clientSecret) {
+        return send(400, { error: "invalid_grant" });
+      }
+      return send(200, {
+        token_type: "Bearer",
+        ...this.omitAccessToken ? {} : { access_token: "access-token" },
+        refresh_token: "refresh-token",
+        expires_in: 300,
+        id_token: await this.idToken(issued)
+      });
+    }
+    send(404, { error: "not_found" });
+  }
+}
+export {
+  FakeOidcProvider
+};

package/testing/index.js

@@ -0,0 +1,2 @@
+export * from "./conformance.js";
+export * from "./fake-idp.js";