Documenso Data Handling

Documenso Data Handling

Output

• A document-data flow with defined classification, access/retention/deletion controls, audit ownership, and safe recovery path.
• Evidence that document content, signer identity, and signature artifacts are excluded from unsafe logs and test fixtures.

Examples

Use a synthetic document and test signer in development to verify encryption/access/retention configuration. Record only a correlation ID and policy result; never place signed documents, signer PII, signature material, or document URLs into repositories, screenshots, or diagnostic logs.

Overview

Best practices for handling documents, signatures, and PII in Documenso integrations. Covers downloading signed PDFs, data retention, GDPR compliance, and secure storage. Note: Documenso cloud stores documents in PostgreSQL by default; self-hosted gives you full control.

Prerequisites

• Understanding of data protection regulations (GDPR, CCPA)
• Secure storage infrastructure (S3, GCS, or local encrypted storage)
• Completed documenso-install-auth setup

Document Lifecycle

DRAFT ──send()──→ PENDING ──all sign──→ COMPLETED
                      │
                      ├──reject()──→ REJECTED
                      └──cancel()──→ CANCELLED

Data handling implications:
- DRAFT: mutable, can delete freely
- PENDING: immutable document, but status changes
- COMPLETED: signed PDF available for download, archive
- REJECTED/CANCELLED: cleanup candidate

Instructions

Step 1: Download Signed Documents

import { Documenso } from "@documenso/sdk-typescript";
import { writeFile } from "node:fs/promises";

const client = new Documenso({ apiKey: process.env.DOCUMENSO_API_KEY! });

async function downloadSignedPdf(documentId: number, outputPath: string) {
  // Verify document is completed
  const doc = await client.documents.getV0(documentId);
  if (doc.status !== "COMPLETED") {
    throw new Error(`Document ${documentId} is ${doc.status}, not COMPLETED`);
  }

  // Download via v1 REST API (SDK may not expose download directly)
  const res = await fetch(
    `https://app.documenso.com/api/v1/documents/${documentId}/download`,
    { headers: { Authorization: `Bearer ${process.env.DOCUMENSO_API_KEY}` } }
  );
  if (!res.ok) throw new Error(`Download failed: ${res.status}`);

  const buffer = Buffer.from(await res.arrayBuffer());
  await writeFile(outputPath, buffer);
  console.log(`Saved signed PDF: ${outputPath} (${buffer.length} bytes)`);
}

Step 2: PII Handling

// Identify PII in Documenso data
interface RecipientPII {
  email: string;    // PII — must be protected
  name: string;     // PII — must be protected
  role: string;     // Not PII
  signingStatus: string; // Not PII
}

// Sanitize before logging
function sanitizeForLogging(payload: any): any {
  const sanitized = { ...payload };
  if (sanitized.recipients) {
    sanitized.recipients = sanitized.recipients.map((r: any) => ({
      ...r,
      email: r.email.replace(/^(.{2}).*(@.*)$/, "$1***$2"),
      name: "[REDACTED]",
    }));
  }
  return sanitized;
}

// Usage: safe to log
console.log("Webhook received:", JSON.stringify(sanitizeForLogging(payload)));
// Output: { email: "ja***@example.com", name: "[REDACTED]" }

Step 3: Data Retention Policy

// src/retention/documenso-cleanup.ts
import { Documenso } from "@documenso/sdk-typescript";

interface RetentionPolicy {
  draftMaxAgeDays: number;      // Delete abandoned drafts
  completedArchiveDays: number; // Archive completed docs
  retainCompletedDays: number;  // Keep completed in Documenso
}

const POLICY: RetentionPolicy = {
  draftMaxAgeDays: 30,
  completedArchiveDays: 7,    // Archive to S3 within 7 days
  retainCompletedDays: 365,   // Keep in Documenso for 1 year
};

async function enforceRetention(client: Documenso) {
  const { documents } = await client.documents.findV0({ page: 1, perPage: 100 });
  const now = Date.now();

  for (const doc of documents) {
    const ageDays = (now - new Date(doc.createdAt).getTime()) / (1000 * 60 * 60 * 24);

    // Delete old drafts
    if (doc.status === "DRAFT" && ageDays > POLICY.draftMaxAgeDays) {
      await client.documents.deleteV0(doc.id);
      console.log(`Deleted abandoned draft: ${doc.title} (${ageDays.toFixed(0)} days old)`);
    }

    // Archive completed documents
    if (doc.status === "COMPLETED" && ageDays > POLICY.completedArchiveDays) {
      await archiveToS3(doc.id, doc.title);
      console.log(`Archived: ${doc.title}`);
    }
  }
}

Step 4: GDPR Data Subject Requests

// Handle GDPR access and erasure requests
async function handleDataSubjectRequest(
  client: Documenso,
  type: "access" | "erasure",
  subjectEmail: string
) {
  const { documents } = await client.documents.findV0({ page: 1, perPage: 100 });

  // Find all documents involving this person
  const subjectDocs = documents.filter((doc: any) =>
    doc.recipients?.some((r: any) => r.email === subjectEmail)
  );

  if (type === "access") {
    // Return all data associated with this person
    return {
      documentsCount: subjectDocs.length,
      documents: subjectDocs.map((d: any) => ({
        title: d.title,
        status: d.status,
        createdAt: d.createdAt,
        role: d.recipients.find((r: any) => r.email === subjectEmail)?.role,
      })),
    };
  }

  if (type === "erasure") {
    // Delete/anonymize where legally permissible
    // Note: completed, signed documents may need to be retained for legal compliance
    const deletable = subjectDocs.filter((d: any) => d.status === "DRAFT");
    for (const doc of deletable) {
      await client.documents.deleteV0(doc.id);
    }
    return {
      deleted: deletable.length,
      retained: subjectDocs.length - deletable.length,
      retainedReason: "Completed documents retained for legal compliance",
    };
  }
}

Step 5: Secure Storage for Downloaded PDFs

import { S3Client, PutObjectCommand } from "@aws-sdk/client-s3";
import crypto from "crypto";

const s3 = new S3Client({ region: "us-east-1" });

async function archiveToS3(documentId: number, title: string) {
  // Download signed PDF
  const res = await fetch(
    `https://app.documenso.com/api/v1/documents/${documentId}/download`,
    { headers: { Authorization: `Bearer ${process.env.DOCUMENSO_API_KEY}` } }
  );
  const buffer = Buffer.from(await res.arrayBuffer());

  // Upload with server-side encryption
  const key = `signed-documents/${documentId}-${Date.now()}.pdf`;
  await s3.send(new PutObjectCommand({
    Bucket: process.env.ARCHIVE_BUCKET!,
    Key: key,
    Body: buffer,
    ContentType: "application/pdf",
    ServerSideEncryption: "aws:kms",
    Metadata: {
      documentId: String(documentId),
      title,
      archivedAt: new Date().toISOString(),
      checksum: crypto.createHash("sha256").update(buffer).digest("hex"),
    },
  }));

  console.log(`Archived to s3://${process.env.ARCHIVE_BUCKET}/${key}`);
}

Data Classification

Error Handling

Resources

• GDPR Requirements
• Documenso Self-Hosting
• AWS S3 Server-Side Encryption

Next Steps

For enterprise RBAC, see documenso-enterprise-rbac.