eleven / messenger Public

Integrations: the registry, one-click GitHub, and self-rotating tokens (#495)

* integrations: the registry + pinned executor, with reviewed response projection

Port of the integrations prototype's stage 1 onto main (docs/integrations.md
design): an integration is DATA — one reviewed JSON manifest per service
(integrations/registry/) declaring its auth, the ONE api host its ops may
touch, and a closed op list, each read or write, writes each carrying the
confirmation line a person taps. The generic executor (integrations/exec.go)
can only do what a manifest spells: bounded args, slot-aware escaping, host
pinning on the BUILT url, on-host-only redirects, response caps.

New over the prototype: `pick` response projection in schema v1. Provider
responses are as reviewable as requests now — the manifest declares which
fields may flow back (root envelope descent + per-object field projection,
dot-paths flattened), and the executor drops everything else before a result
leaves the sidecar. This replaces the prototype's raw 8KB byte-truncation
(which handed apps broken JSON) with an honest "too large" refusal at a 32KB
cap sized to the 64KB encrypted-message blob limit, and it is what makes
GitHub usable at all (a raw repo object is ~100 fields, several KB).

- connect.op v2 in the sidecar: grants gain access read|write (empty = legacy
  = read-only), payloads gain args; any manifest op runs through the executor
  with grant-service match + write-needs-write-grant enforcement. The legacy
  DNSimple "list" path is byte-for-byte untouched.
- GET /api/integrations serves the embedded registry (public, like /api/apps).
- Manifests: GitHub (viewer, repos.list, issues.list, issue.create), DNSimple,
  Stripe, HubSpot — list ops all carry pick projections.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* web+bot: the integrations catalog + service_op consent chips

The member-facing half of the registry (port of the prototype's stages 2+3,
adapted to main's chip framework):

- The Integrations app becomes a registry-driven catalog: one card per service
  (name, category, connected state), each with a paste-a-scoped-token flow
  (sealed to the member's own key — the exact OAuth storage path), the
  manifest's create-a-scoped-token link, and a plain-language summary of what
  connecting allows ("Reads: … · Writes (always confirmed): …"). DNSimple's
  OAuth flow is preserved exactly; a registry fetch failure falls back to the
  old DNSimple-only row. New: pasting a token verifies it immediately through
  the manifest's "viewer" op when one exists ("connected as paulca ✓" / "didn't
  verify: Bad credentials"), best-effort and fail-soft when no bot is online.

- The service_op chip: whitelisted + sanitized (slug/op/access/args all
  bounded), locks on tap, seals an ACCESS-SCOPED one-shot grant
  ({service, token, exp, access}) and round-trips connect.op with args; the
  outcome lands as a private notice in the thread the chip was tapped in —
  never a data dump. sanitizeActions gains the spec.sanitize hook, and
  service_op chips allow a 160-char label so a write's consent line ("Register
  blip.com? This buys the domain and costs real money.") renders whole, never
  cut mid-warning. Legacy requestData keeps its wire bytes; requestOp is the
  scoped sibling apps use.

- The brain proposes ops: a service_op tool whose description is GENERATED
  from the embedded registry (one line per op, with access + args), and every
  proposal is re-checked against the same registry before a chip renders —
  fail at proposal, not at tap. Kept out of chipTools() so the Node-reference
  drift pin stays intact (the Node agent doesn't propose service ops).

- Broker: GET /registry serves the embedded catalog CORS-open — the future
  external-repo serving path (docs/integrations.md).

TestServiceOpEndToEnd drives the whole headline on main's own harness: Eleven
proposes the chip (label = the rendered confirm), the simulated tap seals a
write grant, the fake registrar receives exactly one authorized POST, the
connect.result lands — and the same op under a READ grant is refused with the
registrar untouched.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* web: the GitHub companion app — repos, issues, and open-an-issue

The second connected-service app (after DNSimple), and the first built on the
registry path: once GitHub is linked in Integrations (a fine-grained PAT), the
app appears in New chat and opens as its own thread — your repositories
(filterable, keyboard-navigable, private/archived/fork badges, open-issue and
star counts, last-push age), a drill-in to any repo's open issues and PRs, and
a New-issue form whose submission runs the manifest's write op under a
write-scoped one-shot grant.

No GitHub sidecar and no new bot: every fetch is ctx.host.connected.requestOp
through the instance's existing bot, and what comes back is bounded by the
github manifest's pick projection — only the reviewed fields ever ride into
the thread. Takeover app (no chatMessage), so repo and issue data never echoes
into chat bubbles, previews, or notifications. Fold state (repos + a bounded
per-repo issues map) snapshots and syncs across devices like any app.

Smoke-tested against the real GitHub API, which caught a real bug: a raw
/user/repos page (~400KB) blew the executor's 256KB read cap and surfaced as
"response isn't JSON". Projected ops now read up to 4MB — the pick throws
almost all of it away immediately — and an over-cap body refuses honestly
instead of truncating. The per-op result cap rises to 40KB (a 100-repo page
projects to ~26KB; 40KB base64s to ~54KB, inside the 64KB blob limit).

Native: glyph/title mirrored in ThreadStore (the app itself is web-only for
now, like DNSimple — the native embed can't seal grants yet).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* docs: integrations design doc + changelog for the catalog and GitHub app

docs/integrations.md describes what shipped (manifests as the palette, pick
response projection, per-bot read/write grants, the service_op chip flow, the
companion-app rail) and the external elevenmessenger/integrations repo plan —
manifest PRs validated by the same exported Parse the binary uses, secrets
staying on the broker, catalog served from the broker while execution trusts
the embedded snapshot. connected-services.md points at it and stays the
trust-model reference.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* broker+server+web: the OAuth relay goes service-generic — GitHub one click away

The golden path for connecting a service is now ordered for members: authorize
on the provider's own site whenever the broker has an OAuth app; paste a
scoped token only as the fallback. Nothing here was GitHub-specific to build —
the DNSimple relay generalises:

- Broker: one confidential client per service (oauthApp map). DNSimple keeps
  its legacy LCHAT_DNSIMPLE_* envs; any other OAuth-capable registry service
  is enabled by LCHAT_OAUTH_<ID>_CLIENT_ID/_CLIENT_SECRET, with provider
  endpoints defaulting from the manifest's auth.oauth block (schema gains
  token_url, validated https) and the redirect defaulting to the broker's own
  /oauth/<id>/callback. /config gains ?service=, the relay route becomes
  /oauth/{service}/callback, /api/exchange takes {service, code, state} — all
  three default to dnsimple so pre-multi-service instances and sidecars keep
  working byte-for-byte. The exchange now sends Accept: application/json
  (GitHub answers form-encoded without it) and reads GitHub's
  error/error_description shape alongside DNSimple's message.

- Instance: /api/oauth/config passes ?service= through to the broker with a
  per-service cache; a 404 ("no app for this service") caches as a definitive
  absent so the catalog can decide.

- Web: the catalog probes oauthReady(service) and renders "Connect with X"
  only when the flow can actually start — a service without a registered app
  offers paste-a-token alone, never a dead button. pending() now names the
  service mid-exchange so only that row shows "Connecting…". The sidecar
  exchange (handleOAuthExchange) accepts any registry service and hands the
  sealed token back under the right service name.

github.json flips auth.kind to "both": the moment the broker holds a GitHub
App's client pair, every instance's catalog offers one-click Connect — no
instance or client deploy. Tests: multi-service broker exchange (Accept
header, per-service client pair, unknown-service refusals), github callback
relay, per-service instance config pass-through.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* broker+bot+web: expiring OAuth tokens rotate themselves (GitHub Apps)

GitHub App user tokens live 8 hours with a single-use rotating refresh token —
without support, a connection silently dies the same day. Now the pair is
first-class, and the temporal-custody model from connected-services.md is
native: a stolen credential blob ages out in hours.

- Broker: POST /api/refresh (grant_type=refresh_token, same per-instance auth
  and nothing-persisted shape as the exchange); the exchange itself now
  returns the whole pair {access_token, refresh_token, expires_in} when the
  provider issues one. Non-expiring providers (DNSimple) are unchanged.
- Sidecar: the stored credential and the op grant carry
  {secret, refresh, expires_at}; the SIDECAR is the only refresher. A stale
  pair rotates before the provider call (60s slack); a surprise 401 on a
  supposedly-live token rotates once and retries once — never loops. Rotation
  is serialized per credential (refreshGroup singleflight) so two
  near-simultaneous ops share one rotation instead of the loser burning the
  single-use token, and it is REFUSED when the fresh pair couldn't be handed
  back (no resolvable member key) — a failed op beats a silently severed
  connection. integrations.Execute grows a typed StatusError so the 401
  detection isn't string-matching (message bytes unchanged).
- The fresh pair rides back ON the op result ("renewed", sealed to the
  member, never kept by the bot); the requesting device re-stores it. Web:
  completeOAuth stores the whole pair via the shared storeCredential;
  requestOp forwards refresh/expiry in the grant and re-stores a renewed
  pair best-effort.

Tests: broker refresh (rotated pair round-trip, auth refusal), sidecar
refresh-before-expired (stale token never reaches the provider; renewed pair
opens only with the member key), 401-then-retry-once (exactly one rotation,
auth sequence pinned), and refusal-without-member-key (broker and provider
both untouched).

With this, the GitHub App's "Expire user authorization tokens" setting can
stay ON — expiring tokens are now the preferred, self-healing mode.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* web: a connected service's primary action becomes "Open <service>"

Once DNSimple or GitHub is linked, the catalog row's first button opens the
service's companion app directly (created on first use, via openAppThread) —
connect once, then go straight to your domains or repos. Services without a
companion app (Stripe, HubSpot) keep Replace token / Disconnect only.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>