@payware/mcp-server 1.3.3 → 1.5.0

package/src/payment-institution/transactions/create-pi-transaction.js

@@ -3,6 +3,7 @@ import { createJWTToken } from '../../core/auth/jwt-token.js';
 import { createMinimizedJSON } from '../../core/utils/json-serializer.js';
 import { getSandboxUrl, getProductionUrl, getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
 import { apiErrorResult } from '../../shared/api-errors.js';
+import { CREATES } from '../../shared/tool-annotations.js';
 
 /**
  * Create a payment institution transaction via payware API
@@ -36,6 +37,7 @@ export async function createPITransaction({
   barBarHeight,
   barFontSize,
   barHumanReadableLocation,
+  idempotencyKey,
   useSandbox = true
 }) {
   if (!role || !['SRC', 'DST'].includes(role)) {
@@ -121,7 +123,8 @@ export async function createPITransaction({
   const headers = {
     'Authorization': `Bearer ${tokenData.token}`,
     'Content-Type': 'application/json',
-    'Api-Version': '1' // Required: current API version
+    'Api-Version': '1', // Required: current API version
+    ...(idempotencyKey && { 'Idempotency-Key': idempotencyKey })
   };
 
   try {
@@ -138,6 +141,7 @@ export async function createPITransaction({
       success: true,
       transaction: response.data,
       requestId: response.headers['x-request-id'],
+      replayed: response.headers?.['idempotent-replayed'] === 'true',
       timestamp: new Date().toISOString()
     };
   } catch (error) {
@@ -150,6 +154,7 @@ export async function createPITransaction({
  */
 export const createPITransactionTool = {
   name: "payware_operations_create_transaction",
+  annotations: CREATES,
   description: `Create a new payware transaction as a payment institution. Payment institutions must specify their role and account details.
 
 **Payment Institution Features:**
@@ -183,6 +188,11 @@ export const createPITransactionTool = {
   inputSchema: {
     type: "object",
     properties: {
+      idempotencyKey: {
+        type: "string",
+        description: "Optional. Sent as the Idempotency-Key header. Use one value per payment (a UUID is typical) and the same value on every retry of it: a retry with the same key and body within 24 hours returns the transaction the first call created instead of a new one, and the result reports replayed: true. The same key with a different body is refused (422 ERR_IDEMPOTENCY_KEY_REUSED); a retry while the first call still runs gets 409 ERR_IDEMPOTENCY_KEY_IN_PROGRESS.",
+        pattern: "^[\\x21-\\x7E]{1,255}$"
+      },
       role: {
         type: "string",
         enum: ["SRC", "DST"],
@@ -245,8 +255,7 @@ export const createPITransactionTool = {
       },
       privateKey: {
         type: "string",
-        description: "RSA private key for JWT token creation. Uses environment-specific private key as default.",
-        default: getPrivateKeySafe(true)
+        description: "RSA private key for JWT token creation. Uses environment-specific private key as default."
       },
       passbackParams: {
         type: "string",
@@ -347,6 +356,7 @@ export const createPITransactionTool = {
       barBarHeight,
       barFontSize,
       barHumanReadableLocation,
+      idempotencyKey,
       useSandbox = true
     } = args;
 
@@ -396,6 +406,7 @@ export const createPITransactionTool = {
       barBarHeight,
       barFontSize,
       barHumanReadableLocation,
+      idempotencyKey,
       useSandbox
     });
 
@@ -437,7 +448,7 @@ ${JSON.stringify(result.transaction, null, 2)}
 **Next Steps:**
 1. Save the transaction ID: \`${result.transaction.transactionId || 'N/A'}\`
 2. ${role === 'SRC' ? 'Share transaction ID with payee for processing' : 'Wait for payer to process this transaction'}
-3. Use \`payware_pi_get_transaction_status\` to check status
+3. Use \`payware_operations_get_transaction_status\` to check status
 4. Monitor callback notifications (if callback URL provided)
 5. ${role === 'SRC' ? 'Complete payment through payware interface' : 'Handle incoming payment processing'}`
         }]

package/src/payment-institution/transactions/finalize-transaction.js

@@ -3,6 +3,7 @@ import { createJWTToken } from '../../core/auth/jwt-token.js';
 import { createMinimizedJSON } from '../../core/utils/json-serializer.js';
 import { getSandboxUrl, getProductionUrl, getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
 import { apiErrorResult } from '../../shared/api-errors.js';
+import { COMMITS } from '../../shared/tool-annotations.js';
 
 /**
  * Finalize a transaction as a payment institution via payware API
@@ -98,6 +99,7 @@ export async function finalizeTransaction({
  */
 export const finalizeTransactionTool = {
   name: "payware_operations_finalize_transaction",
+  annotations: COMMITS,
   description: `Finalize a transaction as a payment institution. This updates the transaction status after execution in your payment network.
 
 **Payment Institution Finalization:**
@@ -164,8 +166,7 @@ export const finalizeTransactionTool = {
       },
       privateKey: {
         type: "string",
-        description: "RSA private key for JWT token creation. Uses environment-specific private key as default.",
-        default: getPrivateKeySafe()
+        description: "RSA private key for JWT token creation. Uses environment-specific private key as default."
       },
       useSandbox: {
         type: "boolean",
@@ -233,6 +234,8 @@ export const finalizeTransactionTool = {
       privateKey,
       useSandbox
     });
+    // The success text quotes the endpoint. The helper above keeps its own baseUrl, so it needs one here.
+    const baseUrl = useSandbox ? getSandboxUrl() : getProductionUrl();
 
     if (result.success) {
       const statusEmojis = {
@@ -277,7 +280,7 @@ ${JSON.stringify(result.transaction, null, 2)}
 ${status === 'CONFIRMED' ?
   `1. ✅ Payment completed successfully
 2. Transaction funds should be processed in your network
-3. Use \`payware_pi_get_transaction_history\` to retrieve details later` :
+3. Use \`payware_operations_get_transaction_history\` to retrieve details later` :
   `1. ⚠️ Payment not completed due to: ${statusMessage || status}
 2. Transaction marked as ${status} in payware system
 3. All parties notified via callbacks`
@@ -310,7 +313,7 @@ ${JSON.stringify(result.error.details || result.error, null, 2)}
 **Timestamp:** ${result.timestamp}
 
 **Common Finalization Issues:**
-1. **ERR_MISSING_TRANSACTION**: Transaction ID not found or expired
+1. **ERR_MISSING_TRANSACTION**: Transaction ID not found. **ERR_TRANSACTION_EXPIRED** (also 404): the time to live ran out before the finalize arrived, and the transaction is closed as unpaid
 2. **ERR_TRANSACTION_NOT_PROCESSED**: Transaction hasn't been processed yet
 3. **ERR_ALREADY_PROCESSED**: Transaction already finalized
 4. **ERR_INVALID_STATUS**: Invalid status value provided

package/src/payment-institution/transactions/get-transaction-history.js

@@ -2,6 +2,7 @@ import axios from 'axios';
 import { createJWTToken } from '../../core/auth/jwt-token.js';
 import { getSandboxUrl, getProductionUrl, getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
 import { apiErrorResult } from '../../shared/api-errors.js';
+import { READS } from '../../shared/tool-annotations.js';
 
 /**
  * Get transaction history via payware API (completed/expired transactions)
@@ -54,6 +55,7 @@ export async function getPITransactionHistory({
  */
 export const getPITransactionHistoryTool = {
   name: "payware_operations_get_transaction_history",
+  annotations: READS,
   description: `Get the complete history of a completed or expired payware transaction as a payment institution.
 
 **Use Cases:**
@@ -86,8 +88,7 @@ export const getPITransactionHistoryTool = {
       },
       privateKey: {
         type: "string",
-        description: "RSA private key for JWT token creation. Uses environment-specific private key as default.",
-        default: getPrivateKeySafe()
+        description: "RSA private key for JWT token creation. Uses environment-specific private key as default."
       },
       useSandbox: {
         type: "boolean",
@@ -124,6 +125,8 @@ export const getPITransactionHistoryTool = {
       privateKey,
       useSandbox
     });
+    // The success text quotes the endpoint. The helper above keeps its own baseUrl, so it needs one here.
+    const baseUrl = useSandbox ? getSandboxUrl() : getProductionUrl();
 
     if (result.success) {
       const tx = result.transaction;
@@ -235,7 +238,7 @@ ${JSON.stringify(result.error.details || result.error, null, 2)}
 1. **ERR_MISSING_TRANSACTION (404)**: Transaction not found in history
 2. **HTTP 429 (Too Many Requests)**: API is throttled, implement retry logic
 3. **Authentication Issues**: Verify JWT token and partner credentials
-4. **Transaction Still Active**: Use \`payware_pi_get_transaction_status\` for active transactions
+4. **Transaction Still Active**: Use \`payware_operations_get_transaction_status\` for active transactions
 
 **Troubleshooting:**
 1. Verify transaction ID is correct: 10 characters total, starts with 'pw' (standard), 'pr' (product), or 'ps' (soundbite)
@@ -251,7 +254,7 @@ ${JSON.stringify(result.error.details || result.error, null, 2)}
 - Avoid excessive polling of this endpoint
 
 **Alternative Actions:**
-- If transaction is still active: Use \`payware_pi_get_transaction_status\`
+- If transaction is still active: Use \`payware_operations_get_transaction_status\`
 - If rate limited: Wait and retry after a delay
 - If transaction not found: Verify the transaction ID exists`
         }]

package/src/payment-institution/transactions/get-transaction-status.js

@@ -2,6 +2,7 @@ import axios from 'axios';
 import { createJWTToken } from '../../core/auth/jwt-token.js';
 import { getSandboxUrl, getProductionUrl, getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
 import { apiErrorResult } from '../../shared/api-errors.js';
+import { READS } from '../../shared/tool-annotations.js';
 
 /**
  * Get transaction status via payware API (active transactions)
@@ -54,6 +55,7 @@ export async function getPITransactionStatus({
  */
 export const getPITransactionStatusTool = {
   name: "payware_operations_get_transaction_status",
+  annotations: READS,
   description: `Get the current status of an active payware transaction as a financial institution.
 
 **Use Cases:**
@@ -96,7 +98,7 @@ Four rules a payer-facing app must follow:
 4. **A missing field is usually a plan boundary, not an error.** \`imageUrl\` and \`termsUrl\` are
    Standard and above; \`termsText\` and the descriptions are universal.
 
-For a \`pr\`/\`ps\` identifier the values are resolved live (product -> shop -> merchant fallback, then
+For a \`pr\`, \`pl\` or \`ps\` identifier the values are resolved live (product -> shop -> merchant fallback, then
 plan gating); for the resulting \`pw\` transaction they are the snapshot frozen at creation, so what
 you get always reflects what the payer could have been shown at scan time.
 
@@ -105,14 +107,14 @@ strings at the smallest unit their own currency can be paid in - not always two
 **the value to echo back unchanged at finalize**; \`feeFixed\` and \`feeRate\` are informational, and
 recomputing the fee from them is rejected with ERR_FEE_MISMATCH.
 
-**Note:** This endpoint only returns active transactions. Use \`payware_pi_get_transaction_history\` for completed/expired transactions.`,
+**Note:** This endpoint only returns active transactions. Use \`payware_operations_get_transaction_history\` for completed/expired transactions.`,
   inputSchema: {
     type: "object",
     properties: {
       transactionId: {
         type: "string",
-        description: "Transaction ID to check status. Format: 2-char prefix + 8-char ID. Supports: 'pw' (standard), 'pr' (product), 'ps' (soundbite)",
-        pattern: "^(pw|pr|ps)[0-9A-Za-z]{8}$"
+        description: "Transaction ID to check status. Format: 2-char prefix + 8-char ID. Supports: 'pw' (standard), 'pr' (product), 'pl' (placement: pays as its product, and the payment is attributed to the placement), 'ps' (soundbite)",
+        pattern: "^(pw|pr|pl|ps)[0-9A-Za-z]{8}$"
       },
       partnerId: {
         type: "string",
@@ -121,8 +123,7 @@ recomputing the fee from them is rejected with ERR_FEE_MISMATCH.
       },
       privateKey: {
         type: "string",
-        description: "RSA private key for JWT token creation. Uses environment-specific private key as default.",
-        default: getPrivateKeySafe()
+        description: "RSA private key for JWT token creation. Uses environment-specific private key as default."
       },
       useSandbox: {
         type: "boolean",
@@ -159,6 +160,8 @@ recomputing the fee from them is rejected with ERR_FEE_MISMATCH.
       privateKey,
       useSandbox
     });
+    // The success text quotes the endpoint. The helper above keeps its own baseUrl, so it needs one here.
+    const baseUrl = useSandbox ? getSandboxUrl() : getProductionUrl();
 
     if (result.success) {
       const tx = result.transaction;
@@ -209,8 +212,8 @@ ${JSON.stringify(result.transaction, null, 2)}
 **Next Steps:**
 1. ${!tx.payerAccount ? 'Transaction waiting for payer to process' : 'Transaction processed, waiting for finalization'}
 2. ${tx.timeToLive && parseInt(tx.timeToLive) < 60 ? '⚠️ Transaction expires soon!' : 'Monitor remaining TTL'}
-3. Use \`payware_pi_process_transaction\` if you need to process this transaction
-4. Use \`payware_pi_finalize_transaction\` to confirm/decline after processing
+3. Use \`payware_operations_process_transaction\` if you need to process this transaction
+4. Use \`payware_operations_finalize_transaction\` to confirm/decline after processing
 
 **⚠️ Transaction State:**
 - This is an **active** transaction
@@ -240,18 +243,18 @@ ${JSON.stringify(result.error.details || result.error, null, 2)}
 
 **Common Issues:**
 1. **ERR_MISSING_TRANSACTION (404)**: Transaction not found, expired, or already completed
-2. **Invalid Transaction ID**: Check transaction ID format (10 chars: 'pw'/'pr'/'ps' + 8 chars)
+2. **Invalid Transaction ID**: Check transaction ID format (10 chars: 'pw'/'pr'/'pl'/'ps' + 8 chars)
 3. **Authentication Issues**: Verify JWT token and partner credentials
 
 **Troubleshooting:**
-1. Verify transaction ID is correct: 10 characters total, starts with 'pw' (standard), 'pr' (product), or 'ps' (soundbite)
+1. Verify transaction ID is correct: 10 characters total, starts with 'pw' (standard), 'pr' (product), 'pl' (placement) or 'ps' (soundbite)
 2. Check if transaction has expired or been completed
-3. Use \`payware_pi_get_transaction_history\` for completed/expired transactions
+3. Use \`payware_operations_get_transaction_history\` for completed/expired transactions
 4. Verify your partner credentials and API access
 5. Ensure transaction was created or you have access to it
 
 **Alternative Actions:**
-- If transaction is completed: Use \`payware_pi_get_transaction_history\`
+- If transaction is completed: Use \`payware_operations_get_transaction_history\`
 - If transaction ID is wrong: Verify the correct transaction ID
 - If access issues: Check your payment institution credentials`
         }]

package/src/payment-institution/transactions/process-pi-transaction.js

@@ -3,6 +3,7 @@ import { createJWTToken } from '../../core/auth/jwt-token.js';
 import { createMinimizedJSON } from '../../core/utils/json-serializer.js';
 import { getSandboxUrl, getProductionUrl, getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
 import { apiErrorResult } from '../../shared/api-errors.js';
+import { COMMITS } from '../../shared/tool-annotations.js';
 
 /**
  * Process a transaction as a payment institution via payware API
@@ -27,6 +28,7 @@ export async function processPITransaction({
   deliveryAddress,
   // Payment method for POI transactions (Payment Choice Architecture)
   paymentMethod,
+  idempotencyKey,
   useSandbox = true
 }) {
   if (!transactionId) {
@@ -84,7 +86,8 @@ export async function processPITransaction({
   const headers = {
     'Authorization': `Bearer ${tokenData.token}`,
     'Content-Type': 'application/json',
-    'Api-Version': '1'  // Required: current API version
+    'Api-Version': '1', // Required: current API version
+    ...(idempotencyKey && { 'Idempotency-Key': idempotencyKey })
   };
 
   try {
@@ -100,6 +103,7 @@ export async function processPITransaction({
       success: true,
       transaction: response.data,
       requestId: response.headers['x-request-id'],
+      replayed: response.headers?.['idempotent-replayed'] === 'true',
       timestamp: new Date().toISOString()
     };
   } catch (error) {
@@ -112,6 +116,7 @@ export async function processPITransaction({
  */
 export const processPITransactionTool = {
   name: "payware_operations_process_transaction",
+  annotations: COMMITS,
   description: `Process a transaction as a payment institution. Payment institutions can process transactions created by others and must provide account/friendlyName details.
 
 **Use Cases:**
@@ -146,10 +151,15 @@ export const processPITransactionTool = {
   inputSchema: {
     type: "object",
     properties: {
+      idempotencyKey: {
+        type: "string",
+        description: "Optional. Sent as the Idempotency-Key header. Use one value per payment (a UUID is typical) and the same value on every retry of it: a retry with the same key and body within 24 hours returns the transaction the first call created instead of a new one, and the result reports replayed: true. The same key with a different body is refused (422 ERR_IDEMPOTENCY_KEY_REUSED); a retry while the first call still runs gets 409 ERR_IDEMPOTENCY_KEY_IN_PROGRESS.",
+        pattern: "^[\\x21-\\x7E]{1,255}$"
+      },
       transactionId: {
         type: "string",
-        description: "Transaction ID to process. Format: 2-char prefix + 8-char ID. Supports: 'pw' (standard), 'pr' (product), 'ps' (soundbite)",
-        pattern: "^(pw|pr|ps)[0-9A-Za-z]{8}$"
+        description: "Transaction ID to process. Format: 2-char prefix + 8-char ID. Supports: 'pw' (standard), 'pr' (product), 'pl' (placement: pays as its product, and the payment is attributed to the placement), 'ps' (soundbite)",
+        pattern: "^(pw|pr|pl|ps)[0-9A-Za-z]{8}$"
       },
       account: {
         type: "string",
@@ -205,8 +215,7 @@ export const processPITransactionTool = {
       },
       privateKey: {
         type: "string",
-        description: "RSA private key for JWT token creation. Uses environment-specific private key as default.",
-        default: getPrivateKeySafe()
+        description: "RSA private key for JWT token creation. Uses environment-specific private key as default."
       },
       // Payment method for POI transactions
       paymentMethod: {
@@ -293,6 +302,7 @@ export const processPITransactionTool = {
       privateKey = getPrivateKeySafe(args.useSandbox ?? true),
       paymentMethod,
       deliveryAddress,
+      idempotencyKey,
       useSandbox = true
     } = args;
 
@@ -339,6 +349,7 @@ export const processPITransactionTool = {
       privateKey,
       paymentMethod,
       deliveryAddress,
+      idempotencyKey,
       useSandbox
     });
 
@@ -373,7 +384,7 @@ ${JSON.stringify(result.transaction, null, 2)}
 1. **TRANSACTION_PROCESSED** callback will be sent to counterparty
 2. Wait for callback notification to your URL (if provided)
 3. Monitor transaction status for completion
-4. Use \`payware_pi_finalize_transaction\` to confirm/decline the transaction
+4. Use \`payware_operations_finalize_transaction\` to confirm/decline the transaction
 5. Handle final TRANSACTION_FINALIZED callbacks
 
 **⚠️ Important:**
@@ -403,7 +414,7 @@ ${JSON.stringify(result.error.details || result.error, null, 2)}
 **Timestamp:** ${result.timestamp}
 
 **Common Payment Institution Issues:**
-1. **ERR_MISSING_TRANSACTION**: Transaction ID not found or expired
+1. **ERR_MISSING_TRANSACTION**: Transaction ID not found. **ERR_TRANSACTION_EXPIRED** (also 404): its time to live has run out and it is closed as unpaid
 2. **ERR_ALREADY_PROCESSED**: Transaction already processed
 3. **ERR_MISSING_PARTNER_ACCOUNT**: Account parameter missing or empty
 4. **ERR_MISSING_FRIENDLY_NAME**: Friendly name parameter missing
@@ -412,7 +423,7 @@ ${JSON.stringify(result.error.details || result.error, null, 2)}
 7. **ERR_SPECIFYING_CURRENCY_NOT_ALLOWED**: Cannot change currency on merchant transactions
 
 **Troubleshooting:**
-1. Verify transaction ID is correct: 10 characters total, starts with 'pw' (standard), 'pr' (product), or 'ps' (soundbite)
+1. Verify transaction ID is correct: 10 characters total, starts with 'pw' (standard), 'pr' (product), 'pl' (placement) or 'ps' (soundbite)
 2. Ensure account and friendlyName are provided
 3. Check currency matches original transaction currency
 4. Verify callback URL is provided (especially for payee role)

package/src/payment-institution/transactions/simulate-pi-callback.js

@@ -10,6 +10,8 @@
  * @param {Object} options - Additional options
  * @returns {Object} Mock callback payload
  */
+import { LOCAL } from '../../shared/tool-annotations.js';
+
 export function generateMockPICallback(transactionId, callbackType = 'TRANSACTION_PROCESSED', options = {}) {
   const {
     amount = '57.00',
@@ -146,6 +148,7 @@ export async function simulatePICallbackDelivery(callbackUrl, payload) {
  */
 export const simulatePICallbackTool = {
   name: "payware_operations_simulate_callback",
+  annotations: LOCAL,
   description: "Simulate payment institution callback scenarios for testing webhook handling. Payment institutions receive TRANSACTION_PROCESSED when merchant processes their transaction, and TRANSACTION_FINALIZED when transaction is completed.",
   inputSchema: {
     type: "object",

package/src/payment-institution/transactions/soundbite-transaction.js

@@ -4,6 +4,7 @@ import { createJWTToken } from '../../core/auth/jwt-token.js';
 import { getSandboxUrl, getProductionUrl, getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
 import { readFileSync } from 'fs';
 import { apiErrorResult } from '../../shared/api-errors.js';
+import { CREATES } from '../../shared/tool-annotations.js';
 
 /**
  * Get transaction information using Soundbite file via payware API
@@ -73,6 +74,7 @@ export async function getSoundbiteTransaction({
  */
 export const soundbiteTransactionTool = {
   name: "payware_operations_soundbite_transaction",
+  annotations: CREATES,
   description: `Get transaction information using a Soundbite SDK output file. This allows payment institutions to process transactions using audio-based identifiers.
 
 **Soundbite Integration:**
@@ -105,8 +107,7 @@ export const soundbiteTransactionTool = {
       },
       privateKey: {
         type: "string",
-        description: "RSA private key for JWT token creation. Uses environment-specific private key as default.",
-        default: getPrivateKeySafe()
+        description: "RSA private key for JWT token creation. Uses environment-specific private key as default."
       },
       useSandbox: {
         type: "boolean",
@@ -199,8 +200,8 @@ ${JSON.stringify(result.transaction, null, 2)}
 1. Transaction successfully identified from soundbite file
 2. Use transaction ID: \`${tx.transactionId || 'N/A'}\` for further operations
 3. ${!tx.payerAccount ? 'Process this transaction if you are the payer' : 'Transaction ready for finalization'}
-4. Use \`payware_pi_process_transaction\` to process payment
-5. Use \`payware_pi_finalize_transaction\` to confirm/decline
+4. Use \`payware_operations_process_transaction\` to process payment
+5. Use \`payware_operations_finalize_transaction\` to confirm/decline
 
 **♿ Accessibility Note:**
 - Soundbite provides audio-based alternative to QR/barcode scanning

package/src/proxy-server.js

@@ -33,6 +33,31 @@ class PaywareMCPProxy {
     const allowedOrigins = (process.env.PAYWARE_MCP_PROXY_ORIGINS
       || `http://localhost:${this.port},http://127.0.0.1:${this.port}`)
       .split(',').map((o) => o.trim()).filter(Boolean);
+
+    // DNS rebinding and cross-site requests. The CORS allowlist below decides which pages may READ a
+    // response; it never refuses a request. A page whose hostname has been rebound to 127.0.0.1 is
+    // same-origin with this server, so CORS does not apply to it at all, and a cross-site form POST
+    // needs no preflight - either way the route runs and signs as the partner. Two checks refuse them:
+    // Host must be a name this server answers to (a rebound page sends its own hostname there), and an
+    // Origin, which browsers send on every POST, must be allowlisted. Clients that are not browsers -
+    // curl, the bridge - send no Origin and pass. PAYWARE_MCP_PROXY_HOSTS (comma-separated host:port)
+    // widens the Host list deliberately.
+    const bindHost = process.env.PAYWARE_MCP_PROXY_HOST || '127.0.0.1';
+    const allowedHosts = new Set((process.env.PAYWARE_MCP_PROXY_HOSTS
+      || `localhost:${this.port},127.0.0.1:${this.port},${bindHost}:${this.port}`)
+      .split(',').map((h) => h.trim().toLowerCase()).filter(Boolean));
+    this.app.use((req, res, next) => {
+      const host = (req.headers.host || '').toLowerCase();
+      if (!allowedHosts.has(host)) {
+        return res.status(403).json({ error: 'Forbidden', message: `Host ${host || '(none)'} is not allowed` });
+      }
+      const origin = req.headers.origin;
+      if (origin !== undefined && !allowedOrigins.includes(origin)) {
+        return res.status(403).json({ error: 'Forbidden', message: `Origin ${origin} is not allowed` });
+      }
+      next();
+    });
+
     this.app.use(cors({
       origin: allowedOrigins,
       credentials: true

package/src/shared/placements/api.js

@@ -0,0 +1,51 @@
+import axios from 'axios';
+import { createMinimizedJSON } from '../../core/utils/json-serializer.js';
+import { getSandboxUrl, getProductionUrl } from '../../config/env.js';
+import { createAuthHeaders } from '../auth-headers.js';
+import { apiErrorResult } from '../api-errors.js';
+
+/**
+ * One call to the campaigns, placements and airings API, as a merchant or as an ISV acting for one.
+ *
+ * Built on the shared `createAuthHeaders`, so the on-behalf JWT (`aud` = the merchant, `sub` = its
+ * OAuth2 token) and the content hash come from the same code every newer tool uses. The body is
+ * serialized once and that exact string is both hashed and sent; `transformRequest` stops axios from
+ * serializing it a second time.
+ *
+ * Never throws for an HTTP error: it returns `apiErrorResult`, whose `details` keeps the response
+ * body, which is where a refused replace-all lists its rows.
+ *
+ * @param {Object} params
+ * @param {string} params.method    HTTP verb
+ * @param {string} params.path      path under the API root, ids already encoded
+ * @param {Object} [params.query]   query parameters; undefined values are left out
+ * @param {*} [params.body]         request body, serialized deterministically
+ * @param {boolean} [params.binary] read the response as bytes (images)
+ * @param {Object} params.auth      from the role: partnerType, credentials and useSandbox
+ */
+export async function placementsRequest({ method, path, query, body, binary = false, auth }) {
+  const minimizedBody = body === undefined ? undefined : createMinimizedJSON(body);
+  const headers = await createAuthHeaders(auth.partnerType, { ...auth, requestBody: minimizedBody });
+  const baseUrl = auth.useSandbox ? getSandboxUrl() : getProductionUrl();
+  const params = query && Object.fromEntries(Object.entries(query).filter(([, v]) => v !== undefined && v !== null));
+
+  try {
+    const response = await axios({
+      method,
+      url: `${baseUrl}${path}`,
+      headers,
+      ...(params && Object.keys(params).length > 0 && { params }),
+      ...(minimizedBody !== undefined && { data: minimizedBody, transformRequest: [(data) => data] }),
+      ...(binary && { responseType: 'arraybuffer' })
+    });
+    return {
+      success: true,
+      status: response.status,
+      data: response.data,
+      contentType: response.headers['content-type'],
+      requestId: response.headers['x-request-id']
+    };
+  } catch (error) {
+    return apiErrorResult(error);
+  }
+}