@agentsbloom/sdk 0.2.0 → 0.5.0

package/LICENSE

@@ -1,21 +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.
+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

@@ -1,254 +1,184 @@
-<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).
+# @agentsbloom/sdk
+
+`@agentsbloom/sdk` is a Node.js/Express middleware package for exposing commerce actions to AI agents through AgentsBloom discovery endpoints and supported agent-commerce protocols.
+
+The package includes action discovery, idempotency and in-memory rate-limit helpers, legacy HMAC agent signatures, RFC HTTP Message Signature verification, AP2 mandate verification, optional OpenTelemetry export, and HTML metadata/WebMCP injection.
+
+## Requirements
+
+- Node.js 20 or newer
+- An Express 4 application
+- A real `AGENTSBLOOM_SECRET` for protected legacy-signed write actions
+
+The SDK does not contain a default or demo signing secret. If a protected write request uses the legacy `X-Agent-Signature` flow without a configured secret, it is rejected. RFC HTTP Message Signatures and AP2 mandates use their own verification paths.
+
+## Install
+
+```sh
+npm install @agentsbloom/sdk express
+```
+
+`express` is a peer dependency. OpenTelemetry SDK packages are declared as optional dependencies and npm installs them by default; applications that do not need OTLP export can use `npm install --omit=optional`. The SDK also handles the optional packages being absent when `setupTelemetry()` is called.
+
+## Minimal Express 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 before starting the server");
+}
+
+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(); // stop accepting requests before clearing SDK state
+  } 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 an API key or signing secret in source control, client-side code, logs, or package metadata.
+
+## Configuration
+
+- `apiKey`: AgentsBloom account key used for attribution and service integrations.
+- `agentSecret`: shared 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. Each legacy signature must also include a fresh timestamp and one-time nonce and is bound to the method, path, and parsed request body.
+- `agentKeys`: optional per-agent secrets keyed by `X-Agent-Identifier` (v4 medium pass). Checked before the shared secret, so one leaked agent credential can be replaced without touching every other agent.
+- `revokedIdentifiers`: optional array of identifiers rejected outright before verification.
+- `actionAccess`: optional map of action name to `'anonymous' | 'authenticated'`. `'authenticated'` requires a verified agent signature even for read (GET) invocations of that action.
+- `actionIdentities`: optional per-action identity allow-lists. Entries match a verified identity exactly (`rfc:<keyid>`) or by prefix when ending with `:` (`legacy:`). Enforced on REST actions, `/ap2/checkout`, and MCP tool calls.
+- `maxBodyBytes`: body-size cap in bytes (default 1 MiB), enforced against the received bytes as well as the Content-Length header.
+- `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` and is enforced; declare `method: "GET"` explicitly for a read action.
+- `rateLimit`: optional `{ max, windowMs }` in-memory per-IP limits. OPTIONS preflights count toward the bucket; the tracking map is bounded.
+- `allowedHosts`: optional array of hostnames. When set, discovery URLs are derived from `baseUrl` for any request whose `Host` header is not on the list, preventing Host-header poisoning of the published documents.
+- `idempotency`: optional `{ ttlMs, maxEntries }` for successful write responses keyed by `Idempotency-Key`. Protected action requests authenticate before cache lookup, cache entries are scoped to the middleware instance and verified agent identity, and the cache is bounded with oldest-first eviction.
+- `ap2`: optional AP2 settings including `expectedAudience`, `maxMandateLifetimeSec`, `requireJti`, `requestedCategories`, and `expectedCurrency`. Set `trustedIssuersOnly: true` in production to reject self-certifying did:key mandates (which anyone can mint with an arbitrary budget) and accept only your configured trusted key. `/ap2/checkout` enforces the mandate budget against the total your checkout handler computes (`result.total`/`result.totalPrice`) — always return it; the client-declared `orderTotal` is never authoritative. Mandate and order currencies must agree when both are declared.
+- `merchantJwks`: merchant JWKS document served at the HTTP Message Signatures discovery endpoint. When unset, that endpoint returns 503 rather than serving placeholder keys.
+- `agentJwks`: inline trusted JWKS used to verify RFC HTTP Message Signatures. Key IDs must match a JWK `kid` exactly. Since v4 there is no default JWKS: RFC-signed writes fail closed (503) until this or `agentJwksUrl` is configured.
+- `agentJwksUrl`: HTTPS URL for the trusted agent JWKS. The URL is configured by the merchant; a request cannot select an arbitrary remote JWKS URL.
+- `signature`: optional `{ maxAgeMs, requireAuthority }`. `requireAuthority: true` makes the `@authority` covered component mandatory so the host is bound into every signature.
+- `mcp`: optional `{ maxSessions }` bounding concurrent MCP SSE sessions (default 100).
+- `corsOrigin`: a single origin string, an array of exact origins (matching origins are reflected with `Vary: Origin`; all others receive no allow-origin header), or unset (`*` — warns at startup).
+- Quota operators: import { setQuotaExceededUntil, clearQuotaExceeded } from "@agentsbloom/sdk" to trip/clear the 402 quota gate process-wide, or set AGENTSBLOOM_QUOTA_EXCEEDED_UNTIL (epoch ms) in the environment.
+- `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 a production deployment.
+- `disableSignatureAuth`: explicit compatibility bypass. It should not be enabled for an internet-facing deployment.
+
+The middleware does not replace an application-level authorization layer, a distributed rate limiter, a durable idempotency store, TLS termination, or payment-provider verification.
+
+## Legacy HMAC request signatures
+
+For a mutating action that uses `X-Agent-Signature`, send these headers:
+
+- `X-Agent-Identifier`: printable agent identifier.
+- `X-Agent-Timestamp`: current Unix timestamp in seconds.
+- `X-Agent-Nonce`: a 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. This is an in-memory replay guard; use a durable authentication and replay store when running multiple instances. Identifier-only signatures from older SDK revisions are intentionally rejected; update the signer to include the timestamp and nonce before upgrading.
+
+## RFC HTTP Message Signatures
+
+Protected write requests using the RFC 9421-compatible path must sign `@method`, `@path`, and `content-digest`, and include `created`, `expires`, `nonce`, `keyid`, and `alg` signature parameters. The SDK validates the five-minute default lifetime, rejects reused nonces (atomically — concurrent replays cannot slip through), pins the declared algorithm family to the configured key type (RSA→`rs*`, EC→`es*`, Ed25519/Ed448→`ed*`; SHA-256/384/512 digests derived correctly), rejects multi-label signatures and mismatched Signature/Signature-Input labels, and recomputes `content-digest` from `req.rawBody` when present or the parsed request body otherwise. If an application needs byte-exact verification, configure its body parser to preserve the raw body on `req.rawBody`. Note: `@path` covers the path **including the query string** (self-consistent with this SDK's agent client); enable `signature.requireAuthority` to also bind the host into every signature.
+
+## MCP message authentication
+
+The SSE connection at `/mcp` can advertise the 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. This prevents an unauthenticated MCP client from invoking an action handler.
+
+## 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. Reset the replay cache only when the process is being deliberately reinitialized, such as in a test harness.
+
+## Telemetry
+
+`setupTelemetry()` dynamically loads the optional OpenTelemetry packages and continues without an exporter when they are unavailable. `samplingRatio` is accepted and reported for compatibility, but the current initializer does not apply an SDK-level sampler. `shutdown()` closes the configured provider and clears SDK in-memory state. Applications should call it during graceful process shutdown, after stopping the HTTP server from accepting new requests.
+
+```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
+});
+```
+
+## 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

@@ -1,19 +1,24 @@
-# 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.
+# 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, or provision per-agent credentials via `agentKeys` (with `revokedIdentifiers` for eviction) so one compromised agent cannot forge every other.
+- 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.
+- Configure `agentJwks` or `agentJwksUrl` explicitly: since v4 (0.3.0) there is no default JWKS and RFC 9421 verification fails closed without one. Serve `merchantJwks` if you publish the signatures directory endpoint (it fails closed rather than serving a placeholder).
+- For production AP2, set `ap2.expectedAudience`, provide a trusted `ap2PublicKey`, enable `ap2.trustedIssuersOnly`, and pin `ap2.expectedCurrency`. Always return the handler-computed order total from your checkout handler — it is what the budget cap enforces against.
+- Restrict origins with `corsOrigin` (string or exact-match array; the default is `*` and warns at startup), consider `allowedHosts` to pin discovery-URL derivation, and use `actionAccess`/`actionIdentities` to scope which verified identities may invoke high-value actions such as checkout.
+- Use HTTPS, durable authorization, and a distributed rate/idempotency store for production systems; configure Upstash (`UPSTASH_REDIS_REST_URL`/`TOKEN`) so replay protection is cluster-wide rather than per-instance.
+- Rotate any credential that has appeared in logs, chat, tickets, shell history, or a repository.
+
+See `documentation/security/sdk-v4-hardening.md` for the full list of v4 findings, fixes, and residual risks.