Skip to content

v0.4.1: idempotent replay authorization (security release)

Choose a tag to compare

@arybach arybach released this 29 Oct 21:19
· 180 commits to main since this release
5342fc6

v0.4.1: idempotent replay authorization (security release)

This release corrects how the Agent Gateway serves a repeated request that carries an idempotency key. It contains behaviour changes: read "Upgrade impact" before upgrading, especially if you use a custom idempotency store.

Advisory: GHSA-v5xj-6fr8-2h45 (Medium, 6.3; each class alone 4.3).

What was wrong

Weakness Affected
A stored idempotent result was returned before the caller's current visibility, permission and OAuth scope were checked, so a revoked grant or narrowed scope was still answered with the earlier result >= 0.3.1, < 0.4.1
With an authority guard: a replay was also served after the envelope or a child agent was revoked, and for an invalid child credential >= 0.4.0, < 0.4.1 (the authority guard and child credentials do not exist before 0.4.0)
The key was bound to tenant, subject and capability but not to the arguments or workspace: the same key with different arguments, or from another workspace, returned the first result; with child credentials a different child also received it arguments, workspace: >= 0.3.1, < 0.4.1; child: >= 0.4.0, < 0.4.1
A write whose output the egress policy held for export approval was not stored, and a retry with the same key executed it again >= 0.3.1, < 0.4.1
The built-in store had no time-to-live, size bound or key-length limit >= 0.3.1, < 0.4.1
Replays left no audit event >= 0.3.1, < 0.4.1

A different capability, subject or tenant under the same key was already kept apart in every version. A write whose result an operator established with reconcile_call(executed=True, result=...) was already replayed, not sent again, in 0.4.0.

The shipped Projects mount is not exposed: its seven capabilities are read-only and none is declared idempotent. Exposed are embedders that use idempotent capabilities with caller-supplied keys, an authority guard with delegated children, several workspaces under one principal, or a custom idempotency store.

What changed

  • A replay is answered only after the caller is identified, may see the capability (grants and OAuth scope) and, with an authority guard, passes a new AuthorityGuard.check (scope, envelope, ancestor revocation, child credential, expiry, time allowance). The egress policy is asked again about the stored output. Nothing is executed on a replay, and replays are audited.
  • Each key is bound to a SHA-256 of the workspace, subject, authority key, capability and canonical arguments. A different request under the same key gets idempotency_conflict; a call still running gets idempotency_in_progress (under an authority guard, a concurrent retry of a running direct write is denied with authority:outcome_unknown). Neither reveals the earlier result. Claims are atomic, so concurrent retries execute once.
  • A key on a side-effecting call means "do this once": a retry replays the stored result, also after a reconcile that supplied a result, and for a write whose output is held by the egress policy. A retry of a write whose outcome cannot be established stays blocked (authority:outcome_unknown) and is never retried automatically. reconcile_call(executed=True) without a result gives nothing to replay, so a retry is sent again.
  • The built-in store has a 24 h time-to-live, a 10,000-entry bound and an optional max_entries_per_tenant. Eviction takes completed reads first, oldest first, from the tenant holding the most entries. Completed writes and reconciled results are kept until their time-to-live; when nothing can be evicted, new keyed calls are refused (fail closed, nothing executes). Without a per-tenant cap, one tenant's completed writes can fill the shared store and make new keyed calls fail for every tenant until entries expire.

Upgrade impact

  • IdempotencyStore changed from get/put to begin/complete/abandon/seed, and begin takes a write= keyword. A gateway built with an old-style store raises TypeError at construction. A custom store whose begin lacks write= makes every keyed covered call fail closed with gateway_error. A custom or shared durable store now persists the unfiltered output of a held write for the time-to-live and must protect it accordingly.
  • Keys are per tenant, not per caller: another subject or workspace of the same tenant that sends the same key now gets idempotency_conflict (before, a different subject had its own execution). Use a key that is unique to the request, such as a UUID.
  • A key must be 1 to 256 characters. Arguments that JSON cannot carry (objects, bytes, non-finite numbers), more than 256 KiB, nesting deeper than 16 levels, or argument names that collide after NFC normalisation now fail with gateway_error on a covered capability called with a key.
  • Two new client codes: idempotency_conflict and idempotency_in_progress.
  • A write can still be sent again after its entry expires (24 h), after a restart, on a second worker with its own store, or with a custom store that evicts. Use a durable shared store together with the authority guard in production.

Details: section 34 of docs/PERMISSIONS_MIGRATION.md and RELEASE_NOTES_security.md in the tag.

Also in this release

  • The root Dockerfile builds again (it failed at pip install since 0.3.40). Pass PERMISSIONS_KEY when you run the image; without a key the control plane refuses to start.

What this release does not claim

  • The reviews behind these changes were AI-assisted, with separate reviewer agents working from the code diff. They are not an external audit or third-party certification.
  • Multi-worker and durable stores were not exercised; the built-in store is per process. The binding does not include the OAuth client id.
  • The module proxy (/m/<name> and /m/<name>/api/*) still forwards requests without a credential (issue #528).
  • The Enterprise packages are separate and out of scope of this release.