signed-md 1.1.0 → 1.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +105 -0
  2. package/dist/cli.js +31 -2
  3. package/package.json +4 -3
package/README.md ADDED
@@ -0,0 +1,105 @@
1
+ <p align="center">
2
+ <a href="https://github.com/varops/signed-md"><img src="https://raw.githubusercontent.com/varops/signed-md/main/brand/signedmd-light.svg" alt="Signed.md" height="56"></a>
3
+ </p>
4
+
5
+ <h3 align="center">Check a signed agreement yourself</h3>
6
+
7
+ <p align="center">
8
+ The offline verifier for <a href="https://github.com/varops/signed-md">Signed.md</a> evidence packages.<br>No account, no server, no internet connection.
9
+ </p>
10
+
11
+ <p align="center">
12
+ <a href="https://www.npmjs.com/package/signed-md"><img src="https://img.shields.io/npm/v/signed-md?color=1c1917&label=npm" alt="npm version"></a>
13
+ <a href="https://github.com/varops/signed-md/blob/main/LICENSE"><img src="https://img.shields.io/badge/licence-AGPL--3.0-1c1917" alt="Licence: AGPL-3.0"></a>
14
+ <img src="https://img.shields.io/badge/dependencies-0-f6da1c" alt="No dependencies">
15
+ <img src="https://img.shields.io/badge/works-offline-1c1917" alt="Works offline">
16
+ </p>
17
+
18
+ ---
19
+
20
+ When everyone has signed, [Signed.md](https://github.com/varops/signed-md) gives each party an evidence package: a ZIP with the signed Markdown, the sealed PDF, a hash-chained evidence log and a signed manifest.
21
+
22
+ You shouldn't have to trust the company that sent it. Run one command and see for yourself that nothing was changed after signing:
23
+
24
+ ```bash
25
+ npx signed-md verify agreement.zip
26
+ ```
27
+
28
+ ```text
29
+ Mutual NDA (doc_3ytrryxfn5b4qjhkxw18)
30
+ Revision rev_b74005c16ce436bf916218d24c7e4b0a · key smdk_b8ab402827010b3c
31
+
32
+ ✓ manifest signature valid
33
+ ✓ file agreement.md
34
+ ✓ PDF signature valid – CN=Acme (Signed.md), O=Acme
35
+ ✓ PDF not changed after signing
36
+ ✓ PDF signature timestamp – 2026-11-20T12:06:14.000Z by C=US, O=DigiCert\, Inc., …
37
+ ✓ evidence chain – 16 events
38
+ ✓ agreement.md matches the sent document
39
+ ✓ signer a signed – Jane Doe <jane@example.com>
40
+
41
+ VALID: the package is intact. Pass --keys to also check who signed it.
42
+ ```
43
+
44
+ The output above is shortened. A real run lists every file and check.
45
+
46
+ ## Also check who sent it
47
+
48
+ A package carries its own public key. That proves nothing inside it was changed, but anyone could make a package with their own key. To check it came from the sender's installation, compare it with the sender's published keys:
49
+
50
+ 1. Download the keys once from the sender's server, and keep the file:
51
+
52
+ ```bash
53
+ curl -o signed-md-keys.json https://sign.example.com/.well-known/signed-md-keys.json
54
+ ```
55
+
56
+ 2. Verify against them:
57
+
58
+ ```bash
59
+ npx signed-md verify agreement.zip --keys signed-md-keys.json
60
+ ```
61
+
62
+ ```text
63
+ VALID: the package is intact and signed by a key you trust.
64
+ ```
65
+
66
+ Keep the keys file you downloaded first. If a later package only matches keys fetched later, ask the sender why their key changed.
67
+
68
+ ## What it checks
69
+
70
+ | Check | What it proves |
71
+ |---|---|
72
+ | Manifest and its signature | Every file in the ZIP is the one the server sealed. Nothing was added, removed or edited. |
73
+ | PDF seal (PAdES) | The PDF wasn't changed after signing. PDF readers like Adobe Acrobat check the same seal. |
74
+ | Timestamps (RFC 3161) | A trusted time authority saw the sealed PDF at that time, when the package has a timestamp. |
75
+ | Evidence chain | Each event (sent, viewed, consented, signed) links to the one before it by hash. None was removed or reordered. |
76
+ | Agreement text | Every signer signed the exact text in `agreement.md`, word for word. |
77
+ | Keys (with `--keys`) | The package was sealed by the installation whose keys you trust. |
78
+
79
+ ## Options
80
+
81
+ ```text
82
+ signed-md verify <agreement.zip> [--keys <keys.json>] [--json]
83
+ ```
84
+
85
+ | Option | Description |
86
+ |---|---|
87
+ | `--keys <file>` | A keys file you trust, from the sender's `/.well-known/signed-md-keys.json`. |
88
+ | `--json` | Print the full report as JSON, for scripts and CI. |
89
+ | `--help` | Show the usage. |
90
+
91
+ | Exit code | Meaning |
92
+ |---|---|
93
+ | `0` | Valid |
94
+ | `1` | Invalid: the package was changed, is incomplete, or isn't a Signed.md package |
95
+ | `2` | Wrong usage, or a file couldn't be read |
96
+
97
+ You need Node.js 20 or later. The command is one bundled file with no dependencies. It reads only the files you give it and never connects to the internet.
98
+
99
+ ## About Signed.md
100
+
101
+ [Signed.md](https://github.com/varops/signed-md) is open-source document signing you host yourself. AI agents draft agreements from approved Markdown templates, over MCP or a REST API. People review, approve and send them, and signers sign in the browser. Every completed agreement becomes a sealed, timestamped PDF/A plus the evidence package this tool checks.
102
+
103
+ ## Licence
104
+
105
+ AGPL-3.0-only. This tool checks that a package is intact. It doesn't tell you whether an agreement is legally binding where you are, and it isn't legal advice. See [how Signed.md fits ESIGN, UETA, eIDAS and UK law](https://github.com/varops/signed-md/blob/main/docs/legal.md).
package/dist/cli.js CHANGED
@@ -863,8 +863,32 @@ function run(argv) {
863
863
  return 2;
864
864
  }
865
865
  const keysIdx = rest.indexOf("--keys");
866
- const trustedKeys = keysIdx >= 0 ? trustedKeysFrom(readFileSync(rest[keysIdx + 1], "utf8")) : void 0;
867
- const report = verifyPackage(new Uint8Array(readFileSync(file)), trustedKeys ? { trustedKeys } : {});
866
+ const keysFile = keysIdx >= 0 ? rest[keysIdx + 1] : void 0;
867
+ if (keysIdx >= 0 && (!keysFile || keysFile.startsWith("--"))) {
868
+ console.error("--keys needs a keys file.\n\n" + HELP);
869
+ return 2;
870
+ }
871
+ let trustedKeys;
872
+ let bytes;
873
+ try {
874
+ trustedKeys = keysFile ? trustedKeysFrom(readFileSync(keysFile, "utf8")) : void 0;
875
+ } catch (e) {
876
+ console.error(`Could not read the keys file ${keysFile}: ${reason(e)}`);
877
+ return 2;
878
+ }
879
+ try {
880
+ bytes = new Uint8Array(readFileSync(file));
881
+ } catch (e) {
882
+ console.error(`Could not read ${file}: ${reason(e)}`);
883
+ return 2;
884
+ }
885
+ let report;
886
+ try {
887
+ report = verifyPackage(bytes, trustedKeys ? { trustedKeys } : {});
888
+ } catch (e) {
889
+ console.error(`INVALID: ${file} is not a Signed.md package (${reason(e)}).`);
890
+ return 1;
891
+ }
868
892
  if (rest.includes("--json")) {
869
893
  console.log(JSON.stringify(report, null, 2));
870
894
  return report.ok ? 0 : 1;
@@ -882,6 +906,11 @@ function run(argv) {
882
906
  }
883
907
  return report.ok ? 0 : 1;
884
908
  }
909
+ function reason(e) {
910
+ if (e && typeof e === "object" && "code" in e && e.code === "ENOENT") return "no such file";
911
+ if (e && typeof e === "object" && "code" in e && e.code === "EISDIR") return "it is a folder";
912
+ return e instanceof Error ? e.message : String(e);
913
+ }
885
914
  export {
886
915
  run
887
916
  };
package/package.json CHANGED
@@ -1,18 +1,19 @@
1
1
  {
2
2
  "name": "signed-md",
3
- "version": "1.1.0",
3
+ "version": "1.1.1",
4
4
  "description": "Verify Signed.md completion packages offline.",
5
5
  "type": "module",
6
6
  "bin": {
7
- "signed-md": "./bin/signed-md.js"
7
+ "signed-md": "bin/signed-md.js"
8
8
  },
9
9
  "license": "AGPL-3.0-only",
10
+ "homepage": "https://github.com/varops/signed-md/tree/main/packages/verify#readme",
10
11
  "files": [
11
12
  "bin",
12
13
  "dist"
13
14
  ],
14
15
  "repository": {
15
16
  "type": "git",
16
- "url": "https://github.com/varops/signed-md.git"
17
+ "url": "git+https://github.com/varops/signed-md.git"
17
18
  }
18
19
  }