@coffre/core 0.0.0 → 0.1.1

package/src/identity/signin/github.ts

@@ -0,0 +1,191 @@
+import * as oauth from 'oauth4webapi';
+
+import type { GitHubProviderConfig } from './config.ts';
+import {
+  SigninError,
+  type PendingSignin,
+  type ProviderOptions,
+  type SigninBrand,
+  type SigninProfile,
+  type SigninProvider,
+} from './types.ts';
+
+type GitHubUser = { id: number; login: string; name: string | null };
+type GitHubEmail = { email: string; primary: boolean; verified: boolean };
+
+/**
+ * GitHub's OAuth web flow, which is OAuth 2.0 without OpenID Connect: no ID
+ * token, so the profile comes from the REST API with the access token the
+ * code is exchanged for. That token is used for these two or three calls and
+ * then dropped; coffre never stores it.
+ *
+ * Works with an OAuth App or a GitHub App's user authorization, on github.com
+ * or GitHub Enterprise Server.
+ */
+export class GitHubSigninProvider implements SigninProvider {
+  readonly id: string;
+  readonly issuer: string;
+  readonly label: string;
+  readonly brand: SigninBrand;
+  /** What it was made from, as checked. */
+  readonly config: GitHubProviderConfig;
+  readonly #fetch: typeof fetch;
+
+  constructor(config: GitHubProviderConfig, options: ProviderOptions = {}) {
+    this.id = config.id;
+    this.issuer = config.apiUrl;
+    this.label = config.label;
+    this.brand = config.brand;
+    this.config = config;
+    this.#fetch = options.fetch ?? ((input, init) => fetch(input, init));
+  }
+
+  async start(redirectUri: string, options: { loginHint?: string } = {}) {
+    const pending: PendingSignin = {
+      state: oauth.generateRandomState(),
+      codeVerifier: oauth.generateRandomCodeVerifier(),
+      nonce: null,
+    };
+
+    const url = new URL(`${this.config.webUrl}/login/oauth/authorize`);
+    const params = url.searchParams;
+    params.set('client_id', this.config.clientId);
+    params.set('redirect_uri', redirectUri);
+    // `read:org` lets the membership check see private memberships; without
+    // it, GitHub only reports members who made theirs public.
+    params.set('scope', this.config.organization ? 'read:user user:email read:org' : 'read:user user:email');
+    params.set('state', pending.state);
+    params.set('code_challenge', await oauth.calculatePKCECodeChallenge(pending.codeVerifier));
+    params.set('code_challenge_method', 'S256');
+    params.set('allow_signup', 'false');
+    if (options.loginHint !== undefined) params.set('login', options.loginHint);
+
+    return { url, pending };
+  }
+
+  async finish(callbackUrl: URL, redirectUri: string, pending: PendingSignin): Promise<SigninProfile> {
+    const label = this.config.label;
+    const query = callbackUrl.searchParams;
+
+    if (query.get('state') !== pending.state) {
+      throw new SigninError('state_mismatch', `the ${label} callback does not match this sign-in`);
+    }
+    const refused = query.get('error');
+    if (refused !== null) {
+      throw new SigninError('provider_denied', `${label} refused the sign-in: ${refused}`);
+    }
+    const code = query.get('code');
+    if (code === null || code === '') {
+      throw new SigninError('invalid_response', `the ${label} callback carries no code`);
+    }
+
+    const token = await this.#exchange(code, redirectUri, pending.codeVerifier);
+    const user = await this.#api<GitHubUser>(token, '/user');
+    if (typeof user?.id !== 'number') {
+      throw new SigninError('invalid_response', `${label} did not say who signed in`);
+    }
+
+    const organization = this.config.organization;
+    if (organization !== null && !(await this.#isMember(token, organization))) {
+      throw new SigninError(
+        'not_in_organization',
+        `only members of the ${organization} organization may sign in with ${label}`,
+      );
+    }
+
+    const listed = await this.#api<GitHubEmail[]>(token, '/user/emails');
+    const emails = (Array.isArray(listed) ? listed : [])
+      .filter((entry) => entry.verified && typeof entry.email === 'string')
+      .sort((a, b) => Number(b.primary) - Number(a.primary))
+      .map((entry) => entry.email.trim().toLowerCase());
+
+    return {
+      subject: String(user.id),
+      emails: [...new Set(emails)],
+      name: user.name ?? user.login,
+    };
+  }
+
+  async #exchange(code: string, redirectUri: string, codeVerifier: string): Promise<string> {
+    const label = this.config.label;
+    const response = await this.#send(`${this.config.webUrl}/login/oauth/access_token`, {
+      method: 'POST',
+      headers: {
+        accept: 'application/json',
+        'content-type': 'application/x-www-form-urlencoded',
+      },
+      body: new URLSearchParams({
+        client_id: this.config.clientId,
+        client_secret: this.config.clientSecret,
+        code,
+        redirect_uri: redirectUri,
+        code_verifier: codeVerifier,
+      }),
+    });
+    // GitHub reports a bad code with a 200 and an `error` field.
+    const body = (await readJson(response)) as { access_token?: unknown; error?: unknown } | null;
+    if (!response.ok || body === null) {
+      throw new SigninError('invalid_response', `${label} answered the code exchange with ${response.status}`);
+    }
+    if (typeof body.error === 'string') {
+      throw new SigninError('provider_denied', `${label} refused the code: ${body.error}`);
+    }
+    if (typeof body.access_token !== 'string' || body.access_token === '') {
+      throw new SigninError('invalid_response', `${label} returned no access token`);
+    }
+    return body.access_token;
+  }
+
+  async #isMember(token: string, organization: string): Promise<boolean> {
+    const response = await this.#send(
+      `${this.config.apiUrl}/user/memberships/orgs/${encodeURIComponent(organization)}`,
+      { headers: apiHeaders(token) },
+    );
+    if (response.status === 404 || response.status === 403) return false;
+    const body = (await readJson(response)) as { state?: unknown } | null;
+    if (!response.ok || body === null) {
+      throw new SigninError('invalid_response', `${this.config.label} answered the membership check with ${response.status}`);
+    }
+    return body.state === 'active';
+  }
+
+  async #api<T>(token: string, path: string): Promise<T | null> {
+    const response = await this.#send(`${this.config.apiUrl}${path}`, {
+      headers: apiHeaders(token),
+    });
+    if (!response.ok) {
+      throw new SigninError('invalid_response', `${this.config.label} answered ${path} with ${response.status}`);
+    }
+    return (await readJson(response)) as T | null;
+  }
+
+  // A redirect is never followed: callers treat any answer other than a 2xx,
+  // a 3xx included, as one coffre cannot trust. Workers only offer 'follow'
+  // and 'manual'; 'error' throws there before any request is made.
+  async #send(url: string, init: RequestInit): Promise<Response> {
+    try {
+      return await this.#fetch(url, { ...init, redirect: 'manual', signal: AbortSignal.timeout(10_000) });
+    } catch (cause) {
+      const error = new SigninError('provider_unavailable', `${this.config.label} could not be reached`);
+      (error as Error & { cause?: unknown }).cause = cause;
+      throw error;
+    }
+  }
+}
+
+function apiHeaders(token: string): Record<string, string> {
+  return {
+    accept: 'application/vnd.github+json',
+    authorization: `Bearer ${token}`,
+    'user-agent': 'coffre',
+    'x-github-api-version': '2022-11-28',
+  };
+}
+
+async function readJson(response: Response): Promise<unknown> {
+  try {
+    return await response.json();
+  } catch {
+    return null;
+  }
+}

package/src/identity/signin/index.ts

@@ -0,0 +1,5 @@
+export * from './config.ts';
+export * from './types.ts';
+export { GitHubSigninProvider } from './github.ts';
+export { OidcSigninProvider } from './oidc.ts';
+export { deriveKey, seal, unseal } from './sealed.ts';

package/src/identity/signin/oidc.ts

@@ -0,0 +1,199 @@
+import * as oauth from 'oauth4webapi';
+
+import type { OidcProviderConfig } from './config.ts';
+import {
+  SigninError,
+  type PendingSignin,
+  type ProviderOptions,
+  type SigninBrand,
+  type SigninProfile,
+  type SigninProvider,
+} from './types.ts';
+
+/** Discovery documents change rarely; an hour keeps one fetch off every sign-in. */
+const DISCOVERY_TTL_MS = 60 * 60 * 1000;
+
+type Discovered = { server: oauth.AuthorizationServer; fetchedAt: number };
+
+/**
+ * The authorization code flow with PKCE, against any OpenID Connect issuer.
+ *
+ * Protocol work is delegated to oauth4webapi: discovery with issuer
+ * validation, the RFC 9207 `iss` check on the callback, the token request and
+ * ID token claim validation (issuer, audience, expiry, nonce). The ID token is
+ * received straight from the token endpoint over TLS with client
+ * authentication, which OpenID Connect Core 3.1.3.7 accepts in place of
+ * checking its signature.
+ */
+export class OidcSigninProvider implements SigninProvider {
+  readonly id: string;
+  readonly issuer: string;
+  readonly label: string;
+  readonly brand: SigninBrand;
+  /** What it was made from, as checked. */
+  readonly config: OidcProviderConfig;
+  readonly #fetch: typeof fetch | undefined;
+  readonly #insecure: boolean;
+  #discovered: Discovered | null = null;
+
+  constructor(config: OidcProviderConfig, options: ProviderOptions = {}) {
+    this.id = config.id;
+    this.issuer = config.issuer;
+    this.label = config.label;
+    this.brand = config.brand;
+    this.config = config;
+    this.#fetch = options.fetch;
+    // Only ever true for the dev IdP: config rejects plain HTTP off loopback.
+    this.#insecure = new URL(config.issuer).protocol === 'http:';
+  }
+
+  #http<Method, Body = undefined>(): oauth.HttpRequestOptions<Method, Body> {
+    const options: oauth.HttpRequestOptions<Method, Body> = {
+      signal: () => AbortSignal.timeout(10_000),
+    };
+    if (this.#fetch !== undefined) {
+      const fetchImpl = this.#fetch;
+      options[oauth.customFetch] = (url, init) => fetchImpl(url, init as RequestInit);
+    }
+    if (this.#insecure) options[oauth.allowInsecureRequests] = true;
+    return options;
+  }
+
+  get #client(): oauth.Client {
+    return { client_id: this.config.clientId };
+  }
+
+  async #server(): Promise<oauth.AuthorizationServer> {
+    if (this.#discovered !== null && Date.now() - this.#discovered.fetchedAt < DISCOVERY_TTL_MS) {
+      return this.#discovered.server;
+    }
+    const issuer = new URL(this.config.issuer);
+    let server: oauth.AuthorizationServer;
+    try {
+      const response = await oauth.discoveryRequest(issuer, { ...this.#http<'GET'>(), algorithm: 'oidc' });
+      server = await oauth.processDiscoveryResponse(issuer, response);
+    } catch (error) {
+      throw unavailable(this.config.label, error);
+    }
+    this.#discovered = { server, fetchedAt: Date.now() };
+    return server;
+  }
+
+  async start(redirectUri: string, options: { loginHint?: string } = {}) {
+    const server = await this.#server();
+    if (server.authorization_endpoint === undefined) {
+      throw new SigninError(
+        'invalid_response',
+        `${this.config.label} publishes no authorization endpoint`,
+      );
+    }
+
+    const pending: PendingSignin = {
+      state: oauth.generateRandomState(),
+      codeVerifier: oauth.generateRandomCodeVerifier(),
+      nonce: oauth.generateRandomNonce(),
+    };
+
+    const url = new URL(server.authorization_endpoint);
+    const params = url.searchParams;
+    params.set('client_id', this.config.clientId);
+    params.set('redirect_uri', redirectUri);
+    params.set('response_type', 'code');
+    params.set('scope', this.config.scopes.join(' '));
+    params.set('state', pending.state);
+    params.set('nonce', pending.nonce as string);
+    params.set('code_challenge', await oauth.calculatePKCECodeChallenge(pending.codeVerifier));
+    params.set('code_challenge_method', 'S256');
+    for (const [name, value] of Object.entries(this.config.authorizationParams)) {
+      params.set(name, value);
+    }
+    if (options.loginHint !== undefined) params.set('login_hint', options.loginHint);
+
+    return { url, pending };
+  }
+
+  async finish(callbackUrl: URL, redirectUri: string, pending: PendingSignin): Promise<SigninProfile> {
+    const server = await this.#server();
+    const label = this.config.label;
+
+    let params: URLSearchParams;
+    try {
+      params = oauth.validateAuthResponse(server, this.#client, callbackUrl, pending.state);
+    } catch (error) {
+      if (error instanceof oauth.AuthorizationResponseError) {
+        throw new SigninError('provider_denied', `${label} refused the sign-in: ${error.error}`);
+      }
+      throw new SigninError('state_mismatch', `the ${label} callback does not match this sign-in`);
+    }
+
+    let claims: oauth.IDToken;
+    try {
+      const response = await oauth.authorizationCodeGrantRequest(
+        server,
+        this.#client,
+        oauth.ClientSecretPost(this.config.clientSecret),
+        params,
+        redirectUri,
+        pending.codeVerifier,
+        this.#http<'POST', URLSearchParams>(),
+      );
+      const result = await oauth.processAuthorizationCodeResponse(server, this.#client, response, {
+        expectedNonce: pending.nonce ?? oauth.expectNoNonce,
+        requireIdToken: true,
+      });
+      claims = oauth.getValidatedIdTokenClaims(result) as oauth.IDToken;
+    } catch (error) {
+      if (error instanceof SigninError) throw error;
+      if (error instanceof oauth.ResponseBodyError) {
+        throw new SigninError('provider_denied', `${label} refused the code: ${error.error}`);
+      }
+      if (isNetworkError(error)) throw unavailable(label, error);
+      throw new SigninError('invalid_response', `${label} returned a token coffre cannot trust`);
+    }
+
+    return this.#profile(claims);
+  }
+
+  #profile(claims: oauth.IDToken): SigninProfile {
+    const label = this.config.label;
+
+    if (this.config.hostedDomain !== null && claims.hd !== this.config.hostedDomain) {
+      throw new SigninError(
+        'wrong_domain',
+        `only ${this.config.hostedDomain} accounts may sign in with ${label}`,
+      );
+    }
+
+    const email = typeof claims.email === 'string' ? claims.email.trim().toLowerCase() : '';
+    // Generic OIDC must prove address ownership. Google is authoritative for
+    // Gmail and Workspace, but a third-party address can since have changed hands.
+    // https://developers.google.com/identity/sign-in/web/backend-auth
+    const authoritative = this.config.brand !== 'google'
+      || email.endsWith('@gmail.com')
+      || (typeof claims.hd === 'string' && claims.hd !== '');
+    // Entra says email and preferred_username must not authorize access.
+    // Link its subject while signed in through another provider instead.
+    // https://learn.microsoft.com/en-us/entra/identity-platform/id-token-claims-reference
+    const emails = email !== '' && claims.email_verified === true
+      && authoritative && this.config.brand !== 'microsoft' ? [email] : [];
+
+    return {
+      subject: claims.sub,
+      emails,
+      name: typeof claims.name === 'string' ? claims.name : null,
+    };
+  }
+}
+
+function isNetworkError(error: unknown): boolean {
+  return (
+    error instanceof TypeError ||
+    (error instanceof Error && (error.name === 'TimeoutError' || error.name === 'AbortError'))
+  );
+}
+
+function unavailable(label: string, cause: unknown): SigninError {
+  const error = new SigninError('provider_unavailable', `${label} could not be reached`);
+  (error as Error & { cause?: unknown }).cause = cause;
+  return error;
+}

package/src/identity/signin/sealed.ts

@@ -0,0 +1,55 @@
+import { createCipheriv, createDecipheriv, hkdfSync, randomBytes } from 'node:crypto';
+
+const IV_BYTES = 12;
+const TAG_BYTES = 16;
+const VERSION = 'v1';
+
+/**
+ * Derive a purpose-bound key from one of coffre's existing 32-byte secrets.
+ *
+ * HKDF with a distinct `info` string gives a key that is independent of the
+ * source for every practical purpose, so the sign-in cookie needs no new
+ * secret to provision and a leak of one derived key says nothing about the
+ * others.
+ */
+export function deriveKey(secret: Uint8Array, purpose: string): Buffer {
+  return Buffer.from(hkdfSync('sha256', secret, Buffer.alloc(0), `coffre/${purpose}`, 32));
+}
+
+/**
+ * Encrypt a small JSON value for a round trip through the browser.
+ *
+ * AES-256-GCM authenticates as well as hides, so a tampered or forged value
+ * fails to open rather than decoding into something else. The expiry sits
+ * inside the ciphertext, which keeps an old cookie from being replayed past
+ * it even by a client that ignores Max-Age.
+ */
+export function seal(key: Uint8Array, value: unknown, ttlSeconds: number, now = Date.now()): string {
+  const iv = randomBytes(IV_BYTES);
+  const cipher = createCipheriv('aes-256-gcm', key, iv);
+  cipher.setAAD(Buffer.from(VERSION));
+  const plaintext = Buffer.from(JSON.stringify({ exp: now + ttlSeconds * 1000, value }));
+  const ciphertext = Buffer.concat([cipher.update(plaintext), cipher.final()]);
+  return `${VERSION}.${Buffer.concat([iv, cipher.getAuthTag(), ciphertext]).toString('base64url')}`;
+}
+
+/** The sealed value, or null when it is malformed, forged, tampered with or expired. */
+export function unseal<T>(key: Uint8Array, sealed: string | undefined | null, now = Date.now()): T | null {
+  if (!sealed?.startsWith(`${VERSION}.`)) return null;
+  const raw = Buffer.from(sealed.slice(VERSION.length + 1), 'base64url');
+  if (raw.length <= IV_BYTES + TAG_BYTES) return null;
+  try {
+    const decipher = createDecipheriv('aes-256-gcm', key, raw.subarray(0, IV_BYTES));
+    decipher.setAAD(Buffer.from(VERSION));
+    decipher.setAuthTag(raw.subarray(IV_BYTES, IV_BYTES + TAG_BYTES));
+    const plaintext = Buffer.concat([
+      decipher.update(raw.subarray(IV_BYTES + TAG_BYTES)),
+      decipher.final(),
+    ]);
+    const parsed = JSON.parse(plaintext.toString('utf8')) as { exp?: unknown; value?: unknown };
+    if (typeof parsed.exp !== 'number' || parsed.exp <= now) return null;
+    return parsed.value as T;
+  } catch {
+    return null;
+  }
+}

package/src/identity/signin/types.ts

@@ -0,0 +1,94 @@
+/**
+ * What a provider reports about the person who just signed in.
+ *
+ * `subject` is the provider's permanent id for the account: OIDC's `sub`,
+ * GitHub's numeric user id. coffre binds to it and to nothing else, since a
+ * login name can be renamed and an email address can be handed to someone new.
+ */
+export type SigninProfile = {
+  subject: string;
+  /** Verified addresses only, lowercased, the provider's primary first. */
+  emails: string[];
+  name: string | null;
+};
+
+/**
+ * What must survive the round trip through the provider: the anti-CSRF
+ * state, the PKCE verifier and, for OIDC, the nonce. coffre keeps it in an
+ * encrypted, short-lived cookie rather than in the database, so an
+ * unauthenticated visitor cannot make coffre write anything.
+ */
+export type PendingSignin = {
+  state: string;
+  codeVerifier: string;
+  nonce: string | null;
+};
+
+export type SigninErrorCode =
+  /** The person cancelled, or the provider refused them. */
+  | 'provider_denied'
+  /** The callback does not belong to the sign-in this browser started. */
+  | 'state_mismatch'
+  /** The provider answered, but not in a way that can be trusted. */
+  | 'invalid_response'
+  /** The provider could not be reached. */
+  | 'provider_unavailable'
+  /** The account has no verified email address to match an invitation with. */
+  | 'no_verified_email'
+  /** A Google account outside the configured Workspace domain. */
+  | 'wrong_domain'
+  /** A GitHub account outside the configured organization. */
+  | 'not_in_organization';
+
+export class SigninError extends Error {
+  readonly code: SigninErrorCode;
+  constructor(code: SigninErrorCode, message: string) {
+    super(message);
+    this.code = code;
+  }
+}
+
+export type ProviderOptions = {
+  /** Injected by tests; defaults to globalThis.fetch. */
+  fetch?: typeof fetch;
+};
+
+/** Which mark the sign-in button carries: GitHub's, Google's, Microsoft's, or a plain key. */
+export type SigninBrand = 'github' | 'google' | 'microsoft' | 'oidc';
+
+/**
+ * A way to sign in: send the browser to whoever knows the person, and take
+ * back who they are. `github()`, `google()`, `microsoft()` and `oidc()` make
+ * one; so can a deployment, for a provider that is none of those. coffre
+ * does everything around it: the pending state, sealed in a cookie between
+ * the two calls, binding the profile to a member, sessions, CLI logins and
+ * service tokens.
+ *
+ *   const acme: SigninProvider = {
+ *     id: 'acme',
+ *     issuer: 'https://sso.acme.example',
+ *     label: 'Acme SSO',
+ *     brand: 'oidc',
+ *     async start(redirectUri) { … return { url, pending: { state, codeVerifier, nonce: null } }; },
+ *     async finish(callbackUrl, redirectUri, pending) { … return { subject, emails, name }; },
+ *   };
+ */
+export interface SigninProvider {
+  /** Stable: part of the callback URL, `/auth/callback/{id}`, and of every account bound through it. */
+  readonly id: string;
+  /** The authority whose subjects these are; changing it requires linking accounts again. */
+  readonly issuer: string;
+  /** Button text: "Continue with {label}". */
+  readonly label: string;
+  readonly brand: SigninBrand;
+  /** Where to send the browser, and what to remember until it comes back. */
+  start(redirectUri: string, options?: { loginHint?: string }): Promise<{
+    url: URL;
+    pending: PendingSignin;
+  }>;
+  /**
+   * The person back from the provider, verified: check the callback against
+   * `pending`, and throw a SigninError for anything that does not hold.
+   */
+  finish(callbackUrl: URL, redirectUri: string, pending: PendingSignin): Promise<SigninProfile>;
+}

package/src/identity/tokens.ts

@@ -0,0 +1,45 @@
+import { createHash, randomBytes } from 'node:crypto';
+
+/**
+ * Bearer credentials coffre issues itself: browser sessions, CLI sessions and
+ * service tokens.
+ *
+ * A token is a kind prefix and 32 random bytes, e.g.
+ * `coffre_cli_Qm9Y...`. The prefix tells a person (or a secret scanner) what a
+ * leaked string is; the database stores only its SHA-256, which is enough
+ * for lookups and useless to anyone who reads the table. A plain hash is the
+ * right tool here, unlike for passwords: 256 bits of randomness leave nothing
+ * to brute-force.
+ */
+export type CredentialKind = 'browser' | 'cli' | 'service';
+
+const PREFIX: Record<CredentialKind, string> = {
+  browser: 'coffre_web_',
+  cli: 'coffre_cli_',
+  service: 'coffre_svc_',
+};
+
+const TOKEN = /^coffre_(web|cli|svc)_[A-Za-z0-9_-]{43}$/;
+
+export function generateToken(kind: CredentialKind): string {
+  return PREFIX[kind] + randomBytes(32).toString('base64url');
+}
+
+/** Whether a string has the shape of a coffre token, before any lookup. */
+export function isCoffreToken(value: string): boolean {
+  return TOKEN.test(value);
+}
+
+export function hashToken(token: string): Buffer {
+  return createHash('sha256').update(token, 'utf8').digest();
+}
+
+/**
+ * Enough of a token to recognize it in a list, never enough to use it: the
+ * kind prefix and the last four characters. The prefix is matched rather than
+ * cut at the last underscore, because base64url uses `_` too.
+ */
+export function tokenHint(token: string): string {
+  const prefix = Object.values(PREFIX).find((candidate) => token.startsWith(candidate)) ?? '';
+  return `${prefix}…${token.slice(-4)}`;
+}

package/src/identity/types.ts

@@ -0,0 +1,51 @@
+/**
+ * An authenticated caller.
+ *
+ * Modelled as a tagged union rather than "a user with an optional email",
+ * because Cloudflare Access issues two structurally different tokens:
+ *
+ *   identity token  -> sub = user uuid, email = "admin@acme.example"
+ *   service token   -> sub = ""       , common_name = "<client-id>.access", NO email
+ *
+ * Machine callers (external-secrets, CI) are most of the real traffic, so the
+ * shape that cannot represent them is the wrong shape.
+ */
+export type Principal =
+  | {
+      type: 'user';
+      /** Stable identifier used in grants and in the audit log. */
+      id: string;
+      email: string;
+      subject: string;
+    }
+  | {
+      type: 'service';
+      /** Stable identifier used in grants and in the audit log. */
+      id: string;
+      commonName: string;
+    };
+
+/**
+ * Verifies a bearer token and returns the caller it identifies.
+ *
+ * Cloudflare mode verifies Access JWTs against the team domain; signin mode
+ * looks up coffre's own credentials.
+ */
+export interface IdentityVerifier {
+  verify(token: string, request?: { sourceIp: string | null }): Promise<Principal>;
+}
+
+/** Access delivers the JWT to the origin in this header. */
+export const ACCESS_JWT_HEADER = 'cf-access-jwt-assertion';
+
+/** Where Access JWTs are checked: the team's keys, and the application's AUD tag. */
+export type AccessVerifierConfig = {
+  /** Cloudflare Access team domain, e.g. https://acme.cloudflareaccess.com */
+  issuer: string;
+  /** Usually `${issuer}/cdn-cgi/access/certs`. */
+  jwksUrl: string;
+  /** The AUD tag of the specific Access application. */
+  audience: string;
+  /** Seconds of clock skew tolerated. Kept at 0 by default deliberately. */
+  clockToleranceSeconds?: number;
+};