space-data-module-sdk 0.8.14 → 0.8.16
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/bin/space-data-module.js +91 -0
- package/docs/_shell/consumer-assets.html +5 -0
- package/docs/browser-wasmedge-isomorphic.html +261 -0
- package/docs/byo-wasm-quickstart.html +226 -0
- package/docs/byo-wasm-quickstart.md +204 -0
- package/docs/conformance.html +156 -0
- package/docs/conformance.md +92 -0
- package/docs/emception-shared-memory-verdict.md +209 -0
- package/docs/events-abi.html +313 -0
- package/docs/events-abi.md +530 -0
- package/docs/families/analytics.html +178 -0
- package/docs/families/analytics.md +104 -0
- package/docs/families/attitude.html +157 -0
- package/docs/families/attitude.md +36 -0
- package/docs/families/behavior.html +157 -0
- package/docs/families/behavior.md +36 -0
- package/docs/families/breakup.html +157 -0
- package/docs/families/breakup.md +36 -0
- package/docs/families/conjunction.html +186 -0
- package/docs/families/conjunction.md +121 -0
- package/docs/families/data-source.html +318 -0
- package/docs/families/effects.html +157 -0
- package/docs/families/effects.md +36 -0
- package/docs/families/environment.html +170 -0
- package/docs/families/environment.md +73 -0
- package/docs/families/estimation.html +190 -0
- package/docs/families/estimation.md +128 -0
- package/docs/families/gnc.html +157 -0
- package/docs/families/gnc.md +36 -0
- package/docs/families/maneuver.html +209 -0
- package/docs/families/maneuver.md +206 -0
- package/docs/families/obstruction.html +191 -0
- package/docs/families/obstruction.md +96 -0
- package/docs/families/propagator.html +333 -0
- package/docs/families/propulsion.html +157 -0
- package/docs/families/propulsion.md +36 -0
- package/docs/families/reentry.html +157 -0
- package/docs/families/reentry.md +36 -0
- package/docs/families/rf.html +193 -0
- package/docs/families/rf.md +136 -0
- package/docs/families/scheduler.html +157 -0
- package/docs/families/scheduler.md +36 -0
- package/docs/families/sensor.html +157 -0
- package/docs/families/sensor.md +36 -0
- package/docs/families/signature.html +157 -0
- package/docs/families/signature.md +36 -0
- package/docs/flatsql-host-contract.html +176 -0
- package/docs/flatsql-streaming-standard.html +375 -0
- package/docs/gpu-module-abi.html +233 -0
- package/docs/harness-family-matrix.md +135 -0
- package/docs/index.html +216 -85
- package/docs/isomorphic-pthreads.html +228 -0
- package/docs/isomorphic-pthreads.md +84 -0
- package/docs/isomorphic-sdn-runtime-plan.html +274 -0
- package/docs/language-runtime-matrix.html +182 -0
- package/docs/llms.txt +86 -0
- package/docs/module-bundle-runtime-plan.html +146 -0
- package/docs/module-publication-standard.html +503 -0
- package/docs/node-red-default-node-parity.html +201 -0
- package/docs/propagator-abi.md +73 -21
- package/docs/protect-and-sign.html +181 -0
- package/docs/protect-and-sign.md +120 -0
- package/docs/protocol-installation.html +296 -0
- package/docs/publication-submission.html +158 -0
- package/docs/publication-submission.md +78 -0
- package/docs/secrets-capability.html +206 -0
- package/docs/styles.css +860 -167
- package/docs/testing-harness.html +408 -0
- package/docs/tri-runtime-parity-gate.html +182 -0
- package/docs/tri-runtime-parity.html +203 -0
- package/include/orbpro/orbpro_event_runner.h +951 -0
- package/include/orbpro/orbpro_events_abi.h +565 -0
- package/include/orbpro/orbpro_propagator_abi.h +17 -0
- package/package.json +15 -5
- package/schemas/orbpro/Events.fbs +501 -0
- package/schemas/orbpro/Propagator.fbs +72 -9
- package/schemas/orbpro/reference-frame-crosswalk.json +108 -0
- package/schemas/orbpro/reference-frame.lock.json +98 -0
- package/src/browser.js +13 -0
- package/src/conformance/abiDriver.js +225 -0
- package/src/conformance/index.js +151 -0
- package/src/conformance/propagatorSuite.js +526 -0
- package/src/conformance/selfTest.js +275 -0
- package/src/conformance/selfTestCorpus.js +68 -0
- package/src/conformance/twoBodyReference.js +132 -0
- package/src/generated/orbpro/events-abi.js +206 -0
- package/src/generated/orbpro/events-abi.ts +319 -0
- package/src/generated/orbpro/propagator/reference-frame.js +17 -0
- package/src/generated/orbpro/propagator/reference-frame.ts +91 -1
- package/src/generated/orbpro/propagator-abi.js +17 -0
- package/src/generated/orbpro/propagator-abi.ts +17 -0
- package/src/generated/spacedatastandards/plg/CCT.d.ts +94 -0
- package/src/generated/spacedatastandards/plg/CCT.d.ts.map +1 -0
- package/src/generated/spacedatastandards/plg/CCT.js +208 -0
- package/src/generated/spacedatastandards/plg/CCT.ts +281 -0
- package/src/generated/spacedatastandards/plg/CCTCategory.d.ts +98 -0
- package/src/generated/spacedatastandards/plg/CCTCategory.d.ts.map +1 -0
- package/src/generated/spacedatastandards/plg/CCTCategory.js +177 -0
- package/src/generated/spacedatastandards/plg/CCTCategory.ts +269 -0
- package/src/generated/spacedatastandards/plg/CCTCategoryRollup.d.ts +54 -0
- package/src/generated/spacedatastandards/plg/CCTCategoryRollup.d.ts.map +1 -0
- package/src/generated/spacedatastandards/plg/CCTCategoryRollup.js +106 -0
- package/src/generated/spacedatastandards/plg/CCTCategoryRollup.ts +144 -0
- package/src/generated/spacedatastandards/plg/PLG.d.ts +46 -2
- package/src/generated/spacedatastandards/plg/PLG.d.ts.map +1 -1
- package/src/generated/spacedatastandards/plg/PLG.js +78 -5
- package/src/generated/spacedatastandards/plg/PLG.ts +90 -5
- package/src/generated/spacedatastandards/plg/capabilityClass.d.ts +181 -0
- package/src/generated/spacedatastandards/plg/capabilityClass.d.ts.map +1 -0
- package/src/generated/spacedatastandards/plg/capabilityClass.js +183 -0
- package/src/generated/spacedatastandards/plg/capabilityClass.ts +208 -0
- package/src/generated/spacedatastandards/plg/main.d.ts +4 -0
- package/src/generated/spacedatastandards/plg/main.d.ts.map +1 -1
- package/src/generated/spacedatastandards/plg/main.js +4 -0
- package/src/generated/spacedatastandards/plg/main.ts +4 -0
- package/src/generated/spacedatastandards/plg/pluginCategory.d.ts +40 -2
- package/src/generated/spacedatastandards/plg/pluginCategory.d.ts.map +1 -1
- package/src/generated/spacedatastandards/plg/pluginCategory.js +40 -2
- package/src/generated/spacedatastandards/plg/pluginCategory.ts +40 -2
- package/src/host/browserModuleHarness.js +8 -0
- package/src/host/wasiThreadHost.js +189 -14
- package/src/index.d.ts +18 -1
- package/src/testing/isomorphicHarness.js +233 -0
- package/src/transport/index.js +16 -0
- package/src/transport/records.js +1015 -3
|
@@ -0,0 +1,503 @@
|
|
|
1
|
+
<!doctype html>
|
|
2
|
+
<html lang="en">
|
|
3
|
+
<head>
|
|
4
|
+
<meta charset="utf-8" />
|
|
5
|
+
<meta name="viewport" content="width=device-width, initial-scale=1" />
|
|
6
|
+
<meta name="description" content="This document defines how a compliant Space Data module is published through the" />
|
|
7
|
+
<title>Module publication standard — Space Data Module SDK</title>
|
|
8
|
+
<link rel="stylesheet" href="./styles.css" />
|
|
9
|
+
<!-- SDN_CONSUMER_ASSETS_START -->
|
|
10
|
+
<link rel="stylesheet" href="https://static.spacedatanetwork.org/assets/hd-wallet-ui/2.0.28/sdn-wallet-public-client.c3f68d1cfd88478f10d836a5e829d1dfc6a10157972cf0f7d4d319d0636f2cc4.css" integrity="sha384-fICuhN4I9xqOK1F5vGGzl26opuO+xQIvTZXMSV76lWTBiQ6AfzztMGLLDw8yRT8i" crossorigin="anonymous">
|
|
11
|
+
<script defer src="https://static.spacedatanetwork.org/assets/hd-wallet-ui/2.0.28/sdn-wallet-public-client.f611e7e151a3b5c38384272f8894a4c6634f0a29bf925b0e02e0e27f8db0bfff.js" integrity="sha384-R+QqsKoWJIS7iWrtPmgJ49DVnb1hSGjZokupbLInJd1PLp8RwQhtF/hnaerc33ci" crossorigin="anonymous" data-sdn-wallet-public-client="v1"></script>
|
|
12
|
+
<script defer src="https://static.spacedatanetwork.org/assets/sdn-stack-nav/1.0.0/sdn-stack-nav.52fde607eee38ffa116188201f50258ed50bd18c9f06c1af9678f763147a8fe5.js" integrity="sha384-dgeojhJ8vTszHXIbv7O7nZcEzqD10oUYYJjBmPrV7+kLQEUlXLQD4ek5Q7HOFiO5" crossorigin="anonymous" data-nav-style-url="https://static.spacedatanetwork.org/assets/sdn-stack-nav/1.0.0/sdn-stack-nav.36a36359ce18322185e9ff179f88175bab67d5ad84a14d9c08a54f2ff27267e7.css" data-nav-style-integrity="sha384-c4M8Fg+kYaeOYYtJVr7jJsde24IhSWkWaRyAOHEZU9jozhRck089aw+mnHwxymds" data-wallet-client-url="https://static.spacedatanetwork.org/assets/hd-wallet-ui/2.0.28/sdn-wallet-public-client.f611e7e151a3b5c38384272f8894a4c6634f0a29bf925b0e02e0e27f8db0bfff.js" data-wallet-client-integrity="sha384-R+QqsKoWJIS7iWrtPmgJ49DVnb1hSGjZokupbLInJd1PLp8RwQhtF/hnaerc33ci" data-wallet-style-url="https://static.spacedatanetwork.org/assets/hd-wallet-ui/2.0.28/sdn-wallet-public-client.c3f68d1cfd88478f10d836a5e829d1dfc6a10157972cf0f7d4d319d0636f2cc4.css" data-wallet-style-integrity="sha384-fICuhN4I9xqOK1F5vGGzl26opuO+xQIvTZXMSV76lWTBiQ6AfzztMGLLDw8yRT8i" data-wallet-client-id="sdn-module-sdk-pages-v1" data-wallet-callback-uri="https://digitalarsenal.github.io/space-data-module-sdk/wallet-callback.html" data-wallet-registry-sha256="e1ce6fe903c9700484a8a87d96581c8cad97063dabf63030b4518a31a3bdaa93"></script>
|
|
13
|
+
<!-- SDN_CONSUMER_ASSETS_END -->
|
|
14
|
+
</head>
|
|
15
|
+
<body>
|
|
16
|
+
<a class="skip-link" href="#main">Skip to content</a>
|
|
17
|
+
<sdn-stack-nav active="module-sdk"></sdn-stack-nav>
|
|
18
|
+
<header class="site-header">
|
|
19
|
+
<a class="site-brand" href="./">Space Data Module SDK</a>
|
|
20
|
+
<nav class="header-links" aria-label="Site">
|
|
21
|
+
<a href="./byo-wasm-quickstart.html">Quickstart</a>
|
|
22
|
+
<a href="./conformance.html">Conformance</a>
|
|
23
|
+
<a href="https://github.com/DigitalArsenal/space-data-module-sdk">GitHub</a>
|
|
24
|
+
<a class="stack-button" href="#stack">Stack</a>
|
|
25
|
+
</nav>
|
|
26
|
+
</header>
|
|
27
|
+
<div class="shell">
|
|
28
|
+
<nav class="sidebar" id="sidebar" aria-label="Documentation">
|
|
29
|
+
<h2>Start here</h2><ul>
|
|
30
|
+
<li><a href="./index.html"><span>Harness family matrix</span></a></li>
|
|
31
|
+
<li><a href="./byo-wasm-quickstart.html"><span>BYO-wasm quickstart</span></a></li>
|
|
32
|
+
<li><a href="./conformance.html"><span>Conformance kit</span></a></li>
|
|
33
|
+
<li><a href="./protect-and-sign.html"><span>Protect and sign</span></a></li>
|
|
34
|
+
<li><a href="./publication-submission.html"><span>Publication and listing</span></a></li>
|
|
35
|
+
</ul>
|
|
36
|
+
<h2>Dynamics</h2><ul>
|
|
37
|
+
<li><a href="./families/propagator.html"><span>Propagator</span><span class="tag tag-shipped">shipped</span></a></li>
|
|
38
|
+
<li><a href="./families/maneuver.html"><span>Maneuver</span><span class="tag tag-experimental">experimental</span></a></li>
|
|
39
|
+
<li><a href="./families/propulsion.html"><span>Propulsion</span><span class="tag tag-planned">planned</span></a></li>
|
|
40
|
+
<li><a href="./families/attitude.html"><span>Attitude</span><span class="tag tag-planned">planned</span></a></li>
|
|
41
|
+
<li><a href="./families/gnc.html"><span>GNC</span><span class="tag tag-planned">planned</span></a></li>
|
|
42
|
+
</ul>
|
|
43
|
+
<h2>Environment and interaction</h2><ul>
|
|
44
|
+
<li><a href="./families/rf.html"><span>RF</span><span class="tag tag-designed">designed</span></a></li>
|
|
45
|
+
<li><a href="./families/sensor.html"><span>Sensor</span><span class="tag tag-planned">planned</span></a></li>
|
|
46
|
+
<li><a href="./families/signature.html"><span>Signature</span><span class="tag tag-planned">planned</span></a></li>
|
|
47
|
+
<li><a href="./families/environment.html"><span>Environment</span><span class="tag tag-planned">planned</span></a></li>
|
|
48
|
+
<li><a href="./families/obstruction.html"><span>Obstruction</span><span class="tag tag-designed">designed</span></a></li>
|
|
49
|
+
</ul>
|
|
50
|
+
<h2>Event physics</h2><ul>
|
|
51
|
+
<li><a href="./families/breakup.html"><span>Breakup</span><span class="tag tag-planned">planned</span></a></li>
|
|
52
|
+
<li><a href="./families/reentry.html"><span>Reentry</span><span class="tag tag-planned">planned</span></a></li>
|
|
53
|
+
<li><a href="./families/conjunction.html"><span>Conjunction</span><span class="tag tag-designed">designed</span></a></li>
|
|
54
|
+
<li><a href="./families/effects.html"><span>Effects</span><span class="tag tag-planned">planned</span></a></li>
|
|
55
|
+
</ul>
|
|
56
|
+
<h2>Estimation, data and logic</h2><ul>
|
|
57
|
+
<li><a href="./families/estimation.html"><span>Estimation</span><span class="tag tag-experimental">experimental</span></a></li>
|
|
58
|
+
<li><a href="./families/data-source.html"><span>Data source</span><span class="tag tag-shipped">shipped</span></a></li>
|
|
59
|
+
<li><a href="./families/analytics.html"><span>Analytics</span><span class="tag tag-experimental">experimental</span></a></li>
|
|
60
|
+
<li><a href="./families/scheduler.html"><span>Scheduler</span><span class="tag tag-planned">planned</span></a></li>
|
|
61
|
+
<li><a href="./families/behavior.html"><span>Behavior</span><span class="tag tag-planned">planned</span></a></li>
|
|
62
|
+
</ul>
|
|
63
|
+
<h2>Runtime contract</h2><ul>
|
|
64
|
+
<li><a href="./events-abi.html"><span>Event locator ABI</span></a></li>
|
|
65
|
+
<li><a href="./module-publication-standard.html" aria-current="page"><span>Module publication standard</span></a></li>
|
|
66
|
+
<li><a href="./browser-wasmedge-isomorphic.html"><span>Browser / WasmEdge isomorphism</span></a></li>
|
|
67
|
+
<li><a href="./isomorphic-pthreads.html"><span>Isomorphic pthreads</span></a></li>
|
|
68
|
+
<li><a href="./tri-runtime-parity.html"><span>Tri-runtime parity</span></a></li>
|
|
69
|
+
<li><a href="./tri-runtime-parity-gate.html"><span>Tri-runtime parity gate</span></a></li>
|
|
70
|
+
<li><a href="./testing-harness.html"><span>Testing harness</span></a></li>
|
|
71
|
+
<li><a href="./language-runtime-matrix.html"><span>Language and runtime matrix</span></a></li>
|
|
72
|
+
</ul>
|
|
73
|
+
<h2>Host surfaces</h2><ul>
|
|
74
|
+
<li><a href="./flatsql-host-contract.html"><span>FlatSQL host contract</span></a></li>
|
|
75
|
+
<li><a href="./flatsql-streaming-standard.html"><span>FlatSQL streaming standard</span></a></li>
|
|
76
|
+
<li><a href="./secrets-capability.html"><span>Credential lanes</span></a></li>
|
|
77
|
+
<li><a href="./protocol-installation.html"><span>Protocol installation</span></a></li>
|
|
78
|
+
<li><a href="./gpu-module-abi.html"><span>GPU module ABI</span></a></li>
|
|
79
|
+
<li><a href="./module-bundle-runtime-plan.html"><span>Module bundle runtime</span></a></li>
|
|
80
|
+
<li><a href="./isomorphic-sdn-runtime-plan.html"><span>Isomorphic SDN runtime</span></a></li>
|
|
81
|
+
<li><a href="./node-red-default-node-parity.html"><span>Node-RED node parity</span></a></li>
|
|
82
|
+
</ul>
|
|
83
|
+
</nav>
|
|
84
|
+
<main class="doc" id="main">
|
|
85
|
+
<h1>Module publication standard</h1>
|
|
86
|
+
<p>This document defines how a compliant Space Data module is published through the language package ecosystems used around the SDK runtime surface:</p>
|
|
87
|
+
<ul>
|
|
88
|
+
<li>npm</li>
|
|
89
|
+
<li>PyPI</li>
|
|
90
|
+
<li>Maven Central</li>
|
|
91
|
+
<li>NuGet</li>
|
|
92
|
+
<li>Go modules</li>
|
|
93
|
+
<li>crates.io</li>
|
|
94
|
+
<li>Swift Package Manager</li>
|
|
95
|
+
</ul>
|
|
96
|
+
<p>The goal is simple: a loader should be able to inspect a package, locate the module artifact, and determine whether signatures or encrypted transport metadata are appended as SDS publication records in the module delivery file or shipped as sidecar FlatBuffers.</p>
|
|
97
|
+
<h2 id="scope"><a class="anchor" href="#scope" aria-hidden="true">#</a>Scope</h2>
|
|
98
|
+
<p>This publication standard covers two release modes:</p>
|
|
99
|
+
<ul>
|
|
100
|
+
<li><code>standalone</code>: the package's primary deliverable is the SDN module itself</li>
|
|
101
|
+
<li><code>attached</code>: the package primarily exists for another language runtime, but it also ships one compliant SDN module build artifact</li>
|
|
102
|
+
</ul>
|
|
103
|
+
<p>In both cases the module artifact remains the same canonical format already defined by this repo:</p>
|
|
104
|
+
<ul>
|
|
105
|
+
<li>a runtime payload that is valid WebAssembly bytes once any SDS publication trailer has been stripped and any encrypted delivery payload has been decrypted</li>
|
|
106
|
+
<li>embedded <code>PluginManifest.fbs</code></li>
|
|
107
|
+
<li>manifest accessors</li>
|
|
108
|
+
<ul>
|
|
109
|
+
<li><code>plugin_get_manifest_flatbuffer</code></li>
|
|
110
|
+
<li><code>plugin_get_manifest_flatbuffer_size</code></li>
|
|
111
|
+
</ul>
|
|
112
|
+
<li>optional appended SDS <code>REC</code> trailer carrying <code>MBL</code>, <code>PNM</code>, and optional <code>ENC</code></li>
|
|
113
|
+
</ul>
|
|
114
|
+
<h2 id="core-rules"><a class="anchor" href="#core-rules" aria-hidden="true">#</a>Core Rules</h2>
|
|
115
|
+
<ol>
|
|
116
|
+
<li>A signed-only or unencrypted artifact payload before any publication trailer MUST remain valid <code>.wasm</code>.</li>
|
|
117
|
+
<li>An encrypted binary delivery file MUST be encoded as encrypted payload bytes followed by an appended SDS <code>REC</code> trailer. The bytes before the trailer are ciphertext and are not required to validate as wasm until decrypted.</li>
|
|
118
|
+
<li>If bundle, signature, or encrypted-delivery metadata are carried in the same file, they MUST be appended as an SDS <code>REC</code> trailer at the end of that file.</li>
|
|
119
|
+
<li><code>REC</code> trailers MUST carry standards-sourced <code>MBL</code> metadata plus <code>PNM</code> and optional <code>ENC</code> records where applicable.</li>
|
|
120
|
+
<li>Single-file bundle metadata MUST be read from the appended <code>REC</code> trailer, not from an in-wasm custom section.</li>
|
|
121
|
+
<li>Sidecar FlatBuffers are allowed when a package chooses not to append those metadata payloads to the module artifact.</li>
|
|
122
|
+
<li>Paths in publication metadata are package-relative, never absolute.</li>
|
|
123
|
+
</ol>
|
|
124
|
+
<h2 id="publication-record-extensions"><a class="anchor" href="#publication-record-extensions" aria-hidden="true">#</a>Publication Record Extensions</h2>
|
|
125
|
+
<p>Publication protection metadata is expressed as standards-backed FlatBuffer extensions layered on top of the canonical module artifact.</p>
|
|
126
|
+
<ul>
|
|
127
|
+
<li><code>REC.fbs</code> is the trailing collection wrapper with file identifier <code>$REC</code></li>
|
|
128
|
+
<li><code>MBL.fbs</code> is the module bundle metadata record</li>
|
|
129
|
+
<li><code>PNM.fbs</code> is the signature/publication notice record</li>
|
|
130
|
+
<li><code>ENC.fbs</code> is the encrypted-delivery record</li>
|
|
131
|
+
</ul>
|
|
132
|
+
<p>These records are not arbitrary bytes. Loaders and publishers are expected to use the generated message classes from <code>spacedatastandards.org</code> and preserve the standard file identifiers:</p>
|
|
133
|
+
<ul>
|
|
134
|
+
<li><code>REC</code> => <code>$REC</code></li>
|
|
135
|
+
<li><code>MBL</code> => <code>$MBL</code></li>
|
|
136
|
+
<li><code>PNM</code> => <code>$PNM</code></li>
|
|
137
|
+
<li><code>ENC</code> => <code>$ENC</code></li>
|
|
138
|
+
</ul>
|
|
139
|
+
<p>The runtime-facing rule stays strict:</p>
|
|
140
|
+
<ol>
|
|
141
|
+
<li>Strip or decrypt the publication layer first.</li>
|
|
142
|
+
<li>Instantiate the remaining raw wasm module.</li>
|
|
143
|
+
<li>Read the embedded <code>PluginManifest.fbs</code>.</li>
|
|
144
|
+
</ol>
|
|
145
|
+
<p><code>MBL</code>, <code>PNM</code>, and <code>ENC</code> extend publication and transport handling only. They do not change the canonical module ABI or manifest exports.</p>
|
|
146
|
+
<h2 id="protected-binary-layout"><a class="anchor" href="#protected-binary-layout" aria-hidden="true">#</a>Protected Binary Layout</h2>
|
|
147
|
+
<p>The official same-file protection layout is:</p>
|
|
148
|
+
<div class="codeblock"><div class="codeblock-head">text</div><pre><code>protected-payload-bytes || REC-flatbuffer-bytes || uint32le(REC length) || "$REC"</code></pre></div>
|
|
149
|
+
<p>For signed-only delivery, <code>protected-payload-bytes</code> are the wasm bytes. For encrypted delivery, <code>protected-payload-bytes</code> are ciphertext and the appended <code>REC</code> MUST contain an <code>ENC</code> record with the decryption parameters. Loaders MUST decrypt those ciphertext bytes before attempting wasm validation, manifest inspection, or bundle metadata parsing.</p>
|
|
150
|
+
<p>The <code>PNM</code> content identity applies to the protected payload bytes as stored in the file. For encrypted delivery this means the <code>PNM.CID</code> identifies the ciphertext payload, while the decrypted bytes remain the canonical wasm module that is passed to the runtime.</p>
|
|
151
|
+
<h3 id="pnm-digital-signature-extension"><a class="anchor" href="#pnm-digital-signature-extension" aria-hidden="true">#</a><code>PNM</code> digital-signature extension</h3>
|
|
152
|
+
<p><code>PNM</code> carries the publication notice for the module:</p>
|
|
153
|
+
<ul>
|
|
154
|
+
<li>file identity (<code>FILE_NAME</code>, <code>FILE_ID</code>)</li>
|
|
155
|
+
<li>content identity (<code>CID</code>)</li>
|
|
156
|
+
<li>publish timestamp</li>
|
|
157
|
+
<li>signature and signature-type metadata</li>
|
|
158
|
+
</ul>
|
|
159
|
+
<p>In practice this is the record a host inspects to determine what artifact was published and which signer attested to it.</p>
|
|
160
|
+
<h3 id="mbl-signature-entry-domain-separation-statementdomain"><a class="anchor" href="#mbl-signature-entry-domain-separation-statementdomain" aria-hidden="true">#</a>MBL <code>signature</code> entry — domain separation (<code>statementDomain</code>)</h3>
|
|
161
|
+
<p>The detached Ed25519 signature carried as the MBL bundle's <code>signature</code>-role entry has two forms, and the ARTIFACT chooses which one applies — never the verifier, never a policy:</p>
|
|
162
|
+
<div class="table-wrap"><table><thead><tr><th><code>statementDomain</code></th><th>signature covers</th></tr></thead><tbody><tr><td><code>SDN-MODULE-PUBLICATION-V1</code></td><td>`"SDN-MODULE-PUBLICATION-V1" \</td><td>\</td><td>0x00 \</td><td>\</td><td>sha256(portable)`</td></tr><tr><td>absent</td><td>the bare canonical module (or bundle) digest — legacy</td></tr></tbody></table></div>
|
|
163
|
+
<p><code>portable</code> is the trailer-stripped payload: the exact bytes the runtime instantiates and the node's capability policy identifies by content hash.</p>
|
|
164
|
+
<p>The domain prefix exists because the node's publisher key is the NODE key, and that one bonded key signs several unrelated kinds of statement (dataset publications, module artifacts, update SIGNALS — the advisory pub/sub nudge a publisher pushes so every install upgrades itself in place, which has a live producer — and, still reserved, update manifests). If every statement were a bare SHA-256 digest, a caller who could reach the node's signing endpoint could submit the bytes of one kind of document and staple the returned signature onto another. An ASCII domain label, a <code>NUL</code> that cannot occur inside the label, and a fixed-width 32-byte tail put each statement kind in a disjoint message space with no length ambiguity anywhere in the preimage.</p>
|
|
165
|
+
<p>The domain registry is <strong>closed</strong>: a verifier refuses any label that is not registered, and a module verifier additionally refuses any registered label other than <code>SDN-MODULE-PUBLICATION-V1</code> — so a signature minted for an update manifest or an update signal can never be replayed into a module trailer, which the shared vectors pin as <code>foreign-registered-domain</code> and <code>update-signal-domain-is-refused-for-a-module</code>. Adding a domain is a reviewed change in every implementation at once (<code>src/bundle/sigdomain.js</code> here; <code>internal/sigdomain</code> and its kubo twin in the node), never a request parameter.</p>
|
|
166
|
+
<p><code>statementDomain</code> and <code>algorithm</code> are compared after trimming <strong>Go's</strong> whitespace set (<code>unicode.IsSpace</code> / Unicode <code>White_Space</code>), which is not JavaScript's: Go trims U+0085 NEL and JS does not, JS trims U+FEFF BOM and Go does not. Either mismatch is a "loads on the node, dies in the browser" split, so both are pinned by vectors rather than left to each language's default.</p>
|
|
167
|
+
<p>Legacy artifacts that predate the field keep verifying unchanged. The forms, the preimage bytes and every refusal reason are pinned as shared cross-language vectors in <code>test/support/statement-domain-vectors.json</code>, byte-identical to the node's copies, and asserted by the JS suite and both Go suites.</p>
|
|
168
|
+
<h3 id="enc-encrypted-delivery-extension"><a class="anchor" href="#enc-encrypted-delivery-extension" aria-hidden="true">#</a><code>ENC</code> encrypted-delivery extension</h3>
|
|
169
|
+
<p><code>ENC</code> carries the decryption parameters for a transport-protected module:</p>
|
|
170
|
+
<ul>
|
|
171
|
+
<li>key exchange algorithm (<code>X25519</code>)</li>
|
|
172
|
+
<li>symmetric algorithm (<code>AES_256_GCM</code>; wire enum value <code>1</code>)</li>
|
|
173
|
+
<li>key-derivation function (<code>HKDF_SHA256</code>)</li>
|
|
174
|
+
<li>ephemeral public key</li>
|
|
175
|
+
<li>nonce start (the 12-byte AES-GCM IV)</li>
|
|
176
|
+
<li>optional context, schema hash, recipient key id, and root type</li>
|
|
177
|
+
</ul>
|
|
178
|
+
<p>Encrypted delivery is authenticated:</p>
|
|
179
|
+
<ul>
|
|
180
|
+
<li>The protected payload bytes are laid out as <code>ciphertext || 16-byte GCM tag</code> (the <code>ENC</code> schema has no dedicated tag field).</li>
|
|
181
|
+
<li>The encoded <code>ENC</code> FlatBuffer record itself is the GCM additional authenticated data (AAD), so the context, schema hash, root type, recipient key id, nonce, and ephemeral key are all bound to the ciphertext. Tampering with either the payload or the <code>ENC</code> record MUST cause decryption to fail.</li>
|
|
182
|
+
<li>Records labelled <code>AES_256_CTR</code> are rejected; the SDK neither produces nor decrypts unauthenticated CTR payloads.</li>
|
|
183
|
+
</ul>
|
|
184
|
+
<p>It describes how to decrypt the protected delivery payload. It does not imply a different module file format after decryption.</p>
|
|
185
|
+
<h2 id="aligned-binary-type-refs"><a class="anchor" href="#aligned-binary-type-refs" aria-hidden="true">#</a>Aligned-Binary Type Refs</h2>
|
|
186
|
+
<p>Aligned-binary payloads use the same schema identity as the canonical FlatBuffer payload. They are advertised through the <code>FlatBufferTypeRef</code> extension fields:</p>
|
|
187
|
+
<ul>
|
|
188
|
+
<li><code>wireFormat: "aligned-binary"</code></li>
|
|
189
|
+
<li><code>rootTypeName</code></li>
|
|
190
|
+
<li><code>byteLength</code></li>
|
|
191
|
+
<li><code>requiredAlignment</code></li>
|
|
192
|
+
</ul>
|
|
193
|
+
<p>Every aligned-binary declaration must be paired with the regular <code>wireFormat: "flatbuffer"</code> type for the same schema and file identifier in the same accepted type set. Publication protection applies to the artifact as a whole; aligned-binary is an invoke/payload optimization layered inside the manifest contract.</p>
|
|
194
|
+
<h2 id="canonical-descriptor"><a class="anchor" href="#canonical-descriptor" aria-hidden="true">#</a>Canonical Descriptor</h2>
|
|
195
|
+
<p>The canonical publication descriptor is named <code>sdn-module</code>.</p>
|
|
196
|
+
<p>When represented as a standalone JSON file, the filename is <code>sdn-module.json</code>.</p>
|
|
197
|
+
<p>The full object form is:</p>
|
|
198
|
+
<div class="codeblock"><div class="codeblock-head">json</div><pre><code>{
|
|
199
|
+
"specVersion": 1,
|
|
200
|
+
"publicationMode": "attached",
|
|
201
|
+
"module": {
|
|
202
|
+
"path": "./dist/orbit-lib.module.wasm",
|
|
203
|
+
"packaging": "sds-bundled-wasm",
|
|
204
|
+
"mediaType": "application/wasm",
|
|
205
|
+
"manifestExportSymbol": "plugin_get_manifest_flatbuffer",
|
|
206
|
+
"manifestSizeSymbol": "plugin_get_manifest_flatbuffer_size",
|
|
207
|
+
"pluginId": "com.example.orbit-lib",
|
|
208
|
+
"version": "1.2.3"
|
|
209
|
+
},
|
|
210
|
+
"artifacts": {
|
|
211
|
+
"signature": {
|
|
212
|
+
"storage": "module-trailer",
|
|
213
|
+
"schemaName": "PNM.fbs",
|
|
214
|
+
"fileIdentifier": "$PNM"
|
|
215
|
+
},
|
|
216
|
+
"transport": {
|
|
217
|
+
"storage": "module-trailer",
|
|
218
|
+
"schemaName": "ENC.fbs",
|
|
219
|
+
"fileIdentifier": "$ENC"
|
|
220
|
+
}
|
|
221
|
+
},
|
|
222
|
+
"integrity": {
|
|
223
|
+
"moduleSha256": "2bff0d3d8f4f5aa1d0c7be3e54e15f9f8c9f3a62d5f0a4e8a8d80de28f4f0b31"
|
|
224
|
+
}
|
|
225
|
+
}</code></pre></div>
|
|
226
|
+
<h3 id="required-fields"><a class="anchor" href="#required-fields" aria-hidden="true">#</a>Required Fields</h3>
|
|
227
|
+
<ul>
|
|
228
|
+
<li><code>specVersion</code>: publication spec version, currently <code>1</code></li>
|
|
229
|
+
<li><code>publicationMode</code>: <code>standalone</code> or <code>attached</code></li>
|
|
230
|
+
<li><code>module.path</code>: relative path to the <code>.wasm</code> artifact</li>
|
|
231
|
+
</ul>
|
|
232
|
+
<h3 id="recommended-module-repo-build-layout"><a class="anchor" href="#recommended-module-repo-build-layout" aria-hidden="true">#</a>Recommended Module Repo Build Layout</h3>
|
|
233
|
+
<p>When authoring a module repo before publication packaging, keep the shared compiled artifact at a stable runtime path:</p>
|
|
234
|
+
<ul>
|
|
235
|
+
<li>required: <code>dist/isomorphic/module.wasm</code></li>
|
|
236
|
+
</ul>
|
|
237
|
+
<p>If the repo also ships a browser-specific adapter or wrapper, place it beside the browser runtime path:</p>
|
|
238
|
+
<ul>
|
|
239
|
+
<li>optional: <code>dist/browser/module.js</code></li>
|
|
240
|
+
<li>optional: <code>dist/browser/module.wasm</code></li>
|
|
241
|
+
</ul>
|
|
242
|
+
<p>The publication descriptor can still point anywhere, but the SDK standard for checked-in module repos is that the exact shared browser/WasmEdge build lands at <code>dist/isomorphic/module.wasm</code>.</p>
|
|
243
|
+
<h3 id="recommended-fields"><a class="anchor" href="#recommended-fields" aria-hidden="true">#</a>Recommended Fields</h3>
|
|
244
|
+
<ul>
|
|
245
|
+
<li><code>module.packaging</code>: <code>plain-wasm</code> or <code>sds-bundled-wasm</code></li>
|
|
246
|
+
<li><code>module.mediaType</code>: normally <code>application/wasm</code></li>
|
|
247
|
+
<li><code>module.manifestExportSymbol</code></li>
|
|
248
|
+
<li><code>module.manifestSizeSymbol</code></li>
|
|
249
|
+
<li><code>module.pluginId</code></li>
|
|
250
|
+
<li><code>module.version</code></li>
|
|
251
|
+
<li><code>integrity.moduleSha256</code></li>
|
|
252
|
+
</ul>
|
|
253
|
+
<h3 id="artifact-descriptors"><a class="anchor" href="#artifact-descriptors" aria-hidden="true">#</a>Artifact Descriptors</h3>
|
|
254
|
+
<p>Each optional entry inside <code>artifacts</code> describes one metadata payload related to the module:</p>
|
|
255
|
+
<ul>
|
|
256
|
+
<li><code>authorization</code></li>
|
|
257
|
+
<li><code>signature</code></li>
|
|
258
|
+
<li><code>transport</code></li>
|
|
259
|
+
<li><code>attestation</code></li>
|
|
260
|
+
</ul>
|
|
261
|
+
<p>An artifact descriptor has this shape:</p>
|
|
262
|
+
<div class="codeblock"><div class="codeblock-head">json</div><pre><code>{
|
|
263
|
+
"storage": "module-trailer",
|
|
264
|
+
"path": "./dist/orbit-lib.signature.fb",
|
|
265
|
+
"schemaName": "PNM.fbs",
|
|
266
|
+
"fileIdentifier": "$PNM"
|
|
267
|
+
}</code></pre></div>
|
|
268
|
+
<p>Rules:</p>
|
|
269
|
+
<ul>
|
|
270
|
+
<li><code>storage</code> MUST be <code>module-trailer</code> or <code>package-file</code></li>
|
|
271
|
+
<li><code>module-trailer</code> means the loader scans the end of <code>module.path</code> for an appended <code>REC</code> trailer and resolves the matching record from there</li>
|
|
272
|
+
<li><code>path</code> MUST be present when <code>storage</code> is <code>package-file</code></li>
|
|
273
|
+
<li><code>schemaName</code> SHOULD name the SDS FlatBuffer schema</li>
|
|
274
|
+
<li><code>fileIdentifier</code> SHOULD name the FlatBuffer file identifier</li>
|
|
275
|
+
</ul>
|
|
276
|
+
<h2 id="minimal-shorthand"><a class="anchor" href="#minimal-shorthand" aria-hidden="true">#</a>Minimal Shorthand</h2>
|
|
277
|
+
<p>Package manifests that support arbitrary metadata MAY use a shorthand string when all of the following are true:</p>
|
|
278
|
+
<ul>
|
|
279
|
+
<li>the package only needs to point to one module file</li>
|
|
280
|
+
<li>the module uses the default manifest accessor exports</li>
|
|
281
|
+
<li>all signature and transport metadata are either absent or appended through a <code>REC</code> trailer</li>
|
|
282
|
+
</ul>
|
|
283
|
+
<p>Example:</p>
|
|
284
|
+
<div class="codeblock"><div class="codeblock-head">json</div><pre><code>{
|
|
285
|
+
"name": "@example/orbit-lib",
|
|
286
|
+
"version": "1.2.3",
|
|
287
|
+
"sdn-module": "./dist/orbit-lib.module.wasm"
|
|
288
|
+
}</code></pre></div>
|
|
289
|
+
<p><code>sdn-module.json</code> files MUST use the full object form, not the string shorthand.</p>
|
|
290
|
+
<h2 id="resolution-rules"><a class="anchor" href="#resolution-rules" aria-hidden="true">#</a>Resolution Rules</h2>
|
|
291
|
+
<p>A package consumer resolves publication metadata in this order:</p>
|
|
292
|
+
<ol>
|
|
293
|
+
<li>Read the ecosystem-specific <code>sdn-module</code> carrier if one exists.</li>
|
|
294
|
+
<li>If that carrier is a string, treat it as <code>module.path</code>.</li>
|
|
295
|
+
<li>If that carrier is an object, use it directly.</li>
|
|
296
|
+
<li>If the package has no inline carrier, look for <code>sdn-module.json</code>.</li>
|
|
297
|
+
<li>For JVM artifacts, also look for <code>META-INF/sdn-module.json</code>.</li>
|
|
298
|
+
<li>Resolve <code>module.path</code> and any <code>package-file</code> sidecars relative to the package root or archive root.</li>
|
|
299
|
+
</ol>
|
|
300
|
+
<h2 id="packaging-by-ecosystem"><a class="anchor" href="#packaging-by-ecosystem" aria-hidden="true">#</a>Packaging By Ecosystem</h2>
|
|
301
|
+
<div class="table-wrap"><table><thead><tr><th>Ecosystem</th><th>Recommended carrier</th></tr></thead><tbody><tr><td>npm</td><td><code>package.json["sdn-module"]</code></td></tr><tr><td>PyPI</td><td><code>pyproject.toml [tool."sdn-module"]</code></td></tr><tr><td>crates.io</td><td><code>Cargo.toml [package.metadata."sdn-module"]</code></td></tr><tr><td>Maven Central</td><td><code>META-INF/sdn-module.json</code> inside the JAR, optionally mirrored by a POM property</td></tr><tr><td>NuGet</td><td><code>sdn-module.json</code> at package root, optionally surfaced through build metadata</td></tr><tr><td>Go modules</td><td><code>sdn-module.json</code> at module root</td></tr><tr><td>Swift Package Manager</td><td><code>sdn-module.json</code> at package root</td></tr></tbody></table></div>
|
|
302
|
+
<h3 id="npm"><a class="anchor" href="#npm" aria-hidden="true">#</a>npm</h3>
|
|
303
|
+
<p>Minimal attached example:</p>
|
|
304
|
+
<div class="codeblock"><div class="codeblock-head">json</div><pre><code>{
|
|
305
|
+
"name": "@example/orbit-lib",
|
|
306
|
+
"version": "1.2.3",
|
|
307
|
+
"sdn-module": "./dist/orbit-lib.module.wasm"
|
|
308
|
+
}</code></pre></div>
|
|
309
|
+
<p>Full example:</p>
|
|
310
|
+
<div class="codeblock"><div class="codeblock-head">json</div><pre><code>{
|
|
311
|
+
"name": "@example/orbit-lib",
|
|
312
|
+
"version": "1.2.3",
|
|
313
|
+
"sdn-module": {
|
|
314
|
+
"specVersion": 1,
|
|
315
|
+
"publicationMode": "attached",
|
|
316
|
+
"module": {
|
|
317
|
+
"path": "./dist/orbit-lib.module.wasm",
|
|
318
|
+
"packaging": "sds-bundled-wasm",
|
|
319
|
+
"mediaType": "application/wasm",
|
|
320
|
+
"manifestExportSymbol": "plugin_get_manifest_flatbuffer",
|
|
321
|
+
"manifestSizeSymbol": "plugin_get_manifest_flatbuffer_size"
|
|
322
|
+
}
|
|
323
|
+
}
|
|
324
|
+
}</code></pre></div>
|
|
325
|
+
<h3 id="pypi"><a class="anchor" href="#pypi" aria-hidden="true">#</a>PyPI</h3>
|
|
326
|
+
<div class="codeblock"><div class="codeblock-head">toml</div><pre><code>[tool."sdn-module"]
|
|
327
|
+
specVersion = 1
|
|
328
|
+
publicationMode = "attached"
|
|
329
|
+
|
|
330
|
+
[tool."sdn-module".module]
|
|
331
|
+
path = "./dist/orbit-lib.module.wasm"
|
|
332
|
+
packaging = "sds-bundled-wasm"
|
|
333
|
+
mediaType = "application/wasm"
|
|
334
|
+
manifestExportSymbol = "plugin_get_manifest_flatbuffer"
|
|
335
|
+
manifestSizeSymbol = "plugin_get_manifest_flatbuffer_size"</code></pre></div>
|
|
336
|
+
<h3 id="cratesio"><a class="anchor" href="#cratesio" aria-hidden="true">#</a>crates.io</h3>
|
|
337
|
+
<div class="codeblock"><div class="codeblock-head">toml</div><pre><code>[package.metadata."sdn-module"]
|
|
338
|
+
specVersion = 1
|
|
339
|
+
publicationMode = "attached"
|
|
340
|
+
|
|
341
|
+
[package.metadata."sdn-module".module]
|
|
342
|
+
path = "./dist/orbit-lib.module.wasm"
|
|
343
|
+
packaging = "sds-bundled-wasm"
|
|
344
|
+
mediaType = "application/wasm"
|
|
345
|
+
manifestExportSymbol = "plugin_get_manifest_flatbuffer"
|
|
346
|
+
manifestSizeSymbol = "plugin_get_manifest_flatbuffer_size"</code></pre></div>
|
|
347
|
+
<h3 id="maven-central-and-kotlin"><a class="anchor" href="#maven-central-and-kotlin" aria-hidden="true">#</a>Maven Central And Kotlin</h3>
|
|
348
|
+
<p>Ship a JSON descriptor in the archive:</p>
|
|
349
|
+
<div class="codeblock"><div class="codeblock-head">text</div><pre><code>src/main/resources/META-INF/sdn-module.json</code></pre></div>
|
|
350
|
+
<p>Optional POM property:</p>
|
|
351
|
+
<div class="codeblock"><div class="codeblock-head">xml</div><pre><code><properties>
|
|
352
|
+
<sdn.module.descriptor>META-INF/sdn-module.json</sdn.module.descriptor>
|
|
353
|
+
</properties></code></pre></div>
|
|
354
|
+
<h3 id="nuget"><a class="anchor" href="#nuget" aria-hidden="true">#</a>NuGet</h3>
|
|
355
|
+
<p>Ship the descriptor at package root:</p>
|
|
356
|
+
<div class="codeblock"><div class="codeblock-head">text</div><pre><code>sdn-module.json</code></pre></div>
|
|
357
|
+
<p>The <code>.nupkg</code> should also contain the module artifact at the relative path named by <code>module.path</code>.</p>
|
|
358
|
+
<h3 id="go-modules"><a class="anchor" href="#go-modules" aria-hidden="true">#</a>Go Modules</h3>
|
|
359
|
+
<p>Ship <code>sdn-module.json</code> at the module root next to <code>go.mod</code>.</p>
|
|
360
|
+
<h3 id="swift-package-manager"><a class="anchor" href="#swift-package-manager" aria-hidden="true">#</a>Swift Package Manager</h3>
|
|
361
|
+
<p>Ship <code>sdn-module.json</code> at the package root. If the module artifact must be available through a target at runtime, include the <code>.wasm</code> and sidecar files as resources or through a binary-target wrapper.</p>
|
|
362
|
+
<h2 id="standalone-publication-example"><a class="anchor" href="#standalone-publication-example" aria-hidden="true">#</a>Standalone Publication Example</h2>
|
|
363
|
+
<p><code>sdn-module.json</code></p>
|
|
364
|
+
<div class="codeblock"><div class="codeblock-head">json</div><pre><code>{
|
|
365
|
+
"specVersion": 1,
|
|
366
|
+
"publicationMode": "standalone",
|
|
367
|
+
"module": {
|
|
368
|
+
"path": "./dist/catalog-query.bundle.wasm",
|
|
369
|
+
"packaging": "sds-bundled-wasm",
|
|
370
|
+
"mediaType": "application/wasm",
|
|
371
|
+
"manifestExportSymbol": "plugin_get_manifest_flatbuffer",
|
|
372
|
+
"manifestSizeSymbol": "plugin_get_manifest_flatbuffer_size",
|
|
373
|
+
"pluginId": "org.example.catalog-query",
|
|
374
|
+
"version": "0.2.0"
|
|
375
|
+
},
|
|
376
|
+
"artifacts": {
|
|
377
|
+
"signature": {
|
|
378
|
+
"storage": "module-trailer",
|
|
379
|
+
"schemaName": "PNM.fbs",
|
|
380
|
+
"fileIdentifier": "$PNM"
|
|
381
|
+
}
|
|
382
|
+
}
|
|
383
|
+
}</code></pre></div>
|
|
384
|
+
<h2 id="attached-publication-example"><a class="anchor" href="#attached-publication-example" aria-hidden="true">#</a>Attached Publication Example</h2>
|
|
385
|
+
<p><code>sdn-module.json</code></p>
|
|
386
|
+
<div class="codeblock"><div class="codeblock-head">json</div><pre><code>{
|
|
387
|
+
"specVersion": 1,
|
|
388
|
+
"publicationMode": "attached",
|
|
389
|
+
"module": {
|
|
390
|
+
"path": "./dist/orbit-lib.module.wasm",
|
|
391
|
+
"packaging": "plain-wasm",
|
|
392
|
+
"mediaType": "application/wasm",
|
|
393
|
+
"manifestExportSymbol": "plugin_get_manifest_flatbuffer",
|
|
394
|
+
"manifestSizeSymbol": "plugin_get_manifest_flatbuffer_size",
|
|
395
|
+
"pluginId": "com.example.orbit-lib",
|
|
396
|
+
"version": "1.2.3"
|
|
397
|
+
},
|
|
398
|
+
"artifacts": {
|
|
399
|
+
"signature": {
|
|
400
|
+
"storage": "package-file",
|
|
401
|
+
"path": "./dist/orbit-lib.signature.fb",
|
|
402
|
+
"schemaName": "PNM.fbs",
|
|
403
|
+
"fileIdentifier": "$PNM"
|
|
404
|
+
},
|
|
405
|
+
"transport": {
|
|
406
|
+
"storage": "package-file",
|
|
407
|
+
"path": "./dist/orbit-lib.transport.fb",
|
|
408
|
+
"schemaName": "ENC.fbs",
|
|
409
|
+
"fileIdentifier": "$ENC"
|
|
410
|
+
}
|
|
411
|
+
}
|
|
412
|
+
}</code></pre></div>
|
|
413
|
+
<h2 id="loader-expectations"><a class="anchor" href="#loader-expectations" aria-hidden="true">#</a>Loader Expectations</h2>
|
|
414
|
+
<p>A loader consuming this standard SHOULD:</p>
|
|
415
|
+
<ol>
|
|
416
|
+
<li>locate the publication descriptor</li>
|
|
417
|
+
<li>read <code>module.path</code></li>
|
|
418
|
+
<li>scan the artifact from the end for an appended SDS <code>REC</code> trailer</li>
|
|
419
|
+
<li>resolve <code>PNM</code> / <code>ENC</code> from that trailer before runtime startup</li>
|
|
420
|
+
<li>if <code>ENC</code> is present, decrypt the protected payload bytes before passing bytes to WasmEdge or any other runtime</li>
|
|
421
|
+
<li>if <code>ENC</code> is absent, strip the trailer and use the remaining wasm payload</li>
|
|
422
|
+
<li>inspect the parsed <code>REC</code> trailer for <code>MBL</code></li>
|
|
423
|
+
<li>resolve any <code>package-file</code> metadata through relative paths</li>
|
|
424
|
+
<li>validate manifest exports and any declared integrity hashes</li>
|
|
425
|
+
</ol>
|
|
426
|
+
<p>If <code>module.packaging</code> is <code>sds-bundled-wasm</code>, loaders SHOULD treat the decrypted or stripped wasm payload as the runtime artifact and the appended <code>REC</code> trailer as the single-file bundle/publication metadata container.</p>
|
|
427
|
+
<h2 id="relationship-to-existing-bundle-format"><a class="anchor" href="#relationship-to-existing-bundle-format" aria-hidden="true">#</a>Relationship To Existing Bundle Format</h2>
|
|
428
|
+
<p>This standard uses the appended <code>REC</code> trailer as the single-file publication container. It explains how a package publishes and points to the module artifact plus any appended SDS publication trailer.</p>
|
|
429
|
+
<ul>
|
|
430
|
+
<li><code>REC</code> stays the appended single-file/publication record container</li>
|
|
431
|
+
<li><code>MBL</code> carries bundle metadata inside that trailer</li>
|
|
432
|
+
<li><code>sdn-module</code> is the package-discovery descriptor</li>
|
|
433
|
+
</ul>
|
|
434
|
+
<p>Use the appended <code>REC</code> trailer when you want one self-describing protected artifact. Use <code>sdn-module</code> when you want package managers and loaders to discover that file reliably.</p>
|
|
435
|
+
|
|
436
|
+
<p class="doc-footer">
|
|
437
|
+
Source of truth for this page:
|
|
438
|
+
<code>docs/module-publication-standard.md</code>. Regenerate with
|
|
439
|
+
<code>npm run build:docs</code>.
|
|
440
|
+
</p>
|
|
441
|
+
</main>
|
|
442
|
+
<nav class="rail" aria-label="On this page"><h2>On this page</h2><ul><li><a class="depth-2" href="#scope">Scope</a></li>
|
|
443
|
+
<li><a class="depth-2" href="#core-rules">Core Rules</a></li>
|
|
444
|
+
<li><a class="depth-2" href="#publication-record-extensions">Publication Record Extensions</a></li>
|
|
445
|
+
<li><a class="depth-2" href="#protected-binary-layout">Protected Binary Layout</a></li>
|
|
446
|
+
<li><a class="depth-3" href="#pnm-digital-signature-extension"><code>PNM</code> digital-signature extension</a></li>
|
|
447
|
+
<li><a class="depth-3" href="#mbl-signature-entry-domain-separation-statementdomain">MBL <code>signature</code> entry — domain separation (<code>statementDomain</code>)</a></li>
|
|
448
|
+
<li><a class="depth-3" href="#enc-encrypted-delivery-extension"><code>ENC</code> encrypted-delivery extension</a></li>
|
|
449
|
+
<li><a class="depth-2" href="#aligned-binary-type-refs">Aligned-Binary Type Refs</a></li>
|
|
450
|
+
<li><a class="depth-2" href="#canonical-descriptor">Canonical Descriptor</a></li>
|
|
451
|
+
<li><a class="depth-3" href="#required-fields">Required Fields</a></li>
|
|
452
|
+
<li><a class="depth-3" href="#recommended-module-repo-build-layout">Recommended Module Repo Build Layout</a></li>
|
|
453
|
+
<li><a class="depth-3" href="#recommended-fields">Recommended Fields</a></li>
|
|
454
|
+
<li><a class="depth-3" href="#artifact-descriptors">Artifact Descriptors</a></li>
|
|
455
|
+
<li><a class="depth-2" href="#minimal-shorthand">Minimal Shorthand</a></li>
|
|
456
|
+
<li><a class="depth-2" href="#resolution-rules">Resolution Rules</a></li>
|
|
457
|
+
<li><a class="depth-2" href="#packaging-by-ecosystem">Packaging By Ecosystem</a></li>
|
|
458
|
+
<li><a class="depth-3" href="#npm">npm</a></li>
|
|
459
|
+
<li><a class="depth-3" href="#pypi">PyPI</a></li>
|
|
460
|
+
<li><a class="depth-3" href="#cratesio">crates.io</a></li>
|
|
461
|
+
<li><a class="depth-3" href="#maven-central-and-kotlin">Maven Central And Kotlin</a></li>
|
|
462
|
+
<li><a class="depth-3" href="#nuget">NuGet</a></li>
|
|
463
|
+
<li><a class="depth-3" href="#go-modules">Go Modules</a></li>
|
|
464
|
+
<li><a class="depth-3" href="#swift-package-manager">Swift Package Manager</a></li>
|
|
465
|
+
<li><a class="depth-2" href="#standalone-publication-example">Standalone Publication Example</a></li>
|
|
466
|
+
<li><a class="depth-2" href="#attached-publication-example">Attached Publication Example</a></li>
|
|
467
|
+
<li><a class="depth-2" href="#loader-expectations">Loader Expectations</a></li>
|
|
468
|
+
<li><a class="depth-2" href="#relationship-to-existing-bundle-format">Relationship To Existing Bundle Format</a></li></ul></nav>
|
|
469
|
+
</div>
|
|
470
|
+
<section id="stack" class="section" aria-labelledby="stack-title">
|
|
471
|
+
<div class="section-head">
|
|
472
|
+
<p class="eyebrow">SDN Stack</p>
|
|
473
|
+
<h2 id="stack-title">Connected sites</h2>
|
|
474
|
+
</div>
|
|
475
|
+
<div class="link-list">
|
|
476
|
+
<a href="https://spacedatastandards.org/">
|
|
477
|
+
<span>Standards</span>
|
|
478
|
+
<small>Canonical schemas, record contracts, and generated bindings.</small>
|
|
479
|
+
</a>
|
|
480
|
+
<a href="https://digitalarsenal.github.io/flatbuffers/">
|
|
481
|
+
<span>FlatBuffers</span>
|
|
482
|
+
<small>Binary encoding, schema tooling, and runtime documentation.</small>
|
|
483
|
+
</a>
|
|
484
|
+
<a href="https://digitalarsenal.github.io/flatsql/">
|
|
485
|
+
<span>FlatSQL</span>
|
|
486
|
+
<small>SQL-style queries over FlatBuffer-backed datasets and streams.</small>
|
|
487
|
+
</a>
|
|
488
|
+
<a href="https://spacedatanetwork.org/">
|
|
489
|
+
<span>SDN</span>
|
|
490
|
+
<small>Distributed publication, discovery, delivery, and marketplace infrastructure.</small>
|
|
491
|
+
</a>
|
|
492
|
+
<a href="https://digitalarsenal.github.io/space-data-module-sdk/" class="active">
|
|
493
|
+
<span>Module SDK</span>
|
|
494
|
+
<small>WASM module packaging, validation, and host compatibility tooling.</small>
|
|
495
|
+
</a>
|
|
496
|
+
</div>
|
|
497
|
+
</section>
|
|
498
|
+
<footer class="site-footer">
|
|
499
|
+
Space Data Module SDK — Apache-2.0. Every ABI page renders a Markdown
|
|
500
|
+
source in <code>docs/</code>; edit the Markdown, never the HTML.
|
|
501
|
+
</footer>
|
|
502
|
+
</body>
|
|
503
|
+
</html>
|