docs: align TCP bind capability contract - #24
Merged
Conversation
Signed-off-by: Joshua J. Bouw <jjb@unicity-labs.com>
5 tasks
There was a problem hiding this comment.
Pull request overview
Updates the astrid:net@1.0.0 host ABI documentation to match Astrid’s enforced TCP bind capability contract, clarifying what addresses are permitted and which capability gate applies.
Changes:
- Document
bind-tcpas loopback-only and reject wildcard/non-loopback binds. - Rename the capability gate referenced by docs to
[capabilities].net_bindand note it is distinct fromnet_connect. - Remove prior documentation claims about wildcard-interface support and
net_tcp_bind.
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Comment on lines
+340
to
+344
| /// Astrid confines TCP listeners to loopback hosts: `localhost`, | ||
| /// `127.0.0.0/8`, or `::1`. Wildcard and non-loopback interfaces are | ||
| /// rejected. Port `0` selects an ephemeral port. The requested | ||
| /// `host:port` must match the capsule's `[capabilities].net_bind` | ||
| /// allowlist; this authority is distinct from `net_connect`. |
joshuajbouw
added a commit
to astrid-runtime/astrid
that referenced
this pull request
Aug 12, 2026
## Linked Issue Closes #1230. ## Summary Adds governed inbound TCP listeners for WASM capsules. A capsule can bind an explicitly declared loopback endpoint, await readiness or accept a connection, and use the existing network-stream interface without ambient host networking. ## Changes - Implement bind-tcp with manifest net_bind authorization and a loopback-only boundary. - Prevent TCP declarations from authorizing the kernel-provided Unix CLI listener or session token. - Serialize readiness acceptance, preserve one pending connection, and perform quota plus durable audit accounting at the actual accept effect. - Carry host-observed endpoints with pending connections so transfer cannot lose provenance or leak quota. - Enforce listener and stream ceilings across the pooled capsule runtime with per-Store reset accounting. - Prevent readiness pollables from retaining listener resources after listener drop. - Append NetAccept without shifting existing public audit discriminants. - Pin the canonical WIT submodule to merged astrid-runtime/wit#24 and regenerate the staged publish mirror from that source. ## Verification - cargo test -p astrid-capsule engine::wasm::host::net - cargo test -p astrid-capsule returning_one_store_preserves_another_stores_stream_quota - cargo test -p astrid-audit - cargo clippy for affected crates with all features and warnings denied - repository file-size check reproduced locally Regression coverage includes Unix and TCP authority separation, cancellation and concurrent readiness, listener lifetime, quota release, two-Store pooled accounting, loopback policy, and audit provenance. ## AI / Tool Assistance Assisted-by: Anthropic Claude: Opus 5nAssisted-by: OpenAI Codex: GPT-5 Claude Opus 5 assisted Jamie with the original implementation. Codex performed the subsequent adversarial review, implemented authority and accounting fixes, added regression coverage, aligned contract documentation, and validated the affected crates. Human-authored DCO and GPG signatures remain on every commit. ## Checklist - [x] Linked to an issue - [x] CHANGELOG.md updated - [x] I understand every change in this PR and can explain its design, risks, and validation. - [x] I reviewed and tested any meaningful tool-generated output included in this PR. - [x] Every non-bot, non-merge commit has a matching Signed-off-by trailer. --------- Signed-off-by: Joshua J. Bouw <jjb@unicity-labs.com> Co-authored-by: Joshua J. Bouw <jjb@unicity-labs.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
bind-tcpis loopback-only[capabilities].net_bindauthoritynet_tcp_bindclaimsValidation
Related to astrid-runtime/astrid#1457.