@absolutejs/mcp 0.11.3 → 0.13.0

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+All notable changes to `@absolutejs/mcp`.
+
+This file is generated by `absolute-changelog` from the entries in
+`changelog/`. Edit an entry, not this file — and add new ones under
+`changelog/unreleased/`.
+
+## 0.13.0 — 2026-09-11
+
+### Added
+
+- **Add reviewed host commerce eligibility, execution guards, and reusable credit status tools** (`McpServerConfig`, `McpTool`, `evaluateCommerce`, `createCreditBalanceTool`)

package/README.md

@@ -13,6 +13,54 @@ authorization server. The default negotiated revision is the current finalized
 `2025-11-25` specification; older finalized revisions remain available when
 explicitly requested.
 
+## Commerce across AI hosts
+
+See [Commerce host rules and shared package design](docs/commerce-host-rules.md)
+for the dated host-policy survey, checkout restrictions, secure handoffs, and
+reusable AbsoluteJS package boundaries. Host eligibility is implemented;
+checkout sessions, payment adapters and commerce UI remain planned.
+
+### Enforce host commerce eligibility
+
+`@absolutejs/mcp/commerce` exports `evaluateCommerce`, typed requirements and
+review evidence. Tag every commerce tool with `commerce`; the server hides
+ineligible tools and checks again before execution (including delayed tasks).
+Tools without a commerce tag keep their existing behavior.
+
+```ts
+mcpServer<Caller>({
+  // Existing authorize, issuer, path, serverInfo and agency configuration…
+  commerce: ({ caller }) => resolveReviewedDeployment(caller),
+  tools: () => ({
+    open_checkout: {
+      commerce: { action: "external_checkout", categories: ["usage_credits"] },
+      description: "Open a secure checkout for service credits",
+      inputSchema: { type: "object", properties: {} },
+      handler: () => createSecureCheckoutHandoff(),
+    },
+  }),
+});
+```
+
+`resolveReviewedDeployment` and `createSecureCheckoutHandoff` above are consumer
+integration callbacks, not package exports. Return a `CommerceContext` based on
+trusted server configuration, never the tool arguments or a claimed client name.
+Unknown channels and missing/expired reviews fail closed. A deployment review
+cannot override the bundled ChatGPT digital-sales, Claude interactive-purchase,
+or Cursor marketplace paid-access restrictions. Ambiguous profiles intersect.
+
+Reviews must bind the profile, actions, product categories, source URLs and
+validity window. Capabilities such as external links are checked independently.
+Classify every possible cart category server-side; never trust a model-supplied
+product category. `meta.commerceDecision` records the result for `onCall`.
+
+This gate is **host eligibility only**: preserve ownership checks, Agency action
+authorization, exact purchase confirmation and provider reconciliation. It does
+not inspect arbitrary text, prompts, resources or untagged tools for sales links.
+Consumers must use the same evaluator for those surfaces until shared renderers
+are implemented. An informational-link classification must never redirect users
+to a transaction. No live sales path is enabled by installing this package.
+
 ## Agent action enforcement
 
 Tools carrying manifest contract 2 `authorization` metadata fail closed unless

package/changelog.json

@@ -0,0 +1,22 @@
+{
+	"contract": 1,
+	"name": "@absolutejs/mcp",
+	"releases": [
+		{
+			"changes": [
+				{
+					"kind": "added",
+					"summary": "Add reviewed host commerce eligibility, execution guards, and reusable credit status tools",
+					"symbols": [
+						"McpServerConfig",
+						"McpTool",
+						"evaluateCommerce",
+						"createCreditBalanceTool"
+					]
+				}
+			],
+			"date": "2026-09-11",
+			"version": "0.13.0"
+		}
+	]
+}

package/dist/commerce.js

@@ -0,0 +1,173 @@
+// @bun
+var __defProp = Object.defineProperty;
+var __returnValue = (v) => v;
+function __exportSetter(name, newValue) {
+  this[name] = __returnValue.bind(null, newValue);
+}
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: __exportSetter.bind(all, name)
+    });
+};
+
+// src/creditStatus.ts
+var createCreditBalanceTool = (options) => ({
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    openWorldHint: false,
+    title: "Credit balance"
+  },
+  commerce: { action: "entitlement_status", categories: ["usage_credits"] },
+  description: "Read this account's service-credit allowance, consumption and remaining balance. Does not purchase credits or report the AI assistant's own token usage.",
+  inputSchema: { type: "object", properties: {}, additionalProperties: false },
+  outputSchema: {
+    type: "object",
+    required: ["allowance", "consumed", "remaining", "periodEnd", "unit"],
+    properties: {
+      allowance: { type: "integer", minimum: 0 },
+      consumed: { type: "integer", minimum: 0 },
+      remaining: { type: "integer", minimum: 0 },
+      periodEnd: { type: ["string", "null"] },
+      unit: { const: "service_credits" }
+    },
+    additionalProperties: false
+  },
+  handler: async () => {
+    const balance = await options.read();
+    if (![balance.allowance, balance.consumed, balance.remaining].every((n) => Number.isSafeInteger(n) && n >= 0) || balance.periodEnd !== null && !Number.isFinite(Date.parse(balance.periodEnd)))
+      throw new Error("Credit balance is unavailable");
+    const summary = {
+      allowance: balance.allowance,
+      consumed: balance.consumed,
+      remaining: balance.remaining,
+      periodEnd: balance.periodEnd,
+      unit: "service_credits"
+    };
+    return {
+      content: [
+        {
+          type: "text",
+          text: `${summary.remaining} service credits remaining; ${summary.consumed} consumed.`
+        }
+      ],
+      structuredContent: summary
+    };
+  }
+});
+
+// src/commerce.ts
+var COMMERCE_POLICY_VERSION = "2026-09-10.1";
+var COMMERCE_POLICY_SOURCES = Object.freeze({
+  claude: "https://support.claude.com/en/articles/13454812-use-interactive-connectors-in-claude",
+  chatgpt: "https://developers.openai.com/plugins/app-guidelines#commerce-and-monetization",
+  chatgptCheckout: "https://developers.openai.com/plugins/build/monetization",
+  cursorMarketplace: "https://cursor.com/marketplace-publisher-terms"
+});
+var actions = new Set([
+  "entitlement_status",
+  "informational_link",
+  "paid_access",
+  "pricing",
+  "external_checkout",
+  "saved_method_purchase",
+  "new_method_collection",
+  "subscription",
+  "automatic_refill"
+]);
+var categories = new Set([
+  "physical_goods",
+  "digital_service",
+  "usage_credits",
+  "subscription"
+]);
+var profiles = new Set([
+  "claude-interactive",
+  "chatgpt-plugin",
+  "cursor-marketplace",
+  "direct-mcp",
+  "self-hosted",
+  "unknown"
+]);
+var sales = new Set([
+  "pricing",
+  "external_checkout",
+  "saved_method_purchase",
+  "new_method_collection",
+  "subscription",
+  "automatic_refill"
+]);
+var decision = (status, reason, sourceUrls = [], reviewIds = []) => ({
+  allowed: status === "permitted",
+  status,
+  reason,
+  policyVersion: COMMERCE_POLICY_VERSION,
+  sourceUrls,
+  reviewIds
+});
+var validSource = (source) => {
+  try {
+    const url = new URL(source);
+    return url.protocol === "https:" && !url.username && !url.password;
+  } catch {
+    return false;
+  }
+};
+var reviewed = (review, profile, req, now) => typeof review.id === "string" && review.id.trim().length > 0 && review.profile === profile && Array.isArray(review.actions) && review.actions.includes(req.action) && Array.isArray(review.categories) && req.categories.every((c) => review.categories.includes(c)) && Number.isFinite(Date.parse(review.reviewedAt)) && Date.parse(review.reviewedAt) <= now && Number.isFinite(Date.parse(review.expiresAt)) && Date.parse(review.expiresAt) > now && Array.isArray(review.sourceUrls) && review.sourceUrls.length > 0 && review.sourceUrls.every(validSource);
+var evaluateCommerce = (req, context, now = new Date) => {
+  if (!req || !actions.has(req.action) || !Array.isArray(req.categories) || req.categories.length === 0 || req.categories.some((c) => !categories.has(c)) || !context || !Array.isArray(context.profiles) || context.profiles.length === 0 || context.profiles.some((p) => !profiles.has(p)) || !Number.isFinite(now.getTime()))
+    return decision("unverified", "invalid_commerce_context");
+  const results = context.profiles.map((profile) => {
+    const digital = req.categories.some((c) => c !== "physical_goods");
+    if (profile === "chatgpt-plugin" && digital && sales.has(req.action))
+      return decision("restricted", "chatgpt_digital_commerce", [
+        COMMERCE_POLICY_SOURCES.chatgpt
+      ]);
+    if (profile === "claude-interactive" && [
+      "saved_method_purchase",
+      "new_method_collection",
+      "subscription",
+      "automatic_refill"
+    ].includes(req.action))
+      return decision("restricted", "claude_interactive_purchases", [
+        COMMERCE_POLICY_SOURCES.claude
+      ]);
+    if (profile === "cursor-marketplace" && req.action === "paid_access")
+      return decision("restricted", "cursor_marketplace_paid_access", [
+        COMMERCE_POLICY_SOURCES.cursorMarketplace
+      ]);
+    if (req.action === "entitlement_status")
+      return decision("permitted", "non_transactional_status");
+    if (req.action === "informational_link" && profile === "chatgpt-plugin")
+      return decision("permitted", "chatgpt_entitlement_information", [
+        COMMERCE_POLICY_SOURCES.chatgpt
+      ]);
+    if (profile === "unknown")
+      return decision("unverified", "unknown_host_channel");
+    const review = context.reviews?.find((r) => reviewed(r, profile, req, now.getTime()));
+    return review ? decision("permitted", "reviewed_deployment", [...review.sourceUrls], [review.id]) : decision("unverified", "commerce_review_required");
+  });
+  const blocked = results.find((r) => r.status === "restricted") ?? results.find((r) => !r.allowed);
+  if (blocked)
+    return blocked;
+  const caps = context.capabilities;
+  if ((req.action === "external_checkout" || req.action === "informational_link") && caps?.externalLinks !== true)
+    return decision("unverified", "external_links_unavailable");
+  if ((req.action === "saved_method_purchase" || req.action === "new_method_collection") && caps?.interactiveUi !== true)
+    return decision("unverified", "interactive_ui_unavailable");
+  if (req.action === "new_method_collection" && context.profiles.includes("chatgpt-plugin") && caps?.nativePaymentSheet !== true)
+    return decision("restricted", "chatgpt_native_payment_sheet_required", [
+      COMMERCE_POLICY_SOURCES.chatgptCheckout
+    ]);
+  return decision("permitted", "host_commerce_eligible", [...new Set(results.flatMap((r) => r.sourceUrls))], [...new Set(results.flatMap((r) => r.reviewIds))]);
+};
+export {
+  COMMERCE_POLICY_SOURCES,
+  COMMERCE_POLICY_VERSION,
+  createCreditBalanceTool,
+  evaluateCommerce
+};

package/dist/index.js

@@ -14,6 +14,158 @@ var __export = (target, all) => {
     });
 };
 
+// src/creditStatus.ts
+var createCreditBalanceTool = (options) => ({
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    openWorldHint: false,
+    title: "Credit balance"
+  },
+  commerce: { action: "entitlement_status", categories: ["usage_credits"] },
+  description: "Read this account's service-credit allowance, consumption and remaining balance. Does not purchase credits or report the AI assistant's own token usage.",
+  inputSchema: { type: "object", properties: {}, additionalProperties: false },
+  outputSchema: {
+    type: "object",
+    required: ["allowance", "consumed", "remaining", "periodEnd", "unit"],
+    properties: {
+      allowance: { type: "integer", minimum: 0 },
+      consumed: { type: "integer", minimum: 0 },
+      remaining: { type: "integer", minimum: 0 },
+      periodEnd: { type: ["string", "null"] },
+      unit: { const: "service_credits" }
+    },
+    additionalProperties: false
+  },
+  handler: async () => {
+    const balance = await options.read();
+    if (![balance.allowance, balance.consumed, balance.remaining].every((n) => Number.isSafeInteger(n) && n >= 0) || balance.periodEnd !== null && !Number.isFinite(Date.parse(balance.periodEnd)))
+      throw new Error("Credit balance is unavailable");
+    const summary = {
+      allowance: balance.allowance,
+      consumed: balance.consumed,
+      remaining: balance.remaining,
+      periodEnd: balance.periodEnd,
+      unit: "service_credits"
+    };
+    return {
+      content: [
+        {
+          type: "text",
+          text: `${summary.remaining} service credits remaining; ${summary.consumed} consumed.`
+        }
+      ],
+      structuredContent: summary
+    };
+  }
+});
+
+// src/commerce.ts
+var COMMERCE_POLICY_VERSION = "2026-09-10.1";
+var COMMERCE_POLICY_SOURCES = Object.freeze({
+  claude: "https://support.claude.com/en/articles/13454812-use-interactive-connectors-in-claude",
+  chatgpt: "https://developers.openai.com/plugins/app-guidelines#commerce-and-monetization",
+  chatgptCheckout: "https://developers.openai.com/plugins/build/monetization",
+  cursorMarketplace: "https://cursor.com/marketplace-publisher-terms"
+});
+var actions = new Set([
+  "entitlement_status",
+  "informational_link",
+  "paid_access",
+  "pricing",
+  "external_checkout",
+  "saved_method_purchase",
+  "new_method_collection",
+  "subscription",
+  "automatic_refill"
+]);
+var categories = new Set([
+  "physical_goods",
+  "digital_service",
+  "usage_credits",
+  "subscription"
+]);
+var profiles = new Set([
+  "claude-interactive",
+  "chatgpt-plugin",
+  "cursor-marketplace",
+  "direct-mcp",
+  "self-hosted",
+  "unknown"
+]);
+var sales = new Set([
+  "pricing",
+  "external_checkout",
+  "saved_method_purchase",
+  "new_method_collection",
+  "subscription",
+  "automatic_refill"
+]);
+var decision = (status, reason, sourceUrls = [], reviewIds = []) => ({
+  allowed: status === "permitted",
+  status,
+  reason,
+  policyVersion: COMMERCE_POLICY_VERSION,
+  sourceUrls,
+  reviewIds
+});
+var validSource = (source) => {
+  try {
+    const url = new URL(source);
+    return url.protocol === "https:" && !url.username && !url.password;
+  } catch {
+    return false;
+  }
+};
+var reviewed = (review, profile, req, now) => typeof review.id === "string" && review.id.trim().length > 0 && review.profile === profile && Array.isArray(review.actions) && review.actions.includes(req.action) && Array.isArray(review.categories) && req.categories.every((c) => review.categories.includes(c)) && Number.isFinite(Date.parse(review.reviewedAt)) && Date.parse(review.reviewedAt) <= now && Number.isFinite(Date.parse(review.expiresAt)) && Date.parse(review.expiresAt) > now && Array.isArray(review.sourceUrls) && review.sourceUrls.length > 0 && review.sourceUrls.every(validSource);
+var evaluateCommerce = (req, context, now = new Date) => {
+  if (!req || !actions.has(req.action) || !Array.isArray(req.categories) || req.categories.length === 0 || req.categories.some((c) => !categories.has(c)) || !context || !Array.isArray(context.profiles) || context.profiles.length === 0 || context.profiles.some((p) => !profiles.has(p)) || !Number.isFinite(now.getTime()))
+    return decision("unverified", "invalid_commerce_context");
+  const results = context.profiles.map((profile) => {
+    const digital = req.categories.some((c) => c !== "physical_goods");
+    if (profile === "chatgpt-plugin" && digital && sales.has(req.action))
+      return decision("restricted", "chatgpt_digital_commerce", [
+        COMMERCE_POLICY_SOURCES.chatgpt
+      ]);
+    if (profile === "claude-interactive" && [
+      "saved_method_purchase",
+      "new_method_collection",
+      "subscription",
+      "automatic_refill"
+    ].includes(req.action))
+      return decision("restricted", "claude_interactive_purchases", [
+        COMMERCE_POLICY_SOURCES.claude
+      ]);
+    if (profile === "cursor-marketplace" && req.action === "paid_access")
+      return decision("restricted", "cursor_marketplace_paid_access", [
+        COMMERCE_POLICY_SOURCES.cursorMarketplace
+      ]);
+    if (req.action === "entitlement_status")
+      return decision("permitted", "non_transactional_status");
+    if (req.action === "informational_link" && profile === "chatgpt-plugin")
+      return decision("permitted", "chatgpt_entitlement_information", [
+        COMMERCE_POLICY_SOURCES.chatgpt
+      ]);
+    if (profile === "unknown")
+      return decision("unverified", "unknown_host_channel");
+    const review = context.reviews?.find((r) => reviewed(r, profile, req, now.getTime()));
+    return review ? decision("permitted", "reviewed_deployment", [...review.sourceUrls], [review.id]) : decision("unverified", "commerce_review_required");
+  });
+  const blocked = results.find((r) => r.status === "restricted") ?? results.find((r) => !r.allowed);
+  if (blocked)
+    return blocked;
+  const caps = context.capabilities;
+  if ((req.action === "external_checkout" || req.action === "informational_link") && caps?.externalLinks !== true)
+    return decision("unverified", "external_links_unavailable");
+  if ((req.action === "saved_method_purchase" || req.action === "new_method_collection") && caps?.interactiveUi !== true)
+    return decision("unverified", "interactive_ui_unavailable");
+  if (req.action === "new_method_collection" && context.profiles.includes("chatgpt-plugin") && caps?.nativePaymentSheet !== true)
+    return decision("restricted", "chatgpt_native_payment_sheet_required", [
+      COMMERCE_POLICY_SOURCES.chatgptCheckout
+    ]);
+  return decision("permitted", "host_commerce_eligible", [...new Set(results.flatMap((r) => r.sourceUrls))], [...new Set(results.flatMap((r) => r.reviewIds))]);
+};
+
 // src/guards.ts
 var isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 
@@ -834,9 +986,23 @@ var initialize = async (config, id, params, context) => {
   response.headers.set("Mcp-Session-Id", sessionId);
   return response;
 };
+var commerceDecision = async (config, caller, name, tool) => {
+  if (tool.commerce === undefined)
+    return;
+  try {
+    return evaluateCommerce(tool.commerce, config.commerce ? await config.commerce({ caller, name }) : { profiles: [] });
+  } catch {
+    return evaluateCommerce(tool.commerce, { profiles: [] });
+  }
+};
 var toolsList = async (config, caller, scopes, id, params, protocolVersion) => {
   const tools = await config.tools({ caller, meta: {} });
-  const visible = Object.entries(tools).filter(([, tool]) => scopeAllows(tool, scopes) && agencyAllows(config, tool, scopes)).map(([name, tool]) => ({
+  const eligible = await Promise.all(Object.entries(tools).map(async ([name, tool]) => ({
+    name,
+    allowed: (await commerceDecision(config, caller, name, tool))?.allowed !== false
+  })));
+  const commerceVisible = new Set(eligible.filter((entry) => entry.allowed).map((entry) => entry.name));
+  const visible = Object.entries(tools).filter(([name, tool]) => commerceVisible.has(name) && scopeAllows(tool, scopes) && agencyAllows(config, tool, scopes)).map(([name, tool]) => ({
     annotations: tool.annotations,
     ...tool.coaz === undefined ? {} : { coaz: tool.coaz },
     description: tool.description,
@@ -870,9 +1036,45 @@ var runTool = async (config, caller, scopes, id, name, args, meta, tool, context
   let ok = false;
   let payload;
   try {
-    const invoke = async () => normalizeResult(await tool.handler(args, context));
+    const invoke = async () => {
+      const eligibility2 = await commerceDecision(config, caller, name, tool);
+      if (eligibility2)
+        meta.commerceDecision = eligibility2;
+      if (eligibility2?.allowed === false)
+        return {
+          content: [
+            {
+              type: "text",
+              text: "This commerce action is unavailable in this connection."
+            }
+          ],
+          isError: true,
+          structuredContent: {
+            type: "absolute.commerce_decision",
+            ...eligibility2
+          }
+        };
+      return normalizeResult(await tool.handler(args, context));
+    };
     let result;
-    if (tool.authorization === undefined) {
+    const eligibility = await commerceDecision(config, caller, name, tool);
+    if (eligibility)
+      meta.commerceDecision = eligibility;
+    if (eligibility?.allowed === false) {
+      result = {
+        content: [
+          {
+            type: "text",
+            text: "This commerce action is unavailable in this connection."
+          }
+        ],
+        isError: true,
+        structuredContent: {
+          type: "absolute.commerce_decision",
+          ...eligibility
+        }
+      };
+    } else if (tool.authorization === undefined) {
       result = await invoke();
     } else {
       const agency = config.agency;
@@ -1763,26 +1965,30 @@ var createPostgresMcpSessionStore = ({
   };
 };
 export {
-  verifyBearer,
-  publicMcpTask,
-  protectedResourceMetadata,
-  parseMcpAuthorizationChallenge,
-  metadataPathFor,
-  mcpServer,
-  mcpPostgresSchemaSql,
-  feedbackTools,
-  dispatchMcp,
-  discoverMcpAuthorization,
-  createSessionRegistry,
-  createPostgresMcpTaskStore,
-  createPostgresMcpSessionStore,
-  createMemoryMcpTaskStore,
-  createMemoryMcpOAuthTokenStore,
-  createMcpOAuthProvider,
-  createMcpHandler,
-  createMcpClient,
-  createMcpAuthorizationRequest,
-  McpClientError,
+  COMMERCE_POLICY_SOURCES,
+  COMMERCE_POLICY_VERSION,
+  FEEDBACK_INSTRUCTIONS,
   MCP_LATEST_PROTOCOL_VERSION,
-  FEEDBACK_INSTRUCTIONS
+  McpClientError,
+  createCreditBalanceTool,
+  createMcpAuthorizationRequest,
+  createMcpClient,
+  createMcpHandler,
+  createMcpOAuthProvider,
+  createMemoryMcpOAuthTokenStore,
+  createMemoryMcpTaskStore,
+  createPostgresMcpSessionStore,
+  createPostgresMcpTaskStore,
+  createSessionRegistry,
+  discoverMcpAuthorization,
+  dispatchMcp,
+  evaluateCommerce,
+  feedbackTools,
+  mcpPostgresSchemaSql,
+  mcpServer,
+  metadataPathFor,
+  parseMcpAuthorizationChallenge,
+  protectedResourceMetadata,
+  publicMcpTask,
+  verifyBearer
 };