@semics-tech/emdash-esign 0.0.0-bootstrap.0 → 1.0.0-rc.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 semics
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,105 @@
-# @semics-tech/emdash-esign
+# semics E-sign
 
-Placeholder; no code. See https://github.com/semics-uk/emdash-plugins.
+Simple electronic signatures for [EmDash CMS](https://emdashcms.com): Markdown templates, one signer per
+envelope, a typed name with an optional drawn signature, a hash-chained audit trail, a signed PDF with a certificate, and a public
+`/verify` page. MIT licensed.
+
+The package holds the sandboxed core `semics-esign` (its default export) and the UI kit (`/ui`,
+`/integration`, and the Astro pages and components).
+
+**Documentation** (in `apps/docs/pages` of the repository):
+[install](https://github.com/semics-uk/emdash-plugins/blob/main/apps/docs/pages/install.md),
+[configure](https://github.com/semics-uk/emdash-plugins/blob/main/apps/docs/pages/configure.md), the
+[E-sign guide](https://github.com/semics-uk/emdash-plugins/blob/main/apps/docs/pages/esign.md),
+[data and retention](https://github.com/semics-uk/emdash-plugins/blob/main/apps/docs/pages/privacy.md).
+
+## Install
+
+```sh
+pnpm add @semics-tech/emdash-esign @emdash-cms/sandbox-workerd
+```
+
+```js
+// astro.config.mjs
+import semicsEsign from "@semics-tech/emdash-esign";
+import { esignIntegration } from "@semics-tech/emdash-esign/integration";
+import { esignUi } from "@semics-tech/emdash-esign/ui";
+import { defineConfig } from "astro/config";
+import emdash from "emdash/astro";
+
+export default defineConfig({
+	output: "server",
+	integrations: [
+		esignIntegration(),
+		emdash({
+			siteUrl: "https://sign.example.com",
+			sandboxRunner: "@emdash-cms/sandbox-workerd/sandbox",
+			sandboxed: [semicsEsign],
+			plugins: [esignUi()],
+		}),
+	],
+});
+```
+
+## Retention (operators)
+
+Settings: **Keep personal data (months)**, default 12, and **Keep signed records (years)**, default 7. Both count
+from when an envelope closed (completed, declined, voided or expired; a draft from its last edit). A daily job
+then:
+
+- after the personal-data period, deletes the signer's name, email, IP address, browser, typed name and drawn
+  strokes, the values they entered, any decline reason and their links, the envelope's prefilled values and
+  return URL, and the audit trail's raw personal values together with the salt that could prove them. Drafts
+  are deleted. The audit trail itself still verifies. These are the separate copies: the signed record keeps
+  what it printed (next point).
+- keeps the **signed record** (the signed PDF, the frozen document and the audit trail) until the
+  signed-records period ends. The signed PDF and document still show what was signed: the document may contain
+  the signer's name or email (`{{signer.name}}`, `{{signer.email}}`); the certificate prints the signer's name
+  and IP address, and the participant's name (a minor's name, when a guardian signed); and the signed PDF keeps
+  the values the signer entered under "Details entered by the signer". All of this stays until the
+  signed-records period ends. `/verify` keeps matching the PDF during this period.
+- after the signed-records period, deletes the PDF, document, audit trail and signer record; `/verify` no
+  longer recognises the PDF.
+
+Envelopes still out for signature are never purged. An unsigned one expires `expiryDays` after it was sent (an
+hourly job closes it, so retention can age it out); you can also void it. To delete one person's data on
+request, use **Delete personal data** on the Envelopes page (signer email or envelope id). It removes the
+personal data straight away but keeps the signed record for its own period.
+
+## Develop
+
+```sh
+pnpm install
+pnpm run validate
+pnpm run typecheck
+pnpm run test
+pnpm run build
+```
+
+`pnpm run test` builds the plugin and runs its tests through Worker Loader using EmDash's production sandbox
+wrapper and host bridge. To try it on a site, run `pnpm run dev` here (rebuilds on save) and link this folder
+into the site.
+
+## Publish
+
+```sh
+pnpm run login -- alice.example.com
+pnpm run publish          # builds and uploads artifacts to your PDS
+```
+
+To publish from GitHub Actions, run `pnpm run release:setup`. The command creates one shared workflow at the
+Git repository root.
+
+The registry listing (name, keywords, the description, installation, FAQ and security sections, icon, banner
+and screenshots) is declared in `emdash-plugin.jsonc` and kept in `listing/`. The images are made by the
+playground's `e2e/t103-screenshots.spec.ts`.
+
+## Version bumps
+
+Bump `version` in `package.json` when you ship a release. The scaffold's `emdash-plugin.jsonc` deliberately
+omits `version`: the build reads it from `package.json` so there's a single source of truth. **Bump major** for
+breaking changes, **bump minor** for new routes or hooks, **bump patch** for fixes.
+
+You MUST bump version whenever you change `capabilities`, `allowedHosts`, or `storage` in the manifest.
+Installed users have consented to the old trust contract; a change without a version bump would let new
+behaviour slip past consent.

package/dist/index.d.mts

@@ -0,0 +1,5 @@
+// Auto-generated by emdash-plugin build. Do not edit.
+import type { PluginDescriptor } from "emdash";
+
+declare const descriptor: PluginDescriptor;
+export default descriptor;

package/dist/index.mjs

@@ -0,0 +1,346 @@
+// Auto-generated by emdash-plugin build. Do not edit.
+// Source: emdash-plugin.jsonc + package.json
+//
+// Default-exports a sandboxed plugin descriptor. Pass it directly into
+// emdash's `plugins:` or `sandboxed:` array — no factory call needed.
+
+/** @type {import("emdash").PluginDescriptor} */
+const descriptor = Object.freeze({
+	"id": "semics-esign",
+	"version": "1.0.0-rc.0",
+	"format": "standard",
+	"entrypoint": "@semics-tech/emdash-esign/sandbox",
+	"capabilities": [
+		"media:read",
+		"media:bytes:read",
+		"network:request",
+		"email:send"
+	],
+	"allowedHosts": [
+		"challenges.cloudflare.com"
+	],
+	"storage": {
+		"templates": {
+			"indexes": [
+				"status",
+				"kind",
+				"public"
+			]
+		},
+		"envelopes": {
+			"indexes": [
+				"status",
+				"expiresAt",
+				"createdAt",
+				"clientId",
+				"externalRef",
+				"pdfSha256",
+				"signerEmail",
+				[
+					"status",
+					"expiresAt"
+				]
+			]
+		},
+		"signers": {
+			"indexes": [
+				"envelopeId",
+				"email",
+				"copyTokenHash"
+			],
+			"uniqueIndexes": [
+				"tokenHash"
+			]
+		},
+		"snapshots": {
+			"indexes": [
+				"envelopeId"
+			]
+		},
+		"artifacts": {
+			"indexes": [
+				"envelopeId",
+				[
+					"envelopeId",
+					"kind"
+				]
+			]
+		},
+		"audit_events": {
+			"indexes": [
+				"envelopeId",
+				[
+					"envelopeId",
+					"seq"
+				]
+			]
+		},
+		"clients": {
+			"indexes": [
+				"createdAt"
+			],
+			"uniqueIndexes": [
+				"clientId"
+			]
+		},
+		"nonces": {
+			"indexes": [
+				"expiresAt"
+			],
+			"uniqueIndexes": [
+				"nonce"
+			]
+		},
+		"outbox": {
+			"indexes": [
+				[
+					"status",
+					"nextAttemptAt"
+				]
+			]
+		}
+	},
+	"hooks": [
+		"plugin:activate",
+		"cron"
+	],
+	"routes": [
+		{
+			"name": "public/envelopes/from-intent",
+			"methods": [
+				"POST"
+			],
+			"request": {
+				"body": "json",
+				"maxBytes": 16384
+			},
+			"public": true
+		},
+		{
+			"name": "public/session",
+			"methods": [
+				"POST"
+			],
+			"request": {
+				"body": "json",
+				"maxBytes": 8192
+			},
+			"public": true
+		},
+		{
+			"name": "public/otp/send",
+			"methods": [
+				"POST"
+			],
+			"request": {
+				"body": "json",
+				"maxBytes": 8192
+			},
+			"public": true
+		},
+		{
+			"name": "public/otp/verify",
+			"methods": [
+				"POST"
+			],
+			"request": {
+				"body": "json",
+				"maxBytes": 8192
+			},
+			"public": true
+		},
+		{
+			"name": "public/submit",
+			"methods": [
+				"POST"
+			],
+			"request": {
+				"body": "json",
+				"maxBytes": 262144
+			},
+			"public": true
+		},
+		{
+			"name": "public/decline",
+			"methods": [
+				"POST"
+			],
+			"request": {
+				"body": "json",
+				"maxBytes": 8192
+			},
+			"public": true
+		},
+		{
+			"name": "public/download",
+			"methods": [
+				"GET"
+			],
+			"request": {
+				"body": "none"
+			},
+			"response": "raw",
+			"public": true
+		},
+		{
+			"name": "public/verify",
+			"methods": [
+				"POST"
+			],
+			"request": {
+				"body": "json",
+				"maxBytes": 8192
+			},
+			"public": true
+		},
+		{
+			"name": "public/receipts/lookup",
+			"methods": [
+				"POST"
+			],
+			"request": {
+				"body": "json",
+				"maxBytes": 8192
+			},
+			"public": true
+		},
+		{
+			"name": "public/templates/catalog",
+			"methods": [
+				"POST"
+			],
+			"request": {
+				"body": "json",
+				"maxBytes": 65536
+			},
+			"public": true
+		},
+		{
+			"name": "public/self-serve/start",
+			"methods": [
+				"POST"
+			],
+			"request": {
+				"body": "json",
+				"maxBytes": 65536
+			},
+			"public": true
+		},
+		"admin",
+		"templates/create",
+		"templates/update",
+		"templates/get",
+		"templates/list",
+		"templates/archive",
+		"envelopes/create",
+		"envelopes/send",
+		"envelopes/get",
+		"envelopes/list",
+		"envelopes/resend",
+		"envelopes/void",
+		"outbox/status"
+	],
+	"adminPages": [
+		{
+			"path": "/envelopes",
+			"label": "Envelopes",
+			"icon": "file"
+		},
+		{
+			"path": "/templates",
+			"label": "Templates",
+			"icon": "file-text"
+		},
+		{
+			"path": "/integrations",
+			"label": "Integrations",
+			"icon": "link"
+		},
+		{
+			"path": "/settings",
+			"label": "Settings",
+			"icon": "gear"
+		}
+	],
+	"settingsSchema": {
+		"senderName": {
+			"label": "Sender name",
+			"description": "Shown as the sender of signing emails.",
+			"type": "string"
+		},
+		"consentVersion": {
+			"label": "Consent version",
+			"description": "Recorded with every signature; bump when the wording changes.",
+			"type": "string",
+			"default": "1"
+		},
+		"consentWording": {
+			"label": "Consent wording",
+			"description": "Shown to signers before they sign.",
+			"type": "string",
+			"default": "I agree to use electronic records and an electronic signature for this document.",
+			"multiline": true
+		},
+		"expiryDays": {
+			"label": "Envelope expiry (days)",
+			"type": "number",
+			"default": 30,
+			"min": 1,
+			"max": 365
+		},
+		"reminderCadenceDays": {
+			"label": "Reminder cadence (days)",
+			"description": "Pro: automatic reminders.",
+			"type": "number",
+			"default": 3,
+			"min": 1,
+			"max": 30
+		},
+		"otpDefault": {
+			"label": "Require email code by default",
+			"description": "Pro: one-time code before signing.",
+			"type": "boolean",
+			"default": false
+		},
+		"otpContractTemplates": {
+			"label": "Require email code for contract templates",
+			"description": "Pro.",
+			"type": "boolean",
+			"default": true
+		},
+		"retentionPersonalDataMonths": {
+			"label": "Keep personal data (months)",
+			"type": "number",
+			"default": 12,
+			"min": 1,
+			"max": 120
+		},
+		"retentionSignedRecordsYears": {
+			"label": "Keep signed records (years)",
+			"type": "number",
+			"default": 7,
+			"min": 1,
+			"max": 50
+		},
+		"turnstileSiteKey": {
+			"label": "Turnstile site key",
+			"type": "string"
+		},
+		"turnstileSecretKey": {
+			"label": "Turnstile secret key",
+			"type": "secret"
+		},
+		"integrationMasterKey": {
+			"label": "Integration master key",
+			"description": "Client secrets are derived from this key; it is never shown again.",
+			"type": "secret"
+		},
+		"licenceKey": {
+			"label": "Licence key (Pro)",
+			"description": "Used by E-sign Pro only; the Free edition ignores it. Stored encrypted.",
+			"type": "secret"
+		}
+	}
+});
+
+export default descriptor;