Skip to main content
Version: 1.3.0

Certificate ZIP (Hotep)

Overview​

GET /api/v2/documents/:id/zip streams a ZIP archive containing blockchain proof certificates and receipt files (.json, .ots, etc.). Replaces the legacy backend ZIP route. Neo fetches MongoDB + stored objects and projects a raw field mask to Hotep; Hotep owns all certificate layout logic.

Automatic agents (agent_codes.automatic on bcyip:agent) only download a PDF that is already stored. A missing PDF is published through Hotep POST /api/queues/certificates/publish and the download answers 409 certificates_not_ready. Tower stays Waiting. After three publishes, the sweep retries every six hours and never marks the job failed.

Manual agents (Box, web, or a missing agent attribute) render missing PDFs during the request. Nothing left to put in the zip, or only a polygon proof, is 422 proofs_incomplete.

Chainpoint and ots stay in the zip only when the certificate and the receipt are both present. Polygon stays only beside another included proof. A PDF that is included is posted to Hotep for review. A failed copy does not fail the zip. HOTEP_MODE=test reads dev/, HOTEP_MODE=live reads prd/.

Request​

GET /api/v2/documents/:id/zip?exclude=file&required=chainpoint,ots&only=polygon
Authorization: Bearer <token>
Query paramValuesEffect
excludefileOmit the source document binary from the ZIP
requiredcomma-separated proof typesOnly include proofs of these types (if present on doc)
onlycomma-separated proof typesRestrict archive to these types only

Response: application/zip stream, Content-Disposition: attachment.

Supported proof types: chainpoint, ots, polygon, external. External proof PDFs are served from Swift storage directly (no Hotep call).

Architecture​

Hotep integration​

Neo calls Hotep with projected raw data only — no owner/coauthor transformation in neo.

POST {HOTEP_URL}/api/generate
Authorization: Bearer {HOTEP_SERVICE_TOKEN}
Content-Type: application/json

{ HotepPayload: document, proof, company, user, ... }
Env varRequiredDescription
HOTEP_URLYesHotep service base URL
HOTEP_SERVICE_TOKENYesBearer token for Hotep
HOTEP_MODEYestest (specimen watermark) or live

Swift storage​

Two credential sets (legacy parity):

SetEnv prefixUsed for
FilesOVH_USERNAME, OVH_PASSWORD, OVH_FILES_CONTAINER, …Source document binary
ProofsOVH_PROOFS_*, OVH_PROOFS_CONTAINER_*Receipt blobs per proof type

Keystone v3 auth with in-memory token cache (swift-auth.service.ts).

Technical decisions​

  • Neo as dumb pipe: projectPayload() picks Mongo fields; Hotep resolves owner type, coauthors, represented client, ownerShare
  • Streaming ZIP: archiver pipes to HTTP response — no full archive buffered in memory
  • System path: ZipService.generateZipSystem() used by proof watcher (no user context — resolves job from document)

Key files​

  • src/domains/document/zip.service.ts — ZIP assembly, automatic versus manual paths, incomplete-proof filter
  • src/domains/document/document.controller.ts — GET :id/zip
  • src/core/certificates/certificate-queue.service.ts — Stored-object readiness, publish, slow retry
  • src/core/hotep/hotep.service.ts — POST /api/generate, queue publish, review copy
  • src/core/proof-watcher/proof-watcher.service.ts — Enqueue on confirmation and startup sweep
  • src/core/hotep/hotep.types.ts — HotepPayload projection types
  • src/core/storage/storage.service.ts — Swift HTTP downloads
  • src/core/config/hotep.config.ts, storage.config.ts — Joi-validated env
  • certificate-zip.md (neo-backend repo) — detailed design note
  • Proof watcher change — auto-triggers generateZipSystem on proof confirmation when PROOF_WATCHER_ENABLED=true