Subchapter 39.17

Gateway Summary

PLUGIN READ PLANS

Product Video Sources

Secret Value Patterns V1

Source Schema Example

48 more in the appendix

const empty

export function describeGatewaySummary

This file

Number: 39.17
Position: 17 of 92
Type: JavaScript
Size: 14 KB
Lines: 333

Nearby

Source

lib/gateway-summary.mjs

JavaScript333 lines14 KB

1// Payment-gateway configuration, reduced to what discovery legitimately needs.
2//
3// WHAT THIS MODULE IS: a pure reducer. Gateway JSON in, summary out. It makes no request and
4// imports no transport, so there is no arrangement of callers in which it can reach a live
5// site. The transport (`wp-http.js`) imports THIS module, never the reverse -- that direction
6// is the whole design. The alternative, a "sanctioned reader" module that owns both the
7// request and the reduction, needs an escape hatch out of the transport's deny rule, and an
8// escape hatch is the exposure with extra steps.
9//
10// WHY IT EXISTS: `GET /wc/v3/payment_gateways` returns each gateway's entire settings object,
11// API keys and secrets included. Enumerating gateways is the obvious first move for any
12// payments discovery step, so on a site with a real gateway connected the credential arrives
13// through correct-looking work with no bad intent and no code change. Anything a tool returns

gateway-summary.mjs on GitHub

// is in the model's context, the transcript, and potentially the run artifacts, so there is no

// careful-handling mitigation available above this line. The value has to be dropped here.

//

// THE DEFAULT IS VALUE-FREE. A field's NAME and STATE are reported without its value, which is

// what discovery actually needs -- which gateways are registered, which are enabled, whether a

// credential is configured. Only a short reviewed allowlist of display and behaviour fields

// returns a value at all, and even those pass the shared secret-shape guard first, because

// `description` is free text a vendor or an attacker controls. Matching credential-shaped

// field NAMES and passing everything else through was the earlier design and it was the wrong

// trade: a field called `terminal_number` defeats it, and no name list can anticipate what a

// gateway vendor calls its key.

import { REDACTED, isSecretShaped, isUsable, unusableReason } from './secret-value-guard.js';

/** The one route this module's output can describe. Reported so a reader knows what was read. */

export const GATEWAY_COLLECTION_ROUTE = '/wc/v3/payment_gateways';

/** Request-level outcomes. A SEPARATE axis from field state -- see FIELD_STATES. */

export const REQUEST_OUTCOMES = Object.freeze(['ok', 'unauthorized', 'unreachable', 'malformed']);

/**

* Field states, and the whole vocabulary.

*

* present the field exists and holds a non-empty value

* blank the field exists and is empty

* absent the gateway does not define this field

*

* The secret-resolution states `local_present` / `secret_present` / `missing` / `placeholder` describe secret

* RESOLUTION across a local env file and a secret store. That is a different question from

* inspecting a live gateway field, and the two vocabularies must not be merged. What IS

* inherited from that vocabulary is its output contract: tooling emits names and states, and emits a

* value only where a reviewed allowlist says the field is display configuration.

*/

export const FIELD_STATES = Object.freeze(['present', 'blank', 'absent']);

/**

* Fields whose VALUES may be returned, because a mapper genuinely needs them. Display text and

* behavioural configuration -- never credentials.

*

* Adding an entry is a one-line reviewable decision. Failing to predict what a vendor calls its

* credential is not, which is why this is an allowlist of values rather than a denylist of

* names. An unrecognised field costs its value, not discovery: the caller still learns the

* field exists and whether it is set.

*/

export const VALUE_ALLOWLIST = Object.freeze([

'title',

'description',

'enabled',

'order',

'order_status',

'method_title',

'method_description',

'instructions',

'testmode',

'test_mode',

'checkout_label',

]);

/**

* The credential-like name list, kept here as belt and braces rather than as the

* control. If a field is on VALUE_ALLOWLIST and ALSO reads as a credential name, the allowlist

* itself is wrong; the value is dropped and a warning is recorded rather than resolving the

* contradiction silently in either direction.

*/

const CREDENTIAL_NAME_FRAGMENTS = Object.freeze([

'password', 'secret', 'token', 'apikey', 'consumerkey', 'authorization', 'cookie', 'privatekey',

]);

/**

* Properties of the gateway object that the summary reports in their own right, so they are not

* repeated as fields.

*/

const HOISTED_PROPERTIES = new Set([

'id', 'title', 'enabled', 'order', 'settings',

// REST envelope, not gateway configuration: `_links` holds hrefs back to the same routes the

// transport refuses. Dropping it entirely keeps the summary about the gateway.

'_links',

]);

/**

* Properties WooCommerce's payment-gateway schema declares on every gateway. Listing them is

* what makes `absent` a real observation instead of a state nothing can ever produce: a gateway

* that omits `method_description` is reported `absent`, distinct from one that defines it empty.

*/

const DECLARED_GATEWAY_FIELDS = Object.freeze(['description', 'method_title', 'method_description', 'method_supports']);

/** Sentinel for "the gateway does not define this field". Not a value; never returned. */

const ABSENT = Symbol('absent');

/** Whether the shared secret-shape guard can run at all. See `guardUnusableReason`. */

export function guardIsOperational() {

return isUsable();

}

/**

* Why the guard cannot run, or null when it is fine.

*

* A caller that is about to read gateway configuration must check this FIRST and refuse the

* read rather than proceed unguarded. A guard that silently evaluates an empty pattern set

* returns values verbatim, which is the failure mode worth being loud about.

*/

export function guardUnusableReason() {

return unusableReason();

}

function normalizeFieldName(name) {

return String(name).toLowerCase().replace(/[^a-z0-9]/g, '');

}

function isCredentialShapedName(name) {

const normalized = normalizeFieldName(name);

return CREDENTIAL_NAME_FRAGMENTS.some((fragment) => normalized.includes(fragment));

}

/**

* A WooCommerce settings entry is `{ id, label, type, value, default, ... }`; some gateways and

* some plugins hand back the bare value instead. Both are accepted, and neither the label nor

* the tip is read -- only whether there is a value and, for an allowlisted field, what it is.

*/

function settingEntryValue(entry) {

if (entry && typeof entry === 'object' && !Array.isArray(entry) && Object.hasOwn(entry, 'value')) {

return entry.value;

}

return entry;

}

/**

* Whether a returnable string is, or CONTAINS, a secret-shaped token.

*

* The shared guard matches a whole value, prefix-not-substring — deliberately, because that is

* what keeps a 44-character payment-pointer id from being eaten by the long-opaque rule on the

* plugin's side, where a column value IS the whole value. Here the returnable fields are free

* text: `description` is a paragraph a merchant typed, and a support key pasted mid-sentence

* would sail through a whole-value check.

*

* So the same guard is applied at token granularity. This never widens what counts as

* secret-shaped — every verdict still comes from the one canonical manifest — it only asks the

* question of each token as well as of the whole string. A hit redacts the WHOLE value, never

* the surrounding words: returning "Pay securely. Support key [REDACTED]" would confirm exactly

* where the credential sits and how the rest of the sentence reads.

*/

function containsSecretShapedToken(text) {

if (isSecretShaped(text)) return true;

for (const token of text.split(/[\s,;:"'<>()[\]{}]+/)) {

if (token && token !== text && isSecretShaped(token)) return true;

}

return false;

}

function stateOf(value) {

if (value === ABSENT) return 'absent';

if (value === null || value === undefined || value === '') return 'blank';

if (Array.isArray(value)) return value.length === 0 ? 'blank' : 'present';

if (typeof value === 'object') return Object.keys(value).length === 0 ? 'blank' : 'present';

return 'present';

}

/**

* Whether one field's value may be returned, and in what form.

*

* Returns `{ include, value?, warning?, redacted? }`. `include: false` means the `value`

* property is omitted from the field entry ENTIRELY -- not `null`, not `''` -- so "we withheld

* this" stays distinguishable from "this field is empty", which is what `state: "blank"` means.

*

* `allowlist` is a parameter so the allowlist/credential-name contradiction can be exercised

* directly by a test; there is no name on the shipped allowlist that is also credential-shaped,

* and there had better never be. It is safe as a seam because this function is pure and decides

* only what to do with a value the caller already holds -- it grants no access to anything.

* `reduceGatewayResponse` always uses the default, and nothing else in the read path takes an

* allowlist at all.

*/

export function valueDecision(name, state, value, allowlist = VALUE_ALLOWLIST) {

if (!allowlist.includes(name)) {

return { include: false };

}

if (isCredentialShapedName(name)) {

return {

include: false,

warning: `field "${name}" is on the value allowlist and also reads as a credential name — value dropped; fix the allowlist`,

};

}

if (state !== 'present') {

// `blank` and `absent` have no value to return, and `state` already says so.

return { include: false };

}

if (typeof value === 'string') {

// The allowlist grants permission to return A value. It never grants permission to skip the

// guard: an allowlisted field is display text under vendor control, and nothing stops

// `description` holding a pasted live key.

if (containsSecretShapedToken(value)) {

return { include: true, value: REDACTED, redacted: true };

}

return { include: true, value };

}

if (typeof value === 'number' || typeof value === 'boolean') {

return { include: true, value };

}

// An object or array under an allowlisted name would carry unmodelled properties straight

// through the summary. Report that it is set; do not carry its shape.

return {

include: false,

warning: `field "${name}" is allowlisted but holds a ${Array.isArray(value) ? 'list' : 'structured'} value — value withheld`,

};

}

function guardedText(value) {

if (typeof value !== 'string') return null;

return containsSecretShapedToken(value) ? REDACTED : value;

}

function reduceGateway(gateway, totals, warnings) {

const settings = gateway && typeof gateway.settings === 'object' && !Array.isArray(gateway.settings)

? gateway.settings

: {};

// Settings win over a same-named top-level property: WooCommerce mirrors `description` and

// `title` into both, and the settings entry is the one that holds what the merchant configured.

const values = new Map();

for (const [key, value] of Object.entries(gateway)) {

if (HOISTED_PROPERTIES.has(key)) continue;

values.set(key, value);

}

for (const [key, entry] of Object.entries(settings)) {

values.set(key, settingEntryValue(entry));

}

for (const declared of DECLARED_GATEWAY_FIELDS) {

if (!values.has(declared)) values.set(declared, ABSENT);

}

const fields = [];

for (const name of [...values.keys()].sort()) {

const raw = values.get(name);

const state = stateOf(raw);

if (state === 'present') totals.fieldsPresent += 1;

const decision = valueDecision(name, state, raw);

if (decision.warning) warnings.push(`${gateway.id ?? 'unknown gateway'}: ${decision.warning}`);

// Built key by key, never spread from the source object: a raw-response property that is

// not modelled here must not be able to ride along into the summary.

const field = { name: String(name), state };

if (decision.include) {

field.value = decision.value;

totals.valuesReturned += 1;

if (decision.redacted) totals.valuesRedacted += 1;

} else {

totals.valuesWithheld += 1;

}

fields.push(field);

}

const order = Number.isFinite(Number(gateway.order)) && gateway.order !== '' && gateway.order !== null

? Number(gateway.order)

: null;

return {

id: guardedText(gateway.id),

title: guardedText(gateway.title),

enabled: gateway.enabled === true || gateway.enabled === 'yes',

order,

fields,

};

}

/**

* Reduce a `wc/v3/payment_gateways` response to the summary schema.

*

* Input is the transport's result shape (`{ ok, status, json }`) -- plain data, not a client.

* Output carries ONLY the properties defined here. Never a prefix or suffix of a withheld

* value, never its length, never a hash of it, never whether two fields are equal.

*

* A failed request yields ZERO field entries rather than a page of `absent`, so "this gateway

* has no API key" can never be confused with "we could not ask".

*/

export function reduceGatewayResponse(response) {

const warnings = [];

const totals = { gateways: 0, enabled: 0, fieldsPresent: 0, valuesReturned: 0, valuesWithheld: 0, valuesRedacted: 0 };

const empty = (outcome) => ({ route: GATEWAY_COLLECTION_ROUTE, outcome, gateways: [], totals, warnings });

if (!response || typeof response !== 'object') {

return empty('unreachable');

}

if (response.status === 401 || response.status === 403) {

return empty('unauthorized');

}

if (!response.ok) {

return empty('unreachable');

}

if (!Array.isArray(response.json)) {

return empty('malformed');

}

const gateways = [];

for (const entry of response.json) {

if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {

warnings.push('a gateway entry was not an object and was skipped');

continue;

}

const gateway = reduceGateway(entry, totals, warnings);

totals.gateways += 1;

if (gateway.enabled) totals.enabled += 1;

gateways.push(gateway);

}

return { route: GATEWAY_COLLECTION_ROUTE, outcome: 'ok', gateways, totals, warnings };

}

/**

* One line for the approval gate's plan report. A run that states what it read

* and what it retained is auditable; one that silently read the settings blob is not.

*/

export function describeGatewaySummary(summary) {

if (!summary || summary.outcome !== 'ok') {

return `Payment gateways: not read (${summary?.outcome ?? 'unreachable'}); no gateway configuration retained.`;

}

const t = summary.totals;

return `Payment gateways: read ${summary.route} — ${t.gateways} registered, ${t.enabled} enabled, `

+ `${t.fieldsPresent} configured field(s), ${t.valuesWithheld} value(s) withheld, `

+ `${t.valuesRedacted} redacted, ${t.valuesReturned} display value(s) retained. No credential value retained.`;

}