dsh-plugin-inspector 0.1.0 → 0.2.1

package/lib/types/npm.d.ts

@@ -0,0 +1,40 @@
+/**
+ * `--from-npm` — inspecting a published package without installing it.
+ *
+ * This module is the only path in the tool that reaches a network, and it is
+ * separate from `inspect.ts` on purpose: a directory or tarball scan cannot
+ * arrive here, because nothing on that path imports this file. The steps are
+ * 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`;
+ * 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.
+ *
+ * No subprocess, no disk write, no lifecycle script, and no `npm pack`.
+ * @module dsh-plugin-inspector/npm
+ */
+import type { Report } from './model.ts';
+import { type RegistryOptions, type ResolvedPackage } from './registry.ts';
+/**
+ * The metadata pre-check, which needs no tarball.
+ *
+ * A caller sweeping many packages can read this for each of them at a few
+ * kilobytes apiece and decide which ones are worth downloading.
+ * @param spec - `<name>` or `<name>@<version>`.
+ * @param options - where to fetch from.
+ * @returns what the version document says.
+ * @throws RegistryError when the package or version does not resolve.
+ */
+export declare function precheck(spec: string, options?: RegistryOptions): Promise<ResolvedPackage>;
+/**
+ * Fetch a published package and inspect it in memory.
+ * @param spec - `<name>` or `<name>@<version>`; no version means the `latest` tag.
+ * @param options - where to fetch from.
+ * @returns the complete report, carrying the registry provenance.
+ * @throws RegistryError when the package cannot be resolved, fetched, or verified.
+ * @throws SourceError or ManifestError when the fetched tarball is not a package.
+ */
+export declare function inspectFromNpm(spec: string, options?: RegistryOptions): Promise<Report>;
+//# sourceMappingURL=npm.d.ts.map

package/lib/types/registry.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Fetching a published package from an npm registry, and proving the bytes are
+ * the ones the registry vouched for.
+ *
+ * This is the one module in the tool that opens a socket, and it exists behind
+ * one explicit flag. A network fetch is not execution — nothing here installs,
+ * unpacks to disk, or runs a lifecycle script — but it is a side effect the
+ * tool's other two modes do not have, so it is never reached implicitly: a
+ * directory or tarball scan cannot get here, because neither imports this
+ * module.
+ *
+ * The order of operations is the security property. The packument is read
+ * first, which is ~3 KB and already answers `hasInstallScript`, the install
+ * lifecycle scripts, and whether the package declares `dsh.bundle` — a
+ * pre-check that needs no tarball at all. Only then is the tarball fetched, and
+ * its `dist.integrity` hash is verified **before** any byte of it reaches the
+ * tar parser. A hash mismatch is a refusal, not a warning: the whole point of
+ * the mode is that the analysed bytes are the published bytes.
+ * @module dsh-plugin-inspector/registry
+ */
+/** The public npm registry, used when no other is named. */
+export declare const DEFAULT_REGISTRY = "https://registry.npmjs.org";
+/** Largest packument the tool will read. A version document is a few kilobytes. */
+export declare const MAX_METADATA_BYTES: number;
+/**
+ * Largest compressed tarball the tool will download. The decompressed stream is
+ * capped separately, and lower, by the tar reader.
+ */
+export declare const MAX_TARBALL_BYTES: number;
+/** Thrown when a package cannot be resolved, fetched, or verified. */
+export declare class RegistryError extends Error {
+}
+/** One `<name>` or `<name>@<version>` argument, split. */
+export interface PackageSpec {
+    readonly name: string;
+    /** A version or dist-tag, or `null` to mean the `latest` tag. */
+    readonly version: string | null;
+}
+/**
+ * What the packument says, before anything is downloaded. Every field here
+ * costs one small request and no tarball.
+ */
+export interface ResolvedPackage {
+    readonly name: string;
+    readonly version: string;
+    readonly tarball: string;
+    /** The registry's own SRI string, e.g. `sha512-…`, or `null` on old packages. */
+    readonly integrity: string | null;
+    /** The legacy SHA-1 digest, the only check available when `integrity` is absent. */
+    readonly shasum: string | null;
+    /** The registry's own flag, which is set when npm would run an install script. */
+    readonly hasInstallScript: boolean;
+    /** Install lifecycle script names the manifest declares. */
+    readonly lifecycleScripts: readonly string[];
+    /** The `dsh.bundle.patch` value, which is what makes a package a mounted layer. */
+    readonly bundlePatch: string | null;
+    /** Bytes of metadata read to learn all of the above. */
+    readonly metadataBytes: number;
+}
+/** How a fetched tarball was verified. */
+export interface VerifiedTarball {
+    readonly bytes: Buffer;
+    /** The algorithm the digest was taken with, e.g. `sha512`. */
+    readonly algorithm: string;
+    /** The digest that matched, in the registry's own encoding. */
+    readonly digest: string;
+}
+/** Where to fetch from. */
+export interface RegistryOptions {
+    /** Registry base URL, without a trailing slash. Defaults to {@link DEFAULT_REGISTRY}. */
+    readonly registry?: string;
+    /** Injected for tests; defaults to the global `fetch`. */
+    readonly fetch?: typeof globalThis.fetch;
+}
+/**
+ * Split a `<name>` or `<name>@<version>` argument.
+ *
+ * The `@` that starts a scope is not a separator, so `@scope/name` has no
+ * version and `@scope/name@1.2.3` has one.
+ * @param spec - the argument as typed.
+ * @returns the package name and the requested version, if any.
+ * @throws RegistryError when the name or version is not one the registry accepts.
+ */
+export declare function parseSpec(spec: string): PackageSpec;
+/**
+ * Read the packument for one version, which is the pre-check.
+ * @param spec - the package name and requested version.
+ * @param options - where to fetch from.
+ * @returns everything the metadata says, including the tarball URL and its hash.
+ * @throws RegistryError when the package or version does not resolve, or when
+ * the document does not carry a tarball URL on the registry's own origin.
+ */
+export declare function resolvePackage(spec: PackageSpec, options?: RegistryOptions): Promise<ResolvedPackage>;
+/**
+ * Check downloaded bytes against what the registry published.
+ *
+ * `dist.integrity` is preferred and is a real check. `dist.shasum` is SHA-1 and
+ * is accepted only when there is no `integrity` field at all, which happens on
+ * packages published before npm 5; it is recorded in the report as the weaker
+ * check it is. No digest at all is a refusal, because "verified" would then be
+ * a claim the tool cannot make.
+ * @param bytes - the downloaded tarball.
+ * @param resolved - what the packument said about it.
+ * @returns the algorithm and digest that matched.
+ * @throws RegistryError on a mismatch, an unusable digest, or no digest at all.
+ */
+export declare function verifyIntegrity(bytes: Buffer, resolved: ResolvedPackage): VerifiedTarball;
+/**
+ * Download a resolved package's tarball and verify it before returning it.
+ *
+ * Nothing parses the bytes on the way in — they are counted against a ceiling
+ * and hashed, and a failed hash throws before any caller can see them.
+ * @param resolved - the packument reading for the version to fetch.
+ * @param options - where to fetch from.
+ * @returns the verified tarball, in memory.
+ * @throws RegistryError on a transport failure, an oversized body, or a hash mismatch.
+ */
+export declare function fetchVerifiedTarball(resolved: ResolvedPackage, options?: RegistryOptions): Promise<VerifiedTarball>;
+//# sourceMappingURL=registry.d.ts.map

package/lib/types/source.d.ts

@@ -37,9 +37,15 @@ export declare const DEFAULT_LIMITS: ReadLimits;
 /** Thrown when the target cannot be read at all, which is exit code 2, not a finding. */
 export declare class SourceError extends Error {
 }
+/**
+ * Where the analysed bytes came from. `registry` is a tarball too — the same
+ * in-memory decoding, over bytes fetched by `--from-npm` instead of read from
+ * disk — and is kept distinct so a report says which one it was.
+ */
+export type SourceKind = 'directory' | 'tarball' | 'registry';
 /** The analysed package, decoded into memory. */
 export interface PluginSource {
-    readonly kind: 'directory' | 'tarball';
+    readonly kind: SourceKind;
     /** The target as the user gave it, resolved to an absolute path. */
     readonly path: string;
     /** Package-relative POSIX path to UTF-8 text, for every readable text file. */
@@ -68,4 +74,18 @@ export declare const MAX_STREAM_BYTES: number;
  * tarball, or holds no `package.json`.
  */
 export declare function loadSource(target: string, limits?: ReadLimits): Promise<PluginSource>;
+/**
+ * Decode an npm tarball held in memory, for bytes that never touched the disk.
+ *
+ * The only caller is the `--from-npm` path, which fetches a tarball and
+ * verifies its `dist.integrity` hash before handing the buffer here. Reading it
+ * goes through the same `Parser` as the on-disk path, so the "no extraction,
+ * ever" property covers both.
+ * @param bytes - the complete tarball, gzipped or not.
+ * @param label - what to report as the target path, e.g. `npm:pkg@1.2.3`.
+ * @param limits - resource ceilings; defaults to {@link DEFAULT_LIMITS}.
+ * @returns the decoded package.
+ * @throws SourceError when the buffer is not a readable npm tarball.
+ */
+export declare function loadTarballBuffer(bytes: Buffer, label: string, limits?: ReadLimits): Promise<PluginSource>;
 //# sourceMappingURL=source.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-inspector",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "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",
@@ -56,6 +56,7 @@
     "test": "vitest run --config vitest.config.ts",
     "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",
     "test:e2e": "pnpm run build && vitest run --config vitest.e2e.config.ts"
   }
 }