@starkscan/cli 0.1.0-alpha.2 → 0.1.0

package/README.md

@@ -1,73 +1,113 @@
 # @starkscan/cli
 
-npm/npx launcher for the prebuilt Starkscan CLI.
+Command-line Starkscan client for status checks, explorer reads, local exports,
+and agent setup.
+
+Status: public `0.1.0` stable release. The npm `latest` tag points to the real
+CLI package. Use the untagged install for normal setup and pin `0.1.0` for
+unattended agents or production services that need reproducible installs.
 
 ## Install
 
 ```bash
-npm install -g @starkscan/cli@alpha
+npm install -g @starkscan/cli
 starkscan doctor
 ```
 
-One-off agent run:
+One-off agent setup without a global install:
 
 ```bash
-npx @starkscan/cli@alpha doctor
+npx -y @starkscan/cli init --agent --output-format json
 ```
 
-For unattended agents or production services, pin a smoked exact version instead
-of floating on `@alpha`.
+Exact pin for unattended services:
 
-## Trust status
+```bash
+npx -y @starkscan/cli@0.1.0 init --agent --output-format json
+```
 
-- npm: <https://www.npmjs.com/package/@starkscan/cli>
-- public trust docs: <https://starkscan.co/docs/build/package-trust>
-- machine-readable matrix: <https://starkscan.co/public-client-surface-matrix.json>
-- Socket signal: <https://socket.dev/npm/package/@starkscan/cli>
+The `@beta` tag remains a prerelease channel only. Do not use it for unattended
+production services unless a maintainer explicitly asks you to test a
+prerelease.
+
+## First commands
+
+```bash
+export STARKSCAN_API_KEY="<store this in your shell or agent secret store>"
+export STARKSCAN_CHAIN="SN_MAIN"
+# Optional: only set this for preview or self-hosted hosts.
+# export STARKSCAN_BASE_URL="https://preview.example.com/api"
+
+starkscan status
+starkscan block 8279910
+starkscan tx 0x1234abcd
+starkscan search 0x1234abcd
+```
 
-Socket is an external package-risk signal, not a formal Starkscan security
-certificate. Starkscan package promotion also requires bundled-artifact checksum
-verification, manual passkey or Trusted Publishing/OIDC publish control, and
-the launch gates documented at the public package trust page. The canonical
-source repository is private, so public package trust links intentionally point
-to Starkscan docs instead of GitHub.
+The CLI defaults to `https://api.starkscan.co`, sends `X-Starkscan-Api-Key`,
+and uses the same REST API contract as the SDK. MCP uses a separate
+transport: `POST https://api.starkscan.co/mcp` on the API domain, or
+`POST {appBaseUrl}/api/mcp` on app-origin deployments.
 
-The wrapper uses bundled native artifacts when they are present in the published package, verifies downloaded or bundled archives against checksums in the release manifest, rejects malformed archives, caches the native `starkscan` binary, and forwards all arguments to it. It does not require a Rust toolchain or repository access.
+## Why use it
 
-MCP client setup uses the same package. `print-config` emits machine-readable
-Codex and Claude Code snippets with environment-variable placeholders, not
-secret values. `start` is the stable alias for serving the remote stdio bridge:
+- No Rust toolchain or private repository access required.
+- Prebuilt native `starkscan` binaries are bundled in the npm package.
+- Bundled or downloaded native archives are verified against manifest checksums
+  before execution.
+- `--output-format json` keeps stdout parseable for agents and CI.
+- Stable exit classes make automation predictable: success, usage, auth,
+  rate-limit, timeout, and not-found errors are distinct.
+- MCP helpers print ready-to-paste Codex, Claude Code, Cursor, Claude Desktop,
+  and Cline configs with environment placeholders, not secret values.
+
+## Agent setup
 
 ```bash
-npx -y @starkscan/cli@alpha mcp print-config --transport remote
-npx -y @starkscan/cli@alpha mcp start --transport remote
+npx -y @starkscan/cli@0.1.0 init --agent --output-format json
+npx -y @starkscan/cli@0.1.0 mcp print-config --transport remote
+npx -y @starkscan/cli@0.1.0 mcp start --transport remote
 ```
 
-## Environment
+`print-config` emits machine-readable snippets. Keep `STARKSCAN_API_KEY` in the
+host shell, CI secret store, or MCP client secret store.
+
+## Launcher inspection
+
+Agents can inspect the launcher decision without executing the native binary:
 
 ```bash
-# Use the URL prefix that directly serves `/v1/...`.
-# Some public hosts may expose the API under `/api`; do not include `/v1`.
-export STARKSCAN_BASE_URL="https://REPLACE_WITH_STARKSCAN_API_HOST"
-export STARKSCAN_API_KEY="mzk_test_your_key_here"
-export STARKSCAN_CHAIN="SN_MAIN"
+npx -y @starkscan/cli@0.1.0 --launcher-json
 ```
 
-`STARKSCAN_*` is the public CLI environment contract. The launcher still accepts
-the old internal variable names as hidden compatibility aliases during the beta
-cutover. The CLI sends `X-Starkscan-Api-Key` to the hosted API.
+The JSON includes the package version, resolved binary path, release tag,
+source (`bundled`, `download`, `bin-path`, or `unknown` for legacy caches),
+cache-hit status, and verification status.
 
-## Release binding
+## Trust and safety
 
-By default, the package resolves to bundled artifacts under `artifacts/v<package-version>` when published with native binaries included. Maintainers can override the release source for tests or emergency rollback:
+- npm package: <https://www.npmjs.com/package/@starkscan/cli>
+- CLI docs: <https://starkscan.co/docs/ai/agent-cli>
+- API key setup: <https://starkscan.co/api-key>
+- Package trust: <https://starkscan.co/docs/build/package-trust>
+- Machine-readable launch matrix: <https://starkscan.co/public-client-surface-matrix.json>
+- Socket signal: <https://socket.dev/npm/package/@starkscan/cli>
+
+Socket is an external package-risk signal, not a Starkscan security certificate.
+The public trust source is Starkscan docs because the canonical engineering
+repository is private. Package promotion also requires checked release scripts,
+native artifact checksum verification, npm Trusted Publishing/OIDC for CI
+publishes, and live smoke proof against the hosted API.
 
-- `STARKSCAN_CLI_RELEASE_TAG`: release tag, or `latest`
-- `STARKSCAN_CLI_BUNDLED_ARTIFACT_DIR`: maintainer/test override for the bundled artifact root. Use an absolute path in CI, or a cwd-relative path locally, pointing to a root that contains `artifacts/v<release-tag>/starkscan-cli-manifest.json` and matching platform archives. Example: `STARKSCAN_CLI_BUNDLED_ARTIFACT_DIR=/tmp/starkscan-cli-artifacts npx @starkscan/cli@alpha doctor`
-- `STARKSCAN_CLI_RELEASE_BASE_URL`: maintainer/test release base URL override. Published public packages use bundled artifacts first; beta clients should not set this.
-- `STARKSCAN_CLI_CACHE_DIR`: cache root for downloaded native binaries
-- `STARKSCAN_CLI_BIN_PATH`: use an existing local `starkscan` binary and skip download
-- `STARKSCAN_CLI_RELEASE_REPO`: maintainer/test GitHub repo path override
-- `STARKSCAN_CLI_PLATFORM_OVERRIDE`: force a specific target platform for cross-platform testing
-- `STARKSCAN_CLI_DOWNLOAD_TIMEOUT_MS`: download inactivity timeout in milliseconds, default `120000`
+The CLI forwards public API keys only to Starkscan HTTPS hosts or
+localhost/loopback fixtures. When intentionally testing a private API host, pass
+`--allow-untrusted-base-url` explicitly so keys are not replayed to an
+unexpected endpoint by default.
+
+## Release binding
 
-The package expects release assets produced by `rust-exp/scripts/package-starkscan-cli.sh`: `starkscan-cli-manifest.json`, `starkscan-<platform>.tar.gz`, and matching checksums. Run native packaging and npm packaging from the repository root so `.artifacts/release/cli` is available. Publish the tarball produced by `scripts/package-starkscan-cli-npm.sh` or `scripts/publish-public-cli.sh`; do not publish the package directory directly, because that can omit native artifacts.
+The package resolves bundled artifacts under `artifacts/v<package-version>` when
+published with native binaries included. Maintainer overrides such as
+`STARKSCAN_CLI_RELEASE_TAG`, `STARKSCAN_CLI_RELEASE_BASE_URL`,
+`STARKSCAN_CLI_BUNDLED_ARTIFACT_DIR`, and `STARKSCAN_CLI_BIN_PATH` exist for
+tests and emergency rollback; public clients should not need them.

package/artifacts/{v0.1.0-alpha.2 → v0.1.0}/starkscan-cli-manifest.json

@@ -1,34 +1,34 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-06-04T11:06:41Z",
+  "generatedAt": "2026-06-29T13:07:15Z",
   "artifacts": [
     {
       "name": "starkscan-darwin-aarch64.tar.gz",
       "platform": "darwin-aarch64",
       "target": "darwin-aarch64",
       "archive": "starkscan-darwin-aarch64.tar.gz",
-      "sha256": "a7b841e723af2c89269ca28b461ca6ef94b3cda329a38076356837225e649496"
+      "sha256": "f09d9f6e76be371e0f87da9d1540a77607c37cabb94c69c59959c02cbf523a14"
     },
     {
       "name": "starkscan-darwin-x86_64.tar.gz",
       "platform": "darwin-x86_64",
       "target": "darwin-x86_64",
       "archive": "starkscan-darwin-x86_64.tar.gz",
-      "sha256": "c99ddc5b28f6dcfab8523a6c13ab629fbc38a772c001bb75320490cb83fef382"
+      "sha256": "46319387c9b77503a79dc617fc28aa6b35ba34edda3a6997ce70701591f51885"
     },
     {
       "name": "starkscan-linux-aarch64.tar.gz",
       "platform": "linux-aarch64",
       "target": "linux-aarch64",
       "archive": "starkscan-linux-aarch64.tar.gz",
-      "sha256": "b41ed5a797590eab738a63999b64244e18a546d3ffb4b7659e3e67f81f894597"
+      "sha256": "767bd29fe5562a3ab114f098eecda36d05e816f48e6f8e57df0f66970897887e"
     },
     {
       "name": "starkscan-linux-x86_64.tar.gz",
       "platform": "linux-x86_64",
       "target": "linux-x86_64",
       "archive": "starkscan-linux-x86_64.tar.gz",
-      "sha256": "604970a343d948d426f5482630ac36cd42eb56989f1b3c6eae9113e0bc1584de"
+      "sha256": "2f51b30701dce6502cf4cf070adfcb839c74720015524197de679b65d6d927f5"
     }
   ]
 }

package/artifacts/v0.1.0/starkscan-darwin-aarch64.tar.gz.sha256

@@ -0,0 +1 @@
+f09d9f6e76be371e0f87da9d1540a77607c37cabb94c69c59959c02cbf523a14  starkscan-darwin-aarch64.tar.gz

package/artifacts/v0.1.0/starkscan-darwin-x86_64.tar.gz.sha256

@@ -0,0 +1 @@
+46319387c9b77503a79dc617fc28aa6b35ba34edda3a6997ce70701591f51885  starkscan-darwin-x86_64.tar.gz

package/artifacts/v0.1.0/starkscan-linux-aarch64.tar.gz.sha256

@@ -0,0 +1 @@
+767bd29fe5562a3ab114f098eecda36d05e816f48e6f8e57df0f66970897887e  starkscan-linux-aarch64.tar.gz

package/artifacts/v0.1.0/starkscan-linux-x86_64.tar.gz.sha256

@@ -0,0 +1 @@
+2f51b30701dce6502cf4cf070adfcb839c74720015524197de679b65d6d927f5  starkscan-linux-x86_64.tar.gz

package/bin/starkscan.js

@@ -2,7 +2,18 @@
 import { spawnSync } from 'node:child_process';
 import { constants as osConstants } from 'node:os';
 
-import { ensureStarkscanBinary } from '../scripts/installer.mjs';
+import { ensureStarkscanBinary, resolveStarkscanBinary } from '../scripts/installer.mjs';
+
+function truthyEnv(name) {
+  const value = process.env[name]?.trim().toLowerCase();
+  return value === '1' || value === 'true' || value === 'yes' || value === 'on';
+}
+
+function shouldPrintLauncherJson(args) {
+  return args.includes('--launcher-json')
+    || truthyEnv('STARKSCAN_LAUNCHER_JSON')
+    || truthyEnv('STARKSCAN_CLI_LAUNCHER_JSON');
+}
 
 function exitFromResult(result) {
   if (result.error) {
@@ -24,8 +35,15 @@ function exitFromResult(result) {
 }
 
 try {
+  const args = process.argv.slice(2);
+  if (shouldPrintLauncherJson(args)) {
+    const resolution = await resolveStarkscanBinary();
+    process.stdout.write(`${JSON.stringify(resolution, null, 2)}\n`);
+    process.exit(0);
+  }
+
   const binaryPath = await ensureStarkscanBinary();
-  const result = spawnSync(binaryPath, process.argv.slice(2), {
+  const result = spawnSync(binaryPath, args, {
     stdio: 'inherit',
   });
   exitFromResult(result);

package/package.json

@@ -1,20 +1,31 @@
 {
   "name": "@starkscan/cli",
   "private": false,
-  "version": "0.1.0-alpha.2",
-  "description": "npm/npx launcher for the prebuilt Starkscan explorer CLI.",
+  "version": "0.1.0",
+  "description": "Command-line launcher for Starkscan API, export, and agent workflows.",
   "license": "MIT",
   "type": "module",
   "publishConfig": {
     "access": "public"
   },
   "homepage": "https://starkscan.co/docs/ai/agent-cli",
+  "bugs": {
+    "url": "https://starkscan.co/docs/build/package-trust"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/starknet-innovation/mezcal",
+    "directory": "webapp/packages/cli"
+  },
   "keywords": [
     "starkscan",
     "starknet",
-    "explorer",
+    "block-explorer",
+    "cairo",
+    "web3",
     "cli",
-    "agent"
+    "agent",
+    "npx"
   ],
   "files": [
     "artifacts",
@@ -32,9 +43,11 @@
     "prepack": "npm run verify:bundled && npm run typecheck && npm test",
     "prepublishOnly": "npm run verify:bundled && npm run typecheck && npm test",
     "publish:alpha:dry-run": "./scripts/publish-public-cli.sh --tag alpha --dry-run",
-    "test": "node ./scripts/tests/cli-wrapper.mjs && ./scripts/tests/publish-public-cli.sh",
-    "typecheck": "node --check ./bin/starkscan.js && node --check ./scripts/install.mjs && node --check ./scripts/installer.mjs && node --check ./scripts/verify-bundled-artifacts.mjs && node --check ./scripts/tests/cli-wrapper.mjs",
-    "verify:bundled": "node ./scripts/verify-bundled-artifacts.mjs"
+    "test": "node ./scripts/tests/cli-wrapper.mjs && ./scripts/tests/publish-public-cli.sh && ./scripts/tests/e2e-canary-channel.sh",
+    "test:e2e": "node ./scripts/tests/e2e-canary.mjs",
+    "typecheck": "node --check ./bin/starkscan.js && node --check ./scripts/install.mjs && node --check ./scripts/installer.mjs && node --check ./scripts/verify-bundled-artifacts.mjs && node --check ./scripts/tests/cli-wrapper.mjs && node --check ./scripts/tests/e2e-canary.mjs",
+    "verify:bundled": "node ./scripts/verify-bundled-artifacts.mjs",
+    "publish:beta:dry-run": "./scripts/publish-public-cli.sh --tag beta --dry-run"
   },
   "engines": {
     "node": ">=18"

package/scripts/installer.mjs

@@ -1,9 +1,10 @@
 import { spawnSync } from 'node:child_process';
 import { createHash, randomBytes } from 'node:crypto';
 import { createReadStream, createWriteStream } from 'node:fs';
-import { copyFile, chmod, lstat, mkdir, mkdtemp, readFile, rename, rm } from 'node:fs/promises';
+import { copyFile, chmod, lstat, mkdir, mkdtemp, readFile, rename, rm, writeFile } from 'node:fs/promises';
 import { get as httpGet } from 'node:http';
 import { get as httpsGet } from 'node:https';
+import { isIP } from 'node:net';
 import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
@@ -11,10 +12,15 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const PACKAGE_JSON_PATH = path.join(PACKAGE_ROOT, 'package.json');
 const DEFAULT_BUNDLED_ARTIFACT_ROOT = path.join(PACKAGE_ROOT, 'artifacts');
-const DEFAULT_REPO = 'starknet-innovation/starkscan';
+const DEFAULT_REPO = 'starknet-innovation/mezcal';
 const DEFAULT_DOWNLOAD_TIMEOUT_MS = 120_000;
 const MAX_REDIRECTS = 10;
 const RELEASE_TAG_RE = /^(?=.*[A-Za-z0-9])(?!-)(?!.*\.\.)[A-Za-z0-9._-]+$/;
+const ALLOWED_RELEASE_BASE_HOSTS = new Set(['github.com', 'starkscan.co']);
+const ALLOWED_RELEASE_REDIRECT_HOSTS = new Set([
+  'objects.githubusercontent.com',
+  'release-assets.githubusercontent.com',
+]);
 const SUPPORTED_PLATFORMS = new Set([
   'darwin-aarch64',
   'darwin-x86_64',
@@ -23,6 +29,10 @@ const SUPPORTED_PLATFORMS = new Set([
 ]);
 const PUBLIC_BINARY_NAME = 'starkscan';
 const PUBLIC_MANIFEST_FILENAME = 'starkscan-cli-manifest.json';
+const EXECUTABLE_CHECKS = ['not-symlink', 'regular-file', 'executable'];
+const LOCAL_BIN_PATH_CHECKS = ['absolute-path', ...EXECUTABLE_CHECKS];
+const KNOWN_CACHE_SOURCES = new Set(['bundled', 'download']);
+const MANIFEST_TRUST_CHECKS = new Set(['local-release-manifest', 'unsigned-network-manifest-opt-in']);
 
 function env(name) {
   const value = process.env[name]?.trim();
@@ -37,6 +47,11 @@ function cliEnv(suffix) {
   return envFirst(`STARKSCAN_CLI_${suffix}`, `MEZCAL_CLI_${suffix}`);
 }
 
+function cliFlag(suffix) {
+  const value = cliEnv(suffix)?.toLowerCase();
+  return value === '1' || value === 'true' || value === 'yes' || value === 'on';
+}
+
 function fail(message) {
   throw new Error(message);
 }
@@ -169,8 +184,9 @@ function releaseTagFromVersion(version) {
   return version.startsWith('v') ? version : `v${version}`;
 }
 
-async function resolveReleaseTag() {
-  const tag = cliEnv('RELEASE_TAG') ?? env('MEZCAL_INSTALL_VERSION') ?? releaseTagFromVersion(await packageVersion());
+async function resolveReleaseTag(version) {
+  const packageVersionForTag = version ?? await packageVersion();
+  const tag = cliEnv('RELEASE_TAG') ?? env('MEZCAL_INSTALL_VERSION') ?? releaseTagFromVersion(packageVersionForTag);
   if (tag !== 'latest' && !RELEASE_TAG_RE.test(tag)) {
     fail(`unsupported release tag: ${tag}`);
   }
@@ -178,17 +194,137 @@ async function resolveReleaseTag() {
 }
 
 function releaseRootUrl(baseUrl, releaseTag) {
-  const normalizedBase = baseUrl.replace(/\/+$/, '');
+  const normalizedBase = normalizeReleaseBaseUrl(baseUrl).replace(/\/+$/, '');
   if (releaseTag === 'latest') {
     return `${normalizedBase}/latest/download`;
   }
   return `${normalizedBase}/download/${releaseTag}`;
 }
 
+function releaseBaseHostIsAllowed(hostname) {
+  return ALLOWED_RELEASE_BASE_HOSTS.has(hostname) || hostname.endsWith('.starkscan.co');
+}
+
+function releaseRedirectHttpsHostIsAllowed(hostname) {
+  return releaseBaseHostIsAllowed(hostname) || ALLOWED_RELEASE_REDIRECT_HOSTS.has(hostname);
+}
+
+function releaseBaseHttpHostIsLocal(hostname) {
+  const normalized = hostname.toLowerCase();
+  if (normalized === 'localhost') {
+    return true;
+  }
+  const address = normalized.startsWith('[') && normalized.endsWith(']')
+    ? normalized.slice(1, -1)
+    : normalized;
+  if (address === '::1') {
+    return true;
+  }
+  if (isIP(address) !== 4) {
+    return false;
+  }
+  const octets = address.split('.').map(Number);
+  return octets.length === 4 && octets[0] === 127 && octets.every((octet) => octet >= 0 && octet <= 255);
+}
+
+function releaseGitHubPathMatchesDefaultRepo(pathname) {
+  const normalized = pathname.replace(/\/+$/, '');
+  const [owner, repo, segment, ...extra] = normalized.split('/').filter(Boolean);
+  const [expectedOwner, expectedRepo] = DEFAULT_REPO.split('/');
+  const matchesRepo =
+    owner?.toLowerCase() === expectedOwner.toLowerCase()
+    && repo?.toLowerCase() === expectedRepo.toLowerCase()
+    && segment === 'releases';
+  return { matchesRepo, extra };
+}
+
+function releaseBaseGitHubPathIsAllowed(pathname) {
+  const { matchesRepo, extra } = releaseGitHubPathMatchesDefaultRepo(pathname);
+  return matchesRepo && extra.length === 0;
+}
+
+function releaseRedirectGitHubPathIsAllowed(pathname) {
+  const { matchesRepo } = releaseGitHubPathMatchesDefaultRepo(pathname);
+  return matchesRepo;
+}
+
+export function normalizeReleaseBaseUrl(baseUrl) {
+  let parsed;
+  try {
+    parsed = new URL(baseUrl);
+  } catch {
+    fail(`unsupported STARKSCAN_CLI_RELEASE_BASE_URL: ${baseUrl}`);
+  }
+  if (parsed.search || parsed.hash) {
+    fail('STARKSCAN_CLI_RELEASE_BASE_URL must not include query parameters or fragments');
+  }
+  if (parsed.username || parsed.password) {
+    fail('STARKSCAN_CLI_RELEASE_BASE_URL must not include credentials');
+  }
+
+  if (parsed.protocol === 'file:') {
+    try {
+      const filePath = fileURLToPath(parsed);
+      if (!path.isAbsolute(filePath)) {
+        fail('STARKSCAN_CLI_RELEASE_BASE_URL file: override must resolve to an absolute path');
+      }
+      return pathToFileURL(filePath).href;
+    } catch (error) {
+      if (error instanceof Error && error.message.includes('STARKSCAN_CLI_RELEASE_BASE_URL')) {
+        throw error;
+      }
+      fail('STARKSCAN_CLI_RELEASE_BASE_URL file: override must be an absolute local file URL');
+    }
+  }
+
+  if (parsed.protocol === 'http:') {
+    if (!cliFlag('ALLOW_INSECURE_RELEASE_BASE_URL')) {
+      fail('STARKSCAN_CLI_RELEASE_BASE_URL must use HTTPS or file: unless STARKSCAN_CLI_ALLOW_INSECURE_RELEASE_BASE_URL=1 is set for a local maintainer test');
+    }
+    if (!releaseBaseHttpHostIsLocal(parsed.hostname)) {
+      fail('plaintext HTTP STARKSCAN_CLI_RELEASE_BASE_URL is only allowed for localhost or loopback maintainer fixtures');
+    }
+    return parsed.href;
+  }
+
+  if (parsed.protocol !== 'https:') {
+    fail(`unsupported STARKSCAN_CLI_RELEASE_BASE_URL protocol: ${parsed.protocol}`);
+  }
+
+  if (!releaseBaseHostIsAllowed(parsed.hostname) && !cliFlag('ALLOW_CUSTOM_RELEASE_BASE_URL')) {
+    fail(`custom STARKSCAN_CLI_RELEASE_BASE_URL host is not allowed by default: ${parsed.hostname}`);
+  }
+
+  if (parsed.hostname === 'github.com' && !cliFlag('ALLOW_CUSTOM_RELEASE_BASE_URL') && !releaseBaseGitHubPathIsAllowed(parsed.pathname)) {
+    fail(`custom STARKSCAN_CLI_RELEASE_BASE_URL GitHub repository is not allowed by default: ${parsed.pathname}`);
+  }
+
+  return parsed.href;
+}
+
 function releaseAssetUrl(rootUrl, filename) {
   return `${rootUrl}/${filename}`;
 }
 
+function releaseRootUsesNetwork(rootUrl) {
+  const protocol = new URL(rootUrl).protocol;
+  return protocol === 'https:' || protocol === 'http:';
+}
+
+function releaseManifestTrustCheck(rootUrl) {
+  if (!releaseRootUsesNetwork(rootUrl)) {
+    return 'local-release-manifest';
+  }
+  if (!cliFlag('ALLOW_UNSIGNED_NETWORK_MANIFEST')) {
+    fail(
+      'unsigned network release manifests are not trusted by default; use bundled npm artifacts, '
+      + 'a local file: release source, or set STARKSCAN_CLI_ALLOW_UNSIGNED_NETWORK_MANIFEST=1 '
+      + 'for a maintainer-only fallback until signed manifest verification is available',
+    );
+  }
+  return 'unsigned-network-manifest-opt-in';
+}
+
 function bundledArtifactRoot() {
   const configured = cliEnv('BUNDLED_ARTIFACT_DIR');
   if (!configured) {
@@ -207,6 +343,127 @@ async function hasBundledArtifacts(releaseTag) {
   return Boolean(stat?.isFile());
 }
 
+async function resolveReleaseSource(releaseTag) {
+  const releaseRepo = cliEnv('RELEASE_REPO');
+  const repo = releaseRepo ?? DEFAULT_REPO;
+  if (!/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(repo)) {
+    fail(`unsupported GitHub repo path: ${repo}`);
+  }
+
+  const releaseBaseUrl = cliEnv('RELEASE_BASE_URL');
+  if (
+    !releaseBaseUrl &&
+    !releaseRepo &&
+    await hasBundledArtifacts(releaseTag)
+  ) {
+    return {
+      rootUrl: bundledArtifactRootUrl(releaseTag),
+      source: 'bundled',
+      requestedFrom: 'bundled-artifacts',
+    };
+  }
+
+  const baseUrl = releaseBaseUrl ?? `https://github.com/${repo}/releases`;
+  return {
+    rootUrl: releaseRootUrl(baseUrl, releaseTag),
+    source: 'download',
+    requestedFrom: releaseBaseUrl ? 'release-base-url' : 'github-release',
+  };
+}
+
+function cacheMetadataPath(cachePath) {
+  return `${cachePath}.meta.json`;
+}
+
+async function writeCacheMetadata(cachePath, metadata) {
+  const metadataPath = cacheMetadataPath(cachePath);
+  const stagePath = `${metadataPath}.${process.pid}.${randomBytes(6).toString('hex')}.tmp`;
+  try {
+    await writeFile(stagePath, `${JSON.stringify({ schemaVersion: 1, ...metadata }, null, 2)}\n`);
+    await rename(stagePath, metadataPath);
+  } catch (error) {
+    await rm(stagePath, { force: true }).catch(() => {});
+    throw error;
+  }
+}
+
+async function readCacheMetadata(cachePath, releaseTag, platform) {
+  const metadataPath = cacheMetadataPath(cachePath);
+  try {
+    const parsed = JSON.parse(await readFile(metadataPath, 'utf8'));
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+      throw new Error('cache metadata root must be an object');
+    }
+    if (parsed.schemaVersion !== 1) {
+      throw new Error('cache metadata schemaVersion must be 1');
+    }
+    if (parsed.releaseTag !== releaseTag || parsed.platform !== platform) {
+      throw new Error('cache metadata does not match cache path');
+    }
+    if (typeof parsed.source !== 'string' || !KNOWN_CACHE_SOURCES.has(parsed.source)) {
+      throw new Error('cache metadata source is invalid');
+    }
+    const storedChecks = Array.isArray(parsed.verification?.checks)
+      ? parsed.verification.checks.filter((check) => typeof check === 'string')
+      : [];
+    const manifestTrustChecks = storedChecks.filter((check) => MANIFEST_TRUST_CHECKS.has(check));
+    return {
+      source: parsed.source,
+      requestedFrom: typeof parsed.requestedFrom === 'string' ? parsed.requestedFrom : 'cache-metadata',
+      releaseRootUrl: typeof parsed.releaseRootUrl === 'string' ? parsed.releaseRootUrl : null,
+      manifestTrustChecks,
+      sourceConfidence: 'stored',
+      metadataStatus: 'stored',
+    };
+  } catch (error) {
+    const errorCode = error && typeof error === 'object' && 'code' in error ? String(error.code) : undefined;
+    const isMissing = errorCode === 'ENOENT';
+    return {
+      source: 'unknown',
+      requestedFrom: isMissing ? 'legacy-cache-missing-metadata' : 'cache-metadata-invalid',
+      releaseRootUrl: null,
+      manifestTrustChecks: [],
+      sourceConfidence: 'unknown',
+      metadataStatus: isMissing ? 'missing' : 'invalid',
+      metadataError: isMissing ? undefined : (error instanceof SyntaxError ? 'invalid-json' : errorCode ?? 'invalid-metadata'),
+    };
+  }
+}
+
+function enforceCachedManifestTrustChecks(cachedSource) {
+  const manifestTrustChecks = cachedSource.manifestTrustChecks ?? [];
+  if (cachedSource.metadataStatus !== 'stored') {
+    fail(
+      'cached Starkscan binary is missing trusted cache metadata; delete the cache and reinstall '
+      + 'from bundled npm artifacts or a local file: release source',
+    );
+  }
+  if (manifestTrustChecks.length === 0) {
+    fail(
+      'cached Starkscan binary is missing release manifest trust provenance; delete the cache and reinstall '
+      + 'from bundled npm artifacts or a local file: release source',
+    );
+  }
+  if (
+    manifestTrustChecks.includes('unsigned-network-manifest-opt-in') &&
+    !cliFlag('ALLOW_UNSIGNED_NETWORK_MANIFEST')
+  ) {
+    fail(
+      'cached Starkscan binary was installed from an unsigned network release manifest; '
+      + 'set STARKSCAN_CLI_ALLOW_UNSIGNED_NETWORK_MANIFEST=1 to reuse this maintainer-only '
+      + 'fallback cache, or delete the cache and reinstall from bundled npm artifacts or a local file: release source',
+    );
+  }
+}
+
+function launcherResolution(fields) {
+  return {
+    schemaVersion: 1,
+    packageName: '@starkscan/cli',
+    ...fields,
+  };
+}
+
 export function resolveRedirectUrl(url, location, redirectsLeft) {
   if (redirectsLeft <= 0) {
     fail(`too many redirects downloading ${url}`);
@@ -219,6 +476,27 @@ export function resolveRedirectUrl(url, location, redirectsLeft) {
   if (currentUrl.protocol === 'https:' && redirectUrl.protocol === 'http:') {
     fail(`redirect from HTTPS to HTTP is not allowed: ${redirectUrl.toString()}`);
   }
+  if (redirectUrl.username || redirectUrl.password) {
+    fail('release asset redirect URL must not include credentials');
+  }
+  if (redirectUrl.protocol === 'http:' && !releaseBaseHttpHostIsLocal(redirectUrl.hostname)) {
+    fail('plaintext HTTP release asset redirect is only allowed for localhost or loopback maintainer fixtures');
+  }
+  if (
+    redirectUrl.protocol === 'https:' &&
+    !releaseRedirectHttpsHostIsAllowed(redirectUrl.hostname) &&
+    !cliFlag('ALLOW_CUSTOM_RELEASE_BASE_URL')
+  ) {
+    fail(`custom release asset redirect host is not allowed by default: ${redirectUrl.hostname}`);
+  }
+  if (
+    redirectUrl.protocol === 'https:' &&
+    redirectUrl.hostname === 'github.com' &&
+    !cliFlag('ALLOW_CUSTOM_RELEASE_BASE_URL') &&
+    !releaseRedirectGitHubPathIsAllowed(redirectUrl.pathname)
+  ) {
+    fail(`custom release asset redirect GitHub repository is not allowed by default: ${redirectUrl.pathname}`);
+  }
   return redirectUrl.toString();
 }
 
@@ -351,9 +629,10 @@ async function readManifest(rootUrl, tempDir) {
   return await readDownloadedManifest(manifestPath, PUBLIC_MANIFEST_FILENAME);
 }
 
-async function installFromRelease({ platform, releaseTag, cachePath, rootUrl }) {
+async function installFromRelease({ platform, releaseTag, cachePath, rootUrl, source, requestedFrom }) {
   const tempDir = await mkdtemp(path.join(os.tmpdir(), 'starkscan-npm-cli-'));
   try {
+    const manifestTrustCheck = releaseManifestTrustCheck(rootUrl);
     const manifest = await readManifest(rootUrl, tempDir);
     const matching = manifest.artifacts.filter((artifact) => artifact?.platform === platform);
     if (matching.length !== 1) {
@@ -391,21 +670,75 @@ async function installFromRelease({ platform, releaseTag, cachePath, rootUrl })
       throw error;
     }
     await validateExecutableFile(cachePath, 'cached Starkscan binary');
-    return cachePath;
+    const result = {
+      binaryPath: cachePath,
+      platform,
+      releaseTag,
+      source,
+      requestedFrom,
+      resolvedFrom: 'release',
+      cacheHit: false,
+      cachePath,
+      releaseRootUrl: rootUrl,
+      verification: {
+        status: 'verified-sha256',
+        manifest: PUBLIC_MANIFEST_FILENAME,
+        archive: artifact.archive,
+        sha256: artifact.sha256,
+        checks: [manifestTrustCheck, 'manifest-schema', 'platform-match', 'archive-name', 'archive-sha256', 'single-binary-archive', ...EXECUTABLE_CHECKS],
+      },
+    };
+    await writeCacheMetadata(cachePath, {
+      platform,
+      releaseTag,
+      source,
+      requestedFrom,
+      releaseRootUrl: rootUrl,
+      verification: {
+        status: result.verification.status,
+          manifest: result.verification.manifest,
+          archive: result.verification.archive,
+          sha256: result.verification.sha256,
+          checks: result.verification.checks,
+        },
+      });
+    return result;
   } finally {
     await rm(tempDir, { recursive: true, force: true });
   }
 }
 
-export async function ensureStarkscanBinary(options = {}) {
+export async function resolveStarkscanBinary(options = {}) {
+  const version = await packageVersion();
   const explicitBinary = cliEnv('BIN_PATH');
   if (explicitBinary) {
+    if (!cliFlag('ALLOW_BIN_PATH')) {
+      fail('STARKSCAN_CLI_BIN_PATH requires STARKSCAN_CLI_ALLOW_BIN_PATH=1');
+    }
+    if (!path.isAbsolute(explicitBinary)) {
+      fail(`STARKSCAN_CLI_BIN_PATH must be an absolute path: ${explicitBinary}`);
+    }
     await validateExecutableFile(explicitBinary, 'STARKSCAN_CLI_BIN_PATH');
-    return explicitBinary;
+    return launcherResolution({
+      packageVersion: version,
+      binaryPath: explicitBinary,
+      platform: null,
+      releaseTag: null,
+      source: 'bin-path',
+      requestedFrom: 'bin-path',
+      resolvedFrom: 'bin-path',
+      cacheHit: false,
+      cachePath: null,
+      releaseRootUrl: null,
+      verification: {
+        status: 'validated-local-executable',
+        checks: LOCAL_BIN_PATH_CHECKS,
+      },
+    });
   }
 
   const platform = resolvePlatform();
-  const releaseTag = await resolveReleaseTag();
+  const releaseTag = await resolveReleaseTag(version);
   const cacheDir = path.join(defaultCacheRoot(), releaseTag, platform);
   const cachePath = path.join(cacheDir, PUBLIC_BINARY_NAME);
   const allowCacheReuse = !options.force && releaseTag !== 'latest';
@@ -413,26 +746,45 @@ export async function ensureStarkscanBinary(options = {}) {
     const existing = await lstat(cachePath).catch(() => null);
     if (existing) {
       await validateExecutableFile(cachePath, 'cached Starkscan binary');
-      return cachePath;
+      const cachedSource = await readCacheMetadata(cachePath, releaseTag, platform);
+      enforceCachedManifestTrustChecks(cachedSource);
+      return launcherResolution({
+        packageVersion: version,
+        binaryPath: cachePath,
+        platform,
+        releaseTag,
+        source: cachedSource.source,
+        requestedFrom: cachedSource.requestedFrom,
+        resolvedFrom: 'cache',
+        cacheHit: true,
+        cachePath,
+        releaseRootUrl: cachedSource.releaseRootUrl,
+        sourceConfidence: cachedSource.sourceConfidence,
+        metadataStatus: cachedSource.metadataStatus,
+        ...(cachedSource.metadataError ? { metadataError: cachedSource.metadataError } : {}),
+        verification: {
+          status: 'validated-cached-executable',
+          checks: [...(cachedSource.manifestTrustChecks ?? []), ...EXECUTABLE_CHECKS],
+        },
+      });
     }
   }
 
-  const releaseRepo = cliEnv('RELEASE_REPO');
-  const repo = releaseRepo ?? DEFAULT_REPO;
-  if (!/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(repo)) {
-    fail(`unsupported GitHub repo path: ${repo}`);
-  }
-  const releaseBaseUrl = cliEnv('RELEASE_BASE_URL');
-  let rootUrl;
-  if (
-    !releaseBaseUrl &&
-    !releaseRepo &&
-    await hasBundledArtifacts(releaseTag)
-  ) {
-    rootUrl = bundledArtifactRootUrl(releaseTag);
-  } else {
-    const baseUrl = releaseBaseUrl ?? `https://github.com/${repo}/releases`;
-    rootUrl = releaseRootUrl(baseUrl, releaseTag);
-  }
-  return installFromRelease({ platform, releaseTag, cachePath, rootUrl });
+  const releaseSource = await resolveReleaseSource(releaseTag);
+  return launcherResolution({
+    packageVersion: version,
+    ...await installFromRelease({
+      platform,
+      releaseTag,
+      cachePath,
+      rootUrl: releaseSource.rootUrl,
+      source: releaseSource.source,
+      requestedFrom: releaseSource.requestedFrom,
+    }),
+  });
+}
+
+export async function ensureStarkscanBinary(options = {}) {
+  const resolution = await resolveStarkscanBinary(options);
+  return resolution.binaryPath;
 }

package/scripts/verify-bundled-artifacts.mjs

@@ -1,6 +1,8 @@
 import { createHash } from 'node:crypto';
+import { spawnSync } from 'node:child_process';
 import { createReadStream } from 'node:fs';
-import { lstat, readFile } from 'node:fs/promises';
+import { lstat, mkdtemp, readFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
@@ -15,6 +17,14 @@ const SUPPORTED_PLATFORMS = [
   'linux-x86_64',
 ];
 const PUBLIC_MANIFEST_FILENAME = 'starkscan-cli-manifest.json';
+const PUBLIC_BINARY_NAME = 'starkscan';
+const HOSTED_DEFAULT_BASE_URL = 'https://api.starkscan.co';
+const PUBLIC_HELP_FORBIDDEN_STRINGS = [
+  'http://127.0.0.1:3000',
+  '--internal-api-key',
+  'STARKSCAN_INTERNAL_API_KEY',
+  'X-Explorer-Internal-Key',
+];
 
 function env(name) {
   const value = process.env[name]?.trim();
@@ -29,6 +39,26 @@ function fail(message) {
   throw new Error(`verify-bundled-artifacts: ${message}`);
 }
 
+function describeSpawn(result) {
+  const details = [
+    `status=${result.status ?? 'null'}`,
+    `signal=${result.signal ?? 'none'}`,
+  ];
+  if (result.error?.message) {
+    details.push(`error=${result.error.message}`);
+  }
+  for (const [name, value] of [
+    ['stdout', result.stdout],
+    ['stderr', result.stderr],
+  ]) {
+    const text = String(value ?? '').trim();
+    if (text.length > 0) {
+      details.push(`${name}=${text}`);
+    }
+  }
+  return details.join('; ');
+}
+
 function releaseTagFromVersion(version) {
   return version.startsWith('v') ? version : `v${version}`;
 }
@@ -50,6 +80,97 @@ async function assertFile(filePath, label, remediation) {
   }
 }
 
+function currentReleasePlatform() {
+  const os =
+    process.platform === 'darwin' || process.platform === 'linux'
+      ? process.platform
+      : undefined;
+  const arch =
+    process.arch === 'x64' ? 'x86_64' : process.arch === 'arm64' ? 'aarch64' : undefined;
+  return os && arch ? `${os}-${arch}` : undefined;
+}
+
+function publicVerifierSpawnEnv() {
+  const nextEnv = {};
+  for (const name of ['PATH', 'TMPDIR', 'TMP', 'TEMP', 'LANG', 'LC_ALL', 'LC_CTYPE']) {
+    const value = process.env[name];
+    if (typeof value === 'string' && value.length > 0) {
+      nextEnv[name] = value;
+    }
+  }
+  if (!nextEnv.PATH) {
+    nextEnv.PATH = '/usr/bin:/bin:/usr/sbin:/sbin';
+  }
+  return nextEnv;
+}
+
+async function verifyCurrentPlatformHelpContract(releaseRoot, manifest) {
+  const platform = currentReleasePlatform();
+  if (!platform) return;
+  const artifact = manifest.artifacts.find((candidate) => candidate?.platform === platform);
+  if (!artifact) {
+    fail(`bundled manifest is missing current platform artifact ${platform}`);
+  }
+  const archiveName = artifact.archive ?? artifact.name;
+  const archivePath = path.join(releaseRoot, archiveName);
+  const tmpRoot = await mkdtemp(path.join(tmpdir(), 'starkscan-cli-contract-'));
+  try {
+    const listingResult = spawnSync('tar', ['-tzf', archivePath], {
+      encoding: 'utf8',
+      env: publicVerifierSpawnEnv(),
+      timeout: 15_000,
+    });
+    if (listingResult.status !== 0 || listingResult.error) {
+      fail(`failed to inspect current-platform CLI artifact ${archiveName}: ${describeSpawn(listingResult)}`);
+    }
+    const listing = listingResult.stdout
+      .split(/\r?\n/)
+      .map((entry) => entry.trim())
+      .filter(Boolean);
+    if (listing.length !== 1 || listing[0] !== PUBLIC_BINARY_NAME) {
+      fail(
+        `current-platform CLI artifact ${archiveName} must contain exactly one top-level Starkscan binary; found ${JSON.stringify(listing)}`,
+      );
+    }
+
+    const tarResult = spawnSync('tar', ['-C', tmpRoot, '-xzf', archivePath], {
+      encoding: 'utf8',
+      env: publicVerifierSpawnEnv(),
+      timeout: 15_000,
+    });
+    if (tarResult.status !== 0 || tarResult.error) {
+      fail(`failed to extract current-platform CLI artifact ${archiveName}: ${describeSpawn(tarResult)}`);
+    }
+    const binaryPath = path.join(tmpRoot, PUBLIC_BINARY_NAME);
+    await assertFile(
+      binaryPath,
+      'current-platform bundled binary',
+      'Archive must contain a root starkscan binary.',
+    );
+    const helpResult = spawnSync(binaryPath, ['--help'], {
+      encoding: 'utf8',
+      env: publicVerifierSpawnEnv(),
+      timeout: 15_000,
+    });
+    if (helpResult.status !== 0 || helpResult.error) {
+      fail(
+        `current-platform bundled binary failed --help: ${describeSpawn(helpResult)}`,
+      );
+    }
+    const output = `${helpResult.stdout}\n${helpResult.stderr}`;
+    if (!output.includes(HOSTED_DEFAULT_BASE_URL)) {
+      fail(`current-platform bundled binary help does not advertise hosted default ${HOSTED_DEFAULT_BASE_URL}`);
+    }
+    for (const forbidden of PUBLIC_HELP_FORBIDDEN_STRINGS) {
+      if (output.includes(forbidden)) {
+        fail(`current-platform bundled binary help leaks forbidden public contract string: ${forbidden}`);
+      }
+    }
+  } finally {
+    await rm(tmpRoot, { recursive: true, force: true });
+  }
+}
+
 async function main() {
   const packageJson = JSON.parse(await readFile(PACKAGE_JSON_PATH, 'utf8'));
   if (typeof packageJson.version !== 'string' || packageJson.version.length === 0) {
@@ -114,6 +235,8 @@ async function main() {
       fail(`${archiveName} bytes do not match manifest sha256`);
     }
   }
+
+  await verifyCurrentPlatformHelpContract(releaseRoot, manifest);
 }
 
 main().catch((error) => {

package/artifacts/v0.1.0-alpha.2/starkscan-darwin-aarch64.tar.gz.sha256

@@ -1 +0,0 @@
-a7b841e723af2c89269ca28b461ca6ef94b3cda329a38076356837225e649496  starkscan-darwin-aarch64.tar.gz

package/artifacts/v0.1.0-alpha.2/starkscan-darwin-x86_64.tar.gz.sha256

@@ -1 +0,0 @@
-c99ddc5b28f6dcfab8523a6c13ab629fbc38a772c001bb75320490cb83fef382  starkscan-darwin-x86_64.tar.gz

package/artifacts/v0.1.0-alpha.2/starkscan-linux-aarch64.tar.gz.sha256

@@ -1 +0,0 @@
-b41ed5a797590eab738a63999b64244e18a546d3ffb4b7659e3e67f81f894597  starkscan-linux-aarch64.tar.gz

package/artifacts/v0.1.0-alpha.2/starkscan-linux-x86_64.tar.gz.sha256

@@ -1 +0,0 @@
-604970a343d948d426f5482630ac36cd42eb56989f1b3c6eae9113e0bc1584de  starkscan-linux-x86_64.tar.gz