@atbas/m-mcp 0.1.0

package/dist/catalogue/default-catalogue.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Locate the flow catalogue that ships beside the code.
+ *
+ * Split from `loadFlowCatalogue` so that the loader itself carries no import of
+ * `../paths.js`. That module resolves the corpus directory by walking up from
+ * `import.meta.url`, which is correct for a checkout and for an npm install of
+ * this package and wrong inside a bundle — and the loader is bundled into the
+ * published connector, which ships no corpus directory and reads its
+ * specifications from generated source instead. Keeping the walk here means the
+ * connector never carries it, and `scripts/closure.mjs` enforces that.
+ *
+ * Only the *location* lives here. Loading a catalogue from it is a caller's
+ * decision — `createServerDependencies` makes it once, and the tests that want
+ * the shipped catalogue use `tests/helpers/catalogue.ts` rather than a
+ * convenience wrapper shipped in production code for their benefit.
+ */
+export declare function defaultFlowSource(): string;
+//# sourceMappingURL=default-catalogue.d.ts.map

package/dist/catalogue/default-catalogue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"default-catalogue.d.ts","sourceRoot":"","sources":["../../src/catalogue/default-catalogue.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAE1C"}

package/dist/catalogue/default-catalogue.js

@@ -0,0 +1,21 @@
+import { knowledgePath } from '../paths.js';
+/**
+ * Locate the flow catalogue that ships beside the code.
+ *
+ * Split from `loadFlowCatalogue` so that the loader itself carries no import of
+ * `../paths.js`. That module resolves the corpus directory by walking up from
+ * `import.meta.url`, which is correct for a checkout and for an npm install of
+ * this package and wrong inside a bundle — and the loader is bundled into the
+ * published connector, which ships no corpus directory and reads its
+ * specifications from generated source instead. Keeping the walk here means the
+ * connector never carries it, and `scripts/closure.mjs` enforces that.
+ *
+ * Only the *location* lives here. Loading a catalogue from it is a caller's
+ * decision — `createServerDependencies` makes it once, and the tests that want
+ * the shipped catalogue use `tests/helpers/catalogue.ts` rather than a
+ * convenience wrapper shipped in production code for their benefit.
+ */
+export function defaultFlowSource() {
+    return knowledgePath('flows');
+}
+//# sourceMappingURL=default-catalogue.js.map

package/dist/catalogue/default-catalogue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"default-catalogue.js","sourceRoot":"","sources":["../../src/catalogue/default-catalogue.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,iBAAiB;IAC/B,OAAO,aAAa,CAAC,OAAO,CAAC,CAAC;AAChC,CAAC"}

package/dist/catalogue/endpoints.d.ts

@@ -0,0 +1,22 @@
+import type { JazzCashEnvironment } from '../config/environment.js';
+import type { IntegrationFlow } from './types.js';
+/**
+ * Endpoint resolution and the portal URLs merchants need during onboarding.
+ */
+export declare const JAZZCASH_BASE_URL = "https://onlinepayments.jazzcash.com.pk";
+/** URLs that are not flow endpoints but are part of every onboarding conversation. */
+export declare const PORTAL_URLS: {
+    readonly sandboxSignup: "https://onlinepayments.jazzcash.com.pk/sandbox-frontend/";
+    readonly merchantPortalLogin: "https://onlinepayments.jazzcash.com.pk/merchant-frontend/login";
+    readonly shopifyAppListing: "https://apps.shopify.com/jazzcash";
+};
+/** Resolve the endpoint for a flow in a given environment. */
+export declare function resolveEndpoint(flow: IntegrationFlow, environment: JazzCashEnvironment): string;
+/**
+ * True when the endpoint alone cannot distinguish sandbox from production.
+ *
+ * This holds for every documented flow, which is why `environment` is a required
+ * argument on every network tool rather than something inferred from a URL.
+ */
+export declare function endpointIsAmbiguous(flow: IntegrationFlow): boolean;
+//# sourceMappingURL=endpoints.d.ts.map

package/dist/catalogue/endpoints.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"endpoints.d.ts","sourceRoot":"","sources":["../../src/catalogue/endpoints.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AACpE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD;;GAEG;AAEH,eAAO,MAAM,iBAAiB,2CAA2C,CAAC;AAE1E,sFAAsF;AACtF,eAAO,MAAM,WAAW;;;;CAId,CAAC;AAEX,8DAA8D;AAC9D,wBAAgB,eAAe,CAAC,IAAI,EAAE,eAAe,EAAE,WAAW,EAAE,mBAAmB,GAAG,MAAM,CAE/F;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO,CAElE"}

package/dist/catalogue/endpoints.js

@@ -0,0 +1,24 @@
+/**
+ * Endpoint resolution and the portal URLs merchants need during onboarding.
+ */
+export const JAZZCASH_BASE_URL = 'https://onlinepayments.jazzcash.com.pk';
+/** URLs that are not flow endpoints but are part of every onboarding conversation. */
+export const PORTAL_URLS = {
+    sandboxSignup: `${JAZZCASH_BASE_URL}/sandbox-frontend/`,
+    merchantPortalLogin: `${JAZZCASH_BASE_URL}/merchant-frontend/login`,
+    shopifyAppListing: 'https://apps.shopify.com/jazzcash',
+};
+/** Resolve the endpoint for a flow in a given environment. */
+export function resolveEndpoint(flow, environment) {
+    return environment === 'sandbox' ? flow.endpoints.sandbox : flow.endpoints.production;
+}
+/**
+ * True when the endpoint alone cannot distinguish sandbox from production.
+ *
+ * This holds for every documented flow, which is why `environment` is a required
+ * argument on every network tool rather than something inferred from a URL.
+ */
+export function endpointIsAmbiguous(flow) {
+    return flow.endpoints.sandbox === flow.endpoints.production;
+}
+//# sourceMappingURL=endpoints.js.map

package/dist/catalogue/endpoints.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"endpoints.js","sourceRoot":"","sources":["../../src/catalogue/endpoints.ts"],"names":[],"mappings":"AAGA;;GAEG;AAEH,MAAM,CAAC,MAAM,iBAAiB,GAAG,wCAAwC,CAAC;AAE1E,sFAAsF;AACtF,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,aAAa,EAAE,GAAG,iBAAiB,oBAAoB;IACvD,mBAAmB,EAAE,GAAG,iBAAiB,0BAA0B;IACnE,iBAAiB,EAAE,mCAAmC;CAC9C,CAAC;AAEX,8DAA8D;AAC9D,MAAM,UAAU,eAAe,CAAC,IAAqB,EAAE,WAAgC;IACrF,OAAO,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC;AACxF,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAqB;IACvD,OAAO,IAAI,CAAC,SAAS,CAAC,OAAO,KAAK,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC;AAC9D,CAAC"}

package/dist/catalogue/flows.d.ts

@@ -0,0 +1,32 @@
+import { type CorpusSource } from '../knowledge/source.js';
+import { type IntegrationFlow, type Product } from './types.js';
+/**
+ * Loader for the flow catalogue in `knowledge/flows/`.
+ *
+ * Specifications are parsed and validated once at start-up. A malformed file is
+ * a fatal configuration error rather than a runtime surprise: a flow with a
+ * missing parameter would silently generate an invalid payload.
+ *
+ * Files arrive through a `CorpusSource`, so the same loader serves a catalogue
+ * that is not a directory on this machine.
+ */
+export interface FlowCatalogue {
+    list(): readonly IntegrationFlow[];
+    ids(): readonly string[];
+    get(id: string): IntegrationFlow;
+    find(id: string): IntegrationFlow | undefined;
+    byProduct(product: Product): readonly IntegrationFlow[];
+}
+/**
+ * Load and index every flow specification. Throws if any file is malformed.
+ *
+ * The source is required rather than defaulted to the corpus directory beside
+ * the code. A default would mean a static import of `../paths.js`, whose
+ * package-root walk resolves from `import.meta.url` — and this module is bundled
+ * into the published connector, where that walk answers wrongly and where no
+ * corpus directory exists at all. `loadDefaultFlowCatalogue` in
+ * `./default-catalogue.js` supplies the on-disk source for every caller that
+ * wants it, and keeps that import out of the connector's module graph.
+ */
+export declare function loadFlowCatalogue(source: CorpusSource | string): FlowCatalogue;
+//# sourceMappingURL=flows.d.ts.map

package/dist/catalogue/flows.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flows.d.ts","sourceRoot":"","sources":["../../src/catalogue/flows.ts"],"names":[],"mappings":"AAGA,OAAO,EAAkB,KAAK,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAC3E,OAAO,EAAc,KAAK,eAAe,EAAE,KAAK,OAAO,EAAE,MAAM,YAAY,CAAC;AAE5E;;;;;;;;;GASG;AAEH,MAAM,WAAW,aAAa;IAC5B,IAAI,IAAI,SAAS,eAAe,EAAE,CAAC;IACnC,GAAG,IAAI,SAAS,MAAM,EAAE,CAAC;IACzB,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,eAAe,CAAC;IACjC,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAAC;IAC9C,SAAS,CAAC,OAAO,EAAE,OAAO,GAAG,SAAS,eAAe,EAAE,CAAC;CACzD;AA2BD;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,GAAG,aAAa,CAiC9E"}

package/dist/catalogue/flows.js

@@ -0,0 +1,64 @@
+import { basename } from 'node:path';
+import { JazzCashConfigError, JazzCashNotFoundError } from '../errors.js';
+import { toCorpusSource } from '../knowledge/source.js';
+import { flowSchema } from './types.js';
+function readFlowFile(files, name) {
+    let parsedJson;
+    try {
+        parsedJson = JSON.parse(files.readText(name));
+    }
+    catch (cause) {
+        throw new JazzCashConfigError(`Flow specification ${name} is not readable JSON.`, { cause });
+    }
+    const parsed = flowSchema.safeParse(parsedJson);
+    if (!parsed.success) {
+        const issues = parsed.error.issues.map((issue) => `${issue.path.join('.')}: ${issue.message}`).join('; ');
+        throw new JazzCashConfigError(`Flow specification ${name} is invalid. ${issues}`);
+    }
+    const flow = parsed.data;
+    const expectedId = basename(name, '.json');
+    if (flow.id !== expectedId) {
+        throw new JazzCashConfigError(`Flow specification ${name} declares id "${flow.id}". The file name and the id must match so that citations resolve.`);
+    }
+    return flow;
+}
+/**
+ * Load and index every flow specification. Throws if any file is malformed.
+ *
+ * The source is required rather than defaulted to the corpus directory beside
+ * the code. A default would mean a static import of `../paths.js`, whose
+ * package-root walk resolves from `import.meta.url` — and this module is bundled
+ * into the published connector, where that walk answers wrongly and where no
+ * corpus directory exists at all. `loadDefaultFlowCatalogue` in
+ * `./default-catalogue.js` supplies the on-disk source for every caller that
+ * wants it, and keeps that import out of the connector's module graph.
+ */
+export function loadFlowCatalogue(source) {
+    const files = toCorpusSource(source);
+    let fileNames;
+    try {
+        fileNames = files.entryNames().filter((name) => name.endsWith('.json'));
+    }
+    catch (cause) {
+        throw new JazzCashConfigError(`Unable to read the flow catalogue directory at ${files.location}.`, { cause });
+    }
+    if (fileNames.length === 0) {
+        throw new JazzCashConfigError(`No flow specifications found in ${files.location}.`);
+    }
+    const flows = fileNames.map((name) => readFlowFile(files, name)).sort((left, right) => (left.id < right.id ? -1 : 1));
+    const byId = new Map(flows.map((flow) => [flow.id, flow]));
+    return {
+        list: () => flows,
+        ids: () => flows.map((flow) => flow.id),
+        find: (id) => byId.get(id),
+        get(id) {
+            const flow = byId.get(id);
+            if (flow === undefined) {
+                throw new JazzCashNotFoundError(`No integration flow with id "${id}". Available flows: ${flows.map((entry) => entry.id).join(', ')}.`);
+            }
+            return flow;
+        },
+        byProduct: (product) => flows.filter((flow) => flow.product === product),
+    };
+}
+//# sourceMappingURL=flows.js.map

package/dist/catalogue/flows.js.map

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

package/dist/catalogue/hash-options.d.ts

@@ -0,0 +1,112 @@
+import type { SignatureOptions } from '../domain/signature/registry.js';
+import type { SchemeProvenance } from '../domain/signature/scheme.js';
+import type { IntegrationFlow } from './types.js';
+/**
+ * Hash options derived from a flow specification.
+ *
+ * Requests and responses do NOT share a field-selection rule, and conflating
+ * them is a security defect rather than a tidiness problem:
+ *
+ *  - Requests are prefix-filtered (`pp_`, `ppmpf_`), because a merchant payload
+ *    may legitimately carry application fields that must not be hashed.
+ *  - Responses are NOT prefix-filtered. Card refund v1.1, card refund v2.0 and
+ *    BNPL refund return `ResponseCode`, `ResponseMessage`, `RefundAmount`,
+ *    `TotalRefundAmount` and `SecureHash` with no prefix at all. Applying the
+ *    request filter to those responses removes every field, collapsing the hash
+ *    input to the bare Integrity Salt — which produces the same digest for any
+ *    response body, so a forged response verifies successfully.
+ *
+ * Both derivations live here, named for their direction, so a call site cannot
+ * reach for the wrong one by spreading `flow.hash` into a response check.
+ *
+ * Each derivation also names the signature SCHEME it selects, rather than
+ * returning `flow.hash` directly. A hash specification is structurally
+ * assignable to the JazzCash options whatever construction it describes, so a
+ * direct return compiles for a second scheme and signs it the wrong way, with
+ * no error until the gateway rejects the transaction.
+ */
+/** Field selection and construction for signing and verifying a REQUEST. */
+export declare function requestHashOptions(flow: IntegrationFlow): SignatureOptions;
+/**
+ * Field selection for verifying a RESPONSE.
+ *
+ * The JazzCash spellings are excluded alongside the flow's own field name,
+ * because a flow's field name is not always the one present in a hand-pasted
+ * payload. A flow that declares no response signature contributes no name of
+ * its own, and the two spellings still have to go: this function is also called
+ * for payloads that arrive without a flow.
+ *
+ * JazzCash-scoped, which is every flow the corpus ships. A gateway whose
+ * responses are signed by some other construction would need that construction
+ * derivable from the response spec — which declares no ordered component list,
+ * and inventing one produces a confident digest computed over the wrong string.
+ * Such a gateway must declare what its responses sign, and this function must
+ * then select the scheme the way `requestHashOptions` does.
+ */
+export declare function responseHashOptions(flow: IntegrationFlow): SignatureOptions;
+/**
+ * JazzCash response field selection when the flow is unknown.
+ *
+ * Used by tools that accept a payload without a `flowId`, and by IPN
+ * verification, which has no flow. No prefix filter: an unfiltered hash may be
+ * wrong for a given flow, but a filtered one is silently vacuous for the three
+ * refund flows, and a wrong answer is safer than a vacuous one.
+ *
+ * The scheme is named rather than left to default, because the exclusions below
+ * are JazzCash field names. Another gateway's callback verified with these would
+ * feed its own signature back into its own input and could only ever come back
+ * unverified — a result that must not be read as evidence of a broken
+ * integration.
+ *
+ * That argument covers verification and nothing else, and this constant also
+ * reaches DIAGNOSIS, where "wrong is safer than vacuous" inverts: a wrong
+ * construction replayed through a forensic table reproduces a foreign gateway's
+ * CORRECT signature and reports it as a proven defect. Measured on shipping
+ * code, a gateway signing `SHA256(secret&sorted-values)` was told "Reproduced
+ * your hash exactly by applying a known construction error: Plain SHA-256 used
+ * instead of HMAC-SHA256". `forensicProvenance` is what stops it.
+ */
+export declare const UNKNOWN_FLOW_RESPONSE_HASH_OPTIONS: SignatureOptions;
+/**
+ * Whether a mismatch under the derivation above may be reported as a proven cause.
+ *
+ * A `confirmed` hypothesis says a known wrong construction reproduced the
+ * merchant's signature exactly. That is evidence only where the construction it
+ * varies is the one the payload was signed under, and the three derivations
+ * above differ in whether it is:
+ *
+ *  - REQUEST — `requestHashOptions` reads the construction from the flow's own
+ *    `hash` specification, so it is declared. With no flow the JazzCash default
+ *    applies, and that default selects `pp_`/`ppmpf_` fields only: a payload
+ *    from another gateway contributes nothing to it, so no variant can
+ *    reproduce that gateway's signature. Both are evidence.
+ *  - RESPONSE — both response derivations select the JazzCash construction with
+ *    NO prefix filter, so they will happily hash a foreign payload's fields
+ *    under JazzCash rules. For a flow the corpus knows that is the gateway's own
+ *    construction and the reproduction stands. For a payload arriving without
+ *    one it is this server's guess, and a guess cannot demonstrate what a
+ *    merchant's code did.
+ *
+ * Named for the decision rather than folded into the options, because the
+ * options are also passed to `computeSecureHash`, where the same assumption is
+ * survivable: an unverified response is reported as unverified (assumption A2),
+ * while an unfounded `confirmed` sends a merchant to break working code.
+ */
+export declare function forensicProvenance(flow: IntegrationFlow | undefined, direction: 'request' | 'response'): SchemeProvenance;
+/**
+ * The parameter a flow writes its request signature into.
+ *
+ * Read from the flow rather than spelled `pp_SecureHash` at the call site: that
+ * is JazzCash's name for it, and a payload built for a gateway that spells it
+ * otherwise carries a correct digest in a field that gateway never reads — a
+ * rejected transaction with nothing in the response to explain it. The flow already
+ * carries the answer as the parameter whose `valueType` is `secure-hash`, and
+ * `tests/catalogue/flows.test.ts` asserts every flow declares exactly one, so
+ * no new schema field is needed to derive it.
+ *
+ * Returns `undefined` for a flow that declares none, because a flow that does
+ * not sign has no field to name and inventing one would be the same defect
+ * pointed the other way.
+ */
+export declare function signatureFieldName(flow: IntegrationFlow): string | undefined;
+//# sourceMappingURL=hash-options.d.ts.map

package/dist/catalogue/hash-options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hash-options.d.ts","sourceRoot":"","sources":["../../src/catalogue/hash-options.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AACxE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAEtE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,4EAA4E;AAC5E,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,eAAe,GAAG,gBAAgB,CAwB1E;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,eAAe,GAAG,gBAAgB,CAQ3E;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,kCAAkC,EAAE,gBAIhD,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,eAAe,GAAG,SAAS,EACjC,SAAS,EAAE,SAAS,GAAG,UAAU,GAChC,gBAAgB,CAOlB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,eAAe,GAAG,MAAM,GAAG,SAAS,CAE5E"}

package/dist/catalogue/hash-options.js

@@ -0,0 +1,151 @@
+/**
+ * Hash options derived from a flow specification.
+ *
+ * Requests and responses do NOT share a field-selection rule, and conflating
+ * them is a security defect rather than a tidiness problem:
+ *
+ *  - Requests are prefix-filtered (`pp_`, `ppmpf_`), because a merchant payload
+ *    may legitimately carry application fields that must not be hashed.
+ *  - Responses are NOT prefix-filtered. Card refund v1.1, card refund v2.0 and
+ *    BNPL refund return `ResponseCode`, `ResponseMessage`, `RefundAmount`,
+ *    `TotalRefundAmount` and `SecureHash` with no prefix at all. Applying the
+ *    request filter to those responses removes every field, collapsing the hash
+ *    input to the bare Integrity Salt — which produces the same digest for any
+ *    response body, so a forged response verifies successfully.
+ *
+ * Both derivations live here, named for their direction, so a call site cannot
+ * reach for the wrong one by spreading `flow.hash` into a response check.
+ *
+ * Each derivation also names the signature SCHEME it selects, rather than
+ * returning `flow.hash` directly. A hash specification is structurally
+ * assignable to the JazzCash options whatever construction it describes, so a
+ * direct return compiles for a second scheme and signs it the wrong way, with
+ * no error until the gateway rejects the transaction.
+ */
+/** Field selection and construction for signing and verifying a REQUEST. */
+export function requestHashOptions(flow) {
+    const hash = flow.hash;
+    // Exhaustive by construction: a second algorithm added to the flow schema
+    // fails to compile here rather than silently inheriting this one.
+    switch (hash.algorithm) {
+        case 'hmac-sha256':
+            return {
+                scheme: 'jazzcash',
+                includeFieldPrefixes: hash.includeFieldPrefixes,
+                excludeFields: hash.excludeFields,
+                outputEncoding: hash.outputEncoding,
+                comparison: hash.comparison,
+            };
+    }
+    // A second algorithm fails on this line, naming itself. Left to TypeScript's
+    // "lacks ending return statement" the error is about this function rather than
+    // about the member nobody handled, and the obvious way to silence it is a
+    // `default:` — which signs the new construction as the one above.
+    /* c8 ignore start -- unreachable: the switch above is exhaustive, and the assignment below is what proves it */
+    const _exhaustive = hash.algorithm;
+    return _exhaustive;
+    /* c8 ignore stop */
+}
+/**
+ * Field selection for verifying a RESPONSE.
+ *
+ * The JazzCash spellings are excluded alongside the flow's own field name,
+ * because a flow's field name is not always the one present in a hand-pasted
+ * payload. A flow that declares no response signature contributes no name of
+ * its own, and the two spellings still have to go: this function is also called
+ * for payloads that arrive without a flow.
+ *
+ * JazzCash-scoped, which is every flow the corpus ships. A gateway whose
+ * responses are signed by some other construction would need that construction
+ * derivable from the response spec — which declares no ordered component list,
+ * and inventing one produces a confident digest computed over the wrong string.
+ * Such a gateway must declare what its responses sign, and this function must
+ * then select the scheme the way `requestHashOptions` does.
+ */
+export function responseHashOptions(flow) {
+    const declaredField = flow.response.hashField;
+    return {
+        scheme: 'jazzcash',
+        includeFieldPrefixes: flow.response.hashFieldPrefixes,
+        excludeFields: [...(declaredField === undefined ? [] : [declaredField]), 'pp_SecureHash', 'SecureHash'],
+    };
+}
+/**
+ * JazzCash response field selection when the flow is unknown.
+ *
+ * Used by tools that accept a payload without a `flowId`, and by IPN
+ * verification, which has no flow. No prefix filter: an unfiltered hash may be
+ * wrong for a given flow, but a filtered one is silently vacuous for the three
+ * refund flows, and a wrong answer is safer than a vacuous one.
+ *
+ * The scheme is named rather than left to default, because the exclusions below
+ * are JazzCash field names. Another gateway's callback verified with these would
+ * feed its own signature back into its own input and could only ever come back
+ * unverified — a result that must not be read as evidence of a broken
+ * integration.
+ *
+ * That argument covers verification and nothing else, and this constant also
+ * reaches DIAGNOSIS, where "wrong is safer than vacuous" inverts: a wrong
+ * construction replayed through a forensic table reproduces a foreign gateway's
+ * CORRECT signature and reports it as a proven defect. Measured on shipping
+ * code, a gateway signing `SHA256(secret&sorted-values)` was told "Reproduced
+ * your hash exactly by applying a known construction error: Plain SHA-256 used
+ * instead of HMAC-SHA256". `forensicProvenance` is what stops it.
+ */
+export const UNKNOWN_FLOW_RESPONSE_HASH_OPTIONS = {
+    scheme: 'jazzcash',
+    includeFieldPrefixes: [],
+    excludeFields: ['pp_SecureHash', 'SecureHash'],
+};
+/**
+ * Whether a mismatch under the derivation above may be reported as a proven cause.
+ *
+ * A `confirmed` hypothesis says a known wrong construction reproduced the
+ * merchant's signature exactly. That is evidence only where the construction it
+ * varies is the one the payload was signed under, and the three derivations
+ * above differ in whether it is:
+ *
+ *  - REQUEST — `requestHashOptions` reads the construction from the flow's own
+ *    `hash` specification, so it is declared. With no flow the JazzCash default
+ *    applies, and that default selects `pp_`/`ppmpf_` fields only: a payload
+ *    from another gateway contributes nothing to it, so no variant can
+ *    reproduce that gateway's signature. Both are evidence.
+ *  - RESPONSE — both response derivations select the JazzCash construction with
+ *    NO prefix filter, so they will happily hash a foreign payload's fields
+ *    under JazzCash rules. For a flow the corpus knows that is the gateway's own
+ *    construction and the reproduction stands. For a payload arriving without
+ *    one it is this server's guess, and a guess cannot demonstrate what a
+ *    merchant's code did.
+ *
+ * Named for the decision rather than folded into the options, because the
+ * options are also passed to `computeSecureHash`, where the same assumption is
+ * survivable: an unverified response is reported as unverified (assumption A2),
+ * while an unfounded `confirmed` sends a merchant to break working code.
+ */
+export function forensicProvenance(flow, direction) {
+    if (direction === 'request') {
+        return 'declared';
+    }
+    // With a flow, the response construction above IS that flow's own. Without
+    // one, it is this server's assumption and may not be reported as proof.
+    return flow === undefined ? 'assumed' : 'declared';
+}
+/**
+ * The parameter a flow writes its request signature into.
+ *
+ * Read from the flow rather than spelled `pp_SecureHash` at the call site: that
+ * is JazzCash's name for it, and a payload built for a gateway that spells it
+ * otherwise carries a correct digest in a field that gateway never reads — a
+ * rejected transaction with nothing in the response to explain it. The flow already
+ * carries the answer as the parameter whose `valueType` is `secure-hash`, and
+ * `tests/catalogue/flows.test.ts` asserts every flow declares exactly one, so
+ * no new schema field is needed to derive it.
+ *
+ * Returns `undefined` for a flow that declares none, because a flow that does
+ * not sign has no field to name and inventing one would be the same defect
+ * pointed the other way.
+ */
+export function signatureFieldName(flow) {
+    return flow.parameters.find((parameter) => parameter.valueType === 'secure-hash')?.name;
+}
+//# sourceMappingURL=hash-options.js.map

package/dist/catalogue/hash-options.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hash-options.js","sourceRoot":"","sources":["../../src/catalogue/hash-options.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,4EAA4E;AAC5E,MAAM,UAAU,kBAAkB,CAAC,IAAqB;IACtD,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;IAEvB,0EAA0E;IAC1E,kEAAkE;IAClE,QAAQ,IAAI,CAAC,SAAS,EAAE,CAAC;QACvB,KAAK,aAAa;YAChB,OAAO;gBACL,MAAM,EAAE,UAAU;gBAClB,oBAAoB,EAAE,IAAI,CAAC,oBAAoB;gBAC/C,aAAa,EAAE,IAAI,CAAC,aAAa;gBACjC,cAAc,EAAE,IAAI,CAAC,cAAc;gBACnC,UAAU,EAAE,IAAI,CAAC,UAAU;aAC5B,CAAC;IACN,CAAC;IAED,6EAA6E;IAC7E,+EAA+E;IAC/E,0EAA0E;IAC1E,kEAAkE;IAClE,gHAAgH;IAChH,MAAM,WAAW,GAAU,IAAI,CAAC,SAAS,CAAC;IAC1C,OAAO,WAAW,CAAC;IACnB,oBAAoB;AACtB,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAqB;IACvD,MAAM,aAAa,GAAG,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC;IAE9C,OAAO;QACL,MAAM,EAAE,UAAU;QAClB,oBAAoB,EAAE,IAAI,CAAC,QAAQ,CAAC,iBAAiB;QACrD,aAAa,EAAE,CAAC,GAAG,CAAC,aAAa,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,EAAE,eAAe,EAAE,YAAY,CAAC;KACxG,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,CAAC,MAAM,kCAAkC,GAAqB;IAClE,MAAM,EAAE,UAAU;IAClB,oBAAoB,EAAE,EAAE;IACxB,aAAa,EAAE,CAAC,eAAe,EAAE,YAAY,CAAC;CAC/C,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,UAAU,kBAAkB,CAChC,IAAiC,EACjC,SAAiC;IAEjC,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;QAC5B,OAAO,UAAU,CAAC;IACpB,CAAC;IACD,2EAA2E;IAC3E,wEAAwE;IACxE,OAAO,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,UAAU,CAAC;AACrD,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAAqB;IACtD,OAAO,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,SAAS,KAAK,aAAa,CAAC,EAAE,IAAI,CAAC;AAC1F,CAAC"}