Shade/docs/archive/V2.2.md

Shade V2.2 — Feature plan: product, platform, and developer experience

This document gathers planned features that extend Shade beyond today’s core (X3DH + Double Ratchet + Streams/transfer): groups, asynchronous delivery, richer file UX, web workers, CLI, API docs, and scaffolding.

Add optional per-feature status (Idea / Design / IMP / Done).

---

1. Groups / multiple participants

Vision: Beyond strict 1:1 — multiple identities in the same “conversation” or shared context (messages and possibly shared file/stream policy).

Challenges:

• Today’s Signal-like core is naturally 1:1; groups need either pairwise sessions per member, sender keys / fan-out, or a dedicated group protocol (larger architectural step).
• Lifecycle: invites, member removal, compromised device, history, and group PCS.

Goals for early milestones (proposal):

1. Document a recommended pattern for “group-lite” (e.g. coordinator relays ciphertext without decrypting + clients encrypt per-recipient).
2. Optional minimal API making fan-out easier in the SDK (without promising full MLS).

Acceptance criteria (MVP definition): Explicit scope in docs + one reference architecture; no ambiguous “group is done” without an updated threat model.

---

2. Async store-and-forward messaging

Vision: Recipient need not be online; ciphertext is stored temporarily and fetched when the recipient returns — the server never sees plaintext.

Distinction from the prekey server:

• Prekey stays public keys only (or extended only under strict policy).
• A dedicated relay/inbox service (or app-owned backend) holds encrypted blobs only with TTL, idempotency, and authorization (who may list/fetch).

Deliverables (proposal):

• Protocol sketch: address registration, PUT blob, GET/DELETE or lease, replay protection at the application layer.
• SDK helpers: outgoing queue, poll/pull, or push-notification hook (without dictating mobile platform).

Acceptance criteria: Threat-model section “what the relay sees” + reference implementation or example app.

---

3. File metadata and preview

Vision: Richer UX without leaking sensitive content to the server: filename, MIME type, length where known; optional client-generated thumbnails or previews encrypted as separate blocks or small payloads on the control init path.

Technical considerations:

• Anything sent must be E2EE or omitted; plaintext metadata on the server must be deliberate and minimal.
• Thumbnails should use format hardening on the client (size limits, sandboxing in UI).

Acceptance criteria: Extended stream-init (or sidecar envelope) with optional fields + widget support for “preview when available”.

---

4. Web: worker-based crypto and streaming

Vision: Large files in the browser without blocking the main thread or blowing RAM — Web Crypto / noble inside a Worker, ReadableStream/WritableStream end-to-end chunk pipeline aligned with @shade/streams / transfer.

Deliverables:

• @shade/crypto-web (or companion) patterns: transferable buffers, lifecycle, errors surfaced to the UI.
• Documented constraints (Safari, chunk sizing, Service Worker vs dedicated worker).

Acceptance criteria: E2E demo or test that sends multi‑MiB through a worker without a blocking UI.

---

5. CLI: shade doctor

Vision: One command that diagnoses the environment before production debugging.

Typical checks (proposal):

• Reachability of prekeyServer (/health, optional OpenAPI).
• Local config: storage path, rotation headers, clock skew (relevant for signed requests).
• Streams: transfer routes mounted, auth matches expected key, GET .../state behaves as expected in test mode.
• CLI / Node/Bun runtime versions and @shade/* packages where readable from package.json.

Acceptance criteria: shade doctor with exit codes suitable for CI (warn vs fail).

---

6. OpenAPI / docs

Vision: All HTTP contracts teams are expected to implement (prekey and transfer) appear in one OpenAPI story or clearly linked specs — not only README examples.

Deliverables:

• Consolidate or cross-reference openapi.yaml with transfer endpoints (/v1/transfer/*) and security schemes for chunk upload.
• /docs (Redoc or similar) or published static artifacts for versioned specs.

Acceptance criteria: Generated client (e.g. Python/Go) from spec without manual fixes for the happy path.

---

7. shade init

Vision: Scaffolding from empty repo to a minimal runnable app with Shade and optional streams.

Extensions:

• New or extended template: minimal Hono/Fastify app with Shade.transferRoute() mounted, auth example matching the SDK authenticator, .env template.
• Optional: demo shade doctor after init.

Acceptance criteria: shade init … produces a project that bun install && bun run start runs with documented env vars.

---

Dependencies between items

shade init ─────► doctor (same conventions for URLs and secrets)
openapi/docs ◄── transfer + prekey (single source)
web workers ───► streams UX (large file in browser)
groups ◄──────── store-and-forward (often related socially/technically)
metadata/preview► widgets + proto/control plane

---

Document versioning

• V2.2 — feature backlog as described. Split into issues/ADR per feature when implementation starts.