@beyondwork/docx-react-component 1.0.0

package/docs/plans/waves/deferred/wave-encrypted-intake.md

@@ -0,0 +1,451 @@
+# Deferred Wave - Encrypted Intake And Decrypt Baseline
+
+**Commit message**: `Build: baseline encrypted intake and decrypt flow`
+
+## Component promotions
+
+- encrypted-document-intake-and-decrypt: baseline-proved
+
+## Scope note
+
+This draft is not part of the active numbered wave sequence.
+
+It preserves the previously proposed component-owned encrypted-intake slice in case ownership ever moves back inside the editor.
+
+This wave owns:
+
+- password-to-open Office container detection
+- decrypt-before-import routing
+- runtime-owned password challenge state
+- component-managed password UX
+- explicit unencrypted export warning for decrypted sessions
+- the separate encrypted-fixture proof corpus
+
+This wave does not own:
+
+- host-managed password continuation as public API
+- re-encrypt-on-export
+- IRM or policy encryption
+- live Railway pilot claims
+
+## Context7 defaults
+
+- bundle: word-editor-ooxml
+- query: "ECMA-376 encrypted Office intake, decrypt-before-import invariants, and main-thread password-safe browser flows"
+
+## Agent A0: cont-QA
+
+### Role prompts
+
+- docs/agents/wave-cont-qa-role.md
+
+### Executor
+
+- profile: deep-review
+
+### Context7
+
+- bundle: word-editor-testing
+- query: "encrypted intake proof completeness, password redaction rules, and no-silent-downgrade guarantees"
+
+### Prompt
+
+```text
+Primary goal:
+- Refuse closure unless encrypted intake is baseline-proved with exact fixture evidence and secret-handling rules stay explicit.
+
+Required context before coding:
+- Read docs/reference/repository-guidance.md.
+- Read docs/research/agent-context-sources.md.
+- Read docs/reference/deep-research-report (15).md.
+- Read docs/plans/current-state.md and docs/plans/waves/wave-7.md.
+- Read docs/plans/waves/deferred/encrypted-intake-contracts.md.
+
+Specific expectations:
+- block closure if the normal OOXML importer can receive encrypted bytes
+- block closure if passwords can leak into React state, persisted snapshots, or surfaced diagnostics
+- block closure if the wave overclaims host-managed password APIs or re-encrypt-on-export
+
+File ownership (only touch these paths):
+- docs/plans/waves/reviews/wave-8-cont-qa.md
+```
+
+## Agent A8: Integration Steward
+
+### Role prompts
+
+- docs/agents/wave-integration-role.md
+
+### Executor
+
+- profile: deep-review
+
+### Context7
+
+- bundle: word-editor-runtime
+- query: "integration across sniff routing, decrypt services, runtime import state, and export-warning UX"
+
+### Prompt
+
+```text
+Primary goal:
+- Reconcile the encrypted intake route with the existing runtime, OOXML importer, and preservation pipeline without widening the public API unnecessarily.
+
+Required context before coding:
+- Read docs/reference/repository-guidance.md.
+- Read docs/research/agent-context-sources.md.
+- Read docs/plans/master-plan.md, docs/plans/current-state.md, and docs/plans/waves/deferred/wave-encrypted-intake.md.
+- Read docs/plans/waves/deferred/encrypted-intake-contracts.md.
+
+Specific expectations:
+- block closure if encrypted intake forks a second canonical import path
+- block closure if password state lives in React-owned snapshots instead of runtime-owned redacted state
+- block closure if export-warning behavior can be bypassed for decrypted sessions
+
+File ownership (only touch these paths):
+- .tmp/main-wave-launcher/integration/wave-8.md
+- .tmp/main-wave-launcher/integration/wave-8.json
+```
+
+## Agent A9: Documentation Steward
+
+### Role prompts
+
+- docs/agents/wave-documentation-role.md
+
+### Executor
+
+- profile: docs-pass
+
+### Context7
+
+- bundle: word-editor-contracts
+- query: "documenting encrypted intake boundaries, unchanged public component surface, and shifted later-wave sequencing"
+
+### Prompt
+
+```text
+Primary goal:
+- Keep the shared-plan docs, public API reference, compliance docs, fixture docs, and component matrix aligned with the encrypted-intake contract.
+
+Required context before coding:
+- Read docs/reference/repository-guidance.md.
+- Read docs/research/agent-context-sources.md.
+- Read docs/reference/deep-research-report (15).md.
+- Read docs/plans/master-plan.md, docs/plans/current-state.md, docs/plans/migration.md, and docs/plans/component-cutover-matrix.md.
+- Read docs/plans/waves/deferred/encrypted-intake-contracts.md.
+
+File ownership (only touch these paths):
+- docs/roadmap.md
+- docs/plans/master-plan.md
+- docs/plans/current-state.md
+- docs/plans/migration.md
+- docs/plans/component-cutover-matrix.md
+- docs/plans/component-cutover-matrix.json
+- docs/reference/public-api.md
+- docs/reference/ooxml-compliance.md
+- test/fixtures/docx/README.md
+- test/fixtures/scenarios/docx/README.md
+- test/fixtures/encrypted-docx/README.md
+```
+
+## Agent A1: Container Sniffing And Route Guard
+
+### Executor
+
+- profile: implement-fast
+- budget.minutes: 45
+
+### Context7
+
+- bundle: word-editor-ooxml
+- query: "ZIP versus CFB detection, EncryptedPackage routing, and fail-safe Office container sniffing"
+
+### Skills
+
+- role-implementation
+- domain-docx-compatibility
+
+### Components
+
+- encrypted-document-intake-and-decrypt
+
+### Exit contract
+
+- completion: authoritative
+- durability: durable
+- proof: integration
+- doc-impact: owned
+
+### Deliverables
+
+- src/io/intake/container-sniffer.ts
+- src/io/intake/encrypted-office-detector.ts
+- src/io/intake/import-router.ts
+- test/io/encrypted-container-sniffer.test.ts
+
+### Prompt
+
+```text
+Primary goal:
+- Land the pre-import route guard that cleanly separates normal OPC `.docx` loads from encrypted Office containers.
+
+Required context before coding:
+- Read docs/reference/repository-guidance.md.
+- Read docs/research/agent-context-sources.md.
+- Read docs/reference/ooxml-compliance.md.
+- Read docs/plans/waves/deferred/encrypted-intake-contracts.md.
+
+Specific expectations:
+- no encrypted bytes may reach the normal OOXML importer
+- unsupported ZIP or CFB cases must fail explicitly instead of falling through
+- keep the route package-first and deterministic
+
+File ownership (only touch these paths):
+- src/io/intake/container-sniffer.ts
+- src/io/intake/encrypted-office-detector.ts
+- src/io/intake/import-router.ts
+- test/io/encrypted-container-sniffer.test.ts
+```
+
+## Agent A2: Office Decrypt Engine
+
+### Executor
+
+- profile: implement-fast
+- budget.minutes: 55
+
+### Context7
+
+- bundle: word-editor-ooxml
+- query: "ECMA-376 Agile and Standard decrypt flows, EncryptionInfo parsing, and main-thread-safe browser crypto"
+
+### Skills
+
+- role-implementation
+- domain-docx-compatibility
+
+### Components
+
+- encrypted-document-intake-and-decrypt
+
+### Exit contract
+
+- completion: authoritative
+- durability: durable
+- proof: integration
+- doc-impact: owned
+
+### Deliverables
+
+- src/io/crypto/office-decryptor.ts
+- src/io/crypto/ms-offcrypto/parse-encryption-info-agile.ts
+- src/io/crypto/ms-offcrypto/parse-encryption-info-standard.ts
+- src/io/crypto/ms-offcrypto/decrypt-encrypted-package.ts
+- test/io/office-decryptor.test.ts
+
+### Prompt
+
+```text
+Primary goal:
+- Land browser-safe decrypt support for ECMA-376 Standard and Agile Office encryption without broadening v1 beyond the repo contract.
+
+Required context before coding:
+- Read docs/reference/repository-guidance.md.
+- Read docs/research/agent-context-sources.md.
+- Read docs/reference/deep-research-report (15).md.
+- Read docs/plans/waves/deferred/encrypted-intake-contracts.md.
+
+Specific expectations:
+- support Standard and Agile only
+- reject RC4, extensible providers, and IRM explicitly
+- clear transient buffers and keep progress reporting secret-free
+
+File ownership (only touch these paths):
+- src/io/crypto/office-decryptor.ts
+- src/io/crypto/ms-offcrypto/parse-encryption-info-agile.ts
+- src/io/crypto/ms-offcrypto/parse-encryption-info-standard.ts
+- src/io/crypto/ms-offcrypto/decrypt-encrypted-package.ts
+- test/io/office-decryptor.test.ts
+```
+
+## Agent A3: Runtime Import State And Security Boundaries
+
+### Executor
+
+- profile: implement-fast
+- budget.minutes: 45
+
+### Context7
+
+- bundle: word-editor-runtime
+- query: "runtime-owned import state machines, cancellation cleanup, and redacted UI projections"
+
+### Skills
+
+- role-implementation
+- domain-editor-architecture
+
+### Components
+
+- encrypted-document-intake-and-decrypt
+
+### Exit contract
+
+- completion: authoritative
+- durability: durable
+- proof: integration
+- doc-impact: owned
+
+### Deliverables
+
+- src/runtime/import/import-state-store.ts
+- src/runtime/import/import-controller.ts
+- src/runtime/import/session-security-manager.ts
+- test/runtime/encrypted-import-state.test.ts
+
+### Prompt
+
+```text
+Primary goal:
+- Make encrypted intake runtime-owned, cancellable, and redacted without leaking password or decrypted-package state into canonical or React surfaces.
+
+Required context before coding:
+- Read docs/reference/repository-guidance.md.
+- Read docs/research/agent-context-sources.md.
+- Read docs/plans/waves/deferred/encrypted-intake-contracts.md.
+- Read docs/plans/waves/specs/wave-1-runtime-contracts.md.
+
+Specific expectations:
+- new source loads abort the old import job cleanly
+- React sees only a redacted projection
+- persisted snapshots must never include password or decrypted raw bytes
+
+File ownership (only touch these paths):
+- src/runtime/import/import-state-store.ts
+- src/runtime/import/import-controller.ts
+- src/runtime/import/session-security-manager.ts
+- test/runtime/encrypted-import-state.test.ts
+```
+
+## Agent A4: Password UX And Export Warning
+
+### Executor
+
+- profile: implement-fast
+- budget.minutes: 45
+
+### Context7
+
+- bundle: word-editor-ui
+- query: "password prompt UX, import progress surfaces, and explicit export warnings for decrypted sessions"
+
+### Skills
+
+- role-implementation
+- domain-legal-review
+
+### Components
+
+- encrypted-document-intake-and-decrypt
+
+### Exit contract
+
+- completion: authoritative
+- durability: durable
+- proof: integration
+- doc-impact: owned
+
+### Deliverables
+
+- src/ui/import/password-modal.tsx
+- src/ui/import/import-progress.tsx
+- src/ui/export/encrypted-export-warning.tsx
+- test/ui/encrypted-import-ui.test.tsx
+
+### Prompt
+
+```text
+Primary goal:
+- Land the baseline component-managed password and export-warning UX without bloating the public API.
+
+Required context before coding:
+- Read docs/reference/repository-guidance.md.
+- Read docs/research/agent-context-sources.md.
+- Read DESIGN.md.
+- Read docs/plans/waves/deferred/encrypted-intake-contracts.md.
+
+Specific expectations:
+- keep the UI calm and explicit
+- do not let React own the authoritative password flow state
+- export from decrypted sessions must warn once per session and allow cancel
+
+File ownership (only touch these paths):
+- src/ui/import/password-modal.tsx
+- src/ui/import/import-progress.tsx
+- src/ui/export/encrypted-export-warning.tsx
+- test/ui/encrypted-import-ui.test.tsx
+```
+
+## Agent A5: Encrypted Proof Bundle
+
+### Executor
+
+- profile: proof-owner
+
+### Context7
+
+- bundle: word-editor-testing
+- query: "encrypted fixture proof, wrong-password retry, cleanup evidence, and export-warning reporting"
+
+### Skills
+
+- role-implementation
+- domain-docx-compatibility
+
+### Components
+
+- encrypted-document-intake-and-decrypt
+
+### Exit contract
+
+- completion: authoritative
+- durability: durable
+- proof: integration
+- doc-impact: owned
+
+### Deliverables
+
+- docs/plans/waves/reviews/wave-8-encrypted-proof.md
+
+### Proof artifacts
+
+- path: .tmp/wave-8-encrypted-intake/sniff-report.json | kind: integration-report | required-for: baseline-proved
+- path: .tmp/wave-8-encrypted-intake/decrypt-fixture-report.json | kind: roundtrip-report | required-for: baseline-proved
+- path: .tmp/wave-8-encrypted-intake/password-ui-proof.json | kind: integration-report | required-for: baseline-proved
+- path: .tmp/wave-8-encrypted-intake/export-warning-report.json | kind: action-report | required-for: baseline-proved
+- path: .tmp/wave-8-encrypted-intake/security-cleanup-report.json | kind: diagnostics-report | required-for: baseline-proved
+
+### Prompt
+
+```text
+Primary goal:
+- Produce the bounded proof bundle that justifies baseline-proved encrypted intake without overclaiming live or host-managed behavior.
+
+Required context before coding:
+- Read docs/reference/repository-guidance.md.
+- Read docs/research/agent-context-sources.md.
+- Read docs/reference/deep-research-report (15).md.
+- Read docs/plans/waves/deferred/encrypted-intake-contracts.md.
+- Read test/fixtures/encrypted-docx/README.md.
+
+Specific expectations:
+- cover at least one Agile and one Standard encrypted fixture
+- prove wrong-password retry, cancel, and unsupported-encryption behavior
+- prove the exporter warning path for decrypted sessions
+- prove that encrypted bytes never reach the normal importer
+
+File ownership (only touch these paths):
+- docs/plans/waves/reviews/wave-8-encrypted-proof.md
+- .tmp/wave-8-encrypted-intake/
+```

package/docs/plans/waves/design/README.md

@@ -0,0 +1,5 @@
+# Wave Design Packets
+
+This directory stores design-steward packets for waves that need an explicit pre-implementation handoff.
+
+The Wave 1 packet is the canonical contract freeze for the v1 editor program.