DocuSign Integration

Investigated 2026-07-16 against the DocuSign IAM extension-app framework and its official reference implementations. Conclusion up front: Align fits the framework well as a File IO extension app, and the integration lives entirely in a new execution-layer adapter — zero changes to the ontology / semantic / context layers.

---

1 · How the framework actually worksCopy Anchor Link

DocuSign never hosts your code. An extension app is your own backend, registered via a JSON manifest in the Developer Console. The manifest declares:

Steps in a Maestro workflow (or Navigator / eSignature envelopes for some types) invoke those action URIs at runtime.

Extension types currently offered:

• File Output (cloud storage) — DocuSign pushes an agreement file to you. Actions: WriteFile, ListDrives, ListDirectoryContents.
• File Input (cloud storage) — DocuSign pulls files from you (incl. Navigator ingestion). Actions: Search, GetFile, ListDrives, ListDirectoryContents.
• Data IO — CRUD against your system from workflows (CreateRecord, SearchRecords, PatchRecord, …).
• Data Verification — real-time field validation (bank account, address, SSN, …).
• Connected Fields — real-time custom verification inside eSignature envelopes.

Hard requirements (from the reference implementations)Copy Anchor Link

1. Your backend must BE an OAuth2 provider. DocuSign's connection points at your /api/oauth/authorize + /api/oauth/token (+ a userinfo endpoint); it stores the token and sends it as a Bearer JWT on every action call (reference implementations use HS256). Public apps must use Authorization Code Grant; private apps may use Client Credentials — much simpler, and private distribution is the right fit for Align.

2. Public HTTPS + fast responses. Dev loop is local server + ngrok (DocuSign's own READMEs use it); Docker/Terraform recipes are provided for AWS/Azure/GCP. Action calls are synchronous with short timeouts (~15 s), and delivery is at-least-once → every action must be idempotent.

3. Fixed contracts per template. WriteFile request body:

   Copy Text

   { "files": [ { "basename": "agreement.pdf", "contents": "<base64>", "path": "/reviews" } ],
     "overwrite": true, "metadata": { } }

   Response is a simple JSON ({ "message": "..." }). GetFile / ListDirectoryContents / ListDrives / Search follow similarly small JSON shapes (see the reference repos below).

---

2 · The Align integration designCopy Anchor Link

The natural shape is two File IO extensions in one app, wrapping the review loop:

Inbound — DocuSign → Align (File Output extension)Copy Anchor Link

A Maestro step "archives" the agreement PDF to Align as if we were cloud storage:

1. WriteFile arrives with the base64 PDF.
2. Our handler decodes it and drives the existing document-upload path: create a docreview room, index for RAG, build the knowledge graph, parse sections — all code that already exists in execution/http-api.js services.
3. Respond immediately (room code in the response message/metadata) — well inside the 15 s timeout. The 4-minute human session happens asynchronously in Align's own web UI; real-time Socket.IO chat is not a DocuSign surface and stays ours.
4. Idempotency: key on file hash + envelope metadata → repeated deliveries return the same room instead of creating duplicates.

Outbound — Align → DocuSign (File Input extension)Copy Anchor Link

Once the session ends, the annotated review record (already auto-generated at session end) becomes retrievable:

• ListDrives / ListDirectoryContents expose ended rooms as folders,
• GetFile serves the review-record PDF,
• a later Maestro step (or Navigator ingestion) pulls it back into the agreement trail.

Alternative outbound route: call the eSignature REST API directly to attach the record to the envelope — but that is a normal API integration with its own auth, outside the extension framework; the File Input route keeps everything in one manifest.

Workflow-shape caveatCopy Anchor Link

An extension action cannot block on a human review. The Maestro workflow should either treat Align review as fire-and-forget at the end (post-completion review), or be split into two workflows — deliver-to-Align, then a second flow triggered once the record is retrievable.

---

3 · Fit with Align's architecture and constraintsCopy Anchor Link

• New file: server/execution/docusign-api.js — OAuth provider endpoints (/api/oauth/authorize, /token, /userinfo) + the five action endpoints, plus a manifest.json in the repo. It calls the same room/document services http-api.js uses. Ontology, semantic and context layers are untouched — the layers boundary test stays green by construction.
• Node 12 is fine. DocuSign's reference implementations are TypeScript with express-jwt@8 (needs Node ≥ 14), but none of that stack is required — the contract is plain JSON-over-HTTPS, and HS256 JWT sign/verify is ~15 lines of built-in crypto.createHmac. Express 4.18.2 is already pinned.
• ngrok is the sanctioned dev loop — our static free-tier domain keeps the manifest URIs stable across restarts.
• The real deployment constraint is Ollama, not DocuSign: the backend must run next to the model, so a cloud deployment needs a host running Ollama alongside — or the extension endpoints proxied to wherever Align lives.
• Distribution: register as a private extension app (org-only) — no App Center review, no TOS/privacy URLs required, Client Credentials Grant allowed. A free DocuSign developer account is needed.

Rough effort: the OAuth mock + WriteFile + GetFile adapter is a day or two, most of it testable with the existing socket/HTTP harness plus the Developer Console's built-in extension test tools.

---

4 · SourcesCopy Anchor Link

• Extension apps overview
• Extensions and extension points
• App manifest reference
• Use extensions in Maestro workflows
• Maestro limitations
• Reference implementations (GitHub, the concrete contracts studied):
  • extension-app-file-output-cloud-storage-reference-implementation
  • extension-app-file-input-cloud-storage-reference-implementation
  • extension-app-data-io-reference-implementation
• Fast-track your extension apps with reference implementations