@agentsbloom/sdk 0.2.0

package/LICENSE

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

@@ -0,0 +1,254 @@
+<p align="center">
+  <a href="https://agentsbloom.com">
+    <img src="./assets/logo-mark.svg" alt="AgentsBloom lotus mark" width="96" height="96" />
+  </a>
+</p>
+
+<h1 align="center">@agentsbloom/sdk</h1>
+
+<p align="center">
+  <strong>One install makes your Express store agent-ready.</strong><br />
+  Expose commerce actions to AI agents through open discovery surfaces and secure agent-commerce protocols.
+</p>
+
+<p align="center">
+  <a href="https://docs.agentsbloom.com">Docs</a> ·
+  <a href="https://agentsbloom.com">Marketing</a> ·
+  <a href="https://blog.agentsbloom.com">Blog</a> ·
+  <a href="https://github.com/AgentsBloom">AgentsBloom on GitHub</a>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@agentsbloom/sdk"><img src="https://img.shields.io/npm/v/@agentsbloom/sdk?logo=npm&logoColor=white&label=npm" alt="npm version" /></a>
+  <a href="https://github.com/AgentsBloom/sdk/actions/workflows/ci.yml"><img src="https://github.com/AgentsBloom/sdk/actions/workflows/ci.yml/badge.svg" alt="CI status" /></a>
+  <a href="https://github.com/AgentsBloom/sdk/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-7c3aed.svg" alt="MIT license" /></a>
+</p>
+
+## About AgentsBloom
+
+[AgentsBloom](https://agentsbloom.com) builds open infrastructure for commerce on the agentic web. We help teams make existing server-side commerce actions understandable and usable by software agents while keeping the store in control of its catalog, authorization, inventory, checkout, and payment logic.
+
+This SDK is the open-source Node.js/Express core: a small middleware layer that gives an existing Express store a clear path to agent-ready commerce.
+
+## One install to make an Express store agent-ready
+
+```sh
+npm install @agentsbloom/sdk express
+```
+
+Then add the middleware and describe your store actions:
+
+```js
+import express from "express";
+import { agentsbloom } from "@agentsbloom/sdk";
+
+const app = express();
+
+app.use(express.json({ limit: "1mb" }));
+app.use(agentsbloom({
+  baseUrl: process.env.PUBLIC_STORE_URL,
+  actions: {
+    search: {
+      method: "POST",
+      description: "Search the product catalog.",
+      params: { query: "string" },
+      handler: async ({ query }) => ({
+        query,
+        items: await searchProducts(query)
+      })
+    }
+  }
+}));
+```
+
+Follow the [Express quickstart in the AgentsBloom documentation](https://docs.agentsbloom.com). You do not need to rewrite your storefront or move your commerce logic into a proprietary platform.
+
+## What the SDK provides
+
+- Action discovery and machine-readable commerce metadata.
+- Express middleware for agent-facing store actions.
+- UCP, ACP, AP2, WebMCP, and Web Bot Auth building blocks.
+- RFC 9421-compatible HTTP Message Signature verification.
+- Legacy HMAC signatures with timestamp and nonce replay protection.
+- AP2 mandate creation and verification with budget, audience, lifetime, category, and replay checks.
+- Per-IP rate limiting and idempotency handling for protected writes.
+- Optional OpenTelemetry export with graceful fallback when exporters are unavailable.
+- HTML metadata and WebMCP injection for compatible responses.
+
+## Authentication paths
+
+The SDK does not require an AgentsBloom account just to install or self-host the middleware. Choose the authentication model that fits your integration:
+
+- **Legacy HMAC writes:** configure a private merchant-generated `AGENTSBLOOM_SECRET` or `agentSecret`. This is required only for requests using the legacy `X-Agent-Signature` headers.
+- **RFC HTTP Message Signatures:** configure trusted agent public keys through `agentJwks` or `agentJwksUrl`; this path does not use `AGENTSBLOOM_SECRET`.
+- **AP2:** use the package's signed mandate helpers and verification path.
+- **Local demos:** `demoMode` can bypass signature authentication, but it must never be enabled for an internet-facing production deployment.
+
+An `AGENTSBLOOM_API_KEY` is a separate account/service-integration value. It is not the HMAC signing secret. Keep both values server-side and out of source control.
+
+## Requirements
+
+- Node.js 20 or newer.
+- An Express 4 application.
+- A real `AGENTSBLOOM_SECRET` for protected legacy-signed write actions, or a configured RFC Message Signature trust path.
+
+## Minimal production setup
+
+```js
+import express from "express";
+import { agentsbloom, shutdown } from "@agentsbloom/sdk";
+
+const app = express();
+const agentSecret = process.env.AGENTSBLOOM_SECRET;
+
+if (!agentSecret) {
+  throw new Error("AGENTSBLOOM_SECRET must be configured for legacy-signed writes");
+}
+
+app.use(express.json({ limit: "1mb" }));
+app.use(agentsbloom({
+  apiKey: process.env.AGENTSBLOOM_API_KEY,
+  agentSecret,
+  baseUrl: process.env.PUBLIC_STORE_URL,
+  name: "Example Store",
+  description: "An example store for agent-driven commerce.",
+  actions: {
+    search: {
+      method: "POST",
+      description: "Search the product catalog.",
+      params: { query: "string" },
+      handler: async ({ query }) => ({ query, items: [] })
+    }
+  }
+}));
+
+const server = app.listen(process.env.PORT || 3000);
+const closeServer = () => new Promise((resolve, reject) => {
+  if (!server.listening) return resolve();
+  server.close((error) => error ? reject(error) : resolve());
+});
+const stop = async () => {
+  try {
+    await closeServer();
+  } finally {
+    await shutdown();
+  }
+};
+process.once("SIGTERM", stop);
+process.once("SIGINT", stop);
+```
+
+`baseUrl` should be the canonical public HTTPS origin of the store. Do not put API keys or signing secrets in source control, client-side code, logs, or package metadata.
+
+## Configuration
+
+- `apiKey`: optional AgentsBloom account key used for attribution and service integrations.
+- `agentSecret`: secret used to verify legacy `X-Agent-Identifier`/`X-Agent-Signature` requests. If omitted, `AGENTSBLOOM_SECRET` is read from the environment; if neither is set, legacy signed writes fail closed.
+- `baseUrl`: canonical store origin used for discovery and audience binding.
+- `actions`: map of agent action names to handlers. Handlers receive `(params, req, res)` and may return a value or a promise. `method` defaults to `POST`; declare `method: "GET"` explicitly for a read action.
+- `rateLimit`: optional `{ max, windowMs }` in-memory per-IP limits.
+- `idempotency`: optional `{ ttlMs }` for successful write responses keyed by `Idempotency-Key`.
+- `ap2`: optional AP2 settings including `expectedAudience`, `maxMandateLifetimeSec`, `requireJti`, and `requestedCategories`.
+- `merchantJwks`: merchant JWKS document served at the HTTP Message Signatures discovery endpoint.
+- `agentJwks`: optional inline trusted JWKS used to verify RFC HTTP Message Signatures.
+- `agentJwksUrl`: optional HTTPS URL for the trusted agent JWKS. A request cannot select an arbitrary remote JWKS URL.
+- `signature`: optional `{ maxAgeMs }` for legacy HMAC timestamp validation; the default is five minutes.
+- `demoMode`: explicit local/demo-only bypass for signature authentication. Never enable it in production.
+- `disableSignatureAuth`: explicit compatibility bypass. Do not enable it for an internet-facing deployment.
+
+The middleware does not replace application-level authorization, a distributed rate limiter, a durable idempotency store, TLS termination, or payment-provider verification.
+
+## Legacy HMAC request signatures
+
+For a mutating action using `X-Agent-Signature`, send:
+
+- `X-Agent-Identifier`: printable agent identifier.
+- `X-Agent-Timestamp`: current Unix timestamp in seconds.
+- `X-Agent-Nonce`: unique printable nonce of at least 16 characters.
+- `X-Agent-Signature`: lowercase or uppercase hexadecimal HMAC-SHA-256.
+
+The signed payload is the JSON array `[identifier, method, originalUrl, timestamp, nonce, parsedBody]`, using the configured `agentSecret`. Signatures expire after five minutes by default and a nonce cannot be consumed twice by the same identifier within the process. Identifier-only signatures from older SDK revisions are intentionally rejected.
+
+## RFC HTTP Message Signatures
+
+Protected writes using the RFC 9421-compatible path must sign `@method`, `@path`, and `content-digest`, and include `created`, `expires`, `nonce`, `keyid`, and `alg` parameters. The SDK validates the lifetime, rejects reused nonces, and recomputes `content-digest` from `req.rawBody` when present or the parsed request body otherwise.
+
+## MCP message authentication
+
+The SSE connection at `/mcp` can advertise configured tools, but mutating MCP messages sent to `/mcp/messages` must pass the same configured RFC HTTP Message Signature or legacy `X-Agent-Signature` verification as other protected writes.
+
+## AP2
+
+The package exports helpers for creating and verifying signed AP2 mandates:
+
+```js
+import {
+  createAp2Mandate,
+  verifyAP2Mandates,
+  resetAp2ReplayCache
+} from "@agentsbloom/sdk";
+
+const { token } = createAp2Mandate({
+  audience: "https://store.example",
+  maxBudget: 100
+});
+
+const result = verifyAP2Mandates(
+  { "x-ap2-mandate": `Bearer ${token}` },
+  { orderTotal: 40 },
+  { expectedAudience: "https://store.example" }
+);
+
+if (!result.valid) {
+  throw new Error(result.reason);
+}
+```
+
+Presented mandates are cryptographically verified. The verifier enforces signature algorithms, issuer/audience binding, bounded lifetime, required `jti` replay protection, optional category restrictions, and budget limits.
+
+## Telemetry
+
+`setupTelemetry()` dynamically loads the optional OpenTelemetry packages and continues without an exporter when they are unavailable. `shutdown()` closes the configured provider and clears SDK in-memory state.
+
+```js
+import { setupTelemetry } from "@agentsbloom/sdk";
+
+await setupTelemetry({
+  otlpEndpoint: process.env.AGENTSBLOOM_OTEL_ENDPOINT,
+  serviceName: "example-store",
+  samplingRatio: 1,
+  apiKey: process.env.AGENTSBLOOM_API_KEY
+});
+```
+
+## Learn more
+
+- [AgentsBloom documentation](https://docs.agentsbloom.com)
+- [AgentsBloom marketing site](https://agentsbloom.com)
+- [AgentsBloom blog](https://blog.agentsbloom.com)
+- [AgentsBloom organization](https://github.com/AgentsBloom)
+- [SDK issues and discussions](https://github.com/AgentsBloom/sdk/issues)
+
+## Development and release checks
+
+From this package directory:
+
+```sh
+npm ci
+npm test
+npm run lint
+npm run check:package
+npm run verify:consumer
+npm run release:check
+npm pack --dry-run --ignore-scripts
+```
+
+The package uses an explicit npm `files` allowlist. Tests and release scripts remain in the repository but are intentionally excluded from the published tarball. These commands do not publish to npm.
+
+## Security
+
+Please report suspected vulnerabilities privately. See [`SECURITY.md`](./SECURITY.md). Never include live credentials in an issue, pull request, test fixture, or support request.
+
+## License
+
+MIT. See [`LICENSE`](./LICENSE).

package/SECURITY.md

@@ -0,0 +1,19 @@
+# Security policy
+
+## Reporting a vulnerability
+
+Please report suspected vulnerabilities privately to `contact@agentsbloom.com` with the subject `AgentsBloom SDK security report`. Include the affected package version, a concise reproduction, and the impact. Do not include live API keys, payment credentials, signing secrets, personal data, or private repository URLs in the report.
+
+We will acknowledge a report when practical, investigate it privately, and coordinate a fix and disclosure timeline with the reporter. Please do not disclose an unpatched vulnerability in a public issue or pull request.
+
+## Supported versions
+
+The latest published version is the primary supported version. Security fixes may not be backported to end-of-life versions.
+
+## Deployment guidance
+
+- Configure a unique high-entropy `AGENTSBLOOM_SECRET` for every merchant deployment.
+- Keep secrets in the deployment secret manager or environment, never in source control or browser bundles.
+- Do not use `demoMode` or `disableSignatureAuth` for internet-facing production traffic.
+- Use HTTPS, durable authorization, and a distributed rate/idempotency store for production systems.
+- Rotate any credential that has appeared in logs, chat, tickets, shell history, or a repository.

package/assets/logo-mark.svg

@@ -0,0 +1,25 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64" role="img" aria-labelledby="agentsbloom-title">
+  <title id="agentsbloom-title">AgentsBloom</title>
+  <style>
+    @media (prefers-color-scheme: dark) {
+      .s1 { stop-color: #4A90F7; }
+      .s2 { stop-color: #4EE2F8; }
+      .s3 { stop-color: #C3AFFF; }
+    }
+  </style>
+  <defs>
+    <linearGradient id="lotus-gradient" x1="0" y1="0" x2="1" y2="1">
+      <stop class="s1" offset="0%" stop-color="#1A73E8" />
+      <stop class="s2" offset="50%" stop-color="#22D3EE" />
+      <stop class="s3" offset="100%" stop-color="#A78BFA" />
+    </linearGradient>
+  </defs>
+  <g fill="url(#lotus-gradient)">
+    <path d="M32 52c1.6 2 2.7 3.7 3.3 5.2.2.6 0 1-.6 1.3l-2.7 1.5-2.7-1.5c-.6-.3-.8-.7-.6-1.3.6-1.5 1.7-3.2 3.3-5.2z" />
+    <path d="M14.5 20.8c.2-1 .7-1.2 1.6-.8 4.5 1.9 8 4.8 10.5 8.7 2.3 3.6 3.6 7.7 3.8 12.2 0 1-.4 1.4-1.3 1.1-4.7-1.5-8.4-4.3-11.1-8.4-2.6-4-3.8-8.3-3.5-12.8z" />
+    <path d="M49.5 20.8c-.2-1-.7-1.2-1.6-.8-4.5 1.9-8 4.8-10.5 8.7-2.3 3.6-3.6 7.7-3.8 12.2 0 1 .4 1.4 1.3 1.1 4.7-1.5 8.4-4.3 11.1-8.4 2.6-4 3.8-8.3 3.5-12.8z" />
+    <path d="M4 30c0-1 .3-1.5 1.3-1.6 6.5-.5 12.5 1.2 17.6 4.8 4.6 3.3 7.7 7.8 9.3 13.2.3 1 .1 1.6-.9 1.7-6.8.8-13-.7-18.4-4.6C7.5 39.6 4.3 34.9 4 30z" />
+    <path d="M60 30c0-1-.3-1.5-1.3-1.6-6.5-.5-12.5 1.2-17.6 4.8-4.6 3.3-7.7 7.8-9.3 13.2-.3 1-.1 1.6.9 1.7 6.8.8 13-.7 18.4-4.6C56.5 39.6 59.7 34.9 60 30z" />
+    <path d="M32 6c4.5 6 7.2 12 8 18 .8 6-.5 12-4 18l-4 6-4-6c-3.5-6-4.8-12-4-18 .8-6 3.5-12 8-18z" />
+  </g>
+</svg>

package/index.d.ts

@@ -0,0 +1,124 @@
+export type Protocol = 'WEBMCP' | 'UCP' | 'ACP' | 'AP2' | 'AGENTSBLOOM_REST';
+
+export type AgentActionHandler = (
+  params: Record<string, unknown>,
+  req: unknown,
+  res: unknown
+) => unknown | Promise<unknown>;
+
+export interface AgentAction {
+  method?: string;
+  description?: string;
+  params?: Record<string, string>;
+  handler: AgentActionHandler;
+}
+
+export interface AgentsBloomConfig {
+  apiKey?: string | null;
+  agentSecret?: string | null;
+  name?: string;
+  description?: string;
+  actions?: Record<string, AgentAction>;
+  llmsDoc?: string;
+  baseUrl?: string;
+  corsOrigin?: string;
+  merchantJwks?: Record<string, unknown>;
+  agentJwks?: {
+    keys: Array<Record<string, unknown>>;
+  };
+  agentJwksUrl?: string;
+  signature?: {
+    maxAgeMs?: number;
+  };
+  ap2PublicKey?: unknown;
+  ap2?: {
+    expectedAudience?: string;
+    maxMandateLifetimeSec?: number;
+    requireJti?: boolean;
+    requestedCategories?: string[];
+  };
+  rateLimit?: {
+    max?: number;
+    windowMs?: number;
+  };
+  idempotency?: {
+    ttlMs?: number;
+  };
+  demoMode?: boolean;
+  disableSignatureAuth?: boolean;
+  disableHtmlInjection?: boolean;
+}
+
+export type AgentsBloomMiddleware = (
+  req: unknown,
+  res: unknown,
+  next: (error?: unknown) => void
+) => unknown;
+
+export interface TelemetryOptions {
+  otlpEndpoint?: string;
+  serviceName?: string;
+  samplingRatio?: number;
+  apiKey?: string;
+}
+
+export interface TelemetryConfig {
+  otlpEndpoint: string;
+  serviceName: string;
+  samplingRatio: number;
+}
+
+export interface Ap2VerificationResult {
+  valid: boolean;
+  verified?: boolean;
+  protocol: 'AP2';
+  reason?: string;
+  note?: string;
+  selfCertifying?: boolean;
+  mandates?: Record<string, unknown>;
+}
+
+export interface Ap2VerifyOptions {
+  trustedPublicKey?: unknown;
+  expectedAudience?: string;
+  maxMandateLifetimeSec?: number;
+  requireJti?: boolean;
+  requestedCategories?: string[];
+}
+
+export interface CreateAp2MandateOptions {
+  audience: string;
+  maxBudget: number;
+  currency?: string;
+  allowedCategories?: string[];
+  merchantScope?: string;
+  lifetimeSec?: number;
+  paymentMethod?: string;
+  subject?: string;
+  privateKey?: unknown;
+}
+
+export interface Ap2Mandate {
+  token: string;
+  did: string;
+  publicKey: unknown;
+  privateKey: unknown;
+}
+
+export function agentsbloom(config?: AgentsBloomConfig): AgentsBloomMiddleware;
+export function setupTelemetry(options?: TelemetryOptions): Promise<TelemetryConfig>;
+export function shutdown(): Promise<void>;
+export function resolveProtocol(req: {
+  headers?: Record<string, string | undefined>;
+  path?: string;
+  url?: string;
+}): Protocol;
+export function verifyAP2Mandates(
+  headers?: Record<string, string | undefined>,
+  body?: Record<string, unknown>,
+  publicKeyOrOptions?: unknown | Ap2VerifyOptions
+): Ap2VerificationResult;
+export function createAp2Mandate(options: CreateAp2MandateOptions): Ap2Mandate;
+export function didKeyFromEd25519PublicKey(publicKey: unknown): string;
+export function ed25519PublicKeyFromDidKey(didKey: string): unknown | null;
+export function resetAp2ReplayCache(): void;