From e30554299084f160589e97bee9b24b05f9234bfb Mon Sep 17 00:00:00 2001 From: Steven Enamakel Date: Thu, 15 Oct 2026 03:07:26 +0300 Subject: [PATCH] docs: final pass on MODULE.md, performance, ROADMAP (phase 9) Part of tinyhumansai/openhuman#7328 Co-authored-by: Medulla --- MODULE.md | 34 +++++++++++++++++++++------------- ROADMAP.md | 35 +++++++++++++++++++++++------------ docs/performance.md | 21 ++++++++++++--------- 3 files changed, 56 insertions(+), 34 deletions(-) diff --git a/MODULE.md b/MODULE.md index 5714e31..a03b8ae 100644 --- a/MODULE.md +++ b/MODULE.md @@ -7,7 +7,7 @@ is `ai.tinyhumans.tinysecurity.Policy`, with object Accepted SDK reinit advances a generation and emits `PolicyChanged`; rejected configurations retain the old policy and generation. There are no Init/Reinit RPC methods. Configuration requires `contract_version` and `policy`. The optional -`judge` field may be omitted or set to `null` in this bootstrap. +`judge` field may be omitted or set to `null`, which leaves automatic scoring off. ```json { @@ -23,8 +23,10 @@ RPC methods. Configuration requires `contract_version` and `policy`. The optiona } ``` -Judge configuration has redacted Debug, travels only in SDK config, and is -rejected as unavailable rather than accepted without a functioning engine. +Judge configuration has redacted Debug and travels only in SDK config. A non-null +`judge` is accepted only with its full trusted initialization (resolved credential, +exact endpoint, approval store and configured audit); otherwise init or reinit +rejects and keeps the old policy. See [native approval scoring](crates/tinysecurity-auto/README.md). Invalid thresholds/timeouts are rejected before capability admission. `PolicyInfo` never returns credentials. The wire version is separate from release version. Hosts require matching major and module minor >= host minor; @@ -79,9 +81,15 @@ Durable approval lifecycle/flow/reply, redaction/scanning, scoped egress guards and audit have implemented members in the generated method inventory. Contract 1.7 approvals use explicit initialization and authenticated callbacks; see [durable exact approvals](crates/tinysecurity-approval/README.md). -Network/DNS connection pinning, sandbox isolation and judge remain unavailable; -keyring consent is implemented by the confidential crypto members below. Their reserved payloads do not advertise callable members. -Unsupported member calls return the bus's unknown-member error. +Scoped egress ([egress](docs/egress.md)) issues DNS-vetted, single-use socket grants; +this module never opens the connection, so each transport owner must connect only to +the approved sockets (connection pinning is the transport's job, not claimed here). +Sandbox planning ([sandbox](crates/tinysecurity-sandbox/README.md)) selects and audits +a plan; TinyBox enforces isolation at launch. The optional judge +([scoring](crates/tinysecurity-auto/README.md)) only scores requests that still need +approval and never grants human-only authority. Keyring consent and the password and +pairing members are in the confidential crypto section below. Unsupported member calls +return the bus's unknown-member error. ## Packaging and smoke checks @@ -101,8 +109,9 @@ verification also rejects a wrong digest and tampered bytes before activation, rejects missing SDK configuration, and confirms stopped modules refuse reinit. Fault-injection and timeout latching remain SDK conformance work, not a bootstrap claim. Timing uses 500 sequential calls per method, one Evaluate call for one diagnostic or -one Check call for two checks per sample. See measured results and migration -budgets in [performance](docs/performance.md). +one Check call for two checks per sample. See measured results and the enforced +release budget in [performance](docs/performance.md). OpenHuman's host-side view is +the [security architecture page](https://github.com/tinyhumansai/openhuman/blob/main/gitbooks/developing/architecture/security.md). ## Confidential device handles @@ -195,9 +204,9 @@ policy publication; valid-clock publication rejection preserves old authority. Accepted generations invalidate pending native work and clear aliases, while persistent resolver uncertainty remains unavailable. Native clock faults still close authority permanently. Device replay capacity and every scope epoch are -checked before publication; bootstrap evidence survives accepted reinit. Native OS providers, physical files, passwords, encryption, -plaintext delivery, routine native consumers, pairing and production host -migration remain outside this subset. +checked before publication; bootstrap evidence survives accepted reinit. Physical files, plaintext delivery and routine native consumers remain outside +this subset; password, OS keyring and pairing members are in contract 1.14 below +(`PasswordCrypt2`, `KeyringAccess2`, `PairingControl2`). ## Confidential native config cipher (contract 1.11) @@ -237,8 +246,7 @@ the real hashed TinySecurity cdylib and a separately admitted host-trusted nativ callback fixture. This proves module-to-admitted-native-consumer composition; it does not prove ordinary OpenHuman host callback admission. That TinyBus integration gap remains open. SDK serde/frame/partial-decode copies and process -abort are outside the owned-buffer wiping guarantee. Host migration, passwords, -pairing and app document storage remain separate unfinished capabilities. +abort are outside the owned-buffer wiping guarantee. App document storage remains a separate unfinished capability. ## Registered subject policies (contract 1.12, extended in 1.13) diff --git a/ROADMAP.md b/ROADMAP.md index 5432e02..20f4214 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -1,14 +1,25 @@ # TinySecurity roadmap -The current bootstrap PR implements conservative policy evaluation, ordered checks, -versioned wire contracts, SDK init/reinit and native loading. Publishing those -contracts/artifacts remains pending upstream review and release. It intentionally does -not close the security extraction tracker. - -The [implementation plan](docs/plans/security-module.md) orders the remaining -work: full host policy/command parity, unified redaction, connection-pinned -egress, TinyBox sandbox planning, durable audit/approvals, optional Jev, -native conformance and release gates, reviewed policy expansion, crypto last. - -Production OpenHuman callers move only after upstream capabilities are merged, -released and validated with published checksums and native latency budgets. +Tracked by [OpenHuman #7328](https://github.com/tinyhumansai/openhuman/issues/7328). + +## Delivered + +Policy evaluation and ordered checks, scoped and immutable path policies, redaction +(including the boot diagnostic floor, [ADR 0007](docs/adr/0007-boot-diagnostic-redaction-floor.md)), +scoped egress grants, durable exact approvals, optional judge scoring, sandbox +planning, audit, confidential device, secret, cipher, password, keyring and pairing +members, and a CI-enforced release latency budget ([performance](docs/performance.md)). +`max_cost_per_day_cents` was removed from the contract ([ADR 0006](docs/adr/0006-remove-max-cost-per-day.md)). + +## Open + +- Confidential delivery to an ordinary (non-native) admitted host callback, needed + for config-cipher plaintext delivery and pairing `Begin`/`Verify` (TinyBus gap). +- Native conformance on macOS and Windows runners for device and secret members. +- Fault-injection and timeout latching conformance in the SDK. +- Windows alias, ADS and device-path handling and rich shell grammar parity. +- Calls-per-turn measurement against a representative OpenHuman workload. + +Host callers move to a member only after it is merged, released and validated with +published checksums and the native latency budget. See [MODULE.md](MODULE.md) for the +current surface. diff --git a/docs/performance.md b/docs/performance.md index 4da7fe0..f934fe0 100644 --- a/docs/performance.md +++ b/docs/performance.md @@ -20,18 +20,21 @@ a controlled runner and representative workload. The characterized host debug path over two checks was 35 us p50 / 63 us p99. The native boundary is substantially slower in this debug workload. These -numbers do not establish release-build performance, or a product migration -budget. A provisional gate to measure before migration is <=1 ms p50 and -<=10 ms p99 per batched Check on the same supported native runner. That gate -must be agreed against a representative released-module workload and its -number of calls per turn before host callers move. Bootstrap remains -release-gated irrespective of this synthetic result. +debug numbers are historical; the release-build figures and the agreed budget +below supersede them. ## Release budget (enforced in CI) -Release build, same workload (500 samples per method, Linux x86_64, October 14, -2026): Evaluate 50.6 us p50 / 62.9 us p99; Check (two checks) 52.1 us p50 / -68.6 us p99. +Release build, same workload (500 samples per method, Linux 7.0.0-31-generic +x86_64, October 14, 2026): + +| Native method | p50 | p99 | +| --- | --- | --- | +| Evaluate | 50.6 us | 62.9 us | +| Check (two checks) | 52.1 us | 68.6 us | + +Release is roughly 9x faster at p50 than the debug run above, so debug numbers +must not be used for budgeting. The agreed budget per bus call on a supported native runner is p50 <= 1 ms and p99 <= 10 ms for both Evaluate and Check, roughly 20x and 150x headroom over