@hasna/skills 0.10.51 → 0.10.52

package/docs/plugin-admission.md

@@ -173,6 +173,74 @@ new loaders still require their dedicated review. API failure refuses an update;
 stale projection as synchronized. Claude may retain its previous installation
 after a refused update, whose existing local drift checks continue to apply.
 
+## Reviewed plugin-hook attestation scope
+
+A reviewed discovery input carries `pluginHooks: "reviewed-no-skill-injection"`.
+That value is the reviewer's statement; Skills does not inspect hook behavior.
+What the software currently enforces is narrower:
+
+- It is point-in-time. It binds the listed sources as they were when the review
+  was applied, apart from the manifest projection described here and the
+  retired-root exemption described below. A manifest listed as a plain byte
+  witness with a non-null `sha256` is stored as a `claude-plugin-manifest-v1`
+  projection that ignores the descriptive fields `description`, `version`,
+  `author`, `homepage`, `repository`, `license` and `keywords`. The projection
+  also normalises whitespace and JSON string escaping; key order stays bound.
+  Every other manifest field, including `hooks`, `skills`, `commands` and
+  unknown fields, stays bound.
+- It enforces one coupling only, and only for a Claude
+  `.claude-plugin/plugin.json` listed as a plain byte witness (`hashMode`
+  omitted or `"bytes"`) with a non-null `sha256`. The review must then also list
+  that plugin's `hooks/hooks.json` (when the file exists at review time) and any
+  string `hooks` target in the manifest, each as a plain byte witness with a
+  non-null hash. A non-string `hooks` value and a `hooks` target outside the
+  plugin root are refused. A manifest listed as `claude-plugin-manifest-v1`
+  (the form Skills writes into the stored policy) or as `path-bytes` triggers
+  no hook-file requirement. Nothing else is required.
+- A `hooks/hooks.json` that is absent at review time and appears later is
+  detected if the review pins it with `sha256: null` or covers it with a
+  reviewed `directories` membership witness on the plugin root or its `hooks/`
+  directory. Such a witness, from `captureDiscoveryDirectories(paths)`, binds
+  the recursive path and type of every member, so every check detects added or
+  removed files and directories under it, but not content changes.
+- For plugins not covered by a `claude-plugin-registry` admission witness (see
+  [Discovery transition contract](#discovery-transition-contract)):
+  - other plugin files, such as hook modules (`register.ts`, `runtime.ts` and
+    their imports), `bin/` files and `package.json`, are bound only if the
+    review lists them. A content change to an unlisted file is not detected,
+    and an added or removed file is detected only under a reviewed
+    `directories` witness that covers it;
+  - the review is not anchored to the roots registered in
+    `~/.claude/plugins/installed_plugins.json`. When a review is present, the
+    enabled-plugin walk does not run, so Skills does not check that the listed
+    plugin roots are the registered ones or that every enabled plugin is listed.
+- A `claude-plugin-registry` witness covers its admitted, receipt-backed
+  plugins on every check. It re-reads `installed_plugins.json`, requires each
+  managed row's `installPath` to be `cache/<marketplace>/<plugin>/<version>`,
+  checks every file in every retained cache version against the admission
+  receipts without the review listing them, and binds unmanaged rows exactly.
+- An entirely absent retired Claude version root exempts only its plain byte
+  sources (`hashMode` omitted or `"bytes"`, with no `format`, `fields` or
+  `managedPlugins`). Such a source with a non-null `sha256` is also the only
+  thing that identifies the root, and the root qualifies only while it stays
+  entirely absent and the reviewed settings and registry select a different,
+  verified version. Every other source under that root is re-hashed as usual,
+  and one whose file existed at review no longer matches its hash, so the
+  check refuses. That includes the plugin manifest in the
+  `claude-plugin-manifest-v1` form Skills stores, so a stored review that lists
+  the retired version's manifest refuses until a fresh review replaces it. A
+  `directories` witness that covers the retired root is not exempt either. If
+  the root reappears, its sources are checked again.
+- It is detection-only. Later checks re-hash the stored sources and re-walk any
+  reviewed `directories` witnesses. Drift makes the
+  Skills hooks refuse with `NATIVE_SKILL_DRIFT`; it does not stop, unload or
+  sandbox plugin code, which the native client keeps running.
+- It is a tripwire, not a security boundary. A process running as the same user
+  can rewrite the plugin files and the managed policy that holds the witnesses.
+
+For plugins outside receipt-backed admission, a stronger witness anchored to the
+registered plugin roots is planned and not yet implemented.
+
 ## Marketplace registry timestamps
 
 For an explicitly reviewed `known_marketplaces.json`,
@@ -196,6 +264,123 @@ not proof of a timestamp-only change: review the complete current registration
 and its complementary sources before explicitly replacing an old witness.
 Capturing this witness does not write a policy or approve native registration.
 
+## Marketplace plugin entry witness
+
+`claude-marketplace-entry-v1` witnesses one plugin entry of a Claude
+`marketplace.json`, for a plugin whose only declaration is its marketplace entry
+(for example a `strict: false` entry with no `plugin.json`, such as
+`swift-lsp@claude-plugins-official`). A bytes witness of the whole catalog
+drifts every time Claude refreshes the marketplace by itself; this mode moves
+only when something that decides how the selected entry resolves or what it
+injects changes.
+
+The source names an absolute, normalized `<root>/.claude-plugin/marketplace.json`
+path, the exact marketplace `name` and the exact plugin entry `name`:
+
+```json
+{ "path": "/home/user/.claude/plugins/marketplaces/claude-plugins-official/.claude-plugin/marketplace.json",
+  "hashMode": "claude-marketplace-entry-v1", "marketplace": "claude-plugins-official",
+  "plugin": "swift-lsp", "sha256": "<digest>" }
+```
+
+It is accepted only in explicit reviewed Claude discovery. Paths with `..`,
+`//`, a trailing slash, control characters, another file name or another parent
+directory refuse, as do names outside `[A-Za-z0-9][A-Za-z0-9._-]{0,127}`.
+
+The digest is SHA-256 over the domain prefix
+`hasna.skills.claude-marketplace-entry.v1\0` and canonical JSON (sorted object
+keys, array order and number spelling kept, no whitespace) of:
+
+- the marketplace `name`, `metadata.pluginRoot` (`null` when absent) and
+  `allowCrossMarketplaceDependenciesOn` (`null` when absent), for every entry
+  whether or not it declares `dependencies`: the root allowlist also governs
+  dependencies declared in the plugin's own `plugin.json`, which Claude's
+  auto-update and `/reload-plugins` act on. A present allowlist must be an
+  array of strings, so `null` only ever means absent;
+- the selected entry projected to its bound keys: `name`, `source`, `strict`,
+  `defaultEnabled`, `dependencies`, `relevance`, `headers`, `headersHelper`,
+  `settings`, `userConfig`, `types`, `channels`, `skills`, `commands`, `agents`,
+  `hooks`, `mcpServers`, `lspServers`, `outputStyles`, `workflows`,
+  `experimental`, `themes` and `monitors`, each with its full value.
+
+Key order: this canonical JSON sorts object keys at every level, under the
+domain prefix above. That deliberately differs from `claude-plugin-manifest-v1`,
+which keeps the manifest's own key order and has no domain prefix. Reordering
+keys in the catalog therefore never moves this digest, while array order,
+including the order of `allowCrossMarketplaceDependenciesOn`, stays bound.
+
+The entry's display and catalog metadata is validated and omitted:
+`$schema`, `description`, `version`, `author`, `homepage`, `repository`,
+`license`, `keywords`, `category`, `tags`, `displayName` and `metadata`. A real
+version or install-path change is still caught by the separate
+`installed_plugins.json` witness, which this mode never replaces. Other entries,
+the catalog `description`, `version`, `owner` and `$schema`,
+`forceRemoveDeletedPlugins` and renames of other plugins do not move the digest.
+Adding, removing or changing `allowCrossMarketplaceDependenciesOn` always does.
+
+The mode fails closed. Capture and verification refuse when:
+
+- the file is missing, a link, a special file, larger than 1 MiB, not strict
+  UTF-8, not one JSON object, has trailing content or a duplicate key;
+- the marketplace `name` differs from the bound name, or `plugins` is not an
+  array;
+- the selected entry is missing, appears twice, or has a case-only variant;
+- `renames` maps the selected name to another entry or to `null`;
+- the entry has a key outside the two lists above (including the directory
+  listing fields), `experimental` has a key other than `themes`, `monitors` or
+  `evals`, or an object `source` has an unknown type or a field outside that
+  type's documented fields (a `url` source may also carry `path`, as the
+  official catalog does);
+- the catalog has a top-level key outside `$schema`, `name`, `owner`,
+  `plugins`, `description`, `version`, `metadata`, `forceRemoveDeletedPlugins`,
+  `allowCrossMarketplaceDependenciesOn` and `renames`, or a `metadata` key other
+  than `description`, `version` and `pluginRoot`;
+- an omitted metadata field has the wrong type.
+
+New fields are refused, never ignored, until a reviewed version of this mode
+covers them. A refusal for an unknown key names the mode, the bound marketplace
+name and the exact key path, and never echoes a value. Key names are bounded to
+64 characters and JSON-quoted, with every character outside printable ASCII
+escaped. A plain key extends the path with `.key`; any other key appears as
+`["key"]`. For example:
+
+```text
+claude-marketplace-entry-v1: unknown top-level key "pluginSearchPaths" in claude-plugins-official
+claude-marketplace-entry-v1: unknown key "metadata.skillRoot" in claude-plugins-official
+claude-marketplace-entry-v1: unknown key "plugins[swift-lsp].futureInjector" in claude-plugins-official
+claude-marketplace-entry-v1: unknown key "plugins[swift-lsp].source.script" in claude-plugins-official
+```
+
+Inside a hook check the same text follows `NATIVE_SKILL_DRIFT:`. The only way
+forward after such a refusal is a fresh human review of the changed catalog
+and a guarded exact re-pin through hook installation: write the reviewed
+witnesses to a discovery inputs file, preview `skills hook install --agent
+claude --discovery-inputs <file>`, then run the same command with `--apply`.
+While the unknown key is present this mode refuses capture too, so that review
+must bind the catalog another way, for example an exact `bytes` witness from
+`captureDiscoveryByteSources`, until a reviewed version of this mode covers the
+key. There is no bypass, ignore list or relaxed mode.
+
+The field lists follow the
+[marketplace reference](https://code.claude.com/docs/en/plugins/marketplace-reference)
+and the [plugin manifest reference](https://code.claude.com/docs/en/plugins/manifest-reference),
+read on 2026-10-07.
+
+Capture a witness with
+`skills hook witness --kind claude-marketplace-entry-v1 --path <marketplace.json>
+--marketplace <name> --plugin <name> --json` (or
+`captureClaudeMarketplaceEntry(path, marketplace, plugin)`). Capture writes
+nothing and does not authorize a review. Put the witness in reviewed discovery
+inputs, keep the `settings.json`, `installed_plugins.json` and
+`known_marketplaces.json` witnesses and the plugin's absence witnesses, and
+preview `skills hook install --discovery-inputs <file>` before applying. Hook
+installation never rewrites the catalog, so an entry change between planning
+and applying refuses.
+
+Install a runtime that recognizes `claude-marketplace-entry-v1`, including any
+bundled copy of the verifier, before a policy carries it; an older runtime
+refuses the whole policy because the hash mode is unknown.
+
 ## Claude settings preferences
 
 `captureClaudeSettings(canonicalSettingsPath)` returns a versioned

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/skills",
-  "version": "0.10.51",
+  "version": "0.10.52",
   "description": "Skills library for AI coding agents",
   "type": "module",
   "bin": {