atomic-integration-proxy 0.4.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 and tokens for third-party platforms, and forwards catalog-allowlisted requests to them on behalf of Atomic agents.

Connections retain Atomic agent ownership (issue #54); the proxy has no standalone owner-account login. The owner is the caller's Atomic agent, atomic:agent:<public key>. Signed clients use that key and the proxy verifies it against the key inside the id. Opt-in device clients obtain a scoped bearer session approved by that same owner; see DEVICE_AUTH.md for the contract, browser integration and runnable examples. This source change does not claim deployment to localthought.io.

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.

To run your own instance, see SELF_HOSTING.md: installing (cargo install, Docker, systemd), configuration, PostgreSQL TLS, a reverse proxy, registering OAuth apps, pointing Atomic Server and the data browser at it, upgrades, backups and health checks. This README describes the protocol and the code.

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 a TLS-terminating reverse proxy or platform router 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

With WEBHOOKS_ENABLED=true only (Webhook Deliveries and Webhook Subscriptions, openapi-extensions/spec/):

  • POST /webhooks/{endpointId}: a provider's delivery. The body is capped while it is read, and verified over its exact bytes before anything in it is read. 204 only after it was stored (or recorded as a gap, or wanted by nobody); 401 unverified, 413 over the cap, 503 not stored.

  • POST /connections/{id}/subscriptions {source, parameters, events}, GET and DELETE /subscriptions/{id}, POST /subscriptions/{id}/renew, GET /subscriptions/{id}/events?after=&limit=&wait= (long poll up to 25 seconds), POST /subscriptions/{id}/ack {generation, cursor}, POST /subscriptions/{id}/reconciled {generation, barrier}: signed by the subscription's consumer (the connection's owner, a delegate or a runtime), checked on every request. Subscribing runs the source's access check through the connection, and so do renewals, reconciliations and any fetch whose last passing check is older than 12 hours.

  • 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 answers 200 with a page that continues to the provider (a <meta> refresh plus a button, sent with Referrer-Policy: no-referrer) rather than redirecting: the consent page's CSP form-action governs a form submission's whole redirect chain, and a provider whose authorization endpoint first redirects to another origin of its own (Notion's API host to its app host, for one) would be blocked. The consent page therefore allows form submissions to the proxy only. 0.2.2 and later; 0.2.1 redirected (303). For an API-key platform (type: apiKey in the composed document) the consent page asks for the key, and this seals it and redirects (303) to redirect_uri. When the scheme declares x-api-key-details (openapi-extensions/spec/api-key-details, 0.2.3 and later), the page shows the scheme's description and links its helpUrl (a plain link that opens in a new tab), and this first calls the declared keyCheck operation once with the key: a fixed GET on the document's own https server, no redirects, 10-second timeout. A 401 or 403 answers the consent page again (200) saying the key was not accepted, without spending the consent; any other non-2xx, a redirect or no answer is a 400 and nothing is stored. One consent page makes at most 5 key checks (unreleased): the fifth rejection spends it and answers 400 "Too many attempts to enter a key for this connection; start again from your hub", and nothing is checked for it after that. This bounds one consent page, not a client: anyone can open a new one. Across consent pages, one client network makes at most KEY_CHECK_LIMIT_PER_HOUR (default 20) key checks per platform in any hour (unreleased); over that, the answer is 429 "Too many key checks from your network for ; try again later" with Retry-After, before any key check and without spending the consent (SECURITY.md). A 2xx may give a label (at most 200 characters, sealed with the connection). A platform whose scheme is type: http with scheme: bearer or scheme: basic (unreleased; see "HTTP tokens" below) works the same way: the page asks for an API token (and, for some Basic layouts, a username), the key check is sent the Authorization header a proxied request would carry, and a rejected token is asked for again with "did not accept that API token". For a platform whose composed document declares top-level security: [] and no security scheme (0.2.3 and later), the consent page asks for nothing, and this hands off a connection that holds no credential and redirects (303) to redirect_uri; requests are forwarded with none. Approving the same consent page twice answers 400 "You already approved this connection …" rather than "expired"; the page's one inline script (allowed by its hash) disables the button after the first click.

  • 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", "label"?}. The signer becomes the owner. label is there when an API-key platform's key check gave one. 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), or an opt-in Local Thought device access token for approved GET/HEAD reads (DEVICE_AUTH.md). 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: an Authorization must be a capability or a namespaced Local Thought device access token; retired bearer connection codes remain refused. Both presentations are consumed by the proxy. Of the caller's headers only Content-Type, If-Match, If-None-Match and If-Modified-Since go upstream, plus Idempotency-Key where the operation declares an Idempotency-Key header parameter (and the catalog sets no fixed value for it). From the provider's response, Content-Type, Link, Retry-After, ETag, Last-Modified, X-Total-Count, X-Next-Page and the rate-limit headers X-RateLimit-Limit, -Remaining, -Used, -Reset, -Resource, RateLimit, RateLimit-Policy, RateLimit-Limit, -Remaining and -Reset come back unchanged, by exact name; every other response header is dropped, and every /proxy/… response carries Cache-Control: no-store. On a no-credential connection the Idempotency-Key goes upstream namespaced per connection (an HMAC of the connection id and the key; SECURITY.md), so tenants never share keys. A value the catalog fixes for one of these request headers replaces the caller's.

  • 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", "label"?, "created_at", "last_used_at", "delegations": [...]}], "runtimes": [{"agent", "app", "label", "created_at", "last_used_at"}]}. A connection's label is the key check's label (see /connect/authorize), absent otherwise. A device bearer session instead returns only its approved connections and canonical owner/client/session identity (DEVICE_AUTH.md).

  • 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
429 provider_quota, from /proxy/… only, with Retry-After in seconds: the proxy's own requests to the platform are at a quota the provider counts on the proxy's address (x-throttling; see "Pacing under provider quotas")

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; set it in production Secret for the short-lived consent and OAuth-binding cookies. If unset, a random key is generated at startup (with a warning in the log), and a consent screen open during a restart must be started again. Instances behind one name must share it.
CATALOG_PATH no Local path or HTTPS URL for the catalog JSON. Defaults to https://ontola.github.io/atomic-plugins/overlays/catalog/2026-10-02-auth-profiles.json, this repository's overlays/catalog/2026-10-02-auth-profiles.json as GitHub Pages publishes it from main (0.2.4 defaults to catalog/2026-10-02.json).
DATABASE_URL yes PostgreSQL connection URL. See the TLS note below.
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.
OPERATOR_NAME no Who runs this proxy, as the landing and consent pages name them. Defaults to this integration proxy, and the pages then name no one. The consent page also shows the host of BASE_URL. 0.2.1 and later.
OPERATOR_URL no Absolute http(s) link for OPERATOR_NAME on those pages. Anything else (javascript:, a relative path, credentials in the URL) is refused at startup. 0.2.1 and later.
KEY_CHECK_LIMIT_PER_HOUR no The most API key or token checks the consent form makes for one client network and platform in any hour (a sliding window, counted in PostgreSQL across instances). Defaults to 20; 0 turns the limit off; more than 10000 stops the proxy at startup. Only platforms with a declared key check count. A client over it gets 429 and no key check. A network is an IPv4 address or an IPv6 /64. Unreleased.
WEBHOOKS_ENABLED no true creates the webhook inbox's tables, runs its sweeper and mounts the webhook routes below (ontola/atomic-plugins#369; see SECURITY.md). Unset, empty or false (the default): no inbox table, no sweeper, no webhook route. Any other value stops the proxy at startup. Unreleased.
WEBHOOK_INGRESS_LIMIT_PER_NETWORK no Refusals (unknown or malformed endpoint id, failed verification, oversized body; not 400 or 408) one client network (an IPv4 address or IPv6 /64, found as TRUST_FORWARDED_FOR says, which behind Heroku's router or another proxy must be set) may cause on POST /webhooks/… per minute. Over it, its requests for ids that name no endpoint get 429 with Retry-After, and at most 2 of its requests at a time may wait for the endpoint-lookup slot: while the slot is busy and 2 wait, any further request from such a network gets 429 at once, a delivery to an existing endpoint included (a provider that shares its delivery addresses with the junk sent to it can lose one that way; see SECURITY.md). Default 120; 1 to 100000. Per instance. Read only with WEBHOOKS_ENABLED=true. Unreleased.
WEBHOOK_INGRESS_LIMIT_PER_ENDPOINT no Failed verifications one existing webhook endpoint counts per minute; over it, further ones get 429 instead of 401. A delivery that verifies is never refused for it. Default 600; 1 to 100000. Per instance. Read only with WEBHOOKS_ENABLED=true. Unreleased.
WEBHOOK_SUBSCRIBE_LIMIT_PER_OWNER no Subscription requests per connection owner per hour, counted before the access check reaches the provider; every request counts, retries included. Default 20; 1 to 100000. Per instance. Read only with WEBHOOKS_ENABLED=true. Unreleased.
WEBHOOK_SECRET_<PLATFORM> with webhooks, per platform The secret of a platform's shared application hook, as configured at the provider (<PLATFORM> is the catalog name, upper case, - as _). Read only with WEBHOOKS_ENABLED=true, for platforms whose composed document declares x-webhook-deliveries. Without it, every delivery to that platform is refused and no subscription to it is created. Unreleased.
WEBHOOK_INBOX_MAX_BYTES no The deployment's inbox budget in bytes, payloads plus a stated per-row overhead. Defaults to 1073741824 (1 GiB); at least 268435456 (the per-owner budget). Read only with WEBHOOKS_ENABLED=true: with the inbox off it is ignored, even when invalid. Unreleased.
TRUST_FORWARDED_FOR no; heroku on Heroku Where the key-check limit and the webhook per-network limit (WEBHOOK_INGRESS_LIMIT_PER_NETWORK) find the client address: none (default) uses the TCP peer and ignores X-Forwarded-For; heroku (synonym rightmost) uses only the right-most X-Forwarded-For entry, which Heroku's router (or one reverse proxy in front) appends, and never an entry to its left; when that entry is missing or not an address, one shared bucket. Set heroku only behind such a proxy: without one, a client writes that entry itself. Unreleased.
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's TLS certificate against the system roots when TLS is used; sslmode in DATABASE_URL decides whether it is (prefer by default, which falls back to plaintext against a server without TLS). Use ?sslmode=disable for a PostgreSQL on the same host and ?sslmode=require across any network; see SELF_HOSTING.md. A managed PostgreSQL may set DATABASE_URL for you (Heroku's Postgres add-on does). Schema setup runs in a transaction under an advisory lock, so several instances can start against an empty database at once.

Catalog

Per-platform OAuth app registration for any deployment is in SELF_HOSTING.md. Every callback is <BASE_URL>/oauth/<platform>/callback; the examples below use the localthought.io deployment's BASE_URL.

Discord uses OAUTH_DISCORD_CLIENT_ID and OAUTH_DISCORD_CLIENT_SECRET, with callback https://localthought.io/oauth/discord/callback on localthought.io. Register an OAuth application in the Discord Developer Portal. The catalog composes Discord's full OAD, which declares a bot token and OAuth together, and selects its discordUser authentication profile (see "Authentication profiles" below): the read-only integration uses identify and guilds to read your profile and import server memberships, and every other Discord operation, including all bot-token operations, is refused. It does not import messages or require a bot token. This is declared from Discord's documentation and composition tests; no live Discord connection has been verified with the profile. 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 <BASE_URL>/oauth/spotify/callback (on localthought.io, https://localthought.io/oauth/spotify/callback). 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; the catalog declares only none, so the proxy neither requires nor sends one (OAUTH_SPOTIFY_CLIENT_AUTH_METHOD=none is equivalent). 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 <BASE_URL>/oauth/moneybird/callback. 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/2026-10-02-auth-profiles.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/2026-10-02-auth-profiles.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.

Provider overlay filenames include their kind and full OAD commit SHA under overlays/APIs/, so adding a newer OAD revision leaves existing catalog selections intact. Each overlay's extends identifies that same pinned OAD. The loader rejects a mismatched declaration before applying actions, resolves relative extends against the overlay URL, and continues to support older overlays that omit it. Published revision files are immutable; updating a platform means explicitly changing its openapi and ordered overlays selections together.

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. selection.authenticationProfile is trusted server configuration too: it names one of the document's components.x-authentication-profiles (see "Authentication profiles" below), and excludes oauthSecurityScheme, apiKeySecurityScheme and httpSecurityScheme. selection.apiKeySecurityScheme and selection.httpSecurityScheme do the same as oauthSecurityScheme for a document with several apiKey schemes, or several bearer/basic http schemes. GET /catalog/{platform}.selection.json returns the selection object (or an empty object when absent).

A composed document whose paths holds a path item that is a $ref (OpenAPI 3.1) or not an object is refused at load, naming the platform and path: the proxy does not resolve $ref path items, and no catalog uses one.

Produced classes (x-produces, openapi-extensions/spec/produced-classes, docs/design/pieces.md D4): the shared classes a CRUD resource's objects can be represented as. An overlay sets it on a CRUD Resource Object, and it comes back unchanged in /catalog/{platform}.yaml. It has no place in a catalog entry's selection. The proxy never reads it: nothing it allows, forwards or asks consent for depends on it.

Authentication profiles

A document that declares more than one kind of security scheme (OAuth and an API key, say) is refused unless the catalog entry selects an authentication profile (x-authentication-profiles, 0.1.0-draft). A profile names one security scheme. With selection.authenticationProfile set, the proxy:

  • connects with that scheme only: oauth2 with an authorization-code flow, apiKey, or a bearer or basic http scheme (the last two with their x-api-key-details help link and key check, as for any API-key or token platform);
  • asks for the scopes of the operations the profile covers, and of no other: an operation is covered when its effective security has a requirement whose only member is the profile's scheme;
  • answers 404 method or path is not in the catalog for every operation the profile does not cover, without sending any credential upstream, including operations that accept only anonymous access, only another scheme, or the scheme only combined with another;
  • refuses an unknown profile, an undeclared or unsupported scheme, a profile that covers no operation, or a selection that also names a scheme, instead of falling back to anything else;
  • sends a stored OAuth token only while the platform still resolves to an OAuth scheme, so a selection moved to an API-key profile does not send a user's token to that profile's operations (the person connects again). A stored bearer or basic token is likewise sent only while the platform resolves to an http scheme of the same kind.

Declaring profiles in a document changes nothing until a catalog selects one. The served document (GET /catalog/{platform}.yaml) is the whole composed document; a client reads which operations its connection reaches from their security. Without a profile selection the proxy behaves as before.

HTTP tokens (bearer and basic)

Unreleased (Decision Inbox Q-086). A security scheme of type: http with scheme: bearer or scheme: basic (case-insensitive) is a user credential, like an apiKey scheme: a personal access token pasted on the consent page.

  • Which documents. Without an authentication profile, an http scheme counts only when the document declares no oauth2 and no apiKey scheme. A document that has one of those resolves exactly as before, whatever http schemes it also declares (OAuth documents often declare http basic for client authentication at their token endpoint). With several bearer/basic schemes, selection.httpSecurityScheme names one. A profile may name a bearer or basic scheme of any document. Other http schemes (digest, ...) are not supported.
  • Bearer. The page asks for one token. After trimming it must be 4 to 512 bytes of RFC 6750 b64token ([A-Za-z0-9-._~+/]+=*), where : is also allowed before the padding, for Asana-style personal access tokens (2/<id>/<id>:<secret>, as Asana documents them; not checked with a live token). Requests carry Authorization: Bearer <token>.
  • Basic. The scheme must declare how the token fills the credential, as x-api-key-details.basicCredentials (api-key-details 0.2.0-draft, section 4.3); a basic scheme without it is not offered ("This platform is not available for connection"). The three layouts: {token: username, password: <fixed, may be empty>} (one field), {token: password, username: <fixed>} (one field), and {token: password, usernameLabel: <label>} (a text field with that label for the username, then the token field). There is no layout in which the person types a password other than the token. The token must be 4 to 512 bytes without control characters; as a username it may not contain :. A typed username must be 1 to 256 characters without control characters or :. Requests carry Authorization: Basic base64(username:password).
  • Key check, help and sealing. x-api-key-details helpUrl and keyCheck work as for an API key; the check is sent the same Authorization header the proxied requests will carry. The connection seals the token (and, for Basic, both halves as they were checked) in the same per-row envelope as an API key or OAuth token, and the handoff, redeem and listing never return them.
  • Requests. The proxy sends a stored bearer or basic credential only while the platform still resolves to an http scheme of that same kind and, for credentials stored by the unreleased version, with the same scheme name and (Basic) the same declared layout (its fixed halves and which half is the token; not the username field's label). API keys stored by it are bound to their scheme name and to the scheme's in and name (header names case-insensitive) the same way. Otherwise it answers 401 credential_refresh_failed (connect again). Credentials stored before carry no binding and are sent as before. The caller's own Authorization is never forwarded (above).

Overlay URLs use immutable OAD-revision filenames. Publish new overlay filenames and a new dated catalog together, then explicitly switch CATALOG_PATH or the proxy default to that dated catalog; 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). For a deployment, see SELF_HOSTING.md; GET /healthz is the health check.

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, recording each request's peer address (into_make_service_with_connect_info::<SocketAddr>()) for the key-check limit. A caller that serves build_app's router itself should do the same; without it, and without a trusted X-Forwarded-For, all clients share one limit.
TrustForwardedFor, DEFAULT_KEY_CHECK_LIMIT_PER_HOUR Config::trust_forwarded_for and the default of Config::key_check_limit_per_hour. Unreleased.
WebhookConfig, DEFAULT_WEBHOOK_INBOX_MAX_BYTES Config::webhooks (WEBHOOKS_ENABLED, WEBHOOK_INBOX_MAX_BYTES); #[non_exhaustive], so build one with WebhookConfig::default() and set its fields. Unreleased.
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, CHANGELOG.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.

The localthought.io deployment (Heroku)

This section is about one deployment, not a requirement: the crate runs on any host that provides the environment variables, one HTTP port and PostgreSQL (SELF_HOSTING.md). localthought.io runs on Heroku from the separate repository localthought/integration-proxy, which since its PRs #77 (wrapper) and #78 (0.2.1 from crates.io) holds only the examples/heroku-wrapper/ files and depends on atomic-integration-proxy from crates.io. A change merged here reaches production only after it is published (see "Publishing the crate") and that repository's Cargo.lock is bumped:

# in a localthought/integration-proxy checkout, once <version> is on crates.io
# (raise the requirement in Cargo.toml too when the deployment needs it)
cargo update -p atomic-integration-proxy
cargo build --release --locked
git commit -am "Deploy atomic-integration-proxy <version> from crates.io"

Merging that to its main deploys. Do not copy this source tree there: the wrapper is the whole repository now.

0.3.0 limits key checks per client network (KEY_CHECK_LIMIT_PER_HOUR), and the webhook inbox (unreleased) limits refusals per client network. On Heroku every request's peer address is the router's, so set TRUST_FORWARDED_FOR=heroku before deploying it, or all clients share one limit (the proxy logs a warning at startup when it finds Heroku's DYNO variable without it).

From 0.2.1 the landing and consent pages no longer say "LocalThought" unless told to: set OPERATOR_NAME=LocalThought and OPERATOR_URL=https://localthought.io (Heroku config vars) to keep naming it, or leave both unset for the neutral "this integration proxy".

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. Environment (on 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 (on Heroku, 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.
  • With WEBHOOKS_ENABLED=true, the webhook inbox keeps its subscriptions, retained payloads, per-owner receipts, usage counters and hook cleanup jobs in PostgreSQL too, every one of them bounded (SECURITY.md, "Webhook inbox"). With it off, none of these tables exists.
  • 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.

Pacing under provider quotas

A provider that counts requests per source address counts the proxy's address, shared by every tenant (pieces.md P4). When a platform's composed document declares such a quota in x-throttling (Throttling), the proxy paces its own requests under it:

  • Which buckets. Those the operation selects (its own x-throttling list, or the root applies) whose partitionBy is exactly [sourceIp], or [] (one counter for all callers: the proxy's traffic alone then stays under the whole limit), with a known requests of at most 10,000 and a window.seconds. Buckets partitioned by user, credential or anything else are each caller's own and not paced; a bucket over 10,000 requests per window is not paced either.
  • How. A sliding log per platform and bucket: at most requests requests in any window.seconds, which stays under the limit for fixed (with or without an anchor), sliding and unspecified windows alike. A request is counted just before the provider is called, after authentication, the catalog checks and any token refresh, and is not given back if the provider then fails. A request that would exceed any selected bucket is refused with 429 provider_quota and Retry-After (the seconds until the oldest counted request leaves the window, rounded up); nothing is queued.
  • Limits of the model. The logs are in memory, per instance: N instances behind one egress address may together send up to N times the limit, and a restart starts empty. Other clients behind the same address (or, for [], anywhere) are not seen. The provider still enforces its own limit, and its 429 and Retry-After are forwarded as before.

Browser clients

CORS allows any origin, including a plugin frame's null origin, to send Authorization, Content-Type, If-Match, If-None-Match, If-Modified-Since, Idempotency-Key and the five x-atomic-* headers, and exposes the response headers the proxy forwards (above): Content-Type, Link, Retry-After, ETag, Last-Modified, X-Total-Count, X-Next-Page and the ten rate-limit headers. 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 <BASE_URL>/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. A mixed-kind platform uses the scheme of its selected authentication profile instead (see "Authentication profiles"). Requests cannot select a scheme, a profile 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.