@pylonsync/create-pylon 0.19.0 → 0.20.0

package/templates/imessage/lib/format.ts

@@ -0,0 +1,170 @@
+// Pure display helpers for the dashboard. No React, no data access.
+
+export interface ThreadMessage {
+  id: string;
+  direction: "in" | "out";
+  kind: string;
+  text: string;
+  status: string;
+  detail?: string | null;
+  createdAt: string;
+}
+
+export function initials(name: string | null | undefined, handle: string): string {
+  const source = (name ?? "").trim();
+  if (source) {
+    const parts = source.split(/\s+/).filter(Boolean);
+    const letters = parts.length > 1 ? parts[0][0] + parts[parts.length - 1][0] : parts[0].slice(0, 2);
+    return letters.toUpperCase();
+  }
+  if (handle.includes("@")) return handle[0].toUpperCase();
+  return handle.slice(-2);
+}
+
+/** "3:04 PM" today, "Yesterday", weekday within a week, else "Sep 3". */
+export function listTime(iso: string | null | undefined, now = new Date()): string {
+  if (!iso) return "";
+  const d = new Date(iso);
+  if (Number.isNaN(d.getTime())) return "";
+  const startOfDay = (x: Date) => new Date(x.getFullYear(), x.getMonth(), x.getDate()).getTime();
+  const days = Math.round((startOfDay(now) - startOfDay(d)) / 86_400_000);
+  if (days <= 0) return d.toLocaleTimeString("en-US", { hour: "numeric", minute: "2-digit" });
+  if (days === 1) return "Yesterday";
+  if (days < 7) return d.toLocaleDateString("en-US", { weekday: "long" });
+  return d.toLocaleDateString("en-US", { month: "short", day: "numeric" });
+}
+
+/** Separator label between bubbles, iMessage style: "Today 3:04 PM". */
+export function separatorLabel(iso: string, now = new Date()): string {
+  const d = new Date(iso);
+  const time = d.toLocaleTimeString("en-US", { hour: "numeric", minute: "2-digit" });
+  const day = listTime(iso, now);
+  return day.includes(":") ? `Today ${time}` : `${day} ${time}`;
+}
+
+/** "just now", "2 min ago", "3 h ago", or a date. */
+export function ago(iso: string | null | undefined, now = new Date()): string {
+  if (!iso) return "never";
+  const ms = now.getTime() - new Date(iso).getTime();
+  if (!Number.isFinite(ms)) return "never";
+  if (ms < 45_000) return "just now";
+  if (ms < 3_600_000) return `${Math.round(ms / 60_000)} min ago`;
+  if (ms < 86_400_000) return `${Math.round(ms / 3_600_000)} h ago`;
+  return new Date(iso).toLocaleDateString("en-US", { month: "short", day: "numeric" });
+}
+
+export interface ThreadItem {
+  message: ThreadMessage;
+  /** Show a time separator above this bubble. */
+  separator: string | null;
+  /** Last bubble in a run from the same side: gets the tail. */
+  tail: boolean;
+  /** Caption under the bubble (status), or null. */
+  caption: string | null;
+  captionTone: "muted" | "warn" | "error";
+}
+
+const GAP_FOR_SEPARATOR_MS = 60 * 60 * 1000;
+
+/** Caption for a message whose status the owner should see. */
+export function statusCaption(m: ThreadMessage, isLastOutbound: boolean): Pick<ThreadItem, "caption" | "captionTone"> {
+  if (m.direction === "in") {
+    switch (m.status) {
+      case "awaiting_setup":
+        return { caption: "Not answered yet: waiting for setup", captionTone: "warn" };
+      case "rate_limited":
+        return { caption: "Not answered: hourly limit reached", captionTone: "warn" };
+      case "failed":
+        return { caption: `Reply failed${m.detail ? `: ${m.detail}` : ""}`, captionTone: "error" };
+      case "ignored":
+        if (m.detail === "unknown_sender") return { caption: "Not answered: not on your allowlist", captionTone: "muted" };
+        if (m.detail === "blocked") return { caption: "Not answered: blocked", captionTone: "muted" };
+        if (m.detail === "opt_out") return { caption: "Texted STOP: opted out", captionTone: "muted" };
+        if (m.detail === "opt_in") return { caption: "Texted START: opted back in", captionTone: "muted" };
+        if (m.detail === "opted_out") return { caption: "Not answered: opted out", captionTone: "muted" };
+        if (m.detail === "paused") return { caption: "Not answered: assistant paused", captionTone: "muted" };
+        return { caption: "Not answered", captionTone: "muted" };
+      default:
+        return { caption: null, captionTone: "muted" };
+    }
+  }
+  const who = m.kind === "owner" ? "Sent by you" : m.kind === "reminder" ? "Reminder" : m.kind === "auto_reply" ? "Automatic reply" : null;
+  switch (m.status) {
+    case "queued":
+    case "leased":
+      return { caption: "Sending…", captionTone: "muted" };
+    case "dry_run":
+      return { caption: "Dry run: not sent", captionTone: "warn" };
+    case "failed":
+      return { caption: `Not delivered${m.detail ? `: ${m.detail}` : ""}`, captionTone: "error" };
+    default:
+      if (isLastOutbound) return { caption: who ? `${who} · Delivered` : "Delivered", captionTone: "muted" };
+      return { caption: who, captionTone: "muted" };
+  }
+}
+
+export function buildThread(messages: ThreadMessage[]): ThreadItem[] {
+  const sorted = [...messages].sort((a, b) => (a.createdAt < b.createdAt ? -1 : a.createdAt > b.createdAt ? 1 : 0));
+  let lastOutboundIndex = -1;
+  sorted.forEach((m, i) => {
+    if (m.direction === "out") lastOutboundIndex = i;
+  });
+  return sorted.map((m, i) => {
+    const prev = sorted[i - 1];
+    const next = sorted[i + 1];
+    const gap = prev ? new Date(m.createdAt).getTime() - new Date(prev.createdAt).getTime() : Infinity;
+    const { caption, captionTone } = statusCaption(m, i === lastOutboundIndex);
+    return {
+      message: m,
+      separator: gap > GAP_FOR_SEPARATOR_MS ? separatorLabel(m.createdAt) : null,
+      tail:
+        !next ||
+        next.direction !== m.direction ||
+        new Date(next.createdAt).getTime() - new Date(m.createdAt).getTime() > GAP_FOR_SEPARATOR_MS ||
+        caption !== null,
+      caption,
+      captionTone,
+    };
+  });
+}
+
+/**
+ * The refusal in a tool result, if any: an is_error result, or a JSON body
+ * with an `error` field. Returns null when the tool succeeded.
+ */
+export function toolRefusal(content: unknown, isError: boolean): string | null {
+  const text = typeof content === "string" ? content : JSON.stringify(content ?? "");
+  if (isError) return text.slice(0, 160);
+  try {
+    const parsed = JSON.parse(text) as { error?: unknown };
+    if (parsed && typeof parsed === "object" && typeof parsed.error === "string") return parsed.error;
+  } catch {
+    // Plain-text results are successes.
+  }
+  return null;
+}
+
+/** Human summary of an agent tool call for the activity list. */
+export function describeToolCall(name: string, input: Record<string, unknown>): string {
+  switch (name) {
+    case "remember_note":
+      return `Saved a note: ${String(input.text ?? "")}`;
+    case "recall_notes":
+      return "Read saved notes";
+    case "forget_note":
+      return "Deleted a note";
+    case "set_reminder": {
+      const when = typeof input.when === "string" ? new Date(input.when) : null;
+      const at = when && !Number.isNaN(when.getTime())
+        ? when.toLocaleString("en-US", { weekday: "short", hour: "numeric", minute: "2-digit" })
+        : "later";
+      return `Scheduled a reminder for ${at}`;
+    }
+    case "list_reminders":
+      return "Checked upcoming reminders";
+    case "cancel_reminder":
+      return "Cancelled a reminder";
+    default:
+      return `Used ${name}`;
+  }
+}

package/templates/imessage/lib/gate.ts

@@ -0,0 +1,104 @@
+// Who the assistant answers. Every inbound message goes through `decideInbound`
+// before anything is scheduled, so the assistant never becomes a relay for
+// whoever happens to text the number.
+//
+//   allowed contact      → answer (subject to the per-contact rate limit)
+//   blocked contact      → store, never answer
+//   unknown sender       → store as a request; optionally send ONE fixed reply
+//   STOP / START         → opt out / back in; applies to every contact
+
+export type ContactStatus = "allowed" | "blocked" | "unknown";
+export type UnknownSenderPolicy = "ignore" | "reply_once";
+
+export interface GateSettings {
+  unknownSenderPolicy: UnknownSenderPolicy;
+  /** Inbound messages per contact per rolling hour that get an answer. */
+  rateLimitPerHour: number;
+  /** When true the assistant answers nobody. Messages are still stored. */
+  paused: boolean;
+}
+
+export interface GateContact {
+  status: ContactStatus;
+  optedOut: boolean;
+  /** Set once the one-time reply to an unknown sender has been sent. */
+  autoReplySentAt: string | null;
+}
+
+export type InboundDecision =
+  | { action: "answer" }
+  | { action: "auto_reply" }
+  | { action: "opt_out" }
+  | { action: "opt_in" }
+  | {
+      action: "ignore";
+      reason: "blocked" | "unknown_sender" | "opted_out" | "rate_limited" | "paused";
+    };
+
+const STOP_WORDS = new Set(["stop", "stopall", "unsubscribe", "cancel", "end", "quit"]);
+const START_WORDS = new Set(["start", "unstop", "yes"]);
+
+function keyword(text: string): string {
+  return text.trim().toLowerCase().replace(/[.!\s]+$/g, "");
+}
+
+export function isStopKeyword(text: string): boolean {
+  return STOP_WORDS.has(keyword(text));
+}
+
+export function isStartKeyword(text: string): boolean {
+  return START_WORDS.has(keyword(text));
+}
+
+export function decideInbound(
+  contact: GateContact,
+  text: string,
+  settings: GateSettings,
+  answeredInLastHour: number,
+): InboundDecision {
+  if (isStopKeyword(text)) return { action: "opt_out" };
+  if (contact.optedOut) {
+    return isStartKeyword(text) ? { action: "opt_in" } : { action: "ignore", reason: "opted_out" };
+  }
+  if (contact.status === "blocked") return { action: "ignore", reason: "blocked" };
+  if (contact.status !== "allowed") {
+    if (settings.unknownSenderPolicy === "reply_once" && !contact.autoReplySentAt && !settings.paused) {
+      return { action: "auto_reply" };
+    }
+    return { action: "ignore", reason: "unknown_sender" };
+  }
+  if (settings.paused) return { action: "ignore", reason: "paused" };
+  if (answeredInLastHour >= Math.max(0, settings.rateLimitPerHour)) {
+    return { action: "ignore", reason: "rate_limited" };
+  }
+  return { action: "answer" };
+}
+
+/** Inbound rows stored per unknown sender per hour. Past this, retries and floods are dropped. */
+export const UNKNOWN_SENDER_STORE_LIMIT = 20;
+
+/** New unknown contacts created per rolling hour, across all senders. Past this, new senders are dropped. */
+export const NEW_UNKNOWN_CONTACTS_PER_HOUR = 50;
+
+/** Minimum time between two STOP (or two START) confirmations to one contact. */
+export const KEYWORD_REPLY_INTERVAL_MS = 24 * 60 * 60 * 1000;
+
+/** True when a keyword confirmation may be sent now, given when the last one went out. */
+export function mayConfirmKeyword(lastSentAt: string | null, now: Date): boolean {
+  if (!lastSentAt) return true;
+  const last = Date.parse(lastSentAt);
+  return !Number.isFinite(last) || now.getTime() - last >= KEYWORD_REPLY_INTERVAL_MS;
+}
+
+export const DEFAULT_SETTINGS = {
+  ownerName: "",
+  timezone: "America/Chicago",
+  unknownSenderPolicy: "ignore" as UnknownSenderPolicy,
+  unknownSenderReply:
+    "Hi, this number is an automated assistant that only replies to people on its contact list. Your message was passed along.",
+  rateLimitPerHour: 30,
+  paused: false,
+};
+
+export const OPT_OUT_REPLY = "You won't get more messages from this number. Text START to resume.";
+export const OPT_IN_REPLY = "You're back on. Text STOP any time to stop messages.";

package/templates/imessage/lib/handles.ts

@@ -0,0 +1,67 @@
+// iMessage handles: a phone number in E.164 form or an email address (Apple ID).
+// Every handle that enters the database or leaves through a transport goes
+// through `normalizeHandle`, so one person has exactly one Contact row no matter
+// how a transport formats the number.
+
+export type HandleKind = "phone" | "email";
+
+export interface NormalizedHandle {
+  handle: string;
+  kind: HandleKind;
+}
+
+const EMAIL_RE = /^[a-z0-9._%+-]{1,64}@[a-z0-9.-]{1,253}\.[a-z]{2,24}$/;
+const E164_RE = /^\+[1-9][0-9]{6,14}$/;
+
+/**
+ * Normalize a raw handle. Returns null for anything that is not a plausible
+ * phone number or email, including group-chat identifiers (`chat123…`).
+ *
+ * Phone rules: strip spaces, dashes, dots and parentheses. A leading `+` keeps
+ * the country code as written. Ten bare digits get `defaultCountryCode`
+ * (default "1", North America). Eleven digits starting with that code get a `+`.
+ */
+export function normalizeHandle(
+  raw: string | null | undefined,
+  defaultCountryCode = "1",
+): NormalizedHandle | null {
+  if (typeof raw !== "string") return null;
+  let value = raw.trim();
+  if (value === "" || value.length > 320) return null;
+  // Some transports prefix the service: "tel:+1555…", "mailto:a@b.c", "iMessage;-;+1555…".
+  value = value.replace(/^(tel:|mailto:|sms:|imessage:)/i, "");
+  const semi = value.lastIndexOf(";");
+  if (semi !== -1) value = value.slice(semi + 1);
+
+  if (value.includes("@")) {
+    const email = value.toLowerCase();
+    return EMAIL_RE.test(email) ? { handle: email, kind: "email" } : null;
+  }
+
+  const hasPlus = value.startsWith("+");
+  if (!/^\+?[0-9\s().-]+$/.test(value)) return null;
+  const digits = value.replace(/[^0-9]/g, "");
+  let e164: string;
+  if (hasPlus) {
+    e164 = `+${digits}`;
+  } else if (digits.length === 10) {
+    e164 = `+${defaultCountryCode}${digits}`;
+  } else if (digits.length === 11 && digits.startsWith(defaultCountryCode)) {
+    e164 = `+${digits}`;
+  } else {
+    return null;
+  }
+  return E164_RE.test(e164) ? { handle: e164, kind: "phone" } : null;
+}
+
+/** True when `value` is already a normalized handle. */
+export function isNormalizedHandle(value: string): boolean {
+  return E164_RE.test(value) || EMAIL_RE.test(value);
+}
+
+/** "+15551234567" → "(555) 123-4567" for North American numbers; others unchanged. */
+export function formatHandle(handle: string): string {
+  const m = handle.match(/^\+1(\d{3})(\d{3})(\d{4})$/);
+  if (m) return `(${m[1]}) ${m[2]}-${m[3]}`;
+  return handle;
+}

package/templates/imessage/lib/provider.ts

@@ -0,0 +1,38 @@
+// Whether the server has a model provider configured, derived from the same
+// environment variables Pylon reads for `ctx.llm`:
+//
+//   PYLON_LLM_PROVIDER (or PYLON_AI_PROVIDER) = "anthropic" | "openai"
+//   ANTHROPIC_API_KEY / OPENAI_API_KEY (or PYLON_AI_API_KEY)
+//
+// With no provider set, an ANTHROPIC_API_KEY selects Anthropic and an
+// OPENAI_API_KEY selects OpenAI. The result carries no key material.
+
+export type ProviderName = "anthropic" | "openai";
+
+export interface ProviderStatus {
+  configured: boolean;
+  provider: ProviderName | null;
+}
+
+type Env = Record<string, string | undefined>;
+
+function present(env: Env, key: string): boolean {
+  const v = env[key];
+  return typeof v === "string" && v.trim().length > 0;
+}
+
+export function providerStatus(env: Env): ProviderStatus {
+  const explicit = (env.PYLON_LLM_PROVIDER || env.PYLON_AI_PROVIDER || "").trim();
+  if (explicit === "anthropic") {
+    const ok = present(env, "ANTHROPIC_API_KEY") || present(env, "PYLON_AI_API_KEY");
+    return { configured: ok, provider: "anthropic" };
+  }
+  if (explicit === "openai") {
+    const ok = present(env, "OPENAI_API_KEY") || present(env, "PYLON_AI_API_KEY");
+    return { configured: ok, provider: "openai" };
+  }
+  if (explicit !== "") return { configured: false, provider: null };
+  if (present(env, "ANTHROPIC_API_KEY")) return { configured: true, provider: "anthropic" };
+  if (present(env, "OPENAI_API_KEY")) return { configured: true, provider: "openai" };
+  return { configured: false, provider: null };
+}

package/templates/imessage/lib/relay-protocol.ts

@@ -0,0 +1,95 @@
+// The wire contract between the Mac relay (relay/main.ts) and the server
+// (functions/relaySync.ts). One endpoint, one round trip per poll:
+//
+//   relay → server  POST /api/fn/relaySync
+//                   Authorization: Bearer <RELAY_TOKEN>
+//                   { relayVersion, host, inbound: RelayInboundItem[], acks: RelayAck[] }
+//   server → relay  { accepted: string[], outbound: RelayOutboundItem[] }
+//
+// `accepted` lists the inbound guids the server stored (or had already
+// stored); the relay advances its chat.db watermark only past those.
+// `outbound` is the next batch of replies to send; each is leased to the relay
+// for OUTBOUND_LEASE_MS and returns to the queue when no ack arrives in time.
+
+import { normalizeHandle } from "./handles";
+import type { InboundMessage, MessageTransport, SendResult } from "./transport";
+
+export const RELAY_PROTOCOL_VERSION = 1;
+export const MAX_INBOUND_PER_SYNC = 100;
+export const MAX_OUTBOUND_PER_SYNC = 20;
+export const MAX_TEXT_CHARS = 20_000;
+export const OUTBOUND_LEASE_MS = 60_000;
+/** A relay reply leased this many times without an ack is marked failed. */
+export const MAX_RELAY_ATTEMPTS = 5;
+
+export interface RelayInboundItem {
+  /** chat.db message.guid — globally unique per message. */
+  guid: string;
+  handle: string;
+  text: string;
+  sentAt: string;
+  service: string;
+}
+
+export interface RelayOutboundItem {
+  id: string;
+  handle: string;
+  text: string;
+}
+
+export interface RelayAck {
+  id: string;
+  ok: boolean;
+  error?: string;
+  /** The relay runs with RELAY_DRY_RUN and did not hand the message to Messages.app. */
+  dryRun?: boolean;
+}
+
+export interface RelaySyncRequest {
+  relayVersion: string;
+  host: string;
+  inbound: RelayInboundItem[];
+  acks: RelayAck[];
+}
+
+export interface RelaySyncResponse {
+  accepted: string[];
+  outbound: RelayOutboundItem[];
+}
+
+const GUID_RE = /^[A-Za-z0-9:._-]{1,128}$/;
+
+export function parseRelayInbound(item: unknown): { message: InboundMessage } | { skip: string } {
+  if (typeof item !== "object" || item === null) return { skip: "not an object" };
+  const it = item as Partial<RelayInboundItem>;
+  if (typeof it.guid !== "string" || !GUID_RE.test(it.guid)) return { skip: "bad guid" };
+  const sender = normalizeHandle(typeof it.handle === "string" ? it.handle : "");
+  if (!sender) return { skip: "unrecognized sender" };
+  const text = typeof it.text === "string" ? it.text.slice(0, MAX_TEXT_CHARS) : "";
+  if (text.trim() === "") return { skip: "empty message" };
+  const sentAtMs = typeof it.sentAt === "string" ? Date.parse(it.sentAt) : Number.NaN;
+  return {
+    message: {
+      externalId: `relay:${it.guid}`,
+      handle: sender.handle,
+      text,
+      sentAt: new Date(Number.isFinite(sentAtMs) ? sentAtMs : Date.now()).toISOString(),
+      service: typeof it.service === "string" && it.service !== "" ? it.service.slice(0, 32) : "iMessage",
+    },
+  };
+}
+
+/**
+ * The relay adapter. Sending does not talk to the Mac: the outbound Message
+ * row is already stored with status "queued", and the relay collects it on its
+ * next sync. `send` therefore only reports that.
+ */
+export function relayTransport(dryRun: boolean): MessageTransport {
+  return {
+    name: "relay",
+    normalizeInbound: parseRelayInbound,
+    async send(): Promise<SendResult> {
+      return dryRun ? { status: "dry_run" } : { status: "queued" };
+    },
+  };
+}

package/templates/imessage/lib/reminders.ts

@@ -0,0 +1,41 @@
+// Bounds for reminders the assistant schedules. The model picks the time; the
+// server decides whether it is acceptable.
+
+export const MIN_REMINDER_LEAD_MS = 5 * 60_000;
+export const MAX_REMINDER_HORIZON_MS = 366 * 24 * 60 * 60 * 1000;
+export const MAX_OPEN_REMINDERS_PER_CONTACT = 20;
+/** Reminders the assistant may create for one contact in a rolling day, sent or not. */
+export const MAX_REMINDERS_PER_CONTACT_PER_DAY = 10;
+export const MAX_REMINDER_CHARS = 500;
+export const MAX_NOTE_CHARS = 500;
+export const MAX_NOTES_PER_CONTACT = 100;
+
+export type ReminderTimeCheck = { ok: true; dueAt: string; dueMs: number } | { ok: false; error: string };
+
+/**
+ * Validate a reminder time. Requires an explicit offset or `Z` so "9am" is
+ * never silently read in the server's timezone.
+ */
+export function checkReminderTime(when: string, now: Date): ReminderTimeCheck {
+  const trimmed = when.trim();
+  if (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:?\d{2})$/.test(trimmed)) {
+    return {
+      ok: false,
+      error: "Use an ISO 8601 time with a UTC offset, for example 2026-10-03T09:00:00-05:00.",
+    };
+  }
+  const ms = Date.parse(trimmed);
+  if (!Number.isFinite(ms)) return { ok: false, error: "That time could not be parsed." };
+  if (ms < now.getTime() + MIN_REMINDER_LEAD_MS) {
+    return { ok: false, error: "The reminder time must be at least five minutes in the future." };
+  }
+  if (ms > now.getTime() + MAX_REMINDER_HORIZON_MS) {
+    return { ok: false, error: "Reminders can be at most one year out." };
+  }
+  return { ok: true, dueAt: new Date(ms).toISOString(), dueMs: ms };
+}
+
+/** Collapse whitespace and cap length for text the model wants to store. */
+export function cleanStoredText(text: string, max: number): string {
+  return text.replace(/\s+/g, " ").trim().slice(0, max);
+}

package/templates/imessage/lib/secrets.ts

@@ -0,0 +1,59 @@
+import { createHash, timingSafeEqual } from "node:crypto";
+
+// Shared-secret checks for the two inbound doors (the Sendblue webhook and the
+// Mac relay). Both compare a secret the caller presents against one in the
+// server environment.
+
+/**
+ * Constant-time string comparison. Both sides are hashed to 32 bytes first so
+ * the comparison takes the same time whatever the lengths are, and a length
+ * mismatch is not observable.
+ */
+export function constantTimeEqual(presented: string, expected: string): boolean {
+  const a = createHash("sha256").update(presented, "utf8").digest();
+  const b = createHash("sha256").update(expected, "utf8").digest();
+  return timingSafeEqual(a, b) && presented.length === expected.length;
+}
+
+/** Secrets shorter than this are rejected as configuration, not accepted. */
+export const MIN_SECRET_LENGTH = 24;
+
+export type SecretCheck =
+  | { ok: true }
+  | { ok: false; reason: "not_configured" | "missing" | "invalid" };
+
+/**
+ * Check a presented secret against the configured one. An unset or too-short
+ * configured secret fails closed with `not_configured`: an empty secret must
+ * never mean "accept anything".
+ */
+export function checkSecret(
+  presented: string | null | undefined,
+  configured: string | null | undefined,
+): SecretCheck {
+  const expected = (configured ?? "").trim();
+  if (expected.length < MIN_SECRET_LENGTH) return { ok: false, reason: "not_configured" };
+  const got = (presented ?? "").trim();
+  if (got === "") return { ok: false, reason: "missing" };
+  return constantTimeEqual(got, expected) ? { ok: true } : { ok: false, reason: "invalid" };
+}
+
+/** Pull the token out of an `Authorization: Bearer <token>` header value. */
+export function bearerToken(header: string | null | undefined): string | null {
+  if (typeof header !== "string") return null;
+  const m = header.match(/^\s*Bearer\s+(\S+)\s*$/i);
+  return m ? m[1] : null;
+}
+
+/** Case-insensitive header read. The runtime lowercases names; this also covers fixtures. */
+export function headerValue(
+  headers: Record<string, string> | null | undefined,
+  name: string,
+): string | null {
+  if (!headers) return null;
+  const want = name.toLowerCase();
+  for (const [k, v] of Object.entries(headers)) {
+    if (k.toLowerCase() === want) return v;
+  }
+  return null;
+}