Updates

2026-05-20 23:36:32 -04:00
parent a020270cb1
commit be94546cd3
218 changed files with 9189 additions and 3078 deletions
@@ -1,26 +1,88 @@
 # API: hyper-p2p-session-rotation

-**Protocol:** `session-rotation/v1` · **Export:** `HyperP2PSessionRotation`
+**Protocol:** `session-rotation/v1` · **Export:** `HyperP2PSessionRotation`, `PROTOCOL`
+
+## Overview
+
+Rotates session tokens with monotonic `version` per `sessionId`. Gossips rotations; remote merges when `version >=` local.
+
+## Constructor
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `topic` | `string` \| `Buffer` | `null` | Swarm topic |
+| `keyPair` | `KeyPair` | random | Identity |

 ## Methods

-### `rotateSession(...)`
+### `rotateSession(sessionId, newToken)`

-Domain API.
+- **Returns:** `{ sessionId, token, version, rotatedAt }`
+- **Throws:** `assertNonEmpty` on both args
+- **Gossip:** `{ type: 'session-rotate', sessionId, token, version, rotatedAt }`
+- **Emits:** `rotated`

-### `getSession(...)`
+### `getSession(sessionId)`

-Domain API.
+- **Returns:** session or `null`

-### `listSessions(...)`
+### `listSessions()`

-Domain API.
+- **Returns:** all session values

+### `ready()` / `close()`

-### `getStats()` / `ready()` / `close()`
+Standard.

-Lifecycle helpers.
+## Events
+
+| Event | Payload |
+|-------|---------|
+| `rotated` | session record |
+| `closed` | — |
+
+## getStats()
+
+`rotations`, `gossipIn`, `gossipOut`, `sessions`, `protocol`.
+
+## Wire
+
+| type | fields | behavior |
+|------|--------|----------|
+| `session-rotate` | `sessionId`, `token`, `version`, `rotatedAt` | Replace if newer version |
+
+## Errors
+
+`assertNonEmpty` on session id and token.
+
+See [`../../_shared/ERROR_CODES.md`](../../_shared/ERROR_CODES.md).

 ## P2P

-Joins Hyperswarm when `topic` is set.
+Version starts at 1 on first rotation for a session.
+
+## Testing
+
+```bash
+cd modules/trust-security/hyper-p2p-session-rotation && npm test
+```
+
+## Composition
+
+`hyper-pear-runtime-session`, `hyper-p2p-noise-session-wrap`, `hyper-p2p-key-rotation`.
+
+## Example
+
+See [`examples/basic.js`](../examples/basic.js).
+
+## Remote merge rules
+
+- `session-rotate` applied when `!prev || d.version >= prev.version`
+
+## Lifecycle
+
+`version` increments on each local `rotateSession` call.
+
+## See also
+
+[`docs/architecture.md`](architecture.md), [`../../MODULE_CATEGORIES.md`](../../MODULE_CATEGORIES.md).
@@ -1,11 +1,17 @@
 # Architecture: hyper-p2p-session-rotation

+**Protocol:** `session-rotation/v1` · **Category:** trust-security
+
 ## Wire messages

-| type | fields | direction | behavior |
-|------|--------|-----------|----------|
-| `session-rotate` | sessionId, token, version | gossip | Rotate |
+| type | direction | fields | behavior |
+|------|-----------|--------|----------|
+| `session-rotate` | gossip | `sessionId`, `token`, `version`, `rotatedAt` | LWW by `version` |

-## State
+## State model

-In-memory structures; gossip via `initModuleSwarm` / `gossipSend` when P2P enabled.
+`_sessions`: Map sessionId → `{ sessionId, token, version, rotatedAt }`.
+
+## Composition
+
+`hyper-pear-runtime-session`, `hyper-p2p-noise-session-wrap`.