Skip to main content
Version: 1.1.0

Certificate ZIP Generation (Hotep)

Version: 1.1.0 Date: 2026-07-15

Goal: Provide a downloadable ZIP archive containing blockchain proof certificates and receipts for a document, replacing the legacy backend route with Hotep-powered PDF generation.

Solution: New GET /api/v2/documents/:id/zip endpoint that fetches document data and proofs from MongoDB, projects raw data (with a field mask) to Hotep, which handles all certificate mapping logic, and assembles everything into a streaming ZIP archive.

Features:

  • ZIP archive with proof certificates (PDF via Hotep) and receipts (.json / .ots)
  • Optional inclusion of the source document file
  • Query params exclude=file, required=<types>, only=<types> for filtering
  • Support for chainpoint, ots, polygon, and external proof types
  • External proof certificates served directly from storage (no Hotep generation)
  • Raw payload with field mask: neo sends projected MongoDB data, Hotep does all mapping (owner resolution, coauthors, represented client, ownerShare)
  • Automatic specimen watermark in non-production via HOTEP_MODE env var

Implementation Details:

  • Custom OpenStack Swift client using raw HTTP + Keystone v3 auth (no unmaintained third-party dependency)
  • Token caching with auto-refresh for Swift authentication
  • Two separate Swift credential sets (files vs proofs) matching legacy architecture
  • Neo is a dumb pipe: projectPayload() only picks fields, no transformation
  • Hotep owns all certificate logic: owner type resolution, address formatting, coauthor name concatenation, represented client lookup, ownerShare calculation
  • Representative case: document.owner (ObjectId) matched against company.clients[]._id by Hotep
  • ENV_FILE support in config module to switch env files at startup (useful for local/staging)

Files Modified:

  • src/core/config/storage.config.ts - OVH Swift storage configuration (Joi validated)
  • src/core/config/hotep.config.ts - Hotep service configuration with mode (Joi validated)
  • src/core/config/config.module.ts - Register new config loaders + ENV_FILE support
  • src/core/storage/swift-auth.service.ts - Keystone v3 authentication with token caching
  • src/core/storage/storage.service.ts - File/proof download service (Swift HTTP client)
  • src/core/storage/storage.module.ts - Storage NestJS module
  • src/core/hotep/hotep.types.ts - Raw projection types (HotepPayload, HotepDocumentData, etc.)
  • src/core/hotep/hotep.service.ts - HTTP client for Hotep certificate generation
  • src/core/hotep/hotep.module.ts - Hotep NestJS module
  • src/domains/document/zip.service.ts - ZIP assembly + projectPayload() field mask
  • src/domains/document/document.controller.ts - New GET :id/zip endpoint
  • src/domains/document/document.module.ts - Import StorageModule + HotepModule
  • certificate-zip.md - In-repo technical design note

Related change: Auth middleware null token fix shipped in the same integration wave.

Release fragment: feat-certificate-zip