atomic-integration-proxy 0.2.0

OAuth/catalog integration proxy (pinned OpenAPI catalog, connections owned by Atomic agents, Atomic v2 request signatures, delegations and frame capabilities) used by Atomic Server and LocalThought
Documentation

integration-proxy

A Rust web server that holds OAuth grants and pasted API keys for third-party platforms, and forwards catalog-allowlisted requests to them on behalf of Atomic agents.

There are no proxy accounts, logins or tenants (issue #54). The account is the caller's Atomic agent, atomic:agent:<public key>: every request that matters is signed with that key, and the proxy verifies it against the key inside the id, so it looks nothing up. A connection (one provider grant) is owned by the agent that redeemed it; the owner delegates it to app agents, and may register runtimes (a node's app agent) for them. A plugin frame, which cannot keep a key, uses a short-lived capability signed by the owner and bound to a key the frame holds in memory.

PostgreSQL stores connections (provider credentials sealed with XChaCha20-Poly1305), delegations, runtimes, five-minute connect handoffs and the single-use record of signed requests.

Built with axum, following the OAuth 2.0 Authorization Code flow with PKCE towards providers.

How it works

Identity

Agent ids are accepted as atomic:agent:<key> or the legacy did:ad:agent:<key>, with <key> in either base64 alphabet, padded or not. They are converted to one canonical form, atomic:agent: plus the unpadded base64url key, before they are stored or compared, and only that form is ever returned. Only Ed25519 keys exist today; one function (agent_id::parse) is where another algorithm would be added.

Request signatures (Atomic v2)

Every signed request carries Atomic's own headers:

Header Value
x-atomic-agent the signer's agent id
x-atomic-public-key the signer's Ed25519 public key, base64
x-atomic-timestamp Unix milliseconds
x-atomic-signature base64 Ed25519 signature over the message below
x-atomic-signature-version 2

The signed message is five lines joined by \n, with no trailing newline:

atomic-request-v2
{METHOD}
{full URL, including query}
{timestamp, exactly as in x-atomic-timestamp}
{lowercase hex SHA-256 of the body; e3b0c442…b855 when empty}

The proxy accepts version 2 only; a missing or different version header is refused, never retried as v1. The agent must be atomic:agent: of the public key header. The timestamp must be within ±5 minutes of the proxy's clock, and each signed message is accepted once (a SHA-256 of it is kept for ten minutes).

Full URL is BASE_URL followed by the request's path and query exactly as received, e.g. https://localthought.io/proxy/<id>/github-issues/user/repos?page=2. It is never rebuilt from the Host header: behind TLS termination (Heroku) the process sees plain HTTP. Clients sign the URL they fetch (new URL(u).href). BASE_URL must therefore be exactly the public origin clients use.

Routes

  • GET / — a static landing page. GET /catalog lists the platforms; GET /catalog/{platform}.yaml returns a platform's composed OpenAPI document.
  • GET /connect?platform=<p>&redirect_uri=<url>&code_challenge=<S256>&code_challenge_method=S256 — the consent page, naming the platform and the destination. No login. redirect_uri must be https, loopback http, or the Atomic app's deep link (atomic://…); it may not carry connection_code or error parameters, credentials or a fragment.
  • POST /connect/authorize — the consent form (cookie-bound CSRF token, single use). For an OAuth platform it redirects to the provider; for an API-key platform (type: apiKey in the composed document) the consent page asks for the key, and this seals it.
  • GET /oauth/{platform}/callback — the provider's callback. Only the browser that approved consent can complete it. It redirects to redirect_uri?connection_code=<handoff> (or ?error=access_denied). The handoff is not a credential: it is single-use, valid five minutes, and bound to the PKCE challenge.
  • POST /connect/redeem — signed; body {"code": "<handoff>", "code_verifier": "<PKCE verifier>"}; answers {"connection_id", "platform", "owner"}. The signer becomes the owner. A wrong verifier does not burn the handoff.
  • ANY /proxy/{connection_id}/{platform}/{path} — signed by the owner, a delegated app agent, or a registered runtime of a delegated app; or carrying a frame capability (below). The proxy attaches the provider credential, refreshing an expiring OAuth token (one refresh in flight per connection), and forwards only catalog-allowlisted methods and paths. The caller's Authorization and x-atomic-* headers are never forwarded. Link, Retry-After, ETag, X-Total-Count and X-Next-Page come back unchanged.
  • GET /connections — signed; the signer's connections with their delegations (agent, label, created_at, last_used_at), and the signer's runtimes. Never credentials. Shape: {"owner", "connections": [{"connection_id", "platform", "owner", "created_at", "last_used_at", "delegations": [...]}], "runtimes": [{"agent", "app", "label", "created_at", "last_used_at"}]}.
  • DELETE /connections/{id} — signed by the owner; deletes the connection and its delegations. 204.
  • POST /connections/{id}/agents — signed by the owner; body {"agent", "label"?} delegates the connection to that app agent. DELETE /connections/{id}/agents/{agent} removes the delegation. 204.
  • POST /runtimes — signed; body {"app", "agent", "label"?} registers agent (a node's app agent) as a runtime of installation app for the signer. DELETE /runtimes/{agent} removes it. A runtime can use every connection its app is delegated.
  • GET /healthz — 200 ok when the database answers.

Delegations and runtimes are read on every proxied request, so removing one takes effect on the next request. A connection is deleted after 90 days without an authenticated request (CONNECTION_IDLE_DAYS).

Frame capabilities

A plugin frame (null origin, no storage) generates a non-extractable key in memory; its page, which holds the user's key, signs a capability for it:

Authorization: Capability <payload>.<sig>
payload = base64url(JSON), unpadded:
          {"v":2,"connection_id","platform","aud","app","cnf","exp"}
sig     = the connection owner's Ed25519 signature, base64, over
          "integration-proxy-capability-v2\n" + the JSON bytes

aud is the proxy origin (BASE_URL's scheme, host and port); app is the installation's app agent, which must hold a delegation; cnf is the frame's key as atomic:agent:<key>; exp is Unix seconds, at most 15 minutes ahead. The request itself must also carry v2 headers signed by cnf's key, so a copied capability is useless without the frame. The proxy checks, in order: the owner's signature, aud, exp, connection_id and platform, the delegation for app, and the request signature by cnf (with skew and replay). On 401 capability_expired the frame asks its page for a new one.

Errors

Signed endpoints answer errors as JSON, {"error": "<code>", "message": "<text>"}:

Status error
401 missing_signature, unsupported_signature_version, invalid_agent, agent_key_mismatch, stale_timestamp, bad_signature, replayed, unsupported_authorization (e.g. a retired Bearer connection code), invalid_capability, capability_expired, capability_too_long, wrong_audience, capability_key_mismatch, credential_refresh_failed (connect again)
403 not_owner, not_delegated, capability_scope, platform_mismatch, access_denied
404 unknown_connection (deleted, idle-expired, or never existed: connect again)
400 bad_request, invalid_handoff

Catalog refusals and upstream failures from /proxy/… keep their plain-text bodies (404 method or path is not in the catalog, 502 upstream request failed).

Who may use the proxy

Every signed request's connection owner (and the redeemer, at /connect/redeem) is checked against an AccessPolicy. Delegated agents and frames are checked as their owner, so limits count per owner. The default policy admits every agent except those in REVOKED_SUBJECTS, and only those in ALLOWED_AGENTS when that is set. The atomic.place deployment is meant to plug in a lookup of the agent's SaaS account and tier (build_app_with_access); how an agent is linked to an account is decided in ontola/atomic-saas#138 and is not implemented here.

What was removed (flag day)

Issue #54 decision 6 switched these off with no migration: OIDC application login (/auth/login, /auth/callback, /auth/logout, APP_AUTH_*), API identity login (/auth/login/{platform}, catalog tenantIdentity), tenant:v1: tenants, tenant secrets and SERVER_SECRET, /session, the legacy signed /connect and /oauth/{platform}/start, the /proxy tenant-secret check, the user_id and credentials parameters of /connect, and rotating connection codes (Authorization: Bearer and X-Connection-Code). Existing connection codes stop working; users connect again. The old connection_codes and oauth_states tables are no longer read or written but are not dropped automatically; once the new version is deployed, an operator may drop them with DROP TABLE IF EXISTS connection_codes, oauth_states;.

Setup

1. Configure environment variables

Nothing in the process reads .env files; export the variables, or load a .env into your shell first (set -a; source .env; set +a).

Variable Required Description
BASE_URL no Public URL of the proxy, e.g. https://localthought.io. Defaults to http://localhost:8080. Used for OAuth callback URLs, as the prefix of every signed URL, and (its origin) as a capability's aud. Must be exactly what clients use.
PORT no Port to listen on. Defaults to 8080.
SESSION_SECRET no Secret for the short-lived consent and OAuth-binding cookies. If unset, a random key is generated at startup, and a consent screen open during a restart must be started again.
CATALOG_PATH no Local path or HTTPS URL for the catalog JSON. Defaults to https://ontola.github.io/atomic-plugins/overlays/catalog.json, this repository's overlays/catalog.json as GitHub Pages publishes it from main.
DATABASE_URL yes PostgreSQL connection URL.
ENCRYPTION_KEY yes Base64url-encoded, random 32-byte key for sealed provider credentials. Changing it makes every stored connection unreadable.
REVOKED_SUBJECTS no Comma-separated agent ids (any accepted spelling) the default access policy refuses.
ALLOWED_AGENTS no When set, comma-separated agent ids; the default access policy admits only these owners.
OAUTH_<PLATFORM>_CLIENT_ID, OAUTH_<PLATFORM>_CLIENT_SECRET, OAUTH_<PLATFORM>_CLIENT_AUTH_METHOD per OAuth platform See below.

OAuth credentials are provider-specific. For a catalog platform named google-calendar, configure OAUTH_GOOGLE_CALENDAR_CLIENT_ID and OAUTH_GOOGLE_CALENDAR_CLIENT_SECRET; its callback URI is <BASE_URL>/oauth/google-calendar/callback. Provider names use lowercase letters, digits, and hyphens, and are converted to uppercase with hyphens replaced by underscores for environment-variable names.

The server owns the OAuth endpoints and scopes for every platform in the catalog, reading them from that platform's composed OpenAPI document; a request cannot supply a provider URL, token URL, or scope.

The PostgreSQL client validates the database TLS certificate. Heroku assigns DATABASE_URL automatically when its Postgres add-on is attached. Schema setup runs in a transaction under an advisory lock, so several instances can start against an empty database at once.

Catalog

Discord uses OAUTH_DISCORD_CLIENT_ID and OAUTH_DISCORD_CLIENT_SECRET, with production callback https://localthought.io/oauth/discord/callback. Register an OAuth application in the Discord Developer Portal. The initial read-only integration uses identify and guilds to read your profile and import server memberships; it does not import messages or require a bot token. The guild import requests limit=200, covering Discord's documented maximum number of guilds for a user. The profile endpoint is available as a read operation, not an imported collection. Discord access tokens expire and use the existing refresh-token flow.

Spotify uses OAUTH_SPOTIFY_CLIENT_ID and the callback https://localthought.io/oauth/spotify/callback in production. Register a Spotify Web API app with that exact redirect URI. The integration uses Authorization Code with PKCE, so no client secret is required or transmitted; set OAUTH_SPOTIFY_CLIENT_AUTH_METHOD=none so the proxy does not require or send one. It imports playlists with playlist-read-private and playlist-read-collaborative; no write scopes are requested. No account ID parameter is needed. Development-mode access is subject to Spotify's Premium and app-user allowlist requirements. Access tokens refresh automatically; expired or revoked refresh tokens require reconnecting through OAuth.

Moneybird uses OAUTH_MONEYBIRD_CLIENT_ID and OAUTH_MONEYBIRD_CLIENT_SECRET, with callback https://localthought.io/oauth/moneybird/callback in production. Register an external OAuth application, rather than a personal API token. The sales_invoices scope grants access to contacts (Moneybird has no contacts-only scope). The initial integration imports contacts; supply the administration ID from the Moneybird account when connecting. OAuth tokens without expires_in remain usable until revoked; tokens with an expiry use the normal refresh flow.

overlays/catalog.json in this repository (migrated from the former localthought/overlays repository) is the source of the integration catalog. GitHub Pages publishes overlays/ from main at https://ontola.github.io/atomic-plugins/overlays/, and the proxy defaults to the catalog.json there; set CATALOG_PATH to another HTTPS URL or to a local fixture for development. Each platform names one pinned OpenAPI document (in localthought/ or ontola/openapi-directory, at a commit) and zero or more Overlay Specification documents, each served from that same Pages folder. At startup the proxy downloads those HTTPS sources, applies each overlay's update actions in the listed order, and keeps the resulting YAML in memory.

A catalog entry may also contain a selection object. Consumer query_overrides remain separate from the composed OpenAPI document: choosing to include archived records is client configuration, not an API default. The proxy passes those choices through. selection.oauthSecurityScheme is trusted server configuration: when a document contains multiple OAuth authorization-code Security Schemes, it names the one the proxy uses. The value must be a string naming a declared scheme. GET /catalog/{platform}.selection.json returns the selection object (or an empty object when absent).

Overlay URLs are no longer pinned to a commit: whatever main has in overlays/ is what the next proxy start composes. Change the catalog in one PR: edit the overlays and overlays/catalog.json together; Overlays CI and this crate's default_catalog_* tests (which compose the checked-in catalog, reading the Pages-published overlays from ../overlays/) validate it before merge; after merge, Overlays published checks that Pages serves the merged bytes; then restart the service. OAD URLs remain pinned to an openapi-directory commit. Overlay content cannot currently be pinned: a CATALOG_PATH pointing at a local file or at a commit's raw.githubusercontent.com copy of catalog.json still lists Pages URLs, so its overlays are whatever main serves when the proxy starts.

2. Run it

cargo run

Then open http://localhost:8080 (or your configured BASE_URL).

Development

cargo fmt --all       # format
cargo clippy --all-targets --all-features -- -D warnings   # lint
cargo build            # build
cargo test             # test

CI runs the same checks on every push and pull request that touches integration-proxy/ (see the repository's .github/workflows/integration-proxy-ci.yml), plus cargo package --locked and a build of the Heroku wrapper template.

Library crate

This package is published to crates.io as atomic-integration-proxy (library atomic_integration_proxy, binary integration-proxy), so a deployment can be a thin wrapper that depends on it by semver instead of a copy of the source. The public API is intentionally small; everything else is private and may change in any release:

Item What it does
Config, Config::from_env() All configuration, read from the environment variables described above.
DEFAULT_CATALOG_PATH The pinned catalog URL used when CATALOG_PATH is unset.
build_app(&Config) -> Result<axum::Router, Error> Loads the catalog, connects to PostgreSQL, returns the router (CORS and tracing layers included), with the default EnvAccessPolicy.
build_app_with_access(&Config, Arc<dyn AccessPolicy>) The same, admitting connection owners through a custom policy (e.g. a SaaS account and tier lookup).
AccessPolicy, Access, AllowAll, EnvAccessPolicy The admission check asked about every owner; AllowAll for a self-hosted proxy.
AgentId, parse_agent_id A parsed agent id; as_str() is the canonical atomic:agent: form.
serve(Config) -> Result<(), Error> build_app, then bind 0.0.0.0:{PORT} and serve.
run() -> ExitCode What the binary does: init tracing from RUST_LOG (default info), Config::from_env, serve, print any Error to stderr.
Error Startup/serve failure; Display is the one-line message the binary prints.

A complete wrapper main.rs is:

#[tokio::main]
async fn main() -> std::process::ExitCode {
    atomic_integration_proxy::run().await
}

The only runtime file access is CATALOG_PATH when it is set to a local path; the default is a pinned HTTPS URL, and static/ is compiled into the binary, so the crate needs no files next to the executable.

Publishing the crate

.github/workflows/integration-proxy-publish.yml publishes when a tag integration-proxy-v<version> matching Cargo.toml's version is pushed. It reruns fmt, clippy and the full test suite (including the PostgreSQL tests) first, then publishes through crates.io Trusted Publishing. crates.io only allows Trusted Publishing to be configured on a crate that already exists, so 0.1.0 must be published once by hand by whoever will own the crate; the workflow header lists the one-time crates.io settings. To release:

# bump `version` in integration-proxy/Cargo.toml, merge, then on main:
cd integration-proxy && cargo publish --dry-run
git tag integration-proxy-v0.1.1 && git push origin integration-proxy-v0.1.1

Only src/, static/index.html, static/logo.png, Cargo.toml, Cargo.lock, README.md, SECURITY.md and LICENSE are packaged (cargo package --list shows the exact list). tests/ fixtures are not, so cargo test only works from a checkout of this repository.

Production deployment (localthought.io)

Production runs on Heroku from the separate repository localthought/integration-proxy, which today still carries its own full copy of this source. The target state is that it contains only the files in examples/heroku-wrapper/ and picks up proxy changes by bumping the atomic-integration-proxy version in its Cargo.lock; that directory's README has the switch-over steps.

Until that switch-over, every change merged here must be duplicated there by hand, or production will not get it. Copy the whole tree rather than cherry-picking patches — this package's src/main.rs became src/lib.rs plus a thin src/main.rs, so patches against one layout do not apply to the other:

# from the root of an ontola/atomic-plugins checkout on the merged main,
# with localthought/integration-proxy checked out at ../localthought-integration-proxy
rsync -a --delete \
  --exclude .git --exclude .github --exclude target --exclude .env \
  --exclude examples \
  integration-proxy/ ../localthought-integration-proxy/
cd ../localthought-integration-proxy
cargo fmt --all -- --check && cargo clippy --all-targets -- -D warnings && cargo test
git add -A && git commit -m "Sync from ontola/atomic-plugins@<sha>"

The synced Procfile runs target/release/integration-proxy (the binary was auth-proxy before this package became a crate), and log lines are tagged atomic_integration_proxy instead of auth_proxy, which matters only if RUST_LOG names the old target.

Deploying 0.2 (issue #54 flag day)

0.2 changes the client protocol; deploy it together with the atomic-server release that signs requests (Atomic v2) and uses /proxy/{connection_id}/…, never before it. Heroku config vars:

Variable Change
BASE_URL Check: must be exactly the public origin clients use (for production https://localthought.io, no trailing path). Every signature covers it; a mismatch makes every signed request fail with bad_signature.
APP_AUTH_CLIENT_ID, APP_AUTH_CLIENT_SECRET, APP_AUTH_AUTHORIZATION_URL, APP_AUTH_TOKEN_URL, APP_AUTH_USERINFO_URL, APP_AUTH_LABEL, APP_AUTH_IDENTITY_NAMESPACE No longer read; unset them (heroku config:unset …). 0.1 refused to start without the first five; 0.2 ignores them.
SERVER_SECRET No longer read; unset it.
REVOKED_SUBJECTS Now means agent ids; tenant ids and OIDC subjects listed there no longer match anything. Rewrite or unset it.
ALLOWED_AGENTS New, optional: restrict the proxy to these owners.
SESSION_SECRET, DATABASE_URL, ENCRYPTION_KEY, CATALOG_PATH, PORT, OAUTH_* Unchanged.

Existing connection codes stop working at deploy; users connect again. After the deploy, DROP TABLE IF EXISTS connection_codes, oauth_states; removes the old sealed credentials (optional, irreversible).

Security

Provider credentials are sealed per connection row (the associated data binds each envelope to its row) and never returned to a client. Requests go only to catalog-allowlisted methods and paths. SECURITY.md describes the controls and what is not yet verified.

Notes on state

  • Nothing identifies a browser session: there are no session cookies. The consent screen and the OAuth callback use two short-lived (10 minute) encrypted Secure/HttpOnly/SameSite=Lax cookies: platform_consent (the pending request and CSRF token) and platform_oauth (binding the callback to the approving browser). Provider state, handoffs and connections live in PostgreSQL, so any instance can serve any request.
  • Cookies are marked Secure, so in production BASE_URL must use https://. http://localhost works during local development because browsers treat localhost as a secure context.

Browser clients

CORS allows any origin, including a plugin frame's null origin, to send Authorization, Content-Type, If-Match and the five x-atomic-* headers, and exposes Content-Type, Link, Retry-After, ETag, X-Total-Count and X-Next-Page. Cookie credentials are not enabled for CORS; consent remains a top-level browser navigation.

Todoist

The todoist platform imports projects and active tasks through Todoist API v1 with the read-only data:read scope. Configure OAUTH_TODOIST_CLIENT_ID and OAUTH_TODOIST_CLIENT_SECRET, and register https://localthought.io/oauth/todoist/callback as the OAuth redirect URL. New Todoist applications issue expiring access tokens and rotating refresh tokens; the proxy stores and refreshes these through its existing credential flow. Legacy non-expiring access tokens are also supported. No provider writes are exposed.

Provider documentation: https://developer.todoist.com/api/v1/

Redirect-flow regression checks

cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test
# Isolated local PostgreSQL, never a production database:
TEST_DATABASE_URL='postgres://postgres@localhost:15439/connect_test?sslmode=disable' \
OAUTH_GITHUB_ISSUES_CLIENT_ID=fixture-client OAUTH_GITHUB_ISSUES_CLIENT_SECRET=fixture-secret \
  cargo test -- --include-ignored

CI provides PostgreSQL and includes the database tests; TESTING_COVERAGE.md maps each verification step to its tests. Live Google/GitHub authorization and a hub import must be verified against matching deployed revisions of the proxy and atomic-server; local fixture checks do not establish live access.

OAuth client registration

Integration authorization and token endpoints and required scopes are read from the composed OpenAPI catalog. A platform with one OAuth authorization-code Security Scheme uses it directly. A platform with multiple such schemes must set the catalog's trusted selection.oauthSecurityScheme; missing, non-string, or unknown selections fail closed. Requests cannot select a scheme or supply endpoints. Scopes are taken from operation security requirements (falling back to root requirements), not every scope supported by the server. Public operations require no scopes; unsupported authentication combinations fail closed.

OAUTH_<PLATFORM>_CLIENT_AUTH_METHOD optionally overrides the client authentication method: none, client_secret_post, or client_secret_basic. When omitted, the proxy selects the first usable method in the declared array order of x-oauth-authentication-details.authorizationServerMetadata.token_endpoint_auth_methods_supported in the selected OAuth security scheme. It skips methods the proxy does not implement and methods incompatible with the referenced token/refresh operations. If the array declares no usable method, configuration fails rather than silently falling back.

When that metadata is absent, the proxy retains client_secret_post for compatibility, except when a referenced token or refresh operation requires HTTP Basic authentication: it then uses client_secret_basic. Explicit overrides must still be supported by the metadata and token operations; an invalid override is an error, not a request to auto-select.

For example, Notion advertises only client_secret_basic, so its _CLIENT_AUTH_METHOD setting can be omitted. For ["private_key_jwt", "none", "client_secret_basic"], the proxy skips the unimplemented JWT method and chooses none. Array order is this proxy's default-selection policy, not an assertion of provider preference or the client's registered method. Set the override when your client registration requires a different advertised method. Public clients use none and do not load or send a secret; confidential methods require _CLIENT_SECRET. Missing credentials cause an error and do not trigger selection of another method. Authorization uses S256 PKCE unless trusted metadata explicitly declares PKCE unsupported.

The proxy implements a bounded subset of x-oauth-authentication-details. It reads inline token_endpoint_auth_methods_supported, code_challenge_methods_supported, PKCE requirements, and fixed authorization profile parameters. Parameter references must be local. Schema validation supports type, enum, recursive items, properties, required, and additionalProperties; other validation keywords fail closed. Serialization supports scalar form values, form/space/pipe-delimited scalar arrays, and form/deep-object scalar objects. Reserved OAuth fields and query-name collisions are rejected.

The proxy does not fetch oauth2MetadataUrl and does not interpret tokenEndpointOperation or refreshEndpointOperation. A selected scheme that contains any of those fields is rejected, because discovery or a separately described operation could require different token-request authentication or wire behavior.

Upgrading from 0.1 is a flag day (issue #54, decision 6): see What was removed. Provider callback URLs and OAUTH_* variables do not change; APP_AUTH_* and SERVER_SECRET are no longer read and can be unset. Clients must move to signed requests at the same time.