Managing snapshots

GET    /api/bng/snapshots?tag=<t>                      admin_only
POST   /api/bng/snapshots                              admin_only
GET    /api/bng/snapshots/{id}                         admin_only
DELETE /api/bng/snapshots/{id}                         admin_only
POST   /api/bng/snapshots/{id}/tags                    admin_only
POST   /api/bng/snapshots/_prune                       admin_only
GET    /api/bng/snapshots/{id}/export                  admin_only
POST   /api/bng/snapshots/import                       admin_only

Creation takes a required name, an optional description, and optional tags
matching [A-Za-z0-9_-]{1,32}. It returns 201 with the full snapshot object,
400 on validation failure, 503 if the controller could not be read, and 500
if the settings document is not valid JSON.

The listing returns metadata only — the captured block is stripped — sorted
newest first, and may be filtered by tag. Hash verification runs during listing,
so a corrupted or tampered snapshot is flagged in its warnings without needing
a separate check. A file that fails to parse entirely is skipped rather than
blackholing the listing.

Tag assignment replaces the tag list wholesale. Export returns the snapshot with
its provenance signature attached and an attachment content disposition. Import
accepts that document, strips the signature before storage, and returns the
import verdict:

{
  "id": "snap-20260623T160955Z-pre-upgrade",
  "signature_verified": true,
  "origin": "same-box",
  "warnings": []
}

origin is same-box, cross-box, or legacy.

Pruning is policy-driven and disabled by default. When enabled it applies a
maximum count and optionally a maximum age, with union semantics — a snapshot
is pruned if it trips either cap. Snapshots tagged golden are protected:
they are excluded before the caps are evaluated, so they neither get pruned nor
consume a slot in the count budget. Pruning runs inline after each creation and
on a scheduled trigger, and the _prune endpoint invokes it on demand. Every
pruned snapshot is recorded in the audit log. Manual deletion is unconditional
and has no undo.