Skip to content

integration-proxy: persistent DID-bound connections, so a grant survives idleness and multiple devices #40

Closed

Description

@michielbdejong

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_at for OAuth, or key for API-key providers.
  • It is sealed into the connection code's envelope and nowhere else. On each request the proxy take_connection_codes (an atomic DELETE … RETURNING, security.rs:255), uses the credential, then re-seals it into a freshly generated successor and store_connection_codes that (proxy.rs:488-502).
  • security.rs:100 creates four tables — used_challenges, oauth_states, connection_codes, connection_handoffs. There is no persistent per-connection record.
  • connection_codes rows are inserted at NOW() + 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. StoredCredential carries user_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_connect checks a timestamped challenge and two signatures (proxy.rs:95-119), and used_challenges (nonce PRIMARY KEY, expires_at) with ON 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-server the agent private key is a non-extractable CryptoKeyPair (browser/data-browser/src/helpers/agentStorage.ts:209-223) and signRequest exists (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 connections row 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_at plus a much longer idle TTL (weeks, not minutes) is the right lifecycle for a connections row, 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

  1. michielbdejong commented on Sep 22, 2026

    @michielbdejong
    ContributorAuthor

    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).
    • Its public half is already synced drive data, in an App identities folder kept outside every app's own subtree, because "a key stored in the room it unlocks" would be replaceable by the app. That folder's description already names it the revocation surface: "Removing one from a resource's rights revokes that app."
    • Its secret is never in the graph — handed to the node once via POST /app-agent and kept in PluginMeta.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_id on a connections row is the app agent's DID. Consequences:

    • Per-plugin revocation becomes meaningful and matches is_revoked(tenant_id, user_id), which already exists (proxy.rs:113-117).
    • Per-plugin attribution — traffic arrives as the plugin, not as the person.
    • A compromised plugin cannot act as the user anywhere else on the proxy.
    • One OAuth flow per plugin per platform. That cost is already an accepted trade upstream: 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.

  2. michielbdejong commented on Sep 22, 2026

    @michielbdejong
    ContributorAuthor

    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 in PluginMeta.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:

    • #41 — whether an app agent is usable on a second node at all.
    • #42 — item A of this issue, split out: a refresh token is destroyed after ten idle minutes, which is worth fixing independently of the signature-auth work here.
  3. michielbdejong commented on Sep 23, 2026

    @michielbdejong
    ContributorAuthor

    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

  4. michielbdejong commented on Oct 1, 2026

    @michielbdejong
    ContributorAuthor

    Superseded by the consolidated design in #54 (comment of 2026-09-24) and its implementation:

    #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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions