@yiaany/ghostapi 0.1.9 → 0.2.1

package/docs/providers/stripe-core-pack.md

@@ -1,82 +1,84 @@
-# Stripe Core Pack
-
-The built-in Stripe core pack is a deterministic local simulation for the most common payment workflows. It is not full Stripe compatibility and it never makes outbound network requests.
-
-## Version And Verification
-
-- Verified against Stripe's official API reference and Stripe Node SDK behavior on 2026-08-06.
-- GhostAPI compatibility API version: `2026-02-25.clover`.
-- Pack version: `1.1.0`.
-- Successful pack responses include `x-ghostapi-provider-pack: stripe@1.1.0`, `stripe-version: 2026-02-25.clover`, and a deterministic `request-id`.
-
-The version is an explicit GhostAPI compatibility contract, not a claim that all live Stripe endpoints or fields are supported.
-
-## Supported Operations
-
-| Resource | Operations |
-| --- | --- |
-| Customers | Create, retrieve, update, delete, list |
-| Payment Intents | Create, retrieve, update, confirm, list |
-| Payment Methods | Create minimal `card` method, retrieve, list |
-| Checkout Sessions | Create, retrieve, list |
-| Refunds | Create, retrieve, list |
-| Products | Create, retrieve, update, list |
-| Prices | Create recurring or one-time prices, retrieve, update, list |
-| Subscriptions | Create, retrieve, update, cancel, local `renew` control, list |
-| Invoices | Retrieve, pay, void, list |
-| Events | List, retrieve, and local signed delivery |
-
-List endpoints return Stripe-shaped `{ object: "list", data, has_more, url }` responses and accept `limit`, `starting_after`, and `ending_before` cursors.
-
-The pack accepts form-encoded nested parameters such as `metadata[source]=sdk` and `line_items[0][price_data][unit_amount]=2500`, as emitted by the Stripe Node SDK. JSON bodies are accepted for direct local clients.
-
-## Determinism And State
-
-Objects receive deterministic IDs, timestamps, and request IDs when a fixed runtime clock and ID generator are injected in tests. Normal runtime IDs remain unique across requests. Stateful requests run under GhostAPI's local atomic state transaction; the pack does not access storage itself.
-
-`Idempotency-Key` is represented only by a SHA-256-derived local digest in events and state. A repeated mutation with the same key and parameters returns the original response with `x-ghostapi-idempotency: REPLAY`. Reusing the key with different parameters returns a Stripe-shaped `idempotency_error`. Receipts expire after 24 hours, allowing a new mutation for the same key after the local retention window.
-
-## Billing Lifecycle
-
-Subscriptions use one recurring Price. Creating with `trial_period_days` creates a `trialing` subscription; `POST /v1/subscriptions/:id/renew` is a GhostAPI-only local test control that advances it. A normal renewal produces an Invoice, succeeded Payment Intent, and `active` subscription. `pm_card_chargeDeclined` produces a Stripe `card_error`, preserves an open Invoice, and sets the subscription to `past_due`; `POST /v1/invoices/:id/pay` can recover it. Cancellation marks the subscription `canceled`. Refunds create a `charge.refunded` event and update the local Payment Intent refund total.
-
-## Webhook Testing
-
-State transitions create persisted Stripe-shaped Events for subscription, invoice, payment-intent, and refund lifecycle changes. GhostAPI deliberately does not accept arbitrary webhook target URLs and never sends outbound webhook HTTP requests. Instead, tests pull a raw signed payload from:
-
-```text
-GET /v1/events/:event_id/deliver?delivery_mode=normal|duplicate|delayed|out_of_order|invalid_signature
-```
-
-The response includes `stripe-signature`, generated with HMAC-SHA256 over `timestamp.rawPayload`. The default local-only secret is `whsec_ghostapi_local_test_secret`; set `GHOSTAPI_STRIPE_WEBHOOK_SECRET` to use another test secret. The secret is not stored in state, events, scenarios, or responses. `duplicate` reliably returns the same event ID and payload on repeat calls, `delayed` accepts bounded `delay_ms` (0-10000), `out_of_order` reverses the event-list ordering, and `invalid_signature` corrupts the signature. Use the official `stripe.webhooks.constructEvent` verifier against the raw response body.
-
-Rate-limit (`429` + `Retry-After`), bounded delay/timeout simulation, and `5xx` behavior remain controlled through GhostAPI Fault Lab. These are injected before pack execution, so a client retry with an idempotency key exercises the normal atomic replay path after the fault is disabled.
-
-## Test Card Outcomes
-
-Use the Stripe test payment-method identifier `pm_card_chargeDeclined` (or legacy `tok_chargeDeclined`) when creating or confirming a Payment Intent to receive:
-
-```json
-{
-  "error": {
-    "type": "card_error",
-    "code": "card_declined",
-    "decline_code": "generic_decline"
-  }
-}
-```
-
-No PAN or CVC is required. If a direct client submits card-like fields, GhostAPI masks them before event or snapshot persistence. The returned synthetic Payment Method exposes only fixed non-sensitive card metadata such as `last4`.
-
-## Deliberate Limits
-
-- Disputes, Connect, payment links, Setup Intents, hosted Checkout, tax, proration, dunning, smart retries, and most Stripe APIs remain unsupported.
-- Unsupported operations return a diagnostic `invalid_request_error`; GhostAPI does not generate a fake success.
-- Checkout Sessions are local objects. Their returned URL is a local placeholder and not a hosted checkout page.
-- Payment Intent confirmation has a simplified state model: normal confirmation succeeds; the documented decline token fails.
-- Refunds support `payment_intent` or `charge` input, but only validate a referenced Payment Intent when one is supplied.
-- No live keys, PANs, CVCs, provider credentials, or real network traffic are retained or used.
-
-## Runnable SDK Example
-
-Start GhostAPI and run `examples/stripe-node/checkout-flow.mjs`. The example configures the official Node SDK with its documented host, port, protocol, and API-version client options, then verifies a locally delivered webhook using the SDK; no SDK source patch is required.
+# Stripe Core Pack
+
+The built-in Stripe core pack is a deterministic local simulation for the most common payment workflows. It is not full Stripe compatibility and it never makes outbound network requests.
+
+The locked compatibility lane exercises the official Stripe Node SDK `22.6.0`. Compatibility is version-scoped; it is not a guarantee for every SDK or Stripe API version.
+
+## Version And Verification
+
+- Verified against Stripe's official API reference and Stripe Node SDK behavior on 2026-08-06.
+- GhostAPI compatibility API version: `2026-02-25.clover`.
+- Pack version: `1.1.0`.
+- Successful pack responses include `x-ghostapi-provider-pack: stripe@1.1.0`, `stripe-version: 2026-02-25.clover`, and a deterministic `request-id`.
+
+The version is an explicit GhostAPI compatibility contract, not a claim that all live Stripe endpoints or fields are supported.
+
+## Supported Operations
+
+| Resource          | Operations                                                    |
+| ----------------- | ------------------------------------------------------------- |
+| Customers         | Create, retrieve, update, delete, list                        |
+| Payment Intents   | Create, retrieve, update, confirm, list                       |
+| Payment Methods   | Create minimal `card` method, retrieve, list                  |
+| Checkout Sessions | Create, retrieve, list                                        |
+| Refunds           | Create, retrieve, list                                        |
+| Products          | Create, retrieve, update, list                                |
+| Prices            | Create recurring or one-time prices, retrieve, update, list   |
+| Subscriptions     | Create, retrieve, update, cancel, local `renew` control, list |
+| Invoices          | Retrieve, pay, void, list                                     |
+| Events            | List, retrieve, and local signed delivery                     |
+
+List endpoints return Stripe-shaped `{ object: "list", data, has_more, url }` responses and accept `limit`, `starting_after`, and `ending_before` cursors.
+
+The pack accepts form-encoded nested parameters such as `metadata[source]=sdk` and `line_items[0][price_data][unit_amount]=2500`, as emitted by the Stripe Node SDK. JSON bodies are accepted for direct local clients.
+
+## Determinism And State
+
+Objects receive deterministic IDs, timestamps, and request IDs when a fixed runtime clock and ID generator are injected in tests. Normal runtime IDs remain unique across requests. Stateful requests run under GhostAPI's local atomic state transaction; the pack does not access storage itself.
+
+`Idempotency-Key` is represented only by a SHA-256-derived local digest in events and state. A repeated mutation with the same key and parameters returns the original response with `x-ghostapi-idempotency: REPLAY`. Reusing the key with different parameters returns a Stripe-shaped `idempotency_error`. Receipts expire after 24 hours, allowing a new mutation for the same key after the local retention window.
+
+## Billing Lifecycle
+
+Subscriptions use one recurring Price. Creating with `trial_period_days` creates a `trialing` subscription; `POST /v1/subscriptions/:id/renew` is a GhostAPI-only local test control that advances it. A normal renewal produces an Invoice, succeeded Payment Intent, and `active` subscription. `pm_card_chargeDeclined` produces a Stripe `card_error`, preserves an open Invoice, and sets the subscription to `past_due`; `POST /v1/invoices/:id/pay` can recover it. Cancellation marks the subscription `canceled`. Refunds create a `charge.refunded` event and update the local Payment Intent refund total.
+
+## Webhook Testing
+
+State transitions create persisted Stripe-shaped Events for subscription, invoice, payment-intent, and refund lifecycle changes. GhostAPI deliberately does not accept arbitrary webhook target URLs and never sends outbound webhook HTTP requests. Instead, tests pull a raw signed payload from:
+
+```text
+GET /v1/events/:event_id/deliver?delivery_mode=normal|duplicate|delayed|out_of_order|invalid_signature
+```
+
+The response includes `stripe-signature`, generated with HMAC-SHA256 over `timestamp.rawPayload`. The default local-only secret is `whsec_ghostapi_local_test_secret`; set `GHOSTAPI_STRIPE_WEBHOOK_SECRET` to use another test secret. The secret is not stored in state, events, scenarios, or responses. `duplicate` reliably returns the same event ID and payload on repeat calls, `delayed` accepts bounded `delay_ms` (0-10000), `out_of_order` reverses the event-list ordering, and `invalid_signature` corrupts the signature. Use the official `stripe.webhooks.constructEvent` verifier against the raw response body.
+
+Rate-limit (`429` + `Retry-After`), bounded delay/timeout simulation, and `5xx` behavior remain controlled through GhostAPI Fault Lab. These are injected before pack execution, so a client retry with an idempotency key exercises the normal atomic replay path after the fault is disabled.
+
+## Test Card Outcomes
+
+Use the Stripe test payment-method identifier `pm_card_chargeDeclined` (or legacy `tok_chargeDeclined`) when creating or confirming a Payment Intent to receive:
+
+```json
+{
+  "error": {
+    "type": "card_error",
+    "code": "card_declined",
+    "decline_code": "generic_decline"
+  }
+}
+```
+
+No PAN or CVC is required. If a direct client submits card-like fields, GhostAPI masks them before event or snapshot persistence. The returned synthetic Payment Method exposes only fixed non-sensitive card metadata such as `last4`.
+
+## Deliberate Limits
+
+- Disputes, Connect, payment links, Setup Intents, hosted Checkout, tax, proration, dunning, smart retries, and most Stripe APIs remain unsupported.
+- Unsupported operations return a diagnostic `invalid_request_error`; GhostAPI does not generate a fake success.
+- Checkout Sessions are local objects. Their returned URL is a local placeholder and not a hosted checkout page.
+- Payment Intent confirmation has a simplified state model: normal confirmation succeeds; the documented decline token fails.
+- Refunds support `payment_intent` or `charge` input, but only validate a referenced Payment Intent when one is supplied.
+- No live keys, PANs, CVCs, provider credentials, or real network traffic are retained or used.
+
+## Runnable SDK Example
+
+Start GhostAPI and run `examples/stripe-node/checkout-flow.mjs`. The example configures the official Node SDK with its documented host, port, protocol, and API-version client options, then verifies a locally delivered webhook using the SDK; no SDK source patch is required.

package/docs/releases/README.md

@@ -0,0 +1,13 @@
+# Release Evidence
+
+GhostAPI release evidence is tied to an exact public commit and generated by the release workflow.
+
+For each release, verify:
+
+- the annotated Git tag is `v<package.json version>` and points to the published commit;
+- CI, package smoke tests, and Linux egress enforcement checks passed for that commit;
+- the GitHub Release contains the exact tested npm tarball, `SHA256SUMS`, and a CycloneDX SBOM;
+- the tarball has a GitHub build-provenance attestation;
+- npm shows provenance and its `gitHead` matches the tagged commit.
+
+Historical `0.1.x` artifacts may not satisfy this complete chain and retain their immutable original npm `gitHead` metadata. A reviewed metadata-only history correction was applied before `v0.2.0`; PR #20 records the unchanged trees, messages, and dates. The first release intended to use the complete workflow is `v0.2.0`.

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

@@ -1,34 +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.
+# 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

@@ -1,42 +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.
+# 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

@@ -1,35 +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.
+# 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

@@ -1,52 +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.
+# 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.