modules/network-transport/hyper-p2p-noise-session-wrap

hyper-p2p-noise-session-wrap

Track Noise-oriented session ids locally and gossip open/close state across a topic (metadata only; no crypto in-module).

Category: network-transport · Protocol: noise-session-wrap/v1 · Exports: HyperP2PNoiseSessionWrap, PROTOCOL, newSessionId

When to use

Coordinate session lifecycle labels with peers (pair with real Noise/SecretStream elsewhere).

When not to use

When you only need in-process secret-stream-pair with no gossip.

Quick start

const { HyperP2PNoiseSessionWrap, newSessionId } = require('hyper-p2p-noise-session-wrap')
const wrap = new HyperP2PNoiseSessionWrap({ topic: 'sessions' })
await wrap.ready()
const id = newSessionId()
wrap.createSession({ id, label: 'edge' })
console.log(wrap.getSession(id))
await wrap.close()

Docs

• docs/api.md · docs/architecture.md

Test

npm test

API

Member	Description
new HyperP2PNoiseSessionWrap(opts?)	topic, keyPair.
createSession(opts?)	opts.id optional; throws if duplicate. Gossips session-open.
getSession(id)	Open session snapshot or null.
closeSession(id)	Mark closed + gossip session-close; returns boolean.
newSessionId()	16 random bytes as hex.
getStats()	{ created, closed, gossipIn, gossipOut, open, total, protocol, mode }.
ready() / close()	mode: p2p if topic, else local.

Events: session { id, action: 'open'|'close' }, closed.

Architecture

_sessions Map(id -> { opts, createdAt, closed, closedAt?, remote? })
Gossip open: insert if missing; close: mark closed on remote id

Does not perform handshake—wraps session bookkeeping + gossip sync.

Wire table

type	Fields	Direction
session-open	id, opts, at	Any → all
session-close	id, at	Any → all

Errors

• createSession: duplicate opts.id throws session id already exists.
• Empty id on getSession / closeSession.

Composition

• Use hyper-p2p-secret-stream-pair for real encrypted streams in tests.
• hyper-p2p-session-rotation rotates tokens for the same sessionId label.
• opts is gossiped as JSON-safe metadata only.

Example

const { HyperP2PNoiseSessionWrap, newSessionId } = require('hyper-p2p-noise-session-wrap')

const wrap = new HyperP2PNoiseSessionWrap({ topic: process.argv[2] })
await wrap.ready()

const id = newSessionId()
wrap.createSession({ id, label: 'edge' })
console.log(wrap.getSession(id))
wrap.closeSession(id)
await wrap.close()