@hanzo/event 0.3.32 → 0.3.34

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanzo/event",
-  "version": "0.3.32",
+  "version": "0.3.34",
   "description": "Hanzo Event — the ONE telemetry client. Emits pageview/event/identify/group to the Hanzo Cloud event stream (POST /v1/event), AND reports errors to Sentry as real Sentry envelopes — the error plane needs a DSN, without one nothing reaches Sentry. First-touch attribution, beacon-on-unload, auto error capture, client-side secret/PII scrubbing, a shared event + goal vocabulary. Subsumes @sentry.",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
@@ -17,7 +17,6 @@
   "files": [
     "dist",
     "src",
-    "hz.js",
     "README.md",
     "TAXONOMY.md"
   ],
@@ -82,7 +81,7 @@
     "build": "tsup",
     "dev": "tsup --watch",
     "test": "vitest run",
-    "typecheck": "tsc --noEmit",
+    "typecheck": "tsgo --noEmit -p tsconfig.json",
     "clean": "rm -rf dist"
   }
 }

package/src/anon.d.ts

@@ -1,5 +1,5 @@
 // Types for anon.js, which is hand-written ES5 rather than TypeScript because
-// hz.js and the door's hosted tag inline it VERBATIM and neither has a compiler.
+// The door's hosted tag inlines it VERBATIM and has no compiler.
 // The declarations are here so the bundled client still imports it typed.
 
 /** Mints a time-ordered UUIDv7 (RFC 9562 §5.7) for `now` in epoch milliseconds. */
@@ -8,7 +8,7 @@ export declare function hzUuidv7(now?: number): string
 /**
  * The stable anonymous id for this browser, or '' during SSR.
  *
- * cookie · localStorage `hz_anon_id` · localStorage `hz_id` · in-memory · mint —
+ * cookie · localStorage `iam-anon-id` · adopted keys · in-memory · mint —
  * every existing id is adopted, and only a browser holding none is given a new one.
  */
 export declare function hzAnonId(): string

package/src/anon.js

@@ -1,35 +1,42 @@
-/*! anon.js — THE anonymous-identity chain. ONE implementation, three distributions.
+/*! anon.js — THE anonymous-identity chain. ONE implementation, two distributions.
  *
  * One browser is ONE person on every Hanzo surface, whichever client a page
- * happens to have loaded. There were three implementations writing TWO keys —
- * `hz_anon_id` (the npm client, the hosted tag) and `hz_id` (hz.js) — so the same
- * visitor was several people depending on which snippet the surface shipped.
+ * happens to have loaded. There were once three implementations writing TWO keys —
+ * `hz_anon_id` and `hz_id` — so the same visitor was several people depending on
+ * which snippet the surface shipped.
  *
- * The three call sites:
+ * The two call sites:
  *   1. src/storage.ts        — the bundled npm client; IMPORTS this file.
- *   2. hz.js                 — the no-build script tag; INLINES the marked region.
- *   3. hanzoai/cloud apps/analytics/tag.js — the tag the door hosts at
+ *   2. hanzoai/cloud apps/analytics/tag.js — the tag the door hosts at
  *      /v1/event.js; vendors this file and its tag.go serves the marked region
  *      with the tag as one asset, so the door holds no second copy either.
  *
- * (2) and (3) have no bundler and cannot import anything, which is why the chain
- * lives in a file that is plain ES5 rather than in a .ts: the region between the
- * BEGIN and END markers is COPIED VERBATIM, and src/anon.test.ts fails if hz.js's
- * copy is so much as a byte different. Keep the region ES5, dependency-free,
- * `hz`-prefixed (it is spliced into other people's scopes) and unformatted — a
- * reformat of one copy is a diff against the other.
+ * (2) has no bundler and cannot import anything, which is why the chain lives in a
+ * file that is plain ES5 rather than in a .ts: the region between the BEGIN and END
+ * markers is COPIED VERBATIM. Keep it ES5, dependency-free, `hz`-prefixed (it is
+ * spliced into other people's scopes) and unformatted — a reformat here is a diff
+ * against the vendored copy. After editing, resync the door:
+ *
+ *   curl -fsSL https://unpkg.com/@hanzo/event/src/anon.js -o apps/analytics/anon.js
  */
 
-/* ── BEGIN hz anon chain — copied VERBATIM into hz.js and hanzoai/cloud ────── */
+/* ── BEGIN hz anon chain — copied VERBATIM into hanzoai/cloud ──────────────── */
 
-/** The ONE anonymous-id key, on every surface and in every distribution. */
-var HZ_ANON_KEY = 'hz_anon_id'
+/** The ONE anonymous-id key, on every surface and in every distribution.
+ *
+ *  It names what it is, not who ships it: this value is visible to anyone who opens
+ *  their own cookie jar, and a vendor's name has no business there. Identity is IAM's
+ *  concern whether or not the visitor has said who they are. */
+var HZ_ANON_KEY = 'iam-anon-id'
 
-/** hz.js used to write `hz_id` — a SECOND identity space, so the one-paste tag
- *  and the npm client were two different people on one page. It is READ and never
- *  written: an id already in the wild is ADOPTED into the shared identity, because
- *  minting over one detaches a returning visitor from their own history. */
-var HZ_ANON_LEGACY_KEY = 'hz_id'
+/** Keys an id may already be living under. READ, never written.
+ *
+ *  Each was canonical once — `hz_anon_id` most recently, and `hz_id` before it, when a
+ *  no-build tag wrote a second identity space and one page could hold two people.
+ *  Adopting an id already in the wild is what makes this a rename rather than an
+ *  erasure: minting over one detaches a returning visitor from their own history.
+ *  They are never written, so they leave with the cookies that hold them. */
+var HZ_ANON_ADOPT = ['hz_anon_id', 'hz_id']
 
 /** The registrable domain the cookie is scoped to, so docs, cloud, console,
  *  studio, pay, id and www all read the ONE id. localStorage cannot do this: it is
@@ -165,7 +172,7 @@ function hzAnonWrite(name, value) {
  * Resolution is strictly ADDITIVE — every id that already exists is ADOPTED, and
  * only a browser holding none of them is given a new one:
  *
- *   cookie · localStorage hz_anon_id · localStorage hz_id · in-memory · mint
+ *   cookie · localStorage iam-anon-id · adopted keys · in-memory · mint
  *
  * Minting over an id resets a returning visitor and detaches them from their own
  * history, so the order is the migration: the cookie is the shared home, the two
@@ -175,13 +182,26 @@ function hzAnonWrite(name, value) {
  * localStorage keeps being written, so a rollback finds everyone where it left
  * them, and a browser that refuses cookies still holds one id per origin.
  */
+/**
+ * hzAnonAdopted returns an id already living under a key that used to be canonical,
+ * from the cookie jar first — that is the copy shared across subdomains, so a visitor
+ * who arrived on one host is the same person on the next.
+ */
+function hzAnonAdopted(s) {
+  for (var i = 0; i < HZ_ANON_ADOPT.length; i++) {
+    var id = hzAnonCookie(HZ_ANON_ADOPT[i]) || hzAnonItem(s, HZ_ANON_ADOPT[i])
+    if (id) return id
+  }
+  return ''
+}
+
 function hzAnonId() {
   if (typeof window === 'undefined') return '' // SSR / prerender: no browser to identify
   var s = hzAnonStore()
   var id =
     hzAnonCookie(HZ_ANON_KEY) ||
     hzAnonItem(s, HZ_ANON_KEY) ||
-    hzAnonItem(s, HZ_ANON_LEGACY_KEY) ||
+    hzAnonAdopted(s) ||
     hzAnonMemo ||
     hzUuidv7()
   hzAnonMemo = id

package/src/anon.test.ts

@@ -1,15 +1,13 @@
-// The anonymous-identity chain is ONE implementation with three call sites, and
-// two of them cannot import it: hz.js and the tag hanzoai/cloud hosts at
-// /v1/event.js have no bundler, so they carry the marked region of anon.js
-// VERBATIM. That is the drift risk this file exists to remove — three snippets
-// that agree the day they are written and disagree a quarter later, which is
-// exactly how the same browser came to hold two different anonymous ids under two
-// different key names.
+// The anonymous-identity chain is ONE implementation with two call sites, and one
+// of them cannot import it: the tag hanzoai/cloud hosts at /v1/event.js has no
+// bundler, so it carries the marked region of anon.js VERBATIM. That is the drift
+// risk this file exists to remove — snippets that agree the day they are written
+// and disagree a quarter later, which is exactly how the same browser came to hold
+// two different anonymous ids under two different key names.
 //
-// The behavioural contract is proven where each distribution runs it:
-// storage.test.ts (the npm client) and hz.test.ts (the script tag). This file
-// proves the copies are the SAME TEXT, which is the only thing that keeps those
-// two suites testing one implementation instead of two.
+// The behavioural contract is proven where the chain runs: storage.test.ts. This
+// file proves the region is SPLICEABLE and that it ships, which is what lets the
+// door vendor it instead of writing a second one.
 
 import { describe, expect, it } from 'vitest'
 import { readFileSync } from 'node:fs'
@@ -32,37 +30,19 @@ function span(src: string, what: string): [number, number] {
 /** The shared region, markers included. */
 const region = (src: string, what: string): string => src.slice(...span(src, what))
 
-/** Everything that is NOT the shared region. */
-function outside(src: string, what: string): string {
-  const [b, e] = span(src, what)
-  return src.slice(0, b) + src.slice(e)
-}
-
 const ANON = read('./anon.js')
-const HZ = read('../hz.js')
 
 describe('the shared anon chain', () => {
-  it('is in hz.js as the same text, byte for byte', () => {
-    // Not "equivalent" — IDENTICAL. Anything weaker (normalising whitespace,
-    // comparing behaviour) permits the copies to say different things about which
-    // key they read, which is the bug. To change the chain, edit src/anon.js and
-    // re-splice; never patch a copy.
-    expect(region(HZ, 'hz.js')).toBe(region(ANON, 'anon.js'))
-  })
-
-  it('names one key, and hz.js holds no identity code of its own', () => {
-    // hz.js used to mint into hz_id — a second identity space, so the one-paste
-    // tag and the npm client were two people on one page. Neither key may be
-    // NAMED outside the shared region: a snippet that spells a key is a snippet
-    // that has an opinion about identity, and there is one opinion now.
-    const rest = outside(HZ, 'hz.js')
-    expect(rest).not.toContain("'hz_anon_id'")
-    expect(rest).not.toContain("'hz_id'")
+  it('is marked, so the door can splice exactly it', () => {
+    // cloud's tag.go slices between these markers and PANICS if it cannot find
+    // them, so losing a marker ships a tag whose every event carries an undefined
+    // identity. To change the chain, edit this file; never patch a copy.
+    expect(region(ANON, 'anon.js')).toContain(BEGIN)
   })
 
   it('is inlineable: the region imports nothing and declares no ES6', () => {
-    // It is spliced into two files that have no bundler and into pages the client
-    // does not control, so it must be ES5, self-contained and hz-prefixed.
+    // It is spliced into a file that has no bundler and into pages the client does
+    // not control, so it must be ES5, self-contained and hz-prefixed.
     const r = region(ANON, 'anon.js')
     expect(r).not.toMatch(/\b(?:import|export|const|let|class|=>)\b|=>/)
     for (const [, name] of r.matchAll(/^(?:function|var) ([A-Za-z_$][\w$]*)/gm)) {
@@ -72,9 +52,8 @@ describe('the shared anon chain', () => {
 
   it('ships in the published package, for the door to vendor', () => {
     // hanzoai/cloud vendors this file whole and its tag.go serves the region with
-    // the tag as one asset, so the third call site holds no second copy either.
+    // the tag as one asset, so the second call site holds no copy of its own.
     const pkg = JSON.parse(read('../package.json')) as { files: string[] }
     expect(pkg.files).toContain('src')
-    expect(pkg.files).toContain('hz.js')
   })
 })

package/src/core.ts

@@ -46,6 +46,7 @@ import {
   deriveChannel,
 } from './attribution'
 import { dsnForProduct } from './dsn'
+import { keyForPage } from './org'
 import { EXCEPTION, PAGEVIEW } from './events'
 import { exceptionProperties } from './exception'
 import { scrubText } from './scrub'
@@ -283,12 +284,21 @@ export class Analytics {
       //      carries end to end — KMS `deploy/PUBLISHABLE_KEY` -> the PUBLISHABLE_KEY
       //      build-arg -> the NEXT_PUBLIC_ prefix Next inlines.
       //
-      // A surface that provides neither has no key, and its anonymous traffic
-      // files under `$public` (which drops track/identify/group and answers 200);
-      // the fix is to give it the KMS-sourced env, not to hardcode the org key
-      // here. The key is a credential-class value: its home is KMS, and the ONE
-      // build reads it from there.
-      ingestKey: config.ingestKey ?? readEnv('NEXT_PUBLIC_PUBLISHABLE_KEY'),
+      //   3. the org that owns the HOST this page is served from (`org.ts`).
+      //
+      // Step 3 fires only when a surface configured NOTHING, so it never overrides
+      // the KMS chain above — it replaces going dark with reporting to the right
+      // brand. That is what a static export needs: `output: export` inlines no env,
+      // so before this the only way to report was to commit a key literal, and the
+      // fleet grew one copy per site of a value with a single source.
+      //
+      // A surface no brand claims still has no key, and the door REFUSES an
+      // unattributed event (401 `ingest_key_required`) — the reserved `$public`
+      // tenant that once caught keyless beacons is retired, and anonymous ingest is
+      // refused at every door on every brand host. So there is no quiet fallback to
+      // rely on: an event lands in the org a credential names, or it does not land.
+      ingestKey:
+        config.ingestKey ?? readEnv('NEXT_PUBLIC_PUBLISHABLE_KEY') ?? keyForPage(),
     }
     this.transport = config.transport ?? new DefaultTransport()
     // Error plane, most specific source first: an explicit DSN wins, then the

package/src/index.ts

@@ -44,3 +44,10 @@ export type {
   Transport,
   WireEvent,
 } from './types'
+
+/** Which org owns a host's telemetry — the resolution that lets a surface report
+ *  correctly while configuring nothing. `keyFor` takes an optional keyring so a
+ *  runtime that receives one (hanzo.id serves every brand from one image) resolves
+ *  through this same function rather than a second copy of it. */
+export { ORG_DOMAIN, ORG_KEY, orgOf, keyFor, keyForPage } from './org'
+export type { Keyring } from './org'

package/src/org.test.ts

@@ -0,0 +1,113 @@
+import { describe, it, expect, afterEach } from 'vitest'
+
+import { createAnalytics } from './core'
+import { ORG_KEY, keyFor, keyForPage, orgOf } from './org'
+
+const ENV = 'NEXT_PUBLIC_PUBLISHABLE_KEY'
+
+/** Stand on a host the way a browser does, for the duration of one assertion. */
+function onHost<T>(hostname: string, run: () => T): T {
+  const had = 'location' in globalThis
+  const prev = (globalThis as { location?: unknown }).location
+  Object.defineProperty(globalThis, 'location', {
+    value: { hostname },
+    configurable: true,
+    writable: true,
+  })
+  try {
+    return run()
+  } finally {
+    if (had) Object.defineProperty(globalThis, 'location', { value: prev, configurable: true, writable: true })
+    else delete (globalThis as { location?: unknown }).location
+  }
+}
+
+afterEach(() => {
+  delete process.env[ENV]
+})
+
+describe('the org that owns a host', () => {
+  it('claims a brand domain and every subdomain of it', () => {
+    expect(orgOf('hanzo.ai')).toBe('hanzo')
+    expect(orgOf('lux.network')).toBe('lux')
+    expect(orgOf('zoo.ngo')).toBe('zoo')
+    // an alias inherits by naming its brand's domain — no entry of its own
+    expect(orgOf('explore.lux.network')).toBe('lux')
+    expect(orgOf('id.zoo.network')).toBe('zoo')
+  })
+
+  it('reads a hostname the way a domain compares', () => {
+    expect(orgOf('LUX.NETWORK')).toBe('lux')
+    expect(orgOf('lux.network:3000')).toBe('lux')
+    expect(orgOf('lux.network.')).toBe('lux')
+    expect(orgOf('  hanzo.ai  ')).toBe('hanzo')
+  })
+
+  it('claims nothing it does not own, rather than defaulting to Hanzo', () => {
+    // The defect this exists to prevent: an unrecognised host filed under a brand
+    // that is not its own is silent, reads as working, and surfaces a week later
+    // in someone else's warehouse.
+    for (const host of ['osage.id', 'pars.id', 'id.bootno.de', 'example.com', '']) {
+      expect(orgOf(host)).toBeUndefined()
+      expect(keyFor(host)).toBeUndefined()
+    }
+    // and it must not be fooled by a suffix that merely ENDS with a brand domain
+    expect(orgOf('notlux.network')).toBeUndefined()
+    expect(orgOf('evil-hanzo.ai')).toBeUndefined()
+  })
+})
+
+describe('the key a host resolves to', () => {
+  it('gives each brand its OWN key', () => {
+    const hanzo = keyFor('hanzo.ai')
+    const lux = keyFor('lux.network')
+    const zoo = keyFor('zoo.ngo')
+    for (const k of [hanzo, lux, zoo]) expect(k).toMatch(/^pk-/)
+    // The bug on record: one build-time key filed every brand's visitors into
+    // Hanzo's project. Three brands must resolve to three DIFFERENT keys.
+    expect(new Set([hanzo, lux, zoo]).size).toBe(3)
+    expect(lux).not.toBe(hanzo)
+    expect(zoo).not.toBe(hanzo)
+  })
+
+  it('refuses anything that is not publishable, failing closed', () => {
+    expect(keyFor('hanzo.ai', { hanzo: 'sk-live-secret' })).toBeUndefined()
+    expect(keyFor('hanzo.ai', { hanzo: '' })).toBeUndefined()
+    expect(keyFor('hanzo.ai', {})).toBeUndefined()
+  })
+
+  it('resolves a runtime keyring through the same function, not a second copy', () => {
+    // hanzo.id serves every brand from ONE image and gets its keyring at runtime.
+    expect(keyFor('id.lux.network', { lux: 'pk-runtime-lux' })).toBe('pk-runtime-lux')
+  })
+
+  it('is undefined off a browser, where there is no host to read', () => {
+    expect(keyForPage()).toBeUndefined()
+  })
+})
+
+describe('a surface that configures nothing', () => {
+  it('still reports, to its own brand', () => {
+    const lux = onHost('lux.network', () => createAnalytics({ product: 'site' }))
+    expect((lux as unknown as { cfg: { ingestKey?: string } }).cfg.ingestKey).toBe(ORG_KEY.lux)
+
+    const zoo = onHost('zoo.ngo', () => createAnalytics({ product: 'site' }))
+    expect((zoo as unknown as { cfg: { ingestKey?: string } }).cfg.ingestKey).toBe(ORG_KEY.zoo)
+  })
+
+  it('never overrides what the surface or the build already resolved', () => {
+    const explicit = onHost('lux.network', () =>
+      createAnalytics({ product: 'site', ingestKey: 'pk-explicit' })
+    )
+    expect((explicit as unknown as { cfg: { ingestKey?: string } }).cfg.ingestKey).toBe('pk-explicit')
+
+    process.env[ENV] = 'pk-from-the-build'
+    const env = onHost('lux.network', () => createAnalytics({ product: 'site' }))
+    expect((env as unknown as { cfg: { ingestKey?: string } }).cfg.ingestKey).toBe('pk-from-the-build')
+  })
+
+  it('has no key on a host no brand claims, and invents none', () => {
+    const none = onHost('example.com', () => createAnalytics({ product: 'site' }))
+    expect((none as unknown as { cfg: { ingestKey?: string } }).cfg.ingestKey).toBeUndefined()
+  })
+})

package/src/org.ts

@@ -0,0 +1,129 @@
+/**
+ * Which org owns a host's telemetry.
+ *
+ * A surface should not have to LEARN its key. It already knows the domain it is
+ * served from, and a domain belongs to exactly one brand, so the key is derivable
+ * and asking a surface to carry one is asking it to restate something already
+ * true. This module answers `orgOf(location.hostname)` and hands back that org's
+ * publishable key, which is what lets a static export report correctly while
+ * configuring nothing.
+ *
+ * This is the SAME question `hanzo.id` answers at runtime for the identity hosts
+ * (`pkgs/shared/src/ingest.ts`): one image serves every brand, so the key cannot
+ * be a property of the build. It was, and the bill is on record — Lux's, Zoo's,
+ * Osage's and Pars' visitors were all filed in HANZO's project, because one
+ * build-time key was inlined for every brand. That is the white-label boundary
+ * crossed in the direction that shows up latest. The marketing sites carry the
+ * identical defect in its other form: each commits its OWN key literal, so the
+ * fleet holds N copies of a value with one source, and a site added tomorrow
+ * reports nothing until somebody remembers to paste one in.
+ *
+ * A `pk-` is PUBLISHABLE: it authorizes a write into one org and mints no reading
+ * principal. It is readable in devtools on every deployed page that sends an
+ * event, so stating it here exposes nothing that serving the page did not. What
+ * it does buy is that correct attribution becomes the DEFAULT rather than
+ * something each surface opts into.
+ *
+ * Keyed by ORG, never by host: a brand's facts repeat on every alias it owns
+ * (`lux.id`, `id.lux.network`), and a key stated per host would have to be
+ * repeated too — so the day someone adds an alias and forgets the key, that host
+ * silently stops reporting. Stated once per org, a new alias inherits its brand's
+ * key by naming its brand's domain, which is all an alias ever says.
+ */
+
+/** One publishable key per org. */
+export type Keyring = Readonly<Record<string, string>>
+
+/**
+ * Each org's registrable domains. A host matches a domain when it IS that domain
+ * or a subdomain of it, so `explore.lux.network` needs no entry of its own.
+ *
+ * An org absent from this table resolves to undefined, and that is deliberate:
+ * `osage`, `pars` and `bootnode` have no project of their own yet, and reporting
+ * NOTHING is the honest answer. Filing them under a brand that is not theirs is
+ * the defect this module exists to prevent — it is silent, it reads as working,
+ * and it is only visible later in someone else's warehouse.
+ */
+export const ORG_DOMAIN: Readonly<Record<string, readonly string[]>> = Object.freeze({
+  hanzo: Object.freeze(['hanzo.ai', 'hanzo.app', 'hanzo.chat', 'hanzo.id', 'hanzo.bot', 'hanzo.sh']),
+  lux: Object.freeze([
+    'lux.network',
+    'lux.exchange',
+    'lux.market',
+    'lux.finance',
+    'lux.financial',
+    'lux.credit',
+    'lux.fund',
+    'lux.id',
+  ]),
+  zoo: Object.freeze(['zoo.ngo', 'zoo.network', 'zoolabs.id']),
+})
+
+/**
+ * Each org's publishable key — the same values `universe`'s `SPA_INGEST_KEYRING`
+ * serves to the identity hosts, which are each brand's own insights team token.
+ * Add an org here the day its project exists, never before.
+ */
+export const ORG_KEY: Keyring = Object.freeze({
+  hanzo: 'pk-rM_CdaF2MQckGCrla113SrR1oH4zvqN8xh2I95Z9tY8',
+  lux: 'pk-gUZp6ZVfhJzSwK-rb4oLbVkpCnMBx5uSCpxf_5yEhQk',
+  zoo: 'pk-3TKpKnERV9AQSsBUERWkZejC1O1mUxc1jRzsP3MPbs4',
+})
+
+/** `pk-` is publishable; `sk-` is not, and there is no third thing. Checked at the
+ *  one point a key becomes something a page will send, so a mistyped entry fails
+ *  closed rather than putting a secret in every visitor's tab. */
+const PUBLISHABLE = 'pk-'
+
+/** Strip the port and case a hostname the way a domain compares. */
+const normalize = (host: string): string =>
+  host.trim().toLowerCase().replace(/\.$/, '').split(':')[0] ?? ''
+
+/**
+ * The org that owns a host, or undefined when no brand claims it.
+ *
+ * Longest match wins, so a brand owning both a domain and a subdomain of another
+ * brand's cannot be decided by table order. Pure and total.
+ */
+export function orgOf(host: string): string | undefined {
+  const h = normalize(host)
+  if (!h) return undefined
+  let best: string | undefined
+  let bestLen = 0
+  for (const [org, domains] of Object.entries(ORG_DOMAIN)) {
+    for (const d of domains) {
+      if ((h === d || h.endsWith(`.${d}`)) && d.length > bestLen) {
+        best = org
+        bestLen = d.length
+      }
+    }
+  }
+  return best
+}
+
+/**
+ * The publishable key for a host, or undefined when there is not exactly one to
+ * give.
+ *
+ * Deliberately WITHOUT a fallback: returning Hanzo's key for an unrecognised host
+ * is precisely the defect described above. Undefined is the honest answer and the
+ * caller reports nothing.
+ *
+ * `keyring` is a parameter so the identity runtime — which receives its keyring
+ * from `/config.json` because one image serves every brand — resolves through
+ * this SAME function rather than a second copy of it.
+ */
+export function keyFor(host: string, keyring: Keyring = ORG_KEY): string | undefined {
+  const org = orgOf(host)
+  if (!org) return undefined
+  const key = keyring[org]
+  if (typeof key !== 'string') return undefined
+  const trimmed = key.trim()
+  return trimmed.startsWith(PUBLISHABLE) ? trimmed : undefined
+}
+
+/** The key for the page this code is running on; undefined off a browser. */
+export function keyForPage(keyring: Keyring = ORG_KEY): string | undefined {
+  if (typeof location === 'undefined') return undefined
+  return keyFor(location.hostname, keyring)
+}