specter-sdk 0.1.0

package/README.md

@@ -0,0 +1,73 @@
+# specter-sdk
+
+Thin client for **[Specter](https://specter-ia.vercel.app)** — the *detect → block → prove* firewall / decision API for **AI-agent payments**. It inspects every money-moving action an agent attempts and proves where the destination came from (the user's request, or content the agent ingested mid-task — i.e. prompt injection).
+
+The SDK is the thin "plug"; the decision API is the product. **Zero runtime dependencies.**
+
+```bash
+npm i specter-sdk
+```
+
+## Guard — check an action programmatically
+
+```ts
+import { Guard } from 'specter-sdk';
+
+const guard = new Guard({
+  apiUrl: 'https://specter-decision-api.fly.dev',
+  apiKey: process.env.SPECTER_API_KEY!, // your tenant key
+});
+
+const result = await guard.check({
+  agentId: 'shop-agent',
+  action: {
+    type: 'payment',
+    amount: 79.99,
+    currency: 'USD',
+    destination: 'acct_attacker_x9f3',
+    merchantClaimed: 'Acme Store',
+  },
+  context: {
+    userPrompt: 'Buy the Acme mouse from Acme Store',
+    destinationOrigin: 'ingested_content', // came from a scraped page, not the user
+    sourceRefs: ['firecrawl:https://shop.example/acme'],
+    establishedMerchant: 'Acme Store',
+  },
+});
+
+if (result.decision !== 'allow') {
+  // result.decision: 'deny' | 'review' · result.reason · result.riskScore
+  throw new Error(`Blocked by Specter: ${result.reason}`);
+}
+// safe to execute the payment
+
+// convenience:
+if (await guard.isAllowed({ action })) { /* ... */ }
+```
+
+## Claude Code — drop-in PreToolUse hook
+
+```ts
+import { Guard, createClaudeCodeHook } from 'specter-sdk';
+
+const handle = createClaudeCodeHook(
+  new Guard({ apiUrl: '…', apiKey: '…' }),
+);
+
+// In your hook server, return the handler's response with HTTP 200:
+const response = await handle(claudeCodePayload);
+// → { hookSpecificOutput: { permissionDecision: 'allow' | 'deny' | 'ask', ... } }
+```
+
+> Claude Code only blocks on an HTTP **200** whose body says
+> `permissionDecision: "deny"`. A non-2xx merely logs and the tool runs anyway —
+> so your host must answer 200 with this body. Fails safe to `ask` on any error.
+
+## Types
+
+`Guard`, `GuardOptions`, `CheckInput`, `createClaudeCodeHook`, `HookPayload`,
+`HookResponse`, and the action/decision types (`Action`, `Context`,
+`DecisionResult`, `Decision`, `ActionType`, `DestinationOrigin`, `SignalResult`)
+are all exported.
+
+MIT · [github.com/Eras256/Specter](https://github.com/Eras256/Specter)

package/index.cjs

@@ -0,0 +1,113 @@
+'use strict';
+
+// src/claude-code-hook.ts
+function createClaudeCodeHook(guard) {
+  return async function handle(payload) {
+    try {
+      const action = normalize(payload);
+      const result = await guard.check({
+        agentId: `claude-code:${payload.tool_name ?? "tool"}`,
+        sessionId: payload.session_id ?? "cc-session",
+        action,
+        context: {
+          userPrompt: payload.specter?.userPrompt ?? "",
+          establishedMerchant: payload.specter?.establishedMerchant,
+          destinationOrigin: payload.specter?.destinationOrigin ?? "unknown"
+        }
+      });
+      const permissionDecision = result.decision === "allow" ? "allow" : result.decision === "deny" ? "deny" : "ask";
+      return resp(permissionDecision, result.reason);
+    } catch (err) {
+      return resp("ask", `Specter unavailable, escalating: ${err.message}`);
+    }
+  };
+}
+function resp(permissionDecision, permissionDecisionReason) {
+  return {
+    hookSpecificOutput: {
+      hookEventName: "PreToolUse",
+      permissionDecision,
+      permissionDecisionReason
+    }
+  };
+}
+function normalize(p) {
+  const tool = p.tool_name ?? "unknown";
+  const ti = p.tool_input ?? {};
+  const amount = typeof ti.amount === "number" ? ti.amount : void 0;
+  const destination = str(ti.destination) ?? str(ti.to) ?? str(ti.account) ?? void 0;
+  let type = "other";
+  let command;
+  if (amount != null || destination) type = "payment";
+  else if (tool === "Bash") {
+    type = "shell";
+    command = str(ti.command);
+  } else if (["Read", "Write", "Edit", "NotebookEdit"].includes(tool)) {
+    type = "file";
+    command = str(ti.file_path) ?? str(ti.path);
+  } else command = JSON.stringify(ti);
+  return {
+    type,
+    amount,
+    currency: str(ti.currency),
+    destination,
+    merchantClaimed: str(ti.merchantClaimed),
+    command,
+    rawInput: ti
+  };
+}
+function str(v) {
+  return typeof v === "string" && v.length ? v : void 0;
+}
+
+// src/guard.ts
+var Guard = class {
+  constructor(opts) {
+    this.opts = opts;
+  }
+  opts;
+  async check(input) {
+    const body = {
+      agentId: input.agentId ?? this.opts.agentId ?? "sdk-agent",
+      sessionId: input.sessionId ?? "sdk-session",
+      action: input.action,
+      context: {
+        userPrompt: input.context?.userPrompt ?? "",
+        destinationOrigin: input.context?.destinationOrigin ?? "unknown",
+        sourceRefs: input.context?.sourceRefs ?? [],
+        establishedMerchant: input.context?.establishedMerchant
+      }
+    };
+    const retries = this.opts.retries ?? 1;
+    let lastErr;
+    for (let attempt = 0; attempt <= retries; attempt++) {
+      try {
+        const res = await fetch(`${this.opts.apiUrl.replace(/\/$/, "")}/v1/evaluate`, {
+          method: "POST",
+          headers: {
+            "content-type": "application/json",
+            authorization: `Bearer ${this.opts.apiKey}`
+          },
+          body: JSON.stringify(body),
+          signal: AbortSignal.timeout(this.opts.timeoutMs ?? 4e3)
+        });
+        if (!res.ok) throw new Error(`Specter API ${res.status}: ${await res.text()}`);
+        return await res.json();
+      } catch (err) {
+        lastErr = err;
+      }
+    }
+    throw new Error(
+      `Specter check failed after ${retries + 1} attempts: ${lastErr.message}`
+    );
+  }
+  /** Convenience: true only when the action is explicitly allowed. */
+  async isAllowed(input) {
+    return (await this.check(input)).decision === "allow";
+  }
+};
+
+exports.Guard = Guard;
+exports.createClaudeCodeHook = createClaudeCodeHook;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/claude-code-hook.ts","../src/guard.ts"],"names":[],"mappings":"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","file":"index.cjs","sourcesContent":["import type { Guard } from './guard.js';\nimport type { Action, ActionType, DestinationOrigin } from './types.js';\n\n/** Claude Code PreToolUse hook payload (subset). */\nexport interface HookPayload {\n  session_id?: string;\n  tool_name?: string;\n  tool_input?: Record<string, unknown>;\n  specter?: { userPrompt?: string; establishedMerchant?: string; destinationOrigin?: string };\n}\n\n/** The body Claude Code requires to actually block. */\nexport interface HookResponse {\n  hookSpecificOutput: {\n    hookEventName: 'PreToolUse';\n    permissionDecision: 'allow' | 'deny' | 'ask';\n    permissionDecisionReason: string;\n  };\n}\n\n/**\n * Build a ready-made Claude Code PreToolUse hook handler from a Guard.\n *\n * IMPORTANT: when wired as an HTTP hook, Claude Code only blocks on an HTTP 200\n * whose body says permissionDecision: \"deny\". A non-2xx status merely logs and\n * the tool runs anyway. This handler returns the correct body; the host (the\n * decision API's /hooks/claude-code route, or your own server) must answer 200.\n */\nexport function createClaudeCodeHook(guard: Guard) {\n  return async function handle(payload: HookPayload): Promise<HookResponse> {\n    try {\n      const action = normalize(payload);\n      const result = await guard.check({\n        agentId: `claude-code:${payload.tool_name ?? 'tool'}`,\n        sessionId: payload.session_id ?? 'cc-session',\n        action,\n        context: {\n          userPrompt: payload.specter?.userPrompt ?? '',\n          establishedMerchant: payload.specter?.establishedMerchant,\n          destinationOrigin: (payload.specter?.destinationOrigin as DestinationOrigin) ?? 'unknown',\n        },\n      });\n      const permissionDecision =\n        result.decision === 'allow' ? 'allow' : result.decision === 'deny' ? 'deny' : 'ask';\n      return resp(permissionDecision, result.reason);\n    } catch (err) {\n      // Fail safe: escalate to a human rather than silently allowing.\n      return resp('ask', `Specter unavailable, escalating: ${(err as Error).message}`);\n    }\n  };\n}\n\nfunction resp(\n  permissionDecision: 'allow' | 'deny' | 'ask',\n  permissionDecisionReason: string,\n): HookResponse {\n  return {\n    hookSpecificOutput: {\n      hookEventName: 'PreToolUse',\n      permissionDecision,\n      permissionDecisionReason,\n    },\n  };\n}\n\nfunction normalize(p: HookPayload): Action {\n  const tool = p.tool_name ?? 'unknown';\n  const ti = p.tool_input ?? {};\n  const amount = typeof ti.amount === 'number' ? ti.amount : undefined;\n  const destination = str(ti.destination) ?? str(ti.to) ?? str(ti.account) ?? undefined;\n\n  let type: ActionType = 'other';\n  let command: string | undefined;\n  if (amount != null || destination) type = 'payment';\n  else if (tool === 'Bash') {\n    type = 'shell';\n    command = str(ti.command);\n  } else if (['Read', 'Write', 'Edit', 'NotebookEdit'].includes(tool)) {\n    type = 'file';\n    command = str(ti.file_path) ?? str(ti.path);\n  } else command = JSON.stringify(ti);\n\n  return {\n    type,\n    amount,\n    currency: str(ti.currency),\n    destination,\n    merchantClaimed: str(ti.merchantClaimed),\n    command,\n    rawInput: ti,\n  };\n}\n\nfunction str(v: unknown): string | undefined {\n  return typeof v === 'string' && v.length ? v : undefined;\n}\n","import type { Action, Context, DecisionResult } from './types.js';\n\nexport interface GuardOptions {\n  apiUrl: string;\n  apiKey: string;\n  /** Per-request timeout in ms (default 4000). The gate targets <500ms p99. */\n  timeoutMs?: number;\n  /** Retry attempts on network/5xx (default 1). */\n  retries?: number;\n  agentId?: string;\n}\n\nexport interface CheckInput {\n  agentId?: string;\n  sessionId?: string;\n  action: Action;\n  context?: Partial<Context>;\n}\n\n/**\n * Thin, typed client for the Specter decision API. The whole SDK is the \"plug\";\n * the API is the product. Use `guard.check(action, context)` programmatically,\n * or `createClaudeCodeHook(guard)` for the drop-in Claude Code hook.\n */\nexport class Guard {\n  constructor(private opts: GuardOptions) {}\n\n  async check(input: CheckInput): Promise<DecisionResult> {\n    const body = {\n      agentId: input.agentId ?? this.opts.agentId ?? 'sdk-agent',\n      sessionId: input.sessionId ?? 'sdk-session',\n      action: input.action,\n      context: {\n        userPrompt: input.context?.userPrompt ?? '',\n        destinationOrigin: input.context?.destinationOrigin ?? 'unknown',\n        sourceRefs: input.context?.sourceRefs ?? [],\n        establishedMerchant: input.context?.establishedMerchant,\n      },\n    };\n\n    const retries = this.opts.retries ?? 1;\n    let lastErr: unknown;\n    for (let attempt = 0; attempt <= retries; attempt++) {\n      try {\n        const res = await fetch(`${this.opts.apiUrl.replace(/\\/$/, '')}/v1/evaluate`, {\n          method: 'POST',\n          headers: {\n            'content-type': 'application/json',\n            authorization: `Bearer ${this.opts.apiKey}`,\n          },\n          body: JSON.stringify(body),\n          signal: AbortSignal.timeout(this.opts.timeoutMs ?? 4000),\n        });\n        if (!res.ok) throw new Error(`Specter API ${res.status}: ${await res.text()}`);\n        return (await res.json()) as DecisionResult;\n      } catch (err) {\n        lastErr = err;\n      }\n    }\n    throw new Error(\n      `Specter check failed after ${retries + 1} attempts: ${(lastErr as Error).message}`,\n    );\n  }\n\n  /** Convenience: true only when the action is explicitly allowed. */\n  async isAllowed(input: CheckInput): Promise<boolean> {\n    return (await this.check(input)).decision === 'allow';\n  }\n}\n"]}

package/index.d.cts

@@ -0,0 +1,99 @@
+type ActionType = 'payment' | 'db_write' | 'shell' | 'file' | 'refund' | 'other';
+type DestinationOrigin = 'user_prompt' | 'ingested_content' | 'tool_output' | 'unknown';
+type Decision = 'allow' | 'deny' | 'review';
+interface Action {
+    type: ActionType;
+    amount?: number;
+    currency?: string;
+    /** Payee / account / target identifier. */
+    destination?: string;
+    /** The merchant the action claims it is paying. */
+    merchantClaimed?: string;
+    /** Merchant category, when known. */
+    category?: string;
+    /** For shell / db_write / file actions. */
+    command?: string;
+    /** Whatever the agent actually passed — kept for the audit record. */
+    rawInput?: unknown;
+}
+interface Context {
+    /** The original human instruction that started the task. */
+    userPrompt: string;
+    /** Adapter-declared origin of the destination. */
+    destinationOrigin: DestinationOrigin;
+    /** Provenance breadcrumbs, e.g. ["firecrawl:https://shop.example/item"]. */
+    sourceRefs: string[];
+    /** The merchant established at task start (before any ingestion), if any. */
+    establishedMerchant?: string;
+}
+interface SignalResult {
+    id: string;
+    score: number;
+    verdict: string;
+}
+interface DecisionResult {
+    decision: Decision;
+    riskScore: number;
+    reason: string;
+    signals: Record<string, string>;
+    signalDetail: SignalResult[];
+}
+
+interface GuardOptions {
+    apiUrl: string;
+    apiKey: string;
+    /** Per-request timeout in ms (default 4000). The gate targets <500ms p99. */
+    timeoutMs?: number;
+    /** Retry attempts on network/5xx (default 1). */
+    retries?: number;
+    agentId?: string;
+}
+interface CheckInput {
+    agentId?: string;
+    sessionId?: string;
+    action: Action;
+    context?: Partial<Context>;
+}
+/**
+ * Thin, typed client for the Specter decision API. The whole SDK is the "plug";
+ * the API is the product. Use `guard.check(action, context)` programmatically,
+ * or `createClaudeCodeHook(guard)` for the drop-in Claude Code hook.
+ */
+declare class Guard {
+    private opts;
+    constructor(opts: GuardOptions);
+    check(input: CheckInput): Promise<DecisionResult>;
+    /** Convenience: true only when the action is explicitly allowed. */
+    isAllowed(input: CheckInput): Promise<boolean>;
+}
+
+/** Claude Code PreToolUse hook payload (subset). */
+interface HookPayload {
+    session_id?: string;
+    tool_name?: string;
+    tool_input?: Record<string, unknown>;
+    specter?: {
+        userPrompt?: string;
+        establishedMerchant?: string;
+        destinationOrigin?: string;
+    };
+}
+/** The body Claude Code requires to actually block. */
+interface HookResponse {
+    hookSpecificOutput: {
+        hookEventName: 'PreToolUse';
+        permissionDecision: 'allow' | 'deny' | 'ask';
+        permissionDecisionReason: string;
+    };
+}
+/**
+ * Build a ready-made Claude Code PreToolUse hook handler from a Guard.
+ *
+ * IMPORTANT: when wired as an HTTP hook, Claude Code only blocks on an HTTP 200
+ * whose body says permissionDecision: "deny". A non-2xx status merely logs and
+ * the tool runs anyway. This handler returns the correct body; the host (the
+ * decision API's /hooks/claude-code route, or your own server) must answer 200.
+ */
+declare function createClaudeCodeHook(guard: Guard): (payload: HookPayload) => Promise<HookResponse>;
+
+export { type Action, type ActionType, type CheckInput, type Context, type Decision, type DecisionResult, type DestinationOrigin, Guard, type GuardOptions, type HookPayload, type HookResponse, type SignalResult, createClaudeCodeHook };

package/index.d.ts

@@ -0,0 +1,99 @@
+type ActionType = 'payment' | 'db_write' | 'shell' | 'file' | 'refund' | 'other';
+type DestinationOrigin = 'user_prompt' | 'ingested_content' | 'tool_output' | 'unknown';
+type Decision = 'allow' | 'deny' | 'review';
+interface Action {
+    type: ActionType;
+    amount?: number;
+    currency?: string;
+    /** Payee / account / target identifier. */
+    destination?: string;
+    /** The merchant the action claims it is paying. */
+    merchantClaimed?: string;
+    /** Merchant category, when known. */
+    category?: string;
+    /** For shell / db_write / file actions. */
+    command?: string;
+    /** Whatever the agent actually passed — kept for the audit record. */
+    rawInput?: unknown;
+}
+interface Context {
+    /** The original human instruction that started the task. */
+    userPrompt: string;
+    /** Adapter-declared origin of the destination. */
+    destinationOrigin: DestinationOrigin;
+    /** Provenance breadcrumbs, e.g. ["firecrawl:https://shop.example/item"]. */
+    sourceRefs: string[];
+    /** The merchant established at task start (before any ingestion), if any. */
+    establishedMerchant?: string;
+}
+interface SignalResult {
+    id: string;
+    score: number;
+    verdict: string;
+}
+interface DecisionResult {
+    decision: Decision;
+    riskScore: number;
+    reason: string;
+    signals: Record<string, string>;
+    signalDetail: SignalResult[];
+}
+
+interface GuardOptions {
+    apiUrl: string;
+    apiKey: string;
+    /** Per-request timeout in ms (default 4000). The gate targets <500ms p99. */
+    timeoutMs?: number;
+    /** Retry attempts on network/5xx (default 1). */
+    retries?: number;
+    agentId?: string;
+}
+interface CheckInput {
+    agentId?: string;
+    sessionId?: string;
+    action: Action;
+    context?: Partial<Context>;
+}
+/**
+ * Thin, typed client for the Specter decision API. The whole SDK is the "plug";
+ * the API is the product. Use `guard.check(action, context)` programmatically,
+ * or `createClaudeCodeHook(guard)` for the drop-in Claude Code hook.
+ */
+declare class Guard {
+    private opts;
+    constructor(opts: GuardOptions);
+    check(input: CheckInput): Promise<DecisionResult>;
+    /** Convenience: true only when the action is explicitly allowed. */
+    isAllowed(input: CheckInput): Promise<boolean>;
+}
+
+/** Claude Code PreToolUse hook payload (subset). */
+interface HookPayload {
+    session_id?: string;
+    tool_name?: string;
+    tool_input?: Record<string, unknown>;
+    specter?: {
+        userPrompt?: string;
+        establishedMerchant?: string;
+        destinationOrigin?: string;
+    };
+}
+/** The body Claude Code requires to actually block. */
+interface HookResponse {
+    hookSpecificOutput: {
+        hookEventName: 'PreToolUse';
+        permissionDecision: 'allow' | 'deny' | 'ask';
+        permissionDecisionReason: string;
+    };
+}
+/**
+ * Build a ready-made Claude Code PreToolUse hook handler from a Guard.
+ *
+ * IMPORTANT: when wired as an HTTP hook, Claude Code only blocks on an HTTP 200
+ * whose body says permissionDecision: "deny". A non-2xx status merely logs and
+ * the tool runs anyway. This handler returns the correct body; the host (the
+ * decision API's /hooks/claude-code route, or your own server) must answer 200.
+ */
+declare function createClaudeCodeHook(guard: Guard): (payload: HookPayload) => Promise<HookResponse>;
+
+export { type Action, type ActionType, type CheckInput, type Context, type Decision, type DecisionResult, type DestinationOrigin, Guard, type GuardOptions, type HookPayload, type HookResponse, type SignalResult, createClaudeCodeHook };

package/index.js

@@ -0,0 +1,110 @@
+// src/claude-code-hook.ts
+function createClaudeCodeHook(guard) {
+  return async function handle(payload) {
+    try {
+      const action = normalize(payload);
+      const result = await guard.check({
+        agentId: `claude-code:${payload.tool_name ?? "tool"}`,
+        sessionId: payload.session_id ?? "cc-session",
+        action,
+        context: {
+          userPrompt: payload.specter?.userPrompt ?? "",
+          establishedMerchant: payload.specter?.establishedMerchant,
+          destinationOrigin: payload.specter?.destinationOrigin ?? "unknown"
+        }
+      });
+      const permissionDecision = result.decision === "allow" ? "allow" : result.decision === "deny" ? "deny" : "ask";
+      return resp(permissionDecision, result.reason);
+    } catch (err) {
+      return resp("ask", `Specter unavailable, escalating: ${err.message}`);
+    }
+  };
+}
+function resp(permissionDecision, permissionDecisionReason) {
+  return {
+    hookSpecificOutput: {
+      hookEventName: "PreToolUse",
+      permissionDecision,
+      permissionDecisionReason
+    }
+  };
+}
+function normalize(p) {
+  const tool = p.tool_name ?? "unknown";
+  const ti = p.tool_input ?? {};
+  const amount = typeof ti.amount === "number" ? ti.amount : void 0;
+  const destination = str(ti.destination) ?? str(ti.to) ?? str(ti.account) ?? void 0;
+  let type = "other";
+  let command;
+  if (amount != null || destination) type = "payment";
+  else if (tool === "Bash") {
+    type = "shell";
+    command = str(ti.command);
+  } else if (["Read", "Write", "Edit", "NotebookEdit"].includes(tool)) {
+    type = "file";
+    command = str(ti.file_path) ?? str(ti.path);
+  } else command = JSON.stringify(ti);
+  return {
+    type,
+    amount,
+    currency: str(ti.currency),
+    destination,
+    merchantClaimed: str(ti.merchantClaimed),
+    command,
+    rawInput: ti
+  };
+}
+function str(v) {
+  return typeof v === "string" && v.length ? v : void 0;
+}
+
+// src/guard.ts
+var Guard = class {
+  constructor(opts) {
+    this.opts = opts;
+  }
+  opts;
+  async check(input) {
+    const body = {
+      agentId: input.agentId ?? this.opts.agentId ?? "sdk-agent",
+      sessionId: input.sessionId ?? "sdk-session",
+      action: input.action,
+      context: {
+        userPrompt: input.context?.userPrompt ?? "",
+        destinationOrigin: input.context?.destinationOrigin ?? "unknown",
+        sourceRefs: input.context?.sourceRefs ?? [],
+        establishedMerchant: input.context?.establishedMerchant
+      }
+    };
+    const retries = this.opts.retries ?? 1;
+    let lastErr;
+    for (let attempt = 0; attempt <= retries; attempt++) {
+      try {
+        const res = await fetch(`${this.opts.apiUrl.replace(/\/$/, "")}/v1/evaluate`, {
+          method: "POST",
+          headers: {
+            "content-type": "application/json",
+            authorization: `Bearer ${this.opts.apiKey}`
+          },
+          body: JSON.stringify(body),
+          signal: AbortSignal.timeout(this.opts.timeoutMs ?? 4e3)
+        });
+        if (!res.ok) throw new Error(`Specter API ${res.status}: ${await res.text()}`);
+        return await res.json();
+      } catch (err) {
+        lastErr = err;
+      }
+    }
+    throw new Error(
+      `Specter check failed after ${retries + 1} attempts: ${lastErr.message}`
+    );
+  }
+  /** Convenience: true only when the action is explicitly allowed. */
+  async isAllowed(input) {
+    return (await this.check(input)).decision === "allow";
+  }
+};
+
+export { Guard, createClaudeCodeHook };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/claude-code-hook.ts","../src/guard.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["import type { Guard } from './guard.js';\nimport type { Action, ActionType, DestinationOrigin } from './types.js';\n\n/** Claude Code PreToolUse hook payload (subset). */\nexport interface HookPayload {\n  session_id?: string;\n  tool_name?: string;\n  tool_input?: Record<string, unknown>;\n  specter?: { userPrompt?: string; establishedMerchant?: string; destinationOrigin?: string };\n}\n\n/** The body Claude Code requires to actually block. */\nexport interface HookResponse {\n  hookSpecificOutput: {\n    hookEventName: 'PreToolUse';\n    permissionDecision: 'allow' | 'deny' | 'ask';\n    permissionDecisionReason: string;\n  };\n}\n\n/**\n * Build a ready-made Claude Code PreToolUse hook handler from a Guard.\n *\n * IMPORTANT: when wired as an HTTP hook, Claude Code only blocks on an HTTP 200\n * whose body says permissionDecision: \"deny\". A non-2xx status merely logs and\n * the tool runs anyway. This handler returns the correct body; the host (the\n * decision API's /hooks/claude-code route, or your own server) must answer 200.\n */\nexport function createClaudeCodeHook(guard: Guard) {\n  return async function handle(payload: HookPayload): Promise<HookResponse> {\n    try {\n      const action = normalize(payload);\n      const result = await guard.check({\n        agentId: `claude-code:${payload.tool_name ?? 'tool'}`,\n        sessionId: payload.session_id ?? 'cc-session',\n        action,\n        context: {\n          userPrompt: payload.specter?.userPrompt ?? '',\n          establishedMerchant: payload.specter?.establishedMerchant,\n          destinationOrigin: (payload.specter?.destinationOrigin as DestinationOrigin) ?? 'unknown',\n        },\n      });\n      const permissionDecision =\n        result.decision === 'allow' ? 'allow' : result.decision === 'deny' ? 'deny' : 'ask';\n      return resp(permissionDecision, result.reason);\n    } catch (err) {\n      // Fail safe: escalate to a human rather than silently allowing.\n      return resp('ask', `Specter unavailable, escalating: ${(err as Error).message}`);\n    }\n  };\n}\n\nfunction resp(\n  permissionDecision: 'allow' | 'deny' | 'ask',\n  permissionDecisionReason: string,\n): HookResponse {\n  return {\n    hookSpecificOutput: {\n      hookEventName: 'PreToolUse',\n      permissionDecision,\n      permissionDecisionReason,\n    },\n  };\n}\n\nfunction normalize(p: HookPayload): Action {\n  const tool = p.tool_name ?? 'unknown';\n  const ti = p.tool_input ?? {};\n  const amount = typeof ti.amount === 'number' ? ti.amount : undefined;\n  const destination = str(ti.destination) ?? str(ti.to) ?? str(ti.account) ?? undefined;\n\n  let type: ActionType = 'other';\n  let command: string | undefined;\n  if (amount != null || destination) type = 'payment';\n  else if (tool === 'Bash') {\n    type = 'shell';\n    command = str(ti.command);\n  } else if (['Read', 'Write', 'Edit', 'NotebookEdit'].includes(tool)) {\n    type = 'file';\n    command = str(ti.file_path) ?? str(ti.path);\n  } else command = JSON.stringify(ti);\n\n  return {\n    type,\n    amount,\n    currency: str(ti.currency),\n    destination,\n    merchantClaimed: str(ti.merchantClaimed),\n    command,\n    rawInput: ti,\n  };\n}\n\nfunction str(v: unknown): string | undefined {\n  return typeof v === 'string' && v.length ? v : undefined;\n}\n","import type { Action, Context, DecisionResult } from './types.js';\n\nexport interface GuardOptions {\n  apiUrl: string;\n  apiKey: string;\n  /** Per-request timeout in ms (default 4000). The gate targets <500ms p99. */\n  timeoutMs?: number;\n  /** Retry attempts on network/5xx (default 1). */\n  retries?: number;\n  agentId?: string;\n}\n\nexport interface CheckInput {\n  agentId?: string;\n  sessionId?: string;\n  action: Action;\n  context?: Partial<Context>;\n}\n\n/**\n * Thin, typed client for the Specter decision API. The whole SDK is the \"plug\";\n * the API is the product. Use `guard.check(action, context)` programmatically,\n * or `createClaudeCodeHook(guard)` for the drop-in Claude Code hook.\n */\nexport class Guard {\n  constructor(private opts: GuardOptions) {}\n\n  async check(input: CheckInput): Promise<DecisionResult> {\n    const body = {\n      agentId: input.agentId ?? this.opts.agentId ?? 'sdk-agent',\n      sessionId: input.sessionId ?? 'sdk-session',\n      action: input.action,\n      context: {\n        userPrompt: input.context?.userPrompt ?? '',\n        destinationOrigin: input.context?.destinationOrigin ?? 'unknown',\n        sourceRefs: input.context?.sourceRefs ?? [],\n        establishedMerchant: input.context?.establishedMerchant,\n      },\n    };\n\n    const retries = this.opts.retries ?? 1;\n    let lastErr: unknown;\n    for (let attempt = 0; attempt <= retries; attempt++) {\n      try {\n        const res = await fetch(`${this.opts.apiUrl.replace(/\\/$/, '')}/v1/evaluate`, {\n          method: 'POST',\n          headers: {\n            'content-type': 'application/json',\n            authorization: `Bearer ${this.opts.apiKey}`,\n          },\n          body: JSON.stringify(body),\n          signal: AbortSignal.timeout(this.opts.timeoutMs ?? 4000),\n        });\n        if (!res.ok) throw new Error(`Specter API ${res.status}: ${await res.text()}`);\n        return (await res.json()) as DecisionResult;\n      } catch (err) {\n        lastErr = err;\n      }\n    }\n    throw new Error(\n      `Specter check failed after ${retries + 1} attempts: ${(lastErr as Error).message}`,\n    );\n  }\n\n  /** Convenience: true only when the action is explicitly allowed. */\n  async isAllowed(input: CheckInput): Promise<boolean> {\n    return (await this.check(input)).decision === 'allow';\n  }\n}\n"]}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "specter-sdk",
+  "version": "0.1.0",
+  "description": "Thin client for Specter — the detect → block → prove firewall / decision API for AI-agent payments. Guard.check() + a drop-in Claude Code hook. Zero dependencies.",
+  "type": "module",
+  "main": "./index.cjs",
+  "module": "./index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "import": { "types": "./index.d.ts", "default": "./index.js" },
+      "require": { "types": "./index.d.cts", "default": "./index.cjs" }
+    }
+  },
+  "sideEffects": false,
+  "license": "MIT",
+  "homepage": "https://specter-ia.vercel.app",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Eras256/Specter.git",
+    "directory": "packages/sdk"
+  },
+  "keywords": [
+    "ai-agents",
+    "agent-security",
+    "payments",
+    "prompt-injection",
+    "firewall",
+    "claude-code",
+    "specter"
+  ],
+  "engines": { "node": ">=18" },
+  "publishConfig": { "access": "public" }
+}