scopeblind-agent 1.0.0

package/dist/index.d.mts

@@ -0,0 +1,116 @@
+/**
+ * ScopeBlind Agent SDK — Cryptographic device identity for AI agents, CLIs, and SDKs.
+ *
+ * Uses DPoP (RFC 9449) to create proof-of-possession for each request.
+ * The agent generates an ES256 key pair on first use and stores it locally.
+ * Each request includes a self-signed JWT proof that binds it to the agent's key.
+ *
+ * Quick start:
+ *   npm install scopeblind-agent
+ *
+ *   import { createAgent } from 'scopeblind-agent';
+ *
+ *   const agent = await createAgent({ keyPath: '.scopeblind/agent-key.json' });
+ *
+ *   // Option 1: Get headers to attach to your own fetch
+ *   const headers = agent.headers('POST', 'https://api.example.com/endpoint');
+ *   await fetch(url, { method: 'POST', headers, body: '...' });
+ *
+ *   // Option 2: Use the built-in fetch wrapper
+ *   const res = await agent.fetch('https://api.example.com/endpoint', {
+ *     method: 'POST',
+ *     body: JSON.stringify({ data: '...' }),
+ *   });
+ *
+ * The server running `scopeblind` middleware will automatically verify the DPoP
+ * proof and identify this agent by its key hash (req.scopeblind.dpopDeviceId).
+ *
+ * Full docs: https://www.scopeblind.com/llms.txt
+ */
+interface AgentOptions {
+    /**
+     * Path to store the agent's key pair (JSON file).
+     * If the file doesn't exist, a new key pair will be generated.
+     * Default: '.scopeblind/agent-key.json'
+     */
+    keyPath?: string;
+    /**
+     * Existing JWK key pair to use instead of generating/loading from file.
+     * Useful for serverless environments or in-memory key management.
+     */
+    jwk?: {
+        publicKey: {
+            kty: string;
+            crv: string;
+            x: string;
+            y: string;
+        };
+        privateKey: {
+            kty: string;
+            crv: string;
+            x: string;
+            y: string;
+            d: string;
+        };
+    };
+}
+interface ScopeBlindAgent {
+    /** The agent's device ID (SHA-256 hash of the public key, 16 hex chars) */
+    deviceId: string;
+    /** The agent's public key as JWK */
+    publicKey: {
+        kty: string;
+        crv: string;
+        x: string;
+        y: string;
+    };
+    /**
+     * Create a DPoP proof JWT for a specific request.
+     * Returns the proof string to use as the DPoP header value.
+     */
+    createProof: (method: string, url: string) => string;
+    /**
+     * Get headers object with DPoP proof for a request.
+     * Use this to attach proof to your own fetch/axios calls.
+     */
+    headers: (method: string, url: string, extraHeaders?: Record<string, string>) => Record<string, string>;
+    /**
+     * Fetch wrapper that automatically attaches DPoP proof.
+     * Drop-in replacement for global fetch with automatic proof-of-possession.
+     */
+    fetch: (url: string, init?: RequestInit) => Promise<Response>;
+}
+declare function hashJWK(jwk: {
+    kty: string;
+    crv: string;
+    x: string;
+    y: string;
+}): string;
+/**
+ * Create a ScopeBlind agent with DPoP proof-of-possession capability.
+ *
+ * The agent generates (or loads) an ES256 key pair and creates self-signed
+ * JWT proofs per RFC 9449 for each request. The server-side `scopeblind`
+ * middleware verifies these proofs and identifies the agent by its key hash.
+ *
+ * @param options - Agent configuration
+ * @returns A ScopeBlindAgent instance with proof creation and fetch methods
+ *
+ * @example
+ * ```typescript
+ * import { createAgent } from 'scopeblind-agent';
+ *
+ * const agent = await createAgent();
+ * console.log('Agent device ID:', agent.deviceId);
+ *
+ * // Automatic DPoP proof with fetch wrapper
+ * const res = await agent.fetch('https://api.example.com/endpoint', {
+ *   method: 'POST',
+ *   headers: { 'Content-Type': 'application/json' },
+ *   body: JSON.stringify({ prompt: 'Hello' }),
+ * });
+ * ```
+ */
+declare function createAgent(options?: AgentOptions): Promise<ScopeBlindAgent>;
+
+export { type AgentOptions, type ScopeBlindAgent, createAgent, hashJWK };

package/dist/index.d.ts

@@ -0,0 +1,116 @@
+/**
+ * ScopeBlind Agent SDK — Cryptographic device identity for AI agents, CLIs, and SDKs.
+ *
+ * Uses DPoP (RFC 9449) to create proof-of-possession for each request.
+ * The agent generates an ES256 key pair on first use and stores it locally.
+ * Each request includes a self-signed JWT proof that binds it to the agent's key.
+ *
+ * Quick start:
+ *   npm install scopeblind-agent
+ *
+ *   import { createAgent } from 'scopeblind-agent';
+ *
+ *   const agent = await createAgent({ keyPath: '.scopeblind/agent-key.json' });
+ *
+ *   // Option 1: Get headers to attach to your own fetch
+ *   const headers = agent.headers('POST', 'https://api.example.com/endpoint');
+ *   await fetch(url, { method: 'POST', headers, body: '...' });
+ *
+ *   // Option 2: Use the built-in fetch wrapper
+ *   const res = await agent.fetch('https://api.example.com/endpoint', {
+ *     method: 'POST',
+ *     body: JSON.stringify({ data: '...' }),
+ *   });
+ *
+ * The server running `scopeblind` middleware will automatically verify the DPoP
+ * proof and identify this agent by its key hash (req.scopeblind.dpopDeviceId).
+ *
+ * Full docs: https://www.scopeblind.com/llms.txt
+ */
+interface AgentOptions {
+    /**
+     * Path to store the agent's key pair (JSON file).
+     * If the file doesn't exist, a new key pair will be generated.
+     * Default: '.scopeblind/agent-key.json'
+     */
+    keyPath?: string;
+    /**
+     * Existing JWK key pair to use instead of generating/loading from file.
+     * Useful for serverless environments or in-memory key management.
+     */
+    jwk?: {
+        publicKey: {
+            kty: string;
+            crv: string;
+            x: string;
+            y: string;
+        };
+        privateKey: {
+            kty: string;
+            crv: string;
+            x: string;
+            y: string;
+            d: string;
+        };
+    };
+}
+interface ScopeBlindAgent {
+    /** The agent's device ID (SHA-256 hash of the public key, 16 hex chars) */
+    deviceId: string;
+    /** The agent's public key as JWK */
+    publicKey: {
+        kty: string;
+        crv: string;
+        x: string;
+        y: string;
+    };
+    /**
+     * Create a DPoP proof JWT for a specific request.
+     * Returns the proof string to use as the DPoP header value.
+     */
+    createProof: (method: string, url: string) => string;
+    /**
+     * Get headers object with DPoP proof for a request.
+     * Use this to attach proof to your own fetch/axios calls.
+     */
+    headers: (method: string, url: string, extraHeaders?: Record<string, string>) => Record<string, string>;
+    /**
+     * Fetch wrapper that automatically attaches DPoP proof.
+     * Drop-in replacement for global fetch with automatic proof-of-possession.
+     */
+    fetch: (url: string, init?: RequestInit) => Promise<Response>;
+}
+declare function hashJWK(jwk: {
+    kty: string;
+    crv: string;
+    x: string;
+    y: string;
+}): string;
+/**
+ * Create a ScopeBlind agent with DPoP proof-of-possession capability.
+ *
+ * The agent generates (or loads) an ES256 key pair and creates self-signed
+ * JWT proofs per RFC 9449 for each request. The server-side `scopeblind`
+ * middleware verifies these proofs and identifies the agent by its key hash.
+ *
+ * @param options - Agent configuration
+ * @returns A ScopeBlindAgent instance with proof creation and fetch methods
+ *
+ * @example
+ * ```typescript
+ * import { createAgent } from 'scopeblind-agent';
+ *
+ * const agent = await createAgent();
+ * console.log('Agent device ID:', agent.deviceId);
+ *
+ * // Automatic DPoP proof with fetch wrapper
+ * const res = await agent.fetch('https://api.example.com/endpoint', {
+ *   method: 'POST',
+ *   headers: { 'Content-Type': 'application/json' },
+ *   body: JSON.stringify({ prompt: 'Hello' }),
+ * });
+ * ```
+ */
+declare function createAgent(options?: AgentOptions): Promise<ScopeBlindAgent>;
+
+export { type AgentOptions, type ScopeBlindAgent, createAgent, hashJWK };

package/dist/index.js

@@ -0,0 +1,177 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  createAgent: () => createAgent,
+  hashJWK: () => hashJWK
+});
+module.exports = __toCommonJS(index_exports);
+var import_node_crypto = require("crypto");
+var import_node_fs = require("fs");
+var import_node_path = require("path");
+function generateKeyPair() {
+  const { publicKey, privateKey } = (0, import_node_crypto.generateKeyPairSync)("ec", {
+    namedCurve: "P-256"
+  });
+  const pubJwk = publicKey.export({ format: "jwk" });
+  const privJwk = privateKey.export({ format: "jwk" });
+  return {
+    publicKey: { kty: pubJwk.kty, crv: pubJwk.crv, x: pubJwk.x, y: pubJwk.y },
+    privateKey: { kty: privJwk.kty, crv: privJwk.crv, x: privJwk.x, y: privJwk.y, d: privJwk.d },
+    createdAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
+function loadOrGenerateKey(keyPath) {
+  if ((0, import_node_fs.existsSync)(keyPath)) {
+    try {
+      const data = (0, import_node_fs.readFileSync)(keyPath, "utf8");
+      const stored = JSON.parse(data);
+      if (stored.publicKey?.kty === "EC" && stored.publicKey?.crv === "P-256" && stored.privateKey?.d) {
+        return stored;
+      }
+    } catch {
+    }
+  }
+  const key = generateKeyPair();
+  const dir = (0, import_node_path.dirname)(keyPath);
+  if (!(0, import_node_fs.existsSync)(dir)) {
+    (0, import_node_fs.mkdirSync)(dir, { recursive: true });
+  }
+  (0, import_node_fs.writeFileSync)(keyPath, JSON.stringify(key, null, 2), { mode: 384 });
+  return key;
+}
+function hashJWK(jwk) {
+  const canonical = JSON.stringify({
+    crv: jwk.crv,
+    kty: jwk.kty,
+    x: jwk.x,
+    y: jwk.y
+  });
+  return (0, import_node_crypto.createHash)("sha256").update(canonical).digest("hex").slice(0, 16);
+}
+function base64url(data) {
+  return data.toString("base64url");
+}
+function createDPoPProof(method, url, publicKey, privateKeyJwk) {
+  const header = {
+    typ: "dpop+jwt",
+    alg: "ES256",
+    jwk: publicKey
+  };
+  const now = Math.floor(Date.now() / 1e3);
+  const payload = {
+    jti: (0, import_node_crypto.randomUUID)().replace(/-/g, ""),
+    htm: method.toUpperCase(),
+    htu: url,
+    iat: now
+  };
+  const headerB64 = base64url(Buffer.from(JSON.stringify(header)));
+  const payloadB64 = base64url(Buffer.from(JSON.stringify(payload)));
+  const signingInput = `${headerB64}.${payloadB64}`;
+  const { createPrivateKey } = require("crypto");
+  const privKey = createPrivateKey({
+    key: {
+      ...privateKeyJwk,
+      key_ops: ["sign"]
+    },
+    format: "jwk"
+  });
+  const sign = (0, import_node_crypto.createSign)("SHA256");
+  sign.update(signingInput);
+  const derSig = sign.sign(privKey);
+  const r = extractIntegerFromDER(derSig, 0);
+  const s = extractIntegerFromDER(derSig, r.offset);
+  const rawSig = Buffer.concat([padTo32(r.value), padTo32(s.value)]);
+  const signatureB64 = base64url(rawSig);
+  return `${signingInput}.${signatureB64}`;
+}
+function extractIntegerFromDER(buf, startOffset) {
+  let offset = startOffset;
+  if (offset === 0 && buf[offset] === 48) {
+    offset++;
+    if (buf[offset] & 128) {
+      offset += (buf[offset] & 127) + 1;
+    } else {
+      offset++;
+    }
+  }
+  if (buf[offset] !== 2) throw new Error("Expected INTEGER tag");
+  offset++;
+  const len = buf[offset];
+  offset++;
+  let value = buf.subarray(offset, offset + len);
+  if (value[0] === 0 && value.length > 1) {
+    value = value.subarray(1);
+  }
+  return { value, offset: offset + len };
+}
+function padTo32(buf) {
+  if (buf.length === 32) return buf;
+  if (buf.length > 32) return buf.subarray(buf.length - 32);
+  const padded = Buffer.alloc(32);
+  buf.copy(padded, 32 - buf.length);
+  return padded;
+}
+async function createAgent(options = {}) {
+  const keyPath = options.keyPath || ".scopeblind/agent-key.json";
+  let key;
+  if (options.jwk) {
+    key = {
+      publicKey: options.jwk.publicKey,
+      privateKey: options.jwk.privateKey,
+      createdAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+  } else {
+    key = loadOrGenerateKey(keyPath);
+  }
+  const deviceId = hashJWK(key.publicKey);
+  const createProof = (method, url) => {
+    return createDPoPProof(method, url, key.publicKey, key.privateKey);
+  };
+  const getHeaders = (method, url, extraHeaders) => {
+    return {
+      ...extraHeaders,
+      DPoP: createProof(method, url)
+    };
+  };
+  const agentFetch = async (url, init) => {
+    const method = init?.method || "GET";
+    const dpop = createProof(method, url);
+    const headers = new Headers(init?.headers);
+    headers.set("DPoP", dpop);
+    return globalThis.fetch(url, {
+      ...init,
+      headers
+    });
+  };
+  return {
+    deviceId,
+    publicKey: key.publicKey,
+    createProof,
+    headers: getHeaders,
+    fetch: agentFetch
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createAgent,
+  hashJWK
+});

package/dist/index.mjs

@@ -0,0 +1,158 @@
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+
+// src/index.ts
+import { createHash, generateKeyPairSync, createSign, randomUUID } from "crypto";
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "fs";
+import { dirname } from "path";
+function generateKeyPair() {
+  const { publicKey, privateKey } = generateKeyPairSync("ec", {
+    namedCurve: "P-256"
+  });
+  const pubJwk = publicKey.export({ format: "jwk" });
+  const privJwk = privateKey.export({ format: "jwk" });
+  return {
+    publicKey: { kty: pubJwk.kty, crv: pubJwk.crv, x: pubJwk.x, y: pubJwk.y },
+    privateKey: { kty: privJwk.kty, crv: privJwk.crv, x: privJwk.x, y: privJwk.y, d: privJwk.d },
+    createdAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
+function loadOrGenerateKey(keyPath) {
+  if (existsSync(keyPath)) {
+    try {
+      const data = readFileSync(keyPath, "utf8");
+      const stored = JSON.parse(data);
+      if (stored.publicKey?.kty === "EC" && stored.publicKey?.crv === "P-256" && stored.privateKey?.d) {
+        return stored;
+      }
+    } catch {
+    }
+  }
+  const key = generateKeyPair();
+  const dir = dirname(keyPath);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+  writeFileSync(keyPath, JSON.stringify(key, null, 2), { mode: 384 });
+  return key;
+}
+function hashJWK(jwk) {
+  const canonical = JSON.stringify({
+    crv: jwk.crv,
+    kty: jwk.kty,
+    x: jwk.x,
+    y: jwk.y
+  });
+  return createHash("sha256").update(canonical).digest("hex").slice(0, 16);
+}
+function base64url(data) {
+  return data.toString("base64url");
+}
+function createDPoPProof(method, url, publicKey, privateKeyJwk) {
+  const header = {
+    typ: "dpop+jwt",
+    alg: "ES256",
+    jwk: publicKey
+  };
+  const now = Math.floor(Date.now() / 1e3);
+  const payload = {
+    jti: randomUUID().replace(/-/g, ""),
+    htm: method.toUpperCase(),
+    htu: url,
+    iat: now
+  };
+  const headerB64 = base64url(Buffer.from(JSON.stringify(header)));
+  const payloadB64 = base64url(Buffer.from(JSON.stringify(payload)));
+  const signingInput = `${headerB64}.${payloadB64}`;
+  const { createPrivateKey } = __require("crypto");
+  const privKey = createPrivateKey({
+    key: {
+      ...privateKeyJwk,
+      key_ops: ["sign"]
+    },
+    format: "jwk"
+  });
+  const sign = createSign("SHA256");
+  sign.update(signingInput);
+  const derSig = sign.sign(privKey);
+  const r = extractIntegerFromDER(derSig, 0);
+  const s = extractIntegerFromDER(derSig, r.offset);
+  const rawSig = Buffer.concat([padTo32(r.value), padTo32(s.value)]);
+  const signatureB64 = base64url(rawSig);
+  return `${signingInput}.${signatureB64}`;
+}
+function extractIntegerFromDER(buf, startOffset) {
+  let offset = startOffset;
+  if (offset === 0 && buf[offset] === 48) {
+    offset++;
+    if (buf[offset] & 128) {
+      offset += (buf[offset] & 127) + 1;
+    } else {
+      offset++;
+    }
+  }
+  if (buf[offset] !== 2) throw new Error("Expected INTEGER tag");
+  offset++;
+  const len = buf[offset];
+  offset++;
+  let value = buf.subarray(offset, offset + len);
+  if (value[0] === 0 && value.length > 1) {
+    value = value.subarray(1);
+  }
+  return { value, offset: offset + len };
+}
+function padTo32(buf) {
+  if (buf.length === 32) return buf;
+  if (buf.length > 32) return buf.subarray(buf.length - 32);
+  const padded = Buffer.alloc(32);
+  buf.copy(padded, 32 - buf.length);
+  return padded;
+}
+async function createAgent(options = {}) {
+  const keyPath = options.keyPath || ".scopeblind/agent-key.json";
+  let key;
+  if (options.jwk) {
+    key = {
+      publicKey: options.jwk.publicKey,
+      privateKey: options.jwk.privateKey,
+      createdAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+  } else {
+    key = loadOrGenerateKey(keyPath);
+  }
+  const deviceId = hashJWK(key.publicKey);
+  const createProof = (method, url) => {
+    return createDPoPProof(method, url, key.publicKey, key.privateKey);
+  };
+  const getHeaders = (method, url, extraHeaders) => {
+    return {
+      ...extraHeaders,
+      DPoP: createProof(method, url)
+    };
+  };
+  const agentFetch = async (url, init) => {
+    const method = init?.method || "GET";
+    const dpop = createProof(method, url);
+    const headers = new Headers(init?.headers);
+    headers.set("DPoP", dpop);
+    return globalThis.fetch(url, {
+      ...init,
+      headers
+    });
+  };
+  return {
+    deviceId,
+    publicKey: key.publicKey,
+    createProof,
+    headers: getHeaders,
+    fetch: agentFetch
+  };
+}
+export {
+  createAgent,
+  hashJWK
+};

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "scopeblind-agent",
+  "version": "1.0.0",
+  "description": "Cryptographic device identity for AI agents and CLIs. DPoP proof-of-possession for ScopeBlind-protected APIs.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "module": "dist/index.mjs",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "prepublishOnly": "npm run build"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "keywords": [
+    "scopeblind",
+    "dpop",
+    "proof-of-possession",
+    "ai-agent",
+    "device-identity",
+    "api-security",
+    "rate-limiting",
+    "mcp",
+    "llm-gateway",
+    "bot-protection",
+    "rfc-9449",
+    "cryptographic-identity"
+  ],
+  "author": "Tom Farley <tommy@scopeblind.com>",
+  "license": "MIT",
+  "homepage": "https://www.scopeblind.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nicosxt/scopeblind-gateway"
+  },
+  "bugs": {
+    "url": "https://github.com/nicosxt/scopeblind-gateway/issues"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0",
+    "@types/node": "^20.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}