space-data-module-sdk 0.8.4 → 0.8.5

package/docs/protocol-installation.md

@@ -0,0 +1,196 @@
+# Protocol Installation Metadata
+
+This SDK now separates protocol identity from deployment-time routing.
+
+That split matters because module artifacts are portable, compiled, and
+signable, while deployment endpoints are environment-specific.
+
+## Canonical Manifest
+
+Hosted protocol declarations belong in `manifest.protocols`.
+
+Those declarations describe what a module can host or dial:
+
+- `protocolId`
+- `methodId`
+- `inputPortId`
+- `outputPortId`
+- `wireId`
+- `transportKind`
+- `role`
+- `specUri`
+- `autoInstall`
+- `advertise`
+- `discoveryKey`
+- `defaultPort`
+- `requireSecureTransport`
+
+These fields are embedded in the compiled `PluginManifest.fbs` bytes and are
+part of the canonical module contract.
+
+## Deployment Metadata
+
+Concrete deployment routing does **not** belong in the canonical manifest.
+
+Examples:
+
+- concrete multiaddrs
+- resolved listen ports
+- selected peer IDs
+- deployment URLs
+- interface-keyed input bindings
+- scheduler bindings
+- hosted service bindings
+- request-time auth policy
+- publication, pinning, retention, and archive policy
+
+Those values vary per environment and should not change the identity of a
+signed `.wasm` artifact.
+
+Instead, attach them as a deployment-plan payload inside the bundle `MBL`
+record carried by the appended `REC` trailer.
+
+Deployment plans should use `protocolId` as the required identifier for a
+resolved protocol installation. `wireId` is optional deployment metadata for
+legacy transports that still expose it, not a required routing key.
+
+Deployment input and publication bindings should reference
+`manifest.externalInterfaces[].interfaceId`. That keeps deployment routing tied
+to the declared module contract instead of transport-specific `topic` or
+`wireId` hints.
+
+The standard bundle entry is:
+
+- `entryId`: `deployment-plan`
+- `sectionName`: `sds.deployment`
+- `payloadEncoding`: `json-utf8`
+- `mediaType`: `application/vnd.space-data.module.deployment+json`
+
+## Public Helpers
+
+Use `space-data-module-sdk/deployment` to work with that payload:
+
+- `normalizeDeploymentPlan(...)`
+- `validateDeploymentPlan(...)`
+- `createDeploymentPlanBundleEntry(...)`
+- `findDeploymentPlanEntry(...)`
+- `readDeploymentPlanFromBundle(...)`
+
+## Example Manifest Protocol
+
+```json
+{
+  "protocols": [
+    {
+      "protocolId": "sgp4-stream",
+      "methodId": "propagate",
+      "inputPortId": "request",
+      "outputPortId": "state",
+      "wireId": "/sdn/sgp4/1.0.0",
+      "transportKind": "libp2p",
+      "role": "handle",
+      "specUri": "https://spacedatastandards.org/#/schemas/PNM",
+      "autoInstall": true,
+      "advertise": true,
+      "discoveryKey": "sgp4-stream",
+      "defaultPort": 443,
+      "requireSecureTransport": true
+    }
+  ]
+}
+```
+
+## Example Deployment Plan
+
+```json
+{
+  "formatVersion": 1,
+  "pluginId": "com.example.sgp4",
+  "version": "1.2.3",
+  "protocolInstallations": [
+    {
+      "protocolId": "sgp4-stream",
+      "transportKind": "libp2p",
+      "role": "handle",
+      "peerId": "12D3KooW...",
+      "listenMultiaddrs": [
+        "/ip4/127.0.0.1/tcp/14080/ws/p2p/12D3KooW..."
+      ],
+      "advertisedMultiaddrs": [
+        "/dns4/sgp4.example.test/tcp/443/wss/p2p/12D3KooW..."
+      ],
+      "nodeInfoUrl": "https://sgp4.example.test/api/node/info"
+    }
+  ],
+  "inputBindings": [
+    {
+      "bindingId": "catalog-feed",
+      "interfaceId": "catalog-pubsub",
+      "targetMethodId": "propagate",
+      "targetInputPortId": "request",
+      "sourceKind": "pubsub"
+    }
+  ],
+  "scheduleBindings": [
+    {
+      "scheduleId": "poll-upstream",
+      "bindingMode": "local",
+      "targetMethodId": "propagate",
+      "targetInputPortId": "request",
+      "scheduleKind": "cron",
+      "cron": "*/15 * * * *"
+    }
+  ],
+  "serviceBindings": [
+    {
+      "serviceId": "https-query",
+      "bindingMode": "delegated",
+      "serviceKind": "http-server",
+      "routePath": "/api/sgp4",
+      "method": "GET",
+      "remoteUrl": "https://gateway.example.test/api/sgp4",
+      "authPolicyId": "approved-keys"
+    }
+  ],
+  "authPolicies": [
+    {
+      "policyId": "approved-keys",
+      "bindingMode": "delegated",
+      "targetKind": "service",
+      "targetId": "https-query",
+      "walletProfileId": "orbpro-default",
+      "trustMapId": "approved-operators",
+      "allowServerKeys": ["ed25519:..."]
+    }
+  ],
+  "publicationBindings": [
+    {
+      "publicationId": "state-catalog",
+      "interfaceId": "state-catalog-pubsub",
+      "bindingMode": "local",
+      "sourceKind": "method-output",
+      "sourceMethodId": "propagate",
+      "sourceOutputPortId": "state",
+      "schemaName": "CAT.fbs",
+      "emitPnm": true,
+      "emitFlatbufferArchive": true,
+      "archivePath": "/data/catalog/cat.bin",
+      "queryInterfaceId": "state-query-api",
+      "recordRangeStartField": "startIndex",
+      "recordRangeStopField": "stopIndex"
+    }
+  ]
+}
+```
+
+## Identity Rules
+
+- `wireId` identifies the network protocol.
+- `specUri` identifies the message or schema contract.
+- multiaddrs identify one deployment instance of that protocol.
+- `interfaceId` identifies the declared module boundary used by deployment
+  input/publication bindings.
+- deployment plans should resolve installed protocol surfaces by `protocolId`;
+  include `wireId` only when a host integration still needs that legacy hint.
+
+Do not treat those as interchangeable.

package/docs/secrets-capability.md

@@ -0,0 +1,152 @@
+# Credential Lanes — the `secrets` Capability
+
+A module often needs an operator's third-party credential: a Space-Track login,
+a data-provider API password, an account at whatever service the operator uses.
+The `secrets` capability is how that credential reaches the module **without the
+credential ever living in the module, the manifest, the flow, or a record**.
+
+The operator enters the credential once on their node. The node seals it at rest
+under its own key material. A module the operator has explicitly approved can
+then read exactly that one credential at runtime.
+
+This document is normative for module authors. The guest-side helper is
+[`src/host/cpp/secretsClient.hpp`](../src/host/cpp/secretsClient.hpp); the
+reference host implementation is `sdn-server/internal/modulert/caps/secrets.go`.
+
+## Lanes
+
+A **lane** is a named credential slot on the node — `spacetrack`,
+`acme-weather`, `zephyr_billing`. Lane ids are lowercase
+`[a-z0-9_-]{2,64}`.
+
+**Lanes are operator-defined.** A few are well-known (`spacetrack`, `edc_cpf`,
+`myintelsat`) because the node ships a verifier that can probe them, but an
+operator may create a lane for any service at all. Do not hard-code an
+assumption that a fixed set exists:
+
+- Take the lane id as **module configuration**, not as a compile-time constant,
+  so an operator can point your module at their own lane.
+- Treat "not configured" as a **normal runtime state**, not an error condition
+  that should crash a run.
+- A lane may be permanently **unverified**. The node cannot probe a service it
+  knows nothing about, so `verified_at` stays empty forever for most
+  operator-defined lanes. That is honest, not broken.
+
+## The approval contract
+
+Reading a credential requires **two** things, and neither is something your
+module can arrange for itself.
+
+1. **Declare the capability.** Add `secrets:<lane>` to your manifest's
+   `capabilities` for each lane you read. `secrets:spacetrack` conveys nothing
+   about `secrets:edc_cpf`: the host re-checks the exact lane on **every call**,
+   so a module holding one lane's grant is refused on every other lane.
+
+2. **The operator approves your module's content hash.** Every `secrets:*`
+   capability is *sensitive*. The operator records an approval for your module's
+   exact SHA-256 content hash, for that exact lane, in the node's
+   `capability_policy.json`. Without it the module is **denied at load** — the
+   whole module fails to load, not just the call.
+
+   Recompiling changes the hash and therefore **revokes** the approval. That is
+   deliberate: the approval is for the bytes the operator reviewed, not for a
+   name.
+
+There is **no enumeration**. There is no `secrets.list` and no `secrets.export`.
+A guest can ask for a lane it is already approved for and nothing else; it can
+never discover which credentials the node holds. Do not probe lane names.
+
+## Handling the plaintext
+
+`secrets.get` returns the credential **in the clear**, in your linear memory.
+There is no way around that — the module's job is to present the password to the
+provider's own login, so the secret *is* the message. Once it crosses the
+boundary the host cannot protect it further, and these rules are yours to keep:
+
+- **Never log it.** Not in an error message, not in a trace, not in a progress
+  event, not at debug level.
+- **Never persist it.** Not through `storage.write`, not to the filesystem, not
+  into a record, not into a cache that outlives the call.
+- **Never forward it** anywhere except the provider it belongs to.
+- **Wipe it** as soon as the provider call is done, on success *and* failure
+  paths, and keep its lifetime as short as you can.
+
+If your module also holds `http`, it is technically capable of exfiltrating the
+credential. The operator's approval is precisely the decision to trust it not
+to. Honor that.
+
+## Minimal usage
+
+```cpp
+#include "sdm_hostcall_wire.hpp"   // must be included first
+#include "secretsClient.hpp"
+
+// The lane comes from module configuration — never assume "spacetrack".
+bool fetch_provider_data(const std::string& lane) {
+  sdm_secrets::Credential cred;
+  if (!sdm_secrets::secrets_get(lane, &cred)) {
+    // Not approved for this lane, or the operator has not entered it yet.
+    // Report the CONDITION, never the lane's contents.
+    log_error("provider credential unavailable");
+    return false;
+  }
+
+  const bool ok = provider_login(cred.username, cred.secret);
+  sdm_secrets::wipe(&cred);   // on every path, including this failure one
+  return ok;
+}
+```
+
+Manifest:
+
+```json
+{
+  "pluginId": "com.example.provider-fetch",
+  "capabilities": ["http", "secrets:acme-weather"]
+}
+```
+
+To decide whether a fetch is worth attempting without touching the plaintext:
+
+```cpp
+sdm_secrets::Status status;
+if (sdm_secrets::secrets_status(lane, &status) && status.configured) {
+  // A credential is present. status.username_masked is safe to show an
+  // operator ("o***@acme.example"); status.verified_at is EMPTY when the node
+  // has never probed it, which is normal for an operator-defined lane.
+}
+```
+
+`secrets_status` is gated by the **same** per-lane capability, so an unapproved
+module cannot use it to probe which credentials a node holds.
+
+## Wire shapes
+
+Both operations are plain JSON meta documents; neither uses binary segments.
+
+```
+secrets.get     -> {"id":"<lane>"}
+                <- {"ok":true,"result":{"id":"...","username":"...","secret":"..."}}
+
+secrets.status  -> {"id":"<lane>"}
+                <- {"ok":true,"result":{"id":"...","configured":true,
+                     "username_masked":"o***@example.com",
+                     "updated_at":"...","verified_at":"..."}}
+```
+
+A refusal — unapproved lane, unconfigured credential, no keystore on this node —
+comes back as `{"ok":false,...}` and **never** carries credential material. Both
+helpers return `false` in that case and leave their output parameter untouched.
+A `false` return never means "empty credential"; it means no credential was
+obtained.
+
+## Failure modes worth expecting
+
+| Situation | What you see |
+|---|---|
+| Capability not declared in the manifest | Refused per call (`ok:false`) |
+| Declared but not approved by the operator | **Module denied at load** |
+| Approved for a different lane | Refused per call (`ok:false`) |
+| Lane exists but the operator has not filled it in | `secrets_get` false; `secrets_status` `configured:false` |
+| Lane has no verifier on this node | `verified_at` empty — normal, not an error |
+| Node has no credential keystore | Refused per call (`ok:false`) |

package/docs/styles.css

@@ -0,0 +1,288 @@
+:root {
+  color-scheme: dark;
+  --bg: #05070a;
+  --surface: rgba(15, 19, 25, 0.82);
+  --surface-strong: rgba(22, 27, 35, 0.92);
+  --line: rgba(255, 255, 255, 0.12);
+  --line-strong: rgba(255, 255, 255, 0.2);
+  --text: #f5f5f7;
+  --muted: #a1a1aa;
+  --subtle: #747782;
+  --blue: #58a6ff;
+  --green: #42d392;
+  --amber: #f2cc60;
+  --sdn-stack-footer-height: 40px;
+  --sdn-stack-header-height: 52px;
+  --sdn-stack-header-brand-size: 15px;
+  --sdn-stack-header-link-size: 14px;
+  --sdn-stack-header-action-size: 13px;
+  --sdn-stack-header-mobile-link-size: 16px;
+  font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+}
+
+* {
+  box-sizing: border-box;
+}
+
+body {
+  margin: 0;
+  min-height: 100vh;
+  background:
+    radial-gradient(circle at 16% 18%, rgba(88, 166, 255, 0.16), transparent 30rem),
+    radial-gradient(circle at 84% 20%, rgba(66, 211, 146, 0.12), transparent 28rem),
+    linear-gradient(180deg, rgba(255, 255, 255, 0.035), transparent 20rem),
+    var(--bg);
+  color: var(--text);
+}
+
+a {
+  color: inherit;
+  text-decoration: none;
+}
+
+.site-header {
+  position: fixed;
+  top: 0;
+  left: 0;
+  right: 0;
+  z-index: 1000;
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  height: var(--sdn-stack-header-height, 52px);
+  padding: 0 max(16px, calc((100vw - 1180px) / 2));
+  border-bottom: 1px solid var(--line);
+  background: rgba(5, 7, 10, 0.88);
+  backdrop-filter: blur(18px);
+}
+
+.site-brand {
+  color: var(--text);
+  font-size: var(--sdn-stack-header-brand-size, 15px);
+  font-weight: 800;
+}
+
+.stack-button {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  min-height: 30px;
+  padding: 0 14px;
+  border: 1px solid rgba(88, 166, 255, 0.42);
+  border-radius: 8px;
+  background: rgba(88, 166, 255, 0.16);
+  color: var(--text);
+  font-size: var(--sdn-stack-header-link-size, 14px);
+  font-weight: 800;
+}
+
+main {
+  width: min(1180px, calc(100vw - 32px));
+  margin: 0 auto;
+  padding: 88px 0 calc(var(--sdn-stack-footer-height, 40px) + 72px);
+}
+
+.hero {
+  display: grid;
+  grid-template-columns: minmax(0, 0.92fr) minmax(320px, 1.08fr);
+  gap: 32px;
+  align-items: center;
+  min-height: calc(100vh - 128px);
+}
+
+.hero-copy {
+  min-width: 0;
+}
+
+.eyebrow {
+  margin: 0 0 10px;
+  color: var(--green);
+  font-size: 12px;
+  font-weight: 800;
+  letter-spacing: 0;
+  text-transform: uppercase;
+}
+
+h1,
+h2,
+p {
+  margin-top: 0;
+}
+
+h1 {
+  max-width: 10ch;
+  margin-bottom: 18px;
+  font-size: clamp(48px, 8vw, 92px);
+  line-height: 0.92;
+  letter-spacing: 0;
+}
+
+.lede {
+  max-width: 60ch;
+  color: var(--muted);
+  font-size: 18px;
+  line-height: 1.65;
+}
+
+.actions {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 10px;
+  margin-top: 28px;
+}
+
+.button {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  min-height: 42px;
+  padding: 0 16px;
+  border: 1px solid var(--line);
+  border-radius: 8px;
+  background: rgba(255, 255, 255, 0.06);
+  color: var(--text);
+  font-size: 14px;
+  font-weight: 700;
+}
+
+.button:hover {
+  border-color: var(--line-strong);
+  background: rgba(255, 255, 255, 0.1);
+}
+
+.button.primary {
+  border-color: rgba(88, 166, 255, 0.46);
+  background: rgba(88, 166, 255, 0.2);
+}
+
+.architecture {
+  margin: 0;
+  border: 1px solid var(--line);
+  border-radius: 8px;
+  background: var(--surface);
+  box-shadow: 0 28px 80px rgba(0, 0, 0, 0.36);
+  overflow: hidden;
+}
+
+.architecture img {
+  display: block;
+  width: 100%;
+  height: auto;
+  background: #0d1117;
+}
+
+.quick-grid {
+  display: grid;
+  grid-template-columns: repeat(4, minmax(0, 1fr));
+  gap: 12px;
+  margin: 28px 0 72px;
+}
+
+.quick-grid article {
+  min-width: 0;
+  border: 1px solid var(--line);
+  border-radius: 8px;
+  background: var(--surface);
+  padding: 18px;
+}
+
+.quick-grid h2 {
+  margin-bottom: 8px;
+  font-size: 16px;
+}
+
+.quick-grid p {
+  margin-bottom: 0;
+  color: var(--muted);
+  font-size: 14px;
+  line-height: 1.55;
+}
+
+.docs-list,
+.stack-list {
+  display: grid;
+  grid-template-columns: minmax(220px, 0.34fr) minmax(0, 0.66fr);
+  gap: 28px;
+  align-items: start;
+  border-top: 1px solid var(--line);
+  padding-top: 36px;
+}
+
+.stack-list {
+  margin-top: 72px;
+}
+
+.section-head h2 {
+  margin: 0;
+  font-size: 28px;
+}
+
+.link-list {
+  display: grid;
+  gap: 10px;
+}
+
+.link-list a {
+  display: grid;
+  gap: 6px;
+  border: 1px solid var(--line);
+  border-radius: 8px;
+  background: var(--surface-strong);
+  padding: 18px;
+}
+
+.link-list a:hover {
+  border-color: rgba(88, 166, 255, 0.52);
+}
+
+.link-list a.active {
+  border-color: rgba(88, 166, 255, 0.52);
+  background: rgba(88, 166, 255, 0.14);
+}
+
+.link-list span {
+  color: var(--text);
+  font-weight: 760;
+}
+
+.link-list small {
+  color: var(--muted);
+  font-size: 13px;
+  line-height: 1.45;
+}
+
+@media (max-width: 860px) {
+  main {
+    width: min(100vw - 24px, 1180px);
+    padding-top: 72px;
+  }
+
+  .hero,
+  .docs-list,
+  .stack-list {
+    grid-template-columns: 1fr;
+  }
+
+  .hero {
+    min-height: auto;
+  }
+
+  h1 {
+    max-width: 11ch;
+  }
+
+  .quick-grid {
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+  }
+}
+
+@media (max-width: 560px) {
+  .quick-grid {
+    grid-template-columns: 1fr;
+  }
+
+  .actions {
+    flex-direction: column;
+    align-items: stretch;
+  }
+}