p2ns/docs/plugins/peer.paste.md

Peer Paste Plugin

peer.paste provides temporary, replicated text snippets for the P2NS network.

Overview

• Store paste metadata/content in HyperDB.
• Share via link (/p/:id) or API (/api/pastes/:id/raw).
• Supports expiration, burn-after-read, and max-read limits.
• Includes a websocket-first lightweight web UI with infinite scroll.
• Supports text and markdown formats with client preview.
• Uses encryption by default with optional public mode and optional passphrase-derived mode.
• Supports bounded inline attachments metadata/payloads.

Routes

• POST /api/pastes create a new paste
• GET /api/pastes list active pastes
• GET /api/pastes/mine list active pastes owned by local peer
• GET /api/pastes/:id get paste metadata
• GET /api/pastes/:id/raw consume/read paste content
• GET /api/pastes/:id/attachments list attachment metadata
• GET /api/pastes/:id/attachments/:attachmentId get attachment payload
• PUT /api/pastes/:id update paste (owner only; authenticated)
• DELETE /api/pastes/:id delete paste (owner only; authenticated)
• GET /api/stats get aggregate service stats
• GET /api/health lightweight plugin/db health check
• POST /api/admin/cleanup run cleanup immediately (authenticated)
• GET /api/docs interactive API documentation
• GET /api/openapi.json OpenAPI 3 JSON specification
• GET /p/:id human-readable paste page

HyperDB Schema

Collection: @peerpaste/pastes

Fields:

• id (string, key)
• content (string)
• format (string: text or markdown)
• language (string)
• ownerPeerId (string)
• isPublic (bool)
• encryptionMode (string)
• checksum (string)
• attachmentRefs (stringified JSON array)
• destroyOnRead (bool)
• maxReads (uint)
• readCount (uint)
• createdAt (uint)
• expiresAt (uint)

Index:

• pastes-by-expiry on expiresAt

Lifecycle

• onInit() ensures DB readiness and starts hourly cleanup.
• Cleanup removes expired/consumed pastes and flushes DB.
• onShutdown() clears cleanup interval.

Notes

• Content currently replicates via HyperDB, so use reasonable paste size limits.
• POST and PUT validate content and enforce a max length.
• Raw consumption increments read count and can auto-delete on read constraints.
• The /api/docs endpoint provides copy/paste-ready endpoint summaries.
• The /api/openapi.json endpoint can be imported by API tooling.
• Burn-after-first-read entries are hidden from recent active websocket list views.