midnight-shield 0.0.0-stage → 0.4.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 (53) hide show
  1. package/CHANGELOG.md +68 -0
  2. package/LICENSE +21 -0
  3. package/README.md +382 -2
  4. package/action.yml +56 -0
  5. package/dist/src/analyzer.d.ts +97 -0
  6. package/dist/src/analyzer.js +895 -0
  7. package/dist/src/ast.d.ts +211 -0
  8. package/dist/src/ast.js +2 -0
  9. package/dist/src/browser.d.ts +3 -0
  10. package/dist/src/browser.js +5 -0
  11. package/dist/src/cli.d.ts +2 -0
  12. package/dist/src/cli.js +336 -0
  13. package/dist/src/config.d.ts +26 -0
  14. package/dist/src/config.js +87 -0
  15. package/dist/src/fixes.d.ts +10 -0
  16. package/dist/src/fixes.js +45 -0
  17. package/dist/src/index.d.ts +10 -0
  18. package/dist/src/index.js +10 -0
  19. package/dist/src/lexer.d.ts +18 -0
  20. package/dist/src/lexer.js +135 -0
  21. package/dist/src/linter.d.ts +67 -0
  22. package/dist/src/linter.js +137 -0
  23. package/dist/src/node.d.ts +13 -0
  24. package/dist/src/node.js +98 -0
  25. package/dist/src/parser.d.ts +2 -0
  26. package/dist/src/parser.js +791 -0
  27. package/dist/src/plugin-loader.d.ts +3 -0
  28. package/dist/src/plugin-loader.js +31 -0
  29. package/dist/src/plugins.d.ts +34 -0
  30. package/dist/src/plugins.js +59 -0
  31. package/dist/src/reporters.d.ts +22 -0
  32. package/dist/src/reporters.js +286 -0
  33. package/dist/src/rules.d.ts +23 -0
  34. package/dist/src/rules.js +104 -0
  35. package/dist/src/sdk.d.ts +6 -0
  36. package/dist/src/sdk.js +130 -0
  37. package/dist/src/walk.d.ts +28 -0
  38. package/dist/src/walk.js +110 -0
  39. package/docs/rules/MS000.md +7 -0
  40. package/docs/rules/MS001.md +46 -0
  41. package/docs/rules/MS002.md +42 -0
  42. package/docs/rules/MS003.md +41 -0
  43. package/docs/rules/MS004.md +41 -0
  44. package/docs/rules/MS005.md +32 -0
  45. package/docs/rules/MS006.md +17 -0
  46. package/docs/rules/MS007.md +44 -0
  47. package/docs/rules/MS008.md +59 -0
  48. package/docs/rules/MS009.md +45 -0
  49. package/docs/rules/MS010.md +46 -0
  50. package/docs/rules/MS101.md +32 -0
  51. package/docs/rules/MS102.md +31 -0
  52. package/package.json +67 -4
  53. package/skills/midnight-shield/SKILL.md +67 -0
@@ -0,0 +1,46 @@
1
+ # MS010 linkable-ledger-update
2
+
3
+ **Severity:** medium · **Confidence:** medium
4
+
5
+ ## What it finds
6
+
7
+ In a contract where members act anonymously (an exported circuit authorizes with a Merkle membership proof), the same identifier, derived only from a member's secret, is published by two or more circuits.
8
+
9
+ ## Why it matters
10
+
11
+ Anonymous membership hides *which* member acted. But if every circuit publishes the same tag for a member (for example `hash("tag", secretKey)`), anyone can group all actions with the same tag and link them to one person, even without knowing who that person is. Over time that is often enough to identify them.
12
+
13
+ ## Example
14
+
15
+ ```compact
16
+ circuit memberTag(sk: Bytes<32>): Bytes<32> {
17
+ return persistentHash<Vector<2, Bytes<32>>>([pad(32, "app:tag:"), sk]);
18
+ }
19
+
20
+ export circuit post(): [] {
21
+ // ... Merkle membership proof ...
22
+ posts.insert(disclose(memberTag(secretKey()))); // MS010
23
+ }
24
+
25
+ export circuit react(): [] {
26
+ // ... Merkle membership proof ...
27
+ reactions.insert(disclose(memberTag(secretKey()))); // same tag again
28
+ }
29
+ ```
30
+
31
+ ## Fix
32
+
33
+ Give each action its own domain, so the values cannot be matched across circuits:
34
+
35
+ ```compact
36
+ posts.insert(disclose(persistentHash<Vector<2, Bytes<32>>>([pad(32, "app:post:"), sk])));
37
+ reactions.insert(disclose(persistentHash<Vector<2, Bytes<32>>>([pad(32, "app:react:"), sk])));
38
+ ```
39
+
40
+ If even two posts by the same member should be unlinkable, also mix in something that changes per action (a round number or a post ID).
41
+
42
+ ## Not flagged
43
+
44
+ - Account-style contracts (tokens, access control) without anonymous membership: a stable account identifier is linkable by design, like an address.
45
+ - Identifiers that include fresh randomness or a value that differs per circuit.
46
+ - Identifiers published by a single circuit.
@@ -0,0 +1,32 @@
1
+ # MS101 remote-proof-server
2
+
3
+ **Severity:** critical · **Confidence:** medium · **Applies to:** TypeScript / JavaScript
4
+
5
+ ## What it finds
6
+
7
+ A proof server URL (a string next to `proofServer`, `httpClientProofProvider(...)`, or any URL on port 6300) that points to a host other than `localhost`, `127.0.0.1`, `::1`, `host.docker.internal` or a Docker service named `proof-server`.
8
+
9
+ ## Why it matters
10
+
11
+ To build a proof, the proof server receives the user's private inputs (witness values) in plain form. A proof server on someone else's machine sees every private value of every user who uses it. Midnight's documentation tells you to use only a proof server you control.
12
+
13
+ ## Example
14
+
15
+ ```ts
16
+ const proofProvider = httpClientProofProvider("https://proofs.example.com:6300"); // MS101
17
+ ```
18
+
19
+ ## Fix
20
+
21
+ Run the proof server on the user's machine, and make the URL configurable:
22
+
23
+ ```ts
24
+ const proofProvider = httpClientProofProvider(process.env.MIDNIGHT_PROOF_SERVER ?? "http://localhost:6300");
25
+ ```
26
+
27
+ ## Not flagged
28
+
29
+ - Other remote URLs (indexer, node, faucet): they only see public data.
30
+ - Test files (`*.test.ts`, `*.spec.ts`, and files under `test/`, `tests/`, `__tests__/`), which often use fake remote servers on purpose.
31
+
32
+ Turn off all TypeScript checks with `--no-sdk` or `"sdk": false` in the config file.
@@ -0,0 +1,31 @@
1
+ # MS102 secret-in-log
2
+
3
+ **Severity:** high · **Confidence:** medium · **Applies to:** TypeScript / JavaScript
4
+
5
+ ## What it finds
6
+
7
+ A value whose name says it is a secret (`seed`, `secretKey`, `mnemonic`, `password`, `privateKey`, `sk`) passed directly to `console.*`, `logger.*` or `log.*`, including inside a template string (`` `${seed}` ``).
8
+
9
+ ## Why it matters
10
+
11
+ Logs are copied to CI output, crash reporters, log services and browser consoles, and they are kept for a long time. A wallet seed in a log gives anyone who reads the log full control of the wallet.
12
+
13
+ ## Example
14
+
15
+ ```ts
16
+ console.log(`restoring wallet from ${seed}`); // MS102
17
+ ```
18
+
19
+ ## Fix
20
+
21
+ Log something that cannot be turned back into the secret:
22
+
23
+ ```ts
24
+ console.log(`restoring wallet for ${publicKeyOf(seed)}`);
25
+ ```
26
+
27
+ ## Not flagged
28
+
29
+ - A secret passed through another call first (`publicKeyOf(seed)`), which is treated as a derived value.
30
+ - Metadata of a secret: `seed.length`, `secret.kind`, `secret.type`.
31
+ - Test files.
package/package.json CHANGED
@@ -1,6 +1,69 @@
1
1
  {
2
2
  "name": "midnight-shield",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.4.1",
4
+ "description": "Static analyzer for Midnight Compact contracts and their TypeScript code. Finds security and privacy issues before deploy.",
5
+ "keywords": [
6
+ "midnight",
7
+ "compact",
8
+ "zero-knowledge",
9
+ "zk",
10
+ "privacy",
11
+ "security",
12
+ "static-analysis",
13
+ "linter",
14
+ "smart-contracts",
15
+ "sarif"
16
+ ],
17
+ "homepage": "https://github.com/efforthye/midnight-shield#readme",
18
+ "bugs": {
19
+ "url": "https://github.com/efforthye/midnight-shield/issues"
20
+ },
21
+ "repository": {
22
+ "type": "git",
23
+ "url": "git+https://github.com/efforthye/midnight-shield.git"
24
+ },
25
+ "license": "MIT",
26
+ "author": "efforthye",
27
+ "type": "module",
28
+ "bin": {
29
+ "midnight-shield": "dist/src/cli.js"
30
+ },
31
+ "main": "dist/src/index.js",
32
+ "types": "dist/src/index.d.ts",
33
+ "exports": {
34
+ ".": {
35
+ "types": "./dist/src/index.d.ts",
36
+ "import": "./dist/src/index.js"
37
+ },
38
+ "./package.json": "./package.json"
39
+ },
40
+ "files": [
41
+ "dist/src",
42
+ "docs/rules",
43
+ "skills",
44
+ "action.yml",
45
+ "CHANGELOG.md"
46
+ ],
47
+ "engines": {
48
+ "node": ">=20"
49
+ },
50
+ "scripts": {
51
+ "build": "tsc -p tsconfig.json",
52
+ "prepare": "tsc -p tsconfig.json",
53
+ "test": "npm run build && node scripts/run-tests.mjs",
54
+ "coverage": "npm run build && node scripts/run-tests.mjs --experimental-test-coverage",
55
+ "verify": "npm run build && node scripts/verify-corpus.mjs",
56
+ "demo": "node dist/src/cli.js examples/",
57
+ "playground": "node scripts/build-playground.mjs",
58
+ "prepublishOnly": "npm test"
59
+ },
60
+ "publishConfig": {
61
+ "access": "public",
62
+ "provenance": true
63
+ },
64
+ "devDependencies": {
65
+ "@types/node": "^22.0.0",
66
+ "esbuild": "^0.24.2",
67
+ "typescript": "^5.9.0"
68
+ }
69
+ }
@@ -0,0 +1,67 @@
1
+ ---
2
+ name: midnight-shield
3
+ description: Scan Midnight Compact contracts for security and privacy bugs with Midnight Shield, then fix the findings and re-scan until clean. Use when writing, reviewing, or changing .compact files, or when the user asks to audit or check a Midnight contract.
4
+ ---
5
+
6
+ # Midnight Shield: scan, fix, re-scan
7
+
8
+ Midnight Shield is a static analyzer for Compact. It finds bugs that compile but are unsafe: fake authorization with `ownPublicKey()`, unchecked witnesses, brute-forceable hashes, weak commitments, and hashes without domain tags.
9
+
10
+ ## When to run it
11
+
12
+ - After you write or edit any `.compact` file.
13
+ - Before you tell the user a contract is done or safe.
14
+ - When the user asks for a security or privacy review of Midnight code.
15
+
16
+ ## Step 1: Scan
17
+
18
+ Run from the project root and read the JSON report:
19
+
20
+ ```bash
21
+ npx github:efforthye/midnight-shield <contracts-dir> --format json --fail-on none
22
+ ```
23
+
24
+ Each finding has `ruleId`, `severity`, `confidence`, `message`, `file`, `line`, `col`, `snippet`, and `docUrl`. Treat `low` confidence findings as questions to check, not certain bugs.
25
+
26
+ To see everything the contract makes public, run `--print disclosures`. Any `RAW` row is private data published as is: check that it is meant to be public.
27
+
28
+ ## Step 2: Fix, most severe first
29
+
30
+ Work through findings in order: critical, high, medium, low, info. For each one, open the rule page at `docUrl` if the fix is not obvious.
31
+
32
+ | Rule | Fix |
33
+ | --- | --- |
34
+ | MS001 `own-public-key-auth` | Never authorize with `ownPublicKey()`. Store `persistentHash([pad(32, "<app>:owner:"), sk])` on the ledger and recompute it from a secret-key witness. |
35
+ | MS002 `unconstrained-witness` | Add an `assert` that bounds or checks the witness value (range, set or Merkle membership, relation to ledger state) before it is disclosed or stored. |
36
+ | MS003 `low-entropy-hash` | Replace the hash with `persistentCommit(value, randomness)` using fresh `Bytes<32>` randomness from a witness, or mix a 32-byte secret into the hash. |
37
+ | MS004 `weak-commitment-randomness` | Use fresh 32-byte randomness from a witness for every commitment. Never use constants, ledger values, or the same salt twice. |
38
+ | MS005 `missing-domain-separation` | Add a constant tag as the first hash input, e.g. `pad(32, "<app>:<purpose>:")`, unique per purpose. |
39
+ | MS007 `disclosed-secret` | Never disclose a secret key, seed, or password. Publish `persistentHash([pad(32, "<app>:id:"), sk])` instead. |
40
+ | MS008 `missing-nullifier` | Derive a nullifier `persistentHash([pad(32, "<app>:<action>:"), sk])`, `assert(!used.member(n))`, then `used.insert(n)`. |
41
+ | MS009 `unbound-merkle-path` | Add `assert(disclose(path.leaf == deriveLeaf(secretKey())), "...")` next to the `checkRoot` call. |
42
+ | MS010 `linkable-ledger-update` | Give each circuit's published identifier its own domain tag (and a per-action value if needed). |
43
+ | MS101 `remote-proof-server` | Point the proof server at `http://localhost:6300` (or an env variable that defaults to it). |
44
+ | MS102 `secret-in-log` | Remove the secret from the log call, or log a derived public value. |
45
+ | MS006 `missing-pragma` | Run `--fix`, or add `pragma language_version >= 0.28.0;` at the top. |
46
+ | MS000 `parse-error` | Not a bug in the contract. Tell the user the analyzer skipped that part. |
47
+
48
+ Keep each fix minimal and keep the circuit's behavior the same. If a fix changes the contract's interface (new witness, new ledger field), say so to the user, because the TypeScript side must be updated too.
49
+
50
+ ## Step 3: Re-scan
51
+
52
+ Run the scan again. Repeat until there are no critical, high, or medium findings, then report what changed.
53
+
54
+ ## Suppressing a finding
55
+
56
+ Only suppress when the code is intentionally that way, and say why in the same comment:
57
+
58
+ ```compact
59
+ // shield-disable-next-line MS005 -- tag is supplied by every caller
60
+ return persistentHash<Vector<2, Bytes<32>>>([tag, sk]);
61
+ ```
62
+
63
+ Never suppress MS001, MS003, MS007 or MS009 to make a scan pass. Report them to the user instead if you cannot fix them.
64
+
65
+ ## Report to the user
66
+
67
+ Summarize: how many findings before and after, what you fixed (rule, file, line), and anything left with the reason.