@ultimat3/http 1.2.0 → 3.0.0

package/src/index.ts

@@ -1,6 +1,7 @@
 // The public surface of @ultimat3/http. Explicit, never `export *`: what is not
 // listed here is an implementation detail and may change without a major bump.
 
+export { NEXT_PARAM, nextAfterSignIn, signInRedirect } from './auth-redirect';
 export type { HttpConfig, HttpConfigInput } from './config';
 export { defineHttpConfig, stripBasePath } from './config';
 export type { ActorView, RequestContext, RequestContextInit } from './context';
@@ -10,15 +11,26 @@ export {
   createRequestContext,
   elapsedMs,
   useRequestContext,
+  useRequestCookie,
+  useRequestHeader,
+  useRequestHeaders,
 } from './context';
+export type { InboundCorrelation } from './correlation';
+export { readCorrelation } from './correlation';
 export type { CorsConfig } from './cors';
-export { corsHeaders, DEFAULT_CORS, preflight } from './cors';
+export { allowedOrigin, corsHeaders, DEFAULT_CORS, preflight } from './cors';
+export type { CsrfCheckInput, CsrfConfig, CsrfMode, CsrfVerdict } from './csrf';
+export { checkCsrf, DEFAULT_CSRF, selfOrigin } from './csrf';
+export type { Deadline } from './deadline';
+export { REQUEST_TIMEOUT_HEADER, resolveTimeoutMs, startDeadline } from './deadline';
 export type { ErrorFacts, ProblemDocument } from './error-map';
 export {
   DEFAULT_STATUS,
   ERROR_STATUS,
   factsOf,
+  registerErrorStatus,
   renderErrorLines,
+  resetErrorStatus,
   statusFor,
   toProblem,
 } from './error-map';
@@ -26,60 +38,81 @@ export type { HttpErrorCode } from './errors';
 export {
   bodyInvalid,
   buildSkew,
+  csrfBlocked,
+  draining,
+  errorStatusInvalid,
+  finalizeFailed,
   forbidden,
   HTTP_ERROR_CODES,
   HTTP_ERROR_TITLES,
   HttpError,
   methodNotAllowed,
+  noRequest,
+  overloaded,
+  pathInvalid,
   pipelineNoResponse,
+  rateLimitBucketConflict,
+  rateLimitBucketUnbound,
   rateLimited,
+  rateLimitInvalid,
+  rateLimitNotShared,
+  rateLimitScopeUnset,
+  requestTimedOut,
   routeConflict,
   routeNotFound,
   serverNotStarted,
+  trustProxyUnset,
   unauthenticated,
 } from './errors';
-export type { AuthzDecision, ServerHooks } from './hooks';
-export type { LocaleConfig, TimeZoneConfig } from './locale';
+export type { ForwardedInput, ForwardedSplit } from './forwarded';
 export {
-  DEFAULT_LOCALE_CONFIG,
-  DEFAULT_TZ_CONFIG,
-  isValidTimeZone,
-  negotiateLocale,
-  readCookie,
-  resolveTimeZone,
-} from './locale';
+  clientAddress,
+  clientUsedHttps,
+  FORWARDED_CLIENT_CERT,
+  FORWARDED_FOR,
+  FORWARDED_PROTO,
+  forwardedElement,
+  forwardedValue,
+} from './forwarded';
+export type { Authenticator, AuthzDecision, ServerHooks } from './hooks';
+export { configureAuthenticator, configuredAuthenticator, resetAuthenticator } from './hooks';
+export type { LocaleConfig, TimeZoneConfig } from './locale';
+export { DEFAULT_LOCALE_CONFIG, DEFAULT_TZ_CONFIG, readCookie } from './locale';
 export type { Middleware } from './middleware';
 export { compose } from './middleware';
-export type { OverlayMeta } from './overlay';
+export type { OverlayMeta, OverlayNotice } from './overlay';
 export { overlayResponse, renderOverlay, wantsOverlay } from './overlay';
-export type {
-  HandleInit,
-  Pipeline,
-  PipelineDeps,
-  Stage,
-  StageDoc,
-  StageName,
-  StagePhase,
-  StageRun,
-} from './pipeline';
+export { OVERLAY_STYLE } from './overlay-style';
+export type { PeerIdentity } from './peer-identity';
+export { peerIdentity } from './peer-identity';
+export type { HandleInit, Pipeline, PipelineDeps } from './pipeline';
 export { createPipeline, PIPELINE_STAGES } from './pipeline';
 export type {
   Bucket,
+  MemoryRateLimitStore,
   RateLimitConfig,
   RateLimitDecision,
+  RateLimitDeclaration,
   RateLimiter,
   RateLimitKeyParts,
+  RateLimitScope,
   RateLimitStore,
 } from './rate-limit';
 export {
+  assertRateLimitScope,
   createRateLimiter,
+  DEFAULT_MAX_RATE_LIMIT_KEYS,
   DEFAULT_RATE_LIMIT,
   memoryRateLimitStore,
   rateLimitKey,
+  resolveRateLimitConfig,
+  toBucket,
 } from './rate-limit';
+export { assertRouteBuckets, withRouteBuckets } from './rate-limit-buckets';
+export { setRedirect, takeRedirect } from './redirect';
 export type { QueryValues } from './request';
 export { UltimateRequest } from './request';
-export type { CacheHint } from './response';
+export type { CacheHint, RedirectIntent, RedirectStatus } from './response';
 export {
   applyCacheHeaders,
   cacheControl,
@@ -112,8 +145,11 @@ export {
   normalizePath,
 } from './router';
 export type { SecurityConfig } from './security-headers';
-export { buildCsp, DEFAULT_SECURITY, securityHeaders } from './security-headers';
+export { buildCsp, cspHashSource, DEFAULT_SECURITY, securityHeaders } from './security-headers';
 export type { LifecycleState, ServerHandle, ServerOptions } from './server';
 export { createServer } from './server';
+// The stage vocabulary comes from its declaration site, beside the fourteen implementations it
+// names; `PIPELINE_STAGES` — the ORDER — stays `pipeline.ts`'s.
+export type { Stage, StageDoc, StageName, StagePhase, StageRun } from './stages';
 export type { InferOutput, Schema, ValidationOutcome } from './validate';
 export { formatIssue, validate, validateSync } from './validate';

package/src/locale.ts

@@ -1,31 +1,52 @@
-// Locale and time zone are resolved once per request, before any handler runs, so
-// no code path can format a date or a number without them. `@ultimat3/i18n` owns
-// catalogs; this file only owns the negotiation of the two request-scoped values.
+// WHERE the request's locale and zone are read from — the header and cookie NAMES, and nothing
+// else. What a locale or a zone IS belongs to `@ultimat3/i18n` and `@ultimat3/time` (tier 1, a
+// legal downward import), which is why this file negotiates nothing: three re-implementations
+// lived here and all three disagreed with their owner about the same request.
+
+import { LOCALE_COOKIE } from '@ultimat3/i18n';
+import { TIMEZONE_HEADER } from '@ultimat3/time';
 
 export interface LocaleConfig {
-  readonly supported: readonly string[];
-  readonly default: string;
   /** Cookie the client sets when the user picks a locale explicitly. */
   readonly cookie: string;
 }
 
 export interface TimeZoneConfig {
-  readonly default: string;
   /** Header the client sets from `Intl.DateTimeFormat().resolvedOptions().timeZone`. */
   readonly header: string;
   readonly cookie: string;
 }
 
+/**
+ * The supported set and the fallback are NOT here: `defineCatalogs()` already declares them, and
+ * a second copy in this config meant an app shipping `{ en, fr }` still resolved `ctx.locale` to
+ * `'en'` forever. The cookie name is `@ultimat3/i18n`'s own constant for the same reason — a
+ * language switcher written against the documented `LOCALE_COOKIE` was read by nothing.
+ */
 export const DEFAULT_LOCALE_CONFIG: LocaleConfig = {
-  supported: ['en'],
-  default: 'en',
-  cookie: 'x-locale',
+  cookie: LOCALE_COOKIE,
 };
 
+/** The default zone is `configureTime({ defaultZone })`'s, so a process has one answer, not two. */
 export const DEFAULT_TZ_CONFIG: TimeZoneConfig = {
-  default: 'UTC',
-  header: 'x-timezone',
-  cookie: 'x-timezone',
+  header: TIMEZONE_HEADER,
+  cookie: 'x_timezone',
+};
+
+/**
+ * The raw value on a malformed escape, never a throw. `Cookie:` is attacker-controlled and
+ * `decodeURIComponent('%')` is a bare `URIError` — thrown from the `locale` stage, which runs on
+ * every request, so `curl -H 'Cookie: x-locale=%'` answered 500 and paged the on-call. Nothing is
+ * loosened: a locale that is not in `supported` still falls back, and a time zone `Intl` cannot
+ * format is still refused. `@ultimat3/auth` guards its own cookie reader the same way and for the
+ * same reason; the guard is four lines and this package can never import that one (same tier).
+ */
+const decodeCookieValue = (raw: string): string => {
+  try {
+    return decodeURIComponent(raw);
+  } catch {
+    return raw;
+  }
 };
 
 export const readCookie = (header: string | null, name: string): string | null => {
@@ -34,76 +55,7 @@ export const readCookie = (header: string | null, name: string): string | null =
     const index = part.indexOf('=');
     if (index === -1) continue;
     if (part.slice(0, index).trim() !== name) continue;
-    return decodeURIComponent(part.slice(index + 1).trim());
+    return decodeCookieValue(part.slice(index + 1).trim());
   }
   return null;
 };
-
-interface Weighted {
-  readonly tag: string;
-  readonly q: number;
-}
-
-const parseAcceptLanguage = (header: string): readonly Weighted[] =>
-  header
-    .split(',')
-    .map((entry): Weighted => {
-      const [tag = '', ...params] = entry.trim().split(';');
-      const qParam = params.find((p) => p.trim().startsWith('q='));
-      const q = qParam === undefined ? 1 : Number.parseFloat(qParam.trim().slice(2));
-      return { tag: tag.trim().toLowerCase(), q: Number.isFinite(q) ? q : 0 };
-    })
-    .filter((entry) => entry.tag.length > 0 && entry.q > 0)
-    .sort((a, b) => b.q - a.q);
-
-/**
- * Exact match wins, then primary-subtag match (`de-CH` -> `de`), then the config
- * default. `*` is treated as "no preference" rather than "any locale" so the
- * default stays predictable for SEO and cache keys.
- */
-export const negotiateLocale = (
-  acceptLanguage: string | null,
-  config: LocaleConfig = DEFAULT_LOCALE_CONFIG,
-  explicit?: string | null,
-): string => {
-  const supported = config.supported.map((locale) => locale.toLowerCase());
-  const pick = (candidate: string): string | undefined => {
-    const wanted = candidate.toLowerCase();
-    const exact = supported.indexOf(wanted);
-    if (exact !== -1) return config.supported[exact];
-    const primary = wanted.split('-')[0] ?? wanted;
-    const loose = supported.findIndex((locale) => (locale.split('-')[0] ?? locale) === primary);
-    return loose === -1 ? undefined : config.supported[loose];
-  };
-
-  if (explicit !== undefined && explicit !== null) {
-    const chosen = pick(explicit);
-    if (chosen !== undefined) return chosen;
-  }
-  if (acceptLanguage !== null) {
-    for (const entry of parseAcceptLanguage(acceptLanguage)) {
-      if (entry.tag === '*') break;
-      const chosen = pick(entry.tag);
-      if (chosen !== undefined) return chosen;
-    }
-  }
-  return config.default;
-};
-
-/** A time zone is only accepted if `Intl` can actually format with it. */
-export const isValidTimeZone = (candidate: string): boolean => {
-  try {
-    new Intl.DateTimeFormat('en', { timeZone: candidate }).format(0);
-    return true;
-  } catch {
-    return false;
-  }
-};
-
-export const resolveTimeZone = (
-  candidate: string | null,
-  config: TimeZoneConfig = DEFAULT_TZ_CONFIG,
-): string => {
-  if (candidate !== null && candidate.length > 0 && isValidTimeZone(candidate)) return candidate;
-  return config.default;
-};

package/src/overlay-style.ts

@@ -0,0 +1,43 @@
+// The dev overlay's stylesheet, split from the document that carries it so `security-headers.ts`
+// can hash it into the CSP without importing the renderer — and so the hash is computed from the
+// one copy of the text, never from a constant that drifted away from what the `<style>` holds.
+
+// Token definitions live here and nowhere else; every rule below uses var().
+export const OVERLAY_STYLE = `
+:root {
+  --x-bg: #fbfbfd; --x-surface: #ffffff; --x-border: #e3e3ea;
+  --x-text: #1b1b1f; --x-muted: #6b6b76; --x-danger: #b3261e; --x-accent: #2f4fd8;
+  --x-code-bg: #f3f3f7;
+}
+@media (prefers-color-scheme: dark) {
+  :root {
+    --x-bg: #111115; --x-surface: #1a1a20; --x-border: #2e2e38;
+    --x-text: #ececf1; --x-muted: #9b9baa; --x-danger: #ff8a80; --x-accent: #9db2ff;
+    --x-code-bg: #22222b;
+  }
+}
+* { box-sizing: border-box; }
+body {
+  margin: 0; padding: 2rem; background: var(--x-bg); color: var(--x-text);
+  font: 14px/1.6 ui-monospace, SFMono-Regular, Menlo, monospace;
+}
+main { max-width: 60rem; margin: 0 auto; }
+.card {
+  background: var(--x-surface); border: 1px solid var(--x-border);
+  border-radius: 8px; padding: 1.25rem 1.5rem; margin-bottom: 1rem;
+}
+h1 { font-size: 1.1rem; margin: 0 0 .25rem; color: var(--x-danger); }
+h2 { font-size: .8rem; margin: 0 0 .5rem; color: var(--x-muted);
+     text-transform: uppercase; letter-spacing: .08em; }
+dl { display: grid; grid-template-columns: 5rem 1fr; gap: .35rem 1rem; margin: 0; }
+dt { color: var(--x-muted); }
+dd { margin: 0; overflow-wrap: anywhere; }
+pre { background: var(--x-code-bg); border-radius: 6px; padding: .75rem;
+      margin: 0; overflow-x: auto; }
+a { color: var(--x-accent); }
+.title { color: var(--x-muted); font-weight: normal; }
+/* A notice's term is an X_ code, not a five-character label: at the shared 5rem the codes this
+   card exists to show would sit on top of their own causes. */
+.notices dl { grid-template-columns: 14rem 1fr; }
+.notices dt { overflow-wrap: anywhere; }
+`;

package/src/overlay.ts

@@ -1,59 +1,77 @@
 // The dev error overlay. It renders the SAME facts object the terminal prints and
 // `--json` emits, so a code/cause/fix string can never differ between the three
-// surfaces. Labels here ("cause", "fix") are protocol strings from the error
-// contract, not UI copy, so they are not routed through the i18n catalog.
+// surfaces. Labels here ("cause", "fix", "notices") are protocol strings from the
+// error contract, not UI copy, so they are not routed through the i18n catalog.
 import { factsOf, renderErrorLines, toProblem } from './error-map';
+import { OVERLAY_STYLE } from './overlay-style';
 import { html } from './response';
 
+// `'` is escaped even though every attribute below is double-quoted: the escape set is what the
+// next author reads as the guarantee, and a single-quoted attribute written later would inherit a
+// hole nothing here would have flagged.
 const escapeHtml = (value: string): string =>
   value
     .replaceAll('&', '&')
     .replaceAll('<', '&lt;')
     .replaceAll('>', '&gt;')
-    .replaceAll('"', '&quot;');
+    .replaceAll('"', '&quot;')
+    .replaceAll("'", '&#39;');
+
+/**
+ * An `href` is a SCHEME decision, not an escaping one: `javascript:alert(1)` survives every entity
+ * replacement intact and becomes a link the agent debugging this page clicks. A `docs` value comes
+ * from whichever package raised the error, so anything that is not plainly http(s) renders as text.
+ */
+const docsLink = (value: string): string => {
+  const protocol = URL.parse(value)?.protocol;
+  const safe = protocol === 'https:' || protocol === 'http:';
+  return safe ? `<a href="${escapeHtml(value)}">${escapeHtml(value)}</a>` : escapeHtml(value);
+};
+
+/**
+ * A non-fatal finding rendered next to the error: the same code/cause/fix contract, from a
+ * diagnostic that did not stop the request. Declared structurally — the packages that produce
+ * one (`@ultimat3/entity`'s N+1 codes, reported by `x dev`) are this tier or above and can
+ * never be imported here, exactly as `AuthzDecision` is declared and never imported.
+ */
+export interface OverlayNotice {
+  readonly code: string;
+  readonly cause: string;
+  readonly fix: string;
+  readonly docs?: string;
+}
 
 export interface OverlayMeta {
   readonly requestId?: string;
   readonly method?: string;
   readonly path?: string;
   readonly buildId?: string | null;
+  readonly notices?: readonly OverlayNotice[];
 }
 
-// Token definitions live here and nowhere else; every rule below uses var().
-const STYLE = `
-:root {
-  --x-bg: #fbfbfd; --x-surface: #ffffff; --x-border: #e3e3ea;
-  --x-text: #1b1b1f; --x-muted: #6b6b76; --x-danger: #b3261e; --x-accent: #2f4fd8;
-  --x-code-bg: #f3f3f7;
-}
-@media (prefers-color-scheme: dark) {
-  :root {
-    --x-bg: #111115; --x-surface: #1a1a20; --x-border: #2e2e38;
-    --x-text: #ececf1; --x-muted: #9b9baa; --x-danger: #ff8a80; --x-accent: #9db2ff;
-    --x-code-bg: #22222b;
-  }
-}
-* { box-sizing: border-box; }
-body {
-  margin: 0; padding: 2rem; background: var(--x-bg); color: var(--x-text);
-  font: 14px/1.6 ui-monospace, SFMono-Regular, Menlo, monospace;
-}
-main { max-width: 60rem; margin: 0 auto; }
-.card {
-  background: var(--x-surface); border: 1px solid var(--x-border);
-  border-radius: 8px; padding: 1.25rem 1.5rem; margin-bottom: 1rem;
-}
-h1 { font-size: 1.1rem; margin: 0 0 .25rem; color: var(--x-danger); }
-h2 { font-size: .8rem; margin: 0 0 .5rem; color: var(--x-muted);
-     text-transform: uppercase; letter-spacing: .08em; }
-dl { display: grid; grid-template-columns: 5rem 1fr; gap: .35rem 1rem; margin: 0; }
-dt { color: var(--x-muted); }
-dd { margin: 0; overflow-wrap: anywhere; }
-pre { background: var(--x-code-bg); border-radius: 6px; padding: .75rem;
-      margin: 0; overflow-x: auto; }
-a { color: var(--x-accent); }
-.title { color: var(--x-muted); font-weight: normal; }
-`;
+// One `<dd>` per finding, holding the cause and the runnable fix — the same two lines the
+// terminal prints under a code, so a notice cannot say something the CLI would not.
+const noticeRow = (notice: OverlayNotice): string =>
+  `<dt>${escapeHtml(notice.code)}</dt><dd>${escapeHtml(notice.cause)}<br><code>${escapeHtml(
+    notice.fix,
+  )}</code>${notice.docs === undefined ? '' : `<br>${docsLink(notice.docs)}`}</dd>`;
+
+/**
+ * Nothing at all when there is nothing to report — not an empty card. A request with no findings
+ * must render the bytes this file rendered before notices existed, or every host that never
+ * supplies one still pays for the feature with a card that says nothing. The trailing indent is
+ * part of that: it leaves the card after this one exactly where it already sat.
+ */
+const noticesCard = (notices: readonly OverlayNotice[]): string =>
+  notices.length === 0
+    ? ''
+    : `<section class="card notices">
+    <h2>notices</h2>
+    <dl>
+      ${notices.map(noticeRow).join('\n      ')}
+    </dl>
+  </section>
+  `;
 
 export const renderOverlay = (error: unknown, meta: OverlayMeta = {}): string => {
   const facts = factsOf(error);
@@ -62,14 +80,14 @@ export const renderOverlay = (error: unknown, meta: OverlayMeta = {}): string =>
     ...(meta.path === undefined ? {} : { instance: meta.path }),
   });
   const where = `${meta.method ?? ''} ${meta.path ?? ''}`.trim();
-  return `<style>${STYLE}</style>
+  return `<style>${OVERLAY_STYLE}</style>
 <main>
   <section class="card">
     <h1>${escapeHtml(facts.code)} <span class="title">${escapeHtml(facts.title)}</span></h1>
     <dl>
       <dt>cause</dt><dd>${escapeHtml(facts.cause)}</dd>
       <dt>fix</dt><dd><code>${escapeHtml(facts.fix)}</code></dd>
-      <dt>docs</dt><dd><a href="${escapeHtml(facts.docs)}">${escapeHtml(facts.docs)}</a></dd>
+      <dt>docs</dt><dd>${docsLink(facts.docs)}</dd>
       ${where === '' ? '' : `<dt>route</dt><dd>${escapeHtml(where)}</dd>`}
       ${meta.requestId === undefined ? '' : `<dt>request</dt><dd>${escapeHtml(meta.requestId)}</dd>`}
       ${
@@ -79,7 +97,7 @@ export const renderOverlay = (error: unknown, meta: OverlayMeta = {}): string =>
       }
     </dl>
   </section>
-  <section class="card">
+  ${noticesCard(meta.notices ?? [])}<section class="card">
     <h2>terminal</h2>
     <pre>${escapeHtml(renderErrorLines(error))}</pre>
   </section>

package/src/peer-identity.ts

@@ -0,0 +1,107 @@
+// Who the MESH says is calling. TLS termination is the mesh's job (axiom 7) so the framework's
+// entire contribution is reading a header it has been TOLD to trust: Envoy's
+// `x-forwarded-client-cert`, at the same hop index `x-forwarded-for` is read at. Untrusted, this
+// header is worse than nothing — it authenticates — so an untrusted read answers `null` and
+// there is no second proxy-trust path to get it wrong in.
+
+import { FORWARDED_CLIENT_CERT, type ForwardedInput, forwardedElement } from './forwarded';
+
+/**
+ * The peer's certificate facts, declared structurally rather than imported: `@ultimat3/auth` owns
+ * `ServiceIdentity` and is this tier, so it can never be imported here — the same reason
+ * `AuthzDecision` and `OverlayNotice` are declared in this package. An app maps this onto a
+ * `ServiceIdentity` inside its `configureAuthenticator()`, which is the ONE funnel:
+ * `verifyWorkloadToken(...)` -> `actorFromService(identity)` -> `ctx.actor`. Never a second
+ * authz system that reads a certificate and decides on its own.
+ */
+export interface PeerIdentity {
+  /**
+   * The SPIFFE ID if the peer presented one, else the subject DN, else the first URI SAN. What an
+   * app keys a service on — and always a value a trusted proxy wrote, never the caller.
+   */
+  readonly id: string;
+  /** `spiffe://…` from the URI SANs, when there is one. */
+  readonly spiffeId: string | null;
+  /** The certificate subject DN, e.g. `CN=checkout,OU=payments`. */
+  readonly subject: string | null;
+  readonly uriSans: readonly string[];
+  readonly dnsSans: readonly string[];
+  /** The proxy that terminated the TLS connection, as it named itself. */
+  readonly by: string | null;
+}
+
+/** Splits on a separator that is not inside a double-quoted value. `Subject="CN=a,OU=b"`. */
+const splitUnquoted = (value: string, separator: string): readonly string[] => {
+  const out: string[] = [];
+  let current = '';
+  let quoted = false;
+  let escaped = false;
+  for (const char of value) {
+    if (escaped) {
+      current += char;
+      escaped = false;
+      continue;
+    }
+    if (char === '\\') {
+      escaped = true;
+      continue;
+    }
+    if (char === '"') {
+      quoted = !quoted;
+      continue;
+    }
+    if (char === separator && !quoted) {
+      out.push(current.trim());
+      current = '';
+      continue;
+    }
+    current += char;
+  }
+  out.push(current.trim());
+  return out.filter((entry) => entry.length > 0);
+};
+
+/** `Key=Value` pairs, keys lowercased. `URI` and `DNS` may repeat, so values collect. */
+const pairsOf = (element: string): ReadonlyMap<string, readonly string[]> => {
+  const out = new Map<string, string[]>();
+  for (const pair of splitUnquoted(element, ';')) {
+    const eq = pair.indexOf('=');
+    if (eq <= 0) continue;
+    const key = pair.slice(0, eq).trim().toLowerCase();
+    const value = pair.slice(eq + 1).trim();
+    if (value.length === 0) continue;
+    const existing = out.get(key);
+    if (existing === undefined) out.set(key, [value]);
+    else existing.push(value);
+  }
+  return out;
+};
+
+/**
+ * The peer identity a TRUSTED proxy asserted, or `null`. `null` is the answer for an untrusted
+ * deployment, a missing header and a chain shorter than `trustedProxyHops` alike: a certificate
+ * identity read from a hop nobody vouched for is a confident name for an attacker's claim.
+ */
+export const peerIdentity = (input: ForwardedInput): PeerIdentity | null => {
+  const element = forwardedElement(
+    input.headers.get(FORWARDED_CLIENT_CERT),
+    input.config.trustedProxyHops,
+    splitUnquoted,
+  );
+  if (element === undefined) return null;
+  const pairs = pairsOf(element);
+  const uriSans = pairs.get('uri') ?? [];
+  const dnsSans = pairs.get('dns') ?? [];
+  const subject = pairs.get('subject')?.[0] ?? null;
+  const spiffeId = uriSans.find((uri) => uri.startsWith('spiffe://')) ?? null;
+  const id = spiffeId ?? subject ?? uriSans[0] ?? null;
+  if (id === null) return null;
+  return {
+    id,
+    spiffeId,
+    subject,
+    uriSans,
+    dnsSans,
+    by: pairs.get('by')?.[0] ?? null,
+  };
+};