@hanzo/event 0.3.33 → 0.3.34

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanzo/event",
-  "version": "0.3.33",
+  "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/",
@@ -81,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

@@ -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

@@ -22,14 +22,21 @@
 
 /* ── 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_id` is a SECOND identity space a no-build tag once wrote, so one page could
- *  hold two people. 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/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)
+}

package/src/storage.test.ts

@@ -8,7 +8,7 @@
 
 import { describe, it, expect, vi } from 'vitest'
 
-const ANON = 'hz_anon_id'
+const ANON = 'iam-anon-id'
 const LEGACY = '01920000-0000-7000-8000-0000000000aa'
 const OTHER = '01920000-0000-7000-8000-0000000000bb'
 

package/src/version.ts

@@ -1,4 +1,4 @@
 // The library version, stamped on every event (`libraryVersion`) and on the
 // Sentry `sdk` block. It lives alone so `sentry.ts` can read it without importing
 // `core.ts` — core imports sentry, so the reverse would be an import cycle.
-export const VERSION = '0.3.33'
+export const VERSION = '0.3.34'