# integration-proxy
A Rust web server that holds OAuth grants and pasted API keys for third-party
platforms, and forwards catalog-allowlisted requests to them on behalf of
[Atomic](https://github.com/ontola/atomic-server) agents.
There are no proxy accounts, logins or tenants (issue
[#54](https://github.com/ontola/atomic-plugins/issues/54)). The account is
the caller's Atomic agent, `atomic:agent:<public key>`: every request that
matters is signed with that key, and the proxy verifies it against the key
inside the id, so it looks nothing up. A **connection** (one provider grant)
is owned by the agent that redeemed it; the owner **delegates** it to app
agents, and may register **runtimes** (a node's app agent) for them. A plugin
frame, which cannot keep a key, uses a short-lived **capability** signed by
the owner and bound to a key the frame holds in memory.
PostgreSQL stores connections (provider credentials sealed with
XChaCha20-Poly1305), delegations, runtimes, five-minute connect handoffs and
the single-use record of signed requests.
Built with [axum](https://github.com/tokio-rs/axum), following the OAuth 2.0
Authorization Code flow with PKCE towards providers.
**To run your own instance**, see [SELF_HOSTING.md](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:
```text
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
- `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`](../openapi-extensions/spec/api-key-details/README.md),
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. A 2xx may give a label (at most
200 characters, sealed with the connection). 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). The proxy attaches the provider credential,
refreshing an expiring OAuth token (one refresh in flight per connection),
and forwards only catalog-allowlisted methods and paths. The caller's
`Authorization` and `x-atomic-*` headers are never forwarded. `Link`,
`Retry-After`, `ETag`, `X-Total-Count` and `X-Next-Page` come back unchanged.
- `GET /connections` — **signed**; the signer's connections with their
delegations (`agent`, `label`, `created_at`, `last_used_at`), and the
signer's runtimes. Never credentials. Shape:
`{"owner", "connections": [{"connection_id", "platform", "owner", "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.
- `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:
```text
Authorization: Capability <payload>.<sig>
payload = base64url(JSON), unpadded:
{"v":2,"connection_id","platform","aud","app","cnf","exp"}
sig = the connection owner's Ed25519 signature, base64, over
"integration-proxy-capability-v2\n" + the JSON bytes
```
`aud` is the proxy origin (`BASE_URL`'s scheme, host and port); `app` is the
installation's app agent, which must hold a delegation; `cnf` is the frame's
key as `atomic:agent:<key>`; `exp` is Unix seconds, at most 15 minutes ahead.
The request itself must also carry v2 headers signed by `cnf`'s key, so a
copied capability is useless without the frame. The proxy checks, in order:
the owner's signature, `aud`, `exp`, `connection_id` and `platform`, the
delegation for `app`, and the request signature by `cnf` (with skew and
replay). On `401 capability_expired` the frame asks its page for a new one.
### Errors
Signed endpoints answer errors as JSON, `{"error": "<code>", "message": "<text>"}`:
| Status | `error` |
| --- | --- |
| 401 | `missing_signature`, `unsupported_signature_version`, `invalid_agent`, `agent_key_mismatch`, `stale_timestamp`, `bad_signature`, `replayed`, `unsupported_authorization` (e.g. a retired `Bearer` connection code), `invalid_capability`, `capability_expired`, `capability_too_long`, `wrong_audience`, `capability_key_mismatch`, `credential_refresh_failed` (connect again) |
| 403 | `not_owner`, `not_delegated`, `capability_scope`, `platform_mismatch`, `access_denied` |
| 404 | `unknown_connection` (deleted, idle-expired, or never existed: connect again) |
| 400 | `bad_request`, `invalid_handoff` |
Catalog refusals and upstream failures from `/proxy/…` keep their plain-text
bodies (`404 method or path is not in the catalog`, `502 upstream request failed`).
### Who may use the proxy
Every signed request's connection owner (and the redeemer, at
`/connect/redeem`) is checked against an `AccessPolicy`. Delegated agents and
frames are checked as their owner, so limits count per owner. The default
policy admits every agent except those in `REVOKED_SUBJECTS`, and only those
in `ALLOWED_AGENTS` when that is set. The atomic.place deployment is meant to
plug in a lookup of the agent's SaaS account and tier
([`build_app_with_access`](#library-crate)); 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.json`, this repository's `overlays/catalog/2026-10-02.json` as GitHub Pages publishes it from `main`. |
| `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. |
| `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](SELF_HOSTING.md#database_url-and-postgresql-tls). 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](SELF_HOSTING.md#registering-oauth-apps). 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 initial
read-only integration uses `identify` and `guilds` to read your profile and
import server memberships; it does not import messages or require a bot token.
The guild import requests `limit=200`, covering Discord's documented maximum
number of guilds for a user. The profile endpoint is available as a read
operation, not an imported collection.
Discord access tokens expire and use the existing refresh-token flow.
Spotify uses `OAUTH_SPOTIFY_CLIENT_ID` and the callback
`<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.json`](../overlays/catalog/2026-10-02.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.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.
**GET /catalog/{platform}.selection.json** returns the selection object (or an
empty object when absent).
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
```sh
cargo run
```
Then open `http://localhost:8080` (or your configured `BASE_URL`). For a
deployment, see [SELF_HOSTING.md](SELF_HOSTING.md); `GET /healthz` is the
health check.
## Development
```sh
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](examples/heroku-wrapper/).
## Library crate
This package is published to crates.io as
[`atomic-integration-proxy`](https://crates.io/crates/atomic-integration-proxy)
(library `atomic_integration_proxy`, binary `integration-proxy`), so a
deployment can be a thin wrapper that depends on it by semver instead of a
copy of the source. The public API is intentionally small; everything else is
private and may change in any release:
| Item | What it does |
| --- | --- |
| `Config`, `Config::from_env()` | All configuration, read from the environment variables described above. |
| `DEFAULT_CATALOG_PATH` | The pinned catalog URL used when `CATALOG_PATH` is unset. |
| `build_app(&Config) -> Result<axum::Router, Error>` | Loads the catalog, connects to PostgreSQL, returns the router (CORS and tracing layers included), with the default `EnvAccessPolicy`. |
| `build_app_with_access(&Config, Arc<dyn AccessPolicy>)` | The same, admitting connection owners through a custom policy (e.g. a SaaS account and tier lookup). |
| `AccessPolicy`, `Access`, `AllowAll`, `EnvAccessPolicy` | The admission check asked about every owner; `AllowAll` for a self-hosted proxy. |
| `AgentId`, `parse_agent_id` | A parsed agent id; `as_str()` is the canonical `atomic:agent:` form. |
| `serve(Config) -> Result<(), Error>` | `build_app`, then bind `0.0.0.0:{PORT}` and serve. |
| `run() -> ExitCode` | What the binary does: init `tracing` from `RUST_LOG` (default `info`), `Config::from_env`, `serve`, print any `Error` to stderr. |
| `Error` | Startup/serve failure; `Display` is the one-line message the binary prints. |
A complete wrapper `main.rs` is:
```rust
#[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:
```sh
# 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](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/`](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:
```sh
# 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.
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](SECURITY.md)
describes the controls and what is not yet verified.
## Notes on state
- Nothing identifies a browser session: there are no session cookies. The
consent screen and the OAuth callback use two short-lived (10 minute)
encrypted `Secure`/`HttpOnly`/`SameSite=Lax` cookies: `platform_consent`
(the pending request and CSRF token) and `platform_oauth` (binding the
callback to the approving browser). Provider state, handoffs and
connections live in PostgreSQL, so any instance can serve any request.
- Cookies are marked `Secure`, so in production `BASE_URL` must use
`https://`. `http://localhost` works during local development because
browsers treat `localhost` as a secure context.
## Browser clients
CORS allows any origin, including a plugin frame's `null` origin, to send
`Authorization`, `Content-Type`, `If-Match` and the five `x-atomic-*` headers,
and exposes `Content-Type`, `Link`, `Retry-After`, `ETag`, `X-Total-Count` and
`X-Next-Page`. Cookie credentials are not enabled for CORS; consent remains a
top-level browser navigation.
## Todoist
The `todoist` platform imports projects and active tasks through Todoist API v1
with the read-only `data:read` scope. Configure `OAUTH_TODOIST_CLIENT_ID` and
`OAUTH_TODOIST_CLIENT_SECRET`, and register
`<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
```sh
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](TESTING_COVERAGE.md) maps each verification step to its tests. Live Google/GitHub authorization and a hub import must be verified against matching deployed revisions of the proxy and atomic-server; local fixture checks do not establish live access.
### OAuth client registration
Integration authorization and token endpoints and required scopes are read
from the composed OpenAPI catalog. A platform with one OAuth
authorization-code Security Scheme uses it directly. A platform with multiple
such schemes must set the catalog's trusted
**selection.oauthSecurityScheme**; missing, non-string, or unknown selections
fail closed. Requests cannot select a scheme or supply endpoints. Scopes are
taken from operation security requirements (falling back to root
requirements), not every scope supported by the server. Public operations
require no scopes; unsupported authentication combinations fail closed.
`OAUTH_<PLATFORM>_CLIENT_AUTH_METHOD` optionally overrides the client authentication method: `none`, `client_secret_post`, or `client_secret_basic`. When omitted, the proxy selects the **first usable method in the declared array order** of `x-oauth-authentication-details.authorizationServerMetadata.token_endpoint_auth_methods_supported` in the selected OAuth security scheme. It skips methods the proxy does not implement and methods incompatible with the referenced token/refresh operations. If the array declares no usable method, configuration fails rather than silently falling back.
When that metadata is absent, the proxy retains `client_secret_post` for compatibility, except when a referenced token or refresh operation requires HTTP Basic authentication: it then uses `client_secret_basic`. Explicit overrides must still be supported by the metadata and token operations; an invalid override is an error, not a request to auto-select.
For example, Notion advertises only `client_secret_basic`, so its `_CLIENT_AUTH_METHOD` setting can be omitted. For `["private_key_jwt", "none", "client_secret_basic"]`, the proxy skips the unimplemented JWT method and chooses `none`. Array order is this proxy's default-selection policy, not an assertion of provider preference or the client's registered method. Set the override when your client registration requires a different advertised method. Public clients use `none` and do not load or send a secret; confidential methods require `_CLIENT_SECRET`. Missing credentials cause an error and do not trigger selection of another method. Authorization uses S256 PKCE unless trusted metadata explicitly declares PKCE unsupported.
The proxy implements a bounded subset of
**x-oauth-authentication-details**. It reads inline
**token_endpoint_auth_methods_supported**,
**code_challenge_methods_supported**, PKCE requirements, and fixed
authorization profile parameters. Parameter references must be local. Schema
validation supports **type**, **enum**, recursive **items**, **properties**,
**required**, and **additionalProperties**; other validation keywords fail
closed. Serialization supports scalar form values, form/space/pipe-delimited
scalar arrays, and form/deep-object scalar objects. Reserved OAuth fields and
query-name collisions are rejected.
The proxy does not fetch **oauth2MetadataUrl** and does not interpret
**tokenEndpointOperation** or **refreshEndpointOperation**. A selected scheme
that contains any of those fields is rejected, because discovery or a
separately described operation could require different token-request
authentication or wire behavior.
Upgrading from 0.1 is a flag day (issue #54, decision 6): see
[What was removed](#what-was-removed-flag-day). 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.