Repository navigation
v0.4.1: idempotent replay authorization (security release)
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 getsidempotency_in_progress(under an authority guard, a concurrent retry of a running direct write is denied withauthority: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
IdempotencyStorechanged fromget/puttobegin/complete/abandon/seed, andbegintakes awrite=keyword. A gateway built with an old-style store raisesTypeErrorat construction. A custom store whosebeginlackswrite=makes every keyed covered call fail closed withgateway_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_erroron a covered capability called with a key. - Two new client codes:
idempotency_conflictandidempotency_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
Dockerfilebuilds again (it failed atpip installsince 0.3.40). PassPERMISSIONS_KEYwhen 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.