@atbas/m-mcp 0.1.0

package/dist/gateway/checkout-output.js

@@ -0,0 +1,199 @@
+import { chmodSync, closeSync, constants, existsSync, lstatSync, mkdirSync, openSync, realpathSync, writeSync, } from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { JazzCashConfigError, JazzCashValidationError } from '../errors.js';
+/**
+ * Where a signed checkout form may land, and how it is written there.
+ *
+ * Kept apart from the tools that call it. A generated form embeds the merchant's
+ * pp_Password as a hidden input and carries a valid pp_SecureHash, so deciding
+ * the destination and performing the write are the security-critical half of
+ * `jazzcash_build_checkout_form` — the half worth reading, unit-testing and
+ * gating on its own rather than reading past on the way to a tool registration.
+ *
+ * Nothing here may import `../paths.js`, `../dependencies.js` or
+ * `../registry.js`: this module sits inside the connector's published closure,
+ * and `scripts/closure.mjs` fails the build when the credential surface reaches
+ * the documentation half.
+ */
+/**
+ * Server-side variable that relocates the checkout-form output directory.
+ *
+ * Deliberately not a tool argument. A generated form embeds the merchant's
+ * pp_Password as a hidden input and carries a valid pp_SecureHash, so where it
+ * lands is an operator decision: a caller — or a prompt injection reaching one —
+ * must not be able to steer it into a web root, a synced folder or a git tree.
+ */
+const CHECKOUT_OUTPUT_DIRECTORY_VARIABLE = 'JAZZCASH_CHECKOUT_OUTPUT_DIR';
+/**
+ * Variable naming the per-user state directory, per the XDG base directory spec.
+ *
+ * Not this server's variable: it belongs to the user's whole desktop session, so
+ * a value this module cannot use is ignored rather than treated as a fatal
+ * misconfiguration of the payment server.
+ */
+const STATE_HOME_VARIABLE = 'XDG_STATE_HOME';
+/** Mode every generated page is created and left with. */
+const FORM_FILE_MODE = 0o600;
+/** Mode the output directory is created with, when this call creates it. */
+const FORM_DIRECTORY_MODE = 0o700;
+/**
+ * Directory generated forms land in when the operator has named none.
+ *
+ * Deliberately NOT derived from the package root. This server is installed with
+ * `npx`, which unpacks it into a cache directory npm garbage-collects without
+ * warning: a default under the package would scatter pages embedding the
+ * merchant's password and a valid pp_SecureHash across `~/.npm/_npx/<hash>/`,
+ * where the operator neither expects them nor knows to delete them, and where a
+ * reinstall silently moves the directory out from under them.
+ *
+ * A per-user state directory is the right home instead. It is stable across
+ * reinstalls, it belongs to the operator rather than to a package manager, and
+ * `XDG_STATE_HOME` is the variable a user has already set if they keep such
+ * state somewhere other than `~/.local/state`.
+ *
+ * An empty, whitespace-only or relative `XDG_STATE_HOME` falls back rather than
+ * being used. A blank variable is an unset one, which is the same treatment
+ * {@link CHECKOUT_OUTPUT_DIRECTORY_VARIABLE} gets below. A relative one is
+ * ignored because the XDG specification says it must be, and because joining it
+ * would produce a relative path that {@link canonicalPath} anchors to
+ * `process.cwd()` — for a stdio server that is whatever the AI client chose,
+ * routinely the merchant's own project directory, which is exactly where a page
+ * carrying live credentials must never be written.
+ *
+ * Exported so the default can be asserted directly. Every suite that exercises
+ * the tool pins {@link CHECKOUT_OUTPUT_DIRECTORY_VARIABLE} to a temporary
+ * directory, so without this the default is the one path in this module no test
+ * would ever execute.
+ */
+export function defaultCheckoutRoot() {
+    const stateHome = process.env[STATE_HOME_VARIABLE]?.trim() ?? '';
+    const usable = stateHome !== '' && isAbsolute(stateHome);
+    return join(usable ? stateHome : join(homedir(), '.local', 'state'), 'm-mcp', 'out');
+}
+/**
+ * Canonical absolute form of a path that need not exist yet.
+ *
+ * `realpathSync` throws on a missing path, so the deepest existing ancestor is
+ * resolved and the remaining segments are re-appended. Without this a symlink
+ * inside the output directory would defeat the containment check below. The
+ * walk terminates because `dirname` reaches a fixed point at the filesystem root.
+ *
+ * The final component is deliberately left unresolved when it does not exist,
+ * which is why {@link writeCheckoutForm} refuses to follow it rather than
+ * trusting this result: `existsSync` follows symlinks, so a *dangling* link at
+ * the target file name looks like a path that is simply absent.
+ */
+function canonicalPath(target) {
+    const absolute = resolve(target);
+    const trailing = [];
+    let current = absolute;
+    for (;;) {
+        if (existsSync(current)) {
+            return join(realpathSync(current), ...trailing.reverse());
+        }
+        const parent = dirname(current);
+        /* c8 ignore next 3 -- unreachable while the filesystem root exists; retained because it is what proves this walk terminates */
+        if (parent === current) {
+            return absolute;
+        }
+        trailing.push(basename(current));
+        current = parent;
+    }
+}
+/** True when `candidate` sits underneath `root`. */
+function isWithin(root, candidate) {
+    const offset = relative(root, candidate);
+    return offset !== '' && offset !== '..' && !offset.startsWith(`..${sep}`) && !isAbsolute(offset);
+}
+function assertWithinOutputRoot(root, candidate) {
+    if (isWithin(root, candidate)) {
+        return;
+    }
+    throw new JazzCashValidationError(`Refusing to write a signed checkout form to ${candidate}. The page embeds your merchant password and a valid pp_SecureHash, so it is only ever written inside ${root}. Pass outputPath as a file name relative to that directory, or set ${CHECKOUT_OUTPUT_DIRECTORY_VARIABLE} on the server to move the directory itself.`);
+}
+/**
+ * Refuse a target file name that is itself a symbolic link.
+ *
+ * The containment checks resolve every component *except* the last one, and they
+ * cannot do better: `existsSync` follows links, so a dangling link at the target
+ * name reports the path as absent and the walk hands back the literal in-root
+ * path. The write would then follow the link and deposit the merchant's password
+ * wherever it points, with both containment checks having returned true.
+ *
+ * This is the portable half of the refusal. `O_NOFOLLOW` below is the
+ * authoritative one — it also closes the window between this check and the open
+ * — but it does not exist on Windows, so the check is made here as well and the
+ * behaviour is the same on every platform.
+ */
+function assertNotSymbolicLink(candidate) {
+    if (lstatSync(candidate, { throwIfNoEntry: false })?.isSymbolicLink() !== true) {
+        return;
+    }
+    throw new JazzCashValidationError(`Refusing to write a signed checkout form to ${candidate}, which is a symbolic link. The page embeds your merchant password and a valid pp_SecureHash, and a link is a redirection this server cannot vouch for: following it would put those credentials wherever the link points, outside the directory every containment check was made against. Delete the link, or pass outputPath as a different file name.`);
+}
+/**
+ * Decide where a checkout form may be written, refusing anything outside the
+ * server's own output directory.
+ *
+ * An escaping path is refused rather than silently rewritten: quietly relocating
+ * live credentials would hide where they actually landed.
+ */
+export function resolveCheckoutTarget(outputPath, defaultFileName) {
+    const configured = process.env[CHECKOUT_OUTPUT_DIRECTORY_VARIABLE]?.trim() ?? '';
+    // Refused rather than resolved against `process.cwd()`, which is the same line
+    // `corpusRoot()` draws for `MCP_CORPUS_DIR` in `src/paths.ts`. A relative
+    // value here would not merely find the wrong directory: it would put a page
+    // carrying live credentials under whichever directory the AI client happened
+    // to start the server in, which is routinely a repository.
+    if (configured !== '' && !isAbsolute(configured)) {
+        throw new JazzCashConfigError(`${CHECKOUT_OUTPUT_DIRECTORY_VARIABLE} must be an absolute path, but is "${configured}". A relative path would be resolved against the working directory of whichever process started the server, which is not something this server can predict — and a generated form embeds your merchant password and a valid pp_SecureHash, so it must never land somewhere neither of us chose.`);
+    }
+    const root = canonicalPath(configured === '' ? defaultCheckoutRoot() : configured);
+    const requested = outputPath === undefined || outputPath.trim() === '' ? defaultFileName : outputPath.trim();
+    const path = canonicalPath(resolve(root, requested));
+    assertWithinOutputRoot(root, path);
+    return { root, path };
+}
+/**
+ * Write the page, re-checking containment once the directory exists.
+ *
+ * `resolveCheckoutTarget` could only resolve the symlinks present when it ran,
+ * and the write is what actually discloses the credentials, so the check is made
+ * again against the directory that now exists on disk.
+ *
+ * The directory is created 0700 because every file in it embeds the merchant's
+ * password and a valid pp_SecureHash. On a shared host the process umask alone
+ * would commonly leave it world-readable, and the mode is only applied to
+ * directories this call actually creates — an operator who pointed
+ * `JAZZCASH_CHECKOUT_OUTPUT_DIR` at an existing directory keeps their own
+ * permissions.
+ *
+ * The file is opened rather than handed to `writeFileSync` for two reasons that
+ * `writeFileSync` cannot serve at once. `O_NOFOLLOW` makes the open fail rather
+ * than follow a symbolic link at the target name, which is the one component no
+ * containment check could resolve, and it does so atomically — there is no
+ * window between the check and the write for a link to appear in. And `O_CREAT`
+ * carries the mode, so the page is 0600 from the moment it exists rather than
+ * whatever the umask allows. `chmodSync` follows because a mode passed to
+ * `open` is ignored for a file that already exists, and overwriting yesterday's
+ * world-readable page must tighten it rather than inherit it.
+ */
+export function writeCheckoutForm(target, html) {
+    mkdirSync(dirname(target.path), { recursive: true, mode: FORM_DIRECTORY_MODE });
+    const confirmed = join(canonicalPath(dirname(target.path)), basename(target.path));
+    assertWithinOutputRoot(target.root, confirmed);
+    assertNotSymbolicLink(confirmed);
+    // `constants.O_NOFOLLOW` is absent on Windows, where the expression below
+    // degrades to the remaining flags. `assertNotSymbolicLink` is what keeps the
+    // refusal identical there.
+    const handle = openSync(confirmed, constants.O_WRONLY | constants.O_CREAT | constants.O_TRUNC | constants.O_NOFOLLOW, FORM_FILE_MODE);
+    try {
+        writeSync(handle, html, 0, 'utf8');
+    }
+    finally {
+        closeSync(handle);
+    }
+    chmodSync(confirmed, FORM_FILE_MODE);
+}
+//# sourceMappingURL=checkout-output.js.map

package/dist/gateway/checkout-output.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkout-output.js","sourceRoot":"","sources":["../../src/gateway/checkout-output.ts"],"names":[],"mappings":"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"}

package/dist/gateway/guards.d.ts

@@ -0,0 +1,37 @@
+import type { IntegrationFlow } from '../catalogue/types.js';
+import type { CredentialProfile } from '../config/credentials.js';
+import type { JazzCashEnvironment } from '../config/environment.js';
+import type { CoreDependencies } from '../core/dependencies.js';
+/**
+ * Safety guards for outbound gateway calls.
+ *
+ * Every documented JazzCash flow uses an identical URL for sandbox and
+ * production. The endpoint therefore carries no information about which
+ * environment a request reaches: the credentials decide. Nothing here can be
+ * inferred, so everything is required explicitly.
+ *
+ * Production money movement needs BOTH:
+ *   1. the server started with `JAZZCASH_ALLOW_LIVE=true`, and
+ *   2. the tool call passing `confirmLiveEnvironment: true`.
+ *
+ * One switch could be left on by accident. Two, in different places and owned by
+ * different people, cannot be.
+ */
+export interface GuardRequest {
+    readonly flow: IntegrationFlow;
+    readonly environment: JazzCashEnvironment;
+    readonly confirmLiveEnvironment: boolean | undefined;
+}
+export interface GuardOutcome {
+    readonly profile: CredentialProfile;
+    /** Warnings the caller must surface, e.g. that this call moves real money. */
+    readonly warnings: readonly string[];
+}
+/**
+ * Resolve credentials for a call and refuse it if the guards are not satisfied.
+ *
+ * Returns the warnings the caller must show, rather than logging them and moving
+ * on: a merchant about to move real money should see that on screen.
+ */
+export declare function guardGatewayCall(deps: CoreDependencies, request: GuardRequest): GuardOutcome;
+//# sourceMappingURL=guards.d.ts.map

package/dist/gateway/guards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guards.d.ts","sourceRoot":"","sources":["../../src/gateway/guards.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AACpE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAGhE;;;;;;;;;;;;;;GAcG;AAEH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,QAAQ,CAAC,WAAW,EAAE,mBAAmB,CAAC;IAC1C,QAAQ,CAAC,sBAAsB,EAAE,OAAO,GAAG,SAAS,CAAC;CACtD;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,OAAO,EAAE,iBAAiB,CAAC;IACpC,8EAA8E;IAC9E,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CACtC;AAkCD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,gBAAgB,EAAE,OAAO,EAAE,YAAY,GAAG,YAAY,CA6B5F"}

package/dist/gateway/guards.js

@@ -0,0 +1,44 @@
+import { JazzCashSafetyError } from '../errors.js';
+const SAFETY_DOC_REF = [{ docId: 'card-page-redirection', sectionId: 'endpoint' }];
+function assertLiveOptIn(deps, request) {
+    if (request.environment !== 'production' || !request.flow.movesMoney) {
+        return;
+    }
+    if (!deps.config.allowLive) {
+        throw new JazzCashSafetyError(`Refusing to run ${request.flow.id} against production: this call moves real money and the server was started with JAZZCASH_ALLOW_LIVE=false. Restart with JAZZCASH_ALLOW_LIVE=true and pass confirmLiveEnvironment: true if that is genuinely what you intend. Note that the production endpoint is identical to the sandbox one, so this guard cannot be inferred away.`, { docRefs: SAFETY_DOC_REF, details: { flowId: request.flow.id } });
+    }
+    if (request.confirmLiveEnvironment !== true) {
+        throw new JazzCashSafetyError(`Refusing to run ${request.flow.id} against production without explicit confirmation. This call moves real money. Pass confirmLiveEnvironment: true to proceed.`, { docRefs: SAFETY_DOC_REF, details: { flowId: request.flow.id } });
+    }
+}
+function assertRefundCapability(flow, profile) {
+    const needsMpin = flow.parameters.some((parameter) => parameter.name === 'pp_MerchantMPIN');
+    if (needsMpin && !profile.supportsRefunds()) {
+        throw new JazzCashSafetyError(`${flow.id} requires pp_MerchantMPIN, but no MPIN is configured for the ${profile.environment} environment. Set JAZZCASH_${profile.environment.toUpperCase()}_MERCHANT_MPIN, and save the same MPIN in the merchant portal — refunds fail until it is stored there as well as sent.`, { docRefs: [{ docId: 'card-refund', sectionId: 'common-failures' }] });
+    }
+}
+/**
+ * Resolve credentials for a call and refuse it if the guards are not satisfied.
+ *
+ * Returns the warnings the caller must show, rather than logging them and moving
+ * on: a merchant about to move real money should see that on screen.
+ */
+export function guardGatewayCall(deps, request) {
+    // Throws a JazzCashConfigError naming the missing variables when the profile
+    // is absent, which is a better failure than a 401 from the gateway.
+    const profile = deps.credentials.get(request.environment);
+    assertLiveOptIn(deps, request);
+    assertRefundCapability(request.flow, profile);
+    const warnings = [];
+    if (request.environment === 'production' && request.flow.movesMoney) {
+        warnings.push('This call is running against PRODUCTION and moves real money. It will debit or refund a real account.');
+    }
+    if (request.flow.sameEndpointForBothEnvironments) {
+        warnings.push(`The endpoint is identical for sandbox and production. This call is treated as ${request.environment} because that is the credential profile in use, not because of the URL.`);
+    }
+    if (request.flow.id === 'bnpl-page-redirection-v1.1' || request.flow.id === 'refund-bnpl') {
+        warnings.push('The BNPL guide specifies PRODUCTION credentials for testing. Use the smallest possible amount and refund it afterwards.');
+    }
+    return { profile, warnings };
+}
+//# sourceMappingURL=guards.js.map

package/dist/gateway/guards.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"guards.js","sourceRoot":"","sources":["../../src/gateway/guards.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AA8BnD,MAAM,cAAc,GAAG,CAAC,EAAE,KAAK,EAAE,uBAAuB,EAAE,SAAS,EAAE,UAAU,EAAE,CAAC,CAAC;AAEnF,SAAS,eAAe,CAAC,IAAsB,EAAE,OAAqB;IACpE,IAAI,OAAO,CAAC,WAAW,KAAK,YAAY,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,UAAU,EAAE,CAAC;QACrE,OAAO;IACT,CAAC;IAED,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,CAAC;QAC3B,MAAM,IAAI,mBAAmB,CAC3B,mBAAmB,OAAO,CAAC,IAAI,CAAC,EAAE,wUAAwU,EAC1W,EAAE,OAAO,EAAE,cAAc,EAAE,OAAO,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,CAClE,CAAC;IACJ,CAAC;IAED,IAAI,OAAO,CAAC,sBAAsB,KAAK,IAAI,EAAE,CAAC;QAC5C,MAAM,IAAI,mBAAmB,CAC3B,mBAAmB,OAAO,CAAC,IAAI,CAAC,EAAE,8HAA8H,EAChK,EAAE,OAAO,EAAE,cAAc,EAAE,OAAO,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,CAClE,CAAC;IACJ,CAAC;AACH,CAAC;AAED,SAAS,sBAAsB,CAAC,IAAqB,EAAE,OAA0B;IAC/E,MAAM,SAAS,GAAG,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,IAAI,KAAK,iBAAiB,CAAC,CAAC;IAC5F,IAAI,SAAS,IAAI,CAAC,OAAO,CAAC,eAAe,EAAE,EAAE,CAAC;QAC5C,MAAM,IAAI,mBAAmB,CAC3B,GAAG,IAAI,CAAC,EAAE,gEAAgE,OAAO,CAAC,WAAW,8BAA8B,OAAO,CAAC,WAAW,CAAC,WAAW,EAAE,wHAAwH,EACpR,EAAE,OAAO,EAAE,CAAC,EAAE,KAAK,EAAE,aAAa,EAAE,SAAS,EAAE,iBAAiB,EAAE,CAAC,EAAE,CACtE,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAsB,EAAE,OAAqB;IAC5E,6EAA6E;IAC7E,oEAAoE;IACpE,MAAM,OAAO,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;IAE1D,eAAe,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IAC/B,sBAAsB,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IAE9C,MAAM,QAAQ,GAAa,EAAE,CAAC;IAE9B,IAAI,OAAO,CAAC,WAAW,KAAK,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC,UAAU,EAAE,CAAC;QACpE,QAAQ,CAAC,IAAI,CACX,uGAAuG,CACxG,CAAC;IACJ,CAAC;IAED,IAAI,OAAO,CAAC,IAAI,CAAC,+BAA+B,EAAE,CAAC;QACjD,QAAQ,CAAC,IAAI,CACX,iFAAiF,OAAO,CAAC,WAAW,yEAAyE,CAC9K,CAAC;IACJ,CAAC;IAED,IAAI,OAAO,CAAC,IAAI,CAAC,EAAE,KAAK,4BAA4B,IAAI,OAAO,CAAC,IAAI,CAAC,EAAE,KAAK,aAAa,EAAE,CAAC;QAC1F,QAAQ,CAAC,IAAI,CACX,yHAAyH,CAC1H,CAAC;IACJ,CAAC;IAED,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC;AAC/B,CAAC"}

package/dist/gateway/http-client.d.ts

@@ -0,0 +1,42 @@
+import type { Logger } from '../telemetry/logger.js';
+/**
+ * HTTP transport for gateway calls.
+ *
+ * Deliberately small: native `fetch`, an explicit timeout, a bounded retry for
+ * reads only, and a response size cap. Request and response bodies are never
+ * logged — they carry the merchant password and, on some flows, a CNIC fragment.
+ */
+/** Refuse to buffer more than this from a gateway response. */
+export declare const MAX_RESPONSE_BYTES = 1048576;
+export interface HttpClientOptions {
+    readonly timeoutMs: number;
+    readonly logger: Logger;
+    /** Injectable for tests. Defaults to the global `fetch`. */
+    readonly fetchImpl?: typeof fetch;
+}
+export interface HttpResponse {
+    readonly status: number;
+    readonly ok: boolean;
+    readonly rawText: string;
+    /** The parsed JSON body, or `undefined` when the body was not JSON. */
+    readonly body: unknown;
+    /** The declared media type, verbatim. Absent when the gateway declared none. */
+    readonly contentType?: string | undefined;
+    readonly durationMs: number;
+    readonly attempts: number;
+}
+export interface PostOptions {
+    /**
+     * Whether the call may be retried.
+     *
+     * Only ever true for reads. A payment or refund is NOT idempotent: retrying a
+     * request that may already have been processed can debit a customer twice.
+     * Resolve an uncertain outcome with the Status Inquiry API instead.
+     */
+    readonly retryable: boolean;
+}
+export interface HttpClient {
+    postJson(url: string, payload: unknown, options: PostOptions): Promise<HttpResponse>;
+}
+export declare function createHttpClient(options: HttpClientOptions): HttpClient;
+//# sourceMappingURL=http-client.d.ts.map

package/dist/gateway/http-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-client.d.ts","sourceRoot":"","sources":["../../src/gateway/http-client.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAErD;;;;;;GAMG;AAEH,+DAA+D;AAC/D,eAAO,MAAM,kBAAkB,UAAY,CAAC;AAE5C,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,4DAA4D;IAC5D,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CACnC;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,uEAAuE;IACvE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,gFAAgF;IAChF,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,WAAW;IAC1B;;;;;;OAMG;IACH,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;CACtF;AAyFD,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,iBAAiB,GAAG,UAAU,CA0FvE"}

package/dist/gateway/http-client.js

@@ -0,0 +1,153 @@
+import { JazzCashGatewayError } from '../errors.js';
+/**
+ * HTTP transport for gateway calls.
+ *
+ * Deliberately small: native `fetch`, an explicit timeout, a bounded retry for
+ * reads only, and a response size cap. Request and response bodies are never
+ * logged — they carry the merchant password and, on some flows, a CNIC fragment.
+ */
+/** Refuse to buffer more than this from a gateway response. */
+export const MAX_RESPONSE_BYTES = 1_048_576;
+/** One retry, and only for reads. The loop is bounded by construction. */
+const MAX_ATTEMPTS_RETRYABLE = 2;
+const RETRY_DELAY_MS = 500;
+function isTransient(error) {
+    if (error instanceof DOMException && error.name === 'TimeoutError') {
+        return true;
+    }
+    return error instanceof TypeError;
+}
+function oversizedResponseError() {
+    return new JazzCashGatewayError(`The gateway returned more than ${String(MAX_RESPONSE_BYTES)} bytes, which no documented response approaches. Refusing to parse it.`);
+}
+/**
+ * Read a response body, refusing it as soon as it exceeds the cap.
+ *
+ * The body is consumed chunk by chunk and measured in BYTES. `response.text()`
+ * would defeat the cap twice over: it buffers the whole body before anything can
+ * be compared, so a fast endpoint could exhaust memory inside the timeout
+ * window, and its length is counted in UTF-16 code units, which under-counts
+ * every multi-byte character against a limit named in bytes.
+ */
+async function readBoundedText(response) {
+    // A truthful Content-Length lets an oversized body be refused before a single
+    // chunk is read. An absent or unparseable header yields NaN and is ignored.
+    const declaredBytes = Number(response.headers.get('content-length'));
+    if (Number.isFinite(declaredBytes) && declaredBytes > MAX_RESPONSE_BYTES) {
+        throw oversizedResponseError();
+    }
+    // The runtime's fetch declarations type the body as a stream of `any`; the
+    // fetch specification always yields byte chunks, so it is named as such here
+    // rather than measuring an untyped value.
+    const body = response.body;
+    if (body === null) {
+        return '';
+    }
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    let receivedBytes = 0;
+    let text = '';
+    try {
+        // Terminates on end of stream, or throws once the cap is exceeded. A body
+        // that never ends is bounded by the cap and by the request timeout.
+        let chunk = await reader.read();
+        while (!chunk.done) {
+            receivedBytes += chunk.value.byteLength;
+            if (receivedBytes > MAX_RESPONSE_BYTES) {
+                throw oversizedResponseError();
+            }
+            text += decoder.decode(chunk.value, { stream: true });
+            chunk = await reader.read();
+        }
+    }
+    catch (error) {
+        // Release the connection rather than leaving a half-read body open.
+        await reader.cancel().catch(() => undefined);
+        throw error;
+    }
+    return text + decoder.decode();
+}
+async function delay(milliseconds) {
+    await new Promise((resolve) => {
+        setTimeout(resolve, milliseconds);
+    });
+}
+export function createHttpClient(options) {
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const attempt = async (url, plan) => {
+        const startedAt = Date.now();
+        const response = await fetchImpl(url, plan.buildInit());
+        const rawText = await readBoundedText(response);
+        const contentType = response.headers.get('content-type') ?? undefined;
+        return {
+            status: response.status,
+            ok: response.ok,
+            rawText,
+            body: plan.parseBody(rawText, contentType),
+            contentType,
+            durationMs: Date.now() - startedAt,
+            attempts: 1,
+        };
+    };
+    /**
+     * The retry loop, shared by every request shape.
+     *
+     * Written once so that a second transport cannot acquire a retry policy of its
+     * own: `retryable` is the only thing standing between a failed card sale and a
+     * second debit, and two copies of this loop are two places for it to drift.
+     */
+    const send = async (url, plan, postOptions) => {
+        const maxAttempts = postOptions.retryable ? MAX_ATTEMPTS_RETRYABLE : 1;
+        let lastError;
+        for (let attemptNumber = 1; attemptNumber <= maxAttempts; attemptNumber += 1) {
+            try {
+                const result = await attempt(url, plan);
+                return { ...result, attempts: attemptNumber };
+            }
+            catch (error) {
+                lastError = error;
+                const willRetry = attemptNumber < maxAttempts && isTransient(error);
+                options.logger.warn('Gateway request failed', {
+                    url,
+                    attempt: attemptNumber,
+                    retryable: postOptions.retryable,
+                    willRetry,
+                });
+                if (!willRetry) {
+                    break;
+                }
+                await delay(RETRY_DELAY_MS);
+            }
+        }
+        const hint = postOptions.retryable
+            ? ''
+            : ' This call is not safe to retry automatically: it may already have been processed. Use the Status Inquiry API to establish the outcome before sending it again.';
+        throw new JazzCashGatewayError(`The JazzCash gateway could not be reached at ${url}.${hint}`, {
+            cause: lastError,
+        });
+    };
+    return {
+        async postJson(url, payload, postOptions) {
+            return send(url, {
+                buildInit: () => ({
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
+                    body: JSON.stringify(payload),
+                    signal: AbortSignal.timeout(options.timeoutMs),
+                }),
+                // Parsed whatever the gateway declares: a JSON body served as
+                // text/plain is common enough, and this is the shape every documented
+                // REST response takes.
+                parseBody: (rawText) => {
+                    try {
+                        return JSON.parse(rawText);
+                    }
+                    catch {
+                        return undefined;
+                    }
+                },
+            }, postOptions);
+        },
+    };
+}
+//# sourceMappingURL=http-client.js.map

package/dist/gateway/http-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-client.js","sourceRoot":"","sources":["../../src/gateway/http-client.ts"],"names":[],"mappings":"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"}

package/dist/gateway/rest-client.d.ts

@@ -0,0 +1,42 @@
+import type { IntegrationFlow } from '../catalogue/types.js';
+import type { JazzCashEnvironment } from '../config/environment.js';
+import type { CoreDependencies } from '../core/dependencies.js';
+import { type ClassifiedResponse } from '../domain/response-codes.js';
+import { type RawParameters } from '../domain/types.js';
+import { type HttpClient } from './http-client.js';
+/**
+ * Execute a REST flow end to end: guard, fill credentials, validate, sign, send,
+ * verify, classify.
+ */
+export type ResponseHashVerdict = 'verified' | 'unverified' | 'absent';
+export interface ResponseHashCheck {
+    readonly verdict: ResponseHashVerdict;
+    /** Absent when the flow declares no response signature: there is no field. */
+    readonly field?: string | undefined;
+    readonly note: string;
+}
+export interface GatewayCallResult {
+    readonly flowId: string;
+    readonly environment: JazzCashEnvironment;
+    readonly endpoint: string;
+    /** The transmitted payload with credentials redacted. Safe to display. */
+    readonly requestPreview: Record<string, unknown>;
+    readonly response: Record<string, unknown>;
+    readonly httpStatus: number;
+    readonly durationMs: number;
+    readonly classification: ClassifiedResponse;
+    readonly responseHash: ResponseHashCheck;
+    readonly warnings: readonly string[];
+    readonly nextSteps: readonly string[];
+}
+export interface ExecuteOptions {
+    readonly flow: IntegrationFlow;
+    readonly environment: JazzCashEnvironment;
+    readonly parameters: RawParameters;
+    readonly confirmLiveEnvironment?: boolean | undefined;
+    /** Injectable so tests never touch the network. */
+    readonly httpClient?: HttpClient | undefined;
+}
+/** Send one REST request and interpret the result. */
+export declare function executeFlow(deps: CoreDependencies, options: ExecuteOptions): Promise<GatewayCallResult>;
+//# sourceMappingURL=rest-client.d.ts.map

package/dist/gateway/rest-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rest-client.d.ts","sourceRoot":"","sources":["../../src/gateway/rest-client.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAE7D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AACpE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,EAAoB,KAAK,kBAAkB,EAAE,MAAM,6BAA6B,CAAC;AAExF,OAAO,EAKL,KAAK,aAAa,EACnB,MAAM,oBAAoB,CAAC;AAK5B,OAAO,EAAoB,KAAK,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAGrE;;;GAGG;AAEH,MAAM,MAAM,mBAAmB,GAAG,UAAU,GAAG,YAAY,GAAG,QAAQ,CAAC;AAEvE,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,OAAO,EAAE,mBAAmB,CAAC;IACtC,8EAA8E;IAC9E,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,EAAE,mBAAmB,CAAC;IAC1C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,0EAA0E;IAC1E,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC3C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,cAAc,EAAE,kBAAkB,CAAC;IAC5C,QAAQ,CAAC,YAAY,EAAE,iBAAiB,CAAC;IACzC,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;CACvC;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,QAAQ,CAAC,WAAW,EAAE,mBAAmB,CAAC;IAC1C,QAAQ,CAAC,UAAU,EAAE,aAAa,CAAC;IACnC,QAAQ,CAAC,sBAAsB,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACtD,mDAAmD;IACnD,QAAQ,CAAC,UAAU,CAAC,EAAE,UAAU,GAAG,SAAS,CAAC;CAC9C;AAkOD,sDAAsD;AACtD,wBAAsB,WAAW,CAAC,IAAI,EAAE,gBAAgB,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAmE7G"}