@inner-security/scan 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Inner Security
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,91 @@
+# @inner-security/scan — Inner CLI
+
+A **thin client** of Inner's Verdict API:
+
+- **`npx @inner-security/scan`** — instant dependency scan. Reads your
+  manifest/lockfile, calls the Verdict API, and prints the protected tally
+  (`N packages scanned, K allowed, M blocked`).
+- **`inner init`** — auto-configures the **6 package managers**
+  (npm / pnpm / yarn / pip / poetry / uv) to resolve through the Inner registry proxy.
+
+All detection, scoring, and auth live **server-side**. This package ships no
+detection logic — it only consumes the Verdict API. Real usage is **gated by an
+Inner org API key** (the Datadog model): without a key the scan resolves against
+the public service surface only.
+
+## Install / run
+
+```bash
+# Instant scan (cwd) — no install needed
+npx @inner-security/scan
+npx @inner-security/scan --dir ./my-project --json
+
+# Or install globally for the `inner` umbrella CLI
+npm i -g @inner-security/scan
+inner scan
+inner init
+inner init --proxy https://proxy.example.com --managers npm,pnpm,pip
+```
+
+Bins exposed: `scan` / `inner-scan` (the scan path) and `inner` (umbrella CLI
+with `scan` + `init`). Requires **Node >= 20**.
+
+## API key
+
+Real verdicts are gated by your Inner org API key. Provide it via env:
+
+```bash
+export INNER_API_KEY=ik_...
+npx @inner-security/scan
+```
+
+## Configurable endpoints
+
+Both hosts are env/flag-configurable and **default to dev values today**. Once
+Inner's production hosts are live (PROD-WIRING 3/4/12) these defaults point at
+prod; until then, set them explicitly for real verdicts:
+
+| What | Flag | Env | Default (dev) |
+|------|------|-----|---------------|
+| Verdict API base | `--api-url` | `INNER_API_URL` | `http://localhost:8787` (the local `verdict-api-mock`) |
+| Registry proxy base | `--proxy` (init) | `INNER_PROXY_URL` | `https://proxy.inner.dev` (placeholder) |
+| Org API key | — | `INNER_API_KEY` | (none) |
+
+> The dev defaults are intentional: the published client is name-claimed now and
+> flips to prod hosts once E1's Verdict API + proxy are wired live.
+
+## Verdict resolution
+
+- Items are sent to `POST /v1/verdict` (`VerdictRequest`).
+- The response carries `VerdictEnvelope | PendingResponse`.
+- `PENDING` items are polled at `GET /v1/verdict/{job_id}` with backoff.
+- Every requested package is bucketed by its envelope `action`
+  (`ALLOW` / `BLOCK` / `REVIEW`); unresolved → `unknown`.
+
+## Fail-open cache
+
+Resolved verdicts are written to `.inner-cache/` (last-known-good). If the API is
+unreachable, the scan falls back to that cache: **cached-ALLOW packages still
+resolve**, everything else surfaces as `unknown`. The run is marked *degraded*
+rather than failing outright. Pass `--no-cache` to disable.
+
+## Exit codes
+
+`0` clean · `1` one or more BLOCKED packages · `2` usage/error.
+
+## Package-manager config written by `inner init`
+
+| Manager | File | Key |
+|---------|------|-----|
+| npm | `.npmrc` | `registry=<proxy>/npm/` |
+| pnpm | `.npmrc` | `registry=<proxy>/npm/` |
+| yarn | `.yarnrc.yml` | `npmRegistryServer: "<proxy>/npm/"` |
+| pip | `pip.conf` | `[global] index-url = <proxy>/pypi/simple/` |
+| poetry | `poetry.toml` | `[[tool.poetry.source]] url = <proxy>/pypi/simple/` |
+| uv | `uv.toml` | `[[index]] url = <proxy>/pypi/simple/` |
+
+`inner init` is idempotent and preserves unrelated config lines.
+
+## License
+
+MIT © 2026 Inner Security. See [LICENSE](./LICENSE).

package/bundle/index.d.ts

@@ -0,0 +1,185 @@
+import { VerdictEnvelope, VerdictRequestItem, Ecosystem } from '@inner/contracts';
+import { ScanClientResult, ResolvedItem } from '@inner/verdict-client';
+export { DEFAULT_API_URL, ResolvedItem, ScanClientResult } from '@inner/verdict-client';
+
+/**
+ * Default registry proxy base. PLACEHOLDER — the real Inner proxy host (owned by
+ * E1) must be wired in via INNER_PROXY_URL or `inner init --proxy <url>`.
+ */
+declare const DEFAULT_PROXY_URL = "https://proxy.inner.dev";
+interface ResolvedConfig {
+    /** Verdict API base URL (no trailing slash). */
+    apiUrl: string;
+    /** Registry proxy base URL (no trailing slash). */
+    proxyUrl: string;
+    /** true when apiUrl came from a default (prod URL not wired in). */
+    apiUrlIsDefault: boolean;
+    /** true when proxyUrl came from a default (prod proxy not wired in). */
+    proxyUrlIsDefault: boolean;
+}
+/**
+ * Resolve the Verdict API base URL. Precedence: explicit flag value >
+ * INNER_API_URL env > DEFAULT_API_URL.
+ */
+declare function resolveApiUrl(flagValue?: string): {
+    url: string;
+    isDefault: boolean;
+};
+/**
+ * Resolve the registry proxy base URL. Precedence: explicit flag value >
+ * INNER_PROXY_URL env > DEFAULT_PROXY_URL.
+ */
+declare function resolveProxyUrl(flagValue?: string): {
+    url: string;
+    isDefault: boolean;
+};
+declare function resolveConfig(opts?: {
+    apiUrl?: string;
+    proxyUrl?: string;
+}): ResolvedConfig;
+
+declare const CACHE_DIR_NAME = ".inner-cache";
+/**
+ * Max age (ms) a cached entry is trusted as last-known-good when the envelope
+ * carries no usable `expires_at`. Fail-open is a stop-gap for a transient API
+ * outage, not a license to trust an arbitrarily old verdict. 7 days.
+ */
+declare const CACHE_MAX_AGE_MS: number;
+declare function cacheKey(item: {
+    ecosystem: string;
+    name: string;
+    version: string;
+}): string;
+interface CacheEntry {
+    key: string;
+    cached_at: string;
+    envelope: VerdictEnvelope;
+}
+declare class VerdictCache {
+    readonly dir: string;
+    constructor(rootDir?: string);
+    private pathFor;
+    /** Persist a resolved envelope as last-known-good. */
+    put(item: VerdictRequestItem, envelope: VerdictEnvelope): void;
+    /**
+     * Read a last-known-good envelope that is safe to TRUST for resolution, or
+     * undefined on miss/parse error/untrusted entry.
+     *
+     * The cache is fail-OPEN: only a cached ALLOW that has not gone stale is a
+     * usable verdict. A cached BLOCK/REVIEW (or anything non-ALLOW), or an
+     * expired entry, is treated as a miss so the caller surfaces UNKNOWN and the
+     * operator decides — never a silent allow of a now-known-bad package.
+     */
+    get(item: {
+        ecosystem: string;
+        name: string;
+        version: string;
+    }, now?: Date): VerdictEnvelope | undefined;
+}
+
+interface ManifestScanResult {
+    items: VerdictRequestItem[];
+    /** Files we actually read (for the scan summary / debugging). */
+    sources: string[];
+    /** Ecosystems detected in the project root. */
+    ecosystems: Ecosystem[];
+    /**
+     * Lines/entries the parser could not turn into a concrete (name, version) and
+     * skipped rather than guess (range-only specs, "*"/"latest", git/url deps, …).
+     * Surfaced so a skipped package is never silently treated as unprotected.
+     */
+    warnings: string[];
+    /** Count of skipped/unparseable entries (== warnings.length). */
+    skipped: number;
+}
+/**
+ * Scan a project root. For each ecosystem we prefer the most exact source
+ * available (lockfile > manifest) and stop at the first that yields items.
+ */
+declare function scanManifests(root?: string): ManifestScanResult;
+
+interface ClientOptions {
+    apiUrl: string;
+    /** Per-request timeout in ms. */
+    timeoutMs?: number;
+    /** Max poll attempts for a single PENDING job. */
+    maxPollAttempts?: number;
+    /** Project root used to locate / write `.inner-cache/`. */
+    cacheRoot?: string;
+    /** Disable disk cache entirely (used in tests). */
+    noCache?: boolean;
+}
+declare class VerdictClient {
+    private readonly client;
+    constructor(opts: ClientOptions);
+    /**
+     * Resolve a batch of items. Returns one ResolvedItem per requested item.
+     * On total API failure, falls back to the fail-open cache for every item.
+     */
+    resolve(items: VerdictRequestItem[]): Promise<ScanClientResult>;
+}
+
+interface ScanTally {
+    scanned: number;
+    allowed: number;
+    blocked: number;
+    review: number;
+    unknown: number;
+    fromCache: number;
+}
+interface ScanResult {
+    tally: ScanTally;
+    resolved: ResolvedItem[];
+    sources: string[];
+    ecosystems: string[];
+    degraded: boolean;
+    apiUrl: string;
+    apiUrlIsDefault: boolean;
+    /** Manifest entries the parser couldn't resolve to (name, version) and skipped. */
+    skipped: number;
+    /** One human-readable line per skipped entry (why it was skipped). */
+    warnings: string[];
+}
+declare function aggregate(resolved: ResolvedItem[]): ScanTally;
+interface ScanOptions {
+    root?: string;
+    apiUrl?: string;
+    noCache?: boolean;
+    /** Pre-computed manifest result (used in tests to bypass disk). */
+    manifest?: ManifestScanResult;
+}
+declare function scan(opts?: ScanOptions): Promise<ScanResult>;
+/** Human-readable one-line tally, e.g. the acceptance string. */
+declare function formatTally(t: ScanTally): string;
+
+type PackageManager = 'npm' | 'pnpm' | 'yarn' | 'pip' | 'poetry' | 'uv';
+declare const ALL_PACKAGE_MANAGERS: PackageManager[];
+interface ConfiguredManager {
+    manager: PackageManager;
+    file: string;
+    registry: string;
+    /** 'created' | 'updated' (existing file edited). */
+    outcome: 'created' | 'updated';
+}
+interface InitOptions {
+    root?: string;
+    proxyUrl?: string;
+    /** Only configure these managers (default: all 6). */
+    managers?: PackageManager[];
+}
+interface InitResult {
+    configured: ConfiguredManager[];
+    proxyUrl: string;
+    proxyUrlIsDefault: boolean;
+}
+declare function init(opts?: InitOptions): InitResult;
+
+interface ParsedArgs {
+    _: string[];
+    flags: Record<string, string | boolean>;
+}
+declare function parseArgs(argv: string[]): ParsedArgs;
+declare function flagString(flags: Record<string, string | boolean>, key: string): string | undefined;
+declare function flagBool(flags: Record<string, string | boolean>, key: string): boolean;
+
+export { ALL_PACKAGE_MANAGERS, CACHE_DIR_NAME, CACHE_MAX_AGE_MS, type CacheEntry, type ClientOptions, type ConfiguredManager, DEFAULT_PROXY_URL, type InitOptions, type InitResult, type ManifestScanResult, type PackageManager, type ParsedArgs, type ResolvedConfig, type ScanOptions, type ScanResult, type ScanTally, VerdictCache, VerdictClient, aggregate, cacheKey, flagBool, flagString, formatTally, init, parseArgs, resolveApiUrl, resolveConfig, resolveProxyUrl, scan, scanManifests };