sh-mcp/packages/payments/src/tools.ts

/**
 * MCP tool definitions for the @sh-mcp/payments package.
 *
 * All three tools are finance-tier, require the `finance:read` scope, and MUST
 * call redact() on every sensitive field (bank account, routing, card, SSN)
 * before returning output.  Vendor names and contact details are left intact
 * per the redact() contract.
 *
 * The PaymentsClient is injected via factory functions so tests can supply a
 * mock without AWS credentials or network access.
 *
 * TODO(auth-layer): requireScope() currently only checks the scopes array on
 * the AuthContext object.  Full JWT signature verification, issuer validation,
 * audience binding (aud === 'sh-mcp-finance'), and token-expiry enforcement are
 * handled by the DEFERRED centralized auth middleware in @sh-mcp/shared.  Do
 * NOT remove the requireScope() call — it is the server-side enforcement gate
 * that must remain authoritative even after the middleware is in place.
 */

import { defineTool, requireScope, redact, maskValue } from "@sh-mcp/shared";
import type { AuthContext } from "@sh-mcp/shared";
import type { PaymentsClient, Payment } from "./client.js";

// ---------------------------------------------------------------------------
// Shared output shaping
// ---------------------------------------------------------------------------

/**
 * Redact all sensitive fields on a Payment object in-place and return a new
 * object safe to return to callers / the Slack agent.
 *
 * Fields redacted: bankAccountNumber, bankRoutingNumber, cardNumber.
 * Fields left intact: vendor, vendorContact, memo (may contain vendor info).
 */
function redactPayment(p: Payment): Payment {
  // redact() handles pattern-based redaction for any embedded PII in text fields.
  // maskValue() is used additionally for standalone sensitive field values that
  // redact() cannot match without keyword context (bare account/routing numbers).
  return {
    ...p,
    ...(p.bankAccountNumber !== undefined && {
      bankAccountNumber: maskValue(redact(p.bankAccountNumber)),
    }),
    ...(p.bankRoutingNumber !== undefined && {
      bankRoutingNumber: maskValue(redact(p.bankRoutingNumber)),
    }),
    ...(p.cardNumber !== undefined && {
      // redact() handles Luhn-valid card numbers; maskValue() covers the rest.
      cardNumber: maskValue(redact(p.cardNumber)),
    }),
  };
}

// ---------------------------------------------------------------------------
// lookup_payment_by_vendor
// ---------------------------------------------------------------------------

export interface LookupByVendorInput {
  vendor: string;
  /** Maximum number of results to return. Defaults to 20, max 100. */
  limit?: number;
}

export interface LookupByVendorOutput {
  payments: Payment[];
  count: number;
}

export function makeLookupByVendorTool(client: PaymentsClient) {
  return defineTool<LookupByVendorInput, LookupByVendorOutput>({
    name: "lookup_payment_by_vendor",
    description:
      "Look up PaymentsDashboard records for a given vendor name. " +
      "Returns cleared, pending, voided, and failed payments. " +
      "Sensitive bank, routing, and card fields are masked in the response.",
    tier: "finance",
    requiredScope: "finance:read",
    inputSchema: {
      type: "object",
      properties: {
        vendor: {
          type: "string",
          description:
            "Vendor name to search for (case-insensitive prefix match).",
          minLength: 1,
          maxLength: 200,
        },
        limit: {
          type: "integer",
          description: "Maximum number of results to return (1–100). Defaults to 20.",
          minimum: 1,
          maximum: 100,
          default: 20,
        },
      },
      required: ["vendor"],
      additionalProperties: false,
    },
    async handler(
      input: LookupByVendorInput,
      ctx: AuthContext,
    ): Promise<LookupByVendorOutput> {
      requireScope(ctx, "finance:read");

      const limit = Math.min(input.limit ?? 20, 100);
      const payments = await client.getByVendor(input.vendor, { limit });
      const redacted = payments.map(redactPayment);

      return { payments: redacted, count: redacted.length };
    },
  });
}

// ---------------------------------------------------------------------------
// lookup_payment_by_invoice
// ---------------------------------------------------------------------------

export interface LookupByInvoiceInput {
  invoiceNumber: string;
}

export interface LookupByInvoiceOutput {
  payments: Payment[];
  count: number;
}

export function makeLookupByInvoiceTool(client: PaymentsClient) {
  return defineTool<LookupByInvoiceInput, LookupByInvoiceOutput>({
    name: "lookup_payment_by_invoice",
    description:
      "Look up a payment in PaymentsDashboard by invoice number. " +
      "Sensitive bank, routing, and card fields are masked in the response.",
    tier: "finance",
    requiredScope: "finance:read",
    inputSchema: {
      type: "object",
      properties: {
        invoiceNumber: {
          type: "string",
          description: "The invoice number to look up (exact match).",
          minLength: 1,
          maxLength: 100,
        },
      },
      required: ["invoiceNumber"],
      additionalProperties: false,
    },
    async handler(
      input: LookupByInvoiceInput,
      ctx: AuthContext,
    ): Promise<LookupByInvoiceOutput> {
      requireScope(ctx, "finance:read");

      const payments = await client.getByInvoice(input.invoiceNumber);
      const redacted = payments.map(redactPayment);

      return { payments: redacted, count: redacted.length };
    },
  });
}

// ---------------------------------------------------------------------------
// lookup_payment_by_check
// ---------------------------------------------------------------------------

export interface LookupByCheckInput {
  checkNumber: string;
}

export interface LookupByCheckOutput {
  payments: Payment[];
  count: number;
}

export function makeLookupByCheckTool(client: PaymentsClient) {
  return defineTool<LookupByCheckInput, LookupByCheckOutput>({
    name: "lookup_payment_by_check",
    description:
      "Look up a payment in PaymentsDashboard by check number. " +
      "Sensitive bank, routing, and card fields are masked in the response.",
    tier: "finance",
    requiredScope: "finance:read",
    inputSchema: {
      type: "object",
      properties: {
        checkNumber: {
          type: "string",
          description: "The check number to look up (exact match).",
          minLength: 1,
          maxLength: 50,
        },
      },
      required: ["checkNumber"],
      additionalProperties: false,
    },
    async handler(
      input: LookupByCheckInput,
      ctx: AuthContext,
    ): Promise<LookupByCheckOutput> {
      requireScope(ctx, "finance:read");

      const payments = await client.getByCheck(input.checkNumber);
      const redacted = payments.map(redactPayment);

      return { payments: redacted, count: redacted.length };
    },
  });
}