099-programmable-templates.rst (6645B)
1 .. _dd-99: 2 3 DD 99: Programmable Template Validation 4 ####################################### 5 6 Summary 7 ======= 8 9 This document sketches programmable validation for merchant templates. 10 A locally configured Bash script examines a proposed order after normal 11 template processing and either permits or rejects order creation. 12 13 .. warning:: 14 15 This is an early design sketch. It does not yet define a protocol version, 16 complete input schema or stable configuration API. 17 18 Motivation 19 ========== 20 21 Merchant templates cover common ways of turning client input into an order, 22 but some deployments have local conditions that are too specific for the 23 generic merchant protocol. Examples include checking an institution's local 24 campaign rules, validating a site-specific reference or applying a temporary 25 business restriction. 26 27 Adding every local rule to the merchant backend would make the protocol and 28 implementation increasingly specialized. Programmable template validation 29 would instead let an administrator associate a local Bash script with a 30 template. The script examines a proposed order and either allows or rejects 31 its creation. 32 33 Requirements 34 ============ 35 36 * Normal merchant template validation must run before a custom validator. 37 38 * A validator must be a Bash script configured locally by the merchant 39 operator. 40 41 * The script must initially be limited to allowing or rejecting an order. 42 43 * Script input must use a structured, versioned JSON interface. 44 45 * Failure, timeout or malformed output must reject order creation. 46 47 * Scripts must run with strict time and resource limits. 48 49 * Scripts must not receive merchant secrets or unrelated customer data. 50 51 * Installing or changing scripts must require an administrative 52 permission and produce an audit record. 53 54 Proposed Solution 55 ================= 56 57 The merchant backend performs its normal template processing first: 58 59 1. It parses and validates the template instantiation request. 60 61 2. It resolves products and constructs the proposed contract terms. 62 63 3. If the template has a configured validation script, the backend invokes 64 it with the proposed order as versioned JSON on standard input. 65 66 4. An exit status of zero allows the order. Any other exit status rejects 67 it. 68 69 5. Only an allowed proposal is persisted as an order. 70 71 The script is validation-only. Allowing scripts to rewrite 72 contract terms would make it harder to reason about signatures, totals and 73 which component owns protocol validation. A later design may introduce 74 carefully constrained transformations if concrete use cases require them. 75 76 Script Configuration and Invocation 77 ----------------------------------- 78 79 The merchant operator associates an absolute Bash script path with a 80 template. This is server-side configuration and must never be supplied by a 81 client while instantiating the template. The backend invokes the configured 82 file using a fixed command equivalent to: 83 84 .. code-block:: console 85 86 /bin/bash /configured/path/validate-template.sh 87 88 The backend must not construct a shell command from template request values. 89 The script receives no request-derived command-line arguments. A versioned 90 JSON object is written to its standard input and may contain: 91 92 * the merchant instance and template identifiers; 93 94 * the normalized template request; 95 96 * the proposed contract terms; 97 98 * the current time and a small, explicitly defined execution context; and 99 100 * a version number for the validator input schema. 101 102 It must not contain merchant private keys, database credentials or unrelated 103 customer data. 104 105 The script communicates its decision through its exit status: 106 107 * Exit status 0 permits creation of the proposed order. 108 109 * Any non-zero exit status rejects order creation. 110 111 Standard output is ignored in the initial design. A bounded amount of 112 standard error may be recorded in merchant logs for administrators, but must 113 not automatically be returned to an untrusted client. 114 115 Execution Requirements 116 ---------------------- 117 118 Script execution must be bounded by a short timeout and strict resource 119 limits. Failure, timeout and non-zero process termination must deny order 120 creation. 121 122 Network and filesystem access should be disabled by default. If a deployment 123 needs external state, access should be explicitly configured and documented 124 rather than inherited from the merchant backend process. 125 126 The script runs with a minimal environment and a dedicated unprivileged 127 service account. The backend must not pass authentication tokens, database 128 credentials or other ambient secrets through environment variables. 129 130 Configuration and operation of scripts require an administrative 131 permission separate from ordinary template use. Logs should identify the 132 template, script and outcome without recording complete contract terms or 133 sensitive request values by default. 134 135 Open Design Work 136 ================ 137 138 The following points require concrete use cases and implementation 139 experiments: 140 141 * the exact versioned input schema; 142 143 * how scripts are installed, selected and updated; 144 145 * which merchant API error represents rejection by a script; 146 147 * whether controlled read-only access to local data is necessary; 148 149 * how deterministic behavior and reproducible debugging are achieved; and 150 151 * whether any future version should permit constrained modifications to the 152 proposed contract. 153 154 Security Considerations 155 ======================= 156 157 A script runs on the order-creation path and is therefore both a security 158 boundary and a denial-of-service risk. It must not execute with the merchant 159 backend's full authority. Resource limits and fail-closed behavior are 160 mandatory. Bash is not itself a sandbox, so the operating system must enforce 161 the configured process, filesystem and network restrictions. 162 163 Script updates can change which orders a merchant accepts. Configuration 164 changes therefore need authentication, audit records and an explicit rollback 165 mechanism. 166 167 Test Plan 168 ========= 169 170 An eventual implementation should test exit status zero and non-zero, 171 timeouts, missing or unreadable scripts, process failures, resource 172 exhaustion and attempts to use forbidden network or filesystem access. It 173 should also verify the JSON input, confirm that rejected orders are not 174 partially persisted and ensure that diagnostics do not leak sensitive 175 contract data. 176 177 Definition of Done 178 ================== 179 180 This design is ready for implementation only after the versioned input 181 schema, script configuration, permission model, error mapping and operating 182 system restrictions are specified precisely. At least one real deployment 183 rule must be implemented as a Bash script to validate the interface before it 184 becomes a stable merchant feature.