space-data-module-sdk 0.2.6 → 0.2.8

package/src/compliance/pluginCompliance.js

@@ -8,6 +8,8 @@ import {
   ExternalInterfaceDirection,
   ExternalInterfaceKind,
   InvokeSurface,
+  ProtocolRole,
+  ProtocolTransportKind,
   RuntimeTarget,
 } from "../runtime/constants.js";
 
@@ -50,7 +52,16 @@ export const RecommendedCapabilityIds = Object.freeze([
   "render_hooks",
 ]);
 
+export const StandaloneWasiCapabilityIds = Object.freeze([
+  "logging",
+  "clock",
+  "random",
+  "filesystem",
+  "pipe",
+]);
+
 const RecommendedCapabilitySet = new Set(RecommendedCapabilityIds);
+const StandaloneWasiCapabilitySet = new Set(StandaloneWasiCapabilityIds);
 const RecommendedRuntimeTargets = Object.freeze(Object.values(RuntimeTarget));
 const RecommendedRuntimeTargetSet = new Set(RecommendedRuntimeTargets);
 const DrainPolicySet = new Set(Object.values(DrainPolicy));
@@ -59,6 +70,8 @@ const ExternalInterfaceDirectionSet = new Set(
   Object.values(ExternalInterfaceDirection),
 );
 const ExternalInterfaceKindSet = new Set(Object.values(ExternalInterfaceKind));
+const ProtocolRoleSet = new Set(Object.values(ProtocolRole));
+const ProtocolTransportKindSet = new Set(Object.values(ProtocolTransportKind));
 const BrowserIncompatibleCapabilitySet = new Set([
   "filesystem",
   "pipe",
@@ -79,6 +92,9 @@ const BrowserIncompatibleCapabilitySet = new Set([
   "entity_access",
   "render_hooks",
 ]);
+const StandaloneWasiProtocolTransportKindSet = new Set([
+  ProtocolTransportKind.WASI_PIPE,
+]);
 const IgnoredDirectoryNames = new Set([
   ".git",
   ".hg",
@@ -120,6 +136,57 @@ function hasNonEmptyByteSequence(value) {
   return false;
 }
 
+function normalizeTypeIdentityString(value) {
+  if (!isNonEmptyString(value)) {
+    return null;
+  }
+  return value.trim().toLowerCase();
+}
+
+function normalizeTypeIdentityBytes(value) {
+  if (typeof value === "string") {
+    const trimmed = value.trim().toLowerCase();
+    return trimmed.length > 0 ? trimmed : null;
+  }
+  const bytes = ArrayBuffer.isView(value)
+    ? Array.from(value)
+    : Array.isArray(value)
+      ? value
+      : null;
+  if (!bytes || bytes.length === 0) {
+    return null;
+  }
+  return bytes
+    .map((entry) => Number(entry).toString(16).padStart(2, "0"))
+    .join("");
+}
+
+function allowedTypesReferToSameLogicalSchema(left, right) {
+  const leftSchemaName = normalizeTypeIdentityString(left?.schemaName);
+  const rightSchemaName = normalizeTypeIdentityString(right?.schemaName);
+  if (leftSchemaName && rightSchemaName && leftSchemaName === rightSchemaName) {
+    return true;
+  }
+
+  const leftFileIdentifier = normalizeTypeIdentityString(left?.fileIdentifier);
+  const rightFileIdentifier = normalizeTypeIdentityString(right?.fileIdentifier);
+  if (
+    leftFileIdentifier &&
+    rightFileIdentifier &&
+    leftFileIdentifier === rightFileIdentifier
+  ) {
+    return true;
+  }
+
+  const leftSchemaHash = normalizeTypeIdentityBytes(left?.schemaHash);
+  const rightSchemaHash = normalizeTypeIdentityBytes(right?.schemaHash);
+  if (leftSchemaHash && rightSchemaHash && leftSchemaHash === rightSchemaHash) {
+    return true;
+  }
+
+  return false;
+}
+
 function normalizePayloadWireFormatName(value) {
   if (value === undefined || value === null || value === "") {
     return "flatbuffer";
@@ -151,7 +218,13 @@ function validateStringField(issues, value, location, label) {
   return true;
 }
 
-function validateIntegerField(issues, value, location, label, { min = null } = {}) {
+function validateIntegerField(
+  issues,
+  value,
+  location,
+  label,
+  { min = null, max = null } = {},
+) {
   if (!Number.isInteger(value)) {
     pushIssue(issues, "error", "invalid-integer", `${label} must be an integer.`, location);
     return false;
@@ -166,6 +239,16 @@ function validateIntegerField(issues, value, location, label, { min = null } = {
     );
     return false;
   }
+  if (max !== null && value > max) {
+    pushIssue(
+      issues,
+      "error",
+      "integer-range",
+      `${label} must be less than or equal to ${max}.`,
+      location,
+    );
+    return false;
+  }
   return true;
 }
 
@@ -182,6 +265,61 @@ function validateOptionalIntegerField(
   return validateIntegerField(issues, value, location, label, options);
 }
 
+function validateOptionalBooleanField(issues, value, location, label) {
+  if (value === undefined || value === null) {
+    return true;
+  }
+  if (typeof value !== "boolean") {
+    pushIssue(
+      issues,
+      "error",
+      "invalid-boolean",
+      `${label} must be a boolean when present.`,
+      location,
+    );
+    return false;
+  }
+  return true;
+}
+
+function validateOptionalStringField(issues, value, location, label) {
+  if (value === undefined || value === null) {
+    return true;
+  }
+  return validateStringField(issues, value, location, label);
+}
+
+function normalizeProtocolTransportKind(value) {
+  if (value === undefined || value === null || value === "") {
+    return null;
+  }
+  const normalized = String(value)
+    .trim()
+    .toLowerCase()
+    .replace(/_/g, "-");
+  if (normalized === "websocket") {
+    return ProtocolTransportKind.WS;
+  }
+  if (normalized === "pipe") {
+    return ProtocolTransportKind.WASI_PIPE;
+  }
+  return normalized;
+}
+
+function normalizeProtocolRole(value) {
+  if (value === undefined || value === null || value === "") {
+    return null;
+  }
+  const normalized = String(value)
+    .trim()
+    .toLowerCase()
+    .replace(/_/g, "-");
+  if (normalized === "handler") {
+    return ProtocolRole.HANDLE;
+  }
+  return normalized;
+}
+
 function validateAllowedType(type, issues, location) {
   if (!type || typeof type !== "object" || Array.isArray(type)) {
     pushIssue(issues, "error", "invalid-type-record", "Allowed type entries must be objects.", location);
@@ -307,6 +445,35 @@ function validateAcceptedTypeSet(typeSet, issues, location) {
   typeSet.allowedTypes.forEach((allowedType, index) => {
     validateAllowedType(allowedType, issues, `${location}.allowedTypes[${index}]`);
   });
+
+  const regularConcreteTypes = [];
+  const alignedTypes = [];
+
+  typeSet.allowedTypes.forEach((allowedType, index) => {
+    const wireFormat = normalizePayloadWireFormatName(allowedType?.wireFormat);
+    if (wireFormat === "aligned-binary") {
+      alignedTypes.push({ allowedType, index });
+      return;
+    }
+    if (wireFormat === "flatbuffer" && allowedType?.acceptsAnyFlatbuffer !== true) {
+      regularConcreteTypes.push({ allowedType, index });
+    }
+  });
+
+  alignedTypes.forEach(({ allowedType, index }) => {
+    const hasRegularFallback = regularConcreteTypes.some(({ allowedType: regularType }) =>
+      allowedTypesReferToSameLogicalSchema(allowedType, regularType),
+    );
+    if (!hasRegularFallback) {
+      pushIssue(
+        issues,
+        "error",
+        "missing-flatbuffer-fallback",
+        "Aligned-binary allowed types must be paired with a regular flatbuffer fallback for the same schema in the same acceptedTypeSet.",
+        `${location}.allowedTypes[${index}]`,
+      );
+    }
+  });
 }
 
 function validatePort(port, issues, location, label) {
@@ -576,6 +743,85 @@ function validateProtocol(protocol, issues, location, methodLookup, declaredCapa
       );
     }
   }
+  const wireIdValid = validateStringField(
+    issues,
+    protocol.wireId,
+    `${location}.wireId`,
+    "Protocol wireId",
+  );
+  const normalizedTransportKind = normalizeProtocolTransportKind(
+    protocol.transportKind,
+  );
+  if (!validateStringField(
+    issues,
+    protocol.transportKind,
+    `${location}.transportKind`,
+    "Protocol transportKind",
+  )) {
+    // already reported
+  } else if (!ProtocolTransportKindSet.has(normalizedTransportKind)) {
+    pushIssue(
+      issues,
+      "error",
+      "unknown-protocol-transport-kind",
+      `Protocol "${protocol.protocolId ?? "protocol"}" transportKind must be one of: ${Array.from(ProtocolTransportKindSet).join(", ")}.`,
+      `${location}.transportKind`,
+    );
+  }
+  const normalizedRole = normalizeProtocolRole(protocol.role);
+  if (!validateStringField(
+    issues,
+    protocol.role,
+    `${location}.role`,
+    "Protocol role",
+  )) {
+    // already reported
+  } else if (!ProtocolRoleSet.has(normalizedRole)) {
+    pushIssue(
+      issues,
+      "error",
+      "unknown-protocol-role",
+      `Protocol "${protocol.protocolId ?? "protocol"}" role must be one of: ${Array.from(ProtocolRoleSet).join(", ")}.`,
+      `${location}.role`,
+    );
+  }
+  validateOptionalStringField(
+    issues,
+    protocol.specUri,
+    `${location}.specUri`,
+    "Protocol specUri",
+  );
+  validateOptionalStringField(
+    issues,
+    protocol.discoveryKey,
+    `${location}.discoveryKey`,
+    "Protocol discoveryKey",
+  );
+  validateOptionalBooleanField(
+    issues,
+    protocol.autoInstall,
+    `${location}.autoInstall`,
+    "Protocol autoInstall",
+  );
+  validateOptionalBooleanField(
+    issues,
+    protocol.advertise,
+    `${location}.advertise`,
+    "Protocol advertise",
+  );
+  validateOptionalBooleanField(
+    issues,
+    protocol.requireSecureTransport,
+    `${location}.requireSecureTransport`,
+    "Protocol requireSecureTransport",
+  );
+  validateOptionalIntegerField(
+    issues,
+    protocol.defaultPort,
+    `${location}.defaultPort`,
+    "Protocol defaultPort",
+    { min: 0, max: 65535 },
+  );
   if (
     protocolIdValid &&
     Array.isArray(declaredCapabilities) &&
@@ -590,6 +836,77 @@ function validateProtocol(protocol, issues, location, methodLookup, declaredCapa
       location,
     );
   }
+  if (
+    protocolIdValid &&
+    normalizedRole &&
+    (normalizedRole === ProtocolRole.HANDLE ||
+      normalizedRole === ProtocolRole.BOTH) &&
+    Array.isArray(declaredCapabilities) &&
+    !declaredCapabilities.includes("protocol_handle")
+  ) {
+    pushIssue(
+      issues,
+      "error",
+      "missing-handle-protocol-capability",
+      `Protocol "${protocol.protocolId}" with role "${normalizedRole}" requires the "protocol_handle" capability.`,
+      location,
+    );
+  }
+  if (
+    protocolIdValid &&
+    normalizedRole &&
+    (normalizedRole === ProtocolRole.DIAL ||
+      normalizedRole === ProtocolRole.BOTH) &&
+    Array.isArray(declaredCapabilities) &&
+    !declaredCapabilities.includes("protocol_dial")
+  ) {
+    pushIssue(
+      issues,
+      "error",
+      "missing-dial-protocol-capability",
+      `Protocol "${protocol.protocolId}" with role "${normalizedRole}" requires the "protocol_dial" capability.`,
+      location,
+    );
+  }
+  if (
+    protocol.advertise === true &&
+    normalizedRole === ProtocolRole.DIAL
+  ) {
+    pushIssue(
+      issues,
+      "error",
+      "protocol-advertise-role-conflict",
+      `Protocol "${protocol.protocolId ?? "protocol"}" cannot advertise when role is "dial".`,
+      `${location}.advertise`,
+    );
+  }
+  if (
+    normalizedTransportKind === ProtocolTransportKind.LIBP2P &&
+    Array.isArray(declaredCapabilities) &&
+    !declaredCapabilities.includes("ipfs")
+  ) {
+    pushIssue(
+      issues,
+      "error",
+      "missing-ipfs-capability",
+      `Protocol "${protocol.protocolId ?? "protocol"}" with transportKind "libp2p" requires the "ipfs" capability.`,
+      location,
+    );
+  }
+  if (
+    wireIdValid &&
+    normalizedTransportKind === ProtocolTransportKind.WS &&
+    protocol.defaultPort === 443 &&
+    protocol.requireSecureTransport !== true
+  ) {
+    pushIssue(
+      issues,
+      "warning",
+      "insecure-secure-port-hint",
+      `Protocol "${protocol.protocolId ?? "protocol"}" uses defaultPort 443 without requireSecureTransport=true.`,
+      `${location}.defaultPort`,
+    );
+  }
 }
 
 function validateRuntimeTargets(runtimeTargets, declaredCapabilities, issues, sourceName) {
@@ -658,6 +975,66 @@ function validateRuntimeTargets(runtimeTargets, declaredCapabilities, issues, so
   }
 }
 
+function validateStandaloneWasiTarget(
+  manifest,
+  normalizedInvokeSurfaces,
+  declaredCapabilities,
+  issues,
+  sourceName,
+) {
+  const runtimeTargets = Array.isArray(manifest?.runtimeTargets)
+    ? manifest.runtimeTargets
+    : [];
+  if (!runtimeTargets.includes(RuntimeTarget.WASI)) {
+    return;
+  }
+
+  if (!normalizedInvokeSurfaces.includes(InvokeSurface.COMMAND)) {
+    pushIssue(
+      issues,
+      "error",
+      "missing-wasi-command-surface",
+      'Artifacts targeting the canonical "wasi" runtime must declare the "command" invoke surface so they can run as standalone WASI programs without host wrappers.',
+      `${sourceName}.invokeSurfaces`,
+    );
+  }
+
+  if (Array.isArray(declaredCapabilities)) {
+    for (const capability of declaredCapabilities) {
+      if (!StandaloneWasiCapabilitySet.has(capability)) {
+        pushIssue(
+          issues,
+          "error",
+          "capability-wasi-standalone-conflict",
+          `Capability "${capability}" is not available to a standalone WASI artifact without host wrappers.`,
+          `${sourceName}.capabilities`,
+        );
+      }
+    }
+  }
+
+  if (!Array.isArray(manifest?.protocols)) {
+    return;
+  }
+  manifest.protocols.forEach((protocol, index) => {
+    const normalizedTransportKind = normalizeProtocolTransportKind(
+      protocol?.transportKind,
+    );
+    if (
+      normalizedTransportKind &&
+      !StandaloneWasiProtocolTransportKindSet.has(normalizedTransportKind)
+    ) {
+      pushIssue(
+        issues,
+        "error",
+        "protocol-wasi-standalone-conflict",
+        `Protocol "${protocol?.protocolId ?? "protocol"}" uses transportKind "${protocol?.transportKind}", which requires a host wrapper rather than a standalone WASI runtime.`,
+        `${sourceName}.protocols[${index}].transportKind`,
+      );
+    }
+  });
+}
+
 function validateInvokeSurfaces(invokeSurfaces, issues, sourceName) {
   if (invokeSurfaces === undefined) {
     return [];
@@ -781,7 +1158,11 @@ export function validatePluginManifest(manifest, options = {}) {
     issues,
     sourceName,
   );
-  validateInvokeSurfaces(manifest.invokeSurfaces, issues, sourceName);
+  const normalizedInvokeSurfaces = validateInvokeSurfaces(
+    manifest.invokeSurfaces,
+    issues,
+    sourceName,
+  );
 
   if (!Array.isArray(manifest.externalInterfaces)) {
     pushIssue(
@@ -922,6 +1303,14 @@ export function validatePluginManifest(manifest, options = {}) {
     }
   }
 
+  validateStandaloneWasiTarget(
+    manifest,
+    normalizedInvokeSurfaces,
+    declaredCapabilities,
+    issues,
+    sourceName,
+  );
+
   if (manifest.schemasUsed !== undefined && !Array.isArray(manifest.schemasUsed)) {
     pushIssue(
       issues,

package/src/deployment/index.d.ts

@@ -0,0 +1,224 @@
+import type {
+  PluginManifest,
+  ProtocolRoleName,
+  ProtocolSpec,
+  ProtocolTransportKindName,
+} from "../index.js";
+
+export type InputBindingSourceKindName =
+  | "pubsub"
+  | "protocol-stream"
+  | "catalog-sync";
+export type DeploymentBindingModeName = "local" | "delegated";
+export type ScheduleBindingKindName = "interval" | "cron" | "once";
+
+export interface ResolvedProtocolInstallation {
+  protocolId: string;
+  wireId: string;
+  transportKind: ProtocolTransportKindName | string;
+  role: ProtocolRoleName | string;
+  peerId?: string | null;
+  listenMultiaddrs?: string[];
+  advertisedMultiaddrs?: string[];
+  nodeInfoUrl?: string | null;
+  serviceName?: string | null;
+  resolvedPort?: number;
+  artifactCid?: string | null;
+  description?: string | null;
+}
+
+export interface InputBinding {
+  bindingId: string;
+  targetPluginId?: string | null;
+  targetMethodId: string;
+  targetInputPortId: string;
+  sourceKind: InputBindingSourceKindName | string;
+  topic?: string | null;
+  wireId?: string | null;
+  nodeInfoUrl?: string | null;
+  multiaddrs?: string[];
+  allowPeerIds?: string[];
+  allowServerKeys?: string[];
+  deliveryMode?: string | null;
+  description?: string | null;
+}
+
+export interface ScheduleBinding {
+  scheduleId: string;
+  bindingMode: DeploymentBindingModeName | string;
+  triggerId?: string | null;
+  targetMethodId?: string | null;
+  targetInputPortId?: string | null;
+  scheduleKind: ScheduleBindingKindName | string;
+  cron?: string | null;
+  intervalMs?: number;
+  runAtStartup?: boolean;
+  startupDelayMs?: number;
+  timezone?: string | null;
+  description?: string | null;
+}
+
+export interface ServiceBinding {
+  serviceId: string;
+  bindingMode: DeploymentBindingModeName | string;
+  serviceKind: string;
+  triggerId?: string | null;
+  protocolId?: string | null;
+  routePath?: string | null;
+  method?: string | null;
+  transportKind?: ProtocolTransportKindName | string | null;
+  adapter?: string | null;
+  listenHost?: string | null;
+  listenPort?: number;
+  remoteUrl?: string | null;
+  allowTransports?: string[];
+  authPolicyId?: string | null;
+  description?: string | null;
+  properties?: Record<string, unknown>;
+}
+
+export interface AuthPolicy {
+  policyId: string;
+  bindingMode: DeploymentBindingModeName | string;
+  targetKind: string;
+  targetId?: string | null;
+  adapter?: string | null;
+  walletProfileId?: string | null;
+  trustMapId?: string | null;
+  allowPeerIds?: string[];
+  allowServerKeys?: string[];
+  allowEntityIds?: string[];
+  requireSignedRequests?: boolean;
+  requireEncryptedTransport?: boolean;
+  description?: string | null;
+  properties?: Record<string, unknown>;
+}
+
+export interface PublicationBinding {
+  publicationId: string;
+  bindingMode: DeploymentBindingModeName | string;
+  sourceKind: string;
+  sourceMethodId?: string | null;
+  sourceOutputPortId?: string | null;
+  sourceNodeId?: string | null;
+  sourceTriggerId?: string | null;
+  topic?: string | null;
+  wireId?: string | null;
+  schemaName?: string | null;
+  mediaType?: string | null;
+  archivePath?: string | null;
+  queryServiceId?: string | null;
+  emitPnm?: boolean;
+  emitFlatbufferArchive?: boolean;
+  pinPolicy?: string | null;
+  maxRecords?: number;
+  maxBytes?: number;
+  minLivelinessSeconds?: number;
+  recordRangeStartField?: string | null;
+  recordRangeStopField?: string | null;
+  description?: string | null;
+  properties?: Record<string, unknown>;
+}
+
+export interface ModuleDeploymentPlan {
+  formatVersion?: number;
+  pluginId?: string | null;
+  version?: string | null;
+  artifactCid?: string | null;
+  bundleCid?: string | null;
+  environmentId?: string | null;
+  protocolInstallations?: ResolvedProtocolInstallation[];
+  inputBindings?: InputBinding[];
+  scheduleBindings?: ScheduleBinding[];
+  serviceBindings?: ServiceBinding[];
+  authPolicies?: AuthPolicy[];
+  publicationBindings?: PublicationBinding[];
+}
+
+export interface DeploymentPlanIssue {
+  severity: "error" | "warning";
+  code: string;
+  message: string;
+  location?: string;
+}
+
+export interface DeploymentPlanValidationReport {
+  ok: boolean;
+  plan: ModuleDeploymentPlan;
+  issues: DeploymentPlanIssue[];
+  errors: DeploymentPlanIssue[];
+  warnings: DeploymentPlanIssue[];
+}
+
+export const DEPLOYMENT_PLAN_FORMAT_VERSION: number;
+
+export const InputBindingSourceKind: {
+  PUBSUB: InputBindingSourceKindName;
+  PROTOCOL_STREAM: InputBindingSourceKindName;
+  CATALOG_SYNC: InputBindingSourceKindName;
+};
+
+export const DeploymentBindingMode: {
+  LOCAL: DeploymentBindingModeName;
+  DELEGATED: DeploymentBindingModeName;
+};
+
+export const ScheduleBindingKind: {
+  INTERVAL: ScheduleBindingKindName;
+  CRON: ScheduleBindingKindName;
+  ONCE: ScheduleBindingKindName;
+};
+
+export function normalizeProtocolTransportKindName(
+  value: ProtocolTransportKindName | string | null | undefined,
+): ProtocolTransportKindName | string | null;
+
+export function normalizeProtocolRoleName(
+  value: ProtocolRoleName | string | null | undefined,
+): ProtocolRoleName | string | null;
+
+export function normalizeInputBindingSourceKindName(
+  value: InputBindingSourceKindName | string | null | undefined,
+): InputBindingSourceKindName | string | null;
+
+export function normalizeDeploymentBindingModeName(
+  value: DeploymentBindingModeName | string | null | undefined,
+): DeploymentBindingModeName | string | null;
+
+export function normalizeScheduleBindingKindName(
+  value: ScheduleBindingKindName | string | null | undefined,
+): ScheduleBindingKindName | string | null;
+
+export function normalizeDeploymentPlan(
+  plan: ModuleDeploymentPlan | null | undefined,
+): ModuleDeploymentPlan;
+
+export function validateDeploymentPlan(
+  plan: ModuleDeploymentPlan | null | undefined,
+  options?: { manifest?: PluginManifest | null },
+): DeploymentPlanValidationReport;
+
+export function createDeploymentPlanBundleEntry(
+  plan: ModuleDeploymentPlan | null | undefined,
+  options?: {
+    entryId?: string;
+    role?: string;
+    sectionName?: string;
+    mediaType?: string;
+    description?: string;
+  },
+): {
+  entryId: string;
+  role: string;
+  sectionName: string;
+  payloadEncoding: "json-utf8";
+  mediaType: string;
+  payload: ModuleDeploymentPlan;
+  description: string;
+};
+
+export function findDeploymentPlanEntry(bundleLike: unknown): unknown | null;
+
+export function readDeploymentPlanFromBundle(
+  bundleLike: unknown,
+): ModuleDeploymentPlan | null;