@yiaany/ghostapi 0.1.7 → 0.1.8

package/docs/release-checklist.md

@@ -1,71 +1,83 @@
-# Release Checklist
-
-Use this checklist before publishing GhostAPI to GitHub or npm.
-
-## Metadata
-
-- `package.json` has the correct `name`, `version`, `description`, `license`, `bin`, `files`, `keywords`, and repository metadata.
-- `README.md` explains value, install, CLI, provider coverage, examples, safety, and contributing.
-- `CHANGELOG.md` has an entry for the release.
-- `LICENSE`, `SECURITY.md`, `CONTRIBUTING.md`, and `CODE_OF_CONDUCT.md` are present.
-
-## Local Verification
-
-```bash
-npm run typecheck
-npm test
-npm run build
-```
-
-Smoke check the built CLI:
-
-```bash
-node dist/cli/index.js --help
-node dist/cli/index.js providers list
-node dist/cli/index.js model get
-```
-
-Run local proxy smoke tests:
-
-```bash
-node dist/cli/index.js start --offline --port 8080
-```
-
-Then verify locally:
-
-```bash
-curl http://localhost:8080/health
-curl http://localhost:8080/dashboard
-curl -X POST http://localhost:8080/v1/customers -H "content-type: application/json" -d '{"email":"ada@example.com"}'
-curl http://localhost:8080/v1/customers
-curl -X POST http://localhost:8080/emails -H "content-type: application/json" -d '{"from":"dev@example.com","to":"ada@example.com","subject":"Hello"}'
-curl -X POST http://localhost:8080/2010-04-01/Accounts/AC123/Messages.json -H "content-type: application/x-www-form-urlencoded" -d "To=+15551234567&From=+15557654321&Body=Hello"
-```
-
-## Package Verification
-
-```bash
-npm pack --dry-run
-```
-
-Confirm the package includes only intended release files and does not include:
-
-- `.ghostapi/`
-- `.env`
-- `node_modules/`
-- local logs
-- test output
-
-## Safety Checks
-
-- GhostAPI does not make real provider API calls by default.
-- LLM usage requires explicit API key configuration and receives sanitized requests.
-- Dashboard events are sanitized.
-- Cache keys do not include raw secrets.
-- CLI user errors are actionable and do not print confusing stack traces.
-
-## Publish
-
-- Tag the release.
-- Push to GitHub.
-- Publish to npm only after package dry-run output has been reviewed.
+# Release Checklist
+
+Use this checklist before publishing GhostAPI to GitHub or npm.
+
+## Metadata
+
+- `package.json` has the correct `name`, `version`, `description`, `license`, `bin`, `files`, `keywords`, and repository metadata.
+- `README.md` explains value, install, CLI, provider coverage, examples, safety, and contributing.
+- `CHANGELOG.md` has an entry for the release.
+- `LICENSE`, `SECURITY.md`, `CONTRIBUTING.md`, and `CODE_OF_CONDUCT.md` are present.
+- [Release readiness matrix](release-readiness.md) and [migration/rollback guide](release-migration-and-rollback.md) are current for the proposed release.
+
+## Local Verification
+
+```bash
+npm run typecheck
+npm test
+npm run build
+npm run smoke:package
+```
+
+Smoke check the built CLI:
+
+```bash
+node dist/cli/index.js --help
+node dist/cli/index.js providers list
+node dist/cli/index.js model get
+```
+
+Run local proxy smoke tests:
+
+```bash
+node dist/cli/index.js start --offline --port 8080
+```
+
+Then verify locally:
+
+```bash
+curl http://localhost:8080/health
+curl http://localhost:8080/dashboard
+curl -X POST http://localhost:8080/v1/customers -H "content-type: application/json" -d '{"email":"ada@example.com"}'
+curl http://localhost:8080/v1/customers
+curl -X POST http://localhost:8080/emails -H "content-type: application/json" -d '{"from":"dev@example.com","to":"ada@example.com","subject":"Hello"}'
+curl -X POST http://localhost:8080/2010-04-01/Accounts/AC123/Messages.json -H "content-type: application/x-www-form-urlencoded" -d "To=+15551234567&From=+15557654321&Body=Hello"
+```
+
+## Package Verification
+
+```bash
+npm pack --dry-run
+```
+
+Confirm the package includes only intended release files and does not include:
+
+- `.ghostapi/`
+- `.env`
+- `node_modules/`
+- local logs
+- test output
+
+## Safety Checks
+
+- GhostAPI does not make real provider API calls by default.
+- Ambient `OPENAI_API_KEY` does not enable external LLM access.
+- LLM usage requires explicit opt-in plus `GHOSTAPI_LLM_API_KEY`, and receives sanitized requests.
+- Dashboard events are sanitized.
+- State and persisted event files do not contain secret fixtures used by security tests.
+- Cache keys do not include raw secrets.
+- Ordered request arrays produce distinct cache keys when their order changes.
+- Concurrent child-process state and behavior writes preserve all covered updates.
+- Persisted events rotate at 5 MiB and retain no more than two archives.
+- Non-loopback startup fails without a strong `GHOSTAPI_AUTH_TOKEN`; dashboard APIs and SSE reject missing tokens.
+- Generated tests honor `GHOSTAPI_BASE_URL` instead of requiring port 8080.
+- CLI user errors are actionable and do not print confusing stack traces.
+- GitHub workflows use least-privilege permissions and SHA-pinned actions.
+- Security claims match tests actually run on the target platform; Windows/macOS local simulation is not Linux enforcement evidence.
+- Any full-audit findings have a documented owner and remediation plan.
+
+## Publish
+
+- Tag the release.
+- Push to GitHub.
+- Publish to npm only after package dry-run output has been reviewed.

package/docs/release-migration-and-rollback.md

@@ -0,0 +1,63 @@
+# Release Migration And Rollback
+
+Last reviewed: 2026-08-08.
+
+This guide covers the published local `@yiaany/ghostapi` package. The separate `hosted/` pilot is not part of the npm package and has no production migration or rollback approval.
+
+## Before Upgrade
+
+1. Read the target `CHANGELOG.md`, `SECURITY.md`, platform limitations, and package contents.
+2. Keep the project policy and scenarios under normal source control only if they contain no sensitive data. `.ghostapi/` can contain local simulation data and evidence; do not upload it as a generic backup.
+3. If a local backup is needed, make an access-controlled copy of only the required `.ghostapi/` files and review it for secrets before transferring it.
+4. Run `ghostapi doctor --json`. On Windows and macOS, use `ghostapi start --open` for local simulation; do not expect `ghostapi run` enforcement.
+
+## Upgrade
+
+```bash
+npx @yiaany/ghostapi@<version> init
+npx @yiaany/ghostapi@<version> doctor --json
+```
+
+`init` does not overwrite existing setup files. Review generated setup guidance rather than replacing local policy or agent instructions blindly.
+
+For a source checkout, install the pinned lockfile and run:
+
+```bash
+npm ci
+npm run typecheck
+npm test
+npm run build
+npm run smoke:package
+```
+
+On supported Linux runners, also run the selected enforced workflow and generate a sanitized evidence report. A successful Windows/macOS local simulation must not be used as substitute evidence for Linux namespace enforcement.
+
+## Rollback
+
+1. Stop the local GhostAPI process or CI job.
+2. Reinstall the previously reviewed package version or return the source checkout to the previously reviewed commit using the repository's normal non-destructive deployment procedure.
+3. Re-run `ghostapi doctor --json` and the same local smoke or CI workflow used before the upgrade.
+4. Preserve only sanitized evidence needed to explain the rollback. Do not attach raw traffic, secrets, source code, or local data directories to an issue.
+5. If a local data schema rejects an older runtime, do not hand-edit or delete data in place. Work on an access-controlled copy, report the exact version/error through the security or maintainer channel, and retain the original until a recovery path is reviewed.
+
+## Rollback Scope
+
+- The current local runtime has no account, hosted entitlement, billing state, or remote control plane to roll back.
+- `ghostapi telemetry disable` removes the optional local aggregate; it is not a product-version rollback tool.
+- Local file locks coordinate cooperating processes on one filesystem only. Do not attempt a rollback while concurrent GhostAPI processes write the same data directory.
+
+## Release Verification
+
+Run these on the proposed release commit:
+
+```bash
+npm ci
+npm run typecheck
+npm test
+npm run build
+npm run smoke:package
+npm pack --dry-run
+npm audit --omit=dev
+```
+
+Also review the package file list, tracked-source secret scan, direct runtime dependency licenses, GitHub workflow permissions/action pins, and the known gaps in [release readiness](release-readiness.md). Both the production-only and full dependency audits must pass for this release.

package/docs/release-readiness.md

@@ -0,0 +1,39 @@
+# Release Readiness Matrix
+
+Last reviewed: 2026-08-22.
+
+This matrix is a release-candidate review, not a publication approval. No Git tag, GitHub release, or npm publication was created during this review.
+
+| Feature | Platform / boundary | Guarantee level | Evidence reviewed | Known gap | Owner before release |
+| --- | --- | --- | --- | --- | --- |
+| Local provider simulation, dashboard, MCP | Node.js on Windows and Ubuntu WSL2 | Local simulation only; no real provider calls by default. | Final 0.1.8 root lint and typecheck; 55 files and 341 tests with zero skipped; build; packed-package smoke; full and production audits with zero vulnerabilities. | GitHub Actions has not yet been observed on the exact final pushed commit. | Maintainer: retain the exact-commit CI results before publication. |
+| `ghostapi run` | Linux only when `unshare` and `ip` preflight pass | Loopback-only user/mount/network/PID namespace; fail closed. Not a hostile-code filesystem sandbox. | Native Ubuntu WSL2 enforcement suite passed 12 of 12 tests with zero skipped on 2026-08-22, exercising the Linux namespace boundary. Earlier 0.1.7 WSL evidence remains historical. | Local WSL2 evidence is not a substitute for GitHub Actions on the exact final commit. | Maintainer: observe the pinned workflow after push and retain sanitized evidence. |
+| Policy parser | Local YAML input | Bounded, one-document, no anchors/aliases/interpolation, path-contained parsing. | Unit tests plus 400 deterministic malformed-input cases. | Fuzz corpus is deterministic regression coverage, not a replacement for long-running fuzzing. | Maintainer: extend corpus when syntax support changes. |
+| Evidence reports | Local files and explicit `--run` input | Bounded report/run input, secret redaction, canonical logical hash, fail-closed CI result. | Evidence tests include corruption, traversal, terminal escapes, malformed and oversized run evidence. | Same-user filesystem TOCTOU remains outside the local lock/store threat boundary. | Maintainer: document/assess before any shared filesystem support. |
+| Record/replay and contract import | Local JSON/HAR/OpenAPI input | Bounded JSON only; archives, remote refs, symlinks, unsafe hosts, redirects, and secret-bearing bundles reject. | Scenario and contract suites; deterministic malformed-input coverage. | Sanitization is heuristic and requires operator review before sharing. | Maintainer: maintain provider/sanitizer regression fixtures. |
+| Provider packs | Local runtime | Deterministic provider-shaped behavior; unsupported endpoints fail diagnostically. | Stripe lifecycle/conformance tests and provider tests. | Fidelity remains limited to implemented capabilities, not live-provider parity. | Pack maintainer: add conformance before widening claims. |
+| Root CI workflow | GitHub Actions | Read-only repository token and SHA-pinned actions. | Workflow regression coverage is included in the final root suite; workflow definitions include lint/typecheck/test/build/package/audit, hosted, Docker, and Linux enforcement checks. | The workflows still must be observed on the exact final commit after push. | Maintainer: review and retain the GitHub run before publication. |
+| Hosted pilot | Separate Bun/Elysia codebase, implemented but not deployed | Code-level tenant authorization, role checks, bounded request handling, hashed one-time secrets, durable quotas, idempotency, outbox/worker retries, dead-letter state, retention cleanup, readiness checks, and audit metadata. No live-service guarantee. | Clean hosted install; typecheck; 26 tests with zero skipped, including cloned auth-request body bounds; Bun build; zero-vulnerability audit; local non-root Docker image build; migrations `001`-`004` applied to PostgreSQL 17; concurrent organization quota race passed. | No staging deployment; live Google OAuth, Redis, QStash, sustained load, failover, and disaster-recovery behavior remain unproven. | Hosted owner: complete operational gates before any pilot use. |
+| Product telemetry | Local runtime | Disabled by default, aggregate-only, no network transport; opt-out deletes local aggregate. | Product telemetry tests and package smoke. | Not a hosted/team analytics system. | Product owner: obtain explicit partner need before any networked design. |
+
+## Threat Model Delta Since Session 06
+
+- The old proxy-guidance-only model is now explicitly separated from Linux `ghostapi run` enforcement. Unsupported platforms fail closed instead of treating proxy configuration as isolation.
+- Process execution now creates bounded lifecycle evidence, strips secret-shaped target environment values, limits target output, and records only aggregate output-secret/limit signals.
+- Policy, scenario, contract, evidence, replay, and hosted report inputs have bounded parsers and reject traversal, symlink, archive, remote-reference, unsupported-schema, or secret-bearing inputs where applicable.
+- Root CI now explicitly uses `contents: read`; the PR safety workflow remains SHA-pinned, artifact-bounded, and avoids executing fork code in its write-comment job.
+- The hosted pilot now implements bounded request parsing, explicit tenant/role authorization, exact-origin mutation checks, one-time hashed invitation and ingest secrets, durable quotas, worker/outbox retry limits, dead-letter handling, retention cleanup, security headers, and dependency-aware readiness. These are locally tested implementation claims, not evidence of a deployed service.
+
+## Open P2 Items
+
+| Item | Plan | Owner |
+| --- | --- | --- |
+| GitHub Actions on the exact final commit is still required before publication. | Push the final commit, observe every required pinned workflow and job, and retain the run plus sanitized evidence links. | Maintainer. |
+| Hosted staging and migration rehearsal are incomplete. | Deploy an isolated staging environment and apply the four application migrations plus the pinned Better Auth migration against production-shaped PostgreSQL; verify rollback/forward-recovery procedures and tenant authorization. | Hosted owner. |
+| Hosted load and queue behavior are unproven. | Exercise production-shaped sustained/burst load, Redis rate limits, QStash signature validation/redelivery, outbox leases, worker retries/dead letters, and backlog drain behavior with measured thresholds. | Hosted owner. |
+| Hosted disaster recovery is unproven. | Run repeated backup/restore and regional dependency-failure drills; record measured RPO/RTO instead of claiming the architectural targets. | Hosted owner. |
+| Live OAuth and operational secret/configuration paths are unproven. | Validate Google OAuth redirect/origin configuration, session expiry/rotation, account-linking restrictions, secret rotation, and failure behavior in staging. | Hosted owner. |
+
+## Release Gate
+
+The root local package passed the final local 0.1.8 verification recorded in [the 0.1.8 verification record](development/verification-0.1.8.md). Publication still requires observing GitHub Actions on the exact final commit after push. Do not claim a deployed hosted service, completed hosted operational readiness, Linux enforcement on Windows/macOS, or billing availability from this matrix.

package/docs/security/action-gateway-threat-model.md

@@ -0,0 +1,34 @@
+# Synthetic Action Gateway Threat Model
+
+## Scope
+
+The Session 23 action gateway is a local, data-only implementation of the shared action contract. Its only executor is `ghostapi-synthetic`, which mutates an existing local synthetic world. It has no provider HTTP client, credential input, environment-secret lookup, account configuration, shell execution, webhook delivery, or cloud transport.
+
+It is not a production gateway. Real provider accounts, credentials, sandbox accounts, provider calls, external messages, money movement, deployments, and deletes are out of scope until the Session 23 entry gate has documented design-partner requirements, a separate test account, an approved threat model, and explicit owner authorization.
+
+## Trust Boundaries
+
+- Agent input: `ActionEnvelope` is untrusted data and is strictly schema-validated.
+- Approval input: `ActionApproval` is structured data bound to the canonical SHA-256 action hash and carries Ed25519 provenance from an injected trusted key. A boolean approval, unsigned JSON, unknown key ID, or invalid signature is not accepted.
+- Policy input: the current local policy is loaded again at submit and execute; its version and SHA-256 source hash must match the approved envelope.
+- Identity input: the execution actor/workload pair must match the approved envelope immediately before side effect.
+- Persistence: action records use a private local directory, per-action lock, atomic replacement, regular-file checks, byte bounds, and receipt-chain validation. This coordinates cooperating local processes only; it is not protection from a malicious same-user actor who can alter both state and runtime.
+- Synthetic adapter: execution delegates only to the existing atomic synthetic-world workflow. It has no ambient network or credential capability.
+
+## Invariants
+
+- Canonical serialization sorts object keys and preserves array order. Any argument change changes the action hash and invalidates approval.
+- An approver cannot equal the action actor or workload identity.
+- Approval provenance is verified at submission and re-authenticated from the persisted approval immediately before execution. A missing or unavailable verifier fails closed.
+- Action expiry, approval expiry, policy reference, actor identity, adapter support, and idempotency state are checked immediately before execution.
+- Inbox-issued approvals additionally require verifier-backed durable inbox consumption state; possession of artifact JSON or a trusted public key alone does not authorize gateway execution.
+- Receipts distinguish `requested`, `attempted`, `committed`, `verified`, and `failed`. Each receipt hashes the prior receipt hash plus its canonical content.
+- An `attempted` action is reconciled with `verify` before any subsequent execution. A failed reconciliation is an unknown outcome and is never automatically retried.
+- Duplicate action IDs with a changed envelope or approval are rejected. A verified or committed action returns its existing receipt without another synthetic side effect.
+- Unsupported operations and unsupported compensation fail visibly. The API uses `compensate`, never `rollback`; the current synthetic adapter exposes no compensation.
+
+## Remaining Limits
+
+- Policy schema v1 does not yet express action-level authorization. The gateway rechecks the approved policy version/hash to prevent stale-policy execution; a later production policy extension must add an explicit action decision before exposing a non-synthetic adapter.
+- Local receipt chaining is tamper-evident only while the local store and runtime are trusted. It is not an externally immutable ledger or a legal audit record.
+- A future provider adapter must provide provider-specific idempotency proof, safe reconciliation for timeout ambiguity, credentials held behind a broker/gateway boundary, scoped grants, kill-switch/budget checks, durable audit evidence, and explicit compensation semantics before it can execute any real side effect.

package/docs/security/action-ledger-incident-replay-threat-model.md

@@ -0,0 +1,42 @@
+# Local Action Ledger And Incident Replay Threat Model
+
+## Scope
+
+The local action ledger is a typed API for turning an already persisted synthetic action record into a tenant-scoped, append-only timeline. It records hashes and bounded structured facts for intent, identity, policy decision, approval, credential-grant reference, attempts, provider receipt, verification, compensation status, and governance events.
+
+It does not add a provider client, provider account, credential vault, HTTP transport, production execution path, production credential, hosted audit service, legal/compliance service, or immutable external storage. The current incident pipeline turns a ledger action into one local deterministic synthetic world plus one data-only scenario bundle. Replay uses the existing in-memory `ScenarioReplayer`; it makes no network request and cannot use original credentials.
+
+## Integrity And Privacy
+
+- Each tenant has its own SHA-256 genesis hash and ordered hash chain. Every entry binds its tenant, sequence, timestamp, action reference, stage, structured fields, and previous hash.
+- Tenant metadata stores the current entry count and head hash. Verification detects modified content, reordered entries, removed entries, invalid links, and a mismatched head/count.
+- The store is bounded, strict-schema validated, regular-file/non-symlink checked, serialized with the existing local file lock, and atomically replaced.
+- Ledger values are scalar-only. Raw arguments, payloads, authorization, cookies, tokens, secret/password fields, email, phone, address, card, and body/payload fields are rejected. Action/resource/provider references are persisted only as stable IDs or SHA-256 hashes where the identifier could expose sensitive data.
+- Export verifies the requested tenant chain first and returns entries only for the tenant authorized by the injected access authorizer. It contains no credential material or raw action payload.
+
+## Outcome Semantics
+
+- A `verified` ledger stage is emitted only from a gateway `verified` receipt.
+- A failed receipt with `unknown_outcome` becomes `ambiguous` and `requires_reconciliation`; it is never relabeled successful.
+- A committed receipt without a verified receipt remains unverified. The incident fixture reproduces this distinction locally with `409 requires_reconciliation` rather than inventing success.
+- Credential use is a reference only: `grantIdHash`, credential version, or `not_used`. The ledger never receives or exports the underlying secret.
+
+## Retention, Hold, And Deletion
+
+- `configureRetention()` records a per-tenant retention policy. `appendEntry` enforces the store bound (`MAX_ENTRIES` 2,000): when the cap is reached, entries older than the tenant's `retentionDays` are rotated out and the tenant's hash chain is relinked to genesis — `previousHash`/`entryHash` are recomputed and `entryCount`/`headHash` updated, so a subsequent `verifyTenant` still passes. Rotation is bounded and never silent at the cap: if the store cannot be brought under `MAX_ENTRIES`, the append is rejected with an explicit retention-review error.
+- Rotation is per-tenant and opt-in: a tenant without a `retentionDays` policy is never rotated (its chain remains strictly append-only), and a tenant under `setLegalHold(true)` is never rotated.
+- `setLegalHold(true)` records an active local hold and blocks `requestDeletion()`.
+- `requestDeletion()` records a request timestamp after the hold check. It does not erase entries, backups, or external copies and does not claim GDPR, SEC, HIPAA, or any other compliance behavior.
+- A real retention/deletion workflow needs an approved retention schedule, backup lifecycle, legal authority, trusted identity, durable external evidence, and a cryptographically preserved anchor before destructive deletion can be designed.
+
+## Claimed Basis And Verification
+
+- `policy_decision` and `approval` stages echo caller-supplied decisions as `basis: "caller_claimed"` — they record what the caller asserted at admission time, not an independently verified policy/approval decision, and consumers must treat them as claims.
+- `verifyTenant()` returns `tracked: false` with the tenant's genesis hash as head for a tenant that has no entries, and `tracked: true` for a tenant with entries, so "no ledger yet" is distinguishable from a broken or tampered chain.
+
+## Trust Boundaries And Limits
+
+- `LedgerAccessAuthorizer` is injected. The default authorizer denies everything. Test capability helpers are only local test utilities, not authentication or tenant isolation for a deployed service.
+- Tenant isolation applies to calls that go through a correct injected authorizer. A malicious same-user actor who can replace the local state file and runtime is outside this local filesystem model.
+- The chain is tamper-evident, not absolutely immutable. It does not defend against a compromised host, altered application code, deleted backups, an attacker who replaces both data and trusted head/anchor, distributed filesystems, or a dishonest clock.
+- Sanitization is structural and pattern-based. Operators must inspect incident fixtures before sharing them; GhostAPI does not guarantee perfect anonymization.

package/docs/security/approval-inbox-threat-model.md

@@ -0,0 +1,35 @@
+# Local Approval Inbox Threat Model
+
+## Scope
+
+The approval inbox is a local typed API for the existing `ghostapi-synthetic` action adapter. It does not enable production providers, credentials, deployments, money movement, email, Slack, webhooks, browser approval links, or external notifications.
+
+An approval request is derived from a strict action envelope and its canonical SHA-256 hash. The action's risk is derived by the inbox taxonomy, never accepted from the agent as mutable input. The current synthetic operation maps to `update`; the taxonomy also reserves `read`, `create`, `communicate`, `money_movement`, `delete`, `permission_change`, and `deployment` for future reviewed action contracts.
+
+## Policy And Display
+
+An approval policy can restrict environment, actor, resource, amount, confidence, and action velocity. It defines an expiry and escalation timeout. A request exposes its normalized arguments, exact target, expected effects, reversibility, amount availability/value, policy reason, evidence hash, and successful synthetic preflight result. Missing amount evidence fails a policy that sets a maximum amount.
+
+## Approval Invariants
+
+- Requests, decisions, artifacts, and audit records are strict schema-v1 local data under `.ghostapi/approvals.json`.
+- Approver identities come from an injected verifier and include a verified stable `principalId`. Unverified caller-shaped objects fail closed.
+- An action actor/workload cannot approve its own action through its approver ID, verified principal ID, or independence key.
+- Critical risks or low confidence require distinct verified principals and `independenceKey` values; aliases cannot satisfy two-person approval.
+- Approval artifacts are action-hash-bound, one-time, expiring, and carry Ed25519 provenance from a durable approval-authority key. They are consumed under the inbox lock before execution starts; resumption never issues or consumes a second artifact.
+- The gateway verifies the signature at submission and again from the persisted record at execution. Inbox artifacts also require verifier-confirmed durable request state with the same request ID, action hash, artifact, and `consumedAt`; the request must be `executing`, or already `executed` with a linked receipt hash. Returning an already completed result additionally requires the inbox's stored receipt hash to match the gateway's durable verified receipt. A gateway configured with only the signing authority's public key cannot execute an inbox artifact.
+- Rejection, revoke, timeout, expiry, policy drift, changed action, or changed execution identity deny execution.
+- Edit-and-resubmit supersedes the prior request and requires a changed canonical action hash.
+- The inbox rechecks the policy at execution and then delegates only to the existing action gateway, which repeats provenance/action/approval/policy/identity/idempotency checks before its synthetic side effect.
+- Every approval transition and verified action receipt are connected through one local SHA-256 audit chain. Local chains are tamper-evident only under the existing filesystem trust model.
+
+## Race And Recovery
+
+The inbox serializes approval state and artifact consumption with one private file lock. A revoke that acquires the lock first prevents the side effect; an execution that has consumed the artifact first cannot be revoked as if it were still pending. If the process stops after durable `consumedAt`/`executing` state, recovery resubmits the identical signed artifact and delegates to the gateway's receipt chain. A `requested` receipt continues normally only while the action and approval remain valid; an `attempted` or `committed` receipt can be reconciled after expiry because no new attempt is permitted, and a `verified` receipt is returned without another side effect. The inbox changes to `executed` only after linking that verified receipt hash into its audit chain. Repeated recovery and calls after completion return the same verified receipt. A durable gateway `failed` receipt makes the inbox terminally `execution_failed`; an absent receipt or ambiguous attempted outcome remains `executing` and fail-closed rather than being replayed. Artifact data, local hashes, and filesystem write access are not sufficient to mint new valid approvals without the private signing key. Key rotation is explicit through trusted key IDs; unavailable or unknown verifiers deny recovery and execution.
+
+## Remaining Limits
+
+- The inbox is an API, not a hosted UI or notification channel. Slack/email text must never become an approval source of truth.
+- Signing keys are injected; GhostAPI does not generate, escrow, rotate, or recover durable production key material. Operators must keep private keys outside the data directory and distribute only trusted public keys to executors.
+- There is no authentication transport, RBAC service, trusted OIDC integration, external immutable audit sink, real clock authority, policy engine for production action classes, or real provider executor.
+- A future production integration requires an independently deployed identity/approval authority, provider-specific impact schema, policy authorization, credential broker, kill switch, budgets, durable audit evidence, timeout reconciliation, and compensation semantics.

package/docs/security/credential-broker-threat-model.md

@@ -0,0 +1,52 @@
+# Credential Broker And Workload Identity Threat Model
+
+## Scope
+
+The credential broker is a local typed library for a future execution gateway. It does not expose a CLI, MCP tool, HTTP endpoint, environment-variable loader, provider SDK, or credential-return API. The agent/workload never receives upstream secret material through arguments, stdin, environment variables, logs, reports, grants, receipts, or persisted broker metadata.
+
+Only server-side execution can read a secret. A caller presents a verified workload identity, a short-lived grant, and an exact action reference. The broker reads secret bytes from an injected vault boundary, passes them directly to an injected server-side executor, then zeroes the temporary byte buffer in a `finally` block. It returns a receipt, never the secret or a bearer token.
+
+The included `test-memory-vault`, test executor, workload verifier, action-receipt verifier, and break-glass authorizer exist only for automated tests. They have no network, provider, environment-secret, account, or production side-effect capability. A real integration must supply an existing reviewed vault/KMS adapter and a separately reviewed provider executor; GhostAPI does not implement encryption, key wrapping, or a provider credential protocol.
+
+## Secret Lifecycle
+
+1. Provisioning: an operator registers non-secret metadata: tenant, project, environment, provider, owner workload binding, scope allowlist, expiry, and opaque vault reference. The vault owns secret creation and storage.
+2. Storage: GhostAPI stores only metadata, grant metadata, and use receipts in `.ghostapi/credential-broker.json`. It rejects unknown fields, symlinks, oversized state, secret-shaped identifiers, and plaintext secret fields. A vault reference is not secret material and must not encode a secret.
+3. Use: an authenticated workload requests a server-only grant for one exact action ID, action hash, and verified action receipt hash. The broker persists `executing` before vault/provider I/O, then rechecks workload, tenant/project/environment, provider, scopes, credential status, grant status, expiry, and action reference immediately before vault access and through an executor-provided guard immediately before its side effect.
+4. Rotation: rotation replaces the opaque vault reference, increments the credential version, and revokes every outstanding grant. It does not touch local synthetic worlds, so local simulation stays available.
+5. Revocation: credential revocation marks the credential and all active grants revoked without waiting for vault/provider I/O. New execution attempts and an executor's final active check are denied before a later side effect.
+6. Audit: broker state records action-linked grant metadata and bounded execution receipts. It never stores the secret, a raw provider request, or an executor response body.
+7. Recovery: failures before the provider executor begins receive `failed`; any executor error receives `unknown` because a side effect may already have happened. Neither is retried automatically. Provider-specific reconciliation and duplicate-side-effect handling remain required before a real executor is enabled.
+
+## Workload Identity
+
+Schema-v1 workload identities distinguish `agent_run`, `ci_job`, and `production_service`. Each identity binds tenant, project, environment, workload ID, subject ID, run ID, issue time, and expiry. The broker accepts an identity only through an injected verifier; unverified caller-shaped objects fail closed.
+
+The identity verifier can additionally report whether an owner workload remains active. `listOrphanedCredentials()` returns non-revoked credentials whose owner workload binding is no longer active, so an operator can revoke or rotate them. It does not automatically broaden, transfer, or delete access.
+
+## Invariants
+
+- The grant audience is always `ghostapi-server`; no grant is valid for an agent process.
+- A grant is bounded to one tenant, project, environment, workload kind/ID, provider, sorted scope list, credential version, TTL, and exact action receipt.
+- Standard grants last at most 15 minutes. Break-glass grants require an independent trusted authorizer and last at most 5 minutes.
+- Credential metadata and secret material are separate interfaces. Metadata cannot reconstruct the upstream value.
+- Broker and executor both enforce scope. The executor rejects unsupported scope even if a caller somehow reaches it after broker validation.
+- The executor must call its supplied `assertActive()` immediately before its provider side effect; a future adapter that cannot honor this contract is unsupported.
+- A rotated credential invalidates old grants through both revocation and version mismatch. A revoked or expired grant is rejected even when an old request is replayed.
+- Cross-tenant, project, environment, workload, scope, audience, action, and receipt mismatch all fail closed before secret access.
+- A provider executor must create an action-linked receipt. The current test executor has no real provider capability.
+
+## Break-Glass
+
+Break-glass is disabled by default. An implementation must use a trusted human-controlled approval system that validates a short-lived structured approval bound to the exact action ID/hash/receipt. The approver cannot equal the workload subject or workload ID. The broker stores only approval ID, approver ID, and bounded reason in the grant; it does not store an approval token.
+
+## Crash And Memory Limits
+
+Node.js does not offer a universal guarantee that secret bytes are absent from every process snapshot, heap copy, debugger, or OS crash dump. The broker minimizes exposure by avoiding strings, logs, environment variables, arguments, persistence, and return values; it uses a temporary `Uint8Array` and clears that buffer after executor completion or failure. Operators must still disable or protect crash/core dumps, debugger attachments, and untrusted process inspection in any real deployment.
+
+## Remaining Limits
+
+- This is not a production vault, KMS, HSM, hosted identity provider, approval inbox, provider client, or production action gateway.
+- Local JSON storage is coordination and tamper detection only under the existing single-user filesystem trust model; it is not immutable audit storage.
+- Revocation can stop execution before the executor's final active check, but it cannot undo a provider side effect that already crossed that check; a real provider integration still needs provider idempotency and reconciliation.
+- A real provider executor needs its own test-account gate, provider idempotency/reconciliation proof, action-level policy decision, kill switch, budgets/velocity controls, durable audit sink, timeout ambiguity handling, and compensation semantics before any real side effect is enabled.

package/docs/security/egress-threat-model.md

@@ -0,0 +1,126 @@
+# Egress Threat Model
+
+Last verified: 2026-08-06.
+
+## Security Claim
+
+GhostAPI 0.1.x includes a Linux-only `ghostapi run` backend that starts a command in fresh user, mount, network and PID namespaces with loopback only. It provides a fail-closed default-deny network boundary only after local `unshare`/`ip` preflight succeeds. `ghostapi doctor --egress` reports `NO PROCESS LAUNCHED`: it is a capability report, not proof that a specific run was isolated.
+
+Changing an SDK base URL, setting `HTTP_PROXY`, or instructing an agent to use GhostAPI is useful **accidental safety**. It is not a hostile-code sandbox and is not evidence that production egress was impossible.
+
+No design in this document claims protection from an administrator/root-equivalent actor, a compromised host, or a malicious process with control of the same user account outside a future containment boundary.
+
+## Assets And Security Goals
+
+- Prevent accidental calls to production providers while developers and AI agents test code.
+- Make attempted allowed and blocked connections attributable to one `ghostapi run` execution.
+- Prevent direct IP, alternate DNS, UDP/QUIC, local-network and subprocess bypasses when a supported enforcement backend is active.
+- Fail closed when the requested guarantee cannot be established.
+- Avoid persistent, system-wide proxy, DNS, routing, firewall or daemon state.
+
+## Threat Actors
+
+| Actor or path | Proxy guidance | Process/container enforcement target |
+| --- | --- | --- |
+| Incorrect application code | Usually caught only when it uses the configured local base URL. | Deny all non-explicit network paths. |
+| AI agent creates another HTTP client | Bypasses guidance. | Same child process remains constrained. |
+| `curl`, shell command, or subprocess | Bypasses guidance. | Descendants must remain in the containment boundary. |
+| Direct IP address | Bypasses hostname-based proxy/DNS policy. | No route/socket path unless explicitly allowed. |
+| Custom DNS resolver or DoH | Bypasses configured resolver assumptions. | Resolver traffic is denied with all other network traffic. |
+| UDP or QUIC | Often bypasses HTTP-only controls. | All socket families and protocols are denied by the boundary. |
+| Local-network target | Often omitted from production-focused allowlists. | Deny by default; allow only deliberate loopback transport. |
+| Malicious same-user process | Out of scope for guidance. | Cannot be contained by a boundary it does not enter; same-user hostile code is not a guarantee from Node permission flags. |
+
+## Guarantee Levels
+
+### HTTP Proxy Guidance
+
+GhostAPI configures or documents a local HTTP endpoint and can collect only traffic voluntarily sent there. It can reduce accidental provider calls, but cannot prevent a different HTTP library, an IP literal, custom DNS, subprocess, UDP/QUIC, or local-network request.
+
+This is the active guarantee on platforms without the Linux backend and when a Linux preflight fails.
+
+### Process-Level Enforcement
+
+A process launcher creates an OS-supported restricted execution boundary and starts the target only after a local preflight passes. The future boundary must cover children and inherited handles, deny all network by default, and expose GhostAPI through an intentionally configured loopback or private transport.
+
+On Linux, `ghostapi run -- <command>` now implements a loopback-only process boundary with fresh user, mount, network and PID namespaces. It does not transparently redirect provider TLS traffic and it does not support external network allowlist entries until a reviewed policy gateway exists.
+
+### Container Or Network-Namespace Enforcement
+
+The target runs in a separate container or network namespace with only loopback, no host networking, no privileged mode, and no mounted container-control socket. This can provide the strongest planned local guarantee, but still does not protect against the container runtime daemon, an administrator, a compromised host, or an explicitly reintroduced host-network path.
+
+This is not implemented in GhostAPI 0.1.x.
+
+### Unsupported Or Degraded
+
+If a native primitive is absent, a required privilege is unavailable, or GhostAPI has no reviewed launcher, the command must not claim isolation. It returns a clear degraded or unsupported result and recommends a reviewed container/VM backend where appropriate.
+
+## Platform Capability Model
+
+### Linux
+
+Linux network namespaces isolate network devices, IP stacks, routing tables, firewall state, sockets, and related networking resources. The Linux manual also documents that the kernel must be configured with `CONFIG_NET_NS`; namespace lifecycle can naturally clean up devices once the last process exits. [Linux network namespaces](https://man7.org/linux/man-pages/man7/network_namespaces.7.html)
+
+Implemented backend: an unprivileged parent performs local preflight, writes sanitized run evidence, and launches the target with fresh user, mount, network and PID namespaces. Only loopback is brought up and GhostAPI starts inside the namespace. The parent never creates a veth, route, firewall rule, proxy rule or global daemon. `--pid --fork --kill-child=SIGTERM` makes bootstrap termination kill the namespace init; when PID 1 exits, the PID namespace cannot retain target descendants. A preflight failure starts no target command.
+
+The boundary does not make arbitrary same-user code hostile-safe: a path-based UNIX socket already accessible to the same user, such as a Docker/Podman control socket, is not an IP route and can act as a privileged deputy. The backend does not mount a control socket itself, but it also does not yet construct a filesystem sandbox that hides every host socket.
+
+### Containers
+
+Docker documents `--network none` as a mode that creates only a loopback interface inside the container. [Docker none network driver](https://docs.docker.com/engine/network/drivers/none/)
+
+Planned backend: use an OCI runtime only when a bounded image/mount policy is available. `--network host`, privileged containers, mounted Docker/Podman sockets, and host credentials invalidate the intended boundary. GhostAPI will not start or configure a privileged daemon.
+
+### Windows
+
+Microsoft documents AppContainer as an isolation environment with network access granted only for explicitly allocated Internet, intranet, or server capabilities. [AppContainer isolation](https://learn.microsoft.com/en-us/windows/win32/secauthz/appcontainer-isolation)
+
+Planned backend: a per-run AppContainer or LPAC launcher with no network capabilities and a dedicated writable directory. GhostAPI does not create profiles or launch AppContainers today, and a normal Win32 child process is not constrained. A future implementation must clean up its profile deterministically without changing global Windows Firewall state.
+
+### macOS
+
+Apple's App Sandbox is entitlement-based and intended for signed application bundles, not a general-purpose wrapper for arbitrary developer shell commands. [App Sandbox](https://developer.apple.com/documentation/security/app-sandbox)
+
+Planned backend: use an explicit container or VM backend before claiming egress enforcement for arbitrary child commands. GhostAPI must not report `isolated` solely because proxy environment variables or a deprecated sandbox wrapper exists.
+
+### Node.js Runtime
+
+Node's Permission Model is activated with `--permission`; a launched Node process without `--allow-net` is denied network access. Node explicitly describes the model as a seat belt for trusted code and says it does not provide security guarantees against malicious code. [Node.js Permissions](https://nodejs.org/api/permissions.html)
+
+GhostAPI reports this as a degraded auxiliary control only. It cannot contain non-Node children, is not the future `ghostapi run` hostile-sandbox boundary, and does not replace OS-level isolation.
+
+## Capability API And CLI Contract
+
+```bash
+ghostapi doctor --egress
+ghostapi doctor --egress --json
+```
+
+The JSON report is offline and deterministic apart from local runtime facts. It contains:
+
+- `schemaVersion` for machine consumers.
+- `isolated`, which is currently always `false`.
+- `currentGuarantee`, currently `http-proxy-guidance`.
+- Platform/runtime facts and one record per possible backend.
+- Backend status: `available`, `degraded`, `not-implemented`, or `unsupported`.
+- Required privileges/setup and remaining bypasses.
+- A `globalStateChanged: false` invariant.
+
+The diagnostic command does not open a network connection, change proxy settings, add firewall rules, create network namespaces, create an AppContainer profile, or contact a container daemon. `ghostapi run` performs the Linux namespace preflight and creates only child-owned namespaces.
+
+## Minimal Cross-Platform Architecture
+
+1. A platform-neutral policy compiler canonicalizes the allow/deny policy, local GhostAPI transport, command arguments, and run ID.
+2. An unprivileged parent creates evidence and validates the selected backend before spawning the target.
+3. The Linux backend implements `prepare`, `spawn`, lifecycle evidence and namespace cleanup; Windows AppContainer/LPAC and an explicit OCI/VM runner remain future reviewed backends.
+4. Each backend owns its resources by process or container lifetime. Crash cleanup relies on resource ownership, with bounded reconciliation only for leftovers that can be safely identified by a run-specific marker.
+5. A per-run recorder emits attempted connection metadata and a signed/finalized local evidence artifact. It must distinguish a setup failure from a blocked request and an unknown outcome.
+6. A backend that cannot prove the requested guarantee returns `unsupported` or `degraded`; it never silently falls back to proxy guidance for a command advertised as isolated.
+
+## Non-Goals For The First `ghostapi run`
+
+- Global firewall, global proxy, global DNS, hosts-file, routing-table, or system service changes.
+- Transparent interception of another user's process.
+- Protection from root/administrator, the host kernel, or a compromised container runtime.
+- Hidden installation of a privileged daemon.
+- A claim that Node permissions sandbox hostile code.