- TypeScript 90%
- HTML 5%
- CSS 3%
- JavaScript 2%
linkport #
Send a link from your phone's share sheet and have it open automatically on another device.
phone share sheet ──app──▶ your PDS ──▶ browser extension
(pick a device) (bookmark (opens links for
record) this device)
Every saved link is a permanent, portable
community.lexicon.bookmarks.bookmark
record in your repo — nothing is mutated or deleted, and the target device is
just a device:<id> tag. Devices are records too, so each browser names itself
once and the app lists them. No linkport server sees your data; the extension
reads your public repo with no auth.
Repo layout #
| Path | What it is |
|---|---|
app/ |
Expo app (iOS/Android) — share-sheet target; writes records straight to your PDS |
extension/ |
MV3 browser extension (Chrome + Firefox) — opens links tagged for this device |
worker/ |
Cloudflare Worker — serves the OAuth client-metadata documents; optional AI auto-tagging (POST /tags) |
atproto/ |
Shared atproto layer — bookmark + device collections, device-tag convention, sessions |
How it works #
- Save. The app registers as a share-sheet target. You sign in once with atproto OAuth and each share writes a bookmark record directly to your PDS, with best-effort title/description/image scraped on-device.
- Route. Each browser registers itself as an
app.linkport.devicerecord in your repo, and adevice:<rkey>tag says which one should open the link. No tag (ordevice:all) broadcasts to every device. Names are for you, not for routing — renaming a browser can't misdeliver links already in flight. - Open once. Each extension install opens only records newer than a stored watermark, then advances past everything it saw. Record keys are time-ordered, so there's no server-side read state — each install tracks its own position.
Quickstart #
Three pieces: the Worker at api.linkport.app, which serves the OAuth document
the app signs in against; the app, which saves links; and the extension
on every laptop that should open them. Only the last two are yours to set up —
the Worker is already deployed, and its URL is a constant in the source, so
there's nothing to point anything at. (Running your own copy instead? See
Self-hosting the Worker.)
1. Extension #
pnpm install
pnpm build:extension # → extension/dist/chrome and extension/dist/firefox
- Chrome / Edge / Brave:
chrome://extensions→ enable Developer mode → Load unpacked → selectextension/dist/chrome. - Firefox:
about:debugging#/runtime/this-firefox→ Load Temporary Add-on → pickextension/dist/firefox/manifest.json. (Temporary add-ons unload on close; package withweb-ext/ AMO for a persistent install.)
Then open the extension's Options, enter your handle or DID, and sign in. Signing in registers this browser in your PDS under a name it picks for itself (e.g. "Chrome on Mac"), which is what makes it appear in the app's share sheet — so there's no name to keep in sync by hand. Rename it in the same field any time; that edits the record, not a local string. Poll interval defaults to 15 min.
Opening links needs no sign-in — it reads your public records — but without one
the browser can't register, so you'd have to type a matching device name here
and in the app the old way. The flow returns to
https://api.linkport.app/ext/callback rather than a chromiumapp.org URL, which is
what lets Chrome and Firefox share one code path; the code arrives in the URL
fragment, so it never reaches the worker's server. On first run it sets a "start from now"
watermark, so only links saved after setup open. Click the toolbar button (or
restart the browser) to open pending links immediately.
2. The Worker #
Nothing to do here for a normal setup — api.linkport.app is already deployed
and every client defaults to it. This section is what it does and how to run your
own.
The Worker does two things: it serves the atproto OAuth client-metadata document,
and it generates AI topic tags on request. The first is required — that document
is the client_id, and OAuth is the only way to sign in — while tagging is
optional. It holds no atproto credentials and never writes to your repo: it
answers with tags and the app writes them itself, over its own session.
There is no shared token anywhere in linkport. To call POST /tags the app asks
your PDS for a short-lived JWT naming the Worker as its audience (atproto
service auth), and the Worker verifies that signature against the public
signing key in your DID document. Nothing secret is configured on both sides, so
there is nothing to copy between them and nothing to leak. The Worker's own
identity is did:web:api.linkport.app, which it serves at /.well-known/did.json;
both sides derive it from the client-metadata URL.
The Worker also serves a second client document at
/oauth-ext-client-metadata.json, for the browser extension, plus its redirect
target at /ext/callback. Both are derived from the client URI's origin, so
there's nothing extra to configure. They need their own client_id because an
atproto client is either native or web: the app redirects to a custom URI
scheme it registers with iOS, while an extension can't register a scheme and has
to come back to an HTTPS page — which is why that page is hosted here, on the
client_id origin. It ships no script and never renders the authorization code;
the code is useless to the Worker anyway, since the PKCE verifier and the DPoP
key stay in the extension.
Smoke test what can be checked without a signature:
curl https://api.linkport.app/.well-known/did.json
# => {"@context":[...],"id":"did:web:api.linkport.app",...}
curl -X POST https://api.linkport.app/tags -d '{"url":"https://example.com"}'
# => {"error":"unauthorized"} (correct: no service-auth token)
Tagging itself can only be exercised by a signed-in client, since the token has
to be minted by your PDS. wrangler tail logs why any call was rejected.
Confirm saved records land in your repo by viewing it at pdsls.dev.
3. The app #
Bare-workflow Expo project. The share extension is native (added by
expo-share-intent at prebuild), so it can't run in Expo Go — you need a dev
build.
First, set your own app identity. It's read from a gitignored .env so nothing
account-specific lands in the repo:
cd app
cp .env.example .env
# then edit .env:
# EXPO_PUBLIC_BUNDLE_ID your reverse-DNS bundle id, e.g. com.yourname.linkport
# APPLE_TEAM_ID Apple Developer → Membership → Team ID
npx expo run:ios --device # needs Xcode; pick your plugged-in iPhone
That's the whole .env — the OAuth identity isn't in it. Sign-in points at
api.linkport.app by default, and the native callback scheme
(app.linkport.api:) is
derived from that URL rather than typed, so there's nothing to keep in sync. The
EXPO_PUBLIC_OAUTH_* vars exist only as a fork override; see
Self-hosting the Worker.
expo prebuild generates the native ios//android/ dirs (gitignored) from
app/app.config.ts, which registers that callback scheme. The bundle id feeds both the
build entitlements and the App Group / Keychain access group the app and share
extension share, so they can't drift apart; APPLE_TEAM_ID presets the signing
team on both targets (build-only — it's never shipped in the JS bundle). With a
free Apple ID the install expires after 7 days; a paid account or
AltStore/SideStore avoids the re-sign treadmill.
In the app: sign in with your handle, then share any link → linkport → tap a device. The device list under Settings is filled in by the browsers themselves, so there's nothing to add — it's read-only apart from removing a device you no longer use. A newly registered browser shows up the next time you open the app, since the share sheet reads a local cache rather than spending a network round-trip while you're waiting on the picker. Your PDS is resolved from the handle, so there's no URL to type. The OAuth tokens and their DPoP key live in the OAuth client's MMKV store and the login pointer in the Keychain, both inside the App Group container — which is what lets the share extension write as you without its own login.
AI tags #
Saved links can get topic tags added automatically by Workers AI (free tier: 10k Neurons/day). It's entirely optional and never blocks a save.
There's nothing to configure — the app authenticates to the Worker with a token
your PDS signs on demand, and the Worker URL is the origin serving the OAuth
client-metadata document — so it's just a switch under Settings → "AI tagging",
on by default. Minting those tokens needs an rpc: grant in the OAuth scope
(Authenticate — perform actions on your behalf on the consent screen), so a
session created before that scope existed can't tag: sign out and back in once. Page previews (title/description/image/icon) are scraped on-device
either way and don't involve the Worker at all.
Tags arrive after the save, not with it. A share commits the record immediately, then queues it and asks the Worker for tags in the background — usually landing before the share sheet finishes dismissing. If iOS reaps the share-extension process first, the record stays queued and the app finishes the job on next launch. So a link is never delayed by tagging, and never loses tags permanently either.
Self-hosting the Worker #
api.linkport.app is a public deployment that stores nothing — no repo writes, no
credentials, no record of your links — so most people never need their own. If
you'd rather not depend on it, deploy the Worker yourself and point the clients
at it.
The hostname is load-bearing rather than cosmetic: it is the origin of the OAuth
client_id, and it is the Worker's did:web:<host> identity, so switching to
your own host invalidates every existing session (the granted rpc: scope names
the old audience). Sign out and back in on the app and each browser afterwards.
cd worker
# 1. Point wrangler.jsonc's `routes` at your own hostname (or drop `routes` and
# set "workers_dev": true to use the workers.dev alias).
# 2. Override the client identity. Both, together — a lone override serves a
# document whose redirect doesn't match its host.
wrangler secret put OAUTH_CLIENT_URI # https://<your-host>/oauth-client-metadata.json
wrangler secret put OAUTH_REDIRECT_URI # <reversed-host>:/auth/callback, single slash
# e.g. a.b.workers.dev -> dev.workers.b.a:/auth/callback
wrangler secret put ALLOWED_DIDS # your DID (comma-separate to allow more)
wrangler deploy
ALLOWED_DIDS is a separate question from authentication: it's who may spend
your Workers AI quota. A valid atproto identity the Worker has never heard of is
still a stranger spending your Neurons, so the list fails closed — unset means
nobody, and POST /tags answers 401 until it names at least one DID. It's the
only value a self-hosted deployment must set.
Then tell the clients: put the same client URI and redirect in app/.env as
EXPO_PUBLIC_OAUTH_CLIENT_URI / EXPO_PUBLIC_OAUTH_REDIRECT_URI and rebuild
(npx expo prebuild --clean, since the native callback scheme changes), and
either copy extension/.env.example → extension/.env or let the extension
build fall back to app/.env. The same builder
(@linkport/atproto buildClientMetadata) generates the document on the server
and the object in each client, so the two can't drift.
Local dev: copy worker/.dev.vars.example → worker/.dev.vars, then
pnpm dev:worker. wrangler tail logs why any call was rejected.
To keep the Worker but drop AI tagging server-side, remove the ai binding from
worker/wrangler.jsonc (delete the "ai": { "binding": "AI" } line) and redeploy;
/tags then answers with an empty list.
Possible future features #
- Reverse direction (laptop → phone): extension writes a record tagged for the phone; the app receives an Expo push and opens it on tap.
- Saving links from the browser extension (it can already sign in).
- Safari App Extension packaging.
License #
MIT — see LICENSE.