@atbas/m-mcp 0.1.0

package/dist/domain/secure-hash.js

@@ -0,0 +1,69 @@
+import { createHmac } from 'node:crypto';
+import { buildSignatureFor, computeSignatureFor, diagnoseSignatureFor, verifySignatureFor, } from './signature/registry.js';
+import { JAZZCASH_SCHEME } from './signature/jazzcash.js';
+import { signaturesMatch } from './signature/scheme.js';
+/**
+ * The JazzCash forensic table.
+ *
+ * Reachable only as this scheme's property. Several entries describe how other
+ * gateways sign correctly, so a table shared between providers would report
+ * working code as a proven defect.
+ */
+export const HASH_VARIANTS = JAZZCASH_SCHEME.variants;
+/**
+ * Build the exact string that gets hashed, plus the reasoning behind it.
+ *
+ * Returning the breakdown rather than only the digest is the point: a merchant
+ * debugging `HASH_MISMATCH` needs to see which fields were used and in what
+ * order, which is precisely what no error message from the gateway tells them.
+ */
+export function buildHashString(parameters, integritySalt, options) {
+    return buildSignatureFor(parameters, integritySalt, options);
+}
+/** HMAC-SHA256 a prepared string with the Integrity Salt as key. Lowercase hex. */
+export function hmacSha256Hex(message, key) {
+    return createHmac('sha256', key).update(message, 'utf8').digest('hex');
+}
+/** Compute `pp_SecureHash` for a payload. Lowercase hex, as PHP's `hash_hmac` emits. */
+export function computeSecureHash(parameters, integritySalt, options) {
+    return computeSignatureFor(parameters, integritySalt, options);
+}
+/**
+ * Constant-time, case-insensitive hash comparison.
+ *
+ * Case insensitivity is required, not merely tolerant: request samples in the
+ * guides are lowercase (PHP `hash_hmac` output) while response samples are
+ * uppercase. Both are the same digest.
+ */
+export function hashesMatch(left, right) {
+    return signaturesMatch(left, right, 'case-insensitive');
+}
+/** Verify a supplied hash against a freshly computed one. */
+export function verifySecureHash(parameters, integritySalt, providedHash, options) {
+    return verifySignatureFor(parameters, integritySalt, providedHash, options);
+}
+/**
+ * Explain why a hash does not match.
+ *
+ * Runs the selected scheme's known wrong constructions against the merchant's
+ * own parameters. A variant that reproduces their hash is reported as
+ * `confirmed`: that is not a guess, it is a demonstration of what their code
+ * did — which is why only the scheme the payload was signed under may be asked,
+ * and why `provenance` says whether the payload named that scheme.
+ *
+ * `provenance` is required rather than defaulted, for the same reason it is
+ * required on `diagnoseSignatureFor`: the safe value is the one that reports
+ * less, and a default of `declared` is the unsafe one, so a call site that
+ * forgot the argument would accuse a merchant of a construction error
+ * demonstrated under a construction nobody said they used. `declared` is the
+ * answer for every REQUEST — a flow's own hash specification selects the
+ * construction, and the flowless default selects `pp_`/`ppmpf_` fields only, so
+ * another provider's payload contributes nothing to it and no variant can
+ * reproduce that provider's signature. The response derivations are the ones
+ * that must pass `assumed`; see `requestHashOptions`, `responseHashOptions` and
+ * `forensicProvenance` in `src/catalogue/hash-options.ts`.
+ */
+export function diagnoseHashMismatch(parameters, integritySalt, providedHash, options, provenance) {
+    return diagnoseSignatureFor(parameters, integritySalt, providedHash, options, provenance);
+}
+//# sourceMappingURL=secure-hash.js.map

package/dist/domain/secure-hash.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"secure-hash.js","sourceRoot":"","sources":["../../src/domain/secure-hash.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,OAAO,EACL,iBAAiB,EACjB,mBAAmB,EACnB,oBAAoB,EACpB,kBAAkB,GAEnB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,eAAe,EAAkC,MAAM,yBAAyB,CAAC;AAC1F,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAiCxD;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,aAAa,GAA2D,eAAe,CAAC,QAAQ,CAAC;AAE9G;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAC7B,UAAyB,EACzB,aAAqB,EACrB,OAA0B;IAE1B,OAAO,iBAAiB,CAAC,UAAU,EAAE,aAAa,EAAE,OAAO,CAAC,CAAC;AAC/D,CAAC;AAED,mFAAmF;AACnF,MAAM,UAAU,aAAa,CAAC,OAAe,EAAE,GAAW;IACxD,OAAO,UAAU,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AACzE,CAAC;AAED,wFAAwF;AACxF,MAAM,UAAU,iBAAiB,CAC/B,UAAyB,EACzB,aAAqB,EACrB,OAA0B;IAE1B,OAAO,mBAAmB,CAAC,UAAU,EAAE,aAAa,EAAE,OAAO,CAAC,CAAC;AACjE,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CAAC,IAAY,EAAE,KAAa;IACrD,OAAO,eAAe,CAAC,IAAI,EAAE,KAAK,EAAE,kBAAkB,CAAC,CAAC;AAC1D,CAAC;AAED,6DAA6D;AAC7D,MAAM,UAAU,gBAAgB,CAC9B,UAAyB,EACzB,aAAqB,EACrB,YAAoB,EACpB,OAA0B;IAE1B,OAAO,kBAAkB,CAAC,UAAU,EAAE,aAAa,EAAE,YAAY,EAAE,OAAO,CAAC,CAAC;AAC9E,CAAC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,oBAAoB,CAClC,UAAyB,EACzB,aAAqB,EACrB,YAAoB,EACpB,OAAqC,EACrC,UAA4B;IAE5B,OAAO,oBAAoB,CAAC,UAAU,EAAE,aAAa,EAAE,YAAY,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC;AAC5F,CAAC"}

package/dist/domain/signature/jazzcash.d.ts

@@ -0,0 +1,56 @@
+import { type SignatureEncoding, type SignatureComparison, type SignatureScheme } from './scheme.js';
+/**
+ * Per-flow configuration for the JazzCash scheme, as a caller may supply it.
+ *
+ * `scheme` is optional and single-valued so that every call site written before
+ * a second provider existed still selects this construction. Omitting it is not
+ * a default in the loose sense: an options object with no `scheme` cannot name
+ * any other one.
+ */
+export interface JazzCashHashOptions {
+    readonly scheme?: 'jazzcash' | undefined;
+    /**
+     * Only fields starting with one of these prefixes participate.
+     *
+     * Assumption A1: the PHP samples include non-empty `ppmpf_*` fields, while the
+     * JavaScript linking sample selects only `pp_*`. The two disagree whenever a
+     * `ppmpf_*` field carries a value. The default follows the PHP samples;
+     * flow specifications may override it, so a correction from JazzCash is a data
+     * change rather than a code change.
+     */
+    readonly includeFieldPrefixes?: readonly string[] | undefined;
+    /** Fields excluded regardless of value. Defaults to the hash field itself. */
+    readonly excludeFields?: readonly string[] | undefined;
+    /**
+     * Treat a whitespace-only value as empty.
+     *
+     * Off by default: no guide says whitespace is stripped, and silently trimming
+     * would produce a hash the gateway does not expect. No flow declares it — the
+     * hash specification has no such field — so it is reachable only from a caller
+     * that passes these options directly, as a way of asking "would my hash match
+     * if my gateway ignored whitespace-only values?".
+     *
+     * It resolves into the plan, so the forensic table sees it too: every variant
+     * is the flow's OWN construction with one field changed, and a variant that
+     * quietly reverted this one would differ in two ways and would then name the
+     * wrong cause when it reproduced a merchant's hash. Reverting it is what the
+     * engine did before the plan existed.
+     */
+    readonly treatWhitespaceOnlyAsEmpty?: boolean | undefined;
+    /** Digest encoding. Defaults to the lowercase hex PHP's `hash_hmac` emits. */
+    readonly outputEncoding?: SignatureEncoding | undefined;
+    /** Comparison rule. Defaults to case-insensitive; see `SignatureComparison`. */
+    readonly comparison?: SignatureComparison | undefined;
+}
+/** The same configuration with every default already applied. */
+export interface JazzCashSignatureSettings {
+    readonly includeFieldPrefixes: readonly string[];
+    readonly excludeFields: readonly string[];
+    readonly treatWhitespaceOnlyAsEmpty: boolean;
+    readonly outputEncoding?: SignatureEncoding | undefined;
+    readonly comparison?: SignatureComparison | undefined;
+}
+/** Apply the documented defaults to whatever the caller supplied. */
+export declare function jazzCashSettings(options: JazzCashHashOptions | undefined): JazzCashSignatureSettings;
+export declare const JAZZCASH_SCHEME: SignatureScheme<JazzCashSignatureSettings>;
+//# sourceMappingURL=jazzcash.d.ts.map

package/dist/domain/signature/jazzcash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jazzcash.d.ts","sourceRoot":"","sources":["../../../src/domain/signature/jazzcash.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,iBAAiB,EACtB,KAAK,mBAAmB,EAIxB,KAAK,eAAe,EAErB,MAAM,aAAa,CAAC;AAgCrB;;;;;;;GAOG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,MAAM,CAAC,EAAE,UAAU,GAAG,SAAS,CAAC;IACzC;;;;;;;;OAQG;IACH,QAAQ,CAAC,oBAAoB,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;IAC9D,8EAA8E;IAC9E,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;IACvD;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,0BAA0B,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC1D,8EAA8E;IAC9E,QAAQ,CAAC,cAAc,CAAC,EAAE,iBAAiB,GAAG,SAAS,CAAC;IACxD,gFAAgF;IAChF,QAAQ,CAAC,UAAU,CAAC,EAAE,mBAAmB,GAAG,SAAS,CAAC;CACvD;AAED,iEAAiE;AACjE,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,oBAAoB,EAAE,SAAS,MAAM,EAAE,CAAC;IACjD,QAAQ,CAAC,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C,QAAQ,CAAC,0BAA0B,EAAE,OAAO,CAAC;IAC7C,QAAQ,CAAC,cAAc,CAAC,EAAE,iBAAiB,GAAG,SAAS,CAAC;IACxD,QAAQ,CAAC,UAAU,CAAC,EAAE,mBAAmB,GAAG,SAAS,CAAC;CACvD;AAED,qEAAqE;AACrE,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,mBAAmB,GAAG,SAAS,GAAG,yBAAyB,CAQpG;AAgLD,eAAO,MAAM,eAAe,EAAE,eAAe,CAAC,yBAAyB,CAatE,CAAC"}

package/dist/domain/signature/jazzcash.js

@@ -0,0 +1,214 @@
+import { defineVariants, describeConstruction, } from './scheme.js';
+/**
+ * The JazzCash `pp_SecureHash` construction and its forensics.
+ *
+ * The algorithm, per `How is HMAC-SHA256 calculated (2026).pdf` and confirmed by
+ * the PHP and JavaScript samples in the redirection and linking guides:
+ *
+ *   1. Take every parameter whose value is non-empty.
+ *   2. Sort by parameter NAME, ascending ASCII.
+ *   3. Join the VALUES with `&`.
+ *   4. Prepend the Integrity Salt, separated by `&`.
+ *   5. HMAC-SHA256 the result, using the Integrity Salt as the secret key.
+ *
+ * Official worked example (salt `3vv9wu3a18`):
+ *   `3vv9wu3a18&25000&MC25041&1234&sz1v4agvyf&PKR&T20220518150213`
+ *
+ * Two deliberate divergences from the official PHP sample, both bug fixes:
+ *
+ *  - The sample uses loose comparison (`$value != ""`), which discards an
+ *    integer `0`. This implementation treats a value as empty only when it is
+ *    the empty string after normalisation.
+ *  - The sample sorts with `ksort()` under `SORT_REGULAR`. This implementation
+ *    sorts by ASCII code unit explicitly, which is what the specification says.
+ */
+/** Prefixes whose fields participate in the hash by default. */
+const DEFAULT_HASH_FIELD_PREFIXES = ['pp_', 'ppmpf_'];
+/** Fields never included in their own hash input. */
+const DEFAULT_EXCLUDED_HASH_FIELDS = ['pp_SecureHash', 'SecureHash'];
+/** Apply the documented defaults to whatever the caller supplied. */
+export function jazzCashSettings(options) {
+    return {
+        includeFieldPrefixes: options?.includeFieldPrefixes ?? DEFAULT_HASH_FIELD_PREFIXES,
+        excludeFields: options?.excludeFields ?? DEFAULT_EXCLUDED_HASH_FIELDS,
+        treatWhitespaceOnlyAsEmpty: options?.treatWhitespaceOnlyAsEmpty ?? false,
+        outputEncoding: options?.outputEncoding,
+        comparison: options?.comparison,
+    };
+}
+function jazzCashPlan(settings) {
+    return {
+        selection: {
+            kind: 'prefix',
+            includeFieldPrefixes: settings.includeFieldPrefixes,
+            excludeFields: settings.excludeFields,
+        },
+        ordering: 'name-ascending',
+        pairing: 'values-only',
+        valueTransform: 'as-transmitted',
+        omitEmptyValues: true,
+        treatWhitespaceOnlyAsEmpty: settings.treatWhitespaceOnlyAsEmpty,
+        separator: '&',
+        trailingSeparator: false,
+        secretPlacement: 'prepend',
+        primitive: 'hmac',
+        digest: 'sha256',
+        encoding: settings.outputEncoding ?? 'hex-lowercase',
+        comparison: settings.comparison ?? 'case-insensitive',
+    };
+}
+const JAZZCASH_SECRET = {
+    label: 'Integrity Salt',
+    role: 'It is both prepended to the hash string and used as the HMAC key, so it cannot produce a valid pp_SecureHash.',
+    docRefs: [{ docId: 'hmac-sha256-calculation', sectionId: 'how-is-hmac-sha256-calculated' }],
+};
+const JAZZCASH_NARRATIVE = {
+    matched: 'The hash matches. The secure hash was constructed correctly for this payload and salt.',
+    reproducedPrefix: 'Reproduced your hash exactly by applying a known construction error',
+    unexplained: 'The hash does not match and no known construction error reproduces it. The salt or the transmitted values are the most likely cause.',
+};
+/**
+ * The thirteen ways a JazzCash integration gets this wrong.
+ *
+ * Several entries — a plain digest, the salt at the far end, empty values kept —
+ * are how other gateways sign CORRECTLY, so what this table may be replayed
+ * against matters as much as what is in it.
+ *
+ * Two things keep that honest, and neither is the file boundary. Each entry is a
+ * single-field `PlanDelta` the engine applies to whatever plan it is bound to,
+ * so an entry cannot name a construction of its own; and `defineVariants` binds
+ * this table to `jazzCashPlan`, so every entry is the merchant's own JazzCash
+ * construction with exactly one field wrong. What the types do NOT enforce is
+ * that a delta table is bound to the scheme whose vocabulary it is written in —
+ * bound to another plan, these entries would describe real near misses of that
+ * plan in the wrong provider's words. `tests/domain/signature.test.ts` pins the
+ * binding per scheme, in both directions.
+ */
+const JAZZCASH_VARIANT_DEFINITIONS = [
+    {
+        id: 'salt-appended',
+        label: 'Integrity Salt appended instead of prepended',
+        explanation: 'The salt is joined to the end of the value list rather than the beginning.',
+        fix: 'Build the string as `salt & value1 & value2 & …`. The salt comes first, before any parameter value.',
+        change: { set: 'secretPlacement', to: 'append' },
+    },
+    {
+        id: 'salt-omitted',
+        label: 'Integrity Salt not included in the hash string',
+        explanation: 'The salt is used as the HMAC key but never prepended to the message.',
+        fix: 'Prepend the salt to the concatenated values as well as using it as the HMAC key. It appears twice, by design.',
+        change: { set: 'secretPlacement', to: 'none' },
+    },
+    {
+        id: 'include-empty-fields',
+        label: 'Empty parameters included in the hash string',
+        explanation: 'Every declared parameter was concatenated, including those left as "". Empty fields must still be SENT, but must not be HASHED.',
+        fix: 'Skip parameters whose value is the empty string when building the hash string. Keep sending them in the request payload.',
+        change: { set: 'omitEmptyValues', to: false },
+    },
+    {
+        id: 'include-secure-hash-field',
+        label: 'pp_SecureHash included in its own input',
+        explanation: 'A previous hash value was left in the payload and fed back into the calculation.',
+        fix: 'Remove pp_SecureHash from the parameter set before computing the hash, then add it to the request afterwards.',
+        change: { set: 'excludeFields', to: [] },
+    },
+    {
+        id: 'pp-prefix-only',
+        label: 'ppmpf_* fields excluded from the hash',
+        explanation: 'Only fields named pp_* were hashed. The official JavaScript sample does this; the official PHP samples include non-empty ppmpf_* fields too.',
+        fix: 'Include non-empty ppmpf_1..5 in the hash string, or set the flow to pp_-only if JazzCash confirms that is correct for your account.',
+        change: { set: 'includeFieldPrefixes', to: ['pp_'] },
+    },
+    {
+        id: 'insertion-order',
+        label: 'Values concatenated in payload order rather than sorted',
+        explanation: 'The parameters were not sorted by name before their values were joined.',
+        fix: 'Sort the parameter NAMES ascending by ASCII, then join their VALUES in that order.',
+        change: { set: 'ordering', to: 'as-listed' },
+    },
+    {
+        id: 'descending-order',
+        label: 'Values sorted descending',
+        explanation: 'The sort direction is reversed.',
+        fix: 'Sort ascending, not descending.',
+        change: { set: 'ordering', to: 'name-descending' },
+    },
+    {
+        id: 'case-insensitive-sort',
+        label: 'Parameter names sorted case-insensitively',
+        explanation: 'Sorting was done after lower-casing the names, which reorders fields relative to ASCII order because uppercase letters sort before lowercase.',
+        fix: 'Sort the raw parameter names by ASCII code, without changing their case.',
+        change: { set: 'ordering', to: 'name-ascending-folded' },
+    },
+    {
+        id: 'key-value-pairs',
+        label: 'Keys concatenated alongside values',
+        explanation: 'The string was built as `name=value` pairs rather than values only.',
+        fix: 'Concatenate only the VALUES, separated by &. Parameter names are used for sorting, never for hashing.',
+        change: { set: 'pairing', to: 'name-and-value' },
+    },
+    {
+        id: 'no-separator',
+        label: 'Values concatenated without a separator',
+        explanation: 'The `&` between values was omitted.',
+        fix: 'Separate every value with a single & character, including between the salt and the first value.',
+        change: { set: 'separator', to: '' },
+    },
+    {
+        id: 'trailing-separator',
+        label: 'Trailing separator left on the end of the string',
+        explanation: 'The loop appended `value&` each iteration and the final `&` was never removed.',
+        fix: 'Strip the trailing & before hashing, or join the values instead of appending in a loop.',
+        change: { set: 'trailingSeparator', to: true },
+    },
+    {
+        id: 'plain-sha256',
+        label: 'Plain SHA-256 used instead of HMAC-SHA256',
+        explanation: 'The string was digested directly rather than keyed with the Integrity Salt.',
+        fix: 'Use HMAC-SHA256 with the Integrity Salt as the secret key, e.g. PHP `hash_hmac("sha256", $string, $salt)`.',
+        change: { set: 'primitive', to: 'digest' },
+    },
+    {
+        id: 'whitespace-trimmed',
+        label: 'Values trimmed before hashing',
+        explanation: 'A value carries leading or trailing whitespace in the request but was trimmed before hashing (or vice versa).',
+        fix: 'Hash exactly the value you transmit. Trim your inputs before you build the payload, not afterwards.',
+        change: { set: 'valueTransform', to: 'trimmed' },
+    },
+];
+const JAZZCASH_ADVICE = [
+    {
+        id: 'wrong-salt',
+        label: 'The Integrity Salt does not match the account',
+        explanation: 'None of the common construction errors reproduce your hash, which most often means the salt itself is wrong — for example a sandbox salt used against production credentials, or a value copied with a stray character.',
+        fix: 'Re-copy the Integrity Salt from Integration > Credentials in the portal for the environment you are calling, and confirm it belongs to the same Merchant ID you are sending.',
+    },
+    {
+        id: 'value-differs-from-transmitted',
+        label: 'A hashed value differs from the transmitted value',
+        explanation: 'The hash was computed over a different payload than the one sent — commonly because the amount was converted, a timestamp was regenerated, or a field was modified after hashing.',
+        fix: 'Compute the hash as the last step, from the exact map you are about to transmit, and never mutate the payload afterwards.',
+    },
+    {
+        id: 'jazzcash-encoding-mismatch',
+        label: 'Character encoding differs',
+        explanation: 'A non-ASCII character in a description or bill reference was encoded differently when hashed and when sent.',
+        fix: 'Restrict pp_BillReference to alphanumerics as documented, and keep pp_Description ASCII where possible.',
+    },
+];
+export const JAZZCASH_SCHEME = {
+    id: 'jazzcash',
+    label: 'JazzCash pp_SecureHash (HMAC-SHA256 over sorted values)',
+    secret: JAZZCASH_SECRET,
+    narrative: JAZZCASH_NARRATIVE,
+    plan: jazzCashPlan,
+    // Rendered from the resolved plan and this scheme's own name for its secret,
+    // so a flow that narrows the prefixes or declares base64 is described as it is
+    // configured. The hand-written sentence this replaces was the JazzCash one for
+    // every flow, including flows that do not sign this way at all.
+    describePlan: (plan) => describeConstruction(plan, JAZZCASH_SECRET.label),
+    variants: defineVariants(jazzCashPlan, JAZZCASH_VARIANT_DEFINITIONS),
+    advice: JAZZCASH_ADVICE,
+};
+//# sourceMappingURL=jazzcash.js.map

package/dist/domain/signature/jazzcash.js.map

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

package/dist/domain/signature/registry.d.ts

@@ -0,0 +1,69 @@
+import type { RawParameters } from '../types.js';
+import { type JazzCashHashOptions } from './jazzcash.js';
+import { type SchemeProvenance, type SignatureBreakdown, type SignatureDiagnosis, type SignatureScheme, type SignatureVerification } from './scheme.js';
+/**
+ * Every signature scheme the server knows, and the one place a payload is
+ * matched to one.
+ *
+ * The options object carries the scheme with the settings it belongs to, so
+ * choosing a construction and configuring it are a single decision. The
+ * alternative — a scheme name in one argument and a settings bag in another —
+ * makes it possible to sign a payload with a construction nobody chose, or to
+ * diagnose it with another construction's forensic table, which is the failure
+ * mode this module exists to remove. One scheme is registered today; the
+ * indirection is what keeps that true if a second is ever added.
+ */
+/** Configuration for one signature scheme, tagged with the scheme it selects. */
+export type SignatureOptions = JazzCashHashOptions;
+/** A construction described for a merchant to implement. */
+export interface SignatureDescription {
+    /** How the string that is digested is built, and how it is digested. */
+    readonly construction: string;
+    /** The digest encoding and the comparison rule. */
+    readonly encoding: string;
+}
+/**
+ * Every registered scheme, and the table {@link withScheme} dispatches through.
+ *
+ * What keeps a scheme from being run with another scheme's settings is not this
+ * table: it is `SignatureOptions`, which carries the scheme name inside the
+ * settings object, so choosing a construction and configuring it are a single
+ * decision. Erasing the settings type to `never` here read as though the table
+ * enforced that, and a table credited with a guarantee it does not provide is
+ * one nobody dares give honest types to — which is how it ended up with no
+ * production consumer at all, describing a registry the signing path did not
+ * use.
+ *
+ * `satisfies` rather than an annotation for that reason: every member is pinned
+ * as a scheme, and each keeps the settings type it is actually executed with, so
+ * the branches below name a scheme and its own settings resolver together.
+ * `tests/domain/signature.test.ts` walks `SIGNATURE_SCHEME_IDS` through the
+ * table, so a scheme this file can reach but has not registered fails there.
+ */
+export declare const SIGNATURE_SCHEMES: {
+    readonly jazzcash: SignatureScheme<import("./jazzcash.js").JazzCashSignatureSettings>;
+};
+/** Build the signed string and the reasoning behind it. */
+export declare function buildSignatureFor(parameters: RawParameters, secret: string, options?: SignatureOptions): SignatureBreakdown;
+/** Compute the signature for a payload. */
+export declare function computeSignatureFor(parameters: RawParameters, secret: string, options?: SignatureOptions): string;
+/** Verify a supplied signature against a freshly computed one. */
+export declare function verifySignatureFor(parameters: RawParameters, secret: string, providedSignature: string, options?: SignatureOptions): SignatureVerification;
+/**
+ * Explain a mismatch using the selected scheme's forensics, and no other's.
+ *
+ * `provenance` is required rather than defaulted, because the safe value is the
+ * one that reports less: a call site that forgot it would accuse a merchant of a
+ * construction error demonstrated under a construction nobody said they used.
+ */
+export declare function diagnoseSignatureFor(parameters: RawParameters, secret: string, providedSignature: string, options: SignatureOptions | undefined, provenance: SchemeProvenance): SignatureDiagnosis;
+/**
+ * How a payload signed under these options is built, in two sentences.
+ *
+ * Both are rendered from the RESOLVED plan rather than written at the call site.
+ * A paragraph written at the call site describes the construction its author had
+ * in mind rather than the one the engine ran, and a merchant implements the
+ * paragraph.
+ */
+export declare function describeSignatureFor(options?: SignatureOptions): SignatureDescription;
+//# sourceMappingURL=registry.d.ts.map

package/dist/domain/signature/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../../src/domain/signature/registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD,OAAO,EAAqC,KAAK,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAC5F,OAAO,EAML,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,KAAK,eAAe,EAEpB,KAAK,qBAAqB,EAC3B,MAAM,aAAa,CAAC;AAErB;;;;;;;;;;;GAWG;AAEH,iFAAiF;AACjF,MAAM,MAAM,gBAAgB,GAAG,mBAAmB,CAAC;AAEnD,4DAA4D;AAC5D,MAAM,WAAW,oBAAoB;IACnC,wEAAwE;IACxE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,mDAAmD;IACnD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,iBAAiB;;CAEkD,CAAC;AAsCjF,2DAA2D;AAC3D,wBAAgB,iBAAiB,CAC/B,UAAU,EAAE,aAAa,EACzB,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,gBAAgB,GACzB,kBAAkB,CAIpB;AAED,2CAA2C;AAC3C,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,MAAM,CAIjH;AAED,kEAAkE;AAClE,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,aAAa,EACzB,MAAM,EAAE,MAAM,EACd,iBAAiB,EAAE,MAAM,EACzB,OAAO,CAAC,EAAE,gBAAgB,GACzB,qBAAqB,CAIvB;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,UAAU,EAAE,aAAa,EACzB,MAAM,EAAE,MAAM,EACd,iBAAiB,EAAE,MAAM,EACzB,OAAO,EAAE,gBAAgB,GAAG,SAAS,EACrC,UAAU,EAAE,gBAAgB,GAC3B,kBAAkB,CAIpB;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,CAAC,EAAE,gBAAgB,GAAG,oBAAoB,CAOrF"}

package/dist/domain/signature/registry.js

@@ -0,0 +1,92 @@
+import { JAZZCASH_SCHEME, jazzCashSettings } from './jazzcash.js';
+import { buildSignature, computeSignature, describeEncoding, diagnoseSignature, verifySignature, } from './scheme.js';
+/**
+ * Every registered scheme, and the table {@link withScheme} dispatches through.
+ *
+ * What keeps a scheme from being run with another scheme's settings is not this
+ * table: it is `SignatureOptions`, which carries the scheme name inside the
+ * settings object, so choosing a construction and configuring it are a single
+ * decision. Erasing the settings type to `never` here read as though the table
+ * enforced that, and a table credited with a guarantee it does not provide is
+ * one nobody dares give honest types to — which is how it ended up with no
+ * production consumer at all, describing a registry the signing path did not
+ * use.
+ *
+ * `satisfies` rather than an annotation for that reason: every member is pinned
+ * as a scheme, and each keeps the settings type it is actually executed with, so
+ * the branches below name a scheme and its own settings resolver together.
+ * `tests/domain/signature.test.ts` walks `SIGNATURE_SCHEME_IDS` through the
+ * table, so a scheme this file can reach but has not registered fails there.
+ */
+export const SIGNATURE_SCHEMES = {
+    jazzcash: JAZZCASH_SCHEME,
+};
+function withScheme(options, visitor) {
+    // Absent options mean JazzCash, the only construction the server ships. A
+    // second scheme must be named, never inferred from a missing field.
+    if (options === undefined) {
+        return visitor.run(SIGNATURE_SCHEMES.jazzcash, jazzCashSettings(undefined));
+    }
+    switch (options.scheme) {
+        case undefined:
+        case 'jazzcash':
+            return visitor.run(SIGNATURE_SCHEMES.jazzcash, jazzCashSettings(options));
+    }
+    // A scheme added to `SignatureOptions` and not to the switch fails on this
+    // line, naming itself. Without it the same omission surfaces as "lacks ending
+    // return statement" against the whole function, which invites a `default:`
+    // clause — and a default here means the new scheme's payloads are silently
+    // signed and diagnosed as JazzCash ones, which is exactly what this module
+    // exists to prevent.
+    /* c8 ignore start -- unreachable: the switch above is exhaustive, and the assignment below is what proves it */
+    const _exhaustive = options.scheme;
+    return _exhaustive;
+    /* c8 ignore stop */
+}
+/** Build the signed string and the reasoning behind it. */
+export function buildSignatureFor(parameters, secret, options) {
+    return withScheme(options, {
+        run: (scheme, settings) => buildSignature(scheme, parameters, secret, settings),
+    });
+}
+/** Compute the signature for a payload. */
+export function computeSignatureFor(parameters, secret, options) {
+    return withScheme(options, {
+        run: (scheme, settings) => computeSignature(scheme, parameters, secret, settings),
+    });
+}
+/** Verify a supplied signature against a freshly computed one. */
+export function verifySignatureFor(parameters, secret, providedSignature, options) {
+    return withScheme(options, {
+        run: (scheme, settings) => verifySignature(scheme, parameters, secret, providedSignature, settings),
+    });
+}
+/**
+ * Explain a mismatch using the selected scheme's forensics, and no other's.
+ *
+ * `provenance` is required rather than defaulted, because the safe value is the
+ * one that reports less: a call site that forgot it would accuse a merchant of a
+ * construction error demonstrated under a construction nobody said they used.
+ */
+export function diagnoseSignatureFor(parameters, secret, providedSignature, options, provenance) {
+    return withScheme(options, {
+        run: (scheme, settings) => diagnoseSignature(scheme, parameters, secret, providedSignature, settings, provenance),
+    });
+}
+/**
+ * How a payload signed under these options is built, in two sentences.
+ *
+ * Both are rendered from the RESOLVED plan rather than written at the call site.
+ * A paragraph written at the call site describes the construction its author had
+ * in mind rather than the one the engine ran, and a merchant implements the
+ * paragraph.
+ */
+export function describeSignatureFor(options) {
+    return withScheme(options, {
+        run: (scheme, settings) => {
+            const plan = scheme.plan(settings);
+            return { construction: scheme.describePlan(plan), encoding: describeEncoding(plan) };
+        },
+    });
+}
+//# sourceMappingURL=registry.js.map

package/dist/domain/signature/registry.js.map

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