Sense 58: The Broker

Sense 58 · Forming · Last touched 2026-08-20

• last_verified: 2026-07-27

Synced from docs/design/sense_58_the_broker.md in the engine repo — that’s the source; this page is a build-time mirror.

Status: proposed Date: 2026-07-14 Origin: a conversation about licence control for the local-local deployment mode — a customer runs the whole product on their own machine and may never open the hosted JinDesk. How do you gate who is entitled to run it, when Clerk prod is domain-locked to jinflow.io (won’t run on localhost) and Clerk dev is a playground that authorizes nothing? Companion Sense docs: Sense 25 Identity and Passes (a licence is a pass) · Sense 16 P2P2P (the local-launcher loopback this extends) · Sense 48 The Stage (prod Clerk is the single identity-of-record; dev Clerk is the playground)

Claim

jinflow.io is the broker. A local install never embeds prod identity and never carries the data off the machine — but it does one thin thing over the wire: it asks jinflow.io “who is this, and are they entitled to run?” and gets back a signed pass carrying both answers. Authentication and licensing are two questions on one handshake, brokered by the intermediary, so the data stays sovereign while entitlement stays controlled.

The two axes people keep conflating

• Authentication — who is this person? Clerk owns this.
• Entitlement — is this installation licensed to run, and for what? This is a commercial question Clerk was never meant to answer.

They are orthogonal. Forcing licensing through Clerk is what made it feel impossible (Clerk prod is domain-locked; Clerk dev is a playground). The Broker keeps them separate concerns but answers both on the same channel.

Why an intermediary at all

Clerk production instances are domain-locked: the pk_live_ key only works on jinflow.io, and the embedded SDK 4xx’s on localhost. So a local install cannot embed prod Clerk. It doesn’t have to. The hosted sign-in page lives where Clerk is allowed to run, and the local app bounces through it — the Sense 16 local-launcher loopback, extended. jinflow.io is simply the place where prod identity is legal, and therefore the natural place to also settle the licence.

Per Sense 48, prod Clerk is the single identity-of-record; dev Clerk is playground-only (and localhost is god-mode, so it authorizes nothing anyway). The Broker assumes that resolution.

The handshake

1. The local app opens the browser to the Clerk hosted sign-in on the jinflow.io domain (domain-lock satisfied — Clerk runs where it’s allowed).
2. The user signs in against prod Clerk.
3. Clerk loops back to a localhost callback with the session (the Sense 16 mechanism).
4. The app presents that session to a jinflow.io licensing endpoint (a small Worker — not Clerk) which checks jazzisnow’s entitlement records for that identity.
5. jinflow.io returns a signed pass: { subject, customer, issued_at, expires_at, entitlements } — identity and licence in one artifact.
6. The app verifies the signature against an embedded public key, caches the pass, and runs offline for a grace window. Daily work never touches the network; the app re-handshakes only when the pass nears expiry.

Control lives at the broker. You gate who receives a valid pass; you revoke by not re-issuing; you cap seats and set expiries at issuance. Data lives on the machine — jinflow.io brokers entitlement, never sees the tenant’s data. Sovereignty (Sense 16) intact.

The licence is a pass (Sense 25)

A licence is not a new primitive — it is a Sense 25 pass whose issuer is jazzisnow (signed by the platform key) rather than a tenant owner, carrying entitlements (which packs, seat count, expiry, feature tier). It maps onto the same capability tree: the pass grants capabilities the same way any pass does; it just gates the product, not a tenant’s data. This keeps one authorization model, not two.

Crypto, briefly

• jazzisnow holds a private signing key (e.g. Ed25519); the packaged app embeds only the public key.
• The pass is a small signed document; verification is offline math, not a lookup — so the grace window needs no network.
• Optional machine binding (a hardware fingerprint in the pass) narrows sharing to a seat; strictly opt-in, since it costs portability.

The air-gapped fallback

For a customer who truly never connects: the same signed pass, hand-delivered (emailed / dropped next to the app). Identical verification path, no handshake. This is the exception, not the model — the Broker’s default is the thin periodic handshake, which buys revocation and seat control the pure-offline path can’t.

Honest limits

Any check running on the customer’s machine can, in principle, be patched out. Local entitlement deters honest customers and raises the bar for casual sharing; it never stops a determined attacker. Design for honest customers plus a real legal licence — Ed25519 + expiry + a periodic handshake captures ~95% of the value; DRM beyond that is diminishing returns.

Open questions

• Grace-window length — days offline before a re-handshake is required. Tension: sovereignty/convenience vs. revocation latency.
• Revocation model — expiry-only (simple) vs. a revocation list checked at handshake (stronger, needs the endpoint).
• Seat enforcement — machine binding vs. honor + audit. How hard do we push?
• Entitlement → capability mapping — exactly how a licence’s entitlements project onto the Sense 25 capability tree (packs, feature tiers).
• The endpoint — a Cloudflare Worker on jinflow.io fronting jazzisnow’s licensing records; its schema and its relationship to cloud.yml / the deploy plane.
• Relationship to jin package Phase 4 — the packaging roadmap already lists “licence key / signed pass” auth modes; this Sense is their design home.

Non-goals

• Not a replacement for Clerk. Authentication stays Clerk; the Broker adds the entitlement axis and the local↔hosted bridge.
• Not offline-only licensing. Pure-offline is the air-gapped fallback, not the model — the default is the thin handshake.
• Not perfect DRM. See Honest limits.
• Not a data path. The Broker never carries tenant data — only identity and entitlement.

Related

• Sense 16 P2P2P — the local-launcher loopback the sign-in extends; the sovereignty conviction the Broker preserves.
• Sense 25 Identity and Passes — the pass/capability substrate a licence rides on.
• Sense 48 The Stage — prod-Clerk-as-instance-of-record (dev Clerk = playground) is the assumption the Broker builds on.
• Identity Binding — the dev↔prod Clerk decision that makes prod the single record.
• docs/operations/packaging.md — jin package Phase 4 auth modes land here.

---

Numerical neighbors: ← Sense 57: The Rooms · Sense 59: The Double Circle →