@frihet/mcp-server 2.0.1 → 2.0.2

package/dist/mpp-sandbox.d.ts

@@ -0,0 +1,176 @@
+/**
+ * Machine Payments Protocol (MPP) Sell-Side Sandbox Proof (#269 / Frihet-ERP #3127).
+ *
+ * Implements M0–M4 sandbox eligibility, HTTP 402 challenge/credential/receipt
+ * state machine (`challenged` -> `pending` -> `verified` -> `delivered` |
+ * `failed_delivery_recovery`), and MCP JSON-RPC transport binding (`-32042` /
+ * `-32043`, `_meta['org.paymentauth/credential']`, `_meta['org.paymentauth/receipt']`).
+ *
+ * Strictly gated behind `FRIHET_MPP_EXPERIMENTAL=true` and `profile_test_*`
+ * test profiles. Frozen public connector profiles (`ChatGPT`, `Claude`,
+ * `Google`, `Muse`) are strictly isolated and never modified.
+ */
+export declare const MPP_PROTOCOL_VERSION: "2026-04-sandbox";
+export declare const MPP_MCP_PAYMENT_REQUIRED_CODE: -32042;
+export declare const MPP_MCP_VERIFICATION_FAILED_CODE: -32043;
+export declare const MPP_META_CREDENTIAL_KEY: "org.paymentauth/credential";
+export declare const MPP_META_RECEIPT_KEY: "org.paymentauth/receipt";
+export declare const MPP_SPT_SUPPORTED_REGIONS: readonly ["US", "CA", "ES", "SE"];
+export declare const MPP_SPT_MIN_AMOUNT_MINOR_USD: 50;
+export declare const MPP_USDC_MIN_AMOUNT_MINOR: 1;
+export type MppPaymentMethod = "stripe_spt" | "tempo_usdc";
+export type MppSandboxState = "challenged" | "pending" | "verified" | "delivered" | "failed_delivery_recovery";
+export type MppEligibilityReasonCode = "ELIGIBLE" | "MPP_EXPERIMENTAL_DISABLED" | "MPP_FROZEN_PROFILE_FORBIDDEN" | "MPP_TEST_PROFILE_REQUIRED" | "MPP_MUTATING_RESOURCE_UNSUPPORTED" | "MPP_SPT_UNSUPPORTED_REGION" | "MPP_SPT_CURRENCY_MISMATCH" | "MPP_SPT_BELOW_MINIMUM" | "MPP_STABLECOIN_APPROVAL_REQUIRED" | "MPP_STABLECOIN_CURRENCY_MISMATCH" | "MPP_STABLECOIN_BELOW_MINIMUM";
+export interface MppEligibilityInput {
+    readonly env?: Record<string, string | undefined>;
+    readonly profileId: string;
+    readonly region: string;
+    readonly paymentMethod: MppPaymentMethod;
+    readonly amountMinor: number;
+    readonly currency: string;
+    readonly effect: "read" | "write" | "fiscal";
+    readonly stablecoinApprovalGranted?: boolean;
+    readonly activeConnectorModes?: {
+        readonly openaiMode?: boolean;
+        readonly claudeMode?: boolean;
+        readonly googleMode?: boolean;
+        readonly museMode?: boolean;
+    };
+}
+export interface MppEligibilityVerdict {
+    readonly eligible: boolean;
+    readonly reasonCode: MppEligibilityReasonCode;
+    readonly reason: string;
+    readonly minimumAmountMinor: number;
+    readonly normalizedCurrency: string;
+}
+/**
+ * Deterministic, runtime-neutral FNV-1a 64-bit hex fingerprint for sandbox
+ * payment artifacts so raw secrets, SPT tokens, or wallet signatures are never
+ * stored or echoed in receipts or logs.
+ */
+export declare function fingerprintMppArtifact(kind: "challenge" | "credential" | "settlement" | "receipt", rawValue: string): string;
+/**
+ * M0 — Evaluates whether an operation is eligible for the MPP sell-side sandbox.
+ */
+export declare function evaluateMppSandboxEligibility(input: MppEligibilityInput): MppEligibilityVerdict;
+export interface MppSandboxPrincipal {
+    readonly authenticatedSubjectId?: string;
+    readonly workspaceUid?: string;
+    readonly hasReadPermission: boolean;
+    readonly bearerTokenPresent: boolean;
+}
+export interface MppSandboxResource {
+    readonly workspaceUid: string;
+    readonly resourceId: string;
+    readonly realm: string;
+    readonly effect: "read" | "write" | "fiscal";
+    readonly requestDigest: string;
+    readonly amountMinor: number;
+    readonly currency: string;
+    readonly paymentMethod: MppPaymentMethod;
+    readonly profileId: string;
+    readonly region: string;
+    readonly stablecoinApprovalGranted?: boolean;
+}
+export interface MppSandboxChallenge {
+    readonly challengeId: string;
+    readonly protocolVersion: typeof MPP_PROTOCOL_VERSION;
+    readonly workspaceUid: string;
+    readonly resourceId: string;
+    readonly realm: string;
+    readonly requestDigest: string;
+    readonly paymentMethod: MppPaymentMethod;
+    readonly amountMinor: number;
+    readonly currency: string;
+    readonly issuedAt: string;
+    readonly expiresAt: string;
+    readonly challengeFingerprint: string;
+}
+export interface MppPaymentCredentialInput {
+    readonly challengeId: string;
+    readonly credentialId: string;
+    readonly rawCredentialToken: string;
+    readonly settlementReference: string;
+    readonly workspaceUid: string;
+    readonly resourceId: string;
+    readonly requestDigest: string;
+    readonly amountMinor: number;
+    readonly currency: string;
+    readonly paymentMethod: MppPaymentMethod;
+    readonly reportedFinality: "settled" | "pending" | "declined";
+    readonly observedAt: string;
+}
+export interface MppPaymentReceipt {
+    readonly receiptId: string;
+    readonly challengeId: string;
+    readonly protocolVersion: typeof MPP_PROTOCOL_VERSION;
+    readonly sandbox: true;
+    readonly paymentMethod: MppPaymentMethod;
+    readonly amountMinor: number;
+    readonly currency: string;
+    readonly resourceId: string;
+    readonly requestDigest: string;
+    readonly credentialFingerprint: string;
+    readonly settlementFingerprint: string;
+    readonly settledAt: string;
+    readonly accountingDisposition: "unmapped_sandbox";
+}
+export interface MppSandboxAttemptRecord {
+    readonly challenge: MppSandboxChallenge;
+    state: MppSandboxState;
+    credentialId?: string;
+    credentialFingerprint?: string;
+    settlementFingerprint?: string;
+    receipt?: MppPaymentReceipt;
+    cachedDeliveryPayload?: Record<string, unknown>;
+    recoveryDisposition: "none" | "refund_or_idempotent_retry_required";
+    lastErrorCode?: string;
+}
+export interface MppHttpSandboxResponse {
+    readonly status: 200 | 401 | 402 | 403 | 502;
+    readonly headers: Record<string, string>;
+    readonly body: Record<string, unknown>;
+    readonly mcpErrorCode?: typeof MPP_MCP_PAYMENT_REQUIRED_CODE | typeof MPP_MCP_VERIFICATION_FAILED_CODE;
+    readonly mcpMeta?: Record<string, unknown>;
+}
+/**
+ * M1 / M2 / M3 — Stateful sell-side sandbox coordinator enforcing:
+ * 1. RBAC 401 -> 403 pre-condition before any 402 Payment Required challenge.
+ * 2. Challenge binding (`WWW-Authenticate: Payment` + `Cache-Control: no-store`).
+ * 3. Coexistence of `Authorization: Bearer` and `Payment-Authorization: Payment`.
+ * 4. Anti-substitution & anti-replay guards across workspace, resource, digest, and amount.
+ * 5. State machine: `challenged` -> `pending` -> `verified` -> `delivered` | `failed_delivery_recovery`.
+ * 6. Sanitized `Payment-Receipt` (`Cache-Control: private`) and MCP `_meta['org.paymentauth/receipt']`.
+ */
+export declare class MppSandboxCoordinator {
+    private readonly attemptsByChallengeId;
+    private readonly challengeIdByCredentialId;
+    private readonly env;
+    private readonly activeConnectorModes?;
+    constructor(options?: {
+        readonly env?: Record<string, string | undefined>;
+        readonly activeConnectorModes?: MppEligibilityInput["activeConnectorModes"];
+    });
+    getAttempt(challengeId: string): MppSandboxAttemptRecord | undefined;
+    handleRequest(params: {
+        readonly principal: MppSandboxPrincipal;
+        readonly targetResource: MppSandboxResource;
+        readonly credential?: MppPaymentCredentialInput;
+        readonly nowIso?: string;
+        readonly executeReadResource: () => Promise<Record<string, unknown>>;
+    }): Promise<MppHttpSandboxResponse>;
+}
+/**
+ * M2 — Optional experimental MCP tool registration for local/sandbox verification.
+ * Strictly no-ops unless `env.FRIHET_MPP_EXPERIMENTAL === "true"` and no frozen
+ * connector profile (`openaiMode`, `claudeMode`, `googleMode`, `museMode`) is active.
+ */
+export declare function attachExperimentalMppSandboxTool(server: any, options?: {
+    readonly env?: Record<string, string | undefined>;
+    readonly openaiMode?: boolean;
+    readonly claudeMode?: boolean;
+    readonly googleMode?: boolean;
+    readonly museMode?: boolean;
+}): MppSandboxCoordinator | undefined;
+//# sourceMappingURL=mpp-sandbox.d.ts.map