tarsen-core 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Tarsen Contributors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,57 @@
+# tarsen-core
+
+Static npm package analysis for [Tarsen](../../README.md). Tarsen checks
+executable npm packages **before** developers or AI agents run them.
+
+`tarsen-core` is a pure local analyzer. It **never executes package code**,
+**never runs install scripts**, and **has no cloud connection or telemetry**.
+It turns registry metadata and extracted source files into a stable JSON risk
+report that the CLI (or any other tool) can render.
+
+## What it provides
+
+- **Registry metadata parsing** (`parseMetadata`) — normalize a version manifest
+  and packument into a typed `PackageMetadata`.
+- **Static file scanning** (`scanContent`, `scanFiles`) — pure string pattern
+  detection for child processes, dynamic execution, env/filesystem/network
+  access, and obfuscation. Never imports or evaluates the code it scans.
+- **Safe tarball helpers** (`isTraversalAttempt`, `makeSafeFilter`) — reject path
+  traversal, drop symlinks/hardlinks, and enforce entry caps during extraction.
+- **Risk scoring** (`scoreSignals`, `riskLevel`, `recommend`) — deterministic
+  mapping from signals to a `low | medium | high | unknown` band and a
+  recommendation.
+- **Report contract** (`RiskReport`, `analyzePackage`, `unknownReport`) — the
+  schema emitted by `tarsen check --json`.
+
+## Detection scope
+
+Lifecycle scripts (`preinstall`, `install`, `postinstall`, `prepare`),
+`child_process` / `exec(` / `spawn(` / `execSync(` / `spawnSync(`, `eval(` /
+`Function(`, sensitive `process.env`, `fs.readFile` / `fs.writeFile` / `fs.rm` /
+`fs.unlink`, `os.homedir(`, `fetch(` / `http.request` / `https.request` /
+`axios` / `XMLHttpRequest` / `WebSocket`, large minified files, very long
+lines, base64-like blobs, missing repository/maintainers/description, very new
+packages, and one-edit typosquatting against common package names.
+
+## Usage
+
+```ts
+import { analyzePackage, parseMetadata } from "tarsen-core";
+
+const metadata = parseMetadata(manifest, packument);
+const report = analyzePackage(metadata, [
+  { path: "index.js", content: "require('child_process').exec('whoami')" },
+]);
+// report.risk === "high"
+```
+
+## Safety guarantees
+
+This package only ever reads strings. It does not fetch from the network,
+execute code, or write anywhere — those concerns live in `tarsen`. The tar
+helpers are pure predicates and filter factories; the actual extraction is
+driven by the CLI into a temporary directory that it owns and cleans up.
+
+## License
+
+Apache-2.0. See [LICENSE](../../LICENSE).

package/dist/index.d.ts

@@ -0,0 +1,28 @@
+import type { PackageMetadata, RiskReport } from "./report.js";
+export { SCHEMA_VERSION } from "./report.js";
+export type { PackageMetadata, Recommendation, RiskLevel, RiskReport, RiskSignal, ScanStats, SignalSeverity, } from "./report.js";
+export { parseMetadata, typosquatSignal, isVeryNew, COMMON_PACKAGE_NAMES } from "./metadata.js";
+export { scanContent, scanFiles } from "./scan.js";
+export { capSignals, scoreSignals, riskLevel, recommend, SEVERITY_WEIGHTS } from "./score.js";
+export { isTraversalAttempt, makeSafeFilter, DEFAULT_EXTRACTION_LIMITS, } from "./tar.js";
+export type { ExtractionLimits, ExtractedFile, WalkResult } from "./tar.js";
+export interface AnalyzeOptions {
+    truncated?: boolean;
+}
+/**
+ * Combine metadata + scanned-file signals into a finalized report.
+ *
+ * This is the single entry point the CLI uses after extracting a tarball.
+ * It is a pure function of its inputs and safe to call against untrusted data.
+ */
+export declare function analyzePackage(metadata: PackageMetadata, files: Array<{
+    path: string;
+    content: string;
+}>, options?: AnalyzeOptions): RiskReport;
+/**
+ * Produce an `unknown` report when metadata fetch or extraction fails. The CLI
+ * uses this so `--json` always emits a valid object and a non-zero exit code,
+ * rather than crashing or printing a stack trace.
+ */
+export declare function unknownReport(packageSpec: string, error: unknown): RiskReport;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,eAAe,EAAE,UAAU,EAAc,MAAM,aAAa,CAAC;AAK3E,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,YAAY,EACV,eAAe,EACf,cAAc,EACd,SAAS,EACT,UAAU,EACV,UAAU,EACV,SAAS,EACT,cAAc,GACf,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,SAAS,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAChG,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACnD,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,SAAS,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAC9F,OAAO,EACL,kBAAkB,EAClB,cAAc,EACd,yBAAyB,GAC1B,MAAM,UAAU,CAAC;AAClB,YAAY,EAAE,gBAAgB,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAE5E,MAAM,WAAW,cAAc;IAC7B,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,eAAe,EACzB,KAAK,EAAE,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,EAC/C,OAAO,GAAE,cAAmB,GAC3B,UAAU,CAqBZ;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,UAAU,CAyB7E"}

package/dist/index.js

@@ -0,0 +1,74 @@
+// tarsen-core — static npm package analyzer.
+//
+// Tarsen never executes package code during analysis and never runs install
+// scripts. This package only fetches metadata, scans extracted source files as
+// strings, scores the results, and emits a stable JSON report. There is no
+// cloud connection and no telemetry in this package.
+import { metadataSignals } from "./metadata.js";
+import { scanFiles } from "./scan.js";
+import { capSignals, recommend, riskLevel, scoreSignals } from "./score.js";
+export { SCHEMA_VERSION } from "./report.js";
+export { parseMetadata, typosquatSignal, isVeryNew, COMMON_PACKAGE_NAMES } from "./metadata.js";
+export { scanContent, scanFiles } from "./scan.js";
+export { capSignals, scoreSignals, riskLevel, recommend, SEVERITY_WEIGHTS } from "./score.js";
+export { isTraversalAttempt, makeSafeFilter, DEFAULT_EXTRACTION_LIMITS, } from "./tar.js";
+/**
+ * Combine metadata + scanned-file signals into a finalized report.
+ *
+ * This is the single entry point the CLI uses after extracting a tarball.
+ * It is a pure function of its inputs and safe to call against untrusted data.
+ */
+export function analyzePackage(metadata, files, options = {}) {
+    const raw = [...metadataSignals(metadata), ...scanFiles(files)];
+    const signals = capSignals(raw);
+    const score = scoreSignals(signals);
+    const risk = riskLevel(signals, score);
+    return {
+        schemaVersion: "1.0",
+        package: metadata.name,
+        version: metadata.version,
+        risk,
+        score,
+        recommendation: recommend(risk),
+        signals,
+        metadata,
+        analyzedAt: new Date().toISOString(),
+        stats: {
+            filesScanned: files.length,
+            bytesScanned: files.reduce((n, f) => n + Buffer.byteLength(f.content), 0),
+            truncated: options.truncated ?? false,
+        },
+    };
+}
+/**
+ * Produce an `unknown` report when metadata fetch or extraction fails. The CLI
+ * uses this so `--json` always emits a valid object and a non-zero exit code,
+ * rather than crashing or printing a stack trace.
+ */
+export function unknownReport(packageSpec, error) {
+    return {
+        schemaVersion: "1.0",
+        package: packageSpec,
+        version: "unknown",
+        risk: "unknown",
+        score: 0,
+        recommendation: "unknown_ask_user",
+        signals: [
+            {
+                type: "analysis_error",
+                severity: "high",
+                message: error instanceof Error ? error.message : String(error),
+            },
+        ],
+        metadata: {
+            name: packageSpec,
+            version: "unknown",
+            maintainers: [],
+            dependencies: 0,
+            scripts: {},
+        },
+        analyzedAt: new Date().toISOString(),
+        stats: { filesScanned: 0, bytesScanned: 0, truncated: false },
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,6CAA6C;AAC7C,EAAE;AACF,4EAA4E;AAC5E,+EAA+E;AAC/E,2EAA2E;AAC3E,qDAAqD;AAGrD,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE5E,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAU7C,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,SAAS,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAChG,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACnD,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,SAAS,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAC9F,OAAO,EACL,kBAAkB,EAClB,cAAc,EACd,yBAAyB,GAC1B,MAAM,UAAU,CAAC;AAOlB;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAC5B,QAAyB,EACzB,KAA+C,EAC/C,UAA0B,EAAE;IAE5B,MAAM,GAAG,GAAiB,CAAC,GAAG,eAAe,CAAC,QAAQ,CAAC,EAAE,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC;IAC9E,MAAM,OAAO,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC;IAChC,MAAM,KAAK,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC;IACpC,MAAM,IAAI,GAAG,SAAS,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IACvC,OAAO;QACL,aAAa,EAAE,KAAK;QACpB,OAAO,EAAE,QAAQ,CAAC,IAAI;QACtB,OAAO,EAAE,QAAQ,CAAC,OAAO;QACzB,IAAI;QACJ,KAAK;QACL,cAAc,EAAE,SAAS,CAAC,IAAI,CAAC;QAC/B,OAAO;QACP,QAAQ;QACR,UAAU,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACpC,KAAK,EAAE;YACL,YAAY,EAAE,KAAK,CAAC,MAAM;YAC1B,YAAY,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;YACzE,SAAS,EAAE,OAAO,CAAC,SAAS,IAAI,KAAK;SACtC;KACF,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,WAAmB,EAAE,KAAc;IAC/D,OAAO;QACL,aAAa,EAAE,KAAK;QACpB,OAAO,EAAE,WAAW;QACpB,OAAO,EAAE,SAAS;QAClB,IAAI,EAAE,SAAS;QACf,KAAK,EAAE,CAAC;QACR,cAAc,EAAE,kBAAkB;QAClC,OAAO,EAAE;YACP;gBACE,IAAI,EAAE,gBAAgB;gBACtB,QAAQ,EAAE,MAAM;gBAChB,OAAO,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;aAChE;SACF;QACD,QAAQ,EAAE;YACR,IAAI,EAAE,WAAW;YACjB,OAAO,EAAE,SAAS;YAClB,WAAW,EAAE,EAAE;YACf,YAAY,EAAE,CAAC;YACf,OAAO,EAAE,EAAE;SACZ;QACD,UAAU,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACpC,KAAK,EAAE,EAAE,YAAY,EAAE,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,SAAS,EAAE,KAAK,EAAE;KAC9D,CAAC;AACJ,CAAC"}

package/dist/metadata.d.ts

@@ -0,0 +1,16 @@
+import type { PackageMetadata, RiskSignal } from "./report.js";
+/** A reasonable allowlist of well-known package names for typosquat checks. */
+export declare const COMMON_PACKAGE_NAMES: string[];
+/** Build normalized metadata from a single version manifest + the packument. */
+export declare function parseMetadata(manifest: Record<string, unknown>, packument?: Record<string, unknown>): PackageMetadata;
+/** Return a typosquat signal if the scoped/unscoped name is one edit from a common package. */
+export declare function typosquatSignal(name: string): RiskSignal | undefined;
+/** True if the package was published within the freshness threshold (default 14 days). */
+export declare function isVeryNew(publishedAt: string | undefined, days?: number): boolean;
+/**
+ * Metadata + lifecycle signals. Pure function of the manifest; never touches files.
+ * These run even when no source can be extracted, so a publish-only package still
+ * gets a meaningful report.
+ */
+export declare function metadataSignals(metadata: PackageMetadata): RiskSignal[];
+//# sourceMappingURL=metadata.d.ts.map

package/dist/metadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadata.d.ts","sourceRoot":"","sources":["../src/metadata.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAI/D,+EAA+E;AAC/E,eAAO,MAAM,oBAAoB,UAwBhC,CAAC;AAaF,gFAAgF;AAChF,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,SAAS,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACtC,eAAe,CA0BjB;AAkBD,+FAA+F;AAC/F,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAcpE;AAED,0FAA0F;AAC1F,wBAAgB,SAAS,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,EAAE,IAAI,SAAK,GAAG,OAAO,CAI7E;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,eAAe,GAAG,UAAU,EAAE,CAqCvE"}

package/dist/metadata.js

@@ -0,0 +1,150 @@
+// Normalize raw npm registry document into PackageMetadata and detect
+// metadata-level risk signals (missing fields, very new package, typosquatting).
+//
+// This module deliberately touches only the registry JSON, never the tarball,
+// so it is safe to run against untrusted manifests.
+const LIFECYCLE_SCRIPTS = ["preinstall", "install", "postinstall", "prepare"];
+/** A reasonable allowlist of well-known package names for typosquat checks. */
+export const COMMON_PACKAGE_NAMES = [
+    "typescript",
+    "react",
+    "react-dom",
+    "next",
+    "vite",
+    "webpack",
+    "rollup",
+    "esbuild",
+    "eslint",
+    "prettier",
+    "jest",
+    "vitest",
+    "express",
+    "commander",
+    "lodash",
+    "axios",
+    "chalk",
+    "npm",
+    "pnpm",
+    "yarn",
+    "create-next-app",
+    "create-vite",
+    "create-react-app",
+];
+/** Pull a `name` out of either `{name:"x"}` or `{name:"x",email:"y"}` maintainer shapes. */
+function maintainerName(entry) {
+    if (typeof entry === "string")
+        return entry;
+    if (entry && typeof entry === "object") {
+        const { name, email } = entry;
+        if (typeof name === "string" && name)
+            return name;
+        if (typeof email === "string" && email)
+            return email;
+    }
+    return undefined;
+}
+/** Build normalized metadata from a single version manifest + the packument. */
+export function parseMetadata(manifest, packument = {}) {
+    const version = String(manifest.version ?? "unknown");
+    const repositoryField = manifest.repository;
+    const repository = typeof repositoryField === "string"
+        ? repositoryField
+        : repositoryField && typeof repositoryField === "object"
+            ? String(repositoryField.url ?? "")
+            : null;
+    const maintainers = (manifest.maintainers ?? packument.maintainers ?? []);
+    const time = packument.time;
+    const dist = (manifest.dist ?? {});
+    return {
+        name: String(manifest.name ?? "unknown"),
+        version,
+        description: typeof manifest.description === "string" ? manifest.description : undefined,
+        repository: repository || null,
+        maintainers: maintainers.map(maintainerName).filter((m) => Boolean(m)),
+        publishedAt: time && time[version] ? String(time[version]) : undefined,
+        dependencies: Object.keys(manifest.dependencies ?? {}).length,
+        scripts: manifest.scripts ?? {},
+        tarball: typeof dist.tarball === "string" ? dist.tarball : undefined,
+        unpackedSize: typeof dist.unpackedSize === "number" ? dist.unpackedSize : undefined,
+        fileCount: typeof dist.fileCount === "number" ? dist.fileCount : undefined,
+        bin: manifest.bin,
+    };
+}
+/** Levenshtein edit distance, used for one-edit typosquat detection. */
+function editDistance(a, b) {
+    const d = Array.from({ length: a.length + 1 }, (_, i) => [i]);
+    for (let j = 1; j <= b.length; j++)
+        d[0][j] = j;
+    for (let i = 1; i <= a.length; i++) {
+        for (let j = 1; j <= b.length; j++) {
+            d[i][j] = Math.min(d[i - 1][j] + 1, d[i][j - 1] + 1, d[i - 1][j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+        }
+    }
+    return d[a.length][b.length];
+}
+/** Return a typosquat signal if the scoped/unscoped name is one edit from a common package. */
+export function typosquatSignal(name) {
+    const plain = name.replace(/^@[^/]+\//, "");
+    if (plain.length < 4)
+        return undefined;
+    // A well-known package name is never itself a typosquat, even if it happens
+    // to be one edit from another common package (e.g. `pnpm` vs `npm`).
+    if (COMMON_PACKAGE_NAMES.includes(plain))
+        return undefined;
+    const target = COMMON_PACKAGE_NAMES.find((item) => editDistance(plain, item) === 1);
+    return target
+        ? {
+            type: "typosquatting",
+            severity: "high",
+            message: `package name is one edit away from "${target}"`,
+        }
+        : undefined;
+}
+/** True if the package was published within the freshness threshold (default 14 days). */
+export function isVeryNew(publishedAt, days = 14) {
+    if (!publishedAt)
+        return false;
+    const then = Date.parse(publishedAt);
+    return Number.isFinite(then) && Date.now() - then <= days * 24 * 60 * 60 * 1000;
+}
+/**
+ * Metadata + lifecycle signals. Pure function of the manifest; never touches files.
+ * These run even when no source can be extracted, so a publish-only package still
+ * gets a meaningful report.
+ */
+export function metadataSignals(metadata) {
+    const signals = [];
+    for (const script of LIFECYCLE_SCRIPTS) {
+        const value = metadata.scripts[script];
+        if (value) {
+            signals.push({
+                type: "lifecycle_script",
+                severity: "high",
+                message: `${script} script detected`,
+                file: "package.json",
+                evidence: value,
+            });
+        }
+    }
+    if (!metadata.repository) {
+        signals.push({ type: "metadata_risk", severity: "medium", message: "repository is missing" });
+    }
+    if (!metadata.maintainers.length) {
+        signals.push({ type: "metadata_risk", severity: "medium", message: "maintainers are missing" });
+    }
+    if (!metadata.description) {
+        signals.push({ type: "metadata_risk", severity: "low", message: "description is missing" });
+    }
+    if (isVeryNew(metadata.publishedAt)) {
+        signals.push({
+            type: "metadata_risk",
+            severity: "medium",
+            message: "package was published very recently",
+        });
+    }
+    const typo = typosquatSignal(metadata.name);
+    if (typo)
+        signals.push(typo);
+    return signals;
+}
+//# sourceMappingURL=metadata.js.map

package/dist/metadata.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadata.js","sourceRoot":"","sources":["../src/metadata.ts"],"names":[],"mappings":"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"}

package/dist/report.d.ts

@@ -0,0 +1,52 @@
+export declare const SCHEMA_VERSION: "1.0";
+/** Overall risk band assigned to a package. */
+export type RiskLevel = "low" | "medium" | "high" | "unknown";
+/** What Tarsen advises the operator to do with the package. */
+export type Recommendation = "safe_to_run" | "ask_user" | "do_not_run_without_user_confirmation" | "unknown_ask_user";
+/** Per-signal severity. `unknown` reports (analysis errors) still use `high`. */
+export type SignalSeverity = "low" | "medium" | "high";
+/** A single risky static pattern detected in the package. */
+export interface RiskSignal {
+    type: string;
+    severity: SignalSeverity;
+    message: string;
+    /** Relative path within the extracted tarball (e.g. `index.js`). */
+    file?: string;
+    /** Human-readable location evidence, e.g. `line 42`. */
+    evidence?: string;
+}
+/** Normalized registry metadata used both for scanning and reporting. */
+export interface PackageMetadata {
+    name: string;
+    version: string;
+    description?: string;
+    repository?: string | null;
+    maintainers: string[];
+    publishedAt?: string;
+    dependencies: number;
+    scripts: Record<string, string>;
+    tarball?: string;
+    unpackedSize?: number;
+    fileCount?: number;
+    bin?: string | Record<string, string>;
+}
+/** Stats about the scan itself, useful for interpreting truncation. */
+export interface ScanStats {
+    filesScanned: number;
+    bytesScanned: number;
+    truncated: boolean;
+}
+/** The full report emitted by Tarsen. Serialized verbatim in `--json` mode. */
+export interface RiskReport {
+    schemaVersion: typeof SCHEMA_VERSION;
+    package: string;
+    version: string;
+    risk: RiskLevel;
+    score: number;
+    recommendation: Recommendation;
+    signals: RiskSignal[];
+    metadata: PackageMetadata;
+    analyzedAt: string;
+    stats: ScanStats;
+}
+//# sourceMappingURL=report.d.ts.map

package/dist/report.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"report.d.ts","sourceRoot":"","sources":["../src/report.ts"],"names":[],"mappings":"AAMA,eAAO,MAAM,cAAc,EAAG,KAAc,CAAC;AAE7C,+CAA+C;AAC/C,MAAM,MAAM,SAAS,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,SAAS,CAAC;AAE9D,+DAA+D;AAC/D,MAAM,MAAM,cAAc,GACtB,aAAa,GACb,UAAU,GACV,sCAAsC,GACtC,kBAAkB,CAAC;AAEvB,iFAAiF;AACjF,MAAM,MAAM,cAAc,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;AAEvD,6DAA6D;AAC7D,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,cAAc,CAAC;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,oEAAoE;IACpE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,wDAAwD;IACxD,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,yEAAyE;AACzE,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACvC;AAED,uEAAuE;AACvE,MAAM,WAAW,SAAS;IACxB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,+EAA+E;AAC/E,MAAM,WAAW,UAAU;IACzB,aAAa,EAAE,OAAO,cAAc,CAAC;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,SAAS,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,cAAc,EAAE,cAAc,CAAC;IAC/B,OAAO,EAAE,UAAU,EAAE,CAAC;IACtB,QAAQ,EAAE,eAAe,CAAC;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,SAAS,CAAC;CAClB"}

package/dist/report.js

@@ -0,0 +1,7 @@
+// Risk report types and JSON schema contract.
+//
+// These types are the machine-readable contract emitted by `tarsen check --json`
+// and consumed by `tarsen run` and any downstream tooling. They are stable and
+// versioned via `schemaVersion`. See docs/report.schema.json for the JSON Schema.
+export const SCHEMA_VERSION = "1.0";
+//# sourceMappingURL=report.js.map

package/dist/report.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"report.js","sourceRoot":"","sources":["../src/report.ts"],"names":[],"mappings":"AAAA,8CAA8C;AAC9C,EAAE;AACF,iFAAiF;AACjF,+EAA+E;AAC/E,kFAAkF;AAElF,MAAM,CAAC,MAAM,cAAc,GAAG,KAAc,CAAC"}

package/dist/scan.d.ts

@@ -0,0 +1,12 @@
+import type { RiskSignal } from "./report.js";
+/**
+ * Scan a single file's content. Pure & deterministic given the same input.
+ * Returns at most one signal per rule per file (deduplicated by type).
+ */
+export declare function scanContent(content: string, file: string): RiskSignal[];
+/** Scan every provided file (already read off disk) and flatten the signals. */
+export declare function scanFiles(files: Array<{
+    path: string;
+    content: string;
+}>): RiskSignal[];
+//# sourceMappingURL=scan.d.ts.map

package/dist/scan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scan.d.ts","sourceRoot":"","sources":["../src/scan.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,UAAU,EAAkB,MAAM,aAAa,CAAC;AAgG9D;;;GAGG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,UAAU,EAAE,CA2BvE;AAED,gFAAgF;AAChF,wBAAgB,SAAS,CAAC,KAAK,EAAE,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,GAAG,UAAU,EAAE,CAIvF"}

package/dist/scan.js

@@ -0,0 +1,128 @@
+// Static file scanning: pure functions that turn file contents into RiskSignals.
+//
+// Safety note: these functions only ever inspect strings. They never execute,
+// import, or evaluate package code, so scanning untrusted tarballs is safe.
+// Lifecycle + install-script hooks are handled in metadata.ts (from package.json).
+// The rules here scan source files for the categories in the detection scope.
+const SCAN_RULES = [
+    {
+        type: "dangerous_execution",
+        severity: "high",
+        message: "child process execution detected",
+        pattern: /(?:node:)?child_process|\b(?:execSync|spawnSync|execFileSync|execFile|fork)\s*\(|\b(?:exec|spawn)\s*\(/,
+    },
+    {
+        type: "dynamic_execution",
+        severity: "high",
+        message: "dynamic code execution detected",
+        pattern: /\beval\s*\(|new\s+Function\s*\(|\bFunction\s*\(/,
+    },
+    {
+        type: "filesystem_write",
+        severity: "medium",
+        message: "filesystem write or deletion detected",
+        pattern: /(?:\bfs\.|node:fs)[\s\S]{0,60}\b(?:writeFile|writeFileSync|appendFile|rm|rmSync|unlink|unlinkSync|rmdir|chmod|chown|rename|mkdir|copyFile)\b/,
+    },
+    {
+        type: "filesystem_read",
+        severity: "low",
+        message: "filesystem read or homedir access detected",
+        pattern: /(?:\bfs\.|node:fs)[\s\S]{0,60}\b(?:readFile|readFileSync|readdir|readdirSync|createReadStream|createWriteStream)\b|\bos\.homedir\s*\(/,
+    },
+    {
+        type: "network_access",
+        severity: "medium",
+        message: "network access detected",
+        pattern: /\bfetch\s*\(|\bhttps?\.(?:request|get)\s*\(|\baxios\b|XMLHttpRequest|new\s+WebSocket/,
+    },
+    {
+        type: "shell_command",
+        severity: "high",
+        message: "shell command construction detected",
+        pattern: /\bshell\s*:\s*true|\/bin\/(?:ba|z)?sh|cmd\.exe|powershell(?:\.exe)?/i,
+    },
+];
+/** Return the 1-based line number of the first match for a global regex, else undefined. */
+function lineOf(content, pattern) {
+    const match = content.match(pattern);
+    if (!match || match.index === undefined)
+        return undefined;
+    return `line ${content.slice(0, match.index).split("\n").length}`;
+}
+/** Sensitive env access: NODE_ENV/DEBUG/CI are common and low risk; anything else is high. */
+function environmentSignals(content, file) {
+    const out = [];
+    if (/process\.env(?:\[[^\]]+\]|\.(?!NODE_ENV\b|DEBUG\b|CI\b)[A-Za-z_$][\w$]*)/.test(content)) {
+        out.push({
+            type: "environment_access",
+            severity: "high",
+            message: "potentially sensitive environment access detected",
+            file,
+            evidence: lineOf(content, /process\.env/),
+        });
+    }
+    else if (/process\.env\.(?:NODE_ENV|DEBUG|CI)\b/.test(content)) {
+        out.push({
+            type: "environment_access",
+            severity: "low",
+            message: "runtime environment mode access detected",
+            file,
+            evidence: lineOf(content, /process\.env/),
+        });
+    }
+    return out;
+}
+/** Obfuscation heuristics: very long lines and base64-like blobs. */
+function obfuscationSignals(content, file) {
+    const lines = content.split("\n");
+    if (lines.some((line) => line.length > 2000) || /[A-Za-z0-9+/]{1000,}={0,2}/.test(content)) {
+        return [
+            {
+                type: "obfuscation",
+                severity: "medium",
+                message: "minified, very long, or encoded content detected",
+                file,
+            },
+        ];
+    }
+    return [];
+}
+/**
+ * Scan a single file's content. Pure & deterministic given the same input.
+ * Returns at most one signal per rule per file (deduplicated by type).
+ */
+export function scanContent(content, file) {
+    const signals = [];
+    const seen = new Set();
+    const push = (signal) => {
+        const key = `${signal.type}:${signal.file ?? ""}`;
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        signals.push(signal);
+    };
+    for (const rule of SCAN_RULES) {
+        if (rule.pattern.test(content)) {
+            push({
+                type: rule.type,
+                severity: rule.severity,
+                message: rule.message,
+                file,
+                evidence: lineOf(content, rule.pattern),
+            });
+        }
+    }
+    for (const signal of environmentSignals(content, file))
+        push(signal);
+    for (const signal of obfuscationSignals(content, file))
+        push(signal);
+    return signals;
+}
+/** Scan every provided file (already read off disk) and flatten the signals. */
+export function scanFiles(files) {
+    const out = [];
+    for (const { path, content } of files)
+        out.push(...scanContent(content, path));
+    return out;
+}
+//# sourceMappingURL=scan.js.map

package/dist/scan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scan.js","sourceRoot":"","sources":["../src/scan.ts"],"names":[],"mappings":"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"}

package/dist/score.d.ts

@@ -0,0 +1,12 @@
+import type { Recommendation, RiskLevel, RiskSignal, SignalSeverity } from "./report.js";
+/** Per-severity weight when summing the strongest signal of each type. */
+export declare const SEVERITY_WEIGHTS: Record<SignalSeverity, number>;
+/** Cap duplicate signal types so a chatty detector cannot dominate the report. */
+export declare function capSignals(signals: RiskSignal[], limit?: number): RiskSignal[];
+/** 0-100 score: sum the strongest severity per signal type, capped at 100. */
+export declare function scoreSignals(signals: RiskSignal[]): number;
+/** Map a score + signal distribution to a risk band. */
+export declare function riskLevel(signals: RiskSignal[], score: number): RiskLevel;
+/** Map a risk band to a recommendation. `unknown` is handled by the caller. */
+export declare function recommend(risk: RiskLevel): Recommendation;
+//# sourceMappingURL=score.d.ts.map

package/dist/score.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"score.d.ts","sourceRoot":"","sources":["../src/score.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAEzF,0EAA0E;AAC1E,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,cAAc,EAAE,MAAM,CAI3D,CAAC;AAIF,kFAAkF;AAClF,wBAAgB,UAAU,CAAC,OAAO,EAAE,UAAU,EAAE,EAAE,KAAK,SAAM,GAAG,UAAU,EAAE,CAa3E;AAED,8EAA8E;AAC9E,wBAAgB,YAAY,CAAC,OAAO,EAAE,UAAU,EAAE,GAAG,MAAM,CAY1D;AAED,wDAAwD;AACxD,wBAAgB,SAAS,CAAC,OAAO,EAAE,UAAU,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,SAAS,CAMzE;AAED,+EAA+E;AAC/E,wBAAgB,SAAS,CAAC,IAAI,EAAE,SAAS,GAAG,cAAc,CAWzD"}

package/dist/score.js

@@ -0,0 +1,63 @@
+// Risk scoring and recommendation logic.
+//
+// Pure function of the signal list. Kept separate so it can be unit tested
+// without touching the network or filesystem.
+/** Per-severity weight when summing the strongest signal of each type. */
+export const SEVERITY_WEIGHTS = {
+    high: 35,
+    medium: 12,
+    low: 2,
+};
+const SEVERITY_RANK = { low: 1, medium: 2, high: 3 };
+/** Cap duplicate signal types so a chatty detector cannot dominate the report. */
+export function capSignals(signals, limit = 100) {
+    const seen = new Set();
+    const counts = new Map();
+    const out = [];
+    for (const signal of signals) {
+        const key = `${signal.type}:${signal.file ?? ""}`;
+        if (seen.has(key) || (counts.get(signal.type) ?? 0) >= 5)
+            continue;
+        seen.add(key);
+        counts.set(signal.type, (counts.get(signal.type) ?? 0) + 1);
+        out.push(signal);
+        if (out.length >= limit)
+            break;
+    }
+    return out;
+}
+/** 0-100 score: sum the strongest severity per signal type, capped at 100. */
+export function scoreSignals(signals) {
+    const strongestByType = new Map();
+    for (const signal of signals) {
+        const current = strongestByType.get(signal.type);
+        if (!current || SEVERITY_RANK[signal.severity] > SEVERITY_RANK[current]) {
+            strongestByType.set(signal.type, signal.severity);
+        }
+    }
+    return Math.min(100, [...strongestByType.values()].reduce((sum, severity) => sum + SEVERITY_WEIGHTS[severity], 0));
+}
+/** Map a score + signal distribution to a risk band. */
+export function riskLevel(signals, score) {
+    const hasHigh = signals.some((signal) => signal.severity === "high");
+    const mediumCount = signals.filter((signal) => signal.severity === "medium").length;
+    if (hasHigh)
+        return "high";
+    if (mediumCount > 0 || score >= 10)
+        return "medium";
+    return "low";
+}
+/** Map a risk band to a recommendation. `unknown` is handled by the caller. */
+export function recommend(risk) {
+    switch (risk) {
+        case "high":
+            return "do_not_run_without_user_confirmation";
+        case "medium":
+            return "ask_user";
+        case "low":
+            return "safe_to_run";
+        default:
+            return "unknown_ask_user";
+    }
+}
+//# sourceMappingURL=score.js.map

package/dist/score.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"score.js","sourceRoot":"","sources":["../src/score.ts"],"names":[],"mappings":"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"}

package/dist/tar.d.ts

@@ -0,0 +1,28 @@
+/** Reject a tarball entry whose resolved path would escape the destination. */
+export declare function isTraversalAttempt(entryPath: string, dest: string): boolean;
+/** Entry filter shared with `tar.x`. Returns `true` to KEEP an entry. */
+export interface ExtractionLimits {
+    maxEntries: number;
+}
+/**
+ * Build a `tar.x` filter. Counts entries and drops anything that is a link,
+ * escapes the destination, or would exceed the entry budget.
+ *
+ * `tar` passes each entry header as `header` with a `type` flag:
+ *   0/""  file, 5 directory, 2 symlink, 1 hardlink, etc.
+ */
+export declare function makeSafeFilter(dest: string, limits: ExtractionLimits): (_path: string, entry: {
+    type?: string;
+}) => boolean;
+/** Walked file shape used by the analyzer. */
+export interface ExtractedFile {
+    path: string;
+    content: string;
+}
+export interface WalkResult {
+    files: ExtractedFile[];
+    truncated: boolean;
+}
+/** Conservative defaults mirroring the CLI's own pipeline. */
+export declare const DEFAULT_EXTRACTION_LIMITS: ExtractionLimits;
+//# sourceMappingURL=tar.d.ts.map

package/dist/tar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tar.d.ts","sourceRoot":"","sources":["../src/tar.ts"],"names":[],"mappings":"AAYA,+EAA+E;AAC/E,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAQ3E;AAED,yEAAyE;AACzE,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,gBAAgB,IAE3D,OAAO,MAAM,EAAE,OAAO;IAAE,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,aAQhD;AAED,8CAA8C;AAC9C,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,aAAa,EAAE,CAAC;IACvB,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,8DAA8D;AAC9D,eAAO,MAAM,yBAAyB,EAAE,gBAAyC,CAAC"}

package/dist/tar.js

@@ -0,0 +1,45 @@
+// Safe tarball extraction helpers.
+//
+// These are the hard safety guarantees Tarsen makes during analysis:
+//   - tarballs are extracted ONLY into a caller-provided temporary directory
+//   - path traversal (entries escaping via `../` or absolute paths) is rejected
+//   - symlinks and hardlinks are dropped
+//   - entry count and per-archive byte budgets are enforced
+//
+// This module never executes package code and never runs install scripts.
+import { isAbsolute, normalize, relative, sep } from "node:path";
+/** Reject a tarball entry whose resolved path would escape the destination. */
+export function isTraversalAttempt(entryPath, dest) {
+    const cleaned = normalize(entryPath);
+    if (isAbsolute(cleaned))
+        return true;
+    if (cleaned.startsWith("..") || cleaned.startsWith(`..${sep}`))
+        return true;
+    // Belt-and-braces: resolve relative to dest and confirm it stays inside.
+    const resolved = normalize(`${dest}${sep}${cleaned}`);
+    const rel = relative(dest, resolved);
+    return rel.startsWith("..") || isAbsolute(rel);
+}
+/**
+ * Build a `tar.x` filter. Counts entries and drops anything that is a link,
+ * escapes the destination, or would exceed the entry budget.
+ *
+ * `tar` passes each entry header as `header` with a `type` flag:
+ *   0/""  file, 5 directory, 2 symlink, 1 hardlink, etc.
+ */
+export function makeSafeFilter(dest, limits) {
+    let entries = 0;
+    return (_path, entry) => {
+        entries += 1;
+        if (entries > limits.maxEntries)
+            return false;
+        const type = entry.type ?? "";
+        // Drop all link types (symlink, hardlink, character/block device).
+        if (type === "SymbolicLink" || type === "Link" || type === "2" || type === "1")
+            return false;
+        return !isTraversalAttempt(_path, dest);
+    };
+}
+/** Conservative defaults mirroring the CLI's own pipeline. */
+export const DEFAULT_EXTRACTION_LIMITS = { maxEntries: 10_000 };
+//# sourceMappingURL=tar.js.map

package/dist/tar.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tar.js","sourceRoot":"","sources":["../src/tar.ts"],"names":[],"mappings":"AAAA,mCAAmC;AACnC,EAAE;AACF,qEAAqE;AACrE,6EAA6E;AAC7E,gFAAgF;AAChF,yCAAyC;AACzC,4DAA4D;AAC5D,EAAE;AACF,0EAA0E;AAE1E,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AAEjE,+EAA+E;AAC/E,MAAM,UAAU,kBAAkB,CAAC,SAAiB,EAAE,IAAY;IAChE,MAAM,OAAO,GAAG,SAAS,CAAC,SAAS,CAAC,CAAC;IACrC,IAAI,UAAU,CAAC,OAAO,CAAC;QAAE,OAAO,IAAI,CAAC;IACrC,IAAI,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,OAAO,CAAC,UAAU,CAAC,KAAK,GAAG,EAAE,CAAC;QAAE,OAAO,IAAI,CAAC;IAC5E,yEAAyE;IACzE,MAAM,QAAQ,GAAG,SAAS,CAAC,GAAG,IAAI,GAAG,GAAG,GAAG,OAAO,EAAE,CAAC,CAAC;IACtD,MAAM,GAAG,GAAG,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IACrC,OAAO,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,UAAU,CAAC,GAAG,CAAC,CAAC;AACjD,CAAC;AAOD;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAC,IAAY,EAAE,MAAwB;IACnE,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,OAAO,CAAC,KAAa,EAAE,KAAwB,EAAE,EAAE;QACjD,OAAO,IAAI,CAAC,CAAC;QACb,IAAI,OAAO,GAAG,MAAM,CAAC,UAAU;YAAE,OAAO,KAAK,CAAC;QAC9C,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,IAAI,EAAE,CAAC;QAC9B,mEAAmE;QACnE,IAAI,IAAI,KAAK,cAAc,IAAI,IAAI,KAAK,MAAM,IAAI,IAAI,KAAK,GAAG,IAAI,IAAI,KAAK,GAAG;YAAE,OAAO,KAAK,CAAC;QAC7F,OAAO,CAAC,kBAAkB,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IAC1C,CAAC,CAAC;AACJ,CAAC;AAaD,8DAA8D;AAC9D,MAAM,CAAC,MAAM,yBAAyB,GAAqB,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC"}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "tarsen-core",
+  "version": "0.1.0",
+  "description": "Static npm package risk analysis for Tarsen.",
+  "homepage": "https://github.com/pandapor/tarsen#readme",
+  "repository": { "type": "git", "url": "git+https://github.com/pandapor/tarsen.git", "directory": "packages/core" },
+  "publishConfig": { "access": "public" },
+  "description": "Static npm package analysis, risk scoring, and safe tarball helpers for Tarsen. No cloud, no telemetry.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "package.json",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run"
+  },
+  "license": "Apache-2.0",
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.9.0",
+    "vitest": "^3.2.0"
+  }
+}