atomic-integration-proxy 0.4.3

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
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
# 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](https://github.com/ontola/atomic-server) agents.

Connections retain Atomic agent ownership (issue
[#54](https://github.com/ontola/atomic-plugins/issues/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](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](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

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=&maxBytes=&wait=` (long
  poll up to 25 seconds; at most `maxBytes` of base64 payload per page, an
  event over it alone coming back alone with `payload.omitted: true` and no
  `body`), `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`](../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. 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 <Platform>; 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.
- `POST /agents/transfer` — **signed by the old agent**; body `{"to",
  "proof"}` moves the signer's connections and runtimes to the agent `to`
  and retires the signer (key rotation, #410). `proof` is `to`'s Ed25519
  signature (base64, either alphabet) over
  `integration-proxy-agent-transfer-v1\n{old id}\n{new id}\n{proxy origin}\n{this request's x-atomic-timestamp}`,
  ids canonical. The proxy origin is `BASE_URL`'s scheme, host and port only
  (no path, no trailing `/`), the same `aud` a frame capability carries;
  `BASE_URL` itself, path included, is what the request signature covers. `to` must pass the access policy and must not be retired.
  Delegations stay as they are. Afterwards the old id is refused
  (`403 agent_retired`) as the signer of management calls, of
  `/connect/redeem` and of another transfer, and capabilities it signed no
  longer verify. `409 transfer_blocked` while the old agent has open
  webhook subscriptions; `409 transfer_conflict`, with nothing moved, when
  the new agent already has a runtime with the same agent. `200`
  `{"from", "to", "connections", "runtimes"}` (the counts moved). Only for a
  key the user still holds: see SECURITY.md, "Key rotation".
- `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), `invalid_transfer_proof` |
| 403 | `not_owner`, `not_delegated`, `capability_scope`, `platform_mismatch`, `access_denied`, `agent_retired` |
| 409 | `transfer_blocked`, `transfer_conflict` |
| 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`](#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-29-google-keep-writes.json`, this repository's `overlays/catalog/2026-10-29-google-keep-writes.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](SECURITY.md#webhook-inbox-369-unreleased)). 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 requests of such networks at a time may wait for or hold the endpoint-lookup slot: while 2 do, 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](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 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-29-google-keep-writes.json`](../overlays/catalog/2026-10-29-google-keep-writes.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-29-google-keep-writes.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.

This source default retains the previous auth-profiles catalog's nine entries
and adds Google Keep with a refreshed OAD and auth, pagination and CRUD overlays.
The Keep profile exposes list/get/create/delete notes; Google has no update
operation. Attachment download and sharing stay outside that profile. Device
tokens require a separate, explicit `proxy:write` grant for mutations. Existing
read sessions retain their restrictions. SyncD additionally requires per-collection
write configuration and explicit sending; see
[provider writes](../syncables/docs/daemon-writes.md). An explicit deployment `CATALOG_PATH` still wins.

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). Like the rest of `/catalog` it needs no
signature, so a `throttlingPlans` entry in it tells anyone which provider
plan the deployment is on.

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`](../openapi-extensions/spec/produced-classes/README.md),
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`](../openapi-extensions/spec/authentication-profiles/README.md),
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`](../openapi-extensions/spec/api-key-details/README.md)
  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

```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, 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:

```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.svg`, `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.

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](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](../openapi-extensions/spec/throttling/README.md)), 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.
- **Plan tiers** (Throttling 0.5.0). A bucket whose limit has `tiers` is
  paced at the tier whose `plans` name the deployment's plan, given in the
  dated catalog entry's `selection` as
  `"throttlingPlans": {"<bucket id>": "<plan>"}`. Without one, or for a plan
  no tier names, the proxy keeps within every tier at once, each tier's
  `requests` in its own window as a separate count over the same requests
  (no single tier is safe alone: 30 an hour still allows a burst 20 a second
  forbids). For these proxy-wide buckets the plan that counts is the
  deployment's own (its address or application), so the deployment's
  catalog chooses it. An entry for a bucket without tiers or for a plan no
  tier names is logged when the catalog loads and ignored. A tier over
  10,000 requests per window is left out; the other tiers still count.
- **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

```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. 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](#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.