dsh-plugin-inspector 0.6.0 → 0.8.0

package/lib/types/knowledge.d.ts

@@ -11,9 +11,17 @@
  */
 /**
  * Harness version these tables were transcribed from — the version string in
- * the checkout's own `packages/bundle/*/package.json`.
+ * the shipped bundles' own `package.json`, which is `dsh`'s own version.
+ *
+ * Re-verified against `0.1.2-rc.1`, the release npm tags `latest`, by
+ * extracting each table from the published packages and diffing it against the
+ * one here. What moved: thirteen row ids the bundles gained against three they
+ * dropped, four rows the base layer inserts that only the web bundle carried,
+ * eleven seam keys against one dropped, and two waterfall events against one
+ * dropped. What did not: the sandbox trap table, the teardown surfaces, and
+ * every `DECISION_EVENT_DEFAULTS` citation, all re-read at this release.
  */
-export declare const HARNESS_REFERENCE = "0.1.0-rc.5";
+export declare const HARNESS_REFERENCE = "0.1.2-rc.1";
 /** The shipped bundles, each of which is one patch layer over the profile root. */
 export type BundleName = 'base' | 'headless' | 'web-app';
 /**
@@ -62,7 +70,99 @@ export declare const SECURITY_ROW_IDS: ReadonlyMap<string, string>;
  * replaces a core service for every consumer in its scope.
  */
 export declare const SEAM_KEYS: ReadonlySet<string>;
-/** The subset of {@link SEAM_KEYS} whose replacement removes a constraint. */
+/**
+ * The subset of {@link SEAM_KEYS} whose replacement removes a constraint.
+ *
+ * `authorization` is the registry of flows that obtain a credential through a
+ * conversation with the user, so providing it means owning that conversation.
+ * That is the same class of substitution as `credentials`, which this set
+ * already holds. `fileReferences` decides which paths are offered for
+ * completion and `agentTeams` is the team form of `subagents`, which is
+ * deliberately not here either, so neither of those is in this set.
+ *
+ * Seven of the eleven keys `0.1.2-rc.1` adds are Remote controllers: host
+ * services that own one `ctx.remote.*` namespace the browser client calls
+ * across the wire. A controller belongs here only when the traffic a
+ * substitution redirects to it carries a secret, an execution boundary, or a
+ * decision. A controller that forwards its seam's own verbs and adds a wire
+ * failure vocabulary does not, because the seam it fronts is reachable from
+ * `ctx` without substituting anything.
+ *
+ * Included:
+ * - `credentialsController` is what a browser configuration page calls to store
+ *   a credential. `set(ref, value)` receives the plaintext secret and hands it
+ *   to `ctx.credentials`
+ *   (`@deepseek-ai/dsh-api-settings-controller/lib/index.js:171`), and
+ *   `projectCredentialInfo` at `lib/index.js:78` is what holds a `describe`
+ *   answer to the three fields `CredentialInfo` declares. A layer that provides
+ *   it takes both halves: every secret typed into the settings page, and the
+ *   freedom to answer a read with the stored value.
+ * - `settingsController` passes `redactSecrets: true` on every remote read
+ *   (`@deepseek-ai/dsh-api-settings-controller/lib/index.js:429` and `:544`),
+ *   which is what keeps a `role('secret')` field out of a settings response;
+ *   `@deepseek-ai/dsh-web-search-deepseek/lib/index.js:245` declares one, an
+ *   `apiKey`. Its `update`, `replace` and `mutate` verbs carry that same field's
+ *   value in plaintext from the configuration page. Providing it puts the layer
+ *   on both directions of a secret's path.
+ * - `sessionController` resolves each new Session's cwd from the wire request
+ *   and hands it to `ensureSession`
+ *   (`@deepseek-ai/dsh-api-session-controller/lib/index.js:574`), and
+ *   `@deepseek-ai/dsh-sandbox-policy` resolves that immutable cwd as the
+ *   `workspace-write` root the enforcing filesystem, bash and terminal backends
+ *   fence against. Its `prompt` verb builds the message admitted to the agent
+ *   under `source.kind: 'user'` (`lib/index.js:731`). Providing it chooses the
+ *   sandbox root for every session created from the client, and the text that
+ *   reaches the model under the user's own source label.
+ * - `webhookRuntime` is what a provider adapter such as
+ *   `@deepseek-ai/dsh-webhook-github` dispatches verified deliveries into. Its
+ *   one built-in action creates a Session from a rule result whose fields
+ *   include `workspacePath`, `permissionPreset` and `prompt`
+ *   (`@deepseek-ai/dsh-webhook/lib/types/types.d.ts`), and
+ *   `createWebhookSession` applies that preset through
+ *   `ctx.permissionPresets.set` before admitting the prompt
+ *   (`@deepseek-ai/dsh-webhook/lib/types/session.js:94`, `:117`, `:120`).
+ *   Providing it picks the approval and sandbox preset for an agent started by
+ *   a remote delivery with no user present.
+ *
+ * Excluded:
+ * - `workspaceController` forwards `request.path` to
+ *   `ctx.workspaceRegistry.create` unchanged and adds an ordering queue and
+ *   error mapping (`@deepseek-ai/dsh-api-workspace-controller/lib/index.js:196`
+ *   to `:212`). The registry it fronts is `workspaceRegistry`, which is not
+ *   here, so the substitution reaches nothing the seam does not already offer.
+ * - `directoryPickerController` is three delegations to
+ *   `ctx.directoryPicker.capability()` behind a check that refuses a verb the
+ *   composed backend does not serve
+ *   (`@deepseek-ai/dsh-api-workspace-controller/lib/index.js:423` to `:470`).
+ *   Path fencing lives in the backend, and `directoryPicker` is not here.
+ * - `sessionFileReferences` is the Remote adapter over `fileReferences`, which
+ *   is excluded above for the same reason: the traffic is path candidates
+ *   offered for completion.
+ * - `sessionSkillCatalog` answers with `SkillListValue`, declared as the list
+ *   for one Session's human-facing composer
+ *   (`@deepseek-ai/dsh-api-session-controller/lib/types/types.d.ts:213` to
+ *   `:227`), and its only consumer in this release is the client skill picker
+ *   (`@deepseek-ai/dsh-client-ui-skill/lib/client.js:236`). Skill text reaches a
+ *   model through `ctx.skills.list()` in
+ *   `@deepseek-ai/dsh-tool-skill/lib/index.js:145`, which is the `skills` seam.
+ * - `subagentModelSelection` is a settings owner answering `{ enabled,
+ *   allowedModels }`, sampled when an Agent receives its delegation tools. Model
+ *   routing is `llm` and delegation is `subagents`; neither is here.
+ * - `deepseekLlmApiExtensions` hands a substitute the serialized request body
+ *   and merges the fields it returns, but
+ *   `@deepseek-ai/dsh-llm-deepseek/lib/index.js:1748` rejects any extension
+ *   field colliding with the base request, so `messages`, `tools` and `model`
+ *   are not writable through it. The constraint is in the adapter, not the
+ *   registry the substitution replaces.
+ * - `inspector` is declared by the catalogue and implemented by no shipped
+ *   package: in `0.1.2-rc.1` the key, `InspectorJsonValue` and
+ *   `CordisRuntimeTreeReader` occur only in
+ *   `@deepseek-ai/dsh-tool-cordis/lib/index.js`, and nothing provides or reads
+ *   `ctx.inspector`. No composed row enforces anything through it, so a
+ *   substitution displaces nothing. This is the one entry decided from the
+ *   catalogue rather than from an implementation; a release that ships one is a
+ *   reason to decide it again.
+ */
 export declare const SECURITY_SEAM_KEYS: ReadonlySet<string>;
 /**
  * Waterfall events, from `EVENT_API` in the api-catalog. A listener on one of
@@ -70,9 +170,24 @@ export declare const SECURITY_SEAM_KEYS: ReadonlySet<string>;
  * without calling it short-circuits the chain including the built-in behavior.
  *
  * Note there is no `fs/read-intent` — the intent family is write and edit only.
+ *
+ * `0.1.2-rc.1` renames `tools/code-dispatch-log` to `tools/ptc-dispatch-log`
+ * and adds `user-questions/request`. Both replace content in a durable log copy
+ * or answer a pending request; neither is an `emit` event, so both hand a
+ * listener the trailing `next`.
  */
 export declare const WATERFALL_EVENTS: ReadonlySet<string>;
-/** Waterfall events whose short-circuit removes a decision the user would otherwise make. */
+/**
+ * Waterfall events whose short-circuit removes a decision the user would
+ * otherwise make.
+ *
+ * `user-questions/request` is here for the same reason `approval/request` is:
+ * `ctx.userQuestions` pauses a tool call until a human answers, and the
+ * answerers that put the question on a screen are listeners in the chain rather
+ * than the inner callback (`@deepseek-ai/dsh-user-questions/lib/index.js:69`).
+ * A listener that returns an answer without calling `next()` answers on the
+ * user's behalf and the question is never shown.
+ */
 export declare const DECISION_EVENTS: ReadonlySet<string>;
 /**
  * Globals the dynamic-package sandbox (`cordis-host-runner/src/sandbox.ts`)
@@ -188,4 +303,97 @@ export declare const HARNESS_INERT_CALLS: ReadonlySet<string>;
  * in code, and it is plain YAML.
  */
 export declare const SERVICE_REMAPPING_FIELDS: readonly string[];
+/**
+ * How a Cordis waterfall listener delegates, and what happens when it does not.
+ *
+ * Read out of the installed `@deepseek-ai/cordis@4.0.2` build,
+ * `lib/index.js:317-327`:
+ *
+ * ```js
+ * waterfall(...args) {
+ *   const cbs = this.dispatch("waterfall", args);
+ *   const inner = args.pop();
+ *   const next = () => { return (cbs.shift() ?? inner)(...args); };
+ *   args.push(next);
+ *   return next();
+ * }
+ * ```
+ *
+ * `next` is the trailing argument every listener receives, and `inner` is the
+ * harness's own built-in behavior. A listener that returns without calling
+ * `next()` therefore ends the chain: neither the listeners still in `cbs` nor
+ * `inner` run.
+ *
+ * The scope of that is one dispatch, not the registry. `dispatch()` builds
+ * `cbs` with `.filter(…).map(…)`, which allocates, so `this._hooks[name]` is
+ * never touched and every skipped listener is registered and runs normally on
+ * the next dispatch. The precise word is veto, not removal — Cordis's own
+ * JSDoc at `lib/index.js:311-313` says "vetoes the rest of the chain, including
+ * the built-in behavior". Removal is a different capability with a different
+ * reach, and it has its own table below.
+ */
+export declare const WATERFALL_NEXT_PARAMETER = "next";
+/**
+ * What each decision waterfall's built-in `next` settles on when no listener
+ * claims the dispatch, transcribed from the installed harness `0.1.2-rc.1`.
+ *
+ * This is what a listener that never calls `next()` replaces. The inner
+ * callback is the last argument at each site:
+ * - `tools/pre-execute` — `@deepseek-ai/dsh-tools/lib/index.js:3117`,
+ *   `() => Promise.resolve({ kind: "allow" })`
+ * - `tools/execute` — `dsh-tools/lib/index.js:3214`,
+ *   `() => this.dispatchToolBody(mutableExec)`, so vetoing it substitutes the
+ *   body of the tool call itself
+ * - `approval/request` — `@deepseek-ai/dsh-user-approval/lib/index.js:179`,
+ *   `() => Promise.resolve("unavailable")`, and the surface that would ask the
+ *   user is one of the listeners in the chain rather than the inner callback
+ * - `user-questions/request` —
+ *   `@deepseek-ai/dsh-user-questions/lib/index.js:67`, the `noAnswerer`
+ *   callback passed at `:69`, which rejects with a `UserQuestionError` carrying
+ *   code `NO_PROVIDER`
+ *
+ * The three tables in this module that name events (`WATERFALL_EVENTS`,
+ * `DECISION_EVENTS`, and this one) are keyed to {@link HARNESS_REFERENCE}.
+ */
+export declare const DECISION_EVENT_DEFAULTS: ReadonlyMap<string, string>;
+/**
+ * Receivers whose members name a plugin context.
+ *
+ * The same set the Tier C detached-member check guards on, minus `process`:
+ * a seam is read off the context, never off `process`.
+ */
+export declare const CONTEXT_RECEIVERS: ReadonlySet<string>;
+/**
+ * Array and collection methods that change the receiver rather than reading it.
+ *
+ * Used to tell a write into a service's internals from a read of them. The
+ * distinction is not academic: `dsh-dlp` reads
+ * `ctx.events._hooks['approval/request']?.length` to decide whether an ask
+ * would reach a human, which is an honest use of the same property a hostile
+ * layer splices.
+ */
+export declare const MUTATING_METHODS: ReadonlySet<string>;
+/** One Cordis bookkeeping surface that owns other plugins' registrations. */
+export interface TeardownSurface {
+    /** The member read off the context, e.g. `events`. */
+    readonly service: string;
+    /** The member read off that, e.g. `_hooks`. */
+    readonly member: string;
+    /**
+     * True when merely naming the surface is the finding. False when only a
+     * write counts, because reading it is something an honest plugin does.
+     */
+    readonly readIsEnough: boolean;
+    /** What reaching it does, phrased for a report. */
+    readonly effect: string;
+}
+/**
+ * Cordis internals through which one plugin removes another plugin's
+ * registrations. Read from the installed `@deepseek-ai/cordis@4.0.2` build.
+ *
+ * None of these is guarded by ownership. `ctx.events`, `ctx.registry` and
+ * `ctx.reflect` are own properties of the root context inherited by every
+ * child, so no `inject` declaration is needed to reach any of them.
+ */
+export declare const TEARDOWN_SURFACES: readonly TeardownSurface[];
 //# sourceMappingURL=knowledge.d.ts.map

package/lib/types/model.d.ts

@@ -9,6 +9,7 @@
  * would fire on every legitimate plugin and train users to ignore the tool.
  * @module dsh-plugin-inspector/model
  */
+import type { ProvenanceFact } from './attestation.ts';
 /** How much a finding should weigh on an install decision. */
 export type Severity = 'critical' | 'high' | 'medium' | 'low';
 /**
@@ -25,7 +26,11 @@ export declare const SEVERITY_RANK: Readonly<Record<Severity, number>>;
 export declare const SEVERITIES: readonly Severity[];
 /** Where in the analysed package a finding was observed. */
 export interface Evidence {
-    /** Package-relative path of the file the finding came from. */
+    /**
+     * Package-relative path of the file the finding came from, or the name of the
+     * registry field it came from when the finding is about what the registry
+     * published rather than about the package contents.
+     */
     readonly file: string;
     /** A locator inside that file: a YAML path, a JSON pointer, or `line:column`. */
     readonly path?: string;
@@ -93,6 +98,13 @@ export interface Facts {
     readonly packageName: string;
     readonly packageVersion: string;
     readonly license: string | null;
+    /**
+     * What the registry says about where this tarball was built, and which of
+     * those claims this run checked. Always present: the two modes that read
+     * local bytes report `unavailable`, which is a different answer from a
+     * published package that has no attestation.
+     */
+    readonly provenance: ProvenanceFact;
     /** True when `package.json` declares `dsh.bundle.patch` — a mounted patch layer. */
     readonly mountsAsBundle: boolean;
     /** The declared patch path, verbatim and unresolved, or `null`. */

package/lib/types/npm.d.ts

@@ -7,10 +7,20 @@
  * fixed and their order is the guarantee:
  *
  * 1. read the version document (~3 KB) — which already answers
- *    `hasInstallScript`, the install lifecycle scripts, and `dsh.bundle`;
+ *    `hasInstallScript`, the install lifecycle scripts, `dsh.bundle`, and
+ *    whether the registry holds a provenance attestation at all;
  * 2. download the tarball into memory;
  * 3. verify `dist.integrity` **before** anything parses a byte of it;
- * 4. decode in memory and analyse, exactly as the tarball path does.
+ * 4. read the provenance attestation, when step 1 said there is one, and check
+ *    it against the bytes step 3 vouched for;
+ * 5. decode in memory and analyse, exactly as the tarball path does.
+ *
+ * Step 4 is the only request this module makes that is not unconditional, and
+ * it is skipped for every package the version document says has no attestation
+ * — which on the measured corpus is 28 packages in 40. It never fails an
+ * analysis: an endpoint that is down or a bundle that does not decode leaves
+ * the provenance fact in state `unreadable`, which is a different answer from
+ * `absent` and is printed as one.
  *
  * No subprocess, no disk write, no lifecycle script, and no `npm pack`.
  * @module dsh-plugin-inspector/npm

package/lib/types/registry.d.ts

@@ -54,6 +54,13 @@ export interface ResolvedPackage {
     readonly lifecycleScripts: readonly string[];
     /** The `dsh.bundle.patch` value, which is what makes a package a mounted layer. */
     readonly bundlePatch: string | null;
+    /**
+     * The predicate type of the provenance attestation the registry says it
+     * holds for this version, from `dist.attestations.provenance`, or `null` when
+     * it says it holds none. Reading it here is what keeps the attestation
+     * endpoint unasked for the majority of packages that have no attestation.
+     */
+    readonly provenancePredicateType: string | null;
     /** Bytes of metadata read to learn all of the above. */
     readonly metadataBytes: number;
 }
@@ -116,4 +123,37 @@ export declare function verifyIntegrity(bytes: Buffer, resolved: ResolvedPackage
  * @throws RegistryError on a transport failure, an oversized body, or a hash mismatch.
  */
 export declare function fetchVerifiedTarball(resolved: ResolvedPackage, options?: RegistryOptions): Promise<VerifiedTarball>;
+/**
+ * The endpoint an npm-compatible registry serves a version's attestation
+ * bundle from.
+ *
+ * Built from the registry base URL rather than read out of
+ * `dist.attestations.url`, which is the opposite of how the tarball URL is
+ * handled and is deliberate: the tarball has to come from wherever the registry
+ * says because there is no other way to name it, so that URL is taken from the
+ * document and then refused unless it is same-origin. An attestation needs no
+ * such freedom. Constructing the path here means a doctored packument cannot
+ * redirect the request at all, not even to another path on the same host.
+ *
+ * The name and version are re-validated because both come out of the version
+ * document, which is registry-controlled: `name` is not necessarily the name
+ * that was asked for, and it is interpolated into a URL.
+ * @param registry - the registry base URL, without a trailing slash.
+ * @param name - the resolved package name.
+ * @param version - the resolved version.
+ * @returns the absolute URL.
+ * @throws RegistryError when the document's name or version would not address this endpoint.
+ */
+export declare function attestationUrl(registry: string, name: string, version: string): string;
+/**
+ * Download an attestation document.
+ *
+ * Only ever called when the version document said there is one, so a package
+ * without provenance costs no request at all.
+ * @param url - the endpoint, from {@link attestationUrl}.
+ * @param options - where to fetch from.
+ * @returns the document as served.
+ * @throws RegistryError on a transport failure, a non-2xx status, or an oversized body.
+ */
+export declare function fetchAttestation(url: string, options?: RegistryOptions): Promise<Buffer>;
 //# sourceMappingURL=registry.d.ts.map

package/lib/types/syntax.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Readings of a syntax tree that both capability detection and readability
+ * detection need, and that must agree between them.
+ *
+ * Tier B matches a name; Tier C reports the names it could not match. If the
+ * two disagree about which expressions are constant, a package gets both a
+ * finding and a degrade for the same site, or neither. They agree because they
+ * ask the same function.
+ *
+ * Nothing here evaluates anything. {@link foldConstantString} reads literals
+ * out of an already-parsed tree and concatenates them; it never constructs a
+ * function, and it never touches an identifier's value.
+ * @module dsh-plugin-inspector/syntax
+ */
+import ts from 'typescript';
+/**
+ * The text a constant string expression holds, or `null` when the expression is
+ * not constant.
+ *
+ * Four forms, chosen because each one is a spelling of a name that a reader
+ * sees and a name-matching check does not: a literal, a `+` chain of them, a
+ * template whose every span is one, and `[…].join(…)` over an array of them.
+ * Anything reaching an identifier, a property, or any other call answers
+ * `null` — resolving those is value tracking, which this tool does not do and
+ * which Tier C exists to admit.
+ * @param node - the expression, or `undefined` for a missing argument.
+ * @returns the text, or `null`.
+ */
+export declare function foldConstantString(node: ts.Node | undefined): string | null;
+/**
+ * The Node API that hands back a builtin module without `require` and without
+ * an `import` declaration, added in Node 22.3.
+ *
+ * It reaches the same modules the harness sandbox's `require` trap covers,
+ * from a call that sandbox never sees: the sandbox leaves
+ * `process` `undefined`, so inside it this expression throws, and a mounted
+ * bundle layer is not inside it.
+ * @see https://nodejs.org/api/process.html#processgetbuiltinmoduleid
+ */
+export declare const BUILTIN_MODULE_GETTER = "getBuiltinModule";
+/**
+ * Whether a call is `process.getBuiltinModule(…)`.
+ *
+ * The receiver is required. `getBuiltinModule` pulled off `process` and bound
+ * to a bare name is not this — it is a detached member, which Tier C reports as
+ * dispatch it cannot follow.
+ * @param node - the call expression.
+ * @returns true when the call loads a builtin through `process`.
+ */
+export declare function isBuiltinModuleGetter(node: ts.CallExpression): boolean;
+//# sourceMappingURL=syntax.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-inspector",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Know what a DeepSeek Harness plugin does before you install it — static pre-install analysis of a plugin directory or tarball",
   "license": "MIT",
   "author": "Ivan Tyshchenko",
@@ -57,6 +57,7 @@
     "test:coverage": "vitest run --config vitest.config.ts --coverage",
     "inspect": "node --experimental-strip-types src/cli.ts",
     "sweep": "node --experimental-strip-types scripts/ecosystem-sweep.ts",
+    "sync": "node --experimental-strip-types scripts/harness-sync.ts",
     "test:e2e": "pnpm run build && vitest run --config vitest.e2e.config.ts"
   }
 }