Repository navigation
Description
Summary
The rotating connection code is currently the only carrier of a user's sealed provider credentials. That makes a transport-level detail (single-use rotation) load-bearing for grant durability, with two consequences that are hard to live with: a connection dies after 10 idle minutes, and it cannot exist on more than one device.
This proposes a persistent, DID-bound connection record plus a signature-based auth path alongside the existing rotating-code one.
What the code does today
Verified in integration-proxy/src/{proxy,security}.rs:
StoredCredential(proxy.rs:229-246) holds the real thing:access_token,refresh_token,expires_atfor OAuth, orkeyfor API-key providers.- It is sealed into the connection code's envelope and nowhere else. On each request the proxy
take_connection_codes (an atomicDELETE … RETURNING,security.rs:255), uses the credential, then re-seals it into a freshly generated successor andstore_connection_codes that (proxy.rs:488-502). security.rs:100creates four tables —used_challenges,oauth_states,connection_codes,connection_handoffs. There is no persistent per-connection record.connection_codesrows are inserted atNOW() + INTERVAL '10 minutes'(security.rs:250) and swept on every write (security.rs:245).
The two problems that follow
1. Ten idle minutes destroys the OAuth grant. The TTL resets on each rotation, so an actively syncing client never expires — but a client idle past 10 minutes has its row swept, and the swept row was the only copy of the sealed refresh_token. Recovery is a full re-OAuth. A refresh token is a long-lived grant the user consented to; garbage-collecting it because nobody synced over lunch is a surprising place for it to end.
The same applies to any break in the chain: a dropped response spends the code client-side and rotates it server-side, and the reply carrying the successor is the only copy. The source acknowledges this for the handoff case ("Consume before dispatch: a lost response may have spent the handoff code"); for connection codes it costs the grant.
2. A connection is inherently single-device, single-tab. The credential is a single-use bearer token held in one browser's localStorage. A second device means a second OAuth flow. Two tabs on one device race, and the loser's take_connection_code returns nothing — rotation is an implicit mutex, so concurrency doesn't corrupt anything, it kills the connection.
Proposed
A. A persistent connections table. Stable connection_id, the sealed StoredCredential, the owning user_id (DID), platform, created_at, last_used_at. Not deleted on use. This is the part that decouples grant durability from transport, and it is worth doing even if B is not.
B. Signature-based auth, alongside the rotating code. The caller presents connection_id plus proof it controls the DID that owns it, instead of a bearer code. Nothing needs to be stored client-side, nothing rotates, nothing is single-use, and concurrency and idleness both stop mattering.
Three things make B smaller than it sounds:
- The proxy already records the owning DID.
StoredCredentialcarriesuser_id, e.g.did:ad:agent:test(connect.rs:1395). It knows who owns a connection; it just never authenticates with it. - The proxy already has a challenge/response path with replay protection.
verify_connectchecks a timestamped challenge and two signatures (proxy.rs:95-119), andused_challenges (nonce PRIMARY KEY, expires_at)withON CONFLICT DO NOTHING(security.rs:141) is exactly a replay-nonce table. The change is swapping the verifier from HMAC-over-tenant-secret to Ed25519-over-the-caller's-DID — a new verifier in an existing shape, not a new mechanism. - Atomic clients can already sign without exposing key material. In
ontola/atomic-serverthe agent private key is a non-extractableCryptoKeyPair(browser/data-browser/src/helpers/agentStorage.ts:209-223) andsignRequestexists (browser/lib/src/authentication.ts:38). Server-side the agent secret is available directly.
The existing tenant-secret path doesn't substitute for this: a tenant secret is tenant-wide, so it is not per-user authority and cannot be handed to a browser. The README is explicit that the browser hub "never needs to paste, receive, or store a tenant secret."
C. Short-lived scoped capabilities, for callers that cannot hold the signing key — notably atomic-server's sandboxed plugin frames, which are null-origin and have no storage. The key holder mints a capability scoped to one connection_id and platform with a short exp; the bearer presents it until it expires.
Being honest about what this is: a capability is still a bearer token, so a leaked one is usable until exp. What changes is that it is short-lived, narrowly scoped, cheap to re-mint, and not the carrier of the underlying grant — losing it costs a round trip instead of an OAuth flow. That is the property the current design lacks.
Compatibility
Additive. The rotating-code path can stay for existing clients; a connections row simply becomes the source of truth the codes are minted from.
Open questions
- Capability format and whether the proxy mints it (a session token issued on presentation of a signed request) or verifies one minted by the client. The former keeps the format private to the proxy; the latter needs no extra round trip.
- Whether the DID→public-key resolution is done by the proxy or the key is pinned into the
connectionsrow at connect time. Pinning is simpler and revocable; resolution survives key rotation. - Revocation surface.
is_revoked(tenant_id, user_id)already exists (proxy.rs:113-117); a persistent connection makes per-connection revocation meaningful too. - Whether
last_used_atplus a much longer idle TTL (weeks, not minutes) is the right lifecycle for aconnectionsrow, so dead grants still get cleaned up.
Context
Came out of #21 — where a plugin should keep a proxy credential, given a sandboxed frame with no storage. The conclusion there was that the credential shape, not its storage location, is what needs to change.
Activity
michielbdejong commentedon Sep 22, 2026
Refinement: the signer is the plugin's own agent, not the user
The DID a connection binds to should be the app's agent, not the person's identity. That agent already exists in
ontola/atomic-server:createApp()returns{ agent, secret }— "The app's own agent. Writes it makes are attributable to this DID" (browser/lib/src/plugin-app.ts:63-72).POST /app-agentand kept inPluginMeta.agent_secret, its own redb table (lib/src/db/plugin_meta.rs:12), wrapped with the node key.For this issue that changes one thing: the
user_idon aconnectionsrow is the app agent's DID. Consequences:is_revoked(tenant_id, user_id), which already exists (proxy.rs:113-117).planning/plugin-secrets.md— "Answered: scope is per plugin. Revoking one is then obviously about one plugin. The cost is pasting the same token into two importers, which is the cheaper mistake."This doesn't change the proxy work itself — it's still "verify Ed25519 against the DID pinned on the connection" — only which DID that is. It does make option B more clearly worth having than a per-user binding would.
michielbdejong commentedon Sep 22, 2026
Correction to my comment above: the app agent's secret lives in
Tree::AppAgent, keyed by(drive, app)(lib/src/db/app_agent.rs), not inPluginMeta.agent_secret— that is the server-executed sandbox plugin's agent, a different thing. The separation is deliberate, to stop a plugin spending an app's signing key as if it were an HTTP credential.Nothing else in that comment changes: the DID a connection binds to should still be the app agent's.
Two related items now have their own issues:
michielbdejong commentedon Sep 23, 2026
Adding one angle from #43 §4c, since it belongs to this work rather than to the CI follow-ups.
If connector execution moves into an iframe, single-use rotation becomes a correctness hazard. The client consumes the code before dispatch. That means no concurrency (a second overlapping call throws), no retries, and a dropped response permanently breaks the connection. That is tolerable for one serialized sync loop in one bundle, but not behind
postMessage, which gives no ordering guarantee.The direction suggested there, which fits proposal C: do not give the iframe the credential at all. Keep it in the host page and let the iframe request operations over the existing
FrameBridge.TTLs for reference, from
integration-proxy/src/security.rs: handoff 5 min, connection code 10 min, OAuth states 10 min, nonces 10 min. The connection-code TTL resets on every rotation.🤖 Generated with Claude Code
fix(integration-proxy): keep connection codes for 30 idle days, not 1…
Guard against persisting LocalThought connection codes in the graph (#21
michielbdejong commentedon Oct 1, 2026
Superseded by the consolidated design in #54 (comment of 2026-09-24) and its implementation:
DELETE /connections/{id}.#41 and #42 are closed, and #72 was closed in favour of #122. Further changes to proxy auth go on #54. Production still runs the old flow until the cutover to integrations.atomic.place (ontola/atomic-saas#149).
Generated by Claude Code