Reza DocuHandshake — Backend Document Access Guide

Backend Structure

Backend code lives in server/:

• server/index.ts — Express entrypoint and local backend utility page
• server/routes/auth.ts — magic-link and session routes
• server/routes/documents.ts — upload, secure file access, public signed downloads
• server/routes/admin.ts — admin listing, updates, audit trail, signing helpers
• server/routes/notifications.ts — email notification dispatch
• server/services/ — email, JWT session, token, and storage helpers
• server/sql/001_init.sql — PostgreSQL schema

Core APIs for Document Access

1. List documents as admin

POST /api/admin/list-documents

Body:

{ "adminPassword": "454545" }

Returns:

{ "documents": [ ... ] }

2. Read the audit trail for a document

POST /api/admin/get-document-audit-trail

Body:

{
  "adminPassword": "454545",
  "documentId": "00000000-0000-0000-0000-000000000000"
}

3. View/download a document as admin

GET /api/documents/:id/file?adminPassword=454545

This streams the PDF currently referenced by documents.file_path.

4. View/download a document as the owner

GET /api/documents/:id/file

Requires the rdh_user_session cookie from the magic-link flow.

5. Public signed download link

GET /api/documents/public/download/:token

Used in the signed-document email. The token is a short-lived JWT generated by the backend.

Useful curl Examples

Health check

curl http://localhost:8080/api/health

List documents

curl -sS -X POST http://localhost:8080/api/admin/list-documents \
  -H 'Content-Type: application/json' \
  -d '{"adminPassword":"454545"}'

Fetch audit trail

curl -sS -X POST http://localhost:8080/api/admin/get-document-audit-trail \
  -H 'Content-Type: application/json' \
  -d '{"adminPassword":"454545","documentId":"<DOCUMENT_ID>"}'

Download one document as admin

curl -o document.pdf \
  "http://localhost:8080/api/documents/<DOCUMENT_ID>/file?adminPassword=454545"

Download one document using an admin header

curl -o document.pdf \
  -H 'x-admin-password: 454545' \
  "http://localhost:8080/api/documents/<DOCUMENT_ID>/file"

Auth Model

• User side: magic-link verification sets the rdh_user_session HTTP-only cookie.
• Admin side: most admin endpoints require ADMIN_PASSWORD.
• Current implementation note: analyze-document, generate-signature, and notifications/send do not currently enforce admin auth.

Storage Model

PDFs are stored on disk under STORAGE_ROOT:

• Original uploads: documents/...
• Signed PDFs: signed/...

The database stores only relative file paths.

Local Run Notes

Run the app from prod/:

npm install
cp .env.example .env
npm run db:init
npm run dev:server
npm run dev

Default local URLs:

• Frontend: http://localhost:5173
• Backend API: http://localhost:8080
• Backend utility page: http://localhost:8080/