# 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.