Certificate ZIP (Hotep)

Overview

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

Request

GET /api/v2/documents/:id/zip?exclude=file&required=chainpoint,ots&only=polygon
Authorization: Bearer <token>

Query param	Values	Effect
exclude	file	Omit the source document binary from the ZIP
required	comma-separated proof types	Only include proofs of these types (if present on doc)
only	comma-separated proof types	Restrict 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 var	Required	Description
HOTEP_URL	Yes	Hotep service base URL
HOTEP_SERVICE_TOKEN	Yes	Bearer token for Hotep
HOTEP_MODE	Yes	test (specimen watermark) or live

Swift storage

Two credential sets (legacy parity):

Set	Env prefix	Used for
Files	OVH_USERNAME, OVH_PASSWORD, OVH_FILES_CONTAINER, …	Source document binary
Proofs	OVH_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, projectPayload(), generateZip / generateZipSystem
• src/domains/document/document.controller.ts — GET :id/zip
• src/core/hotep/hotep.service.ts — POST /api/generate client
• 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

Related

• Proof watcher change — auto-triggers generateZipSystem on proof confirmation when PROOF_WATCHER_ENABLED=true