SILVER/NODEDC_PLATFORM
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
Codex
2026-08-11 19:11:48 +03:00
parent 227c7c26c1
commit 393741f1bd
26 changed files with 1887 additions and 127 deletions
Download Patch File Download Diff File Expand all files Collapse all files
device-plane/packages/device-protocol-contract/src/index.mjs
+227 -5
View File
@@ -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);
}
device-plane/packages/device-protocol-contract/test/contract.test.mjs
+116
View File
@@ -2,16 +2,23 @@ import assert from "node:assert/strict";
import test from "node:test";
import {
DEVICE_ADAPTER_ACCEPTANCE_SCHEMA,
DEVICE_ADAPTER_MESSAGE_SCHEMA,
DEVICE_DISCOVERY_SIGNAL_SCHEMA,
DEVICE_PLANE_BINDING_SCHEMA,
assertIdentifierDigest,
assertSafeProjection,
hashRestrictedIdentifier,
maskRestrictedIdentifier,
normalizeDevicePlaneBinding,
normalizeAdapterAcceptance,
normalizeAdapterMessage,
normalizeDiscoverySignal,
normalizeRestrictedIdentifier,
normalizeRestrictedIdentifierProjection,
normalizeRestrictedIdentifierRecord,
toSafeDiscoveryView,
toSafeAdapterMessageView,
} from "../src/index.mjs";
const fakeImei = "000000000000001";
@@ -110,6 +117,25 @@ test("restricted identifier records keep digest internal and expose only a mask"
);
});
test("restricted identifiers support future adapter-defined hardware ids", () => {
const identifier = normalizeRestrictedIdentifier({
kind: "serial",
value: "SN-TRACKER-0001",
});
assert.deepEqual(identifier, {
kind: "serial",
value: "SN-TRACKER-0001",
});
assert.equal(maskRestrictedIdentifier(identifier), "***********0001");
assert.match(
hashRestrictedIdentifier(
identifier,
"test-only-pepper-with-at-least-32-bytes",
),
/^hmac-sha256:[a-f0-9]{64}$/,
);
});
test("rejects unverified framing and command-shaped discovery input", () => {
assert.throws(
() => normalizeDiscoverySignal({
@@ -147,3 +173,93 @@ test("normalizes an opaque Foundry control binding without device data", () => {
assert.deepEqual(binding.capabilities, ["inspect", "observe"]);
assertSafeProjection(binding);
});
test("normalizes a bounded typed adapter message and masks its identity", () => {
const message = {
schemaVersion: DEVICE_ADAPTER_MESSAGE_SCHEMA,
edgeRef: "edge:robot2b-vps-001",
adapterRef: "arusnavi-b2",
protocolProfileRef: "arusnavi.b2.internal.v1",
protocol: "INTERNAL",
sessionRef: "session:test-001",
routeRef: "route:11111111-1111-4111-8111-111111111111",
messageRef: "package:1:abc123",
messageType: "telemetry.package",
sequence: 1,
observedAt: "2026-08-11T12:00:00.000Z",
idempotencyKey: `sha256:${"a".repeat(64)}`,
identifier: { kind: "imei", value: fakeImei },
payloadSchemaRef: "arusnavi.internal.package-metadata.v1",
payload: {
packageNumber: 1,
packetCount: 1,
packageDigest: `sha256:${"b".repeat(64)}`,
},
};
const normalized = normalizeAdapterMessage(message);
const safe = toSafeAdapterMessageView(normalized);
assert.equal(normalized.identifier.value, fakeImei);
assert.equal(safe.identifier.masked, "***********0001");
assert.equal(JSON.stringify(safe).includes(fakeImei), false);
assertSafeProjection(safe);
});
test("rejects oversized, untyped and secret-shaped adapter messages", () => {
const base = {
schemaVersion: DEVICE_ADAPTER_MESSAGE_SCHEMA,
edgeRef: "edge:test",
adapterRef: "generic-tracker",
protocolProfileRef: "generic.tracker.v1",
protocol: "GENERIC",
sessionRef: "session:test",
messageRef: "message:1",
messageType: "telemetry.sample",
sequence: 1,
observedAt: "2026-08-11T12:00:00.000Z",
idempotencyKey: `sha256:${"a".repeat(64)}`,
identifier: { kind: "imei", value: fakeImei },
payloadSchemaRef: "generic.telemetry.v1",
payload: { value: 1 },
};
assert.throws(
() => normalizeAdapterMessage({ ...base, payload: "raw" }),
/device_adapter_message_payload_invalid/,
);
assert.throws(
() => normalizeAdapterMessage({
...base,
payload: { devicePassword: "forbidden" },
}),
/forbidden_device_field/,
);
assert.throws(
() => normalizeAdapterMessage({
...base,
payload: { value: "x".repeat(4096) },
}, { maxBytes: 1024 }),
/device_adapter_message_too_large/,
);
assert.throws(
() => normalizeAdapterMessage({
...base,
idempotencyKey: "message-not-a-digest",
}),
/idempotency_key_invalid/,
);
});
test("accepts only an explicit durable Core acceptance contract", () => {
const acceptance = normalizeAdapterAcceptance({
schemaVersion: DEVICE_ADAPTER_ACCEPTANCE_SCHEMA,
acceptanceRef: "acceptance:test-001",
idempotencyKey: `sha256:${"a".repeat(64)}`,
status: "accepted",
replayed: false,
acceptedAt: "2026-08-11T12:00:00.000Z",
});
assert.equal(acceptance.status, "accepted");
assert.throws(
() => normalizeAdapterAcceptance({ ...acceptance, status: "queued" }),
/device_adapter_acceptance_status_invalid/,
);
});