Skip to content

Commit 25dff5d

Browse files
naorynaory
committed
deploy: b844c4d 
1 parent 4fafccf commit 25dff5d

5 files changed

Lines changed: 277 additions & 1 deletion

File tree

‎spec/architecture/actors/index.html‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2198,6 +2198,10 @@ <h2 id="trust-gateway">Trust Gateway</h2>
21982198
self-report any budget ceiling. The gateway enforces the PA-signed limit independently — it never
21992199
trusts the agent's view of remaining budget. Even if the gateway itself were compromised, the
22002200
XRPL escrow provides an on-chain upper bound that the ledger enforces.</p>
2201+
<p><strong>Key security:</strong> The gateway's XRPL private key SHOULD be stored in an HSM or KMS. The PA
2202+
SHOULD issue an XRPL Credential to the gateway account (<code>CredentialType = hex("mpcp:authorized-gateway")</code>);
2203+
on compromise, the PA deletes the credential to revoke the gateway's on-chain authorization.
2204+
See <a href="../../protocol/trust-model/#gateway-seed-security">Gateway Seed Security</a>.</p>
22012205
<p><strong>Required for:</strong> Online payments, budget enforcement, escrow create/cancel.</p>
22022206
<p><strong>Optional for:</strong> Offline signature-only mode — merchants can accept payments without the gateway
22032207
using Trust Bundle key verification + <code>offlineMaxSinglePayment</code> cap, accepting reduced guarantees

‎spec/profiles/gateway-profile/index.html‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1828,6 +1828,17 @@
18281828
</span>
18291829
</a>
18301830

1831+
</li>
1832+
1833+
<li class="md-nav__item">
1834+
<a href="#gateway-key-protection" class="md-nav__link">
1835+
<span class="md-ellipsis">
1836+
1837+
Gateway key protection
1838+
1839+
</span>
1840+
</a>
1841+
18311842
</li>
18321843

18331844
<li class="md-nav__item">
@@ -2401,6 +2412,17 @@
24012412
</span>
24022413
</a>
24032414

2415+
</li>
2416+
2417+
<li class="md-nav__item">
2418+
<a href="#gateway-key-protection" class="md-nav__link">
2419+
<span class="md-ellipsis">
2420+
2421+
Gateway key protection
2422+
2423+
</span>
2424+
</a>
2425+
24042426
</li>
24052427

24062428
<li class="md-nav__item">
@@ -2748,6 +2770,16 @@ <h3 id="gateway-as-single-point-of-trust">Gateway as single point of trust</h3>
27482770
<li>Signed receipts allow budget owners to detect gateway misbehavior after the fact</li>
27492771
<li>Level 1 passthrough headers allow budget owners to cryptographically verify what the gateway signed</li>
27502772
</ul>
2773+
<h3 id="gateway-key-protection">Gateway key protection</h3>
2774+
<p>For native MPCP deployments, the Trust Gateway holds an XRPL private key that controls escrow
2775+
and payment transactions. Compromise of this key allows an attacker to drain all active
2776+
escrows. See <a href="../../protocol/trust-model/#gateway-seed-security">Gateway Seed Security</a> for
2777+
the full threat analysis. Key recommendations:</p>
2778+
<ul>
2779+
<li>The gateway private key SHOULD be stored in an HSM or cloud KMS — never in plaintext on disk</li>
2780+
<li>The PA SHOULD issue an XRPL Credential to the gateway account; on compromise, the PA deletes the credential to instantly revoke on-chain authorization</li>
2781+
<li>Operators SHOULD monitor for on-chain payments without corresponding SBAs in the audit trail</li>
2782+
</ul>
27512783
<h3 id="budget-owner-session-token-security">Budget owner session token security</h3>
27522784
<p>The <code>sessionToken</code> granted to an agent controls spending up to the session ceiling. It should be treated with the same care as a payment credential:</p>
27532785
<ul>

‎spec/protocol/mpcp/index.html‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2452,6 +2452,14 @@ <h3 id="policy-authority-key-compromise">Policy Authority Key Compromise</h3>
24522452
<p>Trust Bundles that embedded the key before revocation remain valid until their <code>expiresAt</code>.
24532453
Deployments SHOULD use short Trust Bundle lifetimes in high-assurance environments. See
24542454
<a href="../key-resolution/#key-revocation">Key Revocation</a>.</p>
2455+
<h3 id="gateway-seed-compromise">Gateway Seed Compromise</h3>
2456+
<p>If an attacker obtains the Trust Gateway's XRPL private key, they can submit transactions on
2457+
behalf of the gateway — potentially draining all active escrows simultaneously. Per-grant escrow
2458+
bounds exposure per grant, but aggregate exposure is the sum of all active <code>budgetMinor</code> values.</p>
2459+
<p><strong>Mitigations:</strong> Production gateways SHOULD store the private key in an HSM/KMS. The PA SHOULD
2460+
issue an XRPL Credential (XLS-70) to the gateway account; on compromise, the PA deletes the
2461+
credential to revoke the gateway's on-chain authorization. Operators SHOULD monitor for
2462+
on-chain payments without corresponding SBAs. See <a href="../trust-model/#gateway-seed-security">Gateway Seed Security</a>.</p>
24552463
<h3 id="settlement-tampering">Settlement Tampering</h3>
24562464
<p>Verification ensures that executed settlement transactions match authorized parameters before the session is finalized.</p>
24572465
<hr />

‎spec/protocol/trust-model/index.html‎

Lines changed: 232 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1364,6 +1364,78 @@
13641364
</span>
13651365
</a>
13661366

1367+
</li>
1368+
1369+
<li class="md-nav__item">
1370+
<a href="#gateway-seed-security" class="md-nav__link">
1371+
<span class="md-ellipsis">
1372+
1373+
Gateway Seed Security
1374+
1375+
</span>
1376+
</a>
1377+
1378+
<nav class="md-nav" aria-label="Gateway Seed Security">
1379+
<ul class="md-nav__list">
1380+
1381+
<li class="md-nav__item">
1382+
<a href="#threat-gateway-seed-compromise" class="md-nav__link">
1383+
<span class="md-ellipsis">
1384+
1385+
Threat: Gateway Seed Compromise
1386+
1387+
</span>
1388+
</a>
1389+
1390+
</li>
1391+
1392+
<li class="md-nav__item">
1393+
<a href="#mitigation-1-hsm-kms-for-key-storage-should" class="md-nav__link">
1394+
<span class="md-ellipsis">
1395+
1396+
Mitigation 1: HSM / KMS for Key Storage (SHOULD)
1397+
1398+
</span>
1399+
</a>
1400+
1401+
</li>
1402+
1403+
<li class="md-nav__item">
1404+
<a href="#mitigation-2-xrpl-credential-based-gateway-authorization-should" class="md-nav__link">
1405+
<span class="md-ellipsis">
1406+
1407+
Mitigation 2: XRPL Credential-Based Gateway Authorization (SHOULD)
1408+
1409+
</span>
1410+
</a>
1411+
1412+
</li>
1413+
1414+
<li class="md-nav__item">
1415+
<a href="#mitigation-3-on-chain-monitoring-and-alerting-should" class="md-nav__link">
1416+
<span class="md-ellipsis">
1417+
1418+
Mitigation 3: On-Chain Monitoring and Alerting (SHOULD)
1419+
1420+
</span>
1421+
</a>
1422+
1423+
</li>
1424+
1425+
<li class="md-nav__item">
1426+
<a href="#defense-in-depth-summary" class="md-nav__link">
1427+
<span class="md-ellipsis">
1428+
1429+
Defense-in-Depth Summary
1430+
1431+
</span>
1432+
</a>
1433+
1434+
</li>
1435+
1436+
</ul>
1437+
</nav>
1438+
13671439
</li>
13681440

13691441
<li class="md-nav__item">
@@ -2128,6 +2200,78 @@
21282200
</span>
21292201
</a>
21302202

2203+
</li>
2204+
2205+
<li class="md-nav__item">
2206+
<a href="#gateway-seed-security" class="md-nav__link">
2207+
<span class="md-ellipsis">
2208+
2209+
Gateway Seed Security
2210+
2211+
</span>
2212+
</a>
2213+
2214+
<nav class="md-nav" aria-label="Gateway Seed Security">
2215+
<ul class="md-nav__list">
2216+
2217+
<li class="md-nav__item">
2218+
<a href="#threat-gateway-seed-compromise" class="md-nav__link">
2219+
<span class="md-ellipsis">
2220+
2221+
Threat: Gateway Seed Compromise
2222+
2223+
</span>
2224+
</a>
2225+
2226+
</li>
2227+
2228+
<li class="md-nav__item">
2229+
<a href="#mitigation-1-hsm-kms-for-key-storage-should" class="md-nav__link">
2230+
<span class="md-ellipsis">
2231+
2232+
Mitigation 1: HSM / KMS for Key Storage (SHOULD)
2233+
2234+
</span>
2235+
</a>
2236+
2237+
</li>
2238+
2239+
<li class="md-nav__item">
2240+
<a href="#mitigation-2-xrpl-credential-based-gateway-authorization-should" class="md-nav__link">
2241+
<span class="md-ellipsis">
2242+
2243+
Mitigation 2: XRPL Credential-Based Gateway Authorization (SHOULD)
2244+
2245+
</span>
2246+
</a>
2247+
2248+
</li>
2249+
2250+
<li class="md-nav__item">
2251+
<a href="#mitigation-3-on-chain-monitoring-and-alerting-should" class="md-nav__link">
2252+
<span class="md-ellipsis">
2253+
2254+
Mitigation 3: On-Chain Monitoring and Alerting (SHOULD)
2255+
2256+
</span>
2257+
</a>
2258+
2259+
</li>
2260+
2261+
<li class="md-nav__item">
2262+
<a href="#defense-in-depth-summary" class="md-nav__link">
2263+
<span class="md-ellipsis">
2264+
2265+
Defense-in-Depth Summary
2266+
2267+
</span>
2268+
</a>
2269+
2270+
</li>
2271+
2272+
</ul>
2273+
</nav>
2274+
21312275
</li>
21322276

21332277
<li class="md-nav__item">
@@ -2399,12 +2543,100 @@ <h2 id="trust-gateway-as-mandatory-actor">Trust Gateway as Mandatory Actor</h2>
23992543
Bundle so offline merchants can verify that an SBA was produced by an entity operating under a
24002544
registered gateway. (See roadmap: Gateway key in Trust Bundle.)</p>
24012545
<hr />
2546+
<h2 id="gateway-seed-security">Gateway Seed Security</h2>
2547+
<h3 id="threat-gateway-seed-compromise">Threat: Gateway Seed Compromise</h3>
2548+
<p>The Trust Gateway holds an XRPL private key (seed) that controls the gateway account. If an
2549+
attacker obtains this seed, they can submit XRPL transactions on behalf of the gateway —
2550+
draining all active escrows simultaneously.</p>
2551+
<p>Per-grant escrow limits exposure per individual grant (each escrow locks only <code>budgetMinor</code>
2552+
XRP), but an attacker with the seed can finish or drain every active escrow at once. The
2553+
aggregate exposure is the sum of all active grants' <code>budgetMinor</code> values.</p>
2554+
<h3 id="mitigation-1-hsm-kms-for-key-storage-should">Mitigation 1: HSM / KMS for Key Storage (SHOULD)</h3>
2555+
<p>Production gateway deployments SHOULD store the XRPL private key in a Hardware Security Module
2556+
(HSM) or cloud Key Management Service (KMS). The key SHOULD never exist in plaintext on disk
2557+
or in environment variables.</p>
2558+
<p>Benefits:</p>
2559+
<ul>
2560+
<li>The private key cannot be extracted — signing operations are performed inside the HSM</li>
2561+
<li>Access to signing is gated by authentication and audit logging</li>
2562+
<li>Key material survives host compromise (attacker gains shell access but cannot export the key)</li>
2563+
</ul>
2564+
<p>Implementations that cannot use an HSM SHOULD at minimum encrypt the key at rest and restrict
2565+
file permissions to the gateway process user.</p>
2566+
<h3 id="mitigation-2-xrpl-credential-based-gateway-authorization-should">Mitigation 2: XRPL Credential-Based Gateway Authorization (SHOULD)</h3>
2567+
<p>For XRPL deployments, the PA SHOULD issue an on-chain credential to the gateway account using
2568+
XLS-70 Credentials, binding the gateway's authorization to a verifiable on-chain attestation:</p>
2569+
<ul>
2570+
<li><code>Issuer</code> = PA's XRPL address</li>
2571+
<li><code>Subject</code> = Gateway's XRPL address</li>
2572+
<li><code>CredentialType</code> = hex-encoded <code>"mpcp:authorized-gateway"</code></li>
2573+
<li>Optional <code>Expiration</code> aligned with the deployment lifecycle</li>
2574+
</ul>
2575+
<p><strong>On compromise:</strong> The PA deletes the gateway credential via <code>CredentialDelete</code>. Even though
2576+
the attacker holds the seed, actors that verify the gateway's credential (other gateways,
2577+
Permissioned Domains, monitoring systems) will see that the credential no longer exists and
2578+
reject interactions with the compromised gateway.</p>
2579+
<p>This does not prevent the attacker from submitting raw XRPL transactions (the seed still
2580+
controls the account), but it invalidates the gateway's MPCP authorization — new PolicyGrants
2581+
with <code>authorizedGateway</code> pointing to the compromised address will not be issued, and actors
2582+
that check the credential will refuse to interact.</p>
2583+
<h3 id="mitigation-3-on-chain-monitoring-and-alerting-should">Mitigation 3: On-Chain Monitoring and Alerting (SHOULD)</h3>
2584+
<p>Gateway operators SHOULD monitor on-chain activity for anomalous payment patterns that may
2585+
indicate seed compromise:</p>
2586+
<ul>
2587+
<li>XRPL payments from the gateway account that do not have a corresponding SBA in the gateway's
2588+
audit log</li>
2589+
<li>Payments missing the <code>mpcp/grant-id</code> memo, or with memo values that do not match any known
2590+
active grant</li>
2591+
<li>Sudden spikes in transaction volume or aggregate spend across grants</li>
2592+
<li><code>EscrowFinish</code> transactions for grants that the gateway did not initiate</li>
2593+
</ul>
2594+
<p>When anomalies are detected, operators SHOULD:</p>
2595+
<ol>
2596+
<li>Revoke the gateway's on-chain credential (Mitigation 2)</li>
2597+
<li>Revoke all active PolicyGrants that reference the compromised <code>authorizedGateway</code> address</li>
2598+
<li>Rotate to a new gateway account and reissue grants</li>
2599+
</ol>
2600+
<h3 id="defense-in-depth-summary">Defense-in-Depth Summary</h3>
2601+
<table>
2602+
<thead>
2603+
<tr>
2604+
<th>Layer</th>
2605+
<th>Mechanism</th>
2606+
<th>Effect</th>
2607+
</tr>
2608+
</thead>
2609+
<tbody>
2610+
<tr>
2611+
<td>Prevention</td>
2612+
<td>HSM / KMS</td>
2613+
<td>Seed cannot be extracted from host</td>
2614+
</tr>
2615+
<tr>
2616+
<td>Authorization</td>
2617+
<td>XRPL Credential</td>
2618+
<td>PA can revoke gateway's on-chain authorization instantly</td>
2619+
</tr>
2620+
<tr>
2621+
<td>Containment</td>
2622+
<td>Per-grant escrow</td>
2623+
<td>Each grant's exposure is bounded by its <code>budgetMinor</code></td>
2624+
</tr>
2625+
<tr>
2626+
<td>Detection</td>
2627+
<td>On-chain monitoring</td>
2628+
<td>Unauthorized transactions are flagged for response</td>
2629+
</tr>
2630+
</tbody>
2631+
</table>
2632+
<hr />
24022633
<h2 id="see-also">See Also</h2>
24032634
<ul>
24042635
<li><a href="../../architecture/actors/">Actors</a> — Actor definitions including Trust Gateway</li>
24052636
<li><a href="../PolicyGrant/">PolicyGrant</a> — PA-signed grant fields</li>
24062637
<li><a href="../trust-bundles/">Trust Bundles</a> — Offline key distribution</li>
24072638
<li><a href="../rails/">Rails</a> — Rail extensibility and escrow URI scheme</li>
2639+
<li><a href="../key-resolution/#key-revocation">Key Revocation</a> — PA key revocation mechanisms</li>
24082640
</ul>
24092641

24102642

‎spec/search/search_index.json‎

Lines changed: 1 addition & 1 deletion
Large diffs are not rendered by default.

0 commit comments

Comments
 (0)