Updates

trust-security/hyper-p2p-encrypted-topic/docs/api.md

@@ -1,26 +1,91 @@
 # API: hyper-p2p-encrypted-topic
 
-**Protocol:** `encrypted-topic/v1` · **Export:** `HyperP2PEncryptedTopic`
+**Protocol:** `encrypted-topic/v1` · **Export:** `HyperP2PEncryptedTopic`, `PROTOCOL`, `deriveKey`, `xorCrypt`
+
+## Overview
+
+Registers logical topics with a `keyHint`, derives a symmetric key via `hypercore-crypto.hash`, and XOR-encrypts payloads. Gossips `topic-register` so peers learn hints (not raw keys — key re-derived locally).
+
+## Constructor
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `topic` | `string` \| `Buffer` | `null` | Swarm topic |
+| `keyPair` | `KeyPair` | random | Swarm identity |
 
 ## Methods
 
-### `registerTopic(...)`
+### `registerTopic(topicId, keyHint)`
 
-Domain API.
+- **Returns:** `{ topicId, keyHint, key, registeredAt }`
+- **Throws:** `assertNonEmpty` on both args
+- **Gossip:** `{ type: 'topic-register', topicId, keyHint }`
+- **Emits:** `registered` `{ topicId, keyHint }`
 
-### `encryptPayload(...)`
+### `encryptPayload(topicId, data)`
 
-Domain API.
+- **Returns:** Buffer cipher
+- **Throws:** `topic not registered: ${topicId}`
 
-### `decryptPayload(...)`
+### `decryptPayload(topicId, buf)`
 
-Domain API.
+- **Returns:** plain Buffer
+- **Throws:** `buf must be a buffer`; `topic not registered: ${topicId}`
 
+### `ready()` / `close()`
 
-### `getStats()` / `ready()` / `close()`
+Standard swarm.
 
-Lifecycle helpers.
+## Events
+
+| Event | Payload |
+|-------|---------|
+| `registered` | `{ topicId, keyHint }` |
+| `closed` | — |
+
+## getStats()
+
+`registered`, `encrypted`, `decrypted`, `gossipIn`, `gossipOut`, `topics`, `protocol`.
+
+## Wire
+
+| type | fields | behavior |
+|------|--------|----------|
+| `topic-register` | `topicId`, `keyHint` | Insert topic if unknown; derive key |
+
+## Errors
+
+Registration and buffer errors above. Uses `assertNonEmpty` from shared errors.
+
+See [`../../_shared/ERROR_CODES.md`](../../_shared/ERROR_CODES.md).
 
 ## P2P
 
-Joins Hyperswarm when `topic` is set.
+XOR is not authenticated encryption — use for obfuscation/lightweight topic privacy only.
+
+## Testing
+
+```bash
+cd modules/trust-security/hyper-p2p-encrypted-topic && npm test
+```
+
+## Composition
+
+`hyper-p2p-topic-announcer`, `hyper-p2p-key-rotation`, `hyper-p2p-session-rotation`.
+
+## Example
+
+See [`examples/basic.js`](../examples/basic.js).
+
+## Remote merge rules
+
+- `topic-register` only inserts when `topicId` not already local
+- Remote peers re-derive `key` from gossiped `keyHint` (never send raw key)
+
+## Lifecycle
+
+Encrypt/decrypt increment `encrypted` / `decrypted` stats per operation.
+
+## See also
+
+[`docs/architecture.md`](architecture.md), [`../../MODULE_CATEGORIES.md`](../../MODULE_CATEGORIES.md).

trust-security/hyper-p2p-encrypted-topic/docs/architecture.md

@@ -1,11 +1,22 @@
 # Architecture: hyper-p2p-encrypted-topic
 
+**Protocol:** `encrypted-topic/v1` · **Category:** trust-security
+
 ## Wire messages
 
-| type | fields | direction | behavior |
-|------|--------|-----------|----------|
-| `topic-register` | topicId, keyHint | gossip | Register |
+| type | direction | fields | behavior |
+|------|-----------|--------|----------|
+| `topic-register` | gossip | `topicId`, `keyHint` | Store topic; `deriveKey(keyHint)` locally |
 
-## State
+## State model
 
-In-memory structures; gossip via `initModuleSwarm` / `gossipSend` when P2P enabled.
+`_topics`: Map topicId → `{ topicId, keyHint, key, registeredAt }`.
+
+## Helpers
+
+- `deriveKey(hint)` → `crypto.hash(b4a.from(String(hint)))`
+- `xorCrypt(keyBuf, dataBuf)` — byte XOR stream cipher
+
+## Composition
+
+`hyper-p2p-key-rotation`, `hyper-p2p-topic-announcer`.