Security

Byspec v1 does not sandbox command checks. A command or test check runs whatever the spec says, as your user, in the repository, limited only by a timeout and an environment allowlist (PATH, HOME, NODE_OPTIONS, CI, GITHUB_*, BYSPEC_*, AWS_*, plus the check's own env). Only verify specs you trust. Sandboxed execution is what the v2 cloud control plane adds: there, checks run in a CodeBuild container that can reach only S3, CloudWatch Logs, and Bedrock.

Other properties: all file access is jailed to the repository root, including through symlinks; evidence files are written with mode 0600; the judge never receives the parent environment, git remotes, or paths outside its declared evidence; secrets in your environment do not leak into evidence; there is no telemetry and no network traffic other than the configured provider.

Source: README.md § Security

• Child processes run with the allowlisted env (Section 8.5). Secrets in the parent environment do not leak into evidence.
• Evidence files are written with mode 0600.
• core/fs.ts rejects any resolved path outside the repo root, including through symlinks (fs.realpath both sides).
• The judge never receives the parent environment, git remotes, or file paths outside declared evidence.
• v1 provides no sandboxing of command checks beyond timeouts and env allowlisting. The README MUST say so plainly. Sandboxing is the CodeBuild layer in v2.
• No telemetry. No network calls other than the configured provider.

Source: docs/byspec-implementation-spec.md § 17. Security

v1 answers "did the code satisfy the spec?" for a developer who runs the CLI. v2 answers it for a team without anyone running anything: a GitHub App verifies every pull request in an isolated sandbox, records verdicts in a tenant-scoped, KMS-signed ledger, keeps evidence in S3, and posts a check run with per-criterion annotations. The CLI stays the way developers and agents work locally; the control plane is the way a CTO gets a ledger they did not have to operate.

Principles carried over from v1: rules before models, information hiding, the ledger is the product. Two more for v2:

1. The sandbox is the trust boundary. Command and test checks run untrusted code. In v2 they run in a CodeBuild container whose network reaches only the model provider and AWS, never the internet, with per-run caches so isolation does not cost a fresh install every run.
2. Same core, new shells. Every Lambda calls the same @byspec-dev/core functions the CLI calls. Cloud-only behaviour lives behind two interfaces added to core (Sandbox, LedgerStore) plus a Signer.

1.1 In scope for v2#

• Core interfaces: Sandbox (local), LedgerStore (jsonl, none), Signer (none, kms, ed25519-file). Signed ledger entries and signature verification (Section 4).
• http check type (Section 5).
• Evidence export packets, byspec export (Section 6).
• @byspec-dev/cloud: DynamoDB LedgerStore, S3 evidence store, KMS signer (Section 7).
• Control plane in SST v4 (Section 8): HTTP API, GitHub App webhook + manifest-setup flow, Step Functions run pipeline, two-stage CodeBuild sandbox, DynamoDB single table, S3 evidence bucket with SSE-KMS, EventBridge bus.
• GitHub check runs with per-criterion annotations and an evidence packet link (Section 9).
• Dogfood: the byspec repository installs its own GitHub App; every PR gets a Byspec check run.

1.2 Deferred to v2.1 (needs accounts the builder does not have)#

• Clerk auth, Stripe billing, Resend email, and a dashboard. Section 10 fixes the tenant model so these are additive.
• Custom domain api.byspec.dev (needs DNS delegation).

1.3 Non-goals#

Unchanged from v1 §1.3. v2 still does not review style, run tests itself, or write code.

Source: docs/byspec-v2-spec.md § 1. Goal