Universal native-app handoff hosts for sol pbc.
A single Cloudflare Worker that serves app-association surfaces for sol pbc's native apps, dispatched by request host:
go.solstone.appis the solstone universal-link surface: AASA claiming solstone,assetlinks.json,/ppairing fallback,/jjournal-link fallback, and webcredentials.link.solpbc.orgis the extro surface: AASA claiming extro only and/x/syncinstall-fallback. No solstone, no assetlinks, no webcredentials.
The solstone pair-flow QR host is now https://go.solstone.app/p#…. It moved
off link.solpbc.org before launch.
link-host adds no analytics, cookies, third-party scripts, or application request logs. Its production config turns off Workers Logs, Cloudflare's log store for this Worker (property 3 below gives its limit). Payload data rides in the URL fragment, which never enters HTTP. Open source so you can verify.
iOS Universal Links and Android App Links require an
apple-app-site-association and assetlinks.json file at the URL's host. This
Worker serves two app-association handoff hosts from one codebase:
go.solstone.appfor solstone pair-flow links.link.solpbc.orgfor extro sync links.
Today go.solstone.app is consumed by
sol private link (spl) pair-flow QR codes:
scanning a https://go.solstone.app/p#… QR can open the solstone mobile app
when it is installed. Otherwise the fallback page links to the App Store or
Play Store. After installing, the owner can open a valid pairing link.
Future sol pbc apps add their own paths to the relevant host via a small PR.
-
Operator: sol pbc (deployed at
https://go.solstone.appandhttps://link.solpbc.org). -
License: AGPL-3.0-only.
-
Not the relay. This Worker serves the two handoff hosts:
go.solstone.appfor solstone pair-flow andlink.solpbc.orgfor extro sync. They serve AASA/assetlinks + install-fallback pages, hold no keys, see no payload, and run no relay.link.solstone.appis a different service: the hosted splspl-relay(/enroll,/session,/tunnel, the JWTiss,/.well-known/jwks.json). It lives in thesplrepo, not this Worker.Rule of thumb: solstone pair QR →
go.solstone.app/p; extro sync link →link.solpbc.org/x/sync; anything that enrolls, issues a token, or carries tunnel bytes →link.solstone.app. Never cross handoff with relay. -
Status: solstone AASA carries the confirmed iOS value (
7QCG8V4M6H.app.solstone.swift, the paid Apple Developer team and app bundle). extro AASA carries7QCG8V4M6H.org.solpbc.extro. assetlinks ongo.solstone.appclaims the shipped Android phone package (app.solstone.observer.phone) with both the direct-release signing certificate and the Play App Signing certificate. The watch, glasses, and validation packages are deliberately unclaimed. File shape + headers + landing pages validate cleanly today; the iOS Universal Link handoff is wireable now.
These are structural, not policy:
- The URL fragment never enters HTTP. RFC 3986 fragments are processed client-side, so the pairing payload is absent from the request independently of any logging configuration.
- The pages set no cookies and run no analytics or third-party scripts. The pairing and journal-link scripts are served from this origin. They copy the exact fragment into an explicit app-opening link and make no requests. CSP blocks scripted connection APIs.
- Workers Logs is off.
wrangler.tomlturns it off, invocation events included, and this source emits no application logs. That setting covers this Worker's log store. It doesn't change what Cloudflare's network records when it handles a request. - Open source. This repo is public from first commit. Readers can inspect the source and compare its expected responses with the live host.
A visit still leaves edge logs. Cloudflare hosts this Worker and collects standard edge logs of each request. The fragment is never in them.
External API calls from the Worker: none.
| route | response |
|---|---|
GET /.well-known/apple-app-site-association |
solstone AASA JSON, application/json, Cache-Control: public, max-age=3600, no redirects |
GET /.well-known/assetlinks.json |
solstone assetlinks JSON, same caching posture |
GET /p |
solstone landing page (HTML, strict CSP) |
GET /p.js |
the desktop pairing page's script (text/javascript, Cache-Control: public, max-age=300) |
GET /j |
journal-link fallback page (HTML, strict CSP) |
GET /j.js |
journal-link fragment validation and explicit handoff script |
GET /j-assets/* |
vendored font and official store badges; unknown assets return 404 |
GET / |
bare host page (HTML, strict CSP, host-derived title/H1, X-Robots-Tag: noindex) |
GET /robots.txt |
disallow /p, /j and /x, allow / and /.well-known/* |
GET /x/sync |
404 |
| route | response |
|---|---|
GET /.well-known/apple-app-site-association |
extro AASA JSON, application/json, Cache-Control: public, max-age=3600, no redirects |
GET /x/sync |
extro landing page (HTML, strict CSP) |
GET / |
bare host page (HTML, strict CSP, host-derived title/H1, X-Robots-Tag: noindex) |
GET /robots.txt |
disallow /p, /j and /x, allow / and /.well-known/* |
GET /p |
404 |
GET /.well-known/assetlinks.json |
404 |
On both hosts, anything else returns 404; any POST/PUT/DELETE/PATCH
returns 405.
The AASA/assetlinks payloads, HTML pages, and robots.txt are TypeScript string
modules in src/, inlined by the Worker router. There is no static/ content.
src/
index.ts CF Worker — host-aware routes, headers, CSP
index.test.ts Worker route tests
aasa.ts two host-specific AASA payloads, solstone + extro
assetlinks.ts solstone assetlinks JSON (phone package + direct and Play certs)
landing.ts /p HTML and /p.js script — UA-aware solstone install-fallback page
journal.ts /j HTML and /j.js script — journal-link fallback
journal-assets.ts vendored font and official store badges
journal-tokens.ts shared design tokens
landing-extro.ts /x/sync HTML — extro install-fallback page
index-page.ts / HTML — bare host page
robots.ts robots.txt
wrangler.toml CF Worker config (two custom-domain routes)
package.json deps, scripts
tsconfig.json strict TS
biome.json lint + format
/j#<token> keeps the complete token in the browser. The page validates the
outer grammar: 1–512 base64url characters without padding, optionally followed
by ~ and six digits. It neither decrypts nor re-encodes the token.
An explicit button opens solstone://open#<token> on iPhone, iPad and supported
desktops. Android uses an intent: link for the phone package. The browser
fallback stays visible beneath the button; installation help expands below it.
The page cannot detect installation, app launch or journal reachability.
Both handoff scripts refresh their destination at load, hashchange,
pageshow, and activation, so a reused browser pane cannot keep a previous
link's destination. Missing or malformed journal tokens remove the destination.
# install deps
npm install
# run locally on Miniflare
npm run dev
# → http://localhost:8787/
# typecheck, lint, test
npm run typecheck
npm run lint
npm test
# full local CI shim
make ciManual wrangler deploy from an authenticated operator workstation. There is
no GH Actions deploy job, by design. This matches the
spl-relay precedent. Source of truth: this
repo's main branch. Readers can inspect the source and compare its expected
responses with the live host.
# one-time: log in to the sol pbc CF account
wrangler login
# deploy current main to the configured custom domains
wrangler deployThe Worker is bound to go.solstone.app and link.solpbc.org via two
[[routes]] blocks in wrangler.toml. DNS is auto-managed by Cloudflare; HTTPS
certs are auto-provisioned by Cloudflare.
| who | file | what they edit |
|---|---|---|
| CSO | src/assetlinks.ts |
the Android package claim and the direct-release and Play App Signing certificate fingerprints |
| CMO | src/landing.ts |
solstone landing page copy slots (H1, sub, CTAs, footer); App Store / Play Store URLs once each listing is live |
| CMO | src/landing-extro.ts |
extro fallback copy |
| CMO | src/index-page.ts |
bare host page copy |
All edits flow PR → manual deploy.
Day-1 claims are split by host: solstone on go.solstone.app, extro on
link.solpbc.org. Future products (aha, vit, etc.) add their own entries to
the relevant host's AASA payload:
- Add a new bundle + path block to
src/aasa.tsunder the relevant host payload. - Add a new target block to
src/assetlinks.tsif the host needs Android App Links. - Optional: add a new HTML route in
src/index.tsif the path needs a different fallback page (most won't). - PR + manual deploy.
After deploy, check:
- Solstone AASA shape: paste
https://go.solstone.appinto the Branch.io AASA validator and confirm the file parses. Verify the actual handoff on an iPhone with the app installed. - Extro AASA shape: paste
https://link.solpbc.organd confirm only the extro claim parses. - assetlinks shape: validate
https://go.solstone.appwith Google's Digital Asset Links tool. Then install an APK signed by the certificate being checked and inspect Android's App Links state. The installed app must also declare the matchingautoVerifyintent filter. - CSP: open
https://go.solstone.app/pandhttps://link.solpbc.org/x/syncin a browser, open devtools, and confirm no third-party network requests (network tab should show only the page itself; the mac and windows/ppage also loads/p.js).
- sol private link (spl), the first consumer
of
go.solstone.app, the pair-flow QR codes for solstone mobile. - sol pbc, public benefit corporation operating these systems.