@everystack/auth 0.1.0

package/src/jwt/index.ts

@@ -0,0 +1,182 @@
+/**
+ * @everystack/auth/jwt — runtime-agnostic HS256 JWT, zero runtime deps.
+ *
+ * Design contract (see __tests__/jwt/fixtures/vectors.ts for binding details):
+ *   - Algorithm: HS256, fixed. Verify rejects every other `alg` including 'none'.
+ *   - Header: literal `{"alg":"HS256","typ":"JWT"}` — no variation.
+ *   - base64url: RFC 4648 §5, no padding.
+ *   - exp: integer epoch seconds, REQUIRED on verify (with optional clock skew).
+ *   - The library does not own the claim shape. Pass a TClaims generic and
+ *     getSubject/getRole accessors to support legacy payloads.
+ */
+
+import type { HmacFn } from './hmac';
+
+const HEADER_JSON = '{"alg":"HS256","typ":"JWT"}';
+const HEADER_B64 = base64urlEncode(textEncode(HEADER_JSON));
+
+export interface JwtConfig<TClaims extends Record<string, unknown> = Record<string, unknown>> {
+  /** HMAC signing key. String is UTF-8 encoded. */
+  secret: string | Uint8Array;
+  /** HMAC adapter. Required — pick hmacNode or hmacWeb. */
+  hmac: HmacFn;
+  /** Token lifetime in seconds. Default 3600. Used when sign() auto-fills `exp`. */
+  ttlSec?: number;
+  /** Allowed clock skew on verify, seconds. Default 30. */
+  clockSkewSec?: number;
+  /** Whether sign() should auto-add a `jti` claim. Default true. */
+  includeJti?: boolean;
+  /** Claim name used to read subject. Default 'sub'. */
+  getSubject?: (claims: TClaims) => string;
+  /** Claim name used to read role. Default reads `claims.role`. */
+  getRole?: (claims: TClaims) => string;
+  /** Claim used as expiry (epoch seconds). Default reads `claims.exp`. */
+  getExpiry?: (claims: TClaims) => number | undefined;
+  /**
+   * If true, sign() does not reorder/inject keys — the JSON.stringify of
+   * the claims object is used verbatim. Required for byte-identical tokens
+   * across implementations.
+   */
+  canonical?: boolean;
+}
+
+export interface SignOptions {
+  /**
+   * Skip auto-filling iat/exp/jti. The claims object is signed as-is.
+   * Used when the caller (or SQL) controls timestamps.
+   */
+  skipTimestamps?: boolean;
+}
+
+export interface Jwt<TClaims extends Record<string, unknown>> {
+  sign(claims: TClaims, opts?: SignOptions): Promise<string>;
+  verify(token: string): Promise<TClaims | null>;
+  /** Decode the payload without verifying. Useful for debugging only. */
+  decode(token: string): TClaims | null;
+}
+
+export function createJwt<
+  TClaims extends Record<string, unknown> = Record<string, unknown>
+>(config: JwtConfig<TClaims>): Jwt<TClaims> {
+  const secretBytes =
+    typeof config.secret === 'string' ? textEncode(config.secret) : config.secret;
+  const hmac = config.hmac;
+  const ttlSec = config.ttlSec ?? 3600;
+  const clockSkewSec = config.clockSkewSec ?? 30;
+  const includeJti = config.includeJti ?? true;
+  const getExpiry = config.getExpiry ?? ((c) => c.exp as number | undefined);
+
+  async function sign(claims: TClaims, opts: SignOptions = {}): Promise<string> {
+    let payload: Record<string, unknown> = claims;
+    if (!opts.skipTimestamps) {
+      const now = Math.floor(Date.now() / 1000);
+      const additions: Record<string, unknown> = {};
+      if (includeJti && payload.jti === undefined) additions.jti = randomJti();
+      if (payload.iat === undefined) additions.iat = now;
+      if (payload.exp === undefined) additions.exp = now + ttlSec;
+      payload = { ...additions, ...claims };
+    }
+    const payloadJson = JSON.stringify(payload);
+    const payloadB64 = base64urlEncode(textEncode(payloadJson));
+    const signingInput = `${HEADER_B64}.${payloadB64}`;
+    const sig = await hmac(secretBytes, textEncode(signingInput));
+    return `${signingInput}.${base64urlEncode(sig)}`;
+  }
+
+  async function verify(token: string): Promise<TClaims | null> {
+    if (typeof token !== 'string' || token.length === 0) return null;
+    const parts = token.split('.');
+    if (parts.length !== 3) return null;
+    const [headerB64, payloadB64, sigB64] = parts;
+
+    // Header must decode to exactly the canonical HS256 header. This rejects
+    // alg=none, alg=RS256 confusion, and any other algorithm variation.
+    let header: { alg?: string; typ?: string };
+    try {
+      header = JSON.parse(textDecode(base64urlDecode(headerB64)));
+    } catch {
+      return null;
+    }
+    if (header.alg !== 'HS256' || header.typ !== 'JWT') return null;
+
+    const expected = await hmac(secretBytes, textEncode(`${headerB64}.${payloadB64}`));
+    let actual: Uint8Array;
+    try {
+      actual = base64urlDecode(sigB64);
+    } catch {
+      return null;
+    }
+    if (!constantTimeEqual(expected, actual)) return null;
+
+    let claims: TClaims;
+    try {
+      claims = JSON.parse(textDecode(base64urlDecode(payloadB64))) as TClaims;
+    } catch {
+      return null;
+    }
+
+    const exp = getExpiry(claims);
+    if (typeof exp !== 'number') return null;
+    const now = Math.floor(Date.now() / 1000);
+    if (exp + clockSkewSec < now) return null;
+
+    return claims;
+  }
+
+  function decode(token: string): TClaims | null {
+    const parts = token.split('.');
+    if (parts.length !== 3) return null;
+    try {
+      return JSON.parse(textDecode(base64urlDecode(parts[1]))) as TClaims;
+    } catch {
+      return null;
+    }
+  }
+
+  return { sign, verify, decode };
+}
+
+// ─── helpers ────────────────────────────────────────────────────────────────
+
+function textEncode(s: string): Uint8Array {
+  return new TextEncoder().encode(s);
+}
+function textDecode(b: Uint8Array): string {
+  return new TextDecoder().decode(b);
+}
+
+export function base64urlEncode(bytes: Uint8Array): string {
+  let s = '';
+  for (let i = 0; i < bytes.length; i++) s += String.fromCharCode(bytes[i]);
+  // btoa is available in node 16+ and all browsers/workers.
+  const b64 = typeof btoa === 'function' ? btoa(s) : Buffer.from(bytes).toString('base64');
+  return b64.replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+
+export function base64urlDecode(s: string): Uint8Array {
+  const std = s.replace(/-/g, '+').replace(/_/g, '/');
+  const pad = std.length % 4 === 0 ? '' : '='.repeat(4 - (std.length % 4));
+  const bin = typeof atob === 'function' ? atob(std + pad) : Buffer.from(std + pad, 'base64').toString('binary');
+  const out = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+  return out;
+}
+
+function constantTimeEqual(a: Uint8Array, b: Uint8Array): boolean {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) diff |= a[i] ^ b[i];
+  return diff === 0;
+}
+
+function randomJti(): string {
+  // RFC 4122 v4 UUID via crypto.getRandomValues — no deps.
+  const bytes = new Uint8Array(16);
+  crypto.getRandomValues(bytes);
+  bytes[6] = (bytes[6] & 0x0f) | 0x40; // version 4
+  bytes[8] = (bytes[8] & 0x3f) | 0x80; // variant 10
+  const h = Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');
+  return `${h.slice(0, 8)}-${h.slice(8, 12)}-${h.slice(12, 16)}-${h.slice(16, 20)}-${h.slice(20)}`;
+}
+
+export type { HmacFn } from './hmac';

package/src/jwt/jwt.sql

@@ -0,0 +1,177 @@
+-- =============================================================================
+-- @everystack/auth — JWT (HS256) — SQL twin
+--
+-- Pure pgcrypto. No pgsodium, no extensions beyond pgcrypto.
+--
+-- Two entry points:
+--   auth.jwt_sign_raw(payload_json text, secret text) → text
+--     Signs the *exact* payload string verbatim. Use this when you need
+--     byte-identical output to a known canonical JSON (cross-impl conformance).
+--
+--   auth.jwt_sign(claims jsonb, secret text) → text
+--     Convenience wrapper that serializes claims via claims::text.
+--     Note: jsonb sorts keys alphabetically — tokens from this function
+--     are valid but not byte-identical to JS-issued tokens. Cross-verification
+--     still works (verify only checks the signature over the bytes received).
+--
+--   auth.jwt_verify(token text, secret text) → jsonb
+--     Verifies HS256 signature, header (alg=HS256, typ=JWT), and exp.
+--     Returns claims jsonb on success, NULL on any failure.
+--
+-- All functions are pure (no session writes). Compose with your auth schema
+-- to build authenticate() / authenticate_request() flows.
+--
+-- Requires: CREATE EXTENSION IF NOT EXISTS pgcrypto;
+-- =============================================================================
+
+CREATE SCHEMA IF NOT EXISTS auth;
+CREATE EXTENSION IF NOT EXISTS pgcrypto;
+
+-- -----------------------------------------------------------------------------
+-- base64url helpers (RFC 4648 §5, no padding)
+-- -----------------------------------------------------------------------------
+CREATE OR REPLACE FUNCTION auth.base64url_encode(data bytea)
+RETURNS text
+LANGUAGE sql IMMUTABLE STRICT
+AS $$
+  SELECT rtrim(
+    replace(replace(replace(encode(data, 'base64'), E'\n', ''), '+', '-'), '/', '_'),
+    '='
+  );
+$$;
+
+CREATE OR REPLACE FUNCTION auth.base64url_decode(data text)
+RETURNS bytea
+LANGUAGE plpgsql IMMUTABLE STRICT
+AS $$
+DECLARE
+  v_std text;
+  v_mod int;
+BEGIN
+  v_std := replace(replace(data, '-', '+'), '_', '/');
+  v_mod := length(v_std) % 4;
+  IF v_mod = 2 THEN v_std := v_std || '==';
+  ELSIF v_mod = 3 THEN v_std := v_std || '=';
+  END IF;
+  RETURN decode(v_std, 'base64');
+END;
+$$;
+
+-- -----------------------------------------------------------------------------
+-- auth.jwt_sign_raw(payload_json text, secret text) → text
+--
+-- Signs payload_json verbatim. The caller is responsible for canonicalization.
+-- This is the byte-identical primitive used by the conformance suite.
+-- -----------------------------------------------------------------------------
+CREATE OR REPLACE FUNCTION auth.jwt_sign_raw(p_payload_json text, p_secret text)
+RETURNS text
+LANGUAGE plpgsql
+IMMUTABLE STRICT
+SET search_path = auth, public, pg_temp
+AS $$
+DECLARE
+  v_header_b64 text;
+  v_payload_b64 text;
+  v_signing_input text;
+  v_sig_b64 text;
+BEGIN
+  v_header_b64 := auth.base64url_encode(convert_to('{"alg":"HS256","typ":"JWT"}', 'UTF8'));
+  v_payload_b64 := auth.base64url_encode(convert_to(p_payload_json, 'UTF8'));
+  v_signing_input := v_header_b64 || '.' || v_payload_b64;
+  v_sig_b64 := auth.base64url_encode(
+    hmac(convert_to(v_signing_input, 'UTF8'), convert_to(p_secret, 'UTF8'), 'sha256')
+  );
+  RETURN v_signing_input || '.' || v_sig_b64;
+END;
+$$;
+
+COMMENT ON FUNCTION auth.jwt_sign_raw(text, text) IS
+'Sign a JWT HS256 token from a verbatim payload JSON string. Use for canonical/byte-identical output.';
+
+-- -----------------------------------------------------------------------------
+-- auth.jwt_sign(claims jsonb, secret text) → text
+--
+-- Convenience wrapper. Note jsonb key ordering — see header comments.
+-- -----------------------------------------------------------------------------
+CREATE OR REPLACE FUNCTION auth.jwt_sign(p_claims jsonb, p_secret text)
+RETURNS text
+LANGUAGE sql
+IMMUTABLE STRICT
+SET search_path = auth, public, pg_temp
+AS $$
+  SELECT auth.jwt_sign_raw(p_claims::text, p_secret);
+$$;
+
+COMMENT ON FUNCTION auth.jwt_sign(jsonb, text) IS
+'Sign a JWT HS256 token. Convenience over jwt_sign_raw — jsonb sorts keys alphabetically.';
+
+-- -----------------------------------------------------------------------------
+-- auth.jwt_verify(token text, secret text) → jsonb
+--
+-- Verifies HS256 signature, header constraints, and exp. Returns claims
+-- jsonb on success, NULL on any failure. Never raises.
+-- -----------------------------------------------------------------------------
+CREATE OR REPLACE FUNCTION auth.jwt_verify(p_token text, p_secret text)
+RETURNS jsonb
+LANGUAGE plpgsql
+STABLE
+SET search_path = auth, public, pg_temp
+AS $$
+DECLARE
+  v_parts text[];
+  v_header jsonb;
+  v_expected_sig text;
+  v_claims jsonb;
+  v_exp bigint;
+BEGIN
+  IF p_token IS NULL OR p_secret IS NULL THEN
+    RETURN NULL;
+  END IF;
+
+  v_parts := string_to_array(p_token, '.');
+  IF array_length(v_parts, 1) IS DISTINCT FROM 3 THEN
+    RETURN NULL;
+  END IF;
+
+  -- Header check: must be exactly HS256/JWT (no alg confusion, no alg=none).
+  BEGIN
+    v_header := convert_from(auth.base64url_decode(v_parts[1]), 'UTF8')::jsonb;
+  EXCEPTION WHEN OTHERS THEN
+    RETURN NULL;
+  END;
+  IF v_header->>'alg' IS DISTINCT FROM 'HS256'
+     OR v_header->>'typ' IS DISTINCT FROM 'JWT' THEN
+    RETURN NULL;
+  END IF;
+
+  -- Recompute signature from header.payload bytes.
+  v_expected_sig := auth.base64url_encode(
+    hmac(
+      convert_to(v_parts[1] || '.' || v_parts[2], 'UTF8'),
+      convert_to(p_secret, 'UTF8'),
+      'sha256'
+    )
+  );
+  IF v_parts[3] IS DISTINCT FROM v_expected_sig THEN
+    RETURN NULL;
+  END IF;
+
+  -- Decode payload.
+  BEGIN
+    v_claims := convert_from(auth.base64url_decode(v_parts[2]), 'UTF8')::jsonb;
+  EXCEPTION WHEN OTHERS THEN
+    RETURN NULL;
+  END;
+
+  -- exp required (epoch seconds).
+  v_exp := nullif(v_claims->>'exp', '')::bigint;
+  IF v_exp IS NULL OR v_exp < extract(epoch FROM now())::bigint THEN
+    RETURN NULL;
+  END IF;
+
+  RETURN v_claims;
+END;
+$$;
+
+COMMENT ON FUNCTION auth.jwt_verify(text, text) IS
+'Verify HS256 JWT signature + header + exp. Returns claims jsonb or NULL.';

package/src/oauth/index.ts

@@ -0,0 +1,7 @@
+export type { OAuthProvider, OAuthUserInfo } from './types';
+export { verifyOidcToken, createJwksCache } from './verify';
+export type { OidcClaims, JwksCache, JwksFetcher, JwksKey, JwksResponse } from './verify';
+export { createGoogleProvider } from './providers/google';
+export type { GoogleProviderConfig } from './providers/google';
+export { createAppleProvider } from './providers/apple';
+export type { AppleProviderConfig } from './providers/apple';

package/src/oauth/providers/apple.ts

@@ -0,0 +1,43 @@
+import { verifyOidcToken, createJwksCache } from '../verify';
+import type { JwksCache } from '../verify';
+import type { OAuthProvider } from '../types';
+
+const APPLE_JWKS_URI = 'https://appleid.apple.com/auth/keys';
+const APPLE_ISSUER = 'https://appleid.apple.com';
+
+export interface AppleProviderConfig {
+  clientId: string;
+  jwks?: JwksCache;
+}
+
+export function createAppleProvider(
+  configOrClientId: AppleProviderConfig | string
+): OAuthProvider {
+  const config: AppleProviderConfig =
+    typeof configOrClientId === 'string' ? { clientId: configOrClientId } : configOrClientId;
+  const jwks =
+    config.jwks ??
+    createJwksCache({
+      fetcher: async () => {
+        const res = await fetch(APPLE_JWKS_URI);
+        if (!res.ok) throw new Error(`apple jwks fetch failed: ${res.status}`);
+        return res.json();
+      },
+    });
+
+  return {
+    name: 'apple',
+    verify: async (token) => {
+      const claims = await verifyOidcToken(token, {
+        issuer: APPLE_ISSUER,
+        audience: config.clientId,
+        jwks,
+      });
+      if (!claims) return null;
+      const email = claims.email as string | undefined;
+      if (!email) return null;
+      // Apple only sends name on first authorization response, never in id_token.
+      return { uid: claims.sub, email };
+    },
+  };
+}

package/src/oauth/providers/google.ts

@@ -0,0 +1,49 @@
+import { verifyOidcToken, createJwksCache } from '../verify';
+import type { JwksCache } from '../verify';
+import type { OAuthProvider } from '../types';
+
+const GOOGLE_JWKS_URI = 'https://www.googleapis.com/oauth2/v3/certs';
+const GOOGLE_ISSUERS = ['https://accounts.google.com', 'accounts.google.com'];
+
+export interface GoogleProviderConfig {
+  clientId: string;
+  /** Optional pre-configured JWKS cache. Defaults to fetching Google's JWKS. */
+  jwks?: JwksCache;
+}
+
+export function createGoogleProvider(
+  configOrClientId: GoogleProviderConfig | string
+): OAuthProvider {
+  const config: GoogleProviderConfig =
+    typeof configOrClientId === 'string' ? { clientId: configOrClientId } : configOrClientId;
+  const jwks =
+    config.jwks ??
+    createJwksCache({
+      fetcher: async () => {
+        const res = await fetch(GOOGLE_JWKS_URI);
+        if (!res.ok) throw new Error(`google jwks fetch failed: ${res.status}`);
+        return res.json();
+      },
+    });
+
+  return {
+    name: 'google',
+    verify: async (token) => {
+      const claims = await verifyOidcToken(token, {
+        issuer: GOOGLE_ISSUERS,
+        audience: config.clientId,
+        jwks,
+      });
+      if (!claims) return null;
+      const email = claims.email as string | undefined;
+      if (!email) return null;
+      return {
+        uid: claims.sub,
+        email,
+        firstName: claims.given_name as string | undefined,
+        lastName: claims.family_name as string | undefined,
+        avatarUrl: claims.picture as string | undefined,
+      };
+    },
+  };
+}

package/src/oauth/types.ts

@@ -0,0 +1,17 @@
+/**
+ * OAuth provider interface — implementations return normalized user info
+ * from a verified provider id_token.
+ */
+
+export interface OAuthUserInfo {
+  uid: string;
+  email: string;
+  firstName?: string;
+  lastName?: string;
+  avatarUrl?: string;
+}
+
+export interface OAuthProvider {
+  name: string;
+  verify: (token: string) => Promise<OAuthUserInfo | null>;
+}

package/src/oauth/verify.ts

@@ -0,0 +1,193 @@
+/**
+ * RS256 + JWKS verifier — zero runtime deps, uses Web Crypto SubtleCrypto.
+ *
+ * Designed for OIDC id_token verification (Google, Apple, GitHub, etc.).
+ *
+ * Security:
+ *   - Algorithm pinned to RS256. Rejects alg=none, alg=HS256 (algorithm
+ *     confusion), and any other alg.
+ *   - Issuer and audience strictly validated.
+ *   - exp and nbf checked with optional clock skew.
+ *   - JWKS cached with TTL; on missing kid, force-refreshes once.
+ */
+
+export interface OidcClaims {
+  iss: string;
+  aud: string | string[];
+  sub: string;
+  exp: number;
+  nbf?: number;
+  iat?: number;
+  [k: string]: unknown;
+}
+
+export interface JwksKey extends JsonWebKey {
+  kid?: string;
+  alg?: string;
+  use?: string;
+}
+
+export interface JwksResponse {
+  keys: JwksKey[];
+}
+
+export type JwksFetcher = () => Promise<JwksResponse>;
+
+export interface JwksCache {
+  /** Get the JWK for `kid`, refreshing if missing and not refreshed in this call. */
+  getKey(kid: string): Promise<JwksKey | null>;
+}
+
+export interface JwksCacheConfig {
+  fetcher: JwksFetcher;
+  /** Cache lifetime. Default 1 hour. */
+  ttlMs?: number;
+}
+
+export function createJwksCache(config: JwksCacheConfig): JwksCache {
+  const ttlMs = config.ttlMs ?? 3_600_000;
+  let cached: { keys: Map<string, JwksKey>; fetchedAt: number } | null = null;
+  let inflight: Promise<void> | null = null;
+
+  async function refresh(): Promise<void> {
+    if (inflight) return inflight;
+    inflight = (async () => {
+      const res = await config.fetcher();
+      const map = new Map<string, JwksKey>();
+      for (const key of res.keys) {
+        if (key.kid) map.set(key.kid, key);
+      }
+      cached = { keys: map, fetchedAt: Date.now() };
+    })();
+    try {
+      await inflight;
+    } finally {
+      inflight = null;
+    }
+  }
+
+  return {
+    async getKey(kid: string): Promise<JwksKey | null> {
+      if (!cached || Date.now() - cached.fetchedAt > ttlMs) {
+        await refresh();
+      }
+      let key = cached!.keys.get(kid);
+      if (!key) {
+        // Force refresh — could be a key rotation we haven't seen yet.
+        await refresh();
+        key = cached!.keys.get(kid);
+      }
+      return key ?? null;
+    },
+  };
+}
+
+export interface VerifyOidcOptions {
+  issuer: string | string[];
+  audience: string | string[];
+  jwks: JwksCache;
+  /** Allowed clock skew in seconds. Default 30. */
+  clockSkewSec?: number;
+}
+
+export async function verifyOidcToken(
+  token: string,
+  options: VerifyOidcOptions
+): Promise<OidcClaims | null> {
+  if (typeof token !== 'string' || token.length === 0) return null;
+  const parts = token.split('.');
+  if (parts.length !== 3) return null;
+  const [headerB64, payloadB64, sigB64] = parts;
+
+  // Header: pin alg=RS256.
+  let header: { alg?: string; kid?: string; typ?: string };
+  try {
+    header = JSON.parse(b64urlDecodeText(headerB64));
+  } catch {
+    return null;
+  }
+  if (header.alg !== 'RS256' || !header.kid) return null;
+
+  const jwk = await options.jwks.getKey(header.kid);
+  if (!jwk) return null;
+
+  // Import as RSA-SHA256 verify key.
+  let cryptoKey: CryptoKey;
+  try {
+    cryptoKey = await crypto.subtle.importKey(
+      'jwk',
+      jwk as JsonWebKey,
+      { name: 'RSASSA-PKCS1-v1_5', hash: 'SHA-256' },
+      false,
+      ['verify']
+    );
+  } catch {
+    return null;
+  }
+
+  let sig: Uint8Array;
+  try {
+    sig = b64urlDecode(sigB64);
+  } catch {
+    return null;
+  }
+  const data = new TextEncoder().encode(`${headerB64}.${payloadB64}`);
+
+  const ok = await crypto.subtle.verify(
+    { name: 'RSASSA-PKCS1-v1_5' },
+    cryptoKey,
+    sig as BufferSource,
+    data as BufferSource
+  );
+  if (!ok) return null;
+
+  let claims: OidcClaims;
+  try {
+    claims = JSON.parse(b64urlDecodeText(payloadB64)) as OidcClaims;
+  } catch {
+    return null;
+  }
+
+  const skew = options.clockSkewSec ?? 30;
+  const now = Math.floor(Date.now() / 1000);
+  if (typeof claims.exp !== 'number' || claims.exp + skew < now) return null;
+  if (typeof claims.nbf === 'number' && claims.nbf - skew > now) return null;
+
+  if (!matchesString(claims.iss, options.issuer)) return null;
+  if (!matchesAudience(claims.aud, options.audience)) return null;
+
+  if (typeof claims.sub !== 'string' || !claims.sub) return null;
+
+  return claims;
+}
+
+function matchesString(value: unknown, allowed: string | string[]): boolean {
+  if (typeof value !== 'string') return false;
+  return Array.isArray(allowed) ? allowed.includes(value) : allowed === value;
+}
+
+function matchesAudience(
+  claim: string | string[] | undefined,
+  expected: string | string[]
+): boolean {
+  if (claim == null) return false;
+  const claims = Array.isArray(claim) ? claim : [claim];
+  const allowed = Array.isArray(expected) ? expected : [expected];
+  return claims.some((c) => allowed.includes(c));
+}
+
+function b64urlDecodeText(s: string): string {
+  return new TextDecoder().decode(b64urlDecode(s));
+}
+
+function b64urlDecode(s: string): Uint8Array {
+  const std = s.replace(/-/g, '+').replace(/_/g, '/');
+  const pad = std.length % 4 === 0 ? '' : '='.repeat(4 - (std.length % 4));
+  const bin =
+    typeof atob === 'function'
+      ? atob(std + pad)
+      : Buffer.from(std + pad, 'base64').toString('binary');
+  const out = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+  return out;
+}

package/src/oauth.ts

@@ -0,0 +1,6 @@
+/**
+ * @everystack/auth/oauth — OAuth provider verification.
+ *
+ * Back-compat re-export. New code should import from '@everystack/auth/oauth'.
+ */
+export * from './oauth/index';