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.204only after it was stored (or recorded as a gap, or wanted by nobody);401unverified,413over the cap,503not stored. -
POST /connections/{id}/subscriptions{source, parameters, events},GETandDELETE /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 /cataloglists the platforms;GET /catalog/{platform}.yamlreturns 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_urimust behttps, loopbackhttp, or the Atomic app's deep link (atomic://…); it may not carryconnection_codeorerrorparameters, credentials or a fragment. -
POST /connect/authorize— the consent form (cookie-bound CSRF token, single use). For an OAuth platform it answers200with a page that continues to the provider (a<meta>refresh plus a button, sent withReferrer-Policy: no-referrer) rather than redirecting: the consent page's CSPform-actiongoverns 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: apiKeyin the composed document) the consent page asks for the key, and this seals it and redirects (303) toredirect_uri. When the scheme declaresx-api-key-details(openapi-extensions/spec/api-key-details, 0.2.3 and later), the page shows the scheme'sdescriptionand links itshelpUrl(a plain link that opens in a new tab), and this first calls the declaredkeyCheckoperation once with the key: a fixedGETon the document's ownhttpsserver, no redirects, 10-second timeout. A401or403answers 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 a400and nothing is stored. One consent page makes at most 5 key checks (unreleased): the fifth rejection spends it and answers400"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 mostKEY_CHECK_LIMIT_PER_HOUR(default 20) key checks per platform in any hour (unreleased); over that, the answer is429"Too many key checks from your network for ; try again later" withRetry-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 istype: httpwithscheme: bearerorscheme: 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 theAuthorizationheader 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-levelsecurity: []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) toredirect_uri; requests are forwarded with none. Approving the same consent page twice answers400"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 toredirect_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.labelis 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'sAuthorizationandx-atomic-*headers are never forwarded: anAuthorizationmust 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 onlyContent-Type,If-Match,If-None-MatchandIf-Modified-Sincego upstream, plusIdempotency-Keywhere the operation declares anIdempotency-Keyheader 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-Pageand the rate-limit headersX-RateLimit-Limit,-Remaining,-Used,-Reset,-Resource,RateLimit,RateLimit-Policy,RateLimit-Limit,-Remainingand-Resetcome back unchanged, by exact name; every other response header is dropped, and every/proxy/…response carriesCache-Control: no-store. On a no-credential connection theIdempotency-Keygoes 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'slabelis 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"?}registersagent(a node's app agent) as a runtime of installationappfor the signer.DELETE /runtimes/{agent}removes it. A runtime can use every connection its app is delegated. -
GET /healthz—200 okwhen 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:
oauth2with an authorization-code flow,apiKey, or a bearer or basichttpscheme (the last two with theirx-api-key-detailshelp 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
securityhas a requirement whose only member is the profile's scheme; - answers
404 method or path is not in the catalogfor 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
httpscheme 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
httpscheme counts only when the document declares nooauth2and noapiKeyscheme. A document that has one of those resolves exactly as before, whateverhttpschemes it also declares (OAuth documents often declarehttpbasicfor client authentication at their token endpoint). With several bearer/basic schemes,selection.httpSecuritySchemenames one. A profile may name a bearer or basic scheme of any document. Otherhttpschemes (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 carryAuthorization: Bearer <token>. - Basic. The scheme must declare how the token fills the credential, as
x-api-key-details.basicCredentials(api-key-details0.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 carryAuthorization: Basic base64(username:password). - Key check, help and sealing.
x-api-key-detailshelpUrlandkeyCheckwork as for an API key; the check is sent the sameAuthorizationheader 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
httpscheme 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'sinandname(header names case-insensitive) the same way. Otherwise it answers401 credential_refresh_failed(connect again). Credentials stored before carry no binding and are sent as before. The caller's ownAuthorizationis 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
Then open http://localhost:8080 (or your configured BASE_URL). For a
deployment, see SELF_HOSTING.md; GET /healthz is the
health check.
Development
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:
async
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:
&&
&&
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)
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=Laxcookies:platform_consent(the pending request and CSRF token) andplatform_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 productionBASE_URLmust usehttps://.http://localhostworks during local development because browsers treatlocalhostas 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-throttlinglist, or the rootapplies) whosepartitionByis exactly[sourceIp], or[](one counter for all callers: the proxy's traffic alone then stays under the whole limit), with a knownrequestsof at most 10,000 and awindow.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
requestsrequests in anywindow.seconds, which stays under the limit forfixed(with or without ananchor),slidingandunspecifiedwindows 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 with429 provider_quotaandRetry-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 its429andRetry-Afterare 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
# 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 \
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.