@hackaiz/cli 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 HACKTUALIZ Inc.
+
+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

@@ -1,3 +1,36 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# Hackaiz CLI
+
+Command-line client for [Hackaiz](https://hackaiz.com). Requires Node.js 22 or later.
+
+```sh
+npm i -g @hackaiz/cli
+export HACKAIZ_API_KEY='your personal key'
+hackaiz analyze PLATFORM_UUID STABLE_REQUEST_KEY
+hackaiz status PLATFORM_UUID REQUEST_UUID
+hackaiz verify PLATFORM_UUID REQUEST_UUID
+hackaiz report PLATFORM_UUID
+hackaiz findings PLATFORM_UUID
+```
+
+Your key must allow read and launch access for the platform. Analyses are passive only, require current proof of ownership and consent, and use credits as usual. The CLI never publishes fixes and never merges anything. It requests an analysis, then checks its status; you don't need to click anything in Hackaiz. If your connection drops, check the same request again instead of creating a new one. An analysis that has already started is never replayed automatically after an interruption. A partial analysis does not prove full coverage.
+
+Never store your key in a repository or in logs.
+
+`verify` reads only the report linked to that request. It needs a complete analysis and reads all of its findings. Exit codes: `0` = no unresolved High/Critical finding, `1` = such findings exist, `2` = incomplete or unavailable. This checks the saved platform; it does not verify a specific PR commit or deployment.
+
+## Check before installing
+
+```sh
+hackaiz check ./my-skill            # Skill folder, MCP config, package.json, workflow or Dockerfile
+hackaiz check . --sarif > hackaiz.sarif   # CI: exit code 2 on a Danger verdict
+```
+
+### Claude Code hook (automatic check before a Skill, MCP or install command)
+
+Add to `.claude/settings.json` (with `HACKAIZ_API_KEY` set in your environment):
+
+```json
+{ "hooks": { "PreToolUse": [ { "matcher": "Write|Edit|MultiEdit|Bash", "hooks": [ { "type": "command", "command": "hackaiz hook claude" } ] } ] } }
+```
+
+Only Skill/MCP/package/workflow writes and install commands are checked, and each new check uses credits, including unchanged content. Enabling this hook opts into paid checks before these actions; it is not background monitoring. A Danger verdict blocks the action. An incomplete response, missing key, service error or exhausted credits also blocks it: no missing verdict is treated as approval. Set `HACKAIZ_HOOK_FAIL_OPEN=1` only to explicitly choose advisory mode during failures. This hook checks submitted text, not all installed package code or runtime behaviour.

package/bin/check.mjs

@@ -0,0 +1,59 @@
+// `hackaiz check <path> [--sarif]`: static check of a Skill / MCP / package / workflow before installing.
+// Exit 2 on a Danger verdict so CI can block. Secret, binary and generated files are never sent.
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { join, relative, basename } from 'node:path';
+import { randomUUID } from 'node:crypto';
+
+const SKIP_DIR = new Set(['node_modules', '.git', 'dist', 'build', '.next', 'coverage', '.venv', 'venv', '__pycache__']);
+const SECRET = /(^|\/)(\.env(\..*)?|.*\.(pem|key|p12|pfx|keystore|jks)|id_rsa|id_ed25519|\.npmrc|\.netrc)$/i;
+const BINARY = /\.(png|jpe?g|gif|webp|ico|pdf|zip|gz|tgz|exe|dll|so|dylib|wasm|woff2?|ttf|mp[34]|lockb|bin)$/i;
+
+export async function collectComponent(root, { maxFiles = 400, maxFileBytes = 400 * 1024 } = {}) {
+  const files = []; const skipped = [];
+  const s = await stat(root);
+  const walk = async (dir) => {
+    for (const e of await readdir(dir, { withFileTypes: true })) {
+      if (files.length >= maxFiles) return;
+      const full = join(dir, e.name);
+      if (e.isDirectory()) { if (!SKIP_DIR.has(e.name)) await walk(full); continue; }
+      const rel = relative(root, full).replace(/\\/g, '/');
+      const size = (await stat(full)).size;
+      if (SECRET.test(rel) || BINARY.test(rel) || size > maxFileBytes) { skipped.push(rel); continue; }
+      const content = await readFile(full, 'utf8');
+      if (content.includes('\u0000')) { skipped.push(rel); continue; }
+      files.push({ path: rel, content });
+    }
+  };
+  if (s.isDirectory()) await walk(root);
+  else if (!SECRET.test(root)) files.push({ path: basename(root), content: await readFile(root, 'utf8') });
+  return { files, skipped };
+}
+
+export function toSarif(result) {
+  const level = (s) => (s === 'Critical' || s === 'High' ? 'error' : s === 'Medium' ? 'warning' : 'note');
+  return {
+    version: '2.1.0', $schema: 'https://json.schemastore.org/sarif-2.1.0.json',
+    runs: [{
+      tool: { driver: { name: 'Hackaiz Import Gate', informationUri: 'https://hackaiz.com/check', rules: [...new Map((result.findings ?? []).map((f) => [f.rule, { id: f.rule, shortDescription: { text: f.title }, help: { text: f.action }, properties: { cwe: f.cwe, owasp: f.owasp } }])).values()] } },
+      results: (result.findings ?? []).map((f) => ({ ruleId: f.rule, level: level(f.severity), message: { text: `${f.title}: ${f.impact}` }, locations: [{ physicalLocation: { artifactLocation: { uri: f.file }, region: { startLine: f.line } } }] })),
+    }],
+  };
+}
+
+export async function checkCommand(target, flags, { env, fetcher, output }) {
+  if (!target) throw Error('Usage: hackaiz check <path> [--sarif] [--lang fr]');
+  const origin = new URL(env.HACKAIZ_URL ?? 'https://hackaiz.com');
+  if (origin.protocol !== 'https:' || origin.pathname !== '/' || origin.username) throw Error('HACKAIZ_URL must be an HTTPS origin');
+  if (!/^hkz_[A-Za-z0-9_-]{40,}$/.test(env.HACKAIZ_API_KEY ?? '')) throw Error('HACKAIZ_API_KEY is required');
+  const { files } = await collectComponent(target);
+  if (!files.length) throw Error('Nothing to check (secret, binary and large files are never sent)');
+  const lang = flags.includes('--lang') && flags[flags.indexOf('--lang') + 1] === 'fr' ? 'fr' : 'en';
+  const response = await fetcher(`${origin.origin}/api/public/v1/component-checks`, {
+    method: 'POST', redirect: 'error', headers: { authorization: `Bearer ${env.HACKAIZ_API_KEY}`, 'content-type': 'application/json' },
+    body: JSON.stringify({ request_id: randomUUID(), channel: env.GITHUB_ACTIONS === 'true' ? 'ci' : 'cli', name: basename(target).slice(0, 120) || 'component', language: lang, files }),
+  });
+  const data = await response.json();
+  if (!response.ok) throw Error(`Hackaiz ${response.status}: ${data.error ?? 'request_failed'}`);
+  output(JSON.stringify(flags.includes('--sarif') ? toSarif(data) : data, null, 2));
+  return data.verdict === 'danger' ? 2 : 0;
+}

package/bin/gate.mjs

@@ -0,0 +1,6 @@
+/** A gate refers to one saved-platform run, never to an inferred PR commit. */
+export function savedRunGate(analysis, findings) {
+  if (analysis?.status !== 'success') return { verdict: 'inconclusive', reason: 'analysis_not_complete', exitCode: 2 };
+  const dangerous = findings.filter(f => ['critical', 'high'].includes(String(f.severity).toLowerCase()) && f.status !== 'resolved');
+  return dangerous.length ? { verdict: 'fail', unresolvedHighOrCritical: dangerous.length, exitCode: 1 } : { verdict: 'pass', unresolvedHighOrCritical: 0, exitCode: 0 };
+}

package/bin/hackaiz.mjs

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+import { randomUUID } from 'node:crypto';
+import { pathToFileURL } from 'node:url';
+import { savedRunGate } from './gate.mjs';
+
+export async function run(args, { env = process.env, fetcher = fetch, output = console.log, stdin, errorOut, wait = (ms) => new Promise(resolve => setTimeout(resolve, ms)) } = {}) {
+  const [command, projectId, value] = args;
+  if (command === 'help' || !command) {
+    output('hackaiz analyze <project-id> [request-key]\nhackaiz status <project-id> <run-id>\nhackaiz verify <project-id> <run-id>\nhackaiz report <project-id>\nhackaiz findings <project-id>\nhackaiz check <path> [--sarif] [--lang fr]  (Skill/MCP/package/workflow before installing; exit 2 on Danger)\nhackaiz hook claude  (Claude Code PreToolUse hook: blocks Danger Skills/MCP/installs)\nHACKAIZ_API_KEY: personal key. HACKAIZ_URL: optional HTTPS origin.');
+    return 0;
+  }
+  if (command === 'hook') {
+    const { hookCommand } = await import('./hook.mjs');
+    const chunks = []; for await (const c of (stdin ?? process.stdin)) chunks.push(c);
+    return hookCommand({ env, fetcher, stdin: Buffer.concat(chunks.map((c) => Buffer.from(c))).toString('utf8'), errorOut: errorOut ?? console.error });
+  }
+  if (command === 'check') {
+    const { checkCommand } = await import('./check.mjs');
+    return checkCommand(projectId, args.slice(2), { env, fetcher, output });
+  }
+  if (!['analyze', 'status', 'verify', 'report', 'findings'].includes(command)) throw Error('Unsupported command');
+  if (!/^[0-9a-f-]{36}$/i.test(projectId ?? '')) throw Error('A platform UUID is required');
+  const origin = new URL(env.HACKAIZ_URL ?? 'https://hackaiz.com');
+  if (origin.protocol !== 'https:' || origin.username || origin.password || origin.pathname !== '/' || origin.search || origin.hash) throw Error('HACKAIZ_URL must be an HTTPS origin');
+  if (!/^hkz_[A-Za-z0-9_-]{40,}$/.test(env.HACKAIZ_API_KEY ?? '')) throw Error('HACKAIZ_API_KEY is required');
+  const base = `${origin.origin}/api/public/v1/projects/${projectId}`;
+  const call = async (path, body) => {
+    const response = await fetcher(`${base}/${path}`, { method: body ? 'POST' : 'GET', headers: { authorization: `Bearer ${env.HACKAIZ_API_KEY}`, 'content-type': 'application/json' }, ...(body ? { body: JSON.stringify(body) } : {}), redirect: 'error' });
+    const data = await response.json();
+    if (!response.ok) throw Error(`Hackaiz ${response.status}: ${data.error ?? 'request_failed'}${data.purchaseUrl ? ` — ${data.purchaseUrl}` : ''}`);
+    return data;
+  };
+  if (command === 'analyze') {
+    const requestKey = value ?? randomUUID();
+    const accepted = await call('analysis-requests', { request_key: requestKey, channel: env.GITHUB_ACTIONS === 'true' ? 'ci' : 'cli' });
+    if (!/^[0-9a-f-]{36}$/i.test(accepted.requestId ?? '')) throw Error('Invalid analysis response');
+    output(JSON.stringify({ requestId: accepted.requestId, requestKey, status: accepted.status }));
+    if (accepted.delivery === 'configuration_required') throw Error('Autonomous processing is not configured; keep this request ID');
+    // GET-only polling. Closing the client does not cancel autonomous work.
+    // A lost response never creates another run or invokes execution again.
+    for (let attempt = 0; attempt < 360; attempt++) {
+      const result = await call(`analysis-runs/${accepted.requestId}`);
+      const status = result.request?.status;
+      if (['success', 'partial', 'failed', 'cancelled'].includes(status)) {
+        output(JSON.stringify(result));
+        return ['success', 'partial'].includes(status) ? 0 : 2;
+      }
+      await wait(5000);
+    }
+    output(JSON.stringify({ requestId: accepted.requestId, status: 'still_pending', note: 'Use status with the same request ID; do not create a replacement.' }));
+    return 2;
+  }
+  if (command === 'status') {
+    if (!/^[0-9a-f-]{36}$/i.test(value ?? '')) throw Error('A run UUID is required');
+    output(JSON.stringify(await call(`analysis-runs/${value}`))); return 0;
+  }
+  if (command === 'verify') {
+    if (!/^[0-9a-f-]{36}$/i.test(value ?? '')) throw Error('A run UUID is required');
+    const status = await call(`analysis-runs/${value}`);
+    const scan = status.analysis;
+    if (!scan || !/^[0-9a-f-]{36}$/i.test(scan.id ?? '') || status.request?.scan_id !== scan.id || scan.status !== 'success') {
+      output(JSON.stringify({ verdict: 'inconclusive', reason: 'analysis_not_complete_or_unlinked', runId: value }));
+      return 2;
+    }
+    const findings = []; const seen = new Set(); let offset = 0; let total;
+    for (;;) {
+      const result = await call(`findings?scanId=${scan.id}&status=open&limit=100&offset=${offset}`);
+      const invalid = !Array.isArray(result.data) || !Number.isSafeInteger(result.total) || result.total < 0 || result.total > 100000 || (total !== undefined && result.total !== total)
+        || result.data.length > 100 || offset + result.data.length > result.total || (!result.data.length && offset < result.total)
+        || result.data.some(f => !f || f.scan_id !== scan.id || typeof f.id !== 'string' || !f.id || seen.has(f.id) || !['critical', 'high', 'medium', 'low', 'info'].includes(String(f.severity).toLowerCase()) || f.status !== 'open');
+      if (invalid || (Array.isArray(result.data) && new Set(result.data.map(f => f.id)).size !== result.data.length)) {
+        output(JSON.stringify({ verdict: 'inconclusive', reason: 'invalid_findings_pagination', runId: value, scanId: scan.id }));
+        return 2;
+      }
+      total = result.total;
+      result.data.forEach(f => seen.add(f.id));
+      findings.push(...result.data); offset += result.data.length;
+      if (offset === total) break;
+    }
+    const verdict = savedRunGate(scan, findings);
+    output(JSON.stringify({ ...verdict, runId: value, scanId: scan.id, scope: 'saved_platform_not_pr_commit' }));
+    return verdict.exitCode;
+  }
+  let offset = 0;
+  do {
+    const result = await call(`${command === 'report' ? 'scans' : 'findings'}?limit=100&offset=${offset}`);
+    output(JSON.stringify(result));
+    offset += result.data?.length ?? 0;
+    if (!result.data?.length || offset >= result.total) break;
+  } while (true);
+  return 0;
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  run(process.argv.slice(2)).then((code) => { process.exitCode = code; }).catch((error) => { console.error(error.message); process.exitCode = 1; });
+}

package/bin/hook.mjs

@@ -0,0 +1,47 @@
+// Claude Code PreToolUse hook: `hackaiz hook claude`. Reads the hook JSON on stdin.
+// Only Skill/MCP/package/workflow writes and install commands are checked (each check uses credits).
+// Exit 2 blocks Danger, incomplete or unavailable checks. HACKAIZ_HOOK_FAIL_OPEN=1 explicitly opts into advisory mode.
+import { randomUUID } from 'node:crypto';
+const COMPONENT = /(^|\/)(SKILL\.md|mcp\.json|\.mcp\.json|claude_desktop_config\.json|package\.json|requirements\.txt|Dockerfile)$|\.github\/workflows\/[^/]+\.ya?ml$/i;
+const INSTALL = /\b(claude\s+mcp\s+add|npx\s+-y|npm\s+(i|install|add)\b|pnpm\s+add|yarn\s+add|bun\s+add|pip3?\s+install|uvx|pipx\s+install)\b|\b(curl|wget)\b[^|]*\|\s*(ba|z)?sh\b/i;
+
+export function hookTarget(event) {
+  const tool = event?.tool_name; const input = event?.tool_input ?? {};
+  if (['Write', 'Edit', 'MultiEdit'].includes(tool) && typeof input.file_path === 'string' && COMPONENT.test(input.file_path.replace(/\\/g, '/'))) {
+    const content = tool === 'Write' ? input.content : tool === 'Edit' ? input.new_string : (input.edits ?? []).map((e) => e.new_string).join('\n');
+    if (typeof content === 'string' && content) return { name: input.file_path.split(/[\\/]/).slice(-2).join('/'), files: [{ path: input.file_path.split(/[\\/]/).pop(), content }] };
+  }
+  if (tool === 'Bash' && typeof input.command === 'string' && INSTALL.test(input.command)) return { name: 'install-command', files: [{ path: 'install.sh', content: input.command }] };
+  return null;
+}
+
+export async function hookCommand({ env, fetcher, stdin, errorOut }) {
+  const fr = env.HACKAIZ_LANG === 'fr';
+  const unavailable = (detail = '') => {
+    errorOut(fr ? `Vérification Hackaiz indisponible${detail} ; action non vérifiée.` : `Hackaiz check unavailable${detail}; action not checked.`);
+    return env.HACKAIZ_HOOK_FAIL_OPEN === '1' ? 0 : 2;
+  };
+  let event; try { event = JSON.parse(stdin); } catch { return unavailable(); }
+  const target = hookTarget(event);
+  if (!target) return 0;
+  if (!/^hkz_[A-Za-z0-9_-]{40,}$/.test(env.HACKAIZ_API_KEY ?? '')) return unavailable();
+  try {
+    const origin = new URL(env.HACKAIZ_URL ?? 'https://hackaiz.com');
+    if (origin.protocol !== 'https:' || origin.username || origin.password || origin.pathname !== '/' || origin.search || origin.hash) return unavailable();
+    // Opting into this hook authorizes paid checks, not automatic installation on a missing verdict.
+    const r = await fetcher(`${origin.origin}/api/public/v1/component-checks`, {
+      method: 'POST', redirect: 'error', headers: { authorization: `Bearer ${env.HACKAIZ_API_KEY}`, 'content-type': 'application/json' },
+      signal: AbortSignal.timeout(30_000),
+      body: JSON.stringify({ request_id: randomUUID(), channel: 'hook', name: target.name.slice(0, 120), language: env.HACKAIZ_LANG === 'fr' ? 'fr' : 'en', files: target.files }),
+    });
+    const data = await r.json();
+    if (!r.ok) return unavailable(` (${r.status})`);
+    if (data.verdict === 'danger') {
+      errorOut(`${fr ? 'Hackaiz bloque cette action' : 'Hackaiz blocked this'}: ${data.headline}. ${data.summary} ${(data.findings ?? []).slice(0, 3).map((f) => `[${f.rule}] ${f.title} (${f.file}:${f.line})`).join(' ')}`);
+      return 2;
+    }
+    if (data.complete !== true || !['safe', 'attention'].includes(data.verdict)) return unavailable();
+    if (data.verdict === 'attention') errorOut(`${data.headline}. ${data.summary}`);
+    return 0;
+  } catch { return unavailable(); }
+}

package/package.json

@@ -1,6 +1,32 @@
-{
-  "name": "@hackaiz/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "@hackaiz/cli",
+  "version": "0.1.1",
+  "description": "Hackaiz command-line client: run passive security analyses and check components before you install them",
+  "type": "module",
+  "bin": {
+    "hackaiz": "bin/hackaiz.mjs"
+  },
+  "files": [
+    "bin",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "test": "node --test test/*.check.mjs"
+  },
+  "license": "MIT",
+  "homepage": "https://hackaiz.com/tools",
+  "keywords": [
+    "security",
+    "cli",
+    "sast",
+    "mcp",
+    "skills",
+    "claude-code",
+    "supply-chain",
+    "hackaiz"
+  ]
+}