Skip to content

Commit 8c8e218

Browse files
naorynaory
committed
deploy: f677212 
1 parent 26decfc commit 8c8e218

9 files changed

Lines changed: 444 additions & 12 deletions

File tree

‎reference/reference/sdk/index.html‎

Lines changed: 47 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1085,6 +1085,17 @@
10851085
</span>
10861086
</a>
10871087

1088+
</li>
1089+
1090+
<li class="md-nav__item">
1091+
<a href="#cumulative-budget-enforcement" class="md-nav__link">
1092+
<span class="md-ellipsis">
1093+
1094+
Cumulative Budget Enforcement
1095+
1096+
</span>
1097+
</a>
1098+
10881099
</li>
10891100

10901101
<li class="md-nav__item">
@@ -1482,6 +1493,17 @@
14821493
</span>
14831494
</a>
14841495

1496+
</li>
1497+
1498+
<li class="md-nav__item">
1499+
<a href="#cumulative-budget-enforcement" class="md-nav__link">
1500+
<span class="md-ellipsis">
1501+
1502+
Cumulative Budget Enforcement
1503+
1504+
</span>
1505+
</a>
1506+
14851507
</li>
14861508

14871509
<li class="md-nav__item">
@@ -1554,14 +1576,17 @@ <h2 id="import">Import</h2>
15541576
<span class="p">}</span><span class="w"> </span><span class="kr">from</span><span class="w"> </span><span class="s2">&quot;mpcp-service/sdk&quot;</span><span class="p">;</span>
15551577
</code></pre></div>
15561578
<h2 id="policy-grant">Policy Grant</h2>
1557-
<div class="highlight"><pre><span></span><code><span class="k">import</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nx">createPolicyGrant</span><span class="w"> </span><span class="p">}</span><span class="w"> </span><span class="kr">from</span><span class="w"> </span><span class="s2">&quot;mpcp-service/sdk&quot;</span><span class="p">;</span>
1579+
<div class="highlight"><pre><span></span><code><span class="k">import</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nx">createPolicyGrant</span><span class="p">,</span><span class="w"> </span><span class="nx">createSignedPolicyGrant</span><span class="w"> </span><span class="p">}</span><span class="w"> </span><span class="kr">from</span><span class="w"> </span><span class="s2">&quot;mpcp-service/sdk&quot;</span><span class="p">;</span>
15581580

15591581
<span class="kd">const</span><span class="w"> </span><span class="nx">grant</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nx">createPolicyGrant</span><span class="p">({</span>
1560-
<span class="w"> </span><span class="nx">policyHash</span><span class="o">:</span><span class="w"> </span><span class="s2">&quot;a1b2c3&quot;</span><span class="p">,</span>
1582+
<span class="w"> </span><span class="nx">policyHash</span><span class="o">:</span><span class="w"> </span><span class="s2">&quot;a1b2c3d4e5f6&quot;</span><span class="p">,</span>
15611583
<span class="w"> </span><span class="nx">allowedRails</span><span class="o">:</span><span class="w"> </span><span class="p">[</span><span class="s2">&quot;xrpl&quot;</span><span class="p">,</span><span class="w"> </span><span class="s2">&quot;evm&quot;</span><span class="p">],</span>
15621584
<span class="w"> </span><span class="nx">allowedAssets</span><span class="o">:</span><span class="w"> </span><span class="p">[{</span><span class="w"> </span><span class="nx">kind</span><span class="o">:</span><span class="w"> </span><span class="s2">&quot;IOU&quot;</span><span class="p">,</span><span class="w"> </span><span class="nx">currency</span><span class="o">:</span><span class="w"> </span><span class="s2">&quot;RLUSD&quot;</span><span class="p">,</span><span class="w"> </span><span class="nx">issuer</span><span class="o">:</span><span class="w"> </span><span class="s2">&quot;rIssuer&quot;</span><span class="w"> </span><span class="p">}],</span>
15631585
<span class="w"> </span><span class="nx">expiresAt</span><span class="o">:</span><span class="w"> </span><span class="s2">&quot;2030-12-31T23:59:59Z&quot;</span><span class="p">,</span>
15641586
<span class="p">});</span>
1587+
1588+
<span class="c1">// Signed (requires MPCP_POLICY_GRANT_SIGNING_PRIVATE_KEY_PEM — returns null if not set)</span>
1589+
<span class="kd">const</span><span class="w"> </span><span class="nx">signedGrant</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nx">createSignedPolicyGrant</span><span class="p">(</span><span class="nx">grant</span><span class="p">);</span>
15651590
</code></pre></div>
15661591
<h2 id="budget-authorization">Budget Authorization</h2>
15671592
<div class="highlight"><pre><span></span><code><span class="k">import</span><span class="w"> </span><span class="p">{</span>
@@ -1637,6 +1662,14 @@ <h2 id="verification">Verification</h2>
16371662
<span class="kd">const</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nx">result</span><span class="p">,</span><span class="w"> </span><span class="nx">steps</span><span class="w"> </span><span class="p">}</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nx">verifySettlementWithReport</span><span class="p">(</span><span class="nx">context</span><span class="p">);</span>
16381663
<span class="kd">const</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nx">valid</span><span class="p">,</span><span class="w"> </span><span class="nx">checks</span><span class="w"> </span><span class="p">}</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nx">verifySettlementDetailed</span><span class="p">(</span><span class="nx">context</span><span class="p">);</span>
16391664
</code></pre></div>
1665+
<h2 id="cumulative-budget-enforcement">Cumulative Budget Enforcement</h2>
1666+
<p>When performing multiple payments in a session, pass <code>cumulativeSpentMinor</code> to the verification context so the budget check accounts for all prior spending:</p>
1667+
<div class="highlight"><pre><span></span><code><span class="kd">const</span><span class="w"> </span><span class="nx">result</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nx">verifySettlement</span><span class="p">({</span>
1668+
<span class="w"> </span><span class="p">...</span><span class="nx">context</span><span class="p">,</span>
1669+
<span class="w"> </span><span class="nx">cumulativeSpentMinor</span><span class="o">:</span><span class="w"> </span><span class="s2">&quot;5000&quot;</span><span class="p">,</span><span class="w"> </span><span class="c1">// total minor-unit amount spent before this payment</span>
1670+
<span class="p">});</span>
1671+
</code></pre></div>
1672+
<p>The session authority MUST maintain this counter. The verifier is stateless and will not track prior payments on its own.</p>
16401673
<h2 id="environment-variables">Environment Variables</h2>
16411674
<table>
16421675
<thead>
@@ -1670,6 +1703,18 @@ <h2 id="environment-variables">Environment Variables</h2>
16701703
<td>MPCP_SPA_SIGNING_KEY_ID</td>
16711704
<td>Key identifier (default: mpcp-spa-signing-key-1)</td>
16721705
</tr>
1706+
<tr>
1707+
<td>MPCP_POLICY_GRANT_SIGNING_PRIVATE_KEY_PEM</td>
1708+
<td>Private key for signing PolicyGrants</td>
1709+
</tr>
1710+
<tr>
1711+
<td>MPCP_POLICY_GRANT_SIGNING_PUBLIC_KEY_PEM</td>
1712+
<td>Public key for verifying PolicyGrant signatures (when set, unsigned grants are rejected)</td>
1713+
</tr>
1714+
<tr>
1715+
<td>MPCP_POLICY_GRANT_SIGNING_KEY_ID</td>
1716+
<td>Key identifier (default: mpcp-policy-grant-signing-key-1)</td>
1717+
</tr>
16731718
</tbody>
16741719
</table>
16751720
<h2 id="see-also">See Also</h2>

‎reference/search/search_index.json‎

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

‎spec/architecture/actors/index.html‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1943,6 +1943,9 @@ <h2 id="vehicle-wallet-machine-wallet">Vehicle Wallet (Machine Wallet)</h2>
19431943
<li>Executes settlement transactions</li>
19441944
</ul>
19451945
<p>The wallet is the MPCP actor that signs SignedBudgetAuthorization and SignedPaymentAuthorization.</p>
1946+
<blockquote>
1947+
<p><strong>Note on Vehicle Identity:</strong> The <code>vehicleId</code> field in SBA artifacts is self-reported by the wallet. Production deployments SHOULD establish vehicle attestation via device key binding (e.g., a hardware-backed key whose public key is registered with the fleet operator). Without attestation, <code>vehicleId</code> cannot be cryptographically verified and is informational only.</p>
1948+
</blockquote>
19461949
<h2 id="service-provider">Service Provider</h2>
19471950
<p>The entity that receives payment for a service (parking, charging, tolls).</p>
19481951
<p><strong>Responsibilities:</strong></p>

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

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1620,6 +1620,56 @@
16201620
</span>
16211621
</a>
16221622

1623+
</li>
1624+
1625+
<li class="md-nav__item">
1626+
<a href="#full-profile-security-requirements" class="md-nav__link">
1627+
<span class="md-ellipsis">
1628+
1629+
Full Profile Security Requirements
1630+
1631+
</span>
1632+
</a>
1633+
1634+
<nav class="md-nav" aria-label="Full Profile Security Requirements">
1635+
<ul class="md-nav__list">
1636+
1637+
<li class="md-nav__item">
1638+
<a href="#policygrant-signing" class="md-nav__link">
1639+
<span class="md-ellipsis">
1640+
1641+
PolicyGrant Signing
1642+
1643+
</span>
1644+
</a>
1645+
1646+
</li>
1647+
1648+
<li class="md-nav__item">
1649+
<a href="#policyhash-length" class="md-nav__link">
1650+
<span class="md-ellipsis">
1651+
1652+
policyHash Length
1653+
1654+
</span>
1655+
</a>
1656+
1657+
</li>
1658+
1659+
<li class="md-nav__item">
1660+
<a href="#spa-nonce" class="md-nav__link">
1661+
<span class="md-ellipsis">
1662+
1663+
SPA Nonce
1664+
1665+
</span>
1666+
</a>
1667+
1668+
</li>
1669+
1670+
</ul>
1671+
</nav>
1672+
16231673
</li>
16241674

16251675
<li class="md-nav__item">
@@ -1988,6 +2038,56 @@
19882038
</span>
19892039
</a>
19902040

2041+
</li>
2042+
2043+
<li class="md-nav__item">
2044+
<a href="#full-profile-security-requirements" class="md-nav__link">
2045+
<span class="md-ellipsis">
2046+
2047+
Full Profile Security Requirements
2048+
2049+
</span>
2050+
</a>
2051+
2052+
<nav class="md-nav" aria-label="Full Profile Security Requirements">
2053+
<ul class="md-nav__list">
2054+
2055+
<li class="md-nav__item">
2056+
<a href="#policygrant-signing" class="md-nav__link">
2057+
<span class="md-ellipsis">
2058+
2059+
PolicyGrant Signing
2060+
2061+
</span>
2062+
</a>
2063+
2064+
</li>
2065+
2066+
<li class="md-nav__item">
2067+
<a href="#policyhash-length" class="md-nav__link">
2068+
<span class="md-ellipsis">
2069+
2070+
policyHash Length
2071+
2072+
</span>
2073+
</a>
2074+
2075+
</li>
2076+
2077+
<li class="md-nav__item">
2078+
<a href="#spa-nonce" class="md-nav__link">
2079+
<span class="md-ellipsis">
2080+
2081+
SPA Nonce
2082+
2083+
</span>
2084+
</a>
2085+
2086+
</li>
2087+
2088+
</ul>
2089+
</nav>
2090+
19912091
</li>
19922092

19932093
<li class="md-nav__item">
@@ -2110,6 +2210,18 @@ <h2 id="optional-intent-attestation-layer-ial">Optional: Intent Attestation Laye
21102210
<p>Full profile deployments may additionally publish the <code>intentHash</code> to the Intent Attestation Layer (IAL) before settlement execution. This creates a timestamped, tamper-evident public record that the commitment existed prior to the transaction, enabling third-party dispute resolution.</p>
21112211
<p>See <a href="../../protocol/anchoring/">Anchoring</a> for the IAL integration specification.</p>
21122212
<hr />
2213+
<h2 id="full-profile-security-requirements">Full Profile Security Requirements</h2>
2214+
<h3 id="policygrant-signing">PolicyGrant Signing</h3>
2215+
<p>In Full Profile deployments, PolicyGrants MUST be signed by the policy authority. Configure <code>MPCP_POLICY_GRANT_SIGNING_PUBLIC_KEY_PEM</code> on the verifier; unsigned grants will be rejected.</p>
2216+
<h3 id="policyhash-length">policyHash Length</h3>
2217+
<p><code>policyHash</code> MUST be a full SHA-256 hash (64 lowercase hex characters), computed as:</p>
2218+
<div class="highlight"><pre><span></span><code>policyHash = SHA256(&quot;MPCP:Policy:1.0:&quot; || canonicalJson(policyDocument))
2219+
</code></pre></div>
2220+
<p>Short or truncated hashes are rejected in Full Profile deployments. The minimum accepted length is 12 hex characters; the full SHA-256 output (64 chars) is strongly recommended.</p>
2221+
<h3 id="spa-nonce">SPA Nonce</h3>
2222+
<p>The <code>nonce</code> field SHOULD be present in Full Profile SPAs. The reference implementation auto-generates a UUID nonce on every <code>createSignedPaymentAuthorization()</code> call.</p>
2223+
<p>Recipients SHOULD record nonces to detect and reject replayed SPAs within the same session. The verifier itself does not track nonces (stateless model); nonce uniqueness enforcement is the responsibility of the session authority.</p>
2224+
<hr />
21132225
<h2 id="see-also">See Also</h2>
21142226
<ul>
21152227
<li><a href="../lite-profile/">Lite Profile</a> — SPA-only settlement binding</li>

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

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1581,6 +1581,45 @@
15811581
</span>
15821582
</a>
15831583

1584+
</li>
1585+
1586+
<li class="md-nav__item">
1587+
<a href="#security-considerations" class="md-nav__link">
1588+
<span class="md-ellipsis">
1589+
1590+
Security Considerations
1591+
1592+
</span>
1593+
</a>
1594+
1595+
<nav class="md-nav" aria-label="Security Considerations">
1596+
<ul class="md-nav__list">
1597+
1598+
<li class="md-nav__item">
1599+
<a href="#backend-substitution-risk" class="md-nav__link">
1600+
<span class="md-ellipsis">
1601+
1602+
Backend Substitution Risk
1603+
1604+
</span>
1605+
</a>
1606+
1607+
</li>
1608+
1609+
<li class="md-nav__item">
1610+
<a href="#memo-and-metadata" class="md-nav__link">
1611+
<span class="md-ellipsis">
1612+
1613+
Memo and Metadata
1614+
1615+
</span>
1616+
</a>
1617+
1618+
</li>
1619+
1620+
</ul>
1621+
</nav>
1622+
15841623
</li>
15851624

15861625
<li class="md-nav__item">
@@ -1966,6 +2005,45 @@
19662005
</span>
19672006
</a>
19682007

2008+
</li>
2009+
2010+
<li class="md-nav__item">
2011+
<a href="#security-considerations" class="md-nav__link">
2012+
<span class="md-ellipsis">
2013+
2014+
Security Considerations
2015+
2016+
</span>
2017+
</a>
2018+
2019+
<nav class="md-nav" aria-label="Security Considerations">
2020+
<ul class="md-nav__list">
2021+
2022+
<li class="md-nav__item">
2023+
<a href="#backend-substitution-risk" class="md-nav__link">
2024+
<span class="md-ellipsis">
2025+
2026+
Backend Substitution Risk
2027+
2028+
</span>
2029+
</a>
2030+
2031+
</li>
2032+
2033+
<li class="md-nav__item">
2034+
<a href="#memo-and-metadata" class="md-nav__link">
2035+
<span class="md-ellipsis">
2036+
2037+
Memo and Metadata
2038+
2039+
</span>
2040+
</a>
2041+
2042+
</li>
2043+
2044+
</ul>
2045+
</nav>
2046+
19692047
</li>
19702048

19712049
<li class="md-nav__item">
@@ -2090,6 +2168,17 @@ <h2 id="spa-structure">SPA Structure</h2>
20902168
<hr />
20912169
<h2 id="verification-behavior">Verification Behavior</h2>
20922170
<p>Step 3 of the MPCP verification algorithm (intent binding) is skipped when <code>intentHash</code> is absent. All other verification steps apply in full.</p>
2171+
<p>The verification report will include:</p>
2172+
<div class="highlight"><pre><span></span><code>Hash binding: NOT CHECKED (Lite Profile — intentHash absent)
2173+
</code></pre></div>
2174+
<p>The <code>hashBindingChecked</code> field in <code>VerificationReport</code> will be <code>false</code> when <code>intentHash</code> is absent.</p>
2175+
<hr />
2176+
<h2 id="security-considerations">Security Considerations</h2>
2177+
<h3 id="backend-substitution-risk">Backend Substitution Risk</h3>
2178+
<p>In Lite Profile deployments, a compromised backend can substitute payment amounts or destinations <strong>between policy authorization and settlement execution</strong> without invalidating the cryptographic chain. Only the fields explicitly carried in the SPA (rail, asset, amount, destination) are protected.</p>
2179+
<p>Deployments that cannot tolerate this risk MUST use the Full Profile with <code>intentHash</code> binding.</p>
2180+
<h3 id="memo-and-metadata">Memo and Metadata</h3>
2181+
<p>Fields outside the SPA — memo content, ancillary metadata, extended transaction fields — receive no cryptographic protection in Lite Profile. If these fields affect business outcomes, use the Full Profile.</p>
20932182
<hr />
20942183
<h2 id="see-also">See Also</h2>
20952184
<ul>

0 commit comments

Comments
 (0)