rsc-universal 0.1.1

package/skills/e-signature/SKILL.md

@@ -0,0 +1,185 @@
+---
+name: e-signature
+description: "Use when adding legally-valid electronic-signature flows to documents — sending a PDF or template for signature, embedding signing in your own app, tracking status, verifying signing webhooks, and retrieving the signed PDF plus its audit trail via DocuSign or Dropbox Sign. Triggers: 'send this contract for signature', 'create a DocuSign envelope', 'signature_request/send', 'embed signing in our app', 'notify us when it's signed', 'set up DocuSign JWT auth', 'is a typed-name signature legally binding?', 'do we need QES for EU customers?', 'enviar a firmar', 'firma electrònica amb validesa legal'. NOT drafting the contract text itself (that is contracts) and NOT OCR/parsing/extracting fields from documents (that is document-processing)."
+tags: [e-signature, docusign, dropbox-sign, esignature-api, webhooks, eidas, esign-act, audit-trail]
+recommends: [contracts, document-processing, webhooks, api-connector-builder, gdpr-privacy, automation-flows]
+origin: risco
+---
+
+# e-signature
+
+You are wiring a third-party signing API (DocuSign eSignature or Dropbox Sign, ex-HelloSign) into someone's app or backend. You take a PDF or template, define signers and fields, send it for signature, track status, react to completion via a verified webhook, and retrieve the signed PDF plus its audit trail.
+
+You are NOT writing the contract language — clauses, indemnity, liability go to `../contracts/SKILL.md`. You are NOT doing OCR, field extraction, or PDF splitting with no signing involved — that is `../document-processing/SKILL.md`. You only build the signing flow.
+
+## Three rules
+
+1. **Pick the legal tier deliberately, before you write code.** A typed name (SES) is binding for most B2B in the US and EU, but a high-stakes EU document may need AES or QES. Choosing the tier decides which provider features you enable (ID Verification, SMS/access code, qualified signature). Get this wrong and the signature is hard to defend in court.
+2. **Sandbox / `test_mode` before prod, always.** A live send is billable and emails a real human. DocuSign demo env is `https://demo.docusign.net`; Dropbox Sign uses `test_mode: 1`. Only non-test sends count against quota and reach signers.
+3. **The deliverable is the signed PDF + audit trail, retrieved and stored.** A send is not done when status is `sent` — it is done when the signer completes and you have pulled the signed document AND its evidence (DocuSign Certificate of Completion, Dropbox Sign audit-trail PDF). Fire-and-forget is the most common bug here.
+
+## Decision: which legal tier do you need?
+
+US law (ESIGN Act + UETA) has **no tiers** — e-signatures equal wet ink. The EU (eIDAS, and eIDAS 2.0 / Reg (EU) 2024/1183 in force since May 2024) defines three. Map the document's stakes to a tier, then to a provider feature.
+
+| Tier | What it is | When you need it | Provider feature to enable |
+|------|-----------|------------------|----------------------------|
+| **SES** (Simple) | Typed or drawn signature, basic intent + audit trail | Most B2B: offers, NDAs, quotes, US contracts generally | Default flow — just capture the signature + keep the audit trail |
+| **AES** (Advanced) | Uniquely linked to signer, identity-verified, tamper-evident | Higher-value EU contracts, regulated sectors | ID Verification, SMS/access-code auth, signer authentication step |
+| **QES** (Qualified) | EU handwritten-equivalent EU-wide; qualified cert via a QTSP | Where law mandates it (some real-estate, gov, regulated finance) | Qualified signature add-on through a Qualified Trust Service Provider |
+
+If the document is genuinely high-stakes or you are unsure whether a tier is legally mandated, escalate to a lawyer and to `../contracts/SKILL.md` — you do not give legal advice. Detail and the court-admissibility checklist live in `references/legal-tiers.md`.
+
+## Decision: which provider?
+
+Either is fine. Pick one and stay on it so you keep **one** consistent audit trail.
+
+| | DocuSign eSignature | Dropbox Sign (ex-HelloSign) |
+|---|---|---|
+| Auth | OAuth 2.0 **JWT Grant** (RSA keypair, impersonation, one-time consent) | API key (header bearer) |
+| Core call | create **Envelope** | `signature_request/send` |
+| Node SDK | `docusign-esign` (9.0.0) | `@dropbox/sign` (1.11.0) — replaces deprecated `hellosign-sdk` |
+| Embedded | `clientUserId` on recipient + recipient view URL | `signature_request/create_embedded` |
+| Pricing posture | seat/envelope, enterprise-leaning | API: Essentials ~$75/mo (50+ requests, embedded signing included), Standard ~$250/mo annual (adds bulk send + higher volume), free `test_mode` |
+| EU / QES | mature QES + ID Verification | SES/AES focus; check current QES support |
+
+## Auth & setup
+
+Never commit keys. Read everything from env; the RSA private key lives in a secret store or a file path, never inline in source.
+
+| Env var | Provider | Holds |
+|---------|----------|-------|
+| `DOCUSIGN_INTEGRATION_KEY` | DocuSign | client/integration key (GUID) |
+| `DOCUSIGN_USER_ID` | DocuSign | GUID of the user being impersonated |
+| `DOCUSIGN_ACCOUNT_ID` | DocuSign | API account ID |
+| `DOCUSIGN_PRIVATE_KEY` | DocuSign | RSA private key (PEM) — from secret store |
+| `DOCUSIGN_BASE_PATH` | DocuSign | `https://demo.docusign.net/restapi` in sandbox |
+| `DROPBOX_SIGN_API_KEY` | Dropbox Sign | API key |
+
+**DocuSign JWT Grant — five steps** (full walk-through in `references/docusign.md`):
+
+1. Create the integration key + RSA keypair in the DocuSign admin console.
+2. Grant **one-time consent**: visit the consent URL once as the impersonated user (`.../oauth/auth?response_type=code&scope=signature%20impersonation&client_id=...&redirect_uri=...`).
+3. Request a JWT user token (`scope: signature impersonation`), signed with the RSA private key.
+4. Call `/oauth/userinfo` to discover the account's correct **base path** — do not hardcode the prod host while testing.
+5. Use the returned access token + base path for all API calls; refresh before expiry.
+
+Dropbox Sign needs only the API key as a bearer credential — see `references/dropbox-sign.md`.
+
+```bash
+# Bad: key in source, prod host while testing
+const apiKey = "hs_live_abc123";          # committed secret
+const base   = "https://www.docusign.net"; # prod during a test
+
+# Good: from env, sandbox first
+export DROPBOX_SIGN_API_KEY="$(op read op://vault/dropbox-sign/key)"
+export DOCUSIGN_BASE_PATH="https://demo.docusign.net/restapi"
+```
+
+## Send flow — DocuSign
+
+The core object is an **Envelope**. `status: "sent"` sends immediately; `status: "created"` saves a draft. Anchor strings let you place tabs by text in the PDF instead of fixed coordinates.
+
+```javascript
+import docusign from "docusign-esign";
+
+const env = {
+  emailSubject: "Please sign: Offer letter",
+  documents: [{
+    documentBase64: pdfBuffer.toString("base64"),
+    name: "Offer.pdf", fileExtension: "pdf", documentId: "1",
+  }],
+  recipients: {
+    signers: [{
+      email: signer.email, name: signer.name,
+      recipientId: "1", routingOrder: "1",
+      tabs: { signHereTabs: [{ anchorString: "/sig1/", anchorYOffset: "-10" }] },
+    }],
+  },
+  status: "sent", // "created" for a draft you send later
+};
+
+const api = new docusign.EnvelopesApi(apiClient); // apiClient configured with JWT token + base path
+const result = await api.createEnvelope(accountId, { envelopeDefinition: env });
+// store result.envelopeId — your handle for status, webhook correlation, and retrieval
+```
+
+For templates, send with `templateId` + `templateRoles` (prefilled tabs) instead of raw documents. Envelope/tabs anatomy and template send are in `references/docusign.md`.
+
+## Send flow — Dropbox Sign
+
+The core call is `signature_request/send` (or `signature_request/send_with_template`). Keep `testMode: true` until you intend to spend a real request.
+
+```javascript
+import * as DropboxSign from "@dropbox/sign";
+
+const api = new DropboxSign.SignatureRequestApi();
+api.username = process.env.DROPBOX_SIGN_API_KEY; // API key as username
+
+const res = await api.signatureRequestSend({
+  title: "Offer letter",
+  subject: "Please sign",
+  signers: [{ emailAddress: signer.email, name: signer.name, order: 0 }],
+  files: [pdfBuffer], // or fileUrls
+  testMode: true, // flip to false ONLY when going live
+});
+// store res.body.signatureRequest.signatureRequestId
+```
+
+`send_with_template` takes `templateIds` + `signers` mapped to template roles. Details and embedded creation are in `references/dropbox-sign.md`.
+
+## Embedded vs remote signing
+
+- **Remote** (default): provider emails the signer a link. Nothing extra to build.
+- **Embedded** (signer signs inside your own UI): DocuSign requires a `clientUserId` on the recipient, then you request a recipient view URL and iframe/redirect to it. Dropbox Sign uses `signature_request/create_embedded` + the embedded sign URL. Embedded signing is included from the Dropbox Sign Essentials API plan up (it is not a Standard-only feature) — but it still requires a paid API plan, not `test_mode` alone.
+
+## Webhooks / completion
+
+**Verify the signature before you trust anything in the payload.** The body is attacker-controllable until you have verified it.
+
+- **DocuSign Connect**: HMAC-signed; verify the `X-DocuSign-Signature-1` header against the raw request body using your Connect HMAC key.
+- **Dropbox Sign event callbacks**: `event_hash` = HMAC-SHA256 of `event_time + event_type`, keyed by your **API key**.
+
+```javascript
+import crypto from "node:crypto";
+
+// Dropbox Sign: verify event_hash before processing
+function verifyDropboxSign(event, apiKey) {
+  const expected = crypto
+    .createHmac("sha256", apiKey)
+    .update(event.event.event_time + event.event.event_type)
+    .digest("hex");
+  return crypto.timingSafeEqual(
+    Buffer.from(expected), Buffer.from(event.event.event_hash));
+}
+
+// On a verified completion event: retrieve BOTH artifacts, idempotently
+async function onCompleted(requestId) {
+  if (await alreadyHandled(requestId)) return;     // idempotency guard
+  const signedPdf  = await api.signatureRequestFiles(requestId, "pdf");
+  const auditTrail = await api.signatureRequestFiles(requestId, "pdf", { fileType: "audit" });
+  await store(requestId, signedPdf, auditTrail);   // store IDs + bytes, never log bytes
+  await markHandled(requestId);
+}
+```
+
+For DocuSign, on the `Completed` envelope event call `EnvelopesApi.getDocument` for the signed PDF and for `certificate` to get the **Certificate of Completion**. HMAC verification code and Connect setup are in `references/docusign.md`.
+
+## Anti-patterns
+
+| Anti-pattern | Why it is wrong | Do instead |
+|--------------|-----------------|-----------|
+| Processing a webhook payload without verifying the signature | Anyone can POST a fake `completed` event | Verify HMAC (`X-DocuSign-Signature-1` / `event_hash`) on the raw body first |
+| Trusting `status` from the request body you sent | Status lives with the provider, not your hope | Read status from the verified webhook or a status fetch |
+| Sending from prod while still testing | Bills you and emails real people with test docs | DocuSign `demo.docusign.net`; Dropbox Sign `testMode: true` |
+| Logging full document/envelope bytes or signer PII | Leaks the very PII the signature protects | Log provider IDs only; store bytes in a secret-aware store |
+| Storing the signed PDF but not the audit trail | SES is hard to defend in court without who/what/when/where | Always pull the Certificate of Completion / audit-trail PDF too |
+| Reusing one envelope/request to "retry" a send | Duplicates, double-bills, corrupts status | New request per send; use an idempotency guard on completion |
+| Hardcoding the API key / RSA private key in source | Secret leak on first push | Env vars + secret store; key file path, never inline |
+| Skipping the legal-tier decision | Ship a signature that is not legally adequate | Pick SES/AES/QES first; escalate high-stakes to a lawyer + `../contracts/SKILL.md` |
+
+## Verify
+
+Run `scripts/verify.sh <path-to-integration>` against the code you produced. It greps the artifact (no live API call) for: webhook signature verification present and not a TODO, no hardcoded API key or `BEGIN PRIVATE KEY`, a sandbox/`test_mode` guard, and a completion path that retrieves the signed PDF + audit trail. It is read-only and exits 0 on a clean/empty target.
+
+For data-protection touchpoints (consent, retention of signed docs + PII), flag them and route the policy writing to `../gdpr-privacy/SKILL.md`. For non-signing inbound webhook infrastructure, see `../webhooks/SKILL.md`.

package/skills/e-signature/evals/README.md

@@ -0,0 +1,3 @@
+# e-signature evals
+
+`cases.yaml` holds two kinds of checks. `should_trigger` and `should_not_trigger` are routing assertions for the skill's description: each prompt is matched against the catalog router and we confirm e-signature is (or is not) selected, with `should_not_trigger` naming the real sibling that should win instead. `capability` is a rubric-graded scenario: a model implements the described DocuSign integration and a grader (human or LLM) checks the produced code against the `must_include` list — JWT auth, sandbox base path, envelope with explicit status, HMAC webhook verification on the raw body, idempotency, retrieval of both the signed PDF and the audit trail, no hardcoded secrets, and a deliberate legal-tier choice. Run them through the catalog's standard eval harness; routing cases are automatic, the capability case is graded against a generated artifact (and `scripts/verify.sh` can pre-screen that artifact mechanically).

package/skills/e-signature/evals/cases.yaml

@@ -0,0 +1,44 @@
+skill: e-signature
+
+should_trigger:
+  - prompt: "Send this signed offer letter out for signature via DocuSign and let me know when it's done"
+    why: Core send-for-signature plus completion notification — the central flow of the skill.
+  - prompt: "Wire up Dropbox Sign signature_request/send in our Node backend"
+    why: Names the provider and the exact endpoint; unambiguous integration request.
+  - prompt: "Verify the DocuSign Connect webhook and download the signed PDF + certificate of completion when an envelope completes"
+    why: Webhook signature verification plus audit-trail retrieval — the non-obvious depth that distinguishes a correct integration from fire-and-forget.
+  - prompt: "Is a typed-name e-signature legally binding for our EU customers, or do we need QES?"
+    why: Legal-tier triage with no API verb — non-obvious trigger the skill explicitly handles (SES vs QES under eIDAS).
+  - prompt: "Necessitem enviar el contracte a signar amb validesa legal i guardar el rastre d'auditoria"
+    why: Catalan phrasing for send-for-signature with legal validity and storing the audit trail.
+  - prompt: "Set up DocuSign JWT auth so our server can send envelopes without a user logging in"
+    why: JWT Grant server integration — a named setup task the skill covers in detail.
+
+should_not_trigger:
+  - prompt: "Redline the indemnity clause in this MSA and tighten the liability cap"
+    route_to: contracts
+    why: Drafting and reviewing contract text, not building a signing flow.
+  - prompt: "Extract the parties and signature dates from these scanned PDF contracts"
+    route_to: document-processing
+    why: OCR and field extraction with no signing involved.
+  - prompt: "Set up a generic inbound webhook receiver for our Stripe payment events"
+    route_to: webhooks
+    why: Non-signing webhook infrastructure; e-signature only covers signing-event payloads.
+  - prompt: "Write our GDPR data-retention policy for signed documents"
+    route_to: gdpr-privacy
+    why: Policy writing, not the signing integration; e-signature only flags the touchpoints.
+  - prompt: "Build a REST connector to a niche vendor API we have no SDK for"
+    route_to: api-connector-builder
+    why: Generic connector construction, not a signing flow.
+
+capability:
+  - scenario: "Implement DocuSign send-for-signature with JWT auth and a Connect webhook that, on completion, stores the signed PDF plus its audit trail."
+    must_include:
+      - JWT Grant auth — RSA key, impersonated user GUID, one-time consent
+      - base path discovered via /oauth/userinfo, sandbox (demo.docusign.net) before prod
+      - create-envelope with recipients and tabs (anchor or position) and an explicit status (sent vs created)
+      - Connect HMAC signature verification (X-DocuSign-Signature-1) against the raw body BEFORE trusting the payload
+      - idempotent completion handling (no double-processing on retries)
+      - download the signed PDF AND the Certificate of Completion / audit trail, then store
+      - no hardcoded API key or RSA private key in source; env vars / secret store
+      - pick the legal tier (SES/AES/QES) deliberately; recommend a lawyer + contracts for high-stakes docs

package/skills/e-signature/references/docusign.md

@@ -0,0 +1,83 @@
+# DocuSign eSignature — JWT Grant, envelopes, Connect
+
+Node SDK: `docusign-esign` 9.0.0. API version path: `/restapi/v2.1`.
+
+## JWT Grant auth (server / system integration)
+
+Use JWT Grant when no human is present to do an interactive OAuth login — a backend impersonating a service user.
+
+1. **Integration key + RSA keypair.** In the DocuSign admin console (Apps and Keys), create an integration key, then generate an RSA keypair. Keep the private key in a secret store; DocuSign keeps the public key.
+2. **One-time consent.** JWT impersonation requires the impersonated user to have consented once. Build the consent URL and open it as that user:
+   ```text
+   https://account-d.docusign.com/oauth/auth?response_type=code
+     &scope=signature%20impersonation
+     &client_id=<INTEGRATION_KEY>
+     &redirect_uri=<YOUR_REDIRECT>
+   ```
+   (`account-d.docusign.com` is the demo/sandbox auth host; prod is `account.docusign.com`.)
+3. **Request a user token.** Sign a JWT assertion with the RSA private key, `scope: signature impersonation`, `sub` = impersonated user GUID, and exchange it at `/oauth/token` for an access token. The SDK's `requestJWTUserToken` does this.
+4. **Discover the base path.** Call `GET /oauth/userinfo` with the token; read the account's `base_uri` and append `/restapi`. Do NOT hardcode the prod host while testing — sandbox is `https://demo.docusign.net/restapi`.
+5. **Use token + base path** for all `EnvelopesApi` calls. Tokens expire (~1h); refresh before expiry.
+
+```javascript
+import docusign from "docusign-esign";
+import fs from "node:fs";
+
+const apiClient = new docusign.ApiClient();
+apiClient.setOAuthBasePath("account-d.docusign.com"); // demo
+const results = await apiClient.requestJWTUserToken(
+  process.env.DOCUSIGN_INTEGRATION_KEY,
+  process.env.DOCUSIGN_USER_ID,
+  ["signature", "impersonation"],
+  fs.readFileSync(process.env.DOCUSIGN_PRIVATE_KEY_PATH),
+  3600,
+);
+const token = results.body.access_token;
+
+const userInfo = await apiClient.getUserInfo(token);
+const account  = userInfo.accounts.find(a => a.isDefault === "true");
+apiClient.setBasePath(account.baseUri + "/restapi");
+apiClient.addDefaultHeader("Authorization", "Bearer " + token);
+```
+
+## Envelope and tabs anatomy
+
+- **Envelope** wraps documents + recipients + the lifecycle (`created` → `sent` → `delivered` → `completed`/`declined`/`voided`).
+- **Documents**: base64 with `documentId`, `name`, `fileExtension`.
+- **Recipients.signers**: each has `recipientId`, `routingOrder` (signing order), `email`, `name`.
+- **Tabs**: `signHere`, `dateSigned`, `text`, etc. Place by `xPosition`/`yPosition` + `pageNumber`, or by `anchorString` (text already in the PDF, e.g. `/sig1/`) with `anchorXOffset`/`anchorYOffset`. Prefer anchors — they survive layout changes.
+- `clientUserId` on a signer marks them as an **embedded** (captive) signer; you then request a recipient view URL.
+
+## Templates
+
+Reusable envelope skeletons. Send with `templateId` + `templateRoles` (map a role name to email/name + prefilled `tabs`), no raw document needed.
+
+## Connect webhooks + HMAC verification
+
+DocuSign Connect pushes envelope events to your endpoint. Enable HMAC in the Connect config to get a signing key; DocuSign sends `X-DocuSign-Signature-1` (and -2 during key rotation).
+
+```javascript
+import crypto from "node:crypto";
+
+function verifyDocuSign(rawBody, headerSig, hmacKey) {
+  const computed = crypto
+    .createHmac("sha256", hmacKey)
+    .update(rawBody, "utf8")
+    .digest("base64");
+  return crypto.timingSafeEqual(
+    Buffer.from(computed), Buffer.from(headerSig));
+}
+```
+
+Verify against the **raw** request body (not a re-serialized object). On a verified `Completed` event:
+
+```javascript
+const signedPdf   = await envelopesApi.getDocument(accountId, envelopeId, "combined");
+const certificate = await envelopesApi.getDocument(accountId, envelopeId, "certificate");
+```
+
+`"certificate"` returns the **Certificate of Completion** — the court-facing audit trail. Store both.
+
+## Demo → prod go-live
+
+Build entirely on `demo.docusign.net`. To go live, submit the integration key for review / promote it to production through the admin console, then switch the OAuth host to `account.docusign.com` and base path to the prod `base_uri`. Re-grant consent in prod.

package/skills/e-signature/references/dropbox-sign.md

@@ -0,0 +1,73 @@
+# Dropbox Sign (ex-HelloSign) — API key, send, embedded, callbacks
+
+Node SDK: `@dropbox/sign` 1.11.0. It replaces the deprecated `hellosign-sdk`. If you find `hellosign-sdk` in a codebase, migrate.
+
+## API key setup
+
+A single API key authenticates as the account. Pass it as the HTTP basic username (no password), which the SDK handles via `api.username = process.env.DROPBOX_SIGN_API_KEY`. Never commit it; read from env / secret store.
+
+## Which call?
+
+| Call | Use when |
+|------|----------|
+| `signature_request/send` | One-off send with raw files |
+| `signature_request/send_with_template` | Reusable template + role mapping |
+| `signature_request/create_embedded` | Signer signs inside your own UI |
+| `signature_request/create_embedded_with_template` | Embedded + template |
+
+**Only non-`test_mode` POSTs to these endpoints count against quota.** Keep `testMode: true` for all development; flip to `false` only on a deliberate live send.
+
+```javascript
+import * as DropboxSign from "@dropbox/sign";
+
+const api = new DropboxSign.SignatureRequestApi();
+api.username = process.env.DROPBOX_SIGN_API_KEY;
+
+// Template send with role mapping
+const res = await api.signatureRequestSendWithTemplate({
+  templateIds: ["<TEMPLATE_ID>"],
+  subject: "Please sign",
+  signers: [{ role: "Client", emailAddress: signer.email, name: signer.name }],
+  testMode: true,
+});
+const id = res.body.signatureRequest.signatureRequestId;
+```
+
+Signing order is the `order` field on each signer; fields are `customFields` / form fields keyed by API id.
+
+## Embedded signing
+
+`create_embedded` returns signature ids; call `embedded/sign_url` for each to get a short-lived URL, then mount it with the Dropbox Sign embedded JS client. Embedded signing is included from the Essentials API plan up (~$75/mo, 50+ requests) — it is not gated to Standard. What you cannot do is embed on `test_mode` alone with no paid API plan.
+
+## Event callback verification
+
+Dropbox Sign POSTs a JSON callback for events (`signature_request_signed`, `signature_request_all_signed`, etc.). Verify before trusting:
+
+`event_hash` = `HMAC-SHA256( event_time + event_type )` keyed by your **API key**.
+
+```javascript
+import crypto from "node:crypto";
+
+function verify(event, apiKey) {
+  const expected = crypto
+    .createHmac("sha256", apiKey)
+    .update(event.event.event_time + event.event.event_type)
+    .digest("hex");
+  return crypto.timingSafeEqual(
+    Buffer.from(expected), Buffer.from(event.event.event_hash));
+}
+```
+
+Your endpoint must respond with the literal body `Hello API Event Received` (HTTP 200) or Dropbox Sign treats the callback as failed and retries.
+
+## On completion: retrieve both artifacts
+
+```javascript
+const files = new DropboxSign.SignatureRequestApi();
+files.username = process.env.DROPBOX_SIGN_API_KEY;
+
+const signed = await files.signatureRequestFiles(requestId, "pdf");
+const audit  = await files.signatureRequestFiles(requestId, "pdf", { fileType: "audit" });
+```
+
+Store the signed PDF AND the audit-trail PDF. Persist the `signatureRequestId`; never log document bytes or signer PII.

package/skills/e-signature/references/legal-tiers.md

@@ -0,0 +1,37 @@
+# Legal tiers — SES / AES / QES (NOT legal advice)
+
+This is engineering orientation so you wire the right provider features. It is **not legal advice**. For anything high-stakes or jurisdiction-specific, escalate to a lawyer and to `../contracts/SKILL.md`.
+
+## US: no tiers
+
+The **ESIGN Act** (federal) and **UETA** (state-adopted) make an electronic signature legally equivalent to a wet-ink one, with no tiered system. What matters: intent to sign, consent to do business electronically, association of the signature with the record, and retention of the record. A typed name with a captured audit trail is generally binding.
+
+## EU: three tiers under eIDAS
+
+**eIDAS** (and **eIDAS 2.0 — Reg (EU) 2024/1183**, in force since May 2024, which drives the EUDI Wallet) defines:
+
+| Tier | Definition | Legal weight |
+|------|-----------|--------------|
+| **SES** — Simple | Data in electronic form used to sign; minimal identity assurance | Admissible, but the burden of proving it is on you |
+| **AES** — Advanced | Uniquely linked to and capable of identifying the signer; signer-controlled; tamper-evident | Strong evidentiary value |
+| **QES** — Qualified | AES + a qualified certificate from a **Qualified Trust Service Provider (QTSP)** + qualified signature-creation device | Legally equivalent to a handwritten signature EU-wide; explicitly required by some laws |
+
+Use SES for routine B2B. Step up to AES when you need identity assurance / tamper-evidence (enable ID Verification, SMS/access-code auth). Use QES only when a law mandates it (certain real-estate, government, regulated finance) — it requires a QTSP relationship, not just a flag.
+
+## The audit trail is the load-bearing evidence
+
+Whatever the tier, the **audit trail is what defends the signature in court**: who signed, what they signed, when, from where, and proof the document was not altered after. DocuSign emits a **Certificate of Completion**; Dropbox Sign provides an **audit-trail PDF**. Without it, even a valid SES is hard to defend.
+
+### Court-admissibility checklist
+
+- [ ] Signer identity captured (email, name, and for AES/QES an identity check)
+- [ ] Intent to sign recorded (the signing action, not a pre-checked box)
+- [ ] Consent to electronic process captured
+- [ ] Timestamp + IP / location in the audit trail
+- [ ] Tamper-evidence / document hash so post-signature edits are detectable
+- [ ] Both the signed PDF AND the audit-trail document retrieved and stored
+- [ ] Retention period defined for the signed doc + its PII (policy → `../gdpr-privacy/SKILL.md`)
+
+## When to escalate
+
+Escalate to a lawyer (and route contract-text questions to `../contracts/SKILL.md`) when: the document is high-value or high-risk; a specific law may mandate QES; the deal crosses jurisdictions with different e-signature rules; or someone asks whether a particular signature would "hold up in court." You implement the flow — you do not rule on legal sufficiency.

package/skills/e-signature/scripts/verify.sh

@@ -0,0 +1,81 @@
+#!/usr/bin/env bash
+# verify.sh — read-only static check of an e-signature integration artifact.
+# Greps the produced code for the must-haves of a safe signing flow.
+# It does NOT call any live API and never modifies files.
+#
+# Usage: scripts/verify.sh [path]   (default: current directory)
+# Exit:  0 = clean / nothing to flag, 1 = at least one FAIL.
+
+set -euo pipefail
+
+TARGET="${1:-.}"
+
+if [ ! -e "$TARGET" ]; then
+  echo "verify.sh: target '$TARGET' does not exist" >&2
+  exit 1
+fi
+
+# Collect candidate source files (signing-integration code). Empty list => clean pass.
+FILES=()
+while IFS= read -r f; do
+  [ -n "$f" ] && FILES+=("$f")
+done < <(
+  grep -rIl -E 'docusign|dropbox/sign|signature_request|EnvelopesApi|SignatureRequestApi|event_hash|X-DocuSign-Signature' \
+    --include='*.js' --include='*.ts' --include='*.mjs' --include='*.cjs' \
+    --include='*.py' --include='*.go' --include='*.rb' \
+    "$TARGET" 2>/dev/null || true
+)
+
+if [ "${#FILES[@]}" -eq 0 ]; then
+  echo "PASS: no e-signature integration code found in '$TARGET' (nothing to check)"
+  exit 0
+fi
+
+echo "Checking ${#FILES[@]} file(s) under '$TARGET'..."
+FAIL=0
+pass() { echo "PASS: $1"; }
+fail() { echo "FAIL: $1"; FAIL=1; }
+
+# Search helper: matches pattern, excluding comment/TODO-only lines.
+has_real() {
+  # $1 = ERE pattern
+  grep -rIhE "$1" "${FILES[@]}" 2>/dev/null \
+    | grep -vE '^\s*(//|#|\*)' \
+    | grep -viE 'TODO|FIXME|XXX' \
+    | grep -q .
+}
+
+# 1. Webhook signature verification present (and not only a TODO).
+if has_real 'createHmac|hmac\.new|X-DocuSign-Signature|event_hash|timingSafeEqual|compare_digest'; then
+  pass "webhook signature verification present"
+else
+  fail "no webhook signature verification (expected HMAC / event_hash / X-DocuSign-Signature check)"
+fi
+
+# 2. No hardcoded API key or private key in source.
+if grep -rIhE 'hs_live_|BEGIN (RSA )?PRIVATE KEY|api[_-]?key\s*[:=]\s*["'"'"'][A-Za-z0-9]{16,}' "${FILES[@]}" 2>/dev/null | grep -q .; then
+  fail "hardcoded secret detected (API key or PRIVATE KEY literal in source)"
+else
+  pass "no hardcoded API key / private key literal"
+fi
+
+# 3. Sandbox / test_mode guard present.
+if has_real 'demo\.docusign\.net|account-d\.docusign\.com|test_?[mM]ode'; then
+  pass "sandbox / test_mode guard present"
+else
+  fail "no sandbox guard (expected demo.docusign.net or test_mode)"
+fi
+
+# 4. Completion path retrieves signed PDF + audit trail / certificate.
+if has_real 'certificate|audit'; then
+  pass "completion retrieves audit trail / certificate"
+else
+  fail "completion path does not retrieve the audit trail / Certificate of Completion"
+fi
+
+if [ "$FAIL" -ne 0 ]; then
+  echo "verify.sh: one or more checks FAILED"
+  exit 1
+fi
+echo "verify.sh: all checks passed"
+exit 0