@hasna/skills 0.10.50 → 0.10.52

package/dist/server/maintenance-entry.d.ts

@@ -9,7 +9,21 @@ type InspectionManifest = EnrollmentInspectionInput & {
     expiresAt: string;
     manifestDigest: string;
 };
+/** The schema census has its own authorization; no enrollment or inspection manifest can authorize it. */
+type SchemaCensusManifest = {
+    app: "skills";
+    operation: "inspect-schema";
+    manifestVersion: 1;
+    operationId: string;
+    stationId: string;
+    keyId: string;
+    orgId: string;
+    expiresAt: string;
+    manifestDigest: string;
+};
 /** Inspection has its own authorization; a failed enrollment manifest cannot authorize it. */
 export declare function readInspectionManifest(path: string, receiptPath: string): InspectionManifest;
+/** The census has its own authorization; a failed enrollment or inspection manifest cannot authorize it. */
+export declare function readSchemaCensusManifest(path: string, receiptPath: string): SchemaCensusManifest;
 export declare function registerMaintenance(parent: Command): void;
 export {};

package/dist/server/schema-census.d.ts

@@ -0,0 +1,77 @@
+/**
+ * One fixed, closed census of the Skills database maintenance surface.
+ *
+ * Why it exists (I6-00024): a production migration is held until the exact
+ * current registry, version ledger and migration ledger are read from the live
+ * database. The enrollment inspection answers a different question (one
+ * operator key), and no existing reader returns the fixed aggregate + ledger
+ * census. This module is that reader, and it is deliberately shaped so it
+ * cannot become a general SQL console:
+ *
+ *   - No target, query, schema or table input exists. The only argument is the
+ *     database URL, and the operation refuses to run unless the connection
+ *     resolves to the fixed public schema the Skills store uses.
+ *   - Every owned-table read is schema-qualified to `public`. A connection whose
+ *     search path falls through to a later schema cannot substitute another
+ *     schema's tables: a missing public table refuses (CENSUS_SCHEMA_UNAVAILABLE)
+ *     instead of counting rows that do not belong to the fixed target.
+ *   - The transaction is READ ONLY, REPEATABLE READ, with a five-second
+ *     statement timeout and a one-second lock timeout, asserted from inside the
+ *     read path rather than assumed.
+ *   - The output is a closed shape with per-field size bounds, a bounded
+ *     migration ledger and a total serialized-size gate. Nothing is truncated
+ *     silently: a census that would exceed a bound refuses instead.
+ *   - Nothing imports the application store: no initialization, migrations,
+ *     backfills or writes happen on this path.
+ */
+export interface SchemaCensusResult {
+    status: "inspected";
+    database: string;
+    role: string;
+    serverVersion: string;
+    schema: "public";
+    transaction: {
+        readOnly: true;
+        isolation: "repeatable read";
+        statementTimeoutMs: number;
+        lockTimeoutMs: number;
+    };
+    migrations: {
+        count: number;
+        versions: string[];
+    };
+    registry: {
+        rows: number;
+    };
+    versions: {
+        rows: number;
+    };
+    lifecycle: {
+        active: {
+            live: number;
+            tombstoned: number;
+        };
+        archived: {
+            live: number;
+            tombstoned: number;
+        };
+    };
+    authorizationEpoch: {
+        exists: false;
+    } | {
+        exists: true;
+        nullCount: number;
+    };
+}
+type CensusCode = "CENSUS_POSTGRES_REQUIRED" | "CENSUS_SCHEMA_UNAVAILABLE" | "CENSUS_ACCESS_DENIED" | "CENSUS_WRITE_REFUSED" | "CENSUS_TIMEOUT" | "CENSUS_CONNECTION_FAILED" | "CENSUS_TARGET_MISMATCH" | "CENSUS_INVALID_RESULT" | "CENSUS_OUTPUT_UNBOUNDED" | "CENSUS_FAILED";
+export declare class SchemaCensusError extends Error {
+    readonly code: CensusCode;
+    constructor(code: CensusCode);
+}
+/**
+ * Census metadata only. Deliberately does not import or initialize the application store.
+ *
+ * @param databaseUrl explicit PostgreSQL URL; there is no implicit localhost fallback.
+ */
+export declare function inspectSchemaCensus(databaseUrl: string): Promise<SchemaCensusResult>;
+export {};

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
@@ -404,8 +589,8 @@ witness intersecting the write still refuses instead of adopting a new inode.
 
 ## Codex bundled cleanup controls
 
-Qualified native skill review supports a narrow subset of Codex 0.159.2 and
-0.160.0's bundled cleanup hooks. The identities `browser`, `chrome`, `chrome-dev`,
+Qualified native skill review supports a narrow subset of Codex 0.159.2,
+0.160.0 and 0.160.1's bundled cleanup hooks. The identities `browser`, `chrome`, `chrome-dev`,
 `chrome-internal` and `computer-use` in `openai-bundled` may call
 `node_repl.turn_ended`; `unified-computer-use` may call `cua_repl.turn_ended`.
 Only `Interrupt`, `SubagentStop` and `Stop` are accepted, with one group and one
@@ -421,4 +606,6 @@ apply and subsequent discovery checks. This review preserves native cleanup;
 it neither enables plugins nor grants hook trust, browser authority or signing.
 The upstream contracts are
 [0.159.2 bundled hooks](https://github.com/openai/codex/blob/ff6aec96948b70d94983af2641a6b67c94faeff5/codex-rs/plugin/src/bundled_hooks.rs)
-and [0.160.0 bundled hooks](https://github.com/openai/codex/blob/a956835d020762cb2b570053af06f643a11c0ecc/codex-rs/plugin/src/bundled_hooks.rs).
+and [0.160.0 bundled hooks](https://github.com/openai/codex/blob/a956835d020762cb2b570053af06f643a11c0ecc/codex-rs/plugin/src/bundled_hooks.rs);
+0.160.1 carries the identical file
+([0.160.1 bundled hooks](https://github.com/openai/codex/blob/d27764b82f7118f674371e6d6e76271d9d606edb/codex-rs/plugin/src/bundled_hooks.rs)).

package/package.json

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