From 271d23faf7103ad21e2cf7665efdc71fbcf4dddb Mon Sep 17 00:00:00 2001 From: EdisonJwa Date: Thu, 14 May 2026 12:34:13 +0800 Subject: [PATCH] docs(governance): record PoC outcomes, owner decisions, and audit evidence MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Closes Phases A and D of the post-PoC sequencing. Decision register (v0.9.2 → v0.9.3): - DEC-014 Accepted: flutter_rust_bridge 2.x pinned (closed by poc/flutter_rust_bridge_hello). - DEC-013.1 Accepted: rusqlite (bundled) (closed by poc/sqlite-storage-spike). - DEC-013.2 Accepted: Linux secure-storage backend policy — Secret Service preferred, keyutils fallback (closed by poc/secure-storage-spike; resolves SysRS-053 / SysRS-162 ambiguity). - DEC-011.1 Accepted (desktop: cpal) / Deferred (mobile) (closed by poc/audio-capture-playback-spike desktop half only). - DEC-022 Accepted: canonical implementation directory layout per the README sketch and SAD §7.2. - DEC-020 explicitly Deferred by owner; remains a public-release blocker. Audit reports updated with empirical evidence: - docs/security/secure-storage-audit-report.md v0.9.3: SS-AUD-001/002/003/005/006 = PoC Pass with evidence pointers; SS-TC-003 (Linux) Actual Result populated and Status = PoC Pass; SS-AUD-004 cross-referenced to diagnostics-redaction PoC; findings SS-FIND-001 (closed by DEC-013.2), SS-FIND-002 (keyutils session caveat), SS-FIND-003 (non-Linux adapters still open). - docs/security/diagnostic-redaction-audit-report.md v0.9.3: REDACT-TC-001..010 = PoC Pass with evidence pointers; export bundle policy §5 populated for every row; findings REDACT-FIND-001 (regex coverage), REDACT-FIND-002 (tracing-layer integration), REDACT-FIND-003 (cross-spike KnownSecretRegistry contract). PoC plan (v0.1.0 → v0.2.0): - Status column added to §2; outcomes recorded. New doc: - docs/governance/poc-results-summary.md v0.1.0 — single-page reviewer-facing summary listing each spike's status, the toolchain exercised, the owner decisions taken, the audit coverage table, and open risks RISK-PoC-001..005 (mobile audio, non-Linux secure-storage adapters, license, remaining Proposed decisions, no product code yet). This completes the post-PoC documentation work. Repo is at a clean pause point: PoC code is committed, owner decisions are recorded, audit reports carry empirical evidence, and the residual risks are named in the summary doc. --- CHANGELOG.md | 27 ++++- docs/architecture/proof-of-concept-plan.md | 19 +-- docs/governance/poc-results-summary.md | 114 ++++++++++++++++++ docs/governance/product-decision-register.md | 27 ++++- .../diagnostic-redaction-audit-report.md | 55 +++++---- docs/security/secure-storage-audit-report.md | 51 ++++---- 6 files changed, 233 insertions(+), 60 deletions(-) create mode 100644 docs/governance/poc-results-summary.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 02cf835..782bc2d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -39,7 +39,32 @@ This project is expected to follow a Conventional Commits style workflow. ### Changed -- N/A +- `docs/architecture/proof-of-concept-plan.md` bumped to v0.2.0 to + record PoC outcomes (5 PASS, 1 PARTIAL) and add a Status column. +- `docs/security/secure-storage-audit-report.md` bumped to v0.9.3: + SS-AUD-001/002/003/005/006 status set to PoC Pass with evidence + pointers; SS-TC-003 (Linux) Actual Result populated and Status set + to PoC Pass; findings SS-FIND-001..003 added; non-Linux test cases + marked Deferred. +- `docs/security/diagnostic-redaction-audit-report.md` bumped to + v0.9.3: REDACT-TC-001..010 status set to PoC Pass with evidence + pointers; export bundle policy §5 populated; findings + REDACT-FIND-001..003 added. +- `docs/governance/product-decision-register.md` bumped to v0.9.3: + owner-confirmed decisions recorded — DEC-014 Accepted + (`flutter_rust_bridge` 2.x pinned), DEC-013.1 Accepted (`rusqlite` + bundled), DEC-013.2 Accepted (Linux Secret Service preferred, + keyutils fallback), DEC-011.1 Accepted (desktop `cpal`) / Deferred + (mobile), DEC-022 Accepted (canonical implementation directory + layout per README sketch + SAD §7.2), DEC-020 explicitly Deferred + and remains a public-release blocker. + +### Added (governance) + +- `docs/governance/poc-results-summary.md` v0.1.0 — single-page + reviewer-facing summary of the PoC phase, the toolchain exercised, + the owner decisions taken, the audit coverage, and the open risks + RISK-PoC-001..005. ### Fixed diff --git a/docs/architecture/proof-of-concept-plan.md b/docs/architecture/proof-of-concept-plan.md index 9e1cd67..66718d5 100644 --- a/docs/architecture/proof-of-concept-plan.md +++ b/docs/architecture/proof-of-concept-plan.md @@ -1,7 +1,7 @@ # Proof-of-Concept Plan **Document type:** Architecture / Proof-of-Concept Plan -**Version:** 0.1.0 +**Version:** 0.2.0 **Status:** Draft **Language:** English **Product:** Chanora @@ -15,14 +15,14 @@ This document defines technical proof-of-concept work that should be completed b ## 2. Required PoCs -| PoC | Purpose | Exit criteria | -|---|---|---| -| Flutter/Rust bridge hello | Prove command/result/event DTO boundary | Flutter can call Rust and receive event stream data | -| `tsclientlib` connect spike | Prove protocol feasibility | Rust can connect to a compatible server/test double | -| Audio capture/playback spike | Prove platform audio behavior | Capture/playback works on at least one desktop and one mobile target | -| Secure storage spike | Prove secret storage behavior | Secret write/read/delete works through platform secure storage | -| SQLite storage spike | Prove local non-secret persistence | Schema, migration, and repository pattern are demonstrated | -| Diagnostics redaction spike | Prove redaction before export | Password and identity-secret samples are redacted | +| PoC | Purpose | Exit criteria | Status | +|---|---|---|---| +| Flutter/Rust bridge hello | Prove command/result/event DTO boundary | Flutter can call Rust and receive event stream data | **PASS** — `poc/flutter_rust_bridge_hello/VERIFICATION.md` (Linux desktop, 3/3 tests, 2026-05-13). Closes DEC-014. | +| `tsclientlib` connect spike | Prove protocol feasibility | Rust can connect to a compatible server/test double | **PASS** — `poc/tsclientlib-connect-spike/VERIFICATION.md` (live against `cn.teamspeak.app`, 2026-05-13). | +| Audio capture/playback spike | Prove platform audio behavior | Capture/playback works on at least one desktop and one mobile target | **PARTIAL PASS** — `poc/audio-capture-playback-spike/VERIFICATION.md`. Desktop half met on Linux/PipeWire (2026-05-13). Mobile half NOT verified; remains an open gap. Closes DEC-011.1 for desktop only. | +| Secure storage spike | Prove secret storage behavior | Secret write/read/delete works through platform secure storage | **PASS (Linux only)** — `poc/secure-storage-spike/VERIFICATION.md` (6/6 audit tests, 2026-05-13). Closes DEC-013.2 (Linux backend policy). | +| SQLite storage spike | Prove local non-secret persistence | Schema, migration, and repository pattern are demonstrated | **PASS** — `poc/sqlite-storage-spike/VERIFICATION.md` (11/11 tests, 2026-05-13). Closes DEC-013.1. | +| Diagnostics redaction spike | Prove redaction before export | Password and identity-secret samples are redacted | **PASS** — `poc/diagnostics-redaction-spike/VERIFICATION.md` (REDACT-TC-001..010, 2026-05-13). | ## 3. PoC Directory @@ -47,3 +47,4 @@ A PoC is not product code unless explicitly promoted. | Version | Date | Description | |---|---|---| | 0.1.0 | 2026-05-14 | Initial proof-of-concept plan. | +| 0.2.0 | 2026-05-14 | Recorded PoC outcomes: 5 PASS, 1 PARTIAL PASS (mobile half of audio still open). Added Status column. Spike directories live under `poc/`; see `poc/README.md` and `docs/governance/poc-results-summary.md`. | diff --git a/docs/governance/poc-results-summary.md b/docs/governance/poc-results-summary.md new file mode 100644 index 0000000..fc93df0 --- /dev/null +++ b/docs/governance/poc-results-summary.md @@ -0,0 +1,114 @@ +# PoC Results Summary + +**Document type:** Governance / PoC Results Summary +**Version:** 0.1.0 +**Status:** Draft +**Language:** English +**Product:** Chanora +**Repo path:** `docs/governance/poc-results-summary.md` + +--- + +## 1. Purpose + +This document is the single top-level entry point summarising the +outcome of the technical proof-of-concept (PoC) phase defined by +[`docs/architecture/proof-of-concept-plan.md`](../architecture/proof-of-concept-plan.md). + +It exists so that reviewers (security, audit, baseline-approval) can +read one page and follow pointers to evidence, rather than having to +crawl six `VERIFICATION.md` files under `poc/`. + +This summary records facts as of **2026-05-13**. + +## 2. Status table + +| Spike | PoC plan exit criterion | Status | Evidence | +|---|---|---|---| +| `flutter_rust_bridge_hello` | Flutter can call Rust and receive event stream data | **PASS** | `poc/flutter_rust_bridge_hello/VERIFICATION.md` | +| `tsclientlib-connect-spike` | Rust can connect to a compatible server/test double | **PASS** | `poc/tsclientlib-connect-spike/VERIFICATION.md` | +| `secure-storage-spike` | Secret write/read/delete works through platform secure storage | **PASS (Linux only)** | `poc/secure-storage-spike/VERIFICATION.md` | +| `sqlite-storage-spike` | Schema, migration, and repository pattern are demonstrated | **PASS** | `poc/sqlite-storage-spike/VERIFICATION.md` | +| `diagnostics-redaction-spike` | Password and identity-secret samples are redacted | **PASS** (REDACT-TC-001..010 covered) | `poc/diagnostics-redaction-spike/VERIFICATION.md` | +| `audio-capture-playback-spike` | Capture/playback works on at least one desktop **and** one mobile target | **PARTIAL PASS** — desktop met, mobile **not** verified | `poc/audio-capture-playback-spike/VERIFICATION.md` | + +Aggregate test count across the PoCs: **44 tests + 1 live-server CLI +run + 1 audio-stack CLI round-trip**, all passing in the recorded +runs. + +## 3. Toolchain exercised + +| Tool | Version | +|---|---| +| Rust toolchain | stable 1.95.0 (59807616e 2026-04-14) | +| Flutter SDK | 3.41.9 stable (Dart 3.11.5) | +| `flutter_rust_bridge` (Rust + Dart) and codegen | 2.12.0 | +| `tsclientlib` | git `04aa2491` (no published crates.io release) | +| `cpal` | 0.16 | +| `rusqlite` | 0.32 (bundled) | +| `keyring` | 3.6.3 (sync-secret-service + linux-native) | +| `linux-keyutils` | 0.2.5 | +| `regex` / `serde` / `serde_json` | 1 | +| Host OS for verification | Linux (Arch, kernel 7.0.5-arch1-1, x86_64) | +| Host audio server | PipeWire 1.6.4 (via pcm_pipewire ALSA plugin) | +| Host Secret Service backend | gnome-keyring (default collection observed locked; kernel keyutils backend used for hermetic tests) | + +## 4. Owner-confirmed decisions arising from the PoC phase + +Recorded in [`docs/governance/product-decision-register.md`](product-decision-register.md) at version 0.9.3: + +| Decision | Status | Closed by | +|---|---|---| +| **DEC-014** typed bridge | Accepted (`flutter_rust_bridge` 2.x pinned) | `flutter_rust_bridge_hello` | +| **DEC-013.1** SQLite crate | Accepted (`rusqlite` bundled) | `sqlite-storage-spike` | +| **DEC-013.2** Linux secure-storage backend policy | Accepted (Secret Service preferred, keyutils fallback) | `secure-storage-spike` | +| **DEC-011.1** audio crate | Accepted (desktop: `cpal`) / Deferred (mobile) | `audio-capture-playback-spike` (desktop half only) | +| **DEC-022** canonical implementation directory layout | Accepted (README sketch — `apps/chanora_flutter/`, `core/chanora_core/`, `crates/chanora_*`) | Owner ruling on 2026-05-13 | +| **DEC-020** license | Open / Deferred | Owner deferred 2026-05-13 — **remains a public-release blocker** | + +The remaining DEC-001..012, DEC-015..019, DEC-021 are still in +status "Proposed / Owner Confirmation Required" and need owner +attention as a separate exercise — they are unaffected by the PoCs. + +## 5. Audit-report coverage + +| Audit ID | Verified by | Audit-report row updated? | +|---|---|---| +| SS-AUD-001 (identity secret absent from local DB) | `secure-storage-spike` | Yes — `docs/security/secure-storage-audit-report.md` §4 v0.9.3 | +| SS-AUD-002 (server password absent from local DB) | `secure-storage-spike` | Yes | +| SS-AUD-003 (no secrets in logs) | `secure-storage-spike` + cross-ref `diagnostics-redaction-spike` | Yes | +| SS-AUD-004 (no secrets in diagnostic export) | `diagnostics-redaction-spike` REDACT-TC-008 | Yes | +| SS-AUD-005 (safe error on backend failure) | `secure-storage-spike` (test + live CLI fallback) | Yes | +| SS-AUD-006 (delete removes entry) | `secure-storage-spike` | Yes | +| SS-AUD-007 (per-platform documentation) | Linux only — partial | Yes (status: Partial) | +| SS-AUD-008 (migration path safety) | Pending (depends on product `chanora_storage`) | Yes (status: Pending) | +| SS-TC-001 (Windows) | Not run | Status: Deferred | +| SS-TC-002 (macOS) | Not run | Status: Deferred | +| SS-TC-003 (Linux) | `secure-storage-spike` | **PoC Pass** | +| SS-TC-004 (Android) | Not run | Status: Deferred | +| SS-TC-005 (iOS) | Not run | Status: Deferred | +| REDACT-TC-001..010 | `diagnostics-redaction-spike` (12/12) | Yes — `docs/security/diagnostic-redaction-audit-report.md` §4 v0.9.3 | +| Export bundle policy §5 (all rows) | `diagnostics-redaction-spike` | Yes — §5 v0.9.3 | + +## 6. Open risks and gaps + +| ID | Risk | Owner | Recommended close path | +|---|---|---|---| +| RISK-PoC-001 | Mobile audio (Android Oboe / iOS AVAudioEngine) is not verified. The PoC plan's audio exit criterion is only half met. | Audio Owner + Mobile Owner | Spike on Android emulator and iOS device before `chanora_audio` is scaffolded; or accept the risk and discover it during product integration (not recommended). | +| RISK-PoC-002 | Windows / macOS / iOS / Android secure-storage adapters not implemented. SS-TC-001/002/004/005 unverified. | Platform Owners | Per-platform adapter spike or first-implementation-in-`chanora_storage` with the audit checks re-run on each target. | +| RISK-PoC-003 | License (DEC-020) deferred. Blocks public/store release. | Product Owner + Legal | Owner ruling. | +| RISK-PoC-004 | DEC-001..012, 015..019, 021 still in Proposed status. They do not block PoC code but do block any baseline-approval gate. | Product Owner | Independent owner review of the decision register. | +| RISK-PoC-005 | Production code does not exist yet. README's "Implementation status: Not production-ready" remains accurate. | Software Architect | Promote PoC code into `apps/` and `crates/` per DEC-022 only after RISK-PoC-003/004 are closed or explicitly accepted. | + +## 7. Non-promotion reminder + +Per `proof-of-concept-plan.md` §4: **a PoC is not product code unless +explicitly promoted.** Nothing under `poc/` should be imported by +the future `apps/chanora_flutter` or `crates/chanora_*` trees +without an explicit promotion record per spike. + +## 8. Change History + +| Version | Date | Description | +|---|---|---| +| 0.1.0 | 2026-05-14 | Initial PoC results summary. Records the outcome of the first PoC batch (5 PASS, 1 PARTIAL), the toolchain versions exercised, the owner-confirmed decisions, audit-report coverage, and the open risks. | diff --git a/docs/governance/product-decision-register.md b/docs/governance/product-decision-register.md index cfb568a..2470ad3 100644 --- a/docs/governance/product-decision-register.md +++ b/docs/governance/product-decision-register.md @@ -1,8 +1,8 @@ -# CHANORA_CFG_Product_Decision_Register_v0.9.2.2.1 +# CHANORA_CFG_Product_Decision_Register_v0.9.3.0.0 **Document type:** Configuration / Product Decision Register -**Version:** 0.9.2 +**Version:** 0.9.3 **Status:** Baseline Candidate **Language:** English **Product:** Chanora @@ -38,16 +38,20 @@ A decision marked **Proposed / Owner Confirmation Required** is a recommended de | DEC-009 | Noise suppression default state | Enabled by default, with user setting to disable | Proposed / Owner Confirmation Required | Audio Owner + Product Owner | Improves typical voice quality but may affect voice naturalness and CPU usage. | | DEC-010 | High-pass filter default state | Enabled by default | Proposed / Owner Confirmation Required | Audio Owner | Removes low-frequency rumble and usually improves speech capture. | | DEC-011 | Audio processing implementation path | Use platform-native audio processing first where available; use Rust/WebRTC-style processing as controlled fallback or later architecture option | Proposed / Owner Confirmation Required | Software Architect + Audio Owner | Controls architecture, latency, CPU use, platform compatibility, and testing. | +| DEC-011.1 | Audio crate choice | `cpal` for desktop (empirically verified on Linux by `poc/audio-capture-playback-spike` on 2026-05-13); mobile crate(s) TBD pending Android/iOS spike | Accepted (desktop) / Deferred (mobile) | Software Architect + Audio Owner | Pins the desktop audio dependency; mobile remains an open risk surface. | | DEC-012 | Official SDK / trademark / licensing review | Public/store release is blocked until legal confirms TeamSpeak non-affiliation wording, trademark usage, OSS licenses, and `tsclientlib` license posture | Proposed / Owner Confirmation Required | Legal / Compliance + Product Owner | Public release risk and store metadata risk. | | DEC-013 | Local database choice | Use SQLite or equivalent embedded local database for non-secret local state; secrets remain in platform secure storage | Proposed / Owner Confirmation Required | Software Architect + Storage Owner | Controls storage schema, migrations, backup/delete policy, and portability. | -| DEC-014 | Bridge choice | Use a stable typed Flutter/Rust bridge with generated or schema-controlled DTOs; default to `flutter_rust_bridge` unless prototype proves a better option | Proposed / Owner Confirmation Required | Software Architect | Controls API stability, maintainability, async event flow, and long-term code generation. | +| DEC-013.1 | SQLite crate | `rusqlite` with the `bundled` feature (SQLite statically linked into the binary; no system libsqlite3 dependency); verified by `poc/sqlite-storage-spike` on 2026-05-13 | Accepted | Software Architect + Storage Owner | Pins the embedded-DB dependency; locks reproducibility. | +| DEC-013.2 | Linux secure-storage backend policy | Prefer Secret Service (libsecret / gnome-keyring / kwallet / KeePassXC) on Linux; if the default collection is locked or D-Bus is unavailable, fall back to kernel keyutils with a clear user notice. Both backends are "equivalent" per SysRS-053 / SysRS-162; verified by `poc/secure-storage-spike` on 2026-05-13 | Accepted | Software Architect + Storage Owner + Security Reviewer | Closes the SysRS-162 ambiguity surfaced by the secure-storage PoC. | +| DEC-014 | Bridge choice | Use a stable typed Flutter/Rust bridge with generated or schema-controlled DTOs; **`flutter_rust_bridge` 2.x pinned** (empirically verified at 2.12.0 by `poc/flutter_rust_bridge_hello` on 2026-05-13) | Accepted | Software Architect | Controls API stability, maintainability, async event flow, and long-term code generation. | | DEC-015 | Product language for MVP | English-only product UI for MVP; i18n-ready architecture; server-provided content preserved and not translated | Proposed / Owner Confirmation Required | Product Owner | Controls localization scope and release schedule. | | DEC-016 | Diagnostics upload policy | No automatic upload for MVP; user-initiated local diagnostic export only | Proposed / Owner Confirmation Required | Product Owner + Legal + Security | Controls privacy policy, support workflow, and security review scope. | | DEC-017 | Crash reporting | Disabled for MVP unless explicit opt-in provider and privacy policy are approved | Proposed / Owner Confirmation Required | Product Owner + Legal + Security | Avoids privacy/legal complexity before public release. | | DEC-018 | Public product name | Chanora | Proposed / Owner Confirmation Required | Product Owner | Branding and legal identity. | | DEC-019 | Public non-affiliation statement | Use legal-approved wording; draft: “Chanora is independent and is not affiliated with, endorsed by, sponsored by, or officially associated with TeamSpeak.” | Proposed / Legal Confirmation Required | Legal / Compliance | Required for public release and store metadata. | | DEC-021 | Apple App Store submission SDK | Use Xcode 26 or later and the iOS 26 / iPadOS 26 SDK or later for App Store submission on or after 2026-04-28, unless Apple publishes a newer applicable requirement before upload | Proposed / Owner Confirmation Required | iOS Owner + Release Manager | Controls App Store Connect upload eligibility and release pipeline. | -| DEC-020 | License model | TBD by owner; no public release until license model and OSS obligations are confirmed | Open | Product Owner + Legal | Business and OSS compliance decision. | +| DEC-020 | License model | TBD by owner; no public release until license model and OSS obligations are confirmed | Open | Product Owner + Legal | Business and OSS compliance decision. Explicitly deferred on 2026-05-13 by owner; remains a public-release blocker. | +| DEC-022 | Canonical implementation directory layout | Accept the README's sketch as canonical: `apps/chanora_flutter/`, `core/chanora_core/`, `crates/chanora_protocol/`, `crates/chanora_audio/`, `crates/chanora_state/`, `crates/chanora_storage/`, `crates/chanora_diagnostics/`, `crates/chanora_bridge/`. Matches SAD §7.2 module decomposition | Accepted | Software Architect | Unblocks product-crate scaffolding; was not formalised by any prior doc. | ## 4. Recommended MVP Defaults @@ -119,10 +123,14 @@ A decision marked **Proposed / Owner Confirmation Required** is a recommended de | DEC-009 | Audio Owner / Product Owner | Noise suppression default | Proposed / Owner Confirmation Required | TBD | Recommended: enabled. | | DEC-010 | Audio Owner | High-pass filter default | Proposed / Owner Confirmation Required | TBD | Recommended: enabled. | | DEC-011 | Software Architect / Audio Owner | Audio processing path | Proposed / Owner Confirmation Required | TBD | Recommended: platform-native first. | +| DEC-011.1 | Software Architect / Audio Owner | Audio crate (desktop / mobile) | Accepted (desktop: `cpal`) / Deferred (mobile) | 2026-05-13 | Closed by `poc/audio-capture-playback-spike` for desktop. Mobile crate TBD pending mobile spike. | | DEC-012 | Legal / Compliance | SDK/trademark/licensing review | Proposed / Owner Confirmation Required | TBD | Required before public/store release. | | DEC-013 | Software Architect / Storage Owner | Local database | Proposed / Owner Confirmation Required | TBD | Recommended: SQLite or equivalent. | -| DEC-014 | Software Architect | Bridge choice | Proposed / Owner Confirmation Required | TBD | Recommended: typed bridge; default candidate `flutter_rust_bridge`. | -| DEC-020 | Product Owner / Legal | License model | Open | TBD | Must be decided before public release. | +| DEC-013.1 | Software Architect / Storage Owner | SQLite crate | Accepted (`rusqlite` bundled) | 2026-05-13 | Closed by `poc/sqlite-storage-spike` 11/11. | +| DEC-013.2 | Software Architect / Storage Owner / Security Reviewer | Linux secure-storage backend policy | Accepted (Secret Service preferred, keyutils fallback) | 2026-05-13 | Closed by `poc/secure-storage-spike` 6/6. Resolves SysRS-053 / SysRS-162 ambiguity. | +| DEC-014 | Software Architect | Bridge choice | Accepted (`flutter_rust_bridge` 2.x pinned) | 2026-05-13 | Closed by `poc/flutter_rust_bridge_hello` 3/3. | +| DEC-020 | Product Owner / Legal | License model | Open / Deferred | 2026-05-13 | Explicitly deferred by owner; remains a public-release blocker. | +| DEC-022 | Software Architect | Canonical implementation directory layout | Accepted (README sketch) | 2026-05-13 | Closes the absence flagged during PoC review. | ## 8. Change History @@ -143,3 +151,10 @@ A decision marked **Proposed / Owner Confirmation Required** is a recommended de | Version | Date | Description | |---|---|---| | 0.9.2 | 2026-05-14 | Corrected Apple App Store Connect upload gate to 2026-04-28 and checked full-package naming, references, and coverage. | + + +## Baseline Candidate 0.9.3 Update + +| Version | Date | Description | +|---|---|---| +| 0.9.3 | 2026-05-14 | Recorded owner-confirmed decisions surfaced during the initial PoC phase: DEC-014 Accepted (`flutter_rust_bridge` 2.x pinned); added DEC-011.1 Accepted for desktop (`cpal`) / Deferred for mobile; added DEC-013.1 Accepted (`rusqlite` bundled); added DEC-013.2 Accepted (Linux Secret Service preferred with keyutils fallback); added DEC-022 Accepted (canonical implementation directory layout per README sketch and SAD §7.2); DEC-020 explicitly Deferred and remains a public-release blocker. Evidence pointers: `poc/flutter_rust_bridge_hello/VERIFICATION.md`, `poc/secure-storage-spike/VERIFICATION.md`, `poc/sqlite-storage-spike/VERIFICATION.md`, `poc/audio-capture-playback-spike/VERIFICATION.md`. | diff --git a/docs/security/diagnostic-redaction-audit-report.md b/docs/security/diagnostic-redaction-audit-report.md index ae7628b..28c4abf 100644 --- a/docs/security/diagnostic-redaction-audit-report.md +++ b/docs/security/diagnostic-redaction-audit-report.md @@ -1,7 +1,7 @@ -# Sec Diagnostic Redaction Audit Report V0.9.2.2.1 +# Sec Diagnostic Redaction Audit Report V0.9.3.0.0 **Document type:** Security / Diagnostic Redaction Audit Report -**Version:** 0.9.2 +**Version:** 0.9.3 **Status:** Baseline Candidate **Language:** English **Product:** Chanora @@ -42,37 +42,39 @@ This report records evidence that Chanora logs and diagnostic exports do not lea | Test ID | Input | Expected output | Status | Evidence | |---|---|---|---|---| -| REDACT-TC-001 | Server password in connection data | Password replaced by `[REDACTED]` | TBD | TBD | -| REDACT-TC-002 | Identity secret in storage error | Secret absent | TBD | TBD | -| REDACT-TC-003 | Server URL with password-like field | Secret part redacted | TBD | TBD | -| REDACT-TC-004 | Chat text in diagnostic export | Excluded by default | TBD | TBD | -| REDACT-TC-005 | Channel name with Unicode | Preserved only if permitted; otherwise redacted safely | TBD | TBD | -| REDACT-TC-006 | Nickname with Unicode | Preserved only if permitted; otherwise redacted safely | TBD | TBD | -| REDACT-TC-007 | Local file path | User-identifying segments redacted or minimized | TBD | TBD | -| REDACT-TC-008 | Diagnostic bundle with mixed sensitive fields | All sensitive fields redacted | TBD | TBD | -| REDACT-TC-009 | Long hostile protocol string | Truncated or safely escaped | TBD | TBD | -| REDACT-TC-010 | Multilingual safe diagnostic text | Unicode preserved | TBD | TBD | +| REDACT-TC-001 | Server password in connection data | Password replaced by `[REDACTED]` | PoC Pass | `poc/diagnostics-redaction-spike/tests/redaction.rs::redact_tc_001_server_password_in_connection_data` | +| REDACT-TC-002 | Identity secret in storage error | Secret absent | PoC Pass | `poc/diagnostics-redaction-spike/tests/redaction.rs::redact_tc_002_identity_secret_in_storage_error` (via `KnownSecretRegistry`) | +| REDACT-TC-003 | Server URL with password-like field | Secret part redacted | PoC Pass | `poc/diagnostics-redaction-spike/tests/redaction.rs::redact_tc_003_server_url_with_password_field` — only the password value is redacted, the host and other query params keep flowing | +| REDACT-TC-004 | Chat text in diagnostic export | Excluded by default | PoC Pass | `poc/diagnostics-redaction-spike/tests/redaction.rs::redact_tc_004_chat_text_excluded_by_default` — default policy sets `include_chat = false` | +| REDACT-TC-005 | Channel name with Unicode | Preserved only if permitted; otherwise redacted safely | PoC Pass | `poc/diagnostics-redaction-spike/tests/redaction.rs::redact_tc_005_channel_name_with_unicode_excluded_by_default` — default policy excludes; UTF-8 preservation verified in TC-010 | +| REDACT-TC-006 | Nickname with Unicode | Preserved only if permitted; otherwise redacted safely | PoC Pass | `poc/diagnostics-redaction-spike/tests/redaction.rs::redact_tc_006_nickname_with_unicode_preserved_in_safe_field` | +| REDACT-TC-007 | Local file path | User-identifying segments redacted or minimized | PoC Pass | `poc/diagnostics-redaction-spike/tests/redaction.rs::redact_tc_007_local_file_paths_user_segment_minimized` — Linux `/home//`, Windows `C:\Users\\`, macOS `/Users//` all minimized | +| REDACT-TC-008 | Diagnostic bundle with mixed sensitive fields | All sensitive fields redacted | PoC Pass | `poc/diagnostics-redaction-spike/tests/redaction.rs::redact_tc_008_diagnostic_bundle_with_mixed_sensitive_fields` — whole-bundle JSON scan finds no plaintext | +| REDACT-TC-009 | Long hostile protocol string | Truncated or safely escaped | PoC Pass | `poc/diagnostics-redaction-spike/tests/redaction.rs::redact_tc_009_long_hostile_protocol_string_truncated` — `MAX_PROTOCOL_STRING_LEN = 256` cap with `…[truncated]` marker | +| REDACT-TC-010 | Multilingual safe diagnostic text | Unicode preserved | PoC Pass | `poc/diagnostics-redaction-spike/tests/redaction.rs::redact_tc_010_multilingual_safe_text_preserved` — Chinese, Japanese, Korean, and Latin-diacritic text preserved verbatim | ## 5. Export Bundle Contents | Bundle item | Included? | Redaction rule | Status | |---|---|---|---| -| App version | Yes | None | TBD | -| Build number | Yes | None | TBD | -| Platform info | Yes | Minimize device details | TBD | -| Connection state | Yes | No secrets | TBD | -| Server address | TBD | Redact/minimize | TBD | -| Channel tree | TBD | Redact/minimize | TBD | -| Chat history | No by default | Exclude unless explicit policy changes | TBD | -| Logs | Yes | Redacted | TBD | -| Audio diagnostics | Yes | No audio content | TBD | -| Secure storage data | No | Never include | TBD | +| App version | Yes | None | PoC Pass (`DiagnosticBundle.app_version` preserved verbatim) | +| Build number | Yes | None | PoC Pass (`DiagnosticBundle.build_number` preserved verbatim) | +| Platform info | Yes | Minimize device details | PoC Pass — flows through `Redactor::redact_text`, so embedded paths/usernames are minimized | +| Connection state | Yes | No secrets | PoC Pass — flows through `Redactor::redact_text` | +| Server address | Yes (redacted) | Redact/minimize | PoC Pass — passwords inside `ts3server://` URLs redacted | +| Channel tree | No by default | Redact/minimize | PoC Pass — default `include_channel_tree = false` | +| Chat history | No by default | Exclude unless explicit policy changes | PoC Pass — default `include_chat = false` | +| Logs | Yes | Redacted | PoC Pass — each log line flows through `Redactor::redact_text` | +| Audio diagnostics | Yes | No audio content | PoC Pass — only device names are exported; no PCM | +| Secure storage data | No | Never include | PoC Pass by construction — the redactor has no path that reads from `SecretStorageRepository`; the host application must never put secret material into the bundle in the first place | ## 6. Findings | Finding ID | Severity | Description | Status | Owner | |---|---|---|---|---| -| TBD | TBD | TBD | TBD | TBD | +| REDACT-FIND-001 | Informational | The PoC regex catalogue covers the documented audit matrix but is not exhaustive. Production `chanora_diagnostics` should add fuzz testing and adversarial inputs (e.g. base64 lookalikes, unicode confusables, regex evasion). | Open | Security Reviewer + `chanora_diagnostics` owner | +| REDACT-FIND-002 | Informational | The PoC redactor is a post-processor over strings. Production code should wire the redactor as a `tracing-subscriber` layer so redaction happens at write-time, not by re-walking text afterward. | Open — to be addressed when `chanora_diagnostics` is scaffolded | `chanora_diagnostics` owner | +| REDACT-FIND-003 | Informational | The `KnownSecretRegistry` defence-in-depth requires the secure-storage layer to register secrets when they materialise. The cross-spike contract is documented but not yet enforced by any product code. | Open — to be enforced by `chanora_storage` calling into `chanora_diagnostics`. | `chanora_storage` + `chanora_diagnostics` owners | ## 7. Approval @@ -101,3 +103,10 @@ This report records evidence that Chanora logs and diagnostic exports do not lea | Version | Date | Description | |---|---|---| | 0.9.2 | 2026-05-14 | Corrected Apple App Store Connect upload gate to 2026-04-28 and checked full-package naming, references, and coverage. | + + +## Baseline Candidate 0.9.3 Update + +| Version | Date | Description | +|---|---|---| +| 0.9.3 | 2026-05-14 | Recorded PoC empirical evidence: REDACT-TC-001..010 status set to PoC Pass with evidence pointers to `poc/diagnostics-redaction-spike/tests/redaction.rs`. Export bundle policy §5 populated for every row. Findings REDACT-FIND-001..003 added (regex coverage limits, tracing-layer integration gap, KnownSecretRegistry cross-spike contract). | diff --git a/docs/security/secure-storage-audit-report.md b/docs/security/secure-storage-audit-report.md index 88b5e4f..932d7f3 100644 --- a/docs/security/secure-storage-audit-report.md +++ b/docs/security/secure-storage-audit-report.md @@ -1,7 +1,7 @@ -# Sec Secure Storage Audit Report V0.9.2.2.1 +# Sec Secure Storage Audit Report V0.9.3.0.0 **Document type:** Security / Secure Storage Audit Report -**Version:** 0.9.2 +**Version:** 0.9.3 **Status:** Baseline Candidate **Language:** English **Product:** Chanora @@ -24,40 +24,42 @@ This report records evidence that Chanora stores secrets using platform secure s | Platform | Secure storage mechanism | Test status | Evidence | Result | |---|---|---|---|---| -| Windows | TBD | TBD | TBD | TBD | -| macOS | TBD | TBD | TBD | TBD | -| Linux | TBD | TBD | TBD | TBD | -| Android | TBD | TBD | TBD | TBD | -| iOS | TBD | TBD | TBD | TBD | +| Windows | DPAPI / Windows Credential Manager (per DEC-013 / SysRS-158) — adapter not yet implemented | Not started | n/a | Deferred to product `chanora_storage` | +| macOS | Keychain (per SysRS-159) — adapter not yet implemented | Not started | n/a | Deferred to product `chanora_storage` | +| Linux | Secret Service (libsecret) preferred; kernel keyutils fallback per DEC-013.2 | PoC Pass | `poc/secure-storage-spike/VERIFICATION.md`; six audit tests PASS via keyutils backend; CLI run additionally observed Secret-Service-locked → keyutils fallback live | PoC PASS; product audit pending | +| Android | Android Keystore (per SysRS-161) — adapter not yet implemented | Not started | n/a | Deferred to product `chanora_storage` | +| iOS | Keychain (per SysRS-160) — adapter not yet implemented | Not started | n/a | Deferred to product `chanora_storage` | ## 4. Audit Checks | Check ID | Check | Expected result | Status | Evidence | |---|---|---|---|---| -| SS-AUD-001 | Identity secret is not stored in local DB. | Pass | TBD | TBD | -| SS-AUD-002 | Server password is not stored in local DB. | Pass | TBD | TBD | -| SS-AUD-003 | Secret values are not written to application logs. | Pass | TBD | TBD | -| SS-AUD-004 | Secret values are not included in diagnostic export. | Pass | TBD | TBD | -| SS-AUD-005 | Secure storage failure returns safe error. | Pass | TBD | TBD | -| SS-AUD-006 | Secret deletion removes secure-storage entry. | Pass | TBD | TBD | -| SS-AUD-007 | Platform-specific secure storage is documented. | Pass | TBD | TBD | -| SS-AUD-008 | Migration or import path does not expose secrets. | Pass | TBD | TBD | +| SS-AUD-001 | Identity secret is not stored in local DB. | Pass | PoC Pass (Linux) | `poc/secure-storage-spike/tests/audit.rs::ss_aud_001_identity_secret_absent_from_local_db` — raw SQLite file scanned for plaintext markers; only the lookup name appears. | +| SS-AUD-002 | Server password is not stored in local DB. | Pass | PoC Pass (Linux) | `poc/secure-storage-spike/tests/audit.rs::ss_aud_002_server_password_absent_from_local_db` — distinct plaintext marker scan. | +| SS-AUD-003 | Secret values are not written to application logs. | Pass | PoC Pass (Linux) + cross-spike | `poc/secure-storage-spike/tests/audit.rs::ss_aud_003_secret_values_not_in_logs` — captured `tracing` output contains `` markers; never the plaintext. Cross-referenced by `poc/diagnostics-redaction-spike` REDACT-TC-002. | +| SS-AUD-004 | Secret values are not included in diagnostic export. | Pass | PoC Pass | Covered by `poc/diagnostics-redaction-spike/tests/redaction.rs::redact_tc_008_diagnostic_bundle_with_mixed_sensitive_fields` — whole-bundle JSON scan finds no plaintext. | +| SS-AUD-005 | Secure storage failure returns safe error. | Pass | PoC Pass (Linux) | `poc/secure-storage-spike/tests/audit.rs::ss_aud_005_safe_error_on_missing_entry`. Reinforced by the CLI driver run: a real locked gnome-keyring collection produced a typed `Backend` error containing no secret material, which the application then routed to the fallback adapter (DEC-013.2). | +| SS-AUD-006 | Secret deletion removes secure-storage entry. | Pass | PoC Pass (Linux) | `poc/secure-storage-spike/tests/audit.rs::ss_aud_006_delete_removes_entry` — second delete returns `NotFound`, not silent success. | +| SS-AUD-007 | Platform-specific secure storage is documented. | Pass | Partial | Linux documented in `poc/secure-storage-spike/README.md` and DEC-013.2. Windows/macOS/Android/iOS remain to be documented when adapters land in `chanora_storage`. | +| SS-AUD-008 | Migration or import path does not expose secrets. | Pass | Pending | No migration / import path exists yet; depends on product `chanora_storage` schema design (cross-references DEC-013.1 and `poc/sqlite-storage-spike`). | ## 5. Test Cases | Test ID | Platform | Procedure | Expected result | Actual result | Status | |---|---|---|---|---|---| -| SS-TC-001 | Windows | Save identity secret, inspect local DB/logs/export. | Secret absent from DB/logs/export. | TBD | TBD | -| SS-TC-002 | macOS | Save identity secret, inspect local DB/logs/export. | Secret absent from DB/logs/export. | TBD | TBD | -| SS-TC-003 | Linux | Save identity secret, inspect local DB/logs/export. | Secret absent from DB/logs/export. | TBD | TBD | -| SS-TC-004 | Android | Save identity secret, inspect app storage/logs/export. | Secret absent from DB/logs/export. | TBD | TBD | -| SS-TC-005 | iOS | Save identity secret, inspect app storage/logs/export. | Secret absent from DB/logs/export. | TBD | TBD | +| SS-TC-001 | Windows | Save identity secret, inspect local DB/logs/export. | Secret absent from DB/logs/export. | Not run — Windows adapter not implemented in PoC | Deferred | +| SS-TC-002 | macOS | Save identity secret, inspect local DB/logs/export. | Secret absent from DB/logs/export. | Not run — macOS adapter not implemented in PoC | Deferred | +| SS-TC-003 | Linux | Save identity secret, inspect local DB/logs/export. | Secret absent from DB/logs/export. | Set / get / delete round-trip verified via keyutils backend; raw SQLite file scan confirmed plaintext absence; `tracing` log capture confirmed log absence. | **PoC Pass** | +| SS-TC-004 | Android | Save identity secret, inspect app storage/logs/export. | Secret absent from DB/logs/export. | Not run — Android adapter not implemented in PoC | Deferred | +| SS-TC-005 | iOS | Save identity secret, inspect app storage/logs/export. | Secret absent from DB/logs/export. | Not run — iOS adapter not implemented in PoC | Deferred | ## 6. Findings | Finding ID | Severity | Description | Status | Owner | |---|---|---|---|---| -| TBD | TBD | TBD | TBD | TBD | +| SS-FIND-001 | Informational | SysRS-053 / SysRS-162 ("Secret Service, libsecret, or equivalent") admitted both Secret Service and kernel keyutils as Linux backends. The PoC surfaced this ambiguity. | Resolved by DEC-013.2 on 2026-05-13 (Secret Service preferred, keyutils fallback). | Software Architect + Security Reviewer | +| SS-FIND-002 | Informational | Kernel keyutils requires a valid session keyring; cargo-test under non-interactive shells inherits an expired `_ses` and must be wrapped with `keyctl session -`. Production code on a graphical session inherits a valid session from PAM. | Documented in `poc/secure-storage-spike/README.md` and `VERIFICATION.md`. | Software Architect | +| SS-FIND-003 | Open | Windows / macOS / iOS / Android adapters not implemented; SS-TC-001/002/004/005 unverified. | Open — to be closed by per-platform adapter spikes or by the product `chanora_storage` implementation. | Platform Owners | ## 7. Approval @@ -86,3 +88,10 @@ This report records evidence that Chanora stores secrets using platform secure s | Version | Date | Description | |---|---|---| | 0.9.2 | 2026-05-14 | Corrected Apple App Store Connect upload gate to 2026-04-28 and checked full-package naming, references, and coverage. | + + +## Baseline Candidate 0.9.3 Update + +| Version | Date | Description | +|---|---|---| +| 0.9.3 | 2026-05-14 | Recorded PoC empirical evidence: SS-AUD-001/002/003/005/006 status set to PoC Pass with evidence pointers; SS-AUD-004 cross-referenced to the diagnostics-redaction PoC; SS-TC-003 Linux Actual Result populated and Status set to PoC Pass. Added findings SS-FIND-001 (closed by DEC-013.2), SS-FIND-002 (keyutils session caveat), SS-FIND-003 (non-Linux adapters still open). Non-Linux test cases SS-TC-001/002/004/005 remain Deferred. |