feat(device-plane): add universal adapter acceptance boundary

2026-08-11 19:11:48 +03:00
parent 227c7c26c1
commit 393741f1bd
26 changed files with 1887 additions and 127 deletions
@@ -6,6 +6,12 @@ export const DEVICE_DISCOVERY_VIEW_SCHEMA =
  "nodedc.device.discovery-view.v1";
 export const DEVICE_PLANE_BINDING_SCHEMA =
  "nodedc.device-plane-control.binding.v1";
+export const DEVICE_ADAPTER_MESSAGE_SCHEMA =
+  "nodedc.device-adapter-message.v1";
+export const DEVICE_ADAPTER_MESSAGE_VIEW_SCHEMA =
+  "nodedc.device-adapter-message-view.v1";
+export const DEVICE_ADAPTER_ACCEPTANCE_SCHEMA =
+  "nodedc.device-adapter-acceptance.v1";

 export const DEVICE_LIFECYCLE_STATES = Object.freeze([
  "quarantine",
@@ -24,7 +30,9 @@ export const DEVICE_BINDING_CAPABILITIES = Object.freeze([

 const OPAQUE_REF_RE = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
 const IMEI_RE = /^\d{15}$/;
+const IDENTIFIER_VALUE_RE = /^[A-Za-z0-9][A-Za-z0-9._:+\/-]{3,127}$/;
 const DIGEST_RE = /^hmac-sha256:[a-f0-9]{64}$/;
+const SHA256_DIGEST_RE = /^sha256:[a-f0-9]{64}$/;
 const IDENTIFIER_KIND_RE = /^[a-z][a-z0-9._:-]{1,63}$/;
 const forbiddenKeyFragments = Object.freeze([
  "password",
@@ -75,6 +83,129 @@ export function normalizeDiscoverySignal(input) {
  });
 }

+export function normalizeAdapterMessage(input, { maxBytes = 1024 * 1024 } = {}) {
+  assertPlainObject(input, "device_adapter_message");
+  const allowedKeys = new Set([
+    "schemaVersion",
+    "edgeRef",
+    "adapterRef",
+    "protocolProfileRef",
+    "protocol",
+    "sessionRef",
+    "routeRef",
+    "messageRef",
+    "messageType",
+    "sequence",
+    "observedAt",
+    "idempotencyKey",
+    "identifier",
+    "payloadSchemaRef",
+    "payload",
+  ]);
+  rejectUnexpectedKeys(input, allowedKeys, "device_adapter_message_field_unexpected");
+  rejectForbiddenKeys(input);
+  if (input.schemaVersion !== DEVICE_ADAPTER_MESSAGE_SCHEMA) {
+    throw new TypeError("device_adapter_message_schema_invalid");
+  }
+  const normalizedMaxBytes = normalizeByteLimit(maxBytes);
+  const serializedBytes = Buffer.byteLength(JSON.stringify(input), "utf8");
+  if (serializedBytes > normalizedMaxBytes) {
+    throw new TypeError("device_adapter_message_too_large");
+  }
+  const sequence = Number(input.sequence);
+  if (!Number.isSafeInteger(sequence) || sequence < 1) {
+    throw new TypeError("device_adapter_message_sequence_invalid");
+  }
+  assertPlainObject(input.payload, "device_adapter_message_payload");
+  assertJsonValue(input.payload, 0);
+
+  return deepFreeze({
+    schemaVersion: DEVICE_ADAPTER_MESSAGE_SCHEMA,
+    edgeRef: normalizeOpaqueRef(input.edgeRef, "edge_ref"),
+    adapterRef: normalizeAdapterRef(input.adapterRef),
+    protocolProfileRef: normalizeOpaqueRef(
+      input.protocolProfileRef,
+      "protocol_profile_ref",
+    ),
+    protocol: normalizeUpperToken(input.protocol, "protocol"),
+    sessionRef: normalizeOpaqueRef(input.sessionRef, "session_ref"),
+    ...(input.routeRef == null
+      ? {}
+      : { routeRef: normalizeEntityRef(input.routeRef, "route", "route_ref") }),
+    messageRef: normalizeOpaqueRef(input.messageRef, "message_ref"),
+    messageType: normalizeLowerToken(input.messageType, "message_type"),
+    sequence,
+    observedAt: normalizeTimestamp(input.observedAt, "observed_at"),
+    idempotencyKey: normalizeSha256Digest(
+      input.idempotencyKey,
+      "idempotency_key",
+    ),
+    identifier: normalizeRestrictedIdentifier(input.identifier),
+    payloadSchemaRef: normalizeOpaqueRef(
+      input.payloadSchemaRef,
+      "payload_schema_ref",
+    ),
+    payload: cloneJsonValue(input.payload),
+  });
+}
+
+export function toSafeAdapterMessageView(message) {
+  const normalized = normalizeAdapterMessage(message);
+  return deepFreeze({
+    schemaVersion: DEVICE_ADAPTER_MESSAGE_VIEW_SCHEMA,
+    edgeRef: normalized.edgeRef,
+    adapterRef: normalized.adapterRef,
+    protocolProfileRef: normalized.protocolProfileRef,
+    protocol: normalized.protocol,
+    sessionRef: normalized.sessionRef,
+    ...(normalized.routeRef ? { routeRef: normalized.routeRef } : {}),
+    messageRef: normalized.messageRef,
+    messageType: normalized.messageType,
+    sequence: normalized.sequence,
+    observedAt: normalized.observedAt,
+    idempotencyKey: normalized.idempotencyKey,
+    identifier: normalizeRestrictedIdentifierProjection({
+      kind: normalized.identifier.kind,
+      masked: maskRestrictedIdentifier(normalized.identifier),
+    }),
+    payloadSchemaRef: normalized.payloadSchemaRef,
+    payload: normalized.payload,
+  });
+}
+
+export function normalizeAdapterAcceptance(input) {
+  assertPlainObject(input, "device_adapter_acceptance");
+  const allowedKeys = new Set([
+    "schemaVersion",
+    "acceptanceRef",
+    "idempotencyKey",
+    "status",
+    "replayed",
+    "acceptedAt",
+  ]);
+  rejectUnexpectedKeys(input, allowedKeys, "device_adapter_acceptance_field_unexpected");
+  if (input.schemaVersion !== DEVICE_ADAPTER_ACCEPTANCE_SCHEMA) {
+    throw new TypeError("device_adapter_acceptance_schema_invalid");
+  }
+  if (input.status !== "accepted") {
+    throw new TypeError("device_adapter_acceptance_status_invalid");
+  }
+  if (typeof input.replayed !== "boolean") {
+    throw new TypeError("device_adapter_acceptance_replayed_invalid");
+  }
+  return Object.freeze({
+    schemaVersion: DEVICE_ADAPTER_ACCEPTANCE_SCHEMA,
+    acceptanceRef: normalizeOpaqueRef(input.acceptanceRef, "acceptance_ref"),
+    idempotencyKey: normalizeSha256Digest(
+      input.idempotencyKey,
+      "idempotency_key",
+    ),
+    status: "accepted",
+    replayed: input.replayed,
+    acceptedAt: normalizeTimestamp(input.acceptedAt, "accepted_at"),
+  });
+}
+
 export function toSafeDiscoveryView(signal, options = {}) {
  const normalized = normalizeDiscoverySignal(signal);
  const discoveryRef = options.discoveryRef
@@ -204,13 +335,24 @@ export function assertSafeProjection(value) {

 export function normalizeRestrictedIdentifier(input) {
  assertPlainObject(input, "restricted_identifier");
-  if (input.kind !== "imei") {
-    throw new TypeError("restricted_identifier_kind_unsupported");
+  rejectUnexpectedKeys(
+    input,
+    new Set(["kind", "value"]),
+    "restricted_identifier_field_unexpected",
+  );
+  if (typeof input.kind !== "string" || !IDENTIFIER_KIND_RE.test(input.kind)) {
+    throw new TypeError("restricted_identifier_kind_invalid");
  }
-  if (typeof input.value !== "string" || !IMEI_RE.test(input.value)) {
+  if (input.kind === "imei" && !IMEI_RE.test(input.value)) {
    throw new TypeError("restricted_identifier_imei_invalid");
  }
-  return Object.freeze({ kind: "imei", value: input.value });
+  if (
+    typeof input.value !== "string"
+    || !IDENTIFIER_VALUE_RE.test(input.value)
+  ) {
+    throw new TypeError("restricted_identifier_value_invalid");
+  }
+  return Object.freeze({ kind: input.kind, value: input.value });
 }

 export function maskRestrictedIdentifier(identifier) {
@@ -218,7 +360,12 @@ export function maskRestrictedIdentifier(identifier) {
  if (normalized.kind === "imei") {
    return `***********${normalized.value.slice(-4)}`;
  }
-  throw new TypeError("restricted_identifier_kind_unsupported");
+  const visible = normalized.value.slice(-4);
+  const maskedLength = Math.min(
+    124,
+    Math.max(4, normalized.value.length - visible.length),
+  );
+  return `${"*".repeat(maskedLength)}${visible}`;
 }

 function normalizeDiscoveryEvidence(input) {
@@ -265,6 +412,73 @@ function rejectForbiddenKeys(value, path = "$") {
  }
 }

+function rejectUnexpectedKeys(input, allowedKeys, errorCode) {
+  for (const key of Object.keys(input)) {
+    if (!allowedKeys.has(key)) throw new TypeError(`${errorCode}:${key}`);
+  }
+}
+
+function normalizeLowerToken(value, label) {
+  if (typeof value !== "string" || !/^[a-z][a-z0-9._-]{1,127}$/.test(value)) {
+    throw new TypeError(`${label}_invalid`);
+  }
+  return value;
+}
+
+function normalizeAdapterRef(value) {
+  if (typeof value !== "string" || !/^[a-z][a-z0-9-]{1,62}$/.test(value)) {
+    throw new TypeError("adapter_ref_invalid");
+  }
+  return value;
+}
+
+function normalizeSha256Digest(value, label) {
+  if (typeof value !== "string" || !SHA256_DIGEST_RE.test(value)) {
+    throw new TypeError(`${label}_invalid`);
+  }
+  return value;
+}
+
+function normalizeByteLimit(value) {
+  const parsed = Number(value);
+  if (!Number.isSafeInteger(parsed) || parsed < 1024 || parsed > 1024 * 1024) {
+    throw new TypeError("device_adapter_message_limit_invalid");
+  }
+  return parsed;
+}
+
+function assertJsonValue(value, depth) {
+  if (depth > 12) throw new TypeError("device_adapter_message_payload_too_deep");
+  if (value === null || typeof value === "boolean" || typeof value === "string") {
+    if (typeof value === "string" && value.length > 64 * 1024) {
+      throw new TypeError("device_adapter_message_payload_string_too_large");
+    }
+    return;
+  }
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) {
+      throw new TypeError("device_adapter_message_payload_number_invalid");
+    }
+    return;
+  }
+  if (Array.isArray(value)) {
+    if (value.length > 4096) {
+      throw new TypeError("device_adapter_message_payload_array_too_large");
+    }
+    value.forEach((item) => assertJsonValue(item, depth + 1));
+    return;
+  }
+  assertPlainObject(value, "device_adapter_message_payload");
+  if (Object.keys(value).length > 1024) {
+    throw new TypeError("device_adapter_message_payload_object_too_large");
+  }
+  for (const child of Object.values(value)) assertJsonValue(child, depth + 1);
+}
+
+function cloneJsonValue(value) {
+  return JSON.parse(JSON.stringify(value));
+}
+
 function normalizeOpaqueRef(value, label) {
  if (typeof value !== "string" || !OPAQUE_REF_RE.test(value)) {
    throw new TypeError(`${label}_invalid`);
@@ -306,3 +520,11 @@ function assertPlainObject(value, label) {
    throw new TypeError(`${label}_invalid`);
  }
 }
+
+function deepFreeze(value) {
+  if (!value || typeof value !== "object" || Object.isFrozen(value)) {
+    return value;
+  }
+  Object.values(value).forEach(deepFreeze);
+  return Object.freeze(value);
+}