feat: scoped evidence and explicit attestation signatures v0.1

README.md

@@ -6,21 +6,20 @@ Open specifications for Modulora component manifests, provenance, trust evidence
 
 Modulora uses the shadcn registry schema as its first install format. This repository defines companion documents that add creator ownership, source model, immutable release identity, commercial-link metadata, evidence, signatures, and revocation without breaking shadcn compatibility.
 
-Planned artifacts:
+Current artifacts:
 
 ```text
-schemas/
-  modulora-item.schema.json
-  attestation.schema.json
-  evidence.schema.json
-openapi/
-  modulora.openapi.yaml
-fixtures/
-  valid/
-  invalid/
-  malicious/
+schemas/v0/       item, taxonomy, attestation, and evidence schemas
+taxonomy/v0/      canonical categories, component types, aliases
+fixtures/         valid, invalid, and malicious conformance documents
+rfcs/              companion-manifest and scoped-evidence semantics
 ```
 
+Key semantics:
+
+- [`RFC 0001`](./rfcs/0001-companion-manifest.md) — companion manifest model.
+- [`RFC 0002`](./rfcs/0002-scoped-evidence-and-attestations.md) — limitation-aware evidence and the attestation signature boundary.
+
 ## Principles
 
 - Framework-neutral data model; React launches first.
@@ -32,7 +31,7 @@ fixtures/
 
 ## Status
 
-The specification is not yet implemented. See [`CHECKLIST.md`](./CHECKLIST.md).
+The v0 schemas, canonical taxonomy, and conformance fixtures are implemented. Public API contracts remain planned; see [`CHECKLIST.md`](./CHECKLIST.md).
 
 ## Build plan
 

fixtures/invalid/attestation-wrong-signed-payload.json

@@ -0,0 +1,33 @@
+{
+  "schemaVersion": "0",
+  "canonicalization": "modulora-json-c14n-0",
+  "itemRef": {
+    "namespace": "northstar",
+    "name": "calendar",
+    "version": "1.2.0"
+  },
+  "releaseDigest": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+  "sourceCommit": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+  "files": [
+    {
+      "path": "components/ui/calendar.tsx",
+      "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
+    },
+    {
+      "path": "lib/utils.ts",
+      "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
+    }
+  ],
+  "publisher": {
+    "identity": "github:northstar-ui/justin",
+    "authorizedAt": "2026-07-11T18:00:00Z"
+  },
+  "signature": {
+    "keyId": "modulora-platform-2026-01",
+    "algorithm": "ed25519",
+    "value": "QUJDREVG",
+    "signedAt": "2026-07-11T18:00:05Z",
+    "payload": "releaseDigest"
+  },
+  "attestationDigest": "sha256:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc"
+}

fixtures/invalid/evidence-domain-wrong-subject.json

@@ -0,0 +1,21 @@
+{
+  "schemaVersion": "0",
+  "itemRef": {
+    "namespace": "northstar",
+    "name": "calendar",
+    "version": "1.2.0"
+  },
+  "releaseDigest": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+  "records": [
+    {
+      "type": "domain-verified",
+      "status": "passed",
+      "issuer": "x",
+      "timestamp": "2026-07-11T18:00:00Z",
+      "subject": {
+        "kind": "release",
+        "value": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
+      }
+    }
+  ]
+}

fixtures/invalid/evidence-human-review-no-limitations.json

@@ -0,0 +1,22 @@
+{
+  "schemaVersion": "0",
+  "itemRef": {
+    "namespace": "northstar",
+    "name": "calendar",
+    "version": "1.2.0"
+  },
+  "releaseDigest": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+  "records": [
+    {
+      "type": "human-reviewed",
+      "status": "passed",
+      "issuer": "curator:alice",
+      "timestamp": "2026-07-11T18:00:00Z",
+      "subject": {
+        "kind": "release",
+        "value": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
+      },
+      "scope": "Listing review"
+    }
+  ]
+}

fixtures/manifest.json

@@ -101,5 +101,25 @@
     "schema": "modulora-item",
     "valid": true,
     "taxonomy": true
+  },
+  "valid/evidence-domain-verified.json": {
+    "schema": "evidence",
+    "valid": true
+  },
+  "valid/evidence-install-parity.json": {
+    "schema": "evidence",
+    "valid": true
+  },
+  "invalid/evidence-domain-wrong-subject.json": {
+    "schema": "evidence",
+    "valid": false
+  },
+  "invalid/evidence-human-review-no-limitations.json": {
+    "schema": "evidence",
+    "valid": false
+  },
+  "invalid/attestation-wrong-signed-payload.json": {
+    "schema": "attestation",
+    "valid": false
   }
 }

fixtures/valid/attestation.json

@@ -26,6 +26,8 @@
     "keyId": "modulora-platform-2026-01",
     "algorithm": "ed25519",
     "value": "QUJDREVG",
-    "signedAt": "2026-07-11T18:00:05Z"
-  }
-}
+    "signedAt": "2026-07-11T18:00:05Z",
+    "payload": "attestationDigest"
+  },
+  "attestationDigest": "sha256:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc"
+}

fixtures/valid/evidence-domain-verified.json

@@ -0,0 +1,24 @@
+{
+  "schemaVersion": "0",
+  "itemRef": {
+    "namespace": "northstar",
+    "name": "calendar",
+    "version": "1.2.0"
+  },
+  "releaseDigest": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+  "records": [
+    {
+      "type": "domain-verified",
+      "status": "passed",
+      "issuer": "modulora-platform",
+      "timestamp": "2026-07-11T18:00:00Z",
+      "subject": {
+        "kind": "domain",
+        "value": "northstar.dev"
+      },
+      "scope": "DNS TXT challenge for northstar.dev",
+      "limitations": "Proves control at verification time; does not prove source ownership or ongoing domain control.",
+      "expiresAt": "2026-10-11T18:00:00Z"
+    }
+  ]
+}

fixtures/valid/evidence-external-commercial.json

@@ -8,18 +8,27 @@
   "releaseDigest": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
   "records": [
     {
-      "type": "owner-verified",
+      "type": "publisher-identity",
       "status": "passed",
       "issuer": "modulora-platform",
       "timestamp": "2026-07-11T18:00:00Z",
-      "scope": "Domain verification for northstar.dev"
+      "scope": "Domain verification for northstar.dev",
+      "subject": {
+        "kind": "publisher",
+        "value": "Domain verification for northstar.dev"
+      }
     },
     {
       "type": "source-not-assessed",
       "status": "asserted",
       "issuer": "modulora-platform",
       "timestamp": "2026-07-11T18:00:00Z",
-      "scope": "Commercial source is not available to Modulora and has not been scanned or reviewed."
+      "scope": "Commercial source is not available to Modulora and has not been scanned or reviewed.",
+      "subject": {
+        "kind": "source",
+        "value": "@northstar/pro-table@1.2.0"
+      },
+      "limitations": "No source artifact was available to inspect, scan, build, or compare."
     }
   ]
-}
+}

fixtures/valid/evidence-install-parity.json

@@ -0,0 +1,29 @@
+{
+  "schemaVersion": "0",
+  "itemRef": {
+    "namespace": "northstar",
+    "name": "calendar",
+    "version": "1.2.0"
+  },
+  "releaseDigest": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+  "records": [
+    {
+      "type": "install-parity",
+      "status": "passed",
+      "issuer": "modulora-platform",
+      "timestamp": "2026-07-11T18:00:00Z",
+      "subject": {
+        "kind": "install-command",
+        "value": "npx shadcn@latest add https://northstar.dev/r/calendar.json"
+      },
+      "coverage": {
+        "command": "npx shadcn@latest add https://northstar.dev/r/calendar.json",
+        "paths": [
+          "components/ui/calendar.tsx"
+        ]
+      },
+      "scope": "Fetched registry output compared file-for-file with this release.",
+      "limitations": "Comparison covers fetched files only; it does not prove runtime safety."
+    }
+  ]
+}

fixtures/valid/evidence-open-source.json

@@ -8,25 +8,47 @@
   "releaseDigest": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
   "records": [
     {
-      "type": "owner-verified",
+      "type": "publisher-identity",
       "status": "passed",
       "issuer": "modulora-platform",
       "timestamp": "2026-07-11T18:00:00Z",
-      "scope": "GitHub App installation for northstar-ui/components"
+      "scope": "GitHub App installation for northstar-ui/components",
+      "subject": {
+        "kind": "publisher",
+        "value": "GitHub App installation for northstar-ui/components"
+      }
     },
     {
-      "type": "artifact-signed",
+      "type": "content-integrity",
       "status": "passed",
       "issuer": "modulora-platform",
-      "timestamp": "2026-07-11T18:00:05Z"
+      "timestamp": "2026-07-11T18:00:05Z",
+      "subject": {
+        "kind": "release",
+        "value": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
+      },
+      "coverage": {
+        "paths": [
+          "src/components/ui/calendar.tsx"
+        ]
+      }
     },
     {
       "type": "secret-scan",
       "status": "passed",
       "issuer": "modulora-platform",
       "timestamp": "2026-07-11T18:00:10Z",
       "toolVersion": "gitleaks-8.24.0",
-      "limitations": "Pattern-based scan of release files only; cannot prove absence of unknown or obfuscated secrets."
+      "limitations": "Pattern-based scan of release files only; cannot prove absence of unknown or obfuscated secrets.",
+      "subject": {
+        "kind": "release",
+        "value": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
+      },
+      "coverage": {
+        "paths": [
+          "src/components/ui/calendar.tsx"
+        ]
+      }
     }
   ]
-}
+}

rfcs/0002-scoped-evidence-and-attestations.md

@@ -0,0 +1,55 @@
+# RFC 0002: Scoped Evidence and Release Attestations v0.1
+
+**Status:** Accepted for v0
+
+## Principle
+
+Modulora MUST NOT emit or display a generic `verified` or `secure` claim. A trust statement MUST identify:
+
+1. the exact release (`itemRef` + `releaseDigest`),
+2. what was checked (`type`),
+3. the subject and coverage of that check,
+4. who issued it and when, and
+5. what the result does **not** prove (`limitations`) where omission could mislead.
+
+Evidence informs a user; it does not endorse a component.
+
+## Canonical registry-facing evidence
+
+The canonical terms used by registry surfaces are:
+
+- `publisher-identity` — the authenticated publisher identity was bound to the release.
+- `domain-verified` — control of one exact domain was demonstrated. It does not prove source ownership or permanent control.
+- `content-integrity` — the named release/files are bound to the release digest. It does not prove safety.
+- `install-parity` — output fetched through one exact install command matched the covered release files. It does not prove runtime safety or future parity.
+- `secret-scan` — covered paths were scanned by a named tool/version. It cannot prove absence of unknown or obfuscated secrets.
+
+Other schema values support source linking, dependency/license/static scans, builds, human review, unassessed source, deprecation, and revocation. `owner-verified` remains readable for early v0 records; new issuers SHOULD use `publisher-identity`.
+
+## Subject and coverage
+
+`subject` is the exact thing the evidence concerns: a release, publisher, domain, install command, or source. `coverage` is the machine-readable boundary (paths, command, domain, or commit).
+
+A consumer MUST NOT widen evidence beyond those bounds. In particular:
+
+- domain evidence requires a `domain` subject;
+- install parity requires an `install-command` subject and the exact command in coverage;
+- expired evidence MUST be displayed as stale, not passed.
+
+The legacy human-readable `scope` remains valid for v0 compatibility. Issuers SHOULD emit structured `subject`/`coverage` and MAY include `scope` as explanatory copy.
+
+## Limitations
+
+Limitations are REQUIRED for scans, build checks, human review, and `source-not-assessed`. A human review is a listing decision unless its scope explicitly says otherwise; it MUST NOT be presented as a security audit.
+
+## Attestation signature boundary
+
+`releaseDigest` identifies canonical manifest data and sorted file digests. It does not, by itself, bind publisher authorization or other attestation fields.
+
+Therefore an attestation includes `attestationDigest`, computed over the canonical attestation statement excluding `signature` and `transparencyLog`. `signature.payload` MUST equal `attestationDigest`, and `signature.value` signs that digest. Consumers MUST reject a signature that declares any other payload.
+
+A transparency-log reference is optional and does not replace signature validation.
+
+## Digest independence
+
+Evidence, taxonomy, moderation categorization, and display copy are outside the source-content digest. Updating evidence MUST NOT mutate an immutable release or change install parity.