# HappyX Storage And Encryption Plan

Updated: 2026-05-22T20:05:00Z

## Purpose

P12 turns the production handoff into an implementation plan for the two largest remaining boundaries: transactional state and end-to-end encrypted remote sessions.

The current deployment must remain single-process while approvals, events and runs are stored in JSON. This plan describes the next implementation path without claiming that production hardening is complete.

## Phase 1: Transactional State

Target: replace mutable JSON state for approvals, runs and events with a transactional store.

- Use SQLite for the next self-hosted step; keep Postgres-compatible schema naming.
- Tables: `events`, `tasks`, `sessions`, `permissions`, `approval_uses`, `agent_runs`, `agent_run_outputs`, `deployments`.
- Add unique constraints for one-time approval use hashes and run ids.
- Store raw run output separately from public run metadata, with retention enforced in one place.
- Wrap high-risk run creation, approval use and nonce rotation in one transaction.
- Keep JSON import/export migration commands for rollback and audit.

Acceptance:

- Concurrent attempts to reuse an approval use token cannot both succeed.
- Public export/evidence endpoints still pass `npm run verify:public`.
- Smoke tests cover migration, rollback import and retention pruning.

## Phase 2: Encrypted Session Envelope

Target: support remote device sessions without exposing sensitive transcript payloads to public docs or unauthenticated APIs.

- Device identity: per-device public key and revocation record.
- Envelope: `{sessionId, senderDeviceId, sequence, createdAt, ciphertext, nonce, signature}`.
- Replay guard: monotonic sequence per sender/session plus expiry window.
- Key rotation: versioned device keys and server-side revoked key list.
- Recovery: operator-triggered device re-enrollment instead of silent key reset.

Acceptance:

- Server stores encrypted payloads but cannot render plaintext without an authorized device.
- Public state/docs expose only envelope metadata and redacted counters.
- Redaction fixture tests fail if ciphertext, keys or token material is copied into reports.

## Phase 3: Real CLI/PTY Adapter

Target: move beyond curated recipes while preserving the audit and approval model.

- PTY session table with resize, interrupt, kill and reconnect events.
- Bounded transcript chunks with stream type, byte counts and redaction status.
- Explicit operator approval before attaching a public-facing session to a high-risk PTY.
- Backpressure and retention rules shared with existing agent run output storage.

Acceptance:

- Terminal sessions recover after HappyX restart.
- Public exports show transcript metadata only.
- Visual and public verification gates remain release-blocking.

## Release Requirements

Before any phase is considered done:

```bash
node happyx/test/smoke.test.js
npm run verify:public
npm run test:visual
```

The goal remains active until the MAGI active-runtime gate reaches 7 hours or the user explicitly accepts the documented gap.