Documenso Security BasicsSAFE

Model-agnostic agent-skills platform with a harness-free canonical layer, verified adapters, and the ccpi package manager. Explore at tonsofskills.com.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: documenso-security-basics
description: 'Implement security best practices for Documenso document signing integrations.

  Use when securing API keys, configuring webhooks securely,

  or implementing document security measures.

  Trigger with phrases like "documenso security", "secure documenso",

  "documenso API key security", "documenso webhook security".

  '
allowed-tools: Read, Write, Edit
version: 1.14.0
license: MIT
author: Jeremy Longshore <[email protected]>
tags:
- saas
- documenso
- api
- security
- webhooks
compatibility: Designed for Claude Code
---
# Documenso Security Basics

## Output

- A least-privilege Documenso configuration with scoped secrets, signer/document access controls, and an incident/revocation path.
- A tested boundary for document authorization, webhook validation, and safe audit logging.

## Examples

Create a development document with a synthetic signer, validate that only its intended role can view or act on it, and verify any webhook signature before processing. If a token, signing URL, or document is exposed, revoke/contain access and follow the incident procedure before attempting cleanup.

## Overview

Essential security practices for Documenso integrations: API key management, webhook verification, document access control, and self-hosted signing certificate configuration.

## Prerequisites

- Documenso account with API access
- Understanding of environment variables and secret management
- Completed `documenso-install-auth` setup

## Instructions

### Step 1: API Key Security

```typescript
// NEVER hardcode keys
const BAD = new Documenso({ apiKey: "api_abc123..." }); // Exposed in source

// ALWAYS use environment variables
const GOOD = new Documenso({ apiKey: process.env.DOCUMENSO_API_KEY! });
```

**Key management rules:**

- Store in `.env` (never committed) or a secrets manager (Vault, AWS Secrets Manager)
- Use team-scoped keys for team resources, personal keys for personal documents
- Rotate keys on employee offboarding -- revoke in dashboard immediately
- CI/CD: use masked/encrypted secrets (GitHub Secrets, GitLab CI variables)

```bash
# .gitignore — always include
.env
.env.*
!.env.example
```

### Step 2: Key Rotation with Zero Downtime

```typescript
// Support dual keys during rotation
function getApiKey(): string {
  // Try primary first, fall back to secondary during rotation
  return process.env.DOCUMENSO_API_KEY_PRIMARY
    ?? process.env.DOCUMENSO_API_KEY_SECONDARY
    ?? (() => { throw new Error("No Documenso API key configured"); })();
}

// Rotation procedure:
// 1. Generate new key in Documenso dashboard
// 2. Set as DOCUMENSO_API_KEY_SECONDARY, deploy
// 3. Verify secondary key works
// 4. Move secondary to PRIMARY, deploy
// 5. Revoke old key in dashboard
```

### Step 3: Webhook Secret Verification

```typescript
import { timingSafeEqual } from "crypto";

function verifyWebhookSecret(req: Request): boolean {
  const received = req.headers["x-documenso-secret"] as string;
  const expected = process.env.DOCUMENSO_WEBHOOK_SECRET!;

  if (!received || !expected) return false;

  // Use constant-time comparison to prevent timing attacks
  return timingSafeEqual(
    Buffer.from(received, "utf8"),
    Buffer.from(expected, "utf8")
  );
}
```

```python
# Python equivalent
import hmac, os
from flask import request

def verify_webhook(req):
    received = req.headers.get("X-Documenso-Secret", "")
    expected = os.environ["DOCUMENSO_WEBHOOK_SECRET"]
    return hmac.compare_digest(received, expected)
```

### Step 4: Document Access Control

```typescript
// Principle of least privilege with API keys
// Personal keys: only YOUR documents
// Team keys: all documents in the team

// Restrict document access by checking ownership
async function getDocumentSecure(documentId: number, userId: string) {
  const doc = await client.documents.getV0(documentId);

  // Verify the requesting user is the owner or a recipient
  const isOwner = doc.userId === parseInt(userId);
  const isRecipient = doc.recipients?.some(r => r.email === userEmail);

  if (!isOwner && !isRecipient) {
    throw new Error("Access denied: not authorized for this document");
  }

  return doc;
}
```

### Step 5: Signing Certificate Security (Self-Hosted)

Self-hosted Documenso requires a `.p12` signing certificate for legally valid digital signatures.

```bash
# Generate a self-signed certificate (development only)
openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes
openssl pkcs12 -export -out signing-cert.p12 -inkey key.pem -in cert.pem

# Mount into Docker container
docker run -v $(pwd)/signing-cert.p12:/opt/documenso/cert.p12 \
  -e NEXT_PRIVATE_SIGNING_LOCAL_FILE_PATH=/opt/documenso/cert.p12 \
  -e NEXT_PRIVATE_SIGNING_PASSPHRASE=your-passphrase \
  documenso/documenso:latest
```

For production, use a certificate from a trusted CA (e.g., GlobalSign, DigiCert).

### Step 6: Self-Hosted Production Secrets

```bash
# Generate cryptographically secure secrets
openssl rand -hex 32  # NEXTAUTH_SECRET
openssl rand -hex 32  # NEXT_PRIVATE_ENCRYPTION_KEY
openssl rand -hex 32  # NEXT_PRIVATE_ENCRYPTION_SECONDARY_KEY

# Never reuse secrets across environments
# Never use default values in production
```

## Security Checklist

- [ ] API key stored in environment variable, never in source code
- [ ] `.env` in `.gitignore`
- [ ] CI secrets use masked/encrypted storage
- [ ] Team keys rotated on employee offboarding
- [ ] Webhook secret uses constant-time comparison
- [ ] Self-hosted: HTTPS with valid TLS certificates
- [ ] Self-hosted: signing certificate from trusted CA
- [ ] Self-hosted: secrets generated with `openssl rand -hex 32`
- [ ] No API keys or secrets in logs (sanitize before logging)
- [ ] Key rotation procedure documented and tested

## Error Handling

| Security Issue | Indicator | Response |
|---------------|-----------|----------|
| Invalid API key | 401 errors | Rotate key immediately |
| Webhook spoofing | Inv

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (0)

No findings outside the package's declared scope.

Gates applied: no_behavioural_pass.