@hanzo/event 0.3.41 → 0.3.43

package/dist/scrub.d.ts

@@ -3,6 +3,11 @@
 export declare function redactCredentialParams(s: string): string;
 /** redactSecrets removes known secret shapes. Always applied. */
 export declare function redactSecrets(s: string): string;
+/** withoutFragment returns a URL with its fragment removed. A browser never
+ *  sends the fragment to any server — it is where an app keeps what must stay
+ *  on the device, a share link's secret among them — so the client does not
+ *  send it either. */
+export declare function withoutFragment(url: string): string;
 /** scrubPII masks emails and IPs. Applied unless PII capture is enabled. */
 export declare function scrubPII(s: string): string;
 /** Longest free-text field this module will scrub. Every pattern here is a regex

package/dist/scrub.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scrub.d.ts","sourceRoot":"","sources":["../src/scrub.ts"],"names":[],"mappings":"AA8GA;6EAC6E;AAC7E,wBAAgB,sBAAsB,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAExD;AAED,iEAAiE;AACjE,wBAAgB,aAAa,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAI/C;AAED,4EAA4E;AAC5E,wBAAgB,QAAQ,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAK1C;AAED;;;;yEAIyE;AACzE,eAAO,MAAM,aAAa,OAAO,CAAA;AAEjC;4DAC4D;AAC5D,wBAAgB,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,SAAgB,GAAG,MAAM,CAE/D;AAED;qFACqF;AACrF,wBAAgB,SAAS,CAAC,CAAC,EAAE,MAAM,GAAG,SAAS,EAAE,UAAU,UAAQ,GAAG,MAAM,CAM3E"}
+{"version":3,"file":"scrub.d.ts","sourceRoot":"","sources":["../src/scrub.ts"],"names":[],"mappings":"AA8GA;6EAC6E;AAC7E,wBAAgB,sBAAsB,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAExD;AAYD,iEAAiE;AACjE,wBAAgB,aAAa,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAK/C;AAED;;;sBAGsB;AACtB,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAGnD;AAED,4EAA4E;AAC5E,wBAAgB,QAAQ,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAK1C;AAED;;;;yEAIyE;AACzE,eAAO,MAAM,aAAa,OAAO,CAAA;AAEjC;4DAC4D;AAC5D,wBAAgB,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,SAAgB,GAAG,MAAM,CAE/D;AAED;qFACqF;AACrF,wBAAgB,SAAS,CAAC,CAAC,EAAE,MAAM,GAAG,SAAS,EAAE,UAAU,UAAQ,GAAG,MAAM,CAM3E"}

package/dist/storage.d.ts

@@ -21,6 +21,12 @@ export declare function anonId(): string | undefined;
  * and the recorded `last` from disagreeing.
  */
 export declare function sessionId(now?: number): string | undefined;
+/** Make `id` the current session, as if it had begun now. The session a link
+ *  carries is the one the visitor is already in, so the journey stays one session
+ *  across the hop instead of splitting at the host boundary. */
+export declare function adoptSession(id: string, now?: number): void;
+/** Make `id` the browser's anonymous id, replacing the one it held. */
+export declare function adoptAnonId(id: string): void;
 /** Read the persisted first-touch attribution. */
 export declare function getFirstTouch(): Attribution | undefined;
 /** Persist first-touch attribution ONCE — never overwrite an existing record. */

package/dist/storage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../src/storage.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,SAAS,CAAA;AAqBlD;;;;;;;;;;;GAWG;AACH,wBAAgB,MAAM,IAAI,MAAM,GAAG,SAAS,CAE3C;AAOD;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,GAAG,SAAa,GAAG,MAAM,GAAG,SAAS,CAgB9D;AAED,kDAAkD;AAClD,wBAAgB,aAAa,IAAI,WAAW,GAAG,SAAS,CASvD;AAED,iFAAiF;AACjF,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,WAAW,GAAG,WAAW,CAM7D;AAED,wCAAwC;AACxC,wBAAgB,SAAS,IAAI,MAAM,GAAG,SAAS,CAS9C;AAED,+DAA+D;AAC/D,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAUjD"}
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../src/storage.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,SAAS,CAAA;AAqBlD;;;;;;;;;;;GAWG;AACH,wBAAgB,MAAM,IAAI,MAAM,GAAG,SAAS,CAE3C;AAOD;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,GAAG,SAAa,GAAG,MAAM,GAAG,SAAS,CAgB9D;AAED;;gEAEgE;AAChE,wBAAgB,YAAY,CAAC,EAAE,EAAE,MAAM,EAAE,GAAG,SAAa,GAAG,IAAI,CAG/D;AAED,uEAAuE;AACvE,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAE5C;AAED,kDAAkD;AAClD,wBAAgB,aAAa,IAAI,WAAW,GAAG,SAAS,CASvD;AAED,iFAAiF;AACjF,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,WAAW,GAAG,WAAW,CAM7D;AAED,wCAAwC;AACxC,wBAAgB,SAAS,IAAI,MAAM,GAAG,SAAS,CAS9C;AAED,+DAA+D;AAC/D,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAUjD"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanzo/event",
-  "version": "0.3.41",
+  "version": "0.3.43",
   "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/",
@@ -23,7 +23,7 @@
   "repository": {
     "type": "git",
     "url": "git+https://github.com/hanzoai/ui.git",
-    "directory": "pkgs/event"
+    "directory": "pkg/event"
   },
   "keywords": [
     "analytics",

package/src/anon.d.ts

@@ -12,3 +12,6 @@ export declare function hzUuidv7(now?: number): string
  * every existing id is adopted, and only a browser holding none is given a new one.
  */
 export declare function hzAnonId(): string
+
+/** Makes `id` this browser's anonymous id, replacing the one it held. */
+export declare function hzAnonAdopt(id: string): void

package/src/anon.js

@@ -214,6 +214,24 @@ function hzAnonId() {
   return id
 }
 
+/**
+ * hzAnonAdopt makes `id` this browser's anonymous id, replacing whatever it held.
+ *
+ * A visitor who followed a link from another Hanzo host arrives carrying the id that
+ * host minted; keeping the local one splits one journey into two strangers. The
+ * caller has already checked the shape.
+ */
+function hzAnonAdopt(id) {
+  hzAnonMemo = id
+  hzAnonWrite(HZ_ANON_KEY, id)
+  try {
+    var s = hzAnonStore()
+    if (s) s.setItem(HZ_ANON_KEY, id)
+  } catch (e) {
+    /* quota exhausted or a read-only jar — the cookie and memo still carry it */
+  }
+}
+
 /* ── END hz anon chain ─────────────────────────────────────────────────────── */
 
-export { hzAnonId, hzUuidv7 }
+export { hzAnonId, hzAnonAdopt, hzUuidv7 }

package/src/core.test.ts

@@ -270,6 +270,25 @@ describe('Analytics capture', () => {
       })
     })
 
+    // A share link keeps its secret in the fragment, which a browser never sends
+    // to a server. Stamped from window.location.href, it reached /v1/event on
+    // every event of the page, and a 43-character base64url secret matches no
+    // other secret shape. The fragment is dropped from every stamped location.
+    it('never sends a fragment', () => {
+      const secret = 'Zq3LwX0p-Tf9_aB7kQmN2rS8vY1cD4eF6gH5jK0lMnO'
+      withLocation('https://hanzo.ai/chat/shared#' + secret, 'https://hanzo.ai/login#' + secret, () => {
+        const a = mk()
+        a.pageview()
+        a.capture('$click')
+        a.flush()
+        for (const e of tx.all) {
+          expect(JSON.stringify(e)).not.toContain(secret)
+          expect(e.url).toBe('https://hanzo.ai/chat/shared')
+          expect(e.referrer).toBe('https://hanzo.ai/login')
+        }
+      })
+    })
+
     // A redactor that mangles ordinary URLs would destroy the analytics it
     // exists to protect, so the common case must pass through byte-for-byte.
     it('leaves an ordinary url untouched', () => {

package/src/core.ts

@@ -49,7 +49,7 @@ import { dsnForProduct } from './dsn'
 import { keyForPage } from './org'
 import { EXCEPTION, PAGEVIEW } from './events'
 import { exceptionProperties } from './exception'
-import { scrubText } from './scrub'
+import { scrubText, withoutFragment } from './scrub'
 import {
   buildEnvelope,
   buildSentryEvent,
@@ -58,6 +58,8 @@ import {
   type ErrorIdentity,
 } from './sentry'
 import {
+  adoptAnonId,
+  adoptSession,
   anonId,
   sessionId,
   getFirstTouch,
@@ -66,6 +68,7 @@ import {
   mergeCohort,
 } from './storage'
 import { uuidv7 } from './uid'
+import { linkUrl, readLink, stripLink } from './link'
 import type {
   AnalyticsConfig,
   Attribution,
@@ -349,10 +352,26 @@ export class Analytics {
     this.started = true
     if (!isBrowser()) return
 
+    // A link from another Hanzo host carries the visitor with it. Adopt it FIRST, so
+    // the first pageview is already the same person, session and first touch.
+    const linked = readLink(window.location.search)
+    if (linked.anonId) adoptAnonId(linked.anonId)
+    if (linked.sessionId) adoptSession(linked.sessionId)
+    const clean = stripLink(window.location.href)
+    if (clean !== undefined) {
+      try {
+        window.history.replaceState(window.history.state, '', clean)
+      } catch {
+        /* a sandboxed frame may refuse; the params are then simply visible */
+      }
+    }
+
     const parsed = parseAttribution(window.location.search, document.referrer)
-    this.attribution = hasAttribution(parsed)
-      ? setFirstTouchOnce(parsed)
-      : getFirstTouch() ?? parsed
+    // The first touch the link carries is the visit's real origin. Without it this
+    // host's own "first touch" would be the referring Hanzo page, which says nothing.
+    const first = linked.firstTouch && !getFirstTouch() ? setFirstTouchOnce(linked.firstTouch) : undefined
+    this.attribution =
+      first ?? (hasAttribution(parsed) ? setFirstTouchOnce(parsed) : getFirstTouch() ?? parsed)
     this.cohort = mergeCohort({
       channel: this.attribution.channel ?? deriveChannel(this.attribution),
       refCode: this.attribution.refCode,
@@ -378,6 +397,29 @@ export class Analytics {
     }
   }
 
+  /** link returns `url` carrying this visitor's anonymous id, session and first
+   *  touch when the destination is a Hanzo-owned host, so the journey continues
+   *  across the hop. Any other URL comes back unchanged. */
+  link(url: string): string {
+    if (!isBrowser()) return url
+    if (!this.started) this.init()
+    return linkUrl(
+      url,
+      { anonId: anonId(), sessionId: sessionId(), firstTouch: this.attribution },
+      window.location.hostname,
+      window.location.href,
+    )
+  }
+
+  /** authorize decorates an OAuth authorize URL for the redirect to IAM and flushes
+   *  what is queued, because the page is about to unload. Assign the result to
+   *  `location`. */
+  authorize(url: string): string {
+    const out = this.link(url)
+    this.flush(true)
+    return out
+  }
+
   /** identify binds the current visitor to a stable person id (post-login). */
   identify(personId: string, traits?: Record<string, unknown>): void {
     this.personId = personId
@@ -645,10 +687,13 @@ export class Analytics {
     // definition of "must not leave the browser", already tested, mirroring the
     // server's. Guarded on presence so an absent field stays absent instead of
     // becoming the empty string that `host` derivation reads as a page.
+    //
+    // The fragment goes first and whole: nothing after `#` is ever the server's
+    // (see withoutFragment), so it is dropped rather than scrubbed.
     const capturePII = this.cfg.capturePII ?? false
-    if (wire.url) wire.url = scrubText(wire.url, capturePII)
-    if (wire.path) wire.path = scrubText(wire.path, capturePII)
-    if (wire.referrer) wire.referrer = scrubText(wire.referrer, capturePII)
+    if (wire.url) wire.url = scrubText(withoutFragment(wire.url), capturePII)
+    if (wire.path) wire.path = scrubText(withoutFragment(wire.path), capturePII)
+    if (wire.referrer) wire.referrer = scrubText(withoutFragment(wire.referrer), capturePII)
     return wire
   }
 

package/src/events.ts

@@ -9,7 +9,7 @@
  * and there is still exactly one definition.
  *
  * Nothing about the API moved. Every existing import keeps working, the names
- * and their values are unchanged, and `pkgs/events/test/catalog.mjs` fails the
+ * and their values are unchanged, and `pkg/events/test/catalog.mjs` fails the
  * build if a name and its meaning ever disagree.
  *
  * The naming convention lives with the names, in @hanzo/events and TAXONOMY.md:

package/src/index.ts

@@ -17,6 +17,8 @@ export {
 } from './core'
 export { parseDsn, buildSentryEvent, buildEnvelope, framesFromStack } from './sentry'
 export { uuidv7, uuidv7Time } from './uid'
+export { linkUrl, readLink, stripLink, LINK_PARAMS } from './link'
+export type { LinkState } from './link'
 export { PRODUCT_PROJECT, dsnForProduct } from './dsn'
 export type { ErrorIdentity } from './sentry'
 export { scrubText, redactSecrets, scrubPII } from './scrub'

package/src/link.test.ts

@@ -0,0 +1,222 @@
+// Cross-domain continuity: a link between Hanzo hosts carries the visitor, the
+// destination adopts it before its first pageview and cleans the address bar.
+
+import { describe, it, expect, vi, afterEach } from 'vitest'
+import { linkUrl, readLink, stripLink, encodeFirstTouch } from './link'
+import { keyFor, keyForPage } from './org'
+import type { Attribution, Transport, WireEvent } from './types'
+
+const AID = '01920000-0000-7000-8000-0000000000aa'
+const SID = '01920000-0000-7000-8000-0000000000bb'
+const LOCAL = '01920000-0000-7000-8000-0000000000cc'
+const FT: Attribution = {
+  utm: { source: 'x', medium: 'cpc', campaign: 'launch' },
+  refCode: 'r1',
+  referrer: 'https://t.co/abc',
+  channel: 'paid',
+}
+
+const g = globalThis as Record<string, unknown>
+
+function browser(href: string, storage: Record<string, string> = {}) {
+  const url = new URL(href)
+  const store = new Map(Object.entries(storage))
+  const jar = new Map<string, string>()
+  const replaced: string[] = []
+  const location = {
+    href: url.href,
+    hostname: url.hostname,
+    protocol: url.protocol,
+    pathname: url.pathname,
+    search: url.search,
+  }
+  g.window = {
+    location,
+    history: {
+      state: null,
+      replaceState: (_s: unknown, _t: string, next: string) => {
+        replaced.push(next)
+        const u = new URL(next, url)
+        location.href = u.href
+        location.search = u.search
+      },
+    },
+    localStorage: {
+      getItem: (k: string) => store.get(k) ?? null,
+      setItem: (k: string, v: string) => void store.set(k, v),
+    },
+    addEventListener: () => {},
+  }
+  g.document = {
+    get cookie() {
+      return [...jar].map(([k, v]) => `${k}=${v}`).join('; ')
+    },
+    set cookie(raw: string) {
+      const kv = raw.split(';')[0]
+      const eq = kv.indexOf('=')
+      jar.set(kv.slice(0, eq).trim(), kv.slice(eq + 1))
+    },
+    referrer: 'https://hanzo.ai/',
+    visibilityState: 'visible',
+  }
+  return { store, jar, replaced, location }
+}
+
+class Tx implements Transport {
+  all: WireEvent[] = []
+  send(_u: string, body: string) {
+    try {
+      this.all.push(...(JSON.parse(body) as { batch: WireEvent[] }).batch)
+    } catch {
+      /* not JSON */
+    }
+  }
+}
+
+const load = async () => {
+  vi.resetModules()
+  return await import('./core')
+}
+
+afterEach(() => {
+  delete g.window
+  delete g.document
+})
+
+describe('linkUrl', () => {
+  const state = { anonId: AID, sessionId: SID, firstTouch: FT }
+
+  it('appends id, session and first touch for Hanzo-owned hosts', () => {
+    for (const host of ['hanzo.id', 'hanzo.app', 'hanzo.team', 'hanzo.bot', 'id.lux.network', 'zoo.ngo']) {
+      const u = new URL(linkUrl(`https://${host}/login`, state, 'hanzo.ai'))
+      expect(u.searchParams.get('hz_aid')).toBe(AID)
+      expect(u.searchParams.get('hz_sid')).toBe(SID)
+      expect(readLink(u.search).firstTouch).toEqual(FT)
+    }
+  })
+
+  it('leaves foreign hosts and same-host links alone', () => {
+    expect(linkUrl('https://example.com/x', state, 'hanzo.ai')).toBe('https://example.com/x')
+    expect(linkUrl('https://hanzo.ai/x', state, 'hanzo.ai')).toBe('https://hanzo.ai/x')
+    expect(linkUrl('mailto:z@hanzo.ai', state, 'hanzo.ai')).toBe('mailto:z@hanzo.ai')
+    expect(linkUrl('https://evilhanzo.id/x', state, 'hanzo.ai')).toBe('https://evilhanzo.id/x')
+  })
+
+  it('keeps existing query and hash, and refuses a non-UUID id', () => {
+    const out = linkUrl('https://hanzo.id/login/oauth/authorize?client_id=a&x=1#h', { anonId: 'nope' }, 'hanzo.ai')
+    expect(out).toBe('https://hanzo.id/login/oauth/authorize?client_id=a&x=1#h')
+    const ok = new URL(linkUrl('https://hanzo.id/a?client_id=a#h', state, 'hanzo.ai'))
+    expect(ok.searchParams.get('client_id')).toBe('a')
+    expect(ok.hash).toBe('#h')
+  })
+
+  it('round-trips first touch and rejects garbage', () => {
+    expect(readLink('?hz_ft=' + encodeURIComponent(encodeFirstTouch(FT))).firstTouch).toEqual(FT)
+    expect(readLink('?hz_ft=%5B1%5D&hz_aid=zzz').firstTouch).toBeUndefined()
+    expect(readLink('?hz_aid=zzz').anonId).toBeUndefined()
+  })
+
+  it('stripLink removes only its own params', () => {
+    expect(stripLink(`https://hanzo.id/a?hz_aid=${AID}&keep=1&hz_sid=${SID}#f`)).toBe('/a?keep=1#f')
+    expect(stripLink('https://hanzo.id/a?keep=1')).toBeUndefined()
+  })
+})
+
+describe('Analytics adopts a link on init', () => {
+  const href = `https://hanzo.id/login?client_id=c&hz_aid=${AID}&hz_sid=${SID}&hz_ft=${encodeURIComponent(encodeFirstTouch(FT))}`
+
+  it('first pageview carries the linked ids, first touch and a clean address bar', async () => {
+    const b = browser(href, { 'iam-anon-id': LOCAL })
+    const { Analytics } = await load()
+    const tx = new Tx()
+    const a = new Analytics({ product: 't', host: '', transport: tx })
+    a.pageview()
+    a.flush()
+    const e = tx.all[0]
+    expect(e.anonymousId).toBe(AID)
+    expect(e.sessionId).toBe(SID)
+    expect(e.channel).toBe('paid')
+    expect(e.utm?.campaign).toBe('launch')
+    expect(e.url).not.toContain('hz_aid')
+    expect(b.replaced).toEqual(['/login?client_id=c'])
+    expect(b.location.search).toBe('?client_id=c')
+    expect(b.jar.get('iam-anon-id')).toBe(AID)
+    expect(b.store.get('iam-anon-id')).toBe(AID)
+  })
+
+  it('an existing first touch is not overwritten by a link', async () => {
+    browser(href, { hz_first_touch: JSON.stringify({ utm: { source: 'old' }, channel: 'organic' }) })
+    const { Analytics } = await load()
+    const tx = new Tx()
+    const a = new Analytics({ product: 't', host: '', transport: tx })
+    a.pageview()
+    a.flush()
+    expect(tx.all[0].utm?.source).toBe('old')
+    expect(tx.all[0].anonymousId).toBe(AID)
+  })
+
+  it('a link with a bad id changes nothing but is still stripped', async () => {
+    const b = browser('https://hanzo.id/x?hz_aid=evil', { 'iam-anon-id': LOCAL })
+    const { Analytics } = await load()
+    const tx = new Tx()
+    new Analytics({ product: 't', host: '', transport: tx }).pageview()
+    expect(b.replaced).toEqual(['/x'])
+    expect(b.store.get('iam-anon-id')).toBe(LOCAL)
+  })
+})
+
+describe('Analytics.link / authorize / identify', () => {
+  it('link decorates an IAM authorize URL with the current visitor', async () => {
+    browser('https://hanzo.ai/chat?utm_source=news', { 'iam-anon-id': LOCAL })
+    const { Analytics } = await load()
+    const a = new Analytics({ product: 't', host: '', transport: new Tx() })
+    const u = new URL(a.link('https://hanzo.id/login/oauth/authorize?client_id=c&state=s'))
+    expect(u.searchParams.get('client_id')).toBe('c')
+    expect(u.searchParams.get('hz_aid')).toBe(LOCAL)
+    expect(u.searchParams.get('hz_sid')).toMatch(/^[0-9a-f-]{36}$/)
+    expect(readLink(u.search).firstTouch?.utm.source).toBe('news')
+    expect(a.link('https://example.com/x')).toBe('https://example.com/x')
+  })
+
+  it('authorize decorates and flushes what is queued before unload', async () => {
+    browser('https://hanzo.ai/chat', { 'iam-anon-id': LOCAL })
+    const { Analytics } = await load()
+    const tx = new Tx()
+    const a = new Analytics({ product: 't', host: '', transport: tx, flushIntervalMs: 999999 })
+    a.capture('chat_started')
+    const out = a.authorize('https://hanzo.id/login/oauth/authorize?client_id=c')
+    expect(out).toContain('hz_aid=' + LOCAL)
+    expect(tx.all.map((e) => e.event)).toEqual(['chat_started'])
+  })
+
+  it('identify emits the anonymous id and the person id together', async () => {
+    browser('https://hanzo.ai/', { 'iam-anon-id': LOCAL })
+    const { Analytics } = await load()
+    const tx = new Tx()
+    const a = new Analytics({ product: 't', host: '', transport: tx })
+    a.identify('person-1')
+    a.flush()
+    const e = tx.all[0]
+    expect(e.type).toBe('identify')
+    expect(e.anonymousId).toBe(LOCAL)
+    expect(e.personId).toBe('person-1')
+    expect(e.distinctId).toBe('person-1')
+  })
+})
+
+describe('one ingest key across the journey', () => {
+  it('hanzo.ai, hanzo.id, hanzo.app resolve to the same org key', () => {
+    const k = keyFor('hanzo.ai')
+    expect(k).toBeTruthy()
+    for (const h of ['www.hanzo.ai', 'hanzo.id', 'hanzo.app', 'hanzo.team', 'hanzo.bot']) expect(keyFor(h)).toBe(k)
+    const ring = { hanzo: 'pk-runtime' }
+    expect(keyFor('hanzo.id', ring)).toBe(keyFor('hanzo.ai', ring))
+  })
+
+  it('keyForPage on either host names the same project', () => {
+    browser('https://hanzo.id/login')
+    const id = keyForPage()
+    browser('https://hanzo.ai/')
+    expect(keyForPage()).toBe(id)
+  })
+})

package/src/link.ts

@@ -0,0 +1,103 @@
+// Cross-domain visitor continuity.
+//
+// Cookies and localStorage stop at the registrable domain, so a visitor who goes
+// hanzo.ai -> hanzo.id (sign-in) -> back arrived as separate people on each host, and
+// the journey across the sign-in redirect could not be read. A link between two
+// Hanzo hosts therefore carries the visitor's identity in three short query
+// parameters, and the destination adopts them before its first pageview and
+// removes them from the address bar.
+//
+//   hz_aid  anonymous id      hz_sid  session id      hz_ft  first-touch attribution
+//
+// They are appended ONLY when the destination host belongs to a brand in ORG_DOMAIN:
+// an id handed to a host outside the table would be handed to a stranger.
+
+import { orgOf } from './org'
+import type { Attribution } from './types'
+
+export const LINK_PARAMS = { anon: 'hz_aid', session: 'hz_sid', firstTouch: 'hz_ft' } as const
+
+/** Ids are v7 UUIDs; anything else in a URL is someone else's input and is refused. */
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+
+export const isId = (v: string | null | undefined): v is string => !!v && UUID.test(v)
+
+/** What a link carries. Any field may be absent. */
+export interface LinkState {
+  anonId?: string
+  sessionId?: string
+  firstTouch?: Attribution
+}
+
+/** First touch as a compact tuple: utm source, medium, campaign, term, content, refCode,
+ *  referrer, channel. Short because it rides a URL; a tuple because keys cost bytes. */
+export function encodeFirstTouch(a: Attribution): string {
+  return JSON.stringify([
+    a.utm.source, a.utm.medium, a.utm.campaign, a.utm.term, a.utm.content,
+    a.refCode, a.referrer, a.channel,
+  ].map((v) => v ?? ''))
+}
+
+export function decodeFirstTouch(raw: string | null | undefined): Attribution | undefined {
+  if (!raw || raw.length > 1024) return undefined
+  try {
+    const t: unknown = JSON.parse(raw)
+    if (!Array.isArray(t) || t.length !== 8 || t.some((v) => typeof v !== 'string')) return undefined
+    const [source, medium, campaign, term, content, refCode, referrer, channel] = t as string[]
+    const u = (v: string) => v || undefined
+    return {
+      utm: { source: u(source), medium: u(medium), campaign: u(campaign), term: u(term), content: u(content) },
+      refCode: u(refCode),
+      referrer: u(referrer),
+      channel: u(channel),
+    }
+  } catch {
+    return undefined
+  }
+}
+
+/** linkUrl returns `url` with the visitor's identity appended when its host is
+ *  Hanzo-owned and is not `fromHost`; otherwise `url` unchanged. Relative URLs
+ *  resolve against `base`. Never throws. */
+export function linkUrl(url: string, state: LinkState, fromHost: string, base?: string): string {
+  let u: URL
+  try {
+    u = new URL(url, base)
+  } catch {
+    return url
+  }
+  if (u.protocol !== 'https:' && u.protocol !== 'http:') return url
+  if (!orgOf(u.hostname) || u.hostname === fromHost) return url
+  const set = (k: string, v: string | undefined) => v && u.searchParams.set(k, v)
+  if (isId(state.anonId)) set(LINK_PARAMS.anon, state.anonId)
+  if (isId(state.sessionId)) set(LINK_PARAMS.session, state.sessionId)
+  if (state.firstTouch) set(LINK_PARAMS.firstTouch, encodeFirstTouch(state.firstTouch))
+  return u.toString()
+}
+
+/** readLink parses what a link carried out of a location.search value. Invalid
+ *  values are dropped, not repaired. */
+export function readLink(search: string): LinkState {
+  const q = new URLSearchParams(search || '')
+  const a = q.get(LINK_PARAMS.anon)
+  const s = q.get(LINK_PARAMS.session)
+  return {
+    anonId: isId(a) ? a : undefined,
+    sessionId: isId(s) ? s : undefined,
+    firstTouch: decodeFirstTouch(q.get(LINK_PARAMS.firstTouch)),
+  }
+}
+
+/** stripLink returns the path, query and hash of `href` without the link parameters, or
+ *  undefined when there were none. */
+export function stripLink(href: string): string | undefined {
+  const u = new URL(href)
+  let hit = false
+  for (const k of Object.values(LINK_PARAMS)) {
+    if (u.searchParams.has(k)) {
+      u.searchParams.delete(k)
+      hit = true
+    }
+  }
+  return hit ? u.pathname + u.search + u.hash : undefined
+}

package/src/scrub.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest'
-import { redactSecrets, scrubPII, scrubText, MAX_SCRUB_LEN } from './scrub'
+import { redactSecrets, scrubPII, scrubText, withoutFragment, MAX_SCRUB_LEN } from './scrub'
 
 describe('redactSecrets (always applied)', () => {
   it('redacts a hanzo key', () => {
@@ -121,3 +121,36 @@ describe('credential params in a URL', () => {
     expect(out).toContain('page=2')
   })
 })
+
+describe('a 256-bit base64url secret', () => {
+  const secret = 'Zq3LwX0p-Tf9_aB7kQmN2rS8vY1cD4eF6gH5jK0lMnO'
+  it('is redacted wherever it stands alone', () => {
+    expect(secret).toHaveLength(43)
+    for (const s of [secret, 'token ' + secret + ' expired', '/chat/shared/' + secret, '{"token":"' + secret + '"}']) {
+      expect(redactSecrets(s)).not.toContain(secret)
+      expect(redactSecrets(s)).toContain('[redacted]')
+    }
+  })
+  it('is redacted with no digit in it, and behind an encoded fragment mark', () => {
+    const letters = 'ZqLwXp-Tf_aBkQmNrSvYcDeFgHjKlMnOpQrStUvWxYz'
+    expect(letters).toHaveLength(43)
+    expect(redactSecrets('token=' + letters)).not.toContain(letters)
+    const returnUrl = 'https://hanzo.ai/login?next=%2Fchat%2Fshared%23' + secret
+    expect(redactSecrets(returnUrl)).not.toContain(secret)
+    expect(redactSecrets(returnUrl)).toContain('%23[redacted]')
+  })
+  it('leaves a longer or shorter run, and a word-only run, alone', () => {
+    expect(redactSecrets(secret + 'x')).toBe(secret + 'x')
+    expect(redactSecrets(secret.slice(1))).toBe(secret.slice(1))
+    const slug = 'the-quick-brown-fox-jumps-over-the-lazy-dogs'.slice(0, 43)
+    expect(slug).toHaveLength(43)
+    expect(redactSecrets(slug)).toBe(slug)
+  })
+})
+
+describe('withoutFragment', () => {
+  it('drops everything from the first #', () => {
+    expect(withoutFragment('https://hanzo.ai/chat/shared#abc#def')).toBe('https://hanzo.ai/chat/shared')
+    expect(withoutFragment('https://hanzo.ai/pricing?plan=pro')).toBe('https://hanzo.ai/pricing?plan=pro')
+  })
+})

package/src/scrub.ts

@@ -114,13 +114,33 @@ export function redactCredentialParams(s: string): string {
   return s.replace(RE_CREDENTIAL_PARAM, (_m, prefix: string) => prefix + REDACTED)
 }
 
+// A 256-bit secret written as unpadded base64url is exactly 43 characters of
+// [A-Za-z0-9_-] — the shape of a share-link secret, and of any other opaque key
+// minted the same way. The run must stand alone — nothing of the same alphabet
+// on either side, a percent-escape such as the `%23` of an encoded `#` counting
+// as a boundary — so it never fires inside a longer token, and it must mix upper
+// and lower case, which a random 32 bytes does with near certainty and an
+// ordinary word or slug does not. No lookbehind, so it runs on every engine the
+// client ships to.
+const RE_SECRET43 = /(^|[^A-Za-z0-9_-]|%[0-9A-Fa-f]{2})((?=[A-Za-z0-9_-]{0,42}[a-z])(?=[A-Za-z0-9_-]{0,42}[A-Z])[A-Za-z0-9_-]{43})(?![A-Za-z0-9_-])/g
+
 /** redactSecrets removes known secret shapes. Always applied. */
 export function redactSecrets(s: string): string {
   s = redactCredentialParams(s)
   for (const re of SECRET_PATTERNS) s = s.replace(re, REDACTED)
+  s = s.replace(RE_SECRET43, (_m, lead: string) => lead + REDACTED)
   return redactPAN(s)
 }
 
+/** withoutFragment returns a URL with its fragment removed. A browser never
+ *  sends the fragment to any server — it is where an app keeps what must stay
+ *  on the device, a share link's secret among them — so the client does not
+ *  send it either. */
+export function withoutFragment(url: string): string {
+  const at = url.indexOf('#')
+  return at < 0 ? url : url.slice(0, at)
+}
+
 /** scrubPII masks emails and IPs. Applied unless PII capture is enabled. */
 export function scrubPII(s: string): string {
   s = s.replace(RE_EMAIL, EMAIL_MARK)