Skip to content

integration-proxy: persistent DID-bound connections, signed requests and capabilities (candidate for #54) - #72

Closed
michielbdejong wants to merge 1 commit into
mainfrom
claude/issue-40-did-bound-connections
Closed

michielbdejong wants to merge 1 commit into
mainfrom
claude/issue-40-did-bound-connections

Conversation

@michielbdejong

Copy link
Copy Markdown
Contributor

Refs #40
Refs #54

Draft. Do not merge. This is the candidate implementation for the auth re-design discussion in #54. The design decisions listed below are still open there.

Why

Today the rotating connection code is the only place a grant lives. It is a single-use bearer token held in one browser, so a lost response, a second tab or a second device each cost the user a fresh OAuth flow. #42 fixed the ten-minute idle loss. This PR fixes the rest by separating grant durability from how a caller authenticates.

Design

A. Persistent connections table. Each row holds a random 43-character connection_id, the platform, tenant, owning user_id (the DID), and the sealed credential. The row is encrypted with XChaCha20-Poly1305, with associated data naming its connection_id, so envelopes cannot be swapped between rows.

  • /connect/redeem creates the row and now also returns connection_id. The field is additive and not a secret.
  • A connection code now seals only a pointer to its row, so a refreshed or rotated OAuth token exists in exactly one place.
  • Legacy codes that seal a full credential are migrated into a row on first use. Existing clients need no change.
  • Rows are deleted after 90 days (CONNECTION_IDLE_DAYS) without an authenticated request. Knowing an id does not keep a row alive.
  • The successor code is minted right after authentication. A refused path, failed refresh or upstream error therefore still returns one, instead of killing the connection.
  • Concurrent callers that find the access token expired take a lease on the row (refresh_lease_until, 30 s). The winner refreshes and the others wait for its result. A provider that rotates refresh tokens, or detects their reuse, never sees the same one twice.
  • Every authenticated response carries X-Connection-Id.

B. Signed requests. did:ad:agent:{pubkey} contains its own Ed25519 key, so the proxy resolves nothing and pins nothing. A new key is a new DID and needs a new connection.

  • The key holder sends X-Connection-Id, X-Connection-Timestamp (Unix ms) and X-Connection-Signature. The signature is over:
    integration-proxy-request-v1\n<connection_id>\n<METHOD>\n<path?query as sent>\n<timestamp>\n<sha256 hex of body>
    
  • The timestamp must be within ±5 min of the proxy's clock. Each signed message is accepted once: a digest of the message goes into used_challenges.
  • Nothing is stored client-side and nothing rotates. Concurrency, idleness and multiple devices stop mattering.

C. Capabilities. The key holder signs {"v":1,"connection_id","platform","exp"} with the domain prefix integration-proxy-capability-v1\n. A caller that cannot hold the key, such as a sandboxed plugin frame, presents it as Authorization: Capability <payload>.<sig>.

  • A capability is reusable until exp. The proxy refuses one that expires more than 15 min ahead.
  • An expired capability gets 401 capability expired, so the holder knows to mint a new one.
  • Capabilities are minted client-side, as in integrations/HANDOFF-proxy-capabilities.md. The proxy has no minting endpoint.

Both signed formats are domain-separated from each other and from Atomic's "{subject} {timestamp}" auth message. Verification uses verify_strict, which rejects small-order keys and non-canonical signatures. Full format: integration-proxy/README.md → "Persistent connections". Guarantees and gaps: integration-proxy/SECURITY.md → "Persistent connections".

Open decisions (tracked in #54)

  1. Revoking a single connection. Not implemented. The recommendation is an owner-signed DELETE /connections/{id}. Today REVOKED_SUBJECTS can only revoke a whole tenant or DID.
  2. Proof of DID possession at connect/redeem. user_id is still the hub's unverified assertion. Security does not depend on it, because binding a grant to someone else's DID gives the binder nothing. Recommendation: optional now, required later.
  3. Lifetimes. 90 idle days per connection, 15 min maximum per capability, ±5 min skew for signed requests.
  4. B and C, or just B. The Follow-ups after the per-plugin CI lane split (#37, #38) #43 §4c direction (no credential in the iframe, go over FrameBridge) needs only B. The handoff doc needs C.
  5. Multi-node (Check whether an app's agent is usable on a second node (app-agent-per-node gap) #41). On a node that lacks the app agent's key, requests fail closed with 401. If a second node mints its own app DID, it needs its own connection and OAuth flow.

Verification

  • cargo fmt --all -- --check: clean.
  • cargo clippy --all-targets --all-features -- -D warnings: clean.
  • cargo test -- --include-ignored against a fresh local postgres:16-alpine: 136 passed, 0 failed. It ran three times in a row after rebasing onto origin/main 2841447 (which includes integration-proxy: a refresh token is destroyed after ten idle minutes #42 via 10c60eb), using cargo 1.98.1 and the CI fixture OAuth env vars. Plain cargo test: 107 passed, 29 ignored.
  • New PostgreSQL tests:
    • signed requests: no rotation, concurrent use, replay rejected, wrong key and altered target rejected;
    • capabilities: reusable, expired, over-long and forged ones rejected, platform-scoped;
    • a legacy code migrates into a row and the row becomes signable;
    • a refused request still returns a successor code;
    • 5 concurrent callers with an expired token cause exactly 1 refresh, and the rotated refresh token is persisted.
  • Four existing tests read the credential straight out of the code envelope. They now follow the pointer to the row.
  • Pure unit tests in src/did_auth.rs cover DID parsing in both base64 alphabets, message binding and domain separation.

Not verified:

  • No real @tomic/lib or atomic-server client has signed against this. The test signer follows the documented format.
  • Lease takeover after a crashed refresher.
  • Deletion of rows after 90 idle days.
  • Live providers.

🤖 Generated with Claude Code

…ure and capability auth

Before this change, a rotating connection code was the only place a grant
lived, so idleness, a lost response, a second tab or a second device each
cost the user a new OAuth flow. This implements #40 items A, B and C on top
of #42's 30-day code lifetime.

A: a `connections` table holds each grant: a random connection_id,
platform, tenant, owning user_id, and the sealed credential with its AAD
bound to the row. A row is created at /connect/redeem, which now also
returns `connection_id`. Codes minted before this change are migrated into
a row on first use. From then on a code seals only a pointer to its row,
so the credential has a single server-side copy. Rows expire after 90
days (CONNECTION_IDLE_DAYS) without an authenticated request. The
successor code is minted as soon as a request authenticates, so a refused
path, a failed refresh or an upstream error no longer costs the
connection. Concurrent refreshes are serialized by a lease column, so a
rotating refresh token is never spent twice.

B: when user_id is did:ad:agent:{pubkey}, the holder of that Ed25519 key
can sign a single request instead of presenting a code. The signature
covers the connection, method, path+query, timestamp and body digest. It
is sent in X-Connection-Id/-Timestamp/-Signature, must fall within ±5
minutes, and is accepted once (recorded in used_challenges). The DID
carries its own key, so nothing is resolved or pinned.

C: the key holder can also sign a capability
{v, connection_id, platform, exp}, presented as
`Authorization: Capability <payload>.<sig>`. It can be reused until exp,
and the proxy refuses capabilities that live longer than 15 minutes. It
is minted client-side, as proposed in HANDOFF-proxy-capabilities.md;
the proxy has no minting endpoint.

Both signed formats are domain-separated from each other and from
Atomic's "{subject} {timestamp}" auth message. Neither rotates anything.

Not included, and left open for the maintainer: per-connection
revocation, proof of DID possession at connect time, and the idle and
lifetime numbers. SECURITY.md and README document the format and the
limits.

Refs #40

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@michielbdejong

Copy link
Copy Markdown
Contributor Author

Being reworked for the interim #54 decision on a new branch, claude/issue-54-proxy-auth. Its persistent connections, sealed tokens and replay store carry over; its x-connection-* signatures and v1 bearer capability are replaced by Atomic v2 signatures and the v2 frame capability. I'll close this draft once the new PR is open.

@michielbdejong

Copy link
Copy Markdown
Contributor Author

Superseded by #122, which implements the interim #54 design.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant