@kaonis/protocol 1.0.0

package/README.md

@@ -0,0 +1,29 @@
+# @kaonis/protocol
+
+Shared protocol types and runtime schemas for communication between `woly-backend` (node agent) and `woly-cnc-backend` (C&C).
+
+## Exports
+
+- `PROTOCOL_VERSION`
+- `SUPPORTED_PROTOCOL_VERSIONS`
+- `outboundNodeMessageSchema`
+- `inboundCncCommandSchema`
+- Type exports from `index.d.ts` (`NodeMessage`, `CncCommand`, `NodeRegistration`, etc.)
+
+## Publish
+
+From the `woly-backend` repo root:
+
+```bash
+npm run protocol:pack
+npm run protocol:publish
+```
+
+Or use the GitHub workflow: `Publish Protocol Package`.
+
+## Versioning
+
+1. Bump `packages/protocol/package.json` version.
+2. Publish package.
+3. Update both repos to consume the new semver version.
+4. Run protocol contract tests in both repos before merge.

package/index.d.ts

@@ -0,0 +1,82 @@
+import { z } from 'zod';
+
+export const PROTOCOL_VERSION: '1.0.0';
+export const SUPPORTED_PROTOCOL_VERSIONS: readonly string[];
+
+export type HostStatus = 'awake' | 'asleep';
+
+export interface HostPayload {
+  name: string;
+  mac: string;
+  ip: string;
+  status: HostStatus;
+  lastSeen: string | null;
+  discovered: number;
+  pingResponsive?: number | null;
+}
+
+export interface NodeMetadata {
+  version: string;
+  platform: string;
+  protocolVersion: string;
+  networkInfo: {
+    subnet: string;
+    gateway: string;
+  };
+}
+
+export interface NodeRegistration {
+  nodeId: string;
+  name: string;
+  location: string;
+  authToken: string;
+  publicUrl?: string;
+  metadata: NodeMetadata;
+}
+
+export type NodeMessage =
+  | { type: 'register'; data: NodeRegistration }
+  | { type: 'heartbeat'; data: { nodeId: string; timestamp: Date } }
+  | { type: 'host-discovered'; data: { nodeId: string } & HostPayload }
+  | { type: 'host-updated'; data: { nodeId: string } & HostPayload }
+  | { type: 'host-removed'; data: { nodeId: string; name: string } }
+  | { type: 'scan-complete'; data: { nodeId: string; hostCount: number } }
+  | {
+      type: 'command-result';
+      data: {
+        nodeId: string;
+        commandId: string;
+        success: boolean;
+        message?: string;
+        error?: string;
+        timestamp: Date;
+      };
+    };
+
+export interface RegisteredCommandData {
+  nodeId: string;
+  heartbeatInterval: number;
+  protocolVersion?: string;
+}
+
+export type CncCommand =
+  | { type: 'registered'; data: RegisteredCommandData }
+  | { type: 'wake'; commandId: string; data: { hostName: string; mac: string } }
+  | { type: 'scan'; commandId: string; data: { immediate: boolean } }
+  | {
+      type: 'update-host';
+      commandId: string;
+      data: {
+        currentName?: string;
+        name: string;
+        mac?: string;
+        ip?: string;
+        status?: HostStatus;
+      };
+    }
+  | { type: 'delete-host'; commandId: string; data: { name: string } }
+  | { type: 'ping'; data: { timestamp: Date } }
+  | { type: 'error'; message: string };
+
+export const inboundCncCommandSchema: z.ZodType<CncCommand>;
+export const outboundNodeMessageSchema: z.ZodType<NodeMessage>;

package/index.js

@@ -0,0 +1,151 @@
+const { z } = require('zod');
+
+const PROTOCOL_VERSION = '1.0.0';
+const SUPPORTED_PROTOCOL_VERSIONS = [PROTOCOL_VERSION];
+
+const hostStatusSchema = z.enum(['awake', 'asleep']);
+
+const hostPayloadSchema = z.object({
+  name: z.string().min(1),
+  mac: z.string().min(1),
+  ip: z.string().min(1),
+  status: hostStatusSchema,
+  lastSeen: z.string().nullable(),
+  discovered: z.number().int(),
+  pingResponsive: z.number().int().nullable().optional(),
+});
+
+const nodeMetadataSchema = z.object({
+  version: z.string().min(1),
+  platform: z.string().min(1),
+  protocolVersion: z.string().min(1),
+  networkInfo: z.object({
+    subnet: z.string().min(1),
+    gateway: z.string().min(1),
+  }),
+});
+
+const commandResultPayloadSchema = z.object({
+  nodeId: z.string().min(1),
+  commandId: z.string().min(1),
+  success: z.boolean(),
+  message: z.string().optional(),
+  error: z.string().optional(),
+  timestamp: z.coerce.date(),
+});
+
+const outboundNodeMessageSchema = z.discriminatedUnion('type', [
+  z.object({
+    type: z.literal('register'),
+    data: z.object({
+      nodeId: z.string().min(1),
+      name: z.string().min(1),
+      location: z.string().min(1),
+      authToken: z.string().min(1),
+      publicUrl: z.string().optional(),
+      metadata: nodeMetadataSchema,
+    }),
+  }),
+  z.object({
+    type: z.literal('heartbeat'),
+    data: z.object({
+      nodeId: z.string().min(1),
+      timestamp: z.coerce.date(),
+    }),
+  }),
+  z.object({
+    type: z.literal('host-discovered'),
+    data: z
+      .object({
+        nodeId: z.string().min(1),
+      })
+      .merge(hostPayloadSchema),
+  }),
+  z.object({
+    type: z.literal('host-updated'),
+    data: z
+      .object({
+        nodeId: z.string().min(1),
+      })
+      .merge(hostPayloadSchema),
+  }),
+  z.object({
+    type: z.literal('host-removed'),
+    data: z.object({
+      nodeId: z.string().min(1),
+      name: z.string().min(1),
+    }),
+  }),
+  z.object({
+    type: z.literal('scan-complete'),
+    data: z.object({
+      nodeId: z.string().min(1),
+      hostCount: z.number().int().nonnegative(),
+    }),
+  }),
+  z.object({
+    type: z.literal('command-result'),
+    data: commandResultPayloadSchema,
+  }),
+]);
+
+const inboundCncCommandSchema = z.discriminatedUnion('type', [
+  z.object({
+    type: z.literal('registered'),
+    data: z.object({
+      nodeId: z.string().min(1),
+      heartbeatInterval: z.number().int().positive(),
+      protocolVersion: z.string().min(1).optional(),
+    }),
+  }),
+  z.object({
+    type: z.literal('wake'),
+    commandId: z.string().min(1),
+    data: z.object({
+      hostName: z.string().min(1),
+      mac: z.string().min(1),
+    }),
+  }),
+  z.object({
+    type: z.literal('scan'),
+    commandId: z.string().min(1),
+    data: z.object({
+      immediate: z.boolean(),
+    }),
+  }),
+  z.object({
+    type: z.literal('update-host'),
+    commandId: z.string().min(1),
+    data: z.object({
+      currentName: z.string().min(1).optional(),
+      name: z.string().min(1),
+      mac: z.string().min(1).optional(),
+      ip: z.string().min(1).optional(),
+      status: hostStatusSchema.optional(),
+    }),
+  }),
+  z.object({
+    type: z.literal('delete-host'),
+    commandId: z.string().min(1),
+    data: z.object({
+      name: z.string().min(1),
+    }),
+  }),
+  z.object({
+    type: z.literal('ping'),
+    data: z.object({
+      timestamp: z.coerce.date(),
+    }),
+  }),
+  z.object({
+    type: z.literal('error'),
+    message: z.string().min(1),
+  }),
+]);
+
+module.exports = {
+  PROTOCOL_VERSION,
+  SUPPORTED_PROTOCOL_VERSIONS,
+  inboundCncCommandSchema,
+  outboundNodeMessageSchema,
+};

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@kaonis/protocol",
+  "version": "1.0.0",
+  "description": "Shared WoLy node <-> C&C protocol types and runtime schemas",
+  "license": "MIT",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/kaonis/woly-backend.git",
+    "directory": "packages/protocol"
+  },
+  "homepage": "https://github.com/kaonis/woly-backend/tree/master/packages/protocol",
+  "bugs": {
+    "url": "https://github.com/kaonis/woly-backend/issues"
+  },
+  "keywords": [
+    "woly",
+    "protocol",
+    "zod",
+    "websocket"
+  ],
+  "dependencies": {
+    "zod": "^3.24.1"
+  }
+}