@starkscan/cli 0.1.0-alpha.2 → 0.1.0-beta.1

package/README.md

@@ -1,22 +1,33 @@
 # @starkscan/cli
 
-npm/npx launcher for the prebuilt Starkscan CLI.
+Command-line launcher for Starkscan API, export, and agent workflows.
+
+Status: public beta. Use a smoked exact version such as `0.1.0-beta.1` for unattended
+agents or production services.
 
 ## Install
 
 ```bash
-npm install -g @starkscan/cli@alpha
-starkscan doctor
+npm install -g @starkscan/cli@0.1.0-beta.1
+starkscan init
 ```
 
 One-off agent run:
 
 ```bash
-npx @starkscan/cli@alpha doctor
+npx -y @starkscan/cli@0.1.0-beta.1 init --agent --output-format json
 ```
 
 For unattended agents or production services, pin a smoked exact version instead
-of floating on `@alpha`.
+of floating on `@beta`.
+
+## What it does
+
+- Runs the prebuilt native `starkscan` binary without requiring a Rust toolchain.
+- Verifies bundled native archives against release-manifest checksums.
+- Calls the hosted Starkscan API with request IDs and route-class headers.
+- Exposes shell-friendly output for agents, scripts, exports, and operator
+  smoke checks.
 
 ## Trust status
 
@@ -34,38 +45,91 @@ to Starkscan docs instead of GitHub.
 
 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.
 
+Agents can inspect the launcher decision without executing the native binary:
+
+```bash
+npx -y @starkscan/cli@0.1.0-beta.1 --launcher-json
+```
+
+`--launcher-json` also works through `STARKSCAN_LAUNCHER_JSON=1` or
+`STARKSCAN_CLI_LAUNCHER_JSON=1`. The JSON includes the package version,
+resolved binary path, release tag, source (`bundled`, `download`, `bin-path`, or
+`unknown` for legacy caches without valid sidecar metadata), cache-hit status, and
+verification status. It may resolve and verify the binary first, but it does
+not invoke the native `starkscan` executable.
+
 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:
 
 ```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-beta.1 init --agent --output-format json
+npx -y @starkscan/cli@0.1.0-beta.1 mcp print-config --transport remote
+npx -y @starkscan/cli@0.1.0-beta.1 mcp start --transport remote
 ```
 
 ## Environment
 
 ```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"
+# Optional: only set this for preview or self-hosted hosts.
+# export STARKSCAN_BASE_URL="https://preview.example.com/api"
 ```
 
 `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.
+cutover. The CLI defaults to `https://api.starkscan.co` and sends
+`X-Starkscan-Api-Key` to the hosted API.
+
+The native 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.
+
+Supported `STARKSCAN_CHAIN` values are `SN_MAIN` and `SN_SEPOLIA`. Global flags
+can be placed before or after the subcommand, for example
+`starkscan status --output-format json --pretty`.
+
+For agent callers, `--output-format json` always keeps stdout parseable: success
+prints `{ "ok": true, "data": ... }`, and failures before a result payload is
+emitted print
+`{ "ok": false, "error": { "code": "auth_error", "message": "HTTP 401: unauthorized", "exitCode": 3, "exitClass": "auth", "httpStatus": 401, "requestId": "starkscan-cli-..." } }`
+before exiting non-zero. Diagnostic commands such as `doctor` can emit
+`{ "ok": false, "data": ... }` with a non-zero exit. `stream-json` failures
+print one compact `type: "error"` line. Text mode keeps human-readable errors on
+stderr.
+
+Transaction hashes, addresses, token addresses, and calldata values must be
+`0x`-prefixed Starknet field elements. Contract-read selectors can be function
+names such as `balanceOf` or selector felts. Malformed values fail locally before
+any network request with exit code `2`; JSON mode emits `code: "usage_error"`.
+In JSON output, address-shaped fields such as `address`, `fromAddress`,
+`toAddress`, `contractAddress`, and `tokenAddress` are canonicalized to lowercase
+`0x` plus 64 hex characters so agents can join rows reliably. Hashes, calldata,
+selectors, and other felt values are not rewritten.
+
+CLI exit codes are stable for agents: `0` success, `1` runtime, `2`
+usage/bad input, `3` auth, `4` rate-limited, `5` timeout, and `6` not found.
+
+## Minimal commands
+
+```bash
+npx -y @starkscan/cli@0.1.0-beta.1 init
+npx -y @starkscan/cli@0.1.0-beta.1 status
+npx -y @starkscan/cli@0.1.0-beta.1 doctor
+npx -y @starkscan/cli@0.1.0-beta.1 mcp print-config --transport remote
+```
 
 ## Release binding
 
 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:
 
 - `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_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 -y @starkscan/cli@0.1.0-beta.1 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. By default the override must be a local `file:` URL, the official GitHub HTTPS release path, or Starkscan HTTPS. Custom HTTPS hosts or GitHub repo paths require `STARKSCAN_CLI_ALLOW_CUSTOM_RELEASE_BASE_URL=1`; plaintext HTTP requires `STARKSCAN_CLI_ALLOW_INSECURE_RELEASE_BASE_URL=1` and is limited to localhost or loopback maintainer fixtures. Network release manifests are fail-closed unless `STARKSCAN_CLI_ALLOW_UNSIGNED_NETWORK_MANIFEST=1` is set for a maintainer-only fallback; bundled npm artifacts or local `file:` fixtures are preferred until signed manifest verification exists.
 - `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_BIN_PATH`: maintainer/test override to use an existing local `starkscan` binary and skip download. Requires `STARKSCAN_CLI_ALLOW_BIN_PATH=1`; the path must be absolute, executable, and not a symlink.
 - `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`

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

@@ -1,34 +1,34 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-06-04T11:06:41Z",
+  "generatedAt": "2026-06-29T04:53:36Z",
   "artifacts": [
     {
       "name": "starkscan-darwin-aarch64.tar.gz",
       "platform": "darwin-aarch64",
       "target": "darwin-aarch64",
       "archive": "starkscan-darwin-aarch64.tar.gz",
-      "sha256": "a7b841e723af2c89269ca28b461ca6ef94b3cda329a38076356837225e649496"
+      "sha256": "b33a14b7b4e85ee571ee537e46153ea0ef5eb1eb01d6d34c3620c670c13cb371"
     },
     {
       "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": "4bcf906defb317754d38c72a9586219eadfcb9dc725aa920a4fce650c78cf311"
     },
     {
       "name": "starkscan-linux-aarch64.tar.gz",
       "platform": "linux-aarch64",
       "target": "linux-aarch64",
       "archive": "starkscan-linux-aarch64.tar.gz",
-      "sha256": "b41ed5a797590eab738a63999b64244e18a546d3ffb4b7659e3e67f81f894597"
+      "sha256": "a60a493fd6c226b329d9e7a4f1b1c1a0d62a68d59740dd484390306db879bac1"
     },
     {
       "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": "604f25e483adf6b035e37ef803f6e5d5a56bed20b3caa1762d0a46923d384e05"
     }
   ]
 }

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

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

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

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

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

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

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

@@ -0,0 +1 @@
+604f25e483adf6b035e37ef803f6e5d5a56bed20b3caa1762d0a46923d384e05  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-beta.1",
+  "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