@yiaany/ghostapi 0.1.7 → 0.1.9

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

@@ -0,0 +1,104 @@
+# Agent Inventory And Attack-Path Graph Threat Model
+
+Applies to the local agent inventory layer: the persisted inventory store, attack-path graph, blast-radius analysis, detections, remediation workflow, open export, removal analysis, and ROI report.
+
+## Scope
+
+This threat model covers the inventory module added in the "agent inventory, attack-path graph, and indispensability" session:
+
+- `inventory.json` local persisted store under `.ghostapi/`, created by `getDataPaths().inventoryStore`.
+- Import of agents, tools, identities, providers, resources, side effects, credentials, and policies from `config`, `ci`, `gateway`, and `cloud` sources, each record carrying provenance (source, import time, importer) and freshness.
+- The attack-path graph (`agent -> identity -> tool -> provider -> resource -> side effect`) with persisted, provenance- and freshness-carrying edges.
+- Blast-radius analysis, detections, remediation proposals/applications, open export, removal analysis, and the ROI report.
+
+The inventory layer adds no provider, credential, network egress, or hosted control-plane surface. All of it is local-first and synthetic. ROI and removal numbers are derived from imported counters and local records only; nothing is invented, and the pilot entry gate (a real team/enterprise pilot) is not yet met.
+
+## Trust Boundaries
+
+| Boundary | In scope | Out of scope |
+| --- | --- | --- |
+| Operator identity | Every inventory action authenticates through an injectable authorizer and requires an explicit permission (`inventory.import` / `inventory.inspect` / `inventory.analyze` / `inventory.remediate` / `inventory.export`); the test authorizer binds issued identities by reference | Real authn/authz infrastructure |
+| Import sources | Imports declare a source (`config` / `ci` / `gateway` / `cloud`) that is recorded as provenance on every record and edge | Live provider or CI credentials; the layer never reaches out to a source |
+| Tenant isolation | All reads and writes are filtered by `tenantId`; graph, findings, export, attack paths, removal, and ROI are tenant-scoped | Multi-tenant federation |
+| Store | Regular non-symlink JSON file, owner-only on POSIX, bounded bytes and record counts | Remote/distributed storage |
+
+## Assets
+
+- Agent inventory records and graph edges (`inventory.json`).
+- Provenance and freshness metadata attached to every record and edge.
+- Findings and remediation state (proposals, applications, rejections).
+- The open export artifact (inventory, policies, eval scenario references, evidence metadata, removal analysis, ROI).
+- Import-run and import-source ledger.
+
+## Threats And Mitigations
+
+### T1. Unauthenticated or unauthorized inventory writes
+
+Every mutating and reading method calls `authorize` first: `validateOperator` on the authorizer result and an explicit permission check. The default authorizer (`createDisabledInventoryOperatorAuthorizer`) throws "not configured", so a controller with no authorizer cannot be used. Test identities are reference-bound; a plain `{}` is rejected as "not authenticated".
+
+### T2. A poisoned import poisons the graph
+
+`validateImportPayload` enforces strict schema, allowed source types, identifier/scope/hash/timestamp formats, bounded array sizes, and per-kind id uniqueness before anything is stored. Cross-references (e.g. an agent referencing an unknown identity) are validated against both the current import and the persisted state, and a reference to a record that does not exist rejects the whole import. Import payloads are canonicalized to a digest recorded on the import run and source.
+
+### T3. Tenant data leaks across the graph or export
+
+Every graph edge, record, finding, remediation, import run, and source is filtered by `operator.tenantId` in `snapshotFor`, `graphEdges`, `findAttackPaths`, `computeBlastRadius`, `computeFindings`, `computeCoverage`, `computeRemovalAnalysis`, `computeRoiReport`, and `export`. An edge can only be created from a record that belongs to the importing tenant. Cross-tenant leakage is covered by tests.
+
+### T4. Provenance or freshness is missing or forged
+
+Every record and edge carries `provenance` (`sourceId`, `sourceType`, `sourceName`, `importedAt`, `importedBy`) and `freshness` (`firstSeenAt`, `lastSeenAt`) built from the import payload source and the authenticated operator's principal id — never from client-supplied strings. `validateState` re-validates provenance/freshness on every read and write. Edge ids are derived from source/target/relation so re-imports refresh `lastSeenAt` instead of duplicating edges.
+
+Edges have a freshness lifecycle. Attack-path and blast-radius analysis only use edges whose `lastSeenAt` is within the configured `edgeStaleDays` window, so a long-unseen relationship cannot be cited as current reachability evidence. On every import the importing tenant's stale edges are garbage-collected from the store, keeping the graph from accumulating frozen relationships that were never refreshed.
+
+### T5. A remediation expands permissions instead of reducing them
+
+`reduce_scope` proposals are rejected at proposal time unless the reduced scope list is a strict subset of the credential's current grant scopes and removes at least one scope; the same invariant is enforced again at apply time. `revoke` only ever sets a credential to revoked. `assign_owner` only sets an owner id. `onboard_through_gateway` only sets the gateway-managed flag. `create_eval` only records an eval scenario reference — and, when an `evalScenarioExists` resolver is configured, the referenced scenario must actually exist before the proposal is accepted, so a remediation cannot paper over a finding by pointing at a deleted scenario. No remediation path adds scopes or relaxes a control.
+
+Applied remediations are re-verified on every analysis pass: a finding stays resolved only while the remediation remains effective. If a later import re-expands a reduced scope, revokes nothing, clears an assigned owner, un-gates an agent, or deletes the referenced eval scenario, the finding is re-opened instead of staying permanently marked resolved.
+
+Remediation targets are validated against the tenant's live data before a proposal is accepted: an `environment` target must actually be referenced by at least one agent, identity, provider, resource, credential, or policy of the tenant, so a remediation cannot be proposed against a stale or invented environment.
+
+### T6. The store is poisoned or exploded
+
+The store is validated on every read (`validateState`) and write (`atomicWriteJson(this.path, validateState(state))`). Store bytes are capped at 8 MiB; every collection is bounded (`maxAgents`, `maxEdges` 6,000, `maxFindings` 3,000, etc.), and `assertStoreBounds` rejects edges and findings over their caps on every mutation. Import runs are rotated per tenant at `maxImports` (256), keeping the oldest runs trimmed rather than failing the write. The store must be a regular non-symlink file. Oversized or non-JSON stores are rejected, not partially loaded.
+
+### T7. Secret-shaped or control-character data enters the inventory
+
+Identifiers, scopes, and text are validated by regexes and by `sanitizeSecretString`: any value that contains a recognizable secret shape (e.g. `sk_live_*`) or control characters is rejected. Evidence metadata and reasons are bounded text.
+
+### T8. ROI or removal analysis invents savings
+
+The ROI report is built only from imported counters (latest per source) and from actually applied remediations in the store; unmeasured counters are reported as `null` and listed in `notMeasured`, and `basis` is `local_inventory_data_only`. The removal analysis reports only numbers computed from the local store and states plainly when nothing verifiable depends on GhostAPI. The heuristic blast-radius classification is explicitly labeled advisory, not proof of exploitability.
+
+### T9. Attack-path graph is unbounded or cross-tenant
+
+Edges are created only from the importing tenant's records, are keyed by a derived edge id, and are bounded (`maxEdges` 6,000). Path finding is always scoped to the tenant and to a single agent id. Incomplete paths (a record reference missing from the store) are counted separately and reported as incomplete, not silently dropped.
+
+## Permissions And Capabilities Summary
+
+| Action | Check |
+| --- | --- |
+| Import | operator authorizer + `inventory.import` |
+| Inspect / graph / attack paths / blast radius / list remediations | operator authorizer + `inventory.inspect` |
+| Analyze / removal analysis / ROI | operator authorizer + `inventory.analyze` |
+| Propose / apply / reject remediations | operator authorizer + `inventory.remediate` |
+| Export | operator authorizer + `inventory.export` |
+
+## Limits
+
+| Resource | Limit |
+| --- | --- |
+| Store bytes | 8 MiB |
+| Import sources / import runs | 64 / 256 |
+| Agents / tools / identities | 500 / 500 / 500 |
+| Providers / resources / side effects | 200 / 1,000 / 2,000 |
+| Credentials / policies | 500 / 100 |
+| Graph edges | 6,000 |
+| Findings / remediations | 3,000 / 1,000 |
+| References / scopes per record | 64 / 32 |
+
+## Out Of Scope
+
+- Live provider, CI, or gateway ingestion (the layer consumes locally-supplied payloads only).
+- Hosted multi-tenant control plane and federated sources.
+- Automated kill-switch or revocation execution against real providers (remediations mutate the local inventory state only).

package/docs/security/kill-switch-budgets-threat-model.md

@@ -0,0 +1,37 @@
+# Local Kill Switch, Budget, And Blast-Radius Threat Model
+
+## Scope
+
+The Session 27 safety controller is a local, persisted coordination layer for the existing `ghostapi-synthetic` action path. It implements local kill switches, budgets, circuit breakers, bounded queue/dead-letter state, authenticated emergency API calls, audit records, and a scheduled synthetic game-day test. It does not introduce a provider, provider SDK/client, provider account, vault, credential, external HTTP, webhook/email/Slack transport, hosted control plane, or production side effect.
+
+## Emergency Authority
+
+`stop()`, `reenable()`, `configureBudget()`, and `configureCircuit()` require an injected `SafetyEmergencyAuthorizer`. The API accepts only verifier-issued operator objects with a stable principal and explicit permission. `safety.stop`, `safety.reenable`, and `safety.configure` are separate permissions. Empty, secret-shaped, or oversized reasons fail closed and every emergency decision is chained into the bounded local audit log.
+
+There is intentionally no unauthenticated HTTP emergency endpoint, no CLI token parser, and no notification transport. A future deployment needs a separately reviewed identity authority and authenticated transport before exposing this emergency API remotely.
+
+## Enforcement Semantics
+
+- Switch scopes are `global`, `organization`, `project`, `environment`, `agent`, `workload`, `provider`, `operation`, and `risk_class`.
+- Admission serializes against the persisted controller store. Budgets reserve action costs before execution, so parallel callers cannot oversubscribe money, requests, messages, mutations, deletes, token cost, concurrency, or velocity limits.
+- A replay with the same idempotency key and action hash returns a replay lease without a second reservation. Reusing the key with a different action hash is denied.
+- The action gateway calls the controller after plan/simulate and before its attempt record. The synthetic world calls the controller's `commit()` while it holds its own world lock. `commit()` is two-phase: a first mutate re-checks the lease, expiry, and kill-switch/circuit state; only then is the operation executed; a second mutate re-checks the lease and persists the `action.final_check` audit record ("remained active through commit") before returning. A kill switch that wins before the first phase blocks the local mutation. If the lease expires between the phases, `commit()` throws even though the operation already ran — the caller must not treat the action as successfully admitted.
+- Leases are time-bounded: a reserved lease expires after `DEFAULT_LEASE_TTL_MS` (60 s by default, overridable via `leaseTtlMs`). Expired leases are pruned on the next admission, and both `assertActive()` and the `commit()` phases reject an expired lease. `complete()` is tolerant: it still records the outcome for a lease that expired after the operation, so the audit chain reflects what actually happened instead of dropping the terminal record.
+- Kill-switch denials carry the stable error code `SAFETY_KILL_SWITCH` (and admit/commit errors are `SafetyControllerError`), so callers — including the scheduled game day — detect a kill-switch block structurally instead of by parsing message text.
+- Queued actions have a fixed maximum of 100. A full queue returns backpressure. Stopping a matching scope moves queued records to the bounded dead-letter queue; no queued action is auto-retried. The dead-letter queue is also bounded, and when full the oldest entry is evicted so the store never grows without limit.
+- Already approved is not already executable: approval artifacts still pass current policy, identity, idempotency, safety admission, and final-commit checks. An in-flight action that has crossed the final commit cannot be undone; GhostAPI does not claim rollback. A real provider would require idempotency and reconciliation semantics before an equivalent boundary is enabled.
+- Failures, policy violations, latency threshold breaches, and reconciliation mismatches can open persisted circuit breakers. Open breakers deny new admission; no retry loop is created by the controller.
+
+## Persistence And Limits
+
+Critical state lives in `.ghostapi/safety-controller.json`, not process memory. It is strict-schema validated, bounded to 1 MiB, guarded as a regular non-symlink file, serialized with the existing file lock, atomically replaced, and covered by a bounded SHA-256 audit chain. This is local coordination and tamper evidence on one filesystem, not a distributed lock, immutable audit ledger, or defense against a malicious same-user actor who can modify both state and runtime.
+
+## Game Day And Runbook
+
+The scheduled GitHub workflow runs only `test/safetyController.test.ts`, which performs a local synthetic stop/re-enable drill and never creates a provider side effect. The operational procedure is in [`docs/operations/kill-switch-runbook.md`](../operations/kill-switch-runbook.md).
+
+## Remaining Limits
+
+- The controller does not authorize production execution, reconcile a provider outcome, revoke a provider credential, or prove a provider-side stop.
+- Budget units are caller-supplied typed action metadata for the one local synthetic action; a future real action needs independently derived and provider-verified amounts/costs.
+- Local timestamps use the process clock. A real deployment needs a trusted clock, durable audit sink, shared atomic store, reconciliation, and provider-specific final-side-effect guards.

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

@@ -0,0 +1,111 @@
+# Reliability Surface Threat Model
+
+Applies to the local reliability layer: SLO controller, reconciliation service, cost governance, runtime health, and backup/restore.
+
+## Scope
+
+This threat model covers the reliability module added in the "reliability" session:
+
+- `slo.json`, `reconciliation.json`, `costs.json` local persisted stores under `.ghostapi/reliability/`.
+- Backup and restore of the whole local data directory, including the reliability stores.
+- `/health` and `/health/readiness` HTTP endpoints backed by `checkRuntimeHealth`.
+- Reconciliation reading the action ledger and the synthetic worlds directory.
+
+`checkRuntimeHealth` treats every canonical store as a first-class dependency, including `inventory.json` (`inventoryStore`), so a corrupt or missing inventory store is reported as `degraded` and flips readiness, not just the reliability stores.
+
+The reliability layer adds no provider, credential, network egress, or hosted control-plane surface. All of it is local-first and synthetic.
+
+## Trust Boundaries
+
+| Boundary | In scope | Out of scope |
+| --- | --- | --- |
+| Operator identity | SLO, reconciliation, and cost operators authenticate through injectable authorizers; the test authorizer binds issued identities by reference | Real authn/authz infrastructure |
+| Ledger access | Reconciliation uses a verified ledger capability (reference-bound, tenant-scoped, permission-checked) | Key management for live providers |
+| Provider state | Reconciliation inspects synthetic worlds through `createWorldStateReconciliationProvider` | Live provider APIs |
+| HTTP surface | `/health`, `/health/readiness` are public but return only structural readiness | Authenticated control APIs |
+
+## Assets
+
+- SLO samples and configured targets (`slo.json`).
+- Reconciliation findings, resolutions, and last-run state (`reconciliation.json`).
+- Cost records, budgets, alerts (`costs.json`).
+- Backup manifest and copies (`reliability/backups/`).
+- The runtime health report (derived, not persisted).
+
+## Threats And Mitigations
+
+### T1. Unauthorized SLO recording poisons availability targets
+
+`recordSample`/`recordSamples` accept a capability object instead of an operator identity. The capability must be a member of the record-capability set created by `createSloRecordIdentity`; any other object is rejected with "record capability". This is reference-bound, so ambient objects cannot be forged.
+
+Samples are bounded: `MAX_SAMPLES_PER_METRIC` (5,000), `MAX_SAMPLES` (10,000) globally, enforced on every mutation, and `recordSamples` caps each call at `MAX_RECORD_BATCH` (1,000) so a single oversized call cannot blow past the store bound. SLO store bytes are capped at 4 MiB.
+
+Latency evaluation only counts samples whose `ok` flag is true; a latency breach requires both `sample.ok === true` and `durationMs` above the target. Failed samples can no longer be counted as "within SLO" by reporting a low duration.
+
+### T2. Operator impersonation on configure/evaluate/inspect
+
+Every SLO operator action authenticates through the configured authorizer and validates permissions against `slo.configure`/`slo.inspect` only. Identities are reference-bound objects issued by the authorizer; a plain `{}` or any other object is rejected as "not authenticated".
+
+### T3. Reconciliation reads a tampered ledger
+
+`runReconciliation` requires the operator to hold the `reconciliation.manage` permission and takes an explicit `{ identity }` input; a read-only operator is rejected. It calls `exportTenant`; if ledger integrity verification fails, reconciliation is blocked with a clear error and no findings or SLO samples are written. A tampered ledger cannot silently produce a "valid" report. Provider read failures are detected structurally (`SyntheticWorldError` with code `WORLD_NOT_FOUND`) rather than by matching error text, so a missing world is reported deterministically.
+
+### T4. Reconciliation leaks or records sensitive provider evidence
+
+Provider receipts are reduced to `{ actionId }` for matching, and worlds are inspected through the same receipts shape. Findings carry only `actionHash` and bounded non-secret `detail`/`evidenceRef` strings (validated by `identifier`/`hash`/`evidence`/`text`, which reject control characters and secret-shaped values via `sanitizeSecretString`).
+
+### T5. Cost store is poisoned or exploded
+
+Cost records are capped (`MAX_RECORDS` 10,000), budgets capped (`MAX_BUDGETS` 32), alerts capped (`MAX_ALERTS` 100), window capped (`MAX_WINDOW_MS` 90 days), store bytes capped at 4 MiB. Amounts are non-negative integers. `recordCost` is idempotent per tenant: a duplicate `actionId` for the same tenant is rejected, so a replay of a cost record cannot double-charge a budget. `report()` is a pure read — it never writes alert state; only `listAlerts()` persists derived alerts. Reports and alerts are scoped to the operator's tenant via the optional `CostOperator.tenantId`, and alerts honor each budget's `alertOnExceed` flag, so an explicit opt-out cannot be overridden by a global alert pass. Forecast output is explicitly labeled as a linear extrapolation approximation, not a provider invoice.
+
+### T6. Backup/restore path traversal
+
+Restore validates every manifest entry path with `normalizeEntryPath` (rejects `..`, absolute paths, drive-letter prefixes, NUL bytes) and `assertContained` bounds every source and target path within its root. A crafted manifest that escapes the backup root is rejected before any file is written.
+
+### T7. Tampered backup restores bad data
+
+Restore requires `manifest.verified === true` and re-verifies sha256 and size of every entry before and after copy, plus JSON structure for `.json` entries. Tampering with any backed-up file fails "integrity verification" and aborts the restore.
+
+### T8. Backup exfiltrates or follows unsafe links
+
+`collectBackupFiles` refuses symbolic links, non-regular files, `.lock`/`.tmp` files, and refuses the whole backup if any is encountered. Exclusions are path-based, not name-based: only the canonical `cache` and `backups` directories, the current destination, and a top-level `runs` directory are skipped — a nested directory merely named `cache` or `backups` inside a world/contract is still backed up. Because the canonical backups location is excluded, backups do not recursively include earlier backups.
+
+### T9. Runtime health check is a denial vector
+
+Store files are read with `MAX_CHECK_FILE_BYTES` (4 MiB) cap; oversized or non-JSON stores are reported as `degraded`, never loaded fully. The `/health` endpoint returns only `{ ok, ready }`; `/health/readiness` returns the structural report and 503 when not ready.
+
+### T10. Backup/restore destroys the source
+
+Backup only reads the source; restore refuses a target that is the source or inside it, and refuses to restore into a non-empty target directory, so an existing data directory cannot be silently overwritten. Copy is byte-verified before the atomic write to the destination, and failed copies clean up the partial destination.
+
+## Permissions And Capabilities Summary
+
+| Action | Check |
+| --- | --- |
+| SLO record | record capability in `sloRecordCapabilities` |
+| SLO configure/inspect/evaluate | operator authorizer + `slo.configure`/`slo.inspect` |
+| Reconciliation run | operator authorizer + `reconciliation.manage` + ledger capability (tenant-scoped, `export`) |
+| Reconciliation findings/resolve | operator authorizer + `reconciliation.inspect`/`reconciliation.manage` |
+| Cost record/configure/report/alerts | operator authorizer + `cost.*` permissions |
+| Health/backup/restore | local-only; backup/restore are not exposed over HTTP |
+
+## Limits
+
+| Resource | Limit |
+| --- | --- |
+| SLO samples per metric | 5,000 |
+| SLO samples total | 10,000 |
+| SLO targets | 32 |
+| SLO window | 1 hour .. 30 days |
+| Reconciliation findings | 1,000 |
+| Cost records / budgets / alerts | 10,000 / 32 / 100 |
+| Cost window | up to 90 days |
+| Store bytes | 4 MiB each |
+| Backup total bytes | 64 MiB |
+| Health check file bytes | 4 MiB |
+
+## Out Of Scope
+
+- Live SLO alerting to external systems (no egress was added).
+- Multi-node reconciliation consensus (local single-process semantics).
+- Backup to remote/object storage (local directory only).

package/docs/security/trust-ladder-threat-model.md

@@ -0,0 +1,33 @@
+# Local Synthetic Trust Ladder Threat Model
+
+## Scope
+
+The Session 26 trust ladder is a local, synthetic, data-only preparation layer. It models `simulate`, `shadow`, `dry-run`, `approve`, `bounded-auto`, and `trusted` capability contracts, promotion evidence, canary eligibility, comparisons, rollback reasons, and audit records. It does not execute an action and does not integrate with the action gateway, approval inbox, credential broker, vault, provider SDK/client, external HTTP, provider account, test account, hosted control plane, or notification transport.
+
+The local synthetic runtime is not production authorization. `trusted` is intentionally unsupported. `dry-run` is unsupported because no provider-official safe dry-run semantic exists for `ghostapi-synthetic`; it is never emulated by ordinary execution.
+
+## Trust Boundaries
+
+- Target identities are strict synthetic-only values. Production and test-account identities are rejected rather than mixed into local state.
+- Owner decisions arrive only through an injected verifier and compare the verifier-issued stable `principalId` to policy. Caller-shaped owner objects fail closed.
+- Promotion evidence is bounded metadata: run count, violation/error count, named eval status, and timestamps. LLM confidence is not a signal.
+- Shadow comparisons accept only SHA-256 action/context metadata and return matching evidence. They do not read raw provider inputs or invoke an adapter.
+- Bounded outcome comparisons accept only action/outcome/receipt hashes. They do not perform the bounded execution being assessed.
+- State uses private local storage, regular-file/symlink checks, byte limits, a file lock, atomic replacement, and a bounded SHA-256 audit chain. This is coordination/tamper evidence under the existing local filesystem model, not an immutable audit sink.
+
+## Invariants
+
+- Every local capability declares `externalSideEffects: false`.
+- `dry-run` and `trusted` are explicitly unsupported; unsupported levels cannot be promoted into.
+- Promotion has no automatic path. It requires the configured verified owner, fresh evidence, minimum runs, every required passing eval, and violation/error rates at or below policy thresholds.
+- Promotion advances only to the next supported level, so an operator cannot skip review stages.
+- Canary assignment is deterministic from a SHA-256 policy/target bucket, checks tenant and resource scope first, and uses a 0-10,000 basis-point percentage.
+- A canary violation can immediately demote the target to `approve` or open the circuit breaker based on policy. Stop conditions open the breaker. Once open, no further assignment, comparison, or canary outcome is accepted.
+- `rollbackToApproval()` requires the verified policy owner and appends an audit record with the supplied bounded reason.
+- The implementation cannot mutate a synthetic world or a provider because it has no execution dependency or capability.
+
+## Remaining Limits
+
+- Shadow and outcome evidence compare supplied hash metadata. They cannot prove a real provider request or external outcome because the implementation deliberately has no provider transport.
+- This is not an approval authority, action-level policy engine, kill switch for a real provider, budget/velocity enforcement gateway, reconciliation service, test-account boundary, or production audit system.
+- A future real provider integration requires a separately reviewed provider-specific identity model, official dry-run proof where claimed, action authorization, inbox/credential execution boundary, idempotency and reconciliation semantics, kill switch, budgets, durable audit storage, and explicit owner/test-account gates before any side effect is enabled.

package/docs/team-control-plane.md

@@ -0,0 +1,72 @@
+# Team Control-Plane Prototype
+
+## Scope
+
+As of August 8, 2026, the cloud/design-partner gate remains unmet. This is a local architecture prototype stored in a private JSON file. It has no hosted or public endpoint, network listener, deployment, SSO/OIDC/SAML integration, cloud synchronization, telemetry, or external dependency. Local GhostAPI workflows do not require an account or team token.
+
+The store is `.ghostapi/team-control-plane.json` (or the configured `GHOSTAPI_DATA_DIR`). Existing same-directory atomic writes and cooperative cross-process locking protect updates. The store rejects symlinks and data over 1 MiB. This is not a compliance product, immutable storage system, credential broker, or distributed security boundary.
+
+## Data Flow
+
+```mermaid
+flowchart LR
+  Caller[Local typed-library caller] --> Auth[Token authentication or local actor]
+  Auth --> Permit[Central permission and scope evaluator]
+  Permit --> Plane[Local control-plane methods]
+  Plane --> Lock[Locked atomic JSON store]
+  Plane --> Ledger[Per-organization SHA-256 audit chain]
+  Future[Future HTTP transport] -. must apply .-> Headers[CSP and security headers]
+  Future -. must apply .-> Limit[Fixed-window fail-closed limiter]
+  Disabled[Disabled identity provider] -. always denies; no I/O .-> Future
+```
+
+No transport is supplied. A future HTTP layer must authenticate before dispatch, apply `createTeamControlPlaneSecurityHeaders()` (or the immutable `TEAM_CONTROL_PLANE_SECURITY_HEADERS`), use `TeamControlPlaneRateLimiter` before processing with a non-secret opaque principal key, avoid logging raw tokens, and fail closed on invalid keys, invalid limits, invalid clocks, or limiter capacity exhaustion.
+
+## Tenant And Authorization Model
+
+Organizations are tenant boundaries. Projects, environments, scenarios, evidence, policies, service accounts, tokens, and audit records all belong to one organization. Parent references are validated on every read and write. Missing scoped parents return `Resource not found`, preventing cross-tenant identifier disclosure.
+
+All authorization uses the centralized `TEAM_PERMISSION_MATRIX`. The least-privilege matrix is:
+
+| Role | Permissions |
+| --- | --- |
+| `owner` | `member.manage`, `project.manage`, `environment.manage`, `policy.manage`, `token.manage`, `service_account.manage`, `audit.read`, `audit.export`, `data.delete`, `retention.manage`, all scoped reads, `scenario.publish`, `evidence.upload` |
+| `admin` | Everything listed for owner except `member.manage` |
+| `developer` | Scoped reads, `scenario.publish`, `evidence.upload` |
+| `viewer` | Scoped reads only |
+| `service_account` | Token-scoped project/environment reads, `scenario.publish`, and `evidence.upload` only; no organization-wide policy or audit access |
+
+`admin` cannot grant members or issue, rotate, or revoke a token for an owner. `owner` can manage every human-member token. Service-account actors have a distinct `service:<id>` audit identity and cannot impersonate a human member.
+
+## Tokens And Service Accounts
+
+Owners and admins create managed service accounts using an identifier and display name. A service account has no plaintext secret and is not a human member. Tokens are typed `user` or `service`, have SHA-256 digests only in persisted state, are returned once at issuance, can be revoked, and must expire within 90 days.
+
+`issueToken` remains the human-token API. `issueServiceToken` requires a live service account and a nonempty, bounded list of scope entries. Every entry names an existing `{ projectId, environmentId }` and a nonempty subset of service-account scoped permissions. Authentication validates token digest, expiry, revocation, account state, and scope. A service actor is an in-memory authenticated capability returned only by `authenticateToken`; constructing an object with a token id is rejected. Each scoped method resolves that token's persisted scope, expiry, revocation, and account state again before acting. Rotation revokes the prior token and creates the replacement in one locked mutation; `disableServiceAccount` immediately revokes all of its live tokens. No reusable plaintext token is stored.
+
+## Audit Integrity And Export
+
+Schema v3 uses a per-organization append-only SHA-256 chain. Each record includes `sequence`, `previousHash`, and `recordHash`; the organization anchor supplies the sequence and hash before the retained window. `exportAudit` returns the anchor, records, and an integrity result. `verifyAuditExport` is public and detects changes to a record, record order, sequence, or chain link. Exports contain audit metadata only and never include token plaintext or other secrets.
+
+Schema v1 migrates through v2 to v3. Legacy `member` becomes `developer`; typed user tokens replace legacy `memberId` token bindings; legacy audit rows are replayed into a validated v3 SHA-256 chain. Unknown fields, malformed references, invalid token scopes, invalid service-account references, and invalid chains fail closed.
+
+Audit retention is bounded to 90 days and 1,000 records per organization. Pruning does not silently sever the chain: the last pruned record becomes the retained audit anchor. Sanitized evidence is retained for 30 days and capped at 100 records per organization. Owners and admins may explicitly delete evidence; deletion is tenant- and project-bound and audited. `deleteProject` removes that tenant project's environments, scenarios, evidence, and scoped service tokens in the same locked mutation. Audit export is restricted to `audit.export`; data deletion is restricted to `data.delete`.
+
+## Identity And Incident Response
+
+`TeamIdentityProvider` is a future integration boundary only. The single provided implementation, `createDisabledIdentityProvider`, performs no I/O and always denies authentication. No OIDC, SAML, SSO, SCIM, or remote identity protocol is implemented.
+
+If a token is exposed, an owner or authorized admin must revoke it, remove it from local logs or CI output, rotate or issue a short-lived replacement, and inspect `exportAudit` with `verifyAuditExport`. If the integrity result is false or the store fails validation, stop using the store, preserve the file for local investigation, restore only a reviewed local backup, and do not manually repair records or bypass validation. If evidence is incorrectly retained, use explicit evidence deletion or `pruneRetention`; both actions are audited.
+
+## Verification
+
+```bash
+npm run typecheck
+npm test -- --run test/teamControl.test.ts
+```
+
+## Explicit Non-Goals
+
+- No hosted API, public endpoint, deployment, dashboard, cloud sync, billing, SSO, SCIM, or generic project management.
+- No raw traffic, source code, secrets, or automatic artifact upload.
+- No compliance, legal-hold, immutable-storage, or distributed-isolation claim.