Repository navigation
feat(substrate): converge egress policy on every resume - #291
Anish Ramasekar (aramase) wants to merge 4 commits into
Conversation
Signed-off-by: Anish Ramasekar <anish.ramasekar@gmail.com>
There was a problem hiding this comment.
🟡 Changes recommended
Critical races allow stale convergence to restore revoked permissions and let Create/Fork retain an allow policy when the callback returns nil instead of enforcing deny-all.
2 open issues
What changed in this PR
This PR extends the Substrate backend’s egress-policy management so configuration changes reach existing actors before backend-driven resumes, supporting the session isolation work in #251.
Changes:
- Adds semantic policy comparison, version-preconditioned updates, bounded conflict retries, and deny-all clearing.
- Introduces
SyncEgressPolicyfor running actors and classifies unreadable stored policies as configuration errors. - Expands lifecycle and error-handling tests, with documentation covering compatibility changes and enforcement limits.
| File | Description |
|---|---|
spec.md |
Records policy convergence before later resumes. |
session/egress_policy_error_test.go |
Tests API error classification and safe error text. |
runtime/substrate/substrate.go |
Integrates convergence into create, restore, attach, and fork. |
runtime/substrate/egress.go |
Implements comparison, convergence, retries, and explicit sync. |
runtime/substrate/egress_test.go |
Tests policy changes, clearing, conflicts, and sync behavior. |
integrations/substrate/egress.go |
Classifies stored-policy conversion failures. |
integrations/substrate/egress_test.go |
Tests conversion-error classification and privacy. |
integrations/substrate/e2e/egress_test.go |
Adds stored-policy checks across resume and running-actor sync. |
integrations/substrate/cmd/agentsessionsd/substrate.go |
Updates policy-file flag help for convergence behavior. |
integrations/substrate/cmd/agentsessionsd/egress_test.go |
Tests changed policy files reaching existing actors. |
docs/substrate-conformance.md |
Documents convergence, sync, cache limits, and coverage. |
docs/security.md |
Explains policy authority, revocation, and enforcement limits. |
changelog/unreleased/egress-policy-sync.md |
Announces the explicit sync API. |
changelog/unreleased/egress-policy-stored-invalid.md |
Records stored-policy error classification changes. |
changelog/unreleased/egress-policy-converge-compat.md |
Documents changed behavior and client requirements. |
Review effort: Balanced
4bb6c9a to
cc62da1
Compare
There was a problem hiding this comment.
🟡 Changes recommended
A wrapped ErrActorBusy can leak private client diagnostics through Exec/Resume ABORTED errors even with authorization enabled, requiring sanitization via busyRefusal and a regression test.
1 open issue
2 resolved since last review
Review effort: Balanced
cc62da1 to
08c8d6b
Compare
There was a problem hiding this comment.
🟡 Changes recommended
The security documentation should distinguish an unset WithEgressPolicy option, which allows an existing actor to resume with its stored policy, from a configured function returning nil, rather than describing removed configuration as fail-closed.
2 open issues
Review effort: Balanced
Signed-off-by: Anish Ramasekar <anish.ramasekar@gmail.com>
08c8d6b to
d93ad36
Compare
There was a problem hiding this comment.
🟡 Changes recommended
The documentation needs to qualify its stored-policy guarantee because a quick suspend, policy tightening, and resume can still permit traffic under the cached old policy.
1 open issue
2 resolved since last review
Review effort: Balanced
Signed-off-by: Anish Ramasekar <anish.ramasekar@gmail.com>
…refusal Signed-off-by: Anish Ramasekar <anish.ramasekar@gmail.com>
d93ad36 to
4d7b85e
Compare
There was a problem hiding this comment.
🔵 Needs a closer look
Maintainer validation is needed because security-sensitive policy convergence depends on Substrate versioning and gateway-cache behavior, while tests verify stored policies rather than live traffic enforcement or credential injection.
No open issues 🎉
1 resolved since last review
Review effort: Balanced


Closes #251.
A changed
WithEgressPolicy(or-substrate-egress-policy-file) used to reach only actors created after it changed: an actor that already had a policy kept it. The backend now converges each actor's stored policy on the configured one before every resume of a suspended actor, with no opt-out.UpdateActorEgressPolicyunder the UID and version it read. A conflicting writer starts a new read, up to three attempts, then the call fails asErrActorBusy.Backend.SyncEgressPolicy(ctx, sessionUID)applies a changed policy to a running actor without suspending it. Substrate picks it up within its policy caches (about 10 seconds for requests and new connections, 5 seconds for DNS on v1.0.0); an open TLS passthrough connection is not cut. The daemon does not call it.ErrEgressPolicyInvalid, which reaches callers asFAILED_PRECONDITION/COMPUTE_CONFIG_INVALIDwith fixed text.Compatibility (changelog fragment in the Compatibility category):
EgressPolicyClientused withWithEgressPolicymust implementGetActorEgressPolicyandUpdateActorEgressPolicyas well asCreateActorEgressPolicy. AControlClientwithoutEgressPolicyClientis refused (ErrEgressPolicyUnsupported) on every resume of an existing actor and every Sync, whatever the function returns, instead of resuming with the old policy. The daemon already refused that setup at startup.Docs updated: the
EgressPolicyClientandSyncEgressPolicydocs inruntime/substrate/egress.go,docs/security.md,docs/substrate-conformance.md(with spec and conformance IDs) andspec.md.Tested:
ControlClientcover unchanged, changed, nil-clears, create-exists and update-not-found races, precondition conflicts and retry exhaustion, error classification through Exec, Resume and Fork, fork children, and Sync. The fail-closed refusal for a client withoutEgressPolicyClientis pinned for Restore, Create attach and Sync.go test -race ./runtime/substrate/... ./session/...andgo test -race ./...inintegrations/substrate.gofmt,go vet,hack/changelog check,hack/check-doc-links.pyandhack/doccheckpass.