Artstr-Studio/docs/PRIVATE_PUBLISHING_FEATURE.md

# Private (Encrypted) Publishing

## Goals

Let any Artstr design — cover, disc, jewel, custom art, slide, deck — be
published to Nostr **encrypted**, so only the author can read it. An
encrypted design is a normal `kind:30078` addressable event (still
editable in place), but its contents are an encrypted blob instead of
plaintext JSON.

### Product goal (v1 = Phase 1)

**"Private to me."** A design published privately:

- is encrypted so only the author can decrypt it;
- never appears in the public community feed;
- shows in **My Designs**, where the author decrypts and opens it normally;
- stays editable in place — republishing the same `d`-tag supersedes it.

### Non-goals (v1)

- **Sharing with other people** (private-to-selected-pubkeys) — Phase 3.
- **Public ⇄ private toggling** of an already-published design — Phase 2.
- **NIP-59 gift-wrap** metadata privacy — Phase 4.
- **Blossom / NIP-96 offload** for oversized encrypted blobs — Phase 4.
- Hiding that an encrypted Artstr event *exists* — the event, the author
  pubkey, and the timestamp are always public. Encryption hides the
  design *contents*, nothing more.

### Decisions (locked)

1. **Private designs are invisible in the public feed** — they omit the
   `["t","casewrap"]` discovery tag entirely, so the feed query never
   fetches them. No "locked card" in New/Popular/etc.
2. **Phase 1 only** for now — "private to me", no recipients.
3. **Key-wrap uses NIP-44 when available, NIP-04 as fallback** — so the
   feature works with as many NIP-07 extensions as possible.
4. **No `SCHEMA_VERSION` bump** — the decrypted payload is unchanged
   (still v5). The *encryption envelope* is versioned separately.

### The honest caveat

Encryption protects the design *contents*. It does **not** hide that an
encrypted event exists, who authored it, or when. And replacement is not
deletion: if a design was ever public, old public copies may persist on
relays regardless of what is published later. The publish UI must say so.

### Threat model

**Protected:** design *contents* — layers, artwork URLs, text, title,
category and identifiers — from relays, feed scrapers, and anyone
browsing Artstr or any other Nostr client.

**Not protected — and the UI must not imply otherwise:**

- The **existence** of the event, the **author pubkey**, the
  **`created_at`** timestamp, and the event **size** — all public on
  every relay it touches.
- Anything on the **author's own device** — the `localStorage` autosave
  and any "Save project (JSON)" file are plaintext. Encryption applies
  *only* to what is published to Nostr.
- Against a **malicious or compromised NIP-07 extension** — it holds the
  signing key and performs the key-wrap.
- **Forward secrecy** is a non-goal; a fresh AES key per publish is a
  weak bonus, not a guarantee.

---

## Why this fits the repo

- Designs already publish as `kind:30078` addressable events with a
  mode-prefixed `d`-tag; owners already edit in place by republishing the
  same `d`-tag (`publishCurrentTemplateToNostr`, `isEditing()`).
- The project JSON is already the portable, publishable artifact — we
  encrypt *that*, unchanged.
- The community feed already filters by `#t:['casewrap']`; omitting that
  one tag is all it takes to keep a design out of the feed.
- **My Designs** already queries by author pubkey, so the author's own
  encrypted events are fetched there without any query change.
- Image references are remote URLs, never embedded binary — so the
  plaintext to encrypt is bounded to layer JSON.

### Current-state facts the plan is built on

- Publish path: `publishCurrentTemplateToNostr()` builds `payload` per
  mode, a `typeTag`, a `dTag` (`${mode}:${title|imdb|dims}`), tags via
  `getTemplateTags()`, then `{ kind:30078, tags, content:
  JSON.stringify(payload) }`, signed/sent by `publishCommunityEvent()`.
- Feed: `queryRelays(relays, { kinds:[30078], '#t':['casewrap'] }, …)`,
  then `buildRowsFromEvents()` does `JSON.parse(e.content)` and
  `normalizeTemplateMode(payload)` on every event.
- **My Designs** (`loadMyDesigns`) fetches events authored by
  `state.community.myPubkey`.
- NIP-07 surface used today: `window.nostr.getPublicKey`,
  `signEvent`. NIP-44 / NIP-04 are **not** used yet.

---

## Data model

### Public design — UNCHANGED

Public events stay exactly as today: `content` is the raw project JSON
(`{ version:5, templateMode, meta, … }`). Old clients keep working. A
flat, additive `"visibility":"public"` field *may* be added to the
payload, but no wrapper — nothing that moves `templateMode`.

### Encrypted design — new envelope

The event `content` is the **encryption envelope**, not a design payload:

```json
{
  "v": 1,
  "visibility": "encrypted",
  "enc": {
    "alg": "aes-256-gcm",
    "keywrap": "nip44",          // or "nip04"
    "compression": "gzip"        // or "none"
  },
  "iv": "<base64>",
  "ciphertext": "<base64>",
  "recipients": [
    { "pubkey": "<author-pubkey>", "wrappedKey": "<wrapped>" }
  ]
}
```

- `ciphertext` = AES-256-GCM of `gzip(JSON.stringify(projectPayload))`.
- `projectPayload` is the **ordinary, current design JSON** — the exact
  thing `customArtPayload()` / `deckPayload()` / `coverTemplatePayload()`
  / etc. already produce. Decryption yields a payload `loadProjectFromText`
  already understands.
- `recipients[]` carries the AES key wrapped per recipient. In Phase 1
  there is exactly one entry: the author (encrypt-to-self). `wrappedKey`
  is `nostr.nip44.encrypt(authorPubkey, base64(rawAesKey))`, or the NIP-04
  equivalent when `keywrap === "nip04"`.

### Event tags — encrypted designs

Minimal, leak-free:

```
["d",   "artstr-private-<random-id>"]   // random, NOT title/imdb derived
["alt", "Encrypted Artstr design"]      // NIP-31 generic
["encrypted", "nip44"]                  // or "nip04"
```

Deliberately **absent**: `["t","casewrap"]`, `title`, `i` (imdb/upc/…),
`category`, `language`, `template_type`, and the `["t","casewrap-*"]`
tags. `getTemplateTags()` is **not** called for a private design.

The `d`-tag is random but **persistent for that design** — minted once on
first private publish, reused on every edit so replacement works.

---

## Crypto

All in-browser, no new vendored libraries:

- **AES-256-GCM** via WebCrypto (`crypto.subtle`).
- **gzip** via `CompressionStream('gzip')` (fallback: `compression:"none"`
  when unavailable).
- **Key-wrap** via the NIP-07 extension: `window.nostr.nip44.encrypt`,
  falling back to `window.nostr.nip04.encrypt`. Encrypt-to-self is valid —
  ECDH(my privkey, my pubkey) is a well-defined shared secret.

### Encrypt (publish)

```
rawKey   = crypto.getRandomValues(32 bytes)      // fresh per publish
iv       = crypto.getRandomValues(12 bytes)
plain    = gzip(utf8(JSON.stringify(projectPayload)))
cipher   = AES-GCM.encrypt(rawKey, iv, plain)
wrapped  = nostr.nip44.encrypt(authorPubkey, base64(rawKey))   // or nip04
envelope = { v:1, visibility:"encrypted", enc:{…}, iv, ciphertext:cipher,
             recipients:[{ pubkey:authorPubkey, wrappedKey:wrapped }] }
```

### Decrypt (My Designs / open)

```
mine     = envelope.recipients.find(r => r.pubkey === myPubkey)
rawKey   = base64decode(nostr.nip44.decrypt(mine.pubkey, mine.wrappedKey))
plain    = AES-GCM.decrypt(rawKey, envelope.iv, envelope.ciphertext)
payload  = JSON.parse(gunzip(plain))             // ordinary design JSON
```

`keywrap` in the envelope says which of nip44/nip04 to use for the unwrap.

### Capability gate

On opening the publish modal, probe `window.nostr?.nip44?.encrypt ||
window.nostr?.nip04?.encrypt`. If neither exists, the **Private** option
is disabled with a tooltip ("Your Nostr extension doesn't support
encryption"). In practice NIP-04 is near-universal, so this rarely bites.

---

## The surfaces

### 1. Publish modal — visibility control

A radio / segmented control:

```
Publish visibility:
  ( ) Public — listed in the community feed, anyone can open it
  (•) Private — encrypted; only you can open it; not in the feed
```

When **Private** is selected the confirm modal swaps its warning text:

> Private designs are encrypted — relays and other people can't read the
> contents. The event still reveals that *something* was published, by
> your pubkey, at this time. Encryption can't undo a past public publish.

Pre-validation: a private design does **not** require a category (it's
never categorized in a feed). A title is still kept — it rides inside the
encrypted payload and labels the design in My Designs.

### 2. Publish path

`publishCurrentTemplateToNostr()` branches on visibility:

- **Public** — unchanged.
- **Private** — build `payload` as today, then: encrypt → envelope →
  `content`; tags = the minimal leak-free set above; `d`-tag = the
  design's persistent random private id (minted if absent); sign + send
  via `publishCommunityEvent()`.

Editing an already-private design re-encrypts (fresh AES key + iv) and
reuses the same random `d`-tag.

### 3. My Designs — decrypt + render

`loadMyDesigns()` already fetches the author's own events. Decryption is
**progressive**, never a blocking wall:

1. Build rows immediately. An encrypted event (content parses to
   `visibility:"encrypted"`, or the `encrypted` tag is present) first
   renders a placeholder **🔒 locked card** with no contents.
2. Decrypt each locked card asynchronously; as each resolves, swap the
   placeholder for the real card built from the decrypted payload,
   flagged `row.private = true` with a 🔒 badge. Preview / open / fork
   then work on the decrypted payload as usual.
3. If the NIP-07 extension is **absent or locked**, every decrypt fails —
   show one clear "Unlock your Nostr extension to view private designs"
   state, not N broken cards.
4. A genuine decrypt failure on a single design renders a disabled
   "🔒 Could not decrypt" card and never blocks the rest.

### 4. Feed / discovery

No change. Private events lack `["t","casewrap"]`, so `queryRelays` with
`#t:['casewrap']` never returns them. They are invisible everywhere except
My Designs.

### 5. Load / open / fork

Opening a private design from My Designs decrypts first, then calls the
existing `loadProjectFromText(decryptedJSON)`. The loaded project keeps
`visibility:"private"` and its random `d`-tag in state; opening it for
**edit** sets the existing edit context (`editingDTag` = that random
`d`-tag, `editingEventId`, `editingKind`) so a re-publish replaces it in
place and stays private.

**Fork** is a fresh start, so a fork of a private design defaults to
**Private** as well (and mints a *new* random `d`-tag — a fork is a new
design, not a replacement). The user can still switch it to Public in the
publish modal.

"Save project (JSON)" writes the **decrypted** payload — a local file is
plaintext (see Threat model). Encryption is applied only at Nostr publish
time, never to the on-disk JSON.

### 6. Share links

A `/share/<naddr>` for a private design resolves to the encrypted event,
which a non-author cannot decrypt. For Phase 1 the share page shows a
"This design is private" locked state; per-recipient sharing is Phase 3.
"Copy share link" on a private design warns that only you can open it.

---

## State

- `state.visibility` — `"public" | "private"`, default `"public"`.
- `state.privateDTag` — the persistent random `d`-tag for this design once
  it's been published privately (so edits replace correctly).
- Both ride in the saved/loaded project JSON (additive fields) and in
  autosave. The decrypted payload carries `visibility` so a reloaded
  private design stays private.

---

## Phased delivery

### Phase 0 — Validation spike  *(do first; ~half a day)*

Three unknowns can sink the design — probe them before building Phase 1:

1. **NIP-44 / NIP-04 encrypt-to-self** — confirm the target extensions
   (Alby, nos2x, …) accept encrypting to the user's *own* pubkey, and
   that the NIP-04 fallback behaves the same. Self-addressed NIP-04 is
   the established pattern for encrypted NIP-51 lists, so this is *likely*
   fine — but the whole feature rests on it, so verify.
2. **`CompressionStream('gzip')`** — confirm availability on target
   browsers; if absent, the `compression:"none"` path must work.
3. **Relay event-size limits** — publish a deliberately large encrypted
   blob (a ~20-slide deck) to the default relay set and read it back.
   This decides whether Blossom offload (Phase 4) is needed sooner.

If the app already self-encrypts its `kind:10000` mute/block list with
NIP-04, **reuse that codepath** rather than writing a new one.

### Phase 1 — Private to me  *(current target)*

- Encryption helpers (`encryptProjectEnvelope`, `decryptProjectEnvelope`),
  AES-GCM + gzip + NIP-44/NIP-04 key-wrap, capability gate.
- Publish modal visibility control + private warning copy.
- Private publish path: envelope content, minimal tags, random persistent
  `d`-tag, no feed tag.
- My Designs async decrypt pass + 🔒 badge + open/fork on decrypted JSON.
- `visibility` / `privateDTag` in state, save/load, autosave.

**Ship gate:** publish a design privately; confirm it does **not** appear
in the public feed; see it in My Designs with a 🔒 badge; open it — it
decrypts and edits normally; republish — it replaces in place.

### Phase 2 — Public ⇄ Private toggle

Re-publish an existing design with the opposite wrapper under the same
address. Going public→private keeps the *old* public event on relays
(documented, unavoidable).

### Phase 3 — Private to selected pubkeys

Add recipients: wrap the AES key once per recipient into `recipients[]`. A
recipient with a share link decrypts their own `wrappedKey`. Adds a
recipient-picker UI.

### Phase 4 — Hardening

- NIP-59 gift-wrap to hide *who* the recipients are.
- Blossom / NIP-96 offload when an encrypted blob (esp. a large deck)
  exceeds relay event-size limits; chunking as a fallback.

---

## Risks & tradeoffs

| Risk | Mitigation |
|---|---|
| Replacement ≠ deletion — public→private can't erase the past | Documented in UI; Phase 1 is encrypt-first so the design is never public to begin with. |
| NIP-44 plaintext cap (64 KB) | We encrypt with AES-GCM and only *key-wrap* with NIP-44/04 — the wrapped key is tiny, well under the cap. |
| Relay event-size caps — a large encrypted deck may not fit one event | Compress before encrypt; warn on oversized blobs; Blossom offload deferred to Phase 4. |
| Extension lacks `nip44` | NIP-04 fallback; capability gate disables Private if neither exists. |
| `buildRowsFromEvents` is synchronous; decryption is async | Decrypt outside the sync parser — render 🔒 placeholders, then swap in decrypted cards progressively (surface 3). |
| Encrypted event still leaks existence / pubkey / timestamp | Stated plainly in the Threat model and the publish warning; NIP-59 (Phase 4) reduces metadata leakage for shared designs. |
| Fresh AES key per republish | Intentional and harmless — only the author needs it, and it's re-wrapped each publish. |
| An extension might reject `nip44`/`nip04` encrypt-to-self | Validated up front in Phase 0; gate the Private option on a successful capability probe, not just method presence. |
| Many private designs → slow My Designs load | Progressive decrypt: the page is usable immediately; cards fill in as they resolve. |
| A relay rejects an event with no `t` tags / unusual shape | `kind:30078` app-data with a `d` tag is standard; verified against the default relay set in Phase 0. |

---

## Acceptance summary

### Phase 0
- [ ] NIP-44 and NIP-04 encrypt-to-self confirmed working on the target
      extensions.
- [ ] `CompressionStream` availability checked; `compression:"none"`
      fallback exercised.
- [ ] A large encrypted deck publishes to and reads back from the default
      relay set (or the size ceiling is documented).

### Phase 1
- [ ] Publish modal offers Public / Private; Private is gated on
      nip44-or-nip04 capability.
- [ ] A privately-published design is absent from New / Popular / Zapped /
      Search (no `casewrap` tag).
- [ ] The encrypted event carries no title / category / identifier tags
      and a random `d`-tag.
- [ ] My Designs shows the private design with a 🔒 badge; opening it
      decrypts and loads it into the editor.
- [ ] Editing and re-publishing a private design replaces it in place
      (same `d`-tag) and stays private.
- [ ] Decrypted payload is identical to the pre-encryption project JSON
      (round-trip clean) — no `SCHEMA_VERSION` change.