Skip to content

Merge integration-proxy into atomic-server behind a Cargo feature (one instance acts as the proxy) #1650

Open

Description

@michielbdejong

Proposal

Merge the integration-proxy executable into atomic-server, behind a Cargo feature. It is currently a standalone axum and Postgres service on Heroku at localthought.io.

Architecture: one atomic-server instance acts as the integration proxy, usually atomic.place, e.g. at integrations.atomic.place.

  • It holds the OAuth apps and their fixed callback URLs.
  • It stores the connections' tokens.
  • It serves the /proxy endpoint that plugins call.
  • Other atomic-servers (self-hosted, localhost, desktop, other managed nodes) keep using a proxy URL, as they do today. They don't run the proxy themselves.

What merging gives us:

  • Login: the proxy uses atomic-server's own agent authentication, instead of a separate OIDC login configured through APP_AUTH_*.
  • UI: adding and revoking connections lives in the data-browser of that instance, instead of in the proxy's own HTML pages.
  • One codebase for the server and the proxy. A self-hoster can turn the flag on to run their own proxy instance.

How clients authenticate and what a tenant is (the tenant secret today and in future) stays in atomic-plugins#54. This issue is only about the merge.

Layout

  1. A separate workspace crate, e.g. integration-proxy/, not a module in server/.
    • It keeps its "no platform-specific logic in src/" rule and its tests.
    • Downstream wrappers (atomic-saas's atomic-managed-node) can depend on it and plug in policy, e.g. throttling, through a ProxyPolicy hook (see atomic-plugins#78).
  2. An optional dependency of server, behind a feature:
    [features]
    integration-proxy = ["dep:atomic-integration-proxy"]
    Whether it's in default is open. It adds little build weight, since tokio, reqwest and chacha20poly1305 are already in the tree.
  3. Off at runtime unless configured, as with --enable-vector-index. The routes are mounted only on the instance configured to be the proxy, i.e. one with OAUTH_<PLATFORM>_* credentials.

Required refactors

  • Web framework. The proxy uses axum and this server uses actix-web. Either port the handlers to actix, or split the crate into a framework-independent core plus an actix adapter. Port rather than split if nothing needs the standalone axum binary afterwards.
  • Storage. Move the proxy's Postgres tables onto this server's embedded store, so the feature brings no Postgres requirement.
  • Login. Replace the proxy's OIDC login and cookie session with atomic-server's agent authentication. The exact mechanism follows from Remove store ref from resource, add table view #54.

Other points

  • Security bar. The proxy's controls (catalog allowlist, no redirect-following, bounded response bodies, sealed tokens) and their tests must come along unchanged.
  • History. This server previously had /integration-proxy/* relay handlers (with TENANT_SECRET and ATOMIC_INTEGRATION_PROXY_URL), which were removed. Those only relayed calls to the remote proxy; this proposal embeds the proxy itself. Worth checking why they were removed.
  • Migration from localthought.io. Every platform's OAuth app needs the new callback URL registered, and existing connections live in the Heroku Postgres. Run both side by side during the switch.

Order

  1. Move the crate here. Port or split it for actix, and move its storage onto the embedded store.
  2. Feature flag and runtime switch.
  3. Replace the login with agent authentication, per Remove store ref from resource, add table view #54.
  4. Data-browser UI to add and revoke connections, per the use case in atomic-plugins#54.
  5. atomic.place runs it inside atomic-managed-node at integrations.atomic.place.

Related: ontola/atomic-saas#125 (the product surface), #1624 (scoped capability for plugin frames).

Activity

  1. changed the title [-]Embed integration-proxy in atomic-server as a workspace crate behind a Cargo feature[/-] [+]Merge integration-proxy into atomic-server behind a Cargo feature (one instance acts as the proxy)[/+] on Sep 23, 2026
  2. michielbdejong commented on Sep 23, 2026

    @michielbdejong
    ContributorAuthor

    Rewrote the description after discussion. The architecture is one atomic-server instance (usually atomic.place) acting as the integration proxy. It is not embedded on every node, and there is no remote fallback. Auth and tenant-secret design stays in ontola/atomic-plugins#54.

  3. michielbdejong commented on Sep 23, 2026

    @michielbdejong
    ContributorAuthor

    Hostname decision: the UI and the endpoints live on separate origins, both served by the same atomic-server instance.

    • UI (add and revoke connections) lives in the data-browser at app.atomic.place. It calls the proxy cross-origin, signing requests with the agent. The proxy's CORS already allows any origin without credentials, so same-origin buys nothing for login.
    • Endpoints live at integrations.atomic.place: consent, OAuth callbacks, /proxy/*, catalog. Reasons:
      • Origin isolation. /proxy/* returns responses from third-party APIs. Serving them from the app origin, where the agent secret lives in browser storage, would turn any content-type slip or upstream issue into a way to steal that key.
      • Stable callback URLs. The ones registered with every platform stay put if the app or the node hosting the proxy moves.
      • No path collisions with the app's SPA routes.
    • Note that app.atomic.place is served by the control plane, not by an atomic-server. Caddy routes integrations.atomic.place to the designated atomic-server instance, and Terraform needs an explicit DNS record, because the wildcard record would otherwise resolve it to production by accident.
    • Either way, proxied responses should send X-Content-Type-Options: nosniff, as defence in depth.
  4. michielbdejong commented on Sep 24, 2026

    @michielbdejong
    ContributorAuthor

    Direction change (2026-09-24): keep the proxy a separate crate and service; don't merge it into atomic-server

    Michiel has agreed to revisit this. What this issue wanted from merging, and where each benefit stands now:

    Benefit of merging Status without merging
    Login with agent authentication instead of the proxy's OIDC login (APP_AUTH_*) Already done in the standalone proxy. integration-proxy 0.2 (ontola/atomic-plugins#122) removed the tenant concept and OIDC. Connections are owned by atomic:agent ids, every request carries an Atomic v2 signature (#1696), and there are delegations, runtimes and DELETE /connections/{id}.
    Connection UI in the data browser instead of the proxy's HTML pages Works cross-origin. In #1697 the page signs connect, redeem, delegation and revoke calls, and plugin frames call the proxy directly with capabilities. This issue already put the endpoints on their own origin (integrations.atomic.place) for security, so sharing a process adds nothing.
    One codebase, so self-hosters flip a flag Self-hosters run the atomic-integration-proxy crate's binary, or embed the crate in their own wrapper. Decision 12 on atomic-plugins#54 says even an embedded proxy is reached over loopback HTTP, never in-process.
    No Postgres Still true that the proxy needs Postgres. That is the one real cost of keeping it separate.

    What merging would still cost:

    • porting axum to actix, or splitting the crate;
    • moving the security-critical storage (sealed tokens, the single-use request record, refresh locks) from Postgres to the embedded store;
    • tying proxy releases to atomic-server's review and merge cadence;
    • and running the process that holds every user's provider tokens inside a general-purpose server, which widens the damage if anything goes wrong.

    New plan:

    • The proxy stays the atomic-integration-proxy crate in ontola/atomic-plugins.
    • atomic.place runs it as its own small service next to the control plane on Hetzner, at integrations.atomic.place, through a thin wrapper in atomic-saas. It's the same pattern as the current Heroku wrapper (localthought/integration-proxy).
    • The SaaS account and plan check plugs in through the crate's AccessPolicy trait.
    • Remove store ref from resource, add table view #54 decision 6 (flag day, users connect again) means there is no data migration from the Heroku Postgres. The two deployments just run side by side until clients switch.

    I suggest closing this issue as "won't do for now", and reopening it if running a second process ever becomes a real burden.

    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

    enhancementNew feature or requestpluginShould probably be an Atomic Pluginserveratomic-server

    Type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions