@atbas/m-mcp 0.1.0

package/dist/domain/signature/scheme.js

@@ -0,0 +1,398 @@
+import { createHash, createHmac, timingSafeEqual } from 'node:crypto';
+import { SignatureError } from '../../errors.js';
+import { compareParameterNames, normaliseParameters } from '../types.js';
+/**
+ * The vocabulary a request signature is described in, and the engine that
+ * executes one.
+ *
+ * No two gateways sign the same way. JazzCash sorts the payload by field name,
+ * joins the non-empty values with `&`, prepends the Integrity Salt and HMACs
+ * the result.
+ *
+ * That is expressed here as a `SignaturePlan`: a recipe explicit enough that
+ * adding a gateway is a new plan rather than a new branch inside this file. The
+ * alternative — a second engine, or a second set of `if` statements — produces
+ * the failure this module exists to prevent. A forensic table written for one
+ * construction, replayed against a payload signed under another, reports that
+ * payload's CORRECT construction as a proven defect: several entries in the
+ * JazzCash table (a plain digest, the salt at the far end, empty components
+ * kept) are how other gateways legitimately sign.
+ */
+/** Every signature construction the server can produce and diagnose. */
+export const SIGNATURE_SCHEME_IDS = ['jazzcash'];
+/**
+ * Apply one delta to a plan.
+ *
+ * Exhaustive over `PlanDelta`, so a member added to the union fails to compile
+ * here rather than being silently dropped — a dropped delta is a variant that
+ * computes the correct signature under a wrong-construction label.
+ */
+function applyDelta(plan, delta) {
+    switch (delta.set) {
+        case 'ordering':
+            return { ...plan, ordering: delta.to };
+        case 'pairing':
+            return { ...plan, pairing: delta.to };
+        case 'valueTransform':
+            return { ...plan, valueTransform: delta.to };
+        case 'omitEmptyValues':
+            return { ...plan, omitEmptyValues: delta.to };
+        case 'separator':
+            return { ...plan, separator: delta.to };
+        case 'trailingSeparator':
+            return { ...plan, trailingSeparator: delta.to };
+        case 'secretPlacement':
+            return { ...plan, secretPlacement: delta.to };
+        case 'primitive':
+            return { ...plan, primitive: delta.to };
+        case 'digest':
+            return { ...plan, digest: delta.to };
+        case 'encoding':
+            return { ...plan, encoding: delta.to };
+        case 'excludeFields':
+            return { ...plan, selection: { ...plan.selection, excludeFields: delta.to } };
+        case 'includeFieldPrefixes':
+            return { ...plan, selection: { ...plan.selection, includeFieldPrefixes: delta.to } };
+    }
+}
+/**
+ * Read a value for a key that was enumerated from the same record.
+ *
+ * `noUncheckedIndexedAccess` requires a fallback that no current caller can
+ * take: every name reaching here comes from `Object.keys(parameters)`. It is
+ * kept rather than asserted away because a selection rule that names its own
+ * components — rather than filtering the payload's — would take it for a
+ * component the payload never carried, and an assertion would crash there
+ * instead of signing an empty slot.
+ */
+function valueOf(parameters, name) {
+    /* c8 ignore next -- unreachable while every selection filters Object.keys(parameters) */
+    return parameters[name] ?? '';
+}
+function isEmptyValue(value, treatWhitespaceOnlyAsEmpty) {
+    return treatWhitespaceOnlyAsEmpty ? value.trim() === '' : value === '';
+}
+function matchesAnyPrefix(name, prefixes) {
+    // An empty prefix list means "no prefix filtering".
+    return prefixes.length === 0 || prefixes.some((prefix) => name.startsWith(prefix));
+}
+function orderNames(names, ordering) {
+    switch (ordering) {
+        case 'name-ascending':
+            return [...names].sort(compareParameterNames);
+        case 'name-descending':
+            return [...names].sort(compareParameterNames).reverse();
+        case 'name-ascending-folded':
+            return [...names].sort((left, right) => compareParameterNames(left.toLowerCase(), right.toLowerCase()));
+        case 'as-listed':
+            return names;
+    }
+}
+function readValue(parameters, name, plan) {
+    return plan.valueTransform === 'trimmed' ? valueOf(parameters, name).trim() : valueOf(parameters, name);
+}
+/**
+ * Why this field cannot contribute, or `undefined` when it can.
+ *
+ * One function for every selection kind, so that a rule added for one is visibly
+ * either shared or conditional rather than duplicated into a second loop where
+ * it can quietly diverge.
+ */
+function exclusionReasonFor(name, value, plan) {
+    const selection = plan.selection;
+    if (selection.excludeFields.includes(name)) {
+        return 'excluded-field';
+    }
+    if (!matchesAnyPrefix(name, selection.includeFieldPrefixes)) {
+        return 'prefix-not-matched';
+    }
+    if (plan.omitEmptyValues && isEmptyValue(value, plan.treatWhitespaceOnlyAsEmpty)) {
+        return 'empty';
+    }
+    return undefined;
+}
+function selectFields(parameters, plan) {
+    // A prefix scheme reads the payload and filters it, so the candidates are
+    // whatever was transmitted. A selection rule that named its own components
+    // would supply them here instead, and would have to keep a slot for one the
+    // payload never carried — dropping it shifts every later component one place.
+    const candidates = Object.keys(parameters);
+    const components = [];
+    const excludedFields = [];
+    for (const name of orderNames(candidates, plan.ordering)) {
+        const value = readValue(parameters, name, plan);
+        const reason = exclusionReasonFor(name, value, plan);
+        if (reason === undefined) {
+            components.push({ name, value });
+        }
+        else {
+            excludedFields.push({ name, reason });
+        }
+    }
+    return { components, excludedFields };
+}
+function joinComponents(components, plan) {
+    const parts = plan.pairing === 'name-and-value'
+        ? components.map((component) => `${component.name}=${component.value}`)
+        : components.map((component) => component.value);
+    return parts.join(plan.separator);
+}
+function placeSecret(plan, secret, joined, hasComponents) {
+    switch (plan.secretPlacement) {
+        case 'prepend':
+            return hasComponents ? `${secret}${plan.separator}${joined}` : secret;
+        case 'append':
+            return hasComponents ? `${joined}${plan.separator}${secret}` : secret;
+        case 'none':
+            return joined;
+    }
+}
+function assembleMessage(components, secret, plan) {
+    const message = placeSecret(plan, secret, joinComponents(components, plan), components.length > 0);
+    return plan.trailingSeparator ? `${message}${plan.separator}` : message;
+}
+function encodeDigest(message, secret, plan) {
+    const digest = plan.primitive === 'hmac'
+        ? createHmac(plan.digest, secret).update(message, 'utf8').digest()
+        : createHash(plan.digest).update(message, 'utf8').digest();
+    return plan.encoding === 'base64' ? digest.toString('base64') : digest.toString('hex');
+}
+/**
+ * Refuse a secret that carries no characters at all.
+ *
+ * A whitespace-only secret is as unusable as an empty one and far harder to
+ * spot: it survives a `!== ''` check, and every signature computed with it is
+ * then silently wrong, reaching the merchant only as an opaque gateway
+ * rejection. A secret that merely starts with whitespace is left exactly as
+ * supplied — it is signed material, so trimming it would produce the same wrong
+ * digest this guards against.
+ */
+function assertSecret(secret, description) {
+    if (secret.trim() !== '') {
+        return;
+    }
+    const state = secret === '' ? 'is empty' : 'contains only whitespace';
+    throw new SignatureError(`The ${description.label} ${state}. ${description.role}`, {
+        docRefs: description.docRefs,
+    });
+}
+function normaliseForComparison(signature, comparison) {
+    const trimmed = signature.trim();
+    return comparison === 'case-insensitive' ? trimmed.toLowerCase() : trimmed;
+}
+/** Constant-time signature comparison under a scheme's own case rule. */
+export function signaturesMatch(left, right, comparison) {
+    const a = Buffer.from(normaliseForComparison(left, comparison), 'utf8');
+    const b = Buffer.from(normaliseForComparison(right, comparison), 'utf8');
+    if (a.length !== b.length) {
+        return false;
+    }
+    return timingSafeEqual(a, b);
+}
+function quoteAll(names, conjunction) {
+    return names.map((name) => `\`${name}\``).join(conjunction);
+}
+function describeSelection(selection) {
+    // An empty prefix list means no filtering, and the sentence has to say so
+    // rather than trail off after "prefixed" — which is what a merchant was
+    // handed for every flow whose prefixes are empty by construction.
+    return selection.includeFieldPrefixes.length === 0
+        ? 'every field'
+        : `the fields prefixed ${quoteAll(selection.includeFieldPrefixes, ' or ')}`;
+}
+function describeOrdering(ordering) {
+    switch (ordering) {
+        case 'name-ascending':
+            return 'sorted by name (ASCII ascending)';
+        case 'name-descending':
+            return 'sorted by name (ASCII descending)';
+        case 'name-ascending-folded':
+            return 'sorted by lower-cased name';
+        case 'as-listed':
+            return 'in the order listed';
+    }
+}
+function describeSecretPlacement(placement, secretLabel) {
+    switch (placement) {
+        case 'prepend':
+            return `prefixed by the ${secretLabel}`;
+        case 'append':
+            return `followed by the ${secretLabel}`;
+        case 'none':
+            return `with the ${secretLabel} nowhere in the signed string`;
+    }
+}
+/**
+ * One sentence describing exactly how a plan builds the string it digests.
+ *
+ * Derived from the plan rather than written out per scheme, because a sentence
+ * written by hand describes the construction its author had in mind while the
+ * engine executes the one the flow configured — and a merchant implements the
+ * sentence, not the code. The two drift silently: nothing fails when a flow is
+ * described by a paragraph belonging to a different construction.
+ */
+export function describeConstruction(plan, secretLabel) {
+    // Spelled the way each is conventionally written, and the way this repository
+    // writes them elsewhere: `HMAC-SHA256`, but `SHA-512`.
+    const bits = plan.digest === 'sha256' ? '256' : '512';
+    const algorithm = plan.primitive === 'hmac' ? `HMAC-SHA${bits}` : `SHA-${bits}`;
+    const emptyRule = plan.omitEmptyValues ? 'non-empty ' : '';
+    const pairing = plan.pairing === 'name-and-value' ? 'name=value pairs' : 'values';
+    const transform = plan.valueTransform === 'trimmed' ? 'trimmed' : 'exactly as transmitted';
+    const joined = plan.separator === '' ? 'concatenated with no separator' : `joined with "${plan.separator}"`;
+    const trailing = plan.trailingSeparator ? ' and a trailing separator' : '';
+    // Stated only where it applies. It is not a default anywhere, no flow can
+    // declare it, and a merchant told their whitespace-only values are dropped
+    // when they are not would go looking for a difference that is not there.
+    const blanks = plan.omitEmptyValues && plan.treatWhitespaceOnlyAsEmpty ? ' (a whitespace-only value counts as empty)' : '';
+    // The secret appears twice in a keyed construction, which is the single most
+    // common JazzCash misreading: prepended AND used as the key, not either one.
+    const keying = plan.primitive === 'hmac' ? `, and keyed with the ${secretLabel}` : '';
+    return [
+        `${algorithm} over the ${emptyRule}${pairing} of ${describeSelection(plan.selection)}${blanks}`,
+        describeOrdering(plan.ordering),
+        `taken ${transform} and ${joined}${trailing}`,
+        `${describeSecretPlacement(plan.secretPlacement, secretLabel)}${keying}.`,
+    ].join(', ');
+}
+/**
+ * One sentence naming the digest encoding and the comparison rule.
+ *
+ * Read from the plan for the same reason as the construction: a flow declaring
+ * base64 and case-sensitive comparison was told its output was lowercase hex
+ * compared case-insensitively, which is the advice that makes a correct
+ * signature look broken.
+ */
+export function describeEncoding(plan) {
+    const output = plan.encoding === 'base64' ? 'base64' : 'lowercase hex';
+    const comparison = plan.comparison === 'case-insensitive' ? 'case-insensitive' : 'case-sensitive';
+    return `Output is ${output}; comparison is ${comparison}.`;
+}
+/**
+ * Execute a plan, returning the reasoning as well as the signed string.
+ *
+ * Returning the breakdown rather than only the digest is the point: a merchant
+ * debugging a rejected signature needs to see which fields were used and in what
+ * order, which is precisely what no error message from a gateway tells them.
+ */
+function buildFromPlan(parameters, secret, plan) {
+    const { components, excludedFields } = selectFields(parameters, plan);
+    return {
+        includedFields: components.map((component) => component.name),
+        excludedFields,
+        hashString: assembleMessage(components, secret, plan),
+        values: components.map((component) => component.value),
+    };
+}
+/** Execute a plan and return only the encoded signature. */
+function signFromPlan(parameters, secret, plan) {
+    return encodeDigest(buildFromPlan(parameters, secret, plan).hashString, secret, plan);
+}
+/**
+ * Bind a table of plan deltas to a scheme.
+ *
+ * Each variant re-resolves the scheme's plan from the merchant's own settings
+ * before applying its delta, so a flow that narrows the field selection is
+ * diagnosed against ITS construction rather than against the scheme default.
+ */
+export function defineVariants(plan, definitions) {
+    return definitions.map((definition) => ({
+        id: definition.id,
+        label: definition.label,
+        explanation: definition.explanation,
+        fix: definition.fix,
+        compute: (parameters, secret, settings) => signFromPlan(parameters, secret, applyDelta(plan(settings), definition.change)),
+    }));
+}
+/** Build the signed string for a payload under one scheme. */
+export function buildSignature(scheme, parameters, secret, settings) {
+    assertSecret(secret, scheme.secret);
+    return buildFromPlan(normaliseParameters(parameters), secret, scheme.plan(settings));
+}
+/** Compute the signature for a payload under one scheme. */
+export function computeSignature(scheme, parameters, secret, settings) {
+    assertSecret(secret, scheme.secret);
+    return signFromPlan(normaliseParameters(parameters), secret, scheme.plan(settings));
+}
+/** Verify a supplied signature against a freshly computed one. */
+export function verifySignature(scheme, parameters, secret, providedSignature, settings) {
+    assertSecret(secret, scheme.secret);
+    const plan = scheme.plan(settings);
+    const breakdown = buildFromPlan(normaliseParameters(parameters), secret, plan);
+    const expectedHash = encodeDigest(breakdown.hashString, secret, plan);
+    return {
+        matches: signaturesMatch(expectedHash, providedSignature, plan.comparison),
+        expectedHash,
+        providedHash: normaliseForComparison(providedSignature, plan.comparison),
+        breakdown,
+    };
+}
+/**
+ * Summary for a mismatch judged under a construction nobody declared.
+ *
+ * Says what was assumed and offers no proven cause, rather than reusing the
+ * `unexplained` narrative — which would claim no known construction error
+ * reproduces the signature while one may well have done.
+ */
+function assumedSchemeSummary(label) {
+    return `The signature does not match. No flow named the construction, so it was assumed to be ${label}, and nothing is offered as a proven cause: a construction error identified under an assumed construction is just as likely to be another provider's correct one. Name the flow to diagnose the payload against the construction that flow declares.`;
+}
+/**
+ * Explain why a signature does not match, using one scheme's forensics only.
+ *
+ * Every variant of the scheme is executed against the merchant's own parameters.
+ * One that reproduces the signature they actually sent is reported as
+ * `confirmed`: that is not a guess, it is a demonstration of what their code
+ * did — provided the construction being varied is the one the payload was signed
+ * under. `provenance` is what says whether it is; see `SchemeProvenance`. Under
+ * an assumed construction no variant runs at all, and the scheme's ranked advice
+ * is offered as `possible` instead.
+ *
+ * A variant can only ever be its own scheme's plan with one field changed, which
+ * is what stops the table offering another provider's correct construction as a
+ * defect; see `PlanDelta`.
+ */
+export function diagnoseSignature(scheme, parameters, secret, providedSignature, settings, provenance) {
+    const verification = verifySignature(scheme, parameters, secret, providedSignature, settings);
+    if (verification.matches) {
+        return {
+            matches: true,
+            expectedHash: verification.expectedHash,
+            providedHash: verification.providedHash,
+            breakdown: verification.breakdown,
+            hypotheses: [],
+            summary: scheme.narrative.matched,
+        };
+    }
+    const plan = scheme.plan(settings);
+    const normalised = normaliseParameters(parameters);
+    const confirmed = [];
+    if (provenance === 'declared') {
+        for (const variant of scheme.variants) {
+            if (signaturesMatch(variant.compute(normalised, secret, settings), providedSignature, plan.comparison)) {
+                confirmed.push({
+                    id: variant.id,
+                    label: variant.label,
+                    explanation: variant.explanation,
+                    fix: variant.fix,
+                    confidence: 'confirmed',
+                });
+            }
+        }
+    }
+    const hypotheses = confirmed.length > 0 ? confirmed : scheme.advice.map((advice) => ({ ...advice, confidence: 'possible' }));
+    const summary = confirmed.length > 0
+        ? `${scheme.narrative.reproducedPrefix}: ${confirmed.map((entry) => entry.label).join('; ')}.`
+        : provenance === 'declared'
+            ? scheme.narrative.unexplained
+            : assumedSchemeSummary(scheme.label);
+    return {
+        matches: false,
+        expectedHash: verification.expectedHash,
+        providedHash: verification.providedHash,
+        breakdown: verification.breakdown,
+        hypotheses,
+        summary,
+    };
+}
+//# sourceMappingURL=scheme.js.map

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

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

package/dist/domain/txn-ref.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Transaction reference, bill reference and request identifier rules.
+ *
+ * From the MWallet guides:
+ *  - `pp_TxnRefNo` must be unique for every transaction. The recommended format
+ *    is the first three letters of the merchant's domain followed by the
+ *    transaction date/time, e.g. `Goo20230208115409`. The v1.1 sample annotates
+ *    the field as `[20AN]`, i.e. 20 alphanumeric characters.
+ *  - `pp_BillReference` is mandatory, may repeat across transactions, and must
+ *    contain only `A-Z`, `a-z` and `0-9`. Spaces and special characters are not
+ *    allowed.
+ *  - `pp_RequestID` (wallet linking, token inquiry, token delete) must be unique
+ *    for every attempt.
+ */
+export declare const MAX_TXN_REF_LENGTH = 20;
+export declare const MAX_TXN_REF_PREFIX_LENGTH = 3;
+export interface ReferenceCheck {
+    readonly valid: boolean;
+    readonly issues: readonly string[];
+}
+/**
+ * Validate `pp_TxnRefNo` against the documented rules.
+ *
+ * `maxLength` defaults to the documented 20 for callers with no flow to hand.
+ * The validation rule passes the flow's own declared limit instead, so a
+ * correction from JazzCash stays a data change rather than a code change.
+ */
+export declare function validateTxnRefNo(value: string, maxLength?: number): ReferenceCheck;
+/** Validate `pp_BillReference` against the documented rules. */
+export declare function validateBillReference(value: string): ReferenceCheck;
+/** Validate `pp_RequestID` used by the wallet linking and token APIs. */
+export declare function validateRequestId(value: string, maxLength?: number): ReferenceCheck;
+export interface ReferenceOptions {
+    /**
+     * Up to three alphanumeric characters. The guides recommend the first three
+     * letters of the merchant's domain, e.g. `Goo` for `google.com`.
+     */
+    readonly prefix?: string;
+    readonly now?: Date;
+    /**
+     * Append random alphanumeric characters to disambiguate the reference.
+     *
+     * On by default: a second-resolution stamp collides whenever two orders are
+     * placed in the same second, which the gateway rejects as a duplicate
+     * reference. The suffix takes whatever room the prefix leaves inside the
+     * 20-character limit, so a shorter prefix buys more entropy.
+     *
+     * Turning it off yields exactly the documented `prefix + YYYYMMDDHHMMSS`
+     * shape, and with it the certainty that two references generated in the same
+     * second are identical. Only use it where the caller supplies uniqueness by
+     * some other means.
+     */
+    readonly includeRandomSuffix?: boolean;
+}
+/**
+ * Generate a `pp_TxnRefNo`.
+ *
+ * Default shape is `T` + `YYYYMMDDHHMMSS` + five random alphanumeric characters,
+ * filling the 20-character limit. The documented three-letter merchant prefix
+ * leaves three random characters rather than five.
+ *
+ * Uniqueness is probabilistic, not guaranteed. The narrowest case is three
+ * random characters, 62³ ≈ 238,000 combinations within one second, so a given
+ * pair of references taken in that second collides with probability about one in
+ * 240,000 and a collision becomes likely only past roughly 600 references in the
+ * same second. A wall clock alone cannot do better: two builds in one
+ * millisecond, in one process or in two containers, produce the same stamp.
+ * Persist the reference you send, and treat the gateway's duplicate-reference
+ * rejection as a signal to regenerate rather than as a failed payment.
+ */
+export declare function generateTxnRefNo(options?: ReferenceOptions): string;
+/** Generate a `pp_BillReference`. May repeat, but a unique value aids reconciliation. */
+export declare function generateBillReference(options?: ReferenceOptions): string;
+/** Generate a `pp_RequestID` for the wallet linking and token APIs. */
+export declare function generateRequestId(options?: ReferenceOptions): string;
+//# sourceMappingURL=txn-ref.d.ts.map

package/dist/domain/txn-ref.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"txn-ref.d.ts","sourceRoot":"","sources":["../../src/domain/txn-ref.ts"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;GAaG;AAEH,eAAO,MAAM,kBAAkB,KAAK,CAAC;AAErC,eAAO,MAAM,yBAAyB,IAAI,CAAC;AAa3C,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;CACpC;AAsBD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,GAAE,MAA2B,GAAG,cAAc,CAEtG;AAED,gEAAgE;AAChE,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,cAAc,CAEnE;AAED,yEAAyE;AACzE,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,GAAE,MAA2B,GAAG,cAAc,CAEvG;AAED,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,GAAG,CAAC,EAAE,IAAI,CAAC;IACpB;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,OAAO,CAAC;CACxC;AAkDD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,GAAE,gBAAqB,GAAG,MAAM,CAEvE;AAED,yFAAyF;AACzF,wBAAgB,qBAAqB,CAAC,OAAO,GAAE,gBAAqB,GAAG,MAAM,CAE5E;AAED,uEAAuE;AACvE,wBAAgB,iBAAiB,CAAC,OAAO,GAAE,gBAAqB,GAAG,MAAM,CAExE"}

package/dist/domain/txn-ref.js

@@ -0,0 +1,126 @@
+import { randomInt } from 'node:crypto';
+import { JazzCashValidationError } from '../errors.js';
+import { formatTxnDateTime } from './datetime.js';
+/**
+ * Transaction reference, bill reference and request identifier rules.
+ *
+ * From the MWallet guides:
+ *  - `pp_TxnRefNo` must be unique for every transaction. The recommended format
+ *    is the first three letters of the merchant's domain followed by the
+ *    transaction date/time, e.g. `Goo20230208115409`. The v1.1 sample annotates
+ *    the field as `[20AN]`, i.e. 20 alphanumeric characters.
+ *  - `pp_BillReference` is mandatory, may repeat across transactions, and must
+ *    contain only `A-Z`, `a-z` and `0-9`. Spaces and special characters are not
+ *    allowed.
+ *  - `pp_RequestID` (wallet linking, token inquiry, token delete) must be unique
+ *    for every attempt.
+ */
+export const MAX_TXN_REF_LENGTH = 20;
+export const MAX_TXN_REF_PREFIX_LENGTH = 3;
+const ALPHANUMERIC_PATTERN = /^[A-Za-z0-9]+$/;
+/**
+ * The alphabet a generated reference's random suffix is drawn from.
+ *
+ * Restricted to `A-Z`, `a-z` and `0-9` because that is the whole character set
+ * the guides permit for a reference. 62 symbols per character is the most
+ * entropy available inside that rule.
+ */
+const SUFFIX_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
+function checkAlphanumeric(fieldName, value, maxLength) {
+    const issues = [];
+    if (value === '') {
+        issues.push(`${fieldName} is mandatory and must not be empty.`);
+        return { valid: false, issues };
+    }
+    if (!ALPHANUMERIC_PATTERN.test(value)) {
+        const offending = [...new Set([...value].filter((character) => !ALPHANUMERIC_PATTERN.test(character)))];
+        issues.push(`${fieldName} must contain only letters and digits. Remove: ${offending.map((character) => (character === ' ' ? '(space)' : character)).join(' ')}`);
+    }
+    if (maxLength !== undefined && value.length > maxLength) {
+        issues.push(`${fieldName} is ${String(value.length)} characters; the documented maximum is ${String(maxLength)}.`);
+    }
+    return { valid: issues.length === 0, issues };
+}
+/**
+ * Validate `pp_TxnRefNo` against the documented rules.
+ *
+ * `maxLength` defaults to the documented 20 for callers with no flow to hand.
+ * The validation rule passes the flow's own declared limit instead, so a
+ * correction from JazzCash stays a data change rather than a code change.
+ */
+export function validateTxnRefNo(value, maxLength = MAX_TXN_REF_LENGTH) {
+    return checkAlphanumeric('pp_TxnRefNo', value, maxLength);
+}
+/** Validate `pp_BillReference` against the documented rules. */
+export function validateBillReference(value) {
+    return checkAlphanumeric('pp_BillReference', value, undefined);
+}
+/** Validate `pp_RequestID` used by the wallet linking and token APIs. */
+export function validateRequestId(value, maxLength = MAX_TXN_REF_LENGTH) {
+    return checkAlphanumeric('pp_RequestID', value, maxLength);
+}
+/**
+ * Draw a random alphanumeric suffix.
+ *
+ * `node:crypto` rather than `Math.random`: a reference must be unpredictable to
+ * a third party who sees one of them, and `randomInt` rejection-samples so every
+ * character is uniform over the alphabet rather than biased towards its start.
+ */
+function randomSuffix(length) {
+    let suffix = '';
+    for (let index = 0; index < length; index += 1) {
+        suffix += SUFFIX_ALPHABET.charAt(randomInt(SUFFIX_ALPHABET.length));
+    }
+    return suffix;
+}
+function assertPrefix(prefix) {
+    if (prefix !== '' && !ALPHANUMERIC_PATTERN.test(prefix)) {
+        throw new JazzCashValidationError(`Reference prefix "${prefix}" must contain only letters and digits.`);
+    }
+    if (prefix.length > MAX_TXN_REF_PREFIX_LENGTH) {
+        throw new JazzCashValidationError(`Reference prefix "${prefix}" is longer than ${String(MAX_TXN_REF_PREFIX_LENGTH)} characters. The timestamp and its random suffix need the remaining room inside the ${String(MAX_TXN_REF_LENGTH)}-character limit.`);
+    }
+}
+function buildReference(prefix, options) {
+    assertPrefix(prefix);
+    const now = options.now ?? new Date();
+    const stamp = formatTxnDateTime(now);
+    // assertPrefix caps the prefix at three characters, so the remaining room is
+    // at least three even for the longest permitted prefix.
+    const room = MAX_TXN_REF_LENGTH - prefix.length - stamp.length;
+    const suffix = options.includeRandomSuffix === false ? '' : randomSuffix(room);
+    const reference = `${prefix}${stamp}${suffix}`;
+    /* c8 ignore next 5 -- guarded by assertPrefix; retained as a defence in depth */
+    if (reference.length > MAX_TXN_REF_LENGTH) {
+        throw new JazzCashValidationError(`Generated reference "${reference}" exceeds the ${String(MAX_TXN_REF_LENGTH)}-character limit.`);
+    }
+    return reference;
+}
+/**
+ * Generate a `pp_TxnRefNo`.
+ *
+ * Default shape is `T` + `YYYYMMDDHHMMSS` + five random alphanumeric characters,
+ * filling the 20-character limit. The documented three-letter merchant prefix
+ * leaves three random characters rather than five.
+ *
+ * Uniqueness is probabilistic, not guaranteed. The narrowest case is three
+ * random characters, 62³ ≈ 238,000 combinations within one second, so a given
+ * pair of references taken in that second collides with probability about one in
+ * 240,000 and a collision becomes likely only past roughly 600 references in the
+ * same second. A wall clock alone cannot do better: two builds in one
+ * millisecond, in one process or in two containers, produce the same stamp.
+ * Persist the reference you send, and treat the gateway's duplicate-reference
+ * rejection as a signal to regenerate rather than as a failed payment.
+ */
+export function generateTxnRefNo(options = {}) {
+    return buildReference(options.prefix ?? 'T', options);
+}
+/** Generate a `pp_BillReference`. May repeat, but a unique value aids reconciliation. */
+export function generateBillReference(options = {}) {
+    return buildReference(options.prefix ?? 'B', options);
+}
+/** Generate a `pp_RequestID` for the wallet linking and token APIs. */
+export function generateRequestId(options = {}) {
+    return buildReference(options.prefix ?? 'R', options);
+}
+//# sourceMappingURL=txn-ref.js.map

package/dist/domain/txn-ref.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"txn-ref.js","sourceRoot":"","sources":["../../src/domain/txn-ref.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAExC,OAAO,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAC;AAEvD,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAElD;;;;;;;;;;;;;GAaG;AAEH,MAAM,CAAC,MAAM,kBAAkB,GAAG,EAAE,CAAC;AAErC,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,CAAC;AAE3C,MAAM,oBAAoB,GAAG,gBAAgB,CAAC;AAE9C;;;;;;GAMG;AACH,MAAM,eAAe,GAAG,gEAAgE,CAAC;AAOzF,SAAS,iBAAiB,CAAC,SAAiB,EAAE,KAAa,EAAE,SAA6B;IACxF,MAAM,MAAM,GAAa,EAAE,CAAC;IAE5B,IAAI,KAAK,KAAK,EAAE,EAAE,CAAC;QACjB,MAAM,CAAC,IAAI,CAAC,GAAG,SAAS,sCAAsC,CAAC,CAAC;QAChE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC;IAClC,CAAC;IACD,IAAI,CAAC,oBAAoB,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QACtC,MAAM,SAAS,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,MAAM,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC,oBAAoB,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC;QACxG,MAAM,CAAC,IAAI,CACT,GAAG,SAAS,kDAAkD,SAAS,CAAC,GAAG,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC,SAAS,KAAK,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CACpJ,CAAC;IACJ,CAAC;IACD,IAAI,SAAS,KAAK,SAAS,IAAI,KAAK,CAAC,MAAM,GAAG,SAAS,EAAE,CAAC;QACxD,MAAM,CAAC,IAAI,CAAC,GAAG,SAAS,OAAO,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,0CAA0C,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;IACrH,CAAC;IAED,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;AAChD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAa,EAAE,YAAoB,kBAAkB;IACpF,OAAO,iBAAiB,CAAC,aAAa,EAAE,KAAK,EAAE,SAAS,CAAC,CAAC;AAC5D,CAAC;AAED,gEAAgE;AAChE,MAAM,UAAU,qBAAqB,CAAC,KAAa;IACjD,OAAO,iBAAiB,CAAC,kBAAkB,EAAE,KAAK,EAAE,SAAS,CAAC,CAAC;AACjE,CAAC;AAED,yEAAyE;AACzE,MAAM,UAAU,iBAAiB,CAAC,KAAa,EAAE,YAAoB,kBAAkB;IACrF,OAAO,iBAAiB,CAAC,cAAc,EAAE,KAAK,EAAE,SAAS,CAAC,CAAC;AAC7D,CAAC;AAyBD;;;;;;GAMG;AACH,SAAS,YAAY,CAAC,MAAc;IAClC,IAAI,MAAM,GAAG,EAAE,CAAC;IAChB,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,MAAM,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;QAC/C,MAAM,IAAI,eAAe,CAAC,MAAM,CAAC,SAAS,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC,CAAC;IACtE,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,SAAS,YAAY,CAAC,MAAc;IAClC,IAAI,MAAM,KAAK,EAAE,IAAI,CAAC,oBAAoB,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;QACxD,MAAM,IAAI,uBAAuB,CAAC,qBAAqB,MAAM,yCAAyC,CAAC,CAAC;IAC1G,CAAC;IACD,IAAI,MAAM,CAAC,MAAM,GAAG,yBAAyB,EAAE,CAAC;QAC9C,MAAM,IAAI,uBAAuB,CAC/B,qBAAqB,MAAM,oBAAoB,MAAM,CAAC,yBAAyB,CAAC,uFAAuF,MAAM,CAAC,kBAAkB,CAAC,mBAAmB,CACrN,CAAC;IACJ,CAAC;AACH,CAAC;AAED,SAAS,cAAc,CAAC,MAAc,EAAE,OAAyB;IAC/D,YAAY,CAAC,MAAM,CAAC,CAAC;IAErB,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,IAAI,IAAI,EAAE,CAAC;IACtC,MAAM,KAAK,GAAG,iBAAiB,CAAC,GAAG,CAAC,CAAC;IACrC,6EAA6E;IAC7E,wDAAwD;IACxD,MAAM,IAAI,GAAG,kBAAkB,GAAG,MAAM,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC;IAC/D,MAAM,MAAM,GAAG,OAAO,CAAC,mBAAmB,KAAK,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC;IAE/E,MAAM,SAAS,GAAG,GAAG,MAAM,GAAG,KAAK,GAAG,MAAM,EAAE,CAAC;IAE/C,iFAAiF;IACjF,IAAI,SAAS,CAAC,MAAM,GAAG,kBAAkB,EAAE,CAAC;QAC1C,MAAM,IAAI,uBAAuB,CAC/B,wBAAwB,SAAS,iBAAiB,MAAM,CAAC,kBAAkB,CAAC,mBAAmB,CAChG,CAAC;IACJ,CAAC;IAED,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,gBAAgB,CAAC,UAA4B,EAAE;IAC7D,OAAO,cAAc,CAAC,OAAO,CAAC,MAAM,IAAI,GAAG,EAAE,OAAO,CAAC,CAAC;AACxD,CAAC;AAED,yFAAyF;AACzF,MAAM,UAAU,qBAAqB,CAAC,UAA4B,EAAE;IAClE,OAAO,cAAc,CAAC,OAAO,CAAC,MAAM,IAAI,GAAG,EAAE,OAAO,CAAC,CAAC;AACxD,CAAC;AAED,uEAAuE;AACvE,MAAM,UAAU,iBAAiB,CAAC,UAA4B,EAAE;IAC9D,OAAO,cAAc,CAAC,OAAO,CAAC,MAAM,IAAI,GAAG,EAAE,OAAO,CAAC,CAAC;AACxD,CAAC"}