From 90a98a4306e0954c07168b518392cafd18fbd978 Mon Sep 17 00:00:00 2001 From: Joshua Oosthuizen Date: Tue, 17 Nov 2026 12:02:24 +0200 Subject: [PATCH] contracts 1.3.0: agent jobs, reports, stats, join/poll, env templates, church export Jobs of fixed types with strict argument schemas, signed by the Hub with Ed25519 over canonical JSON. Agent requests signed with the server's Ed25519 key. Config sealed to the server's X25519 key (X25519 + HKDF + AES-256-GCM; Node has no XSalsa20). Exports encrypted with a key that only travels in the download link. Co-Authored-By: Claude Opus 5.5 --- packages/contracts/package.json | 2 +- packages/contracts/samples/church-export.json | 50 + .../contracts/schemas/agent-job-config.json | 56 + packages/contracts/schemas/agent-job.json | 1325 +++++++++++++++++ .../contracts/schemas/agent-join-request.json | 55 + .../schemas/agent-join-response.json | 31 + .../contracts/schemas/agent-poll-request.json | 39 + .../schemas/agent-poll-response.json | 21 + packages/contracts/schemas/agent-report.json | 136 ++ packages/contracts/schemas/agent-stats.json | 296 ++++ packages/contracts/schemas/church-export.json | 676 +++++++++ packages/contracts/schemas/env-template.json | 74 + packages/contracts/schemas/script-report.json | 104 ++ packages/contracts/scripts/json-schemas.cjs | 11 + packages/contracts/src/agent.ts | 320 ++++ packages/contracts/src/canonical.ts | 24 + packages/contracts/src/church-export.ts | 85 ++ packages/contracts/src/index.ts | 3 + packages/contracts/src/signing.ts | 162 +- packages/contracts/tests/agent.test.ts | 174 +++ packages/contracts/tests/json-schemas.test.ts | 1 + packages/contracts/tests/samples.test.ts | 2 + 22 files changed, 3645 insertions(+), 2 deletions(-) create mode 100644 packages/contracts/samples/church-export.json create mode 100644 packages/contracts/schemas/agent-job-config.json create mode 100644 packages/contracts/schemas/agent-job.json create mode 100644 packages/contracts/schemas/agent-join-request.json create mode 100644 packages/contracts/schemas/agent-join-response.json create mode 100644 packages/contracts/schemas/agent-poll-request.json create mode 100644 packages/contracts/schemas/agent-poll-response.json create mode 100644 packages/contracts/schemas/agent-report.json create mode 100644 packages/contracts/schemas/agent-stats.json create mode 100644 packages/contracts/schemas/church-export.json create mode 100644 packages/contracts/schemas/env-template.json create mode 100644 packages/contracts/schemas/script-report.json create mode 100644 packages/contracts/src/agent.ts create mode 100644 packages/contracts/src/canonical.ts create mode 100644 packages/contracts/src/church-export.ts create mode 100644 packages/contracts/tests/agent.test.ts diff --git a/packages/contracts/package.json b/packages/contracts/package.json index 907c5fd..3b399c8 100644 --- a/packages/contracts/package.json +++ b/packages/contracts/package.json @@ -1,6 +1,6 @@ { "name": "@crosscode/contracts", - "version": "1.2.0", + "version": "1.3.0", "description": "The shared JSON formats used by every Cross Code product: zod schemas, JSON Schema, TypeScript types and sample payloads", "license": "UNLICENSED", "type": "commonjs", diff --git a/packages/contracts/samples/church-export.json b/packages/contracts/samples/church-export.json new file mode 100644 index 0000000..1245775 --- /dev/null +++ b/packages/contracts/samples/church-export.json @@ -0,0 +1,50 @@ +{ + "schema": "crosscode.church-export/1", + "exportedAt": "2026-11-20T12:00:00.000Z", + "product": "events", + "productVersion": "2.3.0", + "church": { "name": "Grace Demo Church", "timezone": "Africa/Johannesburg" }, + "people": [ + { + "ref": "p1", + "name": "Thandi Example", + "email": "thandi@example.org", + "phone": "+27821234567", + "role": "admin", + "createdAt": "2026-01-10T08:00:00.000Z", + "consent": { "email": true, "whatsapp": false, "privacyNoticeAcceptedAt": "2026-01-10T08:00:00.000Z" } + } + ], + "events": [ + { + "ref": "e1", + "title": "Youth Camp", + "description": "A weekend away.", + "startsAt": "2026-12-04T16:00:00.000Z", + "endsAt": "2026-12-06T12:00:00.000Z", + "location": "Camp Example", + "sessions": [{ "label": "Friday", "startsAt": "2026-12-04T16:00:00.000Z", "endsAt": "2026-12-04T21:00:00.000Z" }], + "ticketTypes": [{ "ref": "t1", "name": "Camper", "priceCents": 60000, "currency": "ZAR" }], + "capacity": 80, + "published": true + } + ], + "registrations": [ + { + "ref": "r1", + "eventRef": "e1", + "personRef": "p1", + "status": "confirmed", + "createdAt": "2026-11-01T09:00:00.000Z", + "attendees": [{ "name": "Thandi Example", "email": "thandi@example.org", "ticketTypeRef": "t1", "checkedInAt": null }], + "answers": [{ "question": "Dietary needs", "answer": "None" }] + } + ], + "payments": [ + { "registrationRef": "r1", "amountCents": 60000, "currency": "ZAR", "method": "card", "status": "paid", "paidAt": "2026-11-01T09:05:00.000Z", "reference": "YOCO-123" } + ], + "checkIns": [], + "rosters": [{ "eventRef": "e1", "role": "Kitchen", "personRef": "p1", "startsAt": null, "endsAt": null }], + "settings": { "org_name": "Grace Demo Church" }, + "files": [{ "path": "uploads/events/camp.jpg", "bytes": 120400 }] +} diff --git a/packages/contracts/schemas/agent-job-config.json b/packages/contracts/schemas/agent-job-config.json new file mode 100644 index 0000000..7f3c330 --- /dev/null +++ b/packages/contracts/schemas/agent-job-config.json @@ -0,0 +1,56 @@ +{ + "$id": "https://c-git.crosscode.co.za/joshua/crosscode-platform/raw/branch/main/packages/contracts/schemas/agent-job-config.json", + "$schema": "https://json-schema.org/draft/2020-12/schema", + "type": "object", + "properties": { + "server": { + "default": {}, + "type": "object", + "propertyNames": { + "type": "string", + "pattern": "^[A-Z][A-Z0-9_]*$" + }, + "additionalProperties": { + "type": "string", + "maxLength": 4000 + } + }, + "defaults": { + "default": {}, + "type": "object", + "propertyNames": { + "type": "string", + "pattern": "^[A-Z][A-Z0-9_]*$" + }, + "additionalProperties": { + "type": "string", + "maxLength": 4000 + } + }, + "install": { + "default": {}, + "type": "object", + "propertyNames": { + "type": "string", + "enum": [ + "events", + "website", + "app", + "accounts" + ] + }, + "additionalProperties": { + "type": "object", + "propertyNames": { + "type": "string", + "pattern": "^[A-Z][A-Z0-9_]*$" + }, + "additionalProperties": { + "type": "string", + "maxLength": 4000 + } + } + } + }, + "additionalProperties": false +} diff --git a/packages/contracts/schemas/agent-job.json b/packages/contracts/schemas/agent-job.json new file mode 100644 index 0000000..24a3d2d --- /dev/null +++ b/packages/contracts/schemas/agent-job.json @@ -0,0 +1,1325 @@ +{ + "$id": "https://c-git.crosscode.co.za/joshua/crosscode-platform/raw/branch/main/packages/contracts/schemas/agent-job.json", + "$schema": "https://json-schema.org/draft/2020-12/schema", + "oneOf": [ + { + "type": "object", + "properties": { + "schema": { + "type": "string", + "const": "crosscode.agent-job/1" + }, + "id": { + "type": "string", + "pattern": "^job_[A-Za-z0-9_-]{8,64}$" + }, + "serverId": { + "type": "string", + "pattern": "^srv_[A-Za-z0-9_-]{8,64}$" + }, + "config": { + "anyOf": [ + { + "type": "object", + "properties": { + "alg": { + "type": "string", + "const": "x25519-hkdf-sha256-aes-256-gcm" + }, + "epk": { + "type": "string", + "pattern": "^[A-Za-z0-9_-]{43}$" + }, + "iv": { + "type": "string", + "pattern": "^[A-Za-z0-9_-]{16}$" + }, + "ciphertext": { + "type": "string", + "maxLength": 200000, + "pattern": "^[A-Za-z0-9_-]+$" + } + }, + "required": [ + "alg", + "epk", + "iv", + "ciphertext" + ], + "additionalProperties": false + }, + { + "type": "null" + } + ] + }, + "notBefore": { + "type": "string", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" + }, + "expiresAt": { + "type": "string", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" + }, + "signature": { + "type": "string", + "pattern": "^[A-Za-z0-9_-]{86}$" + }, + "type": { + "type": "string", + "const": "install" + }, + "args": { + "type": "object", + "properties": { + "church": { + "type": "string", + "pattern": "^[a-z][a-z0-9-]{1,30}$" + }, + "products": { + "minItems": 1, + "maxItems": 4, + "type": "array", + "items": { + "type": "string", + "enum": [ + "events", + "website", + "app", + "accounts" + ] + } + }, + "versions": { + "type": "object", + "propertyNames": { + "type": "string", + "enum": [ + "events", + "website", + "app", + "accounts" + ] + }, + "additionalProperties": { + "type": "string", + "pattern": "^(accounts|events|website|app)@\\d+\\.\\d+\\.\\d+$" + } + }, + "domains": { + "type": "object", + "propertyNames": { + "type": "string", + "enum": [ + "events", + "website", + "app", + "accounts" + ] + }, + "additionalProperties": { + "type": "string", + "maxLength": 253, + "pattern": "^(?=.{1,253}$)([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z]{2,}$" + } + }, + "ports": { + "type": "object", + "propertyNames": { + "type": "string", + "enum": [ + "events", + "website", + "app", + "accounts" + ] + }, + "additionalProperties": { + "type": "object", + "properties": { + "web": { + "type": "integer", + "minimum": 1024, + "maximum": 65535 + }, + "api": { + "type": "integer", + "minimum": 1024, + "maximum": 65535 + } + }, + "required": [ + "web", + "api" + ] + } + } + }, + "required": [ + "church", + "products", + "domains", + "ports" + ], + "additionalProperties": false + } + }, + "required": [ + "schema", + "id", + "serverId", + "notBefore", + "expiresAt", + "signature", + "type", + "args" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "schema": { + "type": "string", + "const": "crosscode.agent-job/1" + }, + "id": { + "type": "string", + "pattern": "^job_[A-Za-z0-9_-]{8,64}$" + }, + "serverId": { + "type": "string", + "pattern": "^srv_[A-Za-z0-9_-]{8,64}$" + }, + "config": { + "anyOf": [ + { + "type": "object", + "properties": { + "alg": { + "type": "string", + "const": "x25519-hkdf-sha256-aes-256-gcm" + }, + "epk": { + "type": "string", + "pattern": "^[A-Za-z0-9_-]{43}$" + }, + "iv": { + "type": "string", + "pattern": "^[A-Za-z0-9_-]{16}$" + }, + "ciphertext": { + "type": "string", + "maxLength": 200000, + "pattern": "^[A-Za-z0-9_-]+$" + } + }, + "required": [ + "alg", + "epk", + "iv", + "ciphertext" + ], + "additionalProperties": false + }, + { + "type": "null" + } + ] + }, + "notBefore": { + "type": "string", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" + }, + "expiresAt": { + "type": "string", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" + }, + "signature": { + "type": "string", + "pattern": "^[A-Za-z0-9_-]{86}$" + }, + "type": { + "type": "string", + "const": "add-product" + }, + "args": { + "type": "object", + "properties": { + "church": { + "type": "string", + "pattern": "^[a-z][a-z0-9-]{1,30}$" + }, + "product": { + "type": "string", + "enum": [ + "events", + "website", + "app", + "accounts" + ] + }, + "version": { + "type": "string", + "pattern": "^(accounts|events|website|app)@\\d+\\.\\d+\\.\\d+$" + }, + "domain": { + "type": "string", + "maxLength": 253, + "pattern": "^(?=.{1,253}$)([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z]{2,}$" + }, + "ports": { + "type": "object", + "properties": { + "web": { + "type": "integer", + "minimum": 1024, + "maximum": 65535 + }, + "api": { + "type": "integer", + "minimum": 1024, + "maximum": 65535 + } + }, + "required": [ + "web", + "api" + ] + } + }, + "required": [ + "church", + "product", + "domain", + "ports" + ], + "additionalProperties": false + } + }, + "required": [ + "schema", + "id", + "serverId", + "notBefore", + "expiresAt", + "signature", + "type", + "args" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "schema": { + "type": "string", + "const": "crosscode.agent-job/1" + }, + "id": { + "type": "string", + "pattern": "^job_[A-Za-z0-9_-]{8,64}$" + }, + "serverId": { + "type": "string", + "pattern": "^srv_[A-Za-z0-9_-]{8,64}$" + }, + "config": { + "anyOf": [ + { + "type": "object", + "properties": { + "alg": { + "type": "string", + "const": "x25519-hkdf-sha256-aes-256-gcm" + }, + "epk": { + "type": "string", + "pattern": "^[A-Za-z0-9_-]{43}$" + }, + "iv": { + "type": "string", + "pattern": "^[A-Za-z0-9_-]{16}$" + }, + "ciphertext": { + "type": "string", + "maxLength": 200000, + "pattern": "^[A-Za-z0-9_-]+$" + } + }, + "required": [ + "alg", + "epk", + "iv", + "ciphertext" + ], + "additionalProperties": false + }, + { + "type": "null" + } + ] + }, + "notBefore": { + "type": "string", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" + }, + "expiresAt": { + "type": "string", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" + }, + "signature": { + "type": "string", + "pattern": "^[A-Za-z0-9_-]{86}$" + }, + "type": { + "type": "string", + "const": "deploy" + }, + "args": { + "type": "object", + "properties": { + "church": { + "type": "string", + "pattern": "^[a-z][a-z0-9-]{1,30}$" + }, + "products": { + "minItems": 1, + "maxItems": 4, + "type": "array", + "items": { + "type": "string", + "enum": [ + "events", + "website", + "app", + "accounts" + ] + } + }, + "versions": { + "maxItems": 4, + "type": "array", + "items": { + "type": "string", + "pattern": "^(accounts|events|website|app)@\\d+\\.\\d+\\.\\d+$" + } + }, + "check": { + "type": "boolean" + } + }, + "required": [ + "church", + "products" + ], + "additionalProperties": false + } + }, + "required": [ + "schema", + "id", + "serverId", + "notBefore", + "expiresAt", + "signature", + "type", + "args" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "schema": { + "type": "string", + "const": "crosscode.agent-job/1" + }, + "id": { + "type": "string", + "pattern": "^job_[A-Za-z0-9_-]{8,64}$" + }, + "serverId": { + "type": "string", + "pattern": "^srv_[A-Za-z0-9_-]{8,64}$" + }, + "config": { + "anyOf": [ + { + "type": "object", + "properties": { + "alg": { + "type": "string", + "const": "x25519-hkdf-sha256-aes-256-gcm" + }, + "epk": { + "type": "string", + "pattern": "^[A-Za-z0-9_-]{43}$" + }, + "iv": { + "type": "string", + "pattern": "^[A-Za-z0-9_-]{16}$" + }, + "ciphertext": { + "type": "string", + "maxLength": 200000, + "pattern": "^[A-Za-z0-9_-]+$" + } + }, + "required": [ + "alg", + "epk", + "iv", + "ciphertext" + ], + "additionalProperties": false + }, + { + "type": "null" + } + ] + }, + "notBefore": { + "type": "string", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" + }, + "expiresAt": { + "type": "string", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" + }, + "signature": { + "type": "string", + "pattern": "^[A-Za-z0-9_-]{86}$" + }, + "type": { + "type": "string", + "const": "adopt" + }, + "args": { + "type": "object", + "properties": { + "church": { + "type": "string", + "pattern": "^[a-z][a-z0-9-]{1,30}$" + }, + "eventsDir": { + "type": "string", + "maxLength": 255, + "pattern": "^\\/(?!.*\\/\\.\\.?(\\/|$))[A-Za-z0-9._/-]+$" + }, + "version": { + "type": "string", + "pattern": "^(accounts|events|website|app)@\\d+\\.\\d+\\.\\d+$" + }, + "address": { + "type": "string", + "maxLength": 253, + "pattern": "^(?=.{1,253}$)([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z]{2,}$" + } + }, + "required": [ + "church", + "eventsDir" + ], + "additionalProperties": false + } + }, + "required": [ + "schema", + "id", + "serverId", + "notBefore", + "expiresAt", + "signature", + "type", + "args" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "schema": { + "type": "string", + "const": "crosscode.agent-job/1" + }, + "id": { + "type": "string", + "pattern": "^job_[A-Za-z0-9_-]{8,64}$" + }, + "serverId": { + "type": "string", + "pattern": "^srv_[A-Za-z0-9_-]{8,64}$" + }, + "config": { + "anyOf": [ + { + "type": "object", + "properties": { + "alg": { + "type": "string", + "const": "x25519-hkdf-sha256-aes-256-gcm" + }, + "epk": { + "type": "string", + "pattern": "^[A-Za-z0-9_-]{43}$" + }, + "iv": { + "type": "string", + "pattern": "^[A-Za-z0-9_-]{16}$" + }, + "ciphertext": { + "type": "string", + "maxLength": 200000, + "pattern": "^[A-Za-z0-9_-]+$" + } + }, + "required": [ + "alg", + "epk", + "iv", + "ciphertext" + ], + "additionalProperties": false + }, + { + "type": "null" + } + ] + }, + "notBefore": { + "type": "string", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" + }, + "expiresAt": { + "type": "string", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" + }, + "signature": { + "type": "string", + "pattern": "^[A-Za-z0-9_-]{86}$" + }, + "type": { + "type": "string", + "const": "adopt-undo" + }, + "args": { + "type": "object", + "properties": { + "church": { + "type": "string", + "pattern": "^[a-z][a-z0-9-]{1,30}$" + } + }, + "required": [ + "church" + ], + "additionalProperties": false + } + }, + "required": [ + "schema", + "id", + "serverId", + "notBefore", + "expiresAt", + "signature", + "type", + "args" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "schema": { + "type": "string", + "const": "crosscode.agent-job/1" + }, + "id": { + "type": "string", + "pattern": "^job_[A-Za-z0-9_-]{8,64}$" + }, + "serverId": { + "type": "string", + "pattern": "^srv_[A-Za-z0-9_-]{8,64}$" + }, + "config": { + "anyOf": [ + { + "type": "object", + "properties": { + "alg": { + "type": "string", + "const": "x25519-hkdf-sha256-aes-256-gcm" + }, + "epk": { + "type": "string", + "pattern": "^[A-Za-z0-9_-]{43}$" + }, + "iv": { + "type": "string", + "pattern": "^[A-Za-z0-9_-]{16}$" + }, + "ciphertext": { + "type": "string", + "maxLength": 200000, + "pattern": "^[A-Za-z0-9_-]+$" + } + }, + "required": [ + "alg", + "epk", + "iv", + "ciphertext" + ], + "additionalProperties": false + }, + { + "type": "null" + } + ] + }, + "notBefore": { + "type": "string", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" + }, + "expiresAt": { + "type": "string", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" + }, + "signature": { + "type": "string", + "pattern": "^[A-Za-z0-9_-]{86}$" + }, + "type": { + "type": "string", + "const": "restart" + }, + "args": { + "type": "object", + "properties": { + "church": { + "type": "string", + "pattern": "^[a-z][a-z0-9-]{1,30}$" + }, + "product": { + "type": "string", + "enum": [ + "events", + "website", + "app", + "accounts" + ] + } + }, + "required": [ + "church" + ], + "additionalProperties": false + } + }, + "required": [ + "schema", + "id", + "serverId", + "notBefore", + "expiresAt", + "signature", + "type", + "args" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "schema": { + "type": "string", + "const": "crosscode.agent-job/1" + }, + "id": { + "type": "string", + "pattern": "^job_[A-Za-z0-9_-]{8,64}$" + }, + "serverId": { + "type": "string", + "pattern": "^srv_[A-Za-z0-9_-]{8,64}$" + }, + "config": { + "anyOf": [ + { + "type": "object", + "properties": { + "alg": { + "type": "string", + "const": "x25519-hkdf-sha256-aes-256-gcm" + }, + "epk": { + "type": "string", + "pattern": "^[A-Za-z0-9_-]{43}$" + }, + "iv": { + "type": "string", + "pattern": "^[A-Za-z0-9_-]{16}$" + }, + "ciphertext": { + "type": "string", + "maxLength": 200000, + "pattern": "^[A-Za-z0-9_-]+$" + } + }, + "required": [ + "alg", + "epk", + "iv", + "ciphertext" + ], + "additionalProperties": false + }, + { + "type": "null" + } + ] + }, + "notBefore": { + "type": "string", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" + }, + "expiresAt": { + "type": "string", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" + }, + "signature": { + "type": "string", + "pattern": "^[A-Za-z0-9_-]{86}$" + }, + "type": { + "type": "string", + "const": "export" + }, + "args": { + "type": "object", + "properties": { + "church": { + "type": "string", + "pattern": "^[a-z][a-z0-9-]{1,30}$" + }, + "exportId": { + "type": "string", + "pattern": "^exp_[A-Za-z0-9_-]{8,64}$" + } + }, + "required": [ + "church", + "exportId" + ], + "additionalProperties": false + } + }, + "required": [ + "schema", + "id", + "serverId", + "notBefore", + "expiresAt", + "signature", + "type", + "args" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "schema": { + "type": "string", + "const": "crosscode.agent-job/1" + }, + "id": { + "type": "string", + "pattern": "^job_[A-Za-z0-9_-]{8,64}$" + }, + "serverId": { + "type": "string", + "pattern": "^srv_[A-Za-z0-9_-]{8,64}$" + }, + "config": { + "anyOf": [ + { + "type": "object", + "properties": { + "alg": { + "type": "string", + "const": "x25519-hkdf-sha256-aes-256-gcm" + }, + "epk": { + "type": "string", + "pattern": "^[A-Za-z0-9_-]{43}$" + }, + "iv": { + "type": "string", + "pattern": "^[A-Za-z0-9_-]{16}$" + }, + "ciphertext": { + "type": "string", + "maxLength": 200000, + "pattern": "^[A-Za-z0-9_-]+$" + } + }, + "required": [ + "alg", + "epk", + "iv", + "ciphertext" + ], + "additionalProperties": false + }, + { + "type": "null" + } + ] + }, + "notBefore": { + "type": "string", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" + }, + "expiresAt": { + "type": "string", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" + }, + "signature": { + "type": "string", + "pattern": "^[A-Za-z0-9_-]{86}$" + }, + "type": { + "type": "string", + "const": "uninstall" + }, + "args": { + "type": "object", + "properties": { + "church": { + "type": "string", + "pattern": "^[a-z][a-z0-9-]{1,30}$" + } + }, + "required": [ + "church" + ], + "additionalProperties": false + } + }, + "required": [ + "schema", + "id", + "serverId", + "notBefore", + "expiresAt", + "signature", + "type", + "args" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "schema": { + "type": "string", + "const": "crosscode.agent-job/1" + }, + "id": { + "type": "string", + "pattern": "^job_[A-Za-z0-9_-]{8,64}$" + }, + "serverId": { + "type": "string", + "pattern": "^srv_[A-Za-z0-9_-]{8,64}$" + }, + "config": { + "anyOf": [ + { + "type": "object", + "properties": { + "alg": { + "type": "string", + "const": "x25519-hkdf-sha256-aes-256-gcm" + }, + "epk": { + "type": "string", + "pattern": "^[A-Za-z0-9_-]{43}$" + }, + "iv": { + "type": "string", + "pattern": "^[A-Za-z0-9_-]{16}$" + }, + "ciphertext": { + "type": "string", + "maxLength": 200000, + "pattern": "^[A-Za-z0-9_-]+$" + } + }, + "required": [ + "alg", + "epk", + "iv", + "ciphertext" + ], + "additionalProperties": false + }, + { + "type": "null" + } + ] + }, + "notBefore": { + "type": "string", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" + }, + "expiresAt": { + "type": "string", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" + }, + "signature": { + "type": "string", + "pattern": "^[A-Za-z0-9_-]{86}$" + }, + "type": { + "type": "string", + "const": "purge" + }, + "args": { + "type": "object", + "properties": { + "church": { + "type": "string", + "pattern": "^[a-z][a-z0-9-]{1,30}$" + } + }, + "required": [ + "church" + ], + "additionalProperties": false + } + }, + "required": [ + "schema", + "id", + "serverId", + "notBefore", + "expiresAt", + "signature", + "type", + "args" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "schema": { + "type": "string", + "const": "crosscode.agent-job/1" + }, + "id": { + "type": "string", + "pattern": "^job_[A-Za-z0-9_-]{8,64}$" + }, + "serverId": { + "type": "string", + "pattern": "^srv_[A-Za-z0-9_-]{8,64}$" + }, + "config": { + "anyOf": [ + { + "type": "object", + "properties": { + "alg": { + "type": "string", + "const": "x25519-hkdf-sha256-aes-256-gcm" + }, + "epk": { + "type": "string", + "pattern": "^[A-Za-z0-9_-]{43}$" + }, + "iv": { + "type": "string", + "pattern": "^[A-Za-z0-9_-]{16}$" + }, + "ciphertext": { + "type": "string", + "maxLength": 200000, + "pattern": "^[A-Za-z0-9_-]+$" + } + }, + "required": [ + "alg", + "epk", + "iv", + "ciphertext" + ], + "additionalProperties": false + }, + { + "type": "null" + } + ] + }, + "notBefore": { + "type": "string", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" + }, + "expiresAt": { + "type": "string", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" + }, + "signature": { + "type": "string", + "pattern": "^[A-Za-z0-9_-]{86}$" + }, + "type": { + "type": "string", + "const": "update-agent" + }, + "args": { + "type": "object", + "properties": { + "version": { + "type": "string", + "pattern": "^agent@\\d+\\.\\d+\\.\\d+$" + } + }, + "required": [ + "version" + ], + "additionalProperties": false + } + }, + "required": [ + "schema", + "id", + "serverId", + "notBefore", + "expiresAt", + "signature", + "type", + "args" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "schema": { + "type": "string", + "const": "crosscode.agent-job/1" + }, + "id": { + "type": "string", + "pattern": "^job_[A-Za-z0-9_-]{8,64}$" + }, + "serverId": { + "type": "string", + "pattern": "^srv_[A-Za-z0-9_-]{8,64}$" + }, + "config": { + "anyOf": [ + { + "type": "object", + "properties": { + "alg": { + "type": "string", + "const": "x25519-hkdf-sha256-aes-256-gcm" + }, + "epk": { + "type": "string", + "pattern": "^[A-Za-z0-9_-]{43}$" + }, + "iv": { + "type": "string", + "pattern": "^[A-Za-z0-9_-]{16}$" + }, + "ciphertext": { + "type": "string", + "maxLength": 200000, + "pattern": "^[A-Za-z0-9_-]+$" + } + }, + "required": [ + "alg", + "epk", + "iv", + "ciphertext" + ], + "additionalProperties": false + }, + { + "type": "null" + } + ] + }, + "notBefore": { + "type": "string", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" + }, + "expiresAt": { + "type": "string", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" + }, + "signature": { + "type": "string", + "pattern": "^[A-Za-z0-9_-]{86}$" + }, + "type": { + "type": "string", + "const": "check-ports" + }, + "args": { + "type": "object", + "properties": { + "ports": { + "minItems": 1, + "maxItems": 50, + "type": "array", + "items": { + "type": "integer", + "minimum": 1024, + "maximum": 65535 + } + } + }, + "required": [ + "ports" + ], + "additionalProperties": false + } + }, + "required": [ + "schema", + "id", + "serverId", + "notBefore", + "expiresAt", + "signature", + "type", + "args" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "schema": { + "type": "string", + "const": "crosscode.agent-job/1" + }, + "id": { + "type": "string", + "pattern": "^job_[A-Za-z0-9_-]{8,64}$" + }, + "serverId": { + "type": "string", + "pattern": "^srv_[A-Za-z0-9_-]{8,64}$" + }, + "config": { + "anyOf": [ + { + "type": "object", + "properties": { + "alg": { + "type": "string", + "const": "x25519-hkdf-sha256-aes-256-gcm" + }, + "epk": { + "type": "string", + "pattern": "^[A-Za-z0-9_-]{43}$" + }, + "iv": { + "type": "string", + "pattern": "^[A-Za-z0-9_-]{16}$" + }, + "ciphertext": { + "type": "string", + "maxLength": 200000, + "pattern": "^[A-Za-z0-9_-]+$" + } + }, + "required": [ + "alg", + "epk", + "iv", + "ciphertext" + ], + "additionalProperties": false + }, + { + "type": "null" + } + ] + }, + "notBefore": { + "type": "string", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" + }, + "expiresAt": { + "type": "string", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" + }, + "signature": { + "type": "string", + "pattern": "^[A-Za-z0-9_-]{86}$" + }, + "type": { + "type": "string", + "const": "status" + }, + "args": { + "type": "object", + "properties": { + "church": { + "type": "string", + "pattern": "^[a-z][a-z0-9-]{1,30}$" + } + }, + "additionalProperties": false + } + }, + "required": [ + "schema", + "id", + "serverId", + "notBefore", + "expiresAt", + "signature", + "type", + "args" + ], + "additionalProperties": false + } + ] +} diff --git a/packages/contracts/schemas/agent-join-request.json b/packages/contracts/schemas/agent-join-request.json new file mode 100644 index 0000000..cc1ae55 --- /dev/null +++ b/packages/contracts/schemas/agent-join-request.json @@ -0,0 +1,55 @@ +{ + "$id": "https://c-git.crosscode.co.za/joshua/crosscode-platform/raw/branch/main/packages/contracts/schemas/agent-join-request.json", + "$schema": "https://json-schema.org/draft/2020-12/schema", + "type": "object", + "properties": { + "agentApiVersion": { + "type": "number", + "const": 1 + }, + "token": { + "type": "string", + "pattern": "^[A-Za-z0-9_-]{32,128}$" + }, + "mode": { + "type": "string", + "enum": [ + "church", + "central" + ] + }, + "hostname": { + "type": "string", + "maxLength": 253 + }, + "agentVersion": { + "type": "string", + "maxLength": 40 + }, + "publicKeys": { + "type": "object", + "properties": { + "ed25519": { + "type": "string", + "pattern": "^[A-Za-z0-9_-]{43}$" + }, + "x25519": { + "type": "string", + "pattern": "^[A-Za-z0-9_-]{43}$" + } + }, + "required": [ + "ed25519", + "x25519" + ] + } + }, + "required": [ + "agentApiVersion", + "token", + "mode", + "hostname", + "agentVersion", + "publicKeys" + ] +} diff --git a/packages/contracts/schemas/agent-join-response.json b/packages/contracts/schemas/agent-join-response.json new file mode 100644 index 0000000..848ee56 --- /dev/null +++ b/packages/contracts/schemas/agent-join-response.json @@ -0,0 +1,31 @@ +{ + "$id": "https://c-git.crosscode.co.za/joshua/crosscode-platform/raw/branch/main/packages/contracts/schemas/agent-join-response.json", + "$schema": "https://json-schema.org/draft/2020-12/schema", + "type": "object", + "properties": { + "serverId": { + "type": "string", + "pattern": "^srv_[A-Za-z0-9_-]{8,64}$" + }, + "hubJobKey": { + "type": "string", + "pattern": "^[A-Za-z0-9_-]{43}$" + }, + "pollSeconds": { + "type": "integer", + "minimum": 5, + "maximum": 600 + }, + "statsSeconds": { + "type": "integer", + "minimum": 15, + "maximum": 3600 + } + }, + "required": [ + "serverId", + "hubJobKey", + "pollSeconds", + "statsSeconds" + ] +} diff --git a/packages/contracts/schemas/agent-poll-request.json b/packages/contracts/schemas/agent-poll-request.json new file mode 100644 index 0000000..dcb4ad9 --- /dev/null +++ b/packages/contracts/schemas/agent-poll-request.json @@ -0,0 +1,39 @@ +{ + "$id": "https://c-git.crosscode.co.za/joshua/crosscode-platform/raw/branch/main/packages/contracts/schemas/agent-poll-request.json", + "$schema": "https://json-schema.org/draft/2020-12/schema", + "type": "object", + "properties": { + "agentApiVersion": { + "type": "number", + "const": 1 + }, + "agentVersion": { + "type": "string", + "maxLength": 40 + }, + "mode": { + "type": "string", + "enum": [ + "church", + "central" + ] + }, + "runningJobId": { + "anyOf": [ + { + "type": "string", + "pattern": "^job_[A-Za-z0-9_-]{8,64}$" + }, + { + "type": "null" + } + ] + } + }, + "required": [ + "agentApiVersion", + "agentVersion", + "mode", + "runningJobId" + ] +} diff --git a/packages/contracts/schemas/agent-poll-response.json b/packages/contracts/schemas/agent-poll-response.json new file mode 100644 index 0000000..b718cf3 --- /dev/null +++ b/packages/contracts/schemas/agent-poll-response.json @@ -0,0 +1,21 @@ +{ + "$id": "https://c-git.crosscode.co.za/joshua/crosscode-platform/raw/branch/main/packages/contracts/schemas/agent-poll-response.json", + "$schema": "https://json-schema.org/draft/2020-12/schema", + "type": "object", + "properties": { + "jobs": { + "maxItems": 10, + "type": "array", + "items": {} + }, + "pollSeconds": { + "type": "integer", + "minimum": 5, + "maximum": 600 + } + }, + "required": [ + "jobs", + "pollSeconds" + ] +} diff --git a/packages/contracts/schemas/agent-report.json b/packages/contracts/schemas/agent-report.json new file mode 100644 index 0000000..d4d320d --- /dev/null +++ b/packages/contracts/schemas/agent-report.json @@ -0,0 +1,136 @@ +{ + "$id": "https://c-git.crosscode.co.za/joshua/crosscode-platform/raw/branch/main/packages/contracts/schemas/agent-report.json", + "$schema": "https://json-schema.org/draft/2020-12/schema", + "type": "object", + "properties": { + "schema": { + "type": "string", + "const": "crosscode.agent-report/1" + }, + "jobId": { + "type": "string", + "pattern": "^job_[A-Za-z0-9_-]{8,64}$" + }, + "serverId": { + "type": "string", + "pattern": "^srv_[A-Za-z0-9_-]{8,64}$" + }, + "type": { + "type": "string", + "enum": [ + "install", + "add-product", + "deploy", + "adopt", + "adopt-undo", + "restart", + "export", + "uninstall", + "purge", + "update-agent", + "check-ports", + "status" + ] + }, + "status": { + "type": "string", + "enum": [ + "succeeded", + "failed", + "rolled-back", + "refused", + "expired" + ] + }, + "startedAt": { + "type": "string", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" + }, + "finishedAt": { + "type": "string", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" + }, + "steps": { + "maxItems": 200, + "type": "array", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "maxLength": 200 + }, + "startedAt": { + "type": "string", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" + }, + "finishedAt": { + "anyOf": [ + { + "type": "string", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" + }, + { + "type": "null" + } + ] + }, + "outcome": { + "type": "string", + "enum": [ + "ok", + "failed", + "skipped", + "rolled-back" + ] + }, + "detail": { + "type": "string", + "maxLength": 2000 + } + }, + "required": [ + "name", + "startedAt", + "finishedAt", + "outcome" + ] + } + }, + "result": { + "default": {}, + "type": "object", + "propertyNames": { + "type": "string" + }, + "additionalProperties": {} + }, + "message": { + "type": "string", + "maxLength": 2000 + }, + "log": { + "maxItems": 200, + "type": "array", + "items": { + "type": "string", + "maxLength": 1000 + } + } + }, + "required": [ + "schema", + "jobId", + "serverId", + "type", + "status", + "startedAt", + "finishedAt", + "steps", + "log" + ] +} diff --git a/packages/contracts/schemas/agent-stats.json b/packages/contracts/schemas/agent-stats.json new file mode 100644 index 0000000..901bcc0 --- /dev/null +++ b/packages/contracts/schemas/agent-stats.json @@ -0,0 +1,296 @@ +{ + "$id": "https://c-git.crosscode.co.za/joshua/crosscode-platform/raw/branch/main/packages/contracts/schemas/agent-stats.json", + "$schema": "https://json-schema.org/draft/2020-12/schema", + "type": "object", + "properties": { + "schema": { + "type": "string", + "const": "crosscode.agent-stats/1" + }, + "at": { + "type": "string", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" + }, + "ram": { + "type": "object", + "properties": { + "totalBytes": { + "type": "number", + "minimum": 0 + }, + "usedBytes": { + "type": "number", + "minimum": 0 + }, + "availableBytes": { + "type": "number", + "minimum": 0 + }, + "swapTotalBytes": { + "type": "number", + "minimum": 0 + }, + "swapUsedBytes": { + "type": "number", + "minimum": 0 + } + }, + "required": [ + "totalBytes", + "usedBytes", + "availableBytes", + "swapTotalBytes", + "swapUsedBytes" + ] + }, + "cpu": { + "type": "object", + "properties": { + "percent": { + "type": "number", + "minimum": 0, + "maximum": 100 + }, + "load1": { + "type": "number", + "minimum": 0 + }, + "load5": { + "type": "number", + "minimum": 0 + }, + "load15": { + "type": "number", + "minimum": 0 + }, + "cores": { + "type": "integer", + "exclusiveMinimum": 0, + "maximum": 9007199254740991 + } + }, + "required": [ + "percent", + "load1", + "load5", + "load15", + "cores" + ] + }, + "disks": { + "maxItems": 30, + "type": "array", + "items": { + "type": "object", + "properties": { + "mount": { + "type": "string", + "maxLength": 255 + }, + "totalBytes": { + "type": "number", + "minimum": 0 + }, + "usedBytes": { + "type": "number", + "minimum": 0 + }, + "freeBytes": { + "type": "number", + "minimum": 0 + } + }, + "required": [ + "mount", + "totalBytes", + "usedBytes", + "freeBytes" + ] + } + }, + "uptimeSeconds": { + "type": "number", + "minimum": 0 + }, + "versions": { + "type": "object", + "properties": { + "os": { + "type": "string", + "maxLength": 200 + }, + "node": { + "type": "string", + "maxLength": 40 + }, + "postgres": { + "anyOf": [ + { + "type": "string", + "maxLength": 40 + }, + { + "type": "null" + } + ] + }, + "frpc": { + "anyOf": [ + { + "type": "string", + "maxLength": 40 + }, + { + "type": "null" + } + ] + }, + "agent": { + "type": "string", + "maxLength": 40 + } + }, + "required": [ + "os", + "node", + "postgres", + "frpc", + "agent" + ] + }, + "frpcRunning": { + "type": [ + "boolean", + "null" + ] + }, + "processes": { + "maxItems": 200, + "type": "array", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "maxLength": 100 + }, + "church": { + "anyOf": [ + { + "type": "string", + "pattern": "^[a-z][a-z0-9-]{1,30}$" + }, + { + "type": "null" + } + ] + }, + "product": { + "anyOf": [ + { + "type": "string", + "enum": [ + "events", + "website", + "app", + "accounts" + ] + }, + { + "type": "null" + } + ] + }, + "status": { + "type": "string", + "maxLength": 40 + }, + "memoryBytes": { + "type": "number", + "minimum": 0 + }, + "cpuPercent": { + "type": "number", + "minimum": 0 + }, + "restarts": { + "type": "integer", + "minimum": 0, + "maximum": 9007199254740991 + }, + "uptimeSeconds": { + "type": "number", + "minimum": 0 + } + }, + "required": [ + "name", + "church", + "product", + "status", + "memoryBytes", + "cpuPercent", + "restarts", + "uptimeSeconds" + ] + } + }, + "central": { + "anyOf": [ + { + "type": "object", + "properties": { + "proxyBindAddr": { + "anyOf": [ + { + "type": "string", + "maxLength": 100 + }, + { + "type": "null" + } + ] + }, + "allowPorts": { + "anyOf": [ + { + "type": "string", + "maxLength": 2000 + }, + { + "type": "null" + } + ] + }, + "frpsRunning": { + "type": [ + "boolean", + "null" + ] + } + }, + "required": [ + "proxyBindAddr", + "allowPorts", + "frpsRunning" + ] + }, + { + "type": "null" + } + ] + } + }, + "required": [ + "schema", + "at", + "ram", + "cpu", + "disks", + "uptimeSeconds", + "versions", + "frpcRunning", + "processes" + ] +} diff --git a/packages/contracts/schemas/church-export.json b/packages/contracts/schemas/church-export.json new file mode 100644 index 0000000..b2743d5 --- /dev/null +++ b/packages/contracts/schemas/church-export.json @@ -0,0 +1,676 @@ +{ + "$id": "https://c-git.crosscode.co.za/joshua/crosscode-platform/raw/branch/main/packages/contracts/schemas/church-export.json", + "$schema": "https://json-schema.org/draft/2020-12/schema", + "type": "object", + "properties": { + "schema": { + "type": "string", + "const": "crosscode.church-export/1" + }, + "exportedAt": { + "type": "string", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" + }, + "product": { + "type": "string", + "enum": [ + "events", + "website", + "app", + "accounts" + ] + }, + "productVersion": { + "type": "string", + "maxLength": 40 + }, + "church": { + "type": "object", + "properties": { + "name": { + "type": "string", + "maxLength": 300 + }, + "timezone": { + "anyOf": [ + { + "type": "string", + "pattern": "^[A-Za-z_]+(\\/[A-Za-z0-9_+-]+){0,2}$|^UTC$" + }, + { + "type": "null" + } + ] + } + }, + "required": [ + "name", + "timezone" + ] + }, + "people": { + "type": "array", + "items": { + "type": "object", + "properties": { + "ref": { + "type": "string", + "pattern": "^p[0-9]+$" + }, + "name": { + "type": "string", + "maxLength": 300 + }, + "email": { + "anyOf": [ + { + "type": "string", + "maxLength": 254 + }, + { + "type": "null" + } + ] + }, + "phone": { + "anyOf": [ + { + "type": "string", + "maxLength": 40 + }, + { + "type": "null" + } + ] + }, + "role": { + "type": "string", + "maxLength": 40 + }, + "createdAt": { + "anyOf": [ + { + "type": "string", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" + }, + { + "type": "null" + } + ] + }, + "consent": { + "type": "object", + "properties": { + "email": { + "type": [ + "boolean", + "null" + ] + }, + "whatsapp": { + "type": [ + "boolean", + "null" + ] + }, + "privacyNoticeAcceptedAt": { + "anyOf": [ + { + "type": "string", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" + }, + { + "type": "null" + } + ] + } + }, + "required": [ + "email", + "whatsapp", + "privacyNoticeAcceptedAt" + ] + } + }, + "required": [ + "ref", + "name", + "email", + "phone", + "role", + "createdAt", + "consent" + ] + } + }, + "events": { + "type": "array", + "items": { + "type": "object", + "properties": { + "ref": { + "type": "string", + "pattern": "^e[0-9]+$" + }, + "title": { + "type": "string", + "maxLength": 500 + }, + "description": { + "anyOf": [ + { + "type": "string", + "maxLength": 20000 + }, + { + "type": "null" + } + ] + }, + "startsAt": { + "anyOf": [ + { + "type": "string", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" + }, + { + "type": "null" + } + ] + }, + "endsAt": { + "anyOf": [ + { + "type": "string", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" + }, + { + "type": "null" + } + ] + }, + "location": { + "anyOf": [ + { + "type": "string", + "maxLength": 500 + }, + { + "type": "null" + } + ] + }, + "sessions": { + "type": "array", + "items": { + "type": "object", + "properties": { + "label": { + "anyOf": [ + { + "type": "string", + "maxLength": 300 + }, + { + "type": "null" + } + ] + }, + "startsAt": { + "anyOf": [ + { + "type": "string", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" + }, + { + "type": "null" + } + ] + }, + "endsAt": { + "anyOf": [ + { + "type": "string", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" + }, + { + "type": "null" + } + ] + } + }, + "required": [ + "label", + "startsAt", + "endsAt" + ] + } + }, + "ticketTypes": { + "type": "array", + "items": { + "type": "object", + "properties": { + "ref": { + "type": "string", + "pattern": "^t[0-9]+$" + }, + "name": { + "type": "string", + "maxLength": 300 + }, + "priceCents": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 + }, + "currency": { + "type": "string", + "minLength": 3, + "maxLength": 3 + } + }, + "required": [ + "ref", + "name", + "priceCents", + "currency" + ] + } + }, + "capacity": { + "anyOf": [ + { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 + }, + { + "type": "null" + } + ] + }, + "published": { + "type": "boolean" + } + }, + "required": [ + "ref", + "title", + "description", + "startsAt", + "endsAt", + "location", + "sessions", + "ticketTypes", + "capacity", + "published" + ] + } + }, + "registrations": { + "type": "array", + "items": { + "type": "object", + "properties": { + "ref": { + "type": "string", + "pattern": "^r[0-9]+$" + }, + "eventRef": { + "type": "string", + "pattern": "^e[0-9]+$" + }, + "personRef": { + "anyOf": [ + { + "type": "string", + "pattern": "^p[0-9]+$" + }, + { + "type": "null" + } + ] + }, + "status": { + "type": "string", + "maxLength": 40 + }, + "createdAt": { + "anyOf": [ + { + "type": "string", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" + }, + { + "type": "null" + } + ] + }, + "attendees": { + "type": "array", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "maxLength": 300 + }, + "email": { + "anyOf": [ + { + "type": "string", + "maxLength": 254 + }, + { + "type": "null" + } + ] + }, + "ticketTypeRef": { + "anyOf": [ + { + "type": "string", + "pattern": "^t[0-9]+$" + }, + { + "type": "null" + } + ] + }, + "checkedInAt": { + "anyOf": [ + { + "type": "string", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" + }, + { + "type": "null" + } + ] + } + }, + "required": [ + "name", + "email", + "ticketTypeRef", + "checkedInAt" + ] + } + }, + "answers": { + "default": [], + "type": "array", + "items": { + "type": "object", + "properties": { + "question": { + "type": "string", + "maxLength": 500 + }, + "answer": { + "type": "string", + "maxLength": 5000 + } + }, + "required": [ + "question", + "answer" + ] + } + } + }, + "required": [ + "ref", + "eventRef", + "personRef", + "status", + "createdAt", + "attendees" + ] + } + }, + "payments": { + "type": "array", + "items": { + "type": "object", + "properties": { + "registrationRef": { + "anyOf": [ + { + "type": "string", + "pattern": "^r[0-9]+$" + }, + { + "type": "null" + } + ] + }, + "amountCents": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 + }, + "currency": { + "type": "string", + "minLength": 3, + "maxLength": 3 + }, + "method": { + "type": "string", + "maxLength": 40 + }, + "status": { + "type": "string", + "maxLength": 40 + }, + "paidAt": { + "anyOf": [ + { + "type": "string", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" + }, + { + "type": "null" + } + ] + }, + "reference": { + "anyOf": [ + { + "type": "string", + "maxLength": 200 + }, + { + "type": "null" + } + ] + } + }, + "required": [ + "registrationRef", + "amountCents", + "currency", + "method", + "status", + "paidAt", + "reference" + ] + } + }, + "checkIns": { + "type": "array", + "items": { + "type": "object", + "properties": { + "eventRef": { + "type": "string", + "pattern": "^e[0-9]+$" + }, + "personRef": { + "anyOf": [ + { + "type": "string", + "pattern": "^p[0-9]+$" + }, + { + "type": "null" + } + ] + }, + "name": { + "anyOf": [ + { + "type": "string", + "maxLength": 300 + }, + { + "type": "null" + } + ] + }, + "at": { + "anyOf": [ + { + "type": "string", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" + }, + { + "type": "null" + } + ] + } + }, + "required": [ + "eventRef", + "personRef", + "name", + "at" + ] + } + }, + "rosters": { + "type": "array", + "items": { + "type": "object", + "properties": { + "eventRef": { + "anyOf": [ + { + "type": "string", + "pattern": "^e[0-9]+$" + }, + { + "type": "null" + } + ] + }, + "role": { + "type": "string", + "maxLength": 200 + }, + "personRef": { + "anyOf": [ + { + "type": "string", + "pattern": "^p[0-9]+$" + }, + { + "type": "null" + } + ] + }, + "startsAt": { + "anyOf": [ + { + "type": "string", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" + }, + { + "type": "null" + } + ] + }, + "endsAt": { + "anyOf": [ + { + "type": "string", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" + }, + { + "type": "null" + } + ] + } + }, + "required": [ + "eventRef", + "role", + "personRef", + "startsAt", + "endsAt" + ] + } + }, + "settings": { + "type": "object", + "propertyNames": { + "type": "string", + "maxLength": 100 + }, + "additionalProperties": { + "type": "string", + "maxLength": 5000 + } + }, + "files": { + "type": "array", + "items": { + "type": "object", + "properties": { + "path": { + "type": "string", + "pattern": "^uploads\\/[A-Za-z0-9._/-]+$" + }, + "bytes": { + "type": "integer", + "minimum": 0, + "maximum": 9007199254740991 + } + }, + "required": [ + "path", + "bytes" + ] + } + } + }, + "required": [ + "schema", + "exportedAt", + "product", + "productVersion", + "church", + "people", + "events", + "registrations", + "payments", + "checkIns", + "rosters", + "settings", + "files" + ] +} diff --git a/packages/contracts/schemas/env-template.json b/packages/contracts/schemas/env-template.json new file mode 100644 index 0000000..b9cd40b --- /dev/null +++ b/packages/contracts/schemas/env-template.json @@ -0,0 +1,74 @@ +{ + "$id": "https://c-git.crosscode.co.za/joshua/crosscode-platform/raw/branch/main/packages/contracts/schemas/env-template.json", + "$schema": "https://json-schema.org/draft/2020-12/schema", + "type": "object", + "properties": { + "schema": { + "type": "string", + "const": "crosscode.env-template/1" + }, + "product": { + "type": "string", + "enum": [ + "events", + "website", + "app", + "accounts" + ] + }, + "files": { + "type": "object", + "propertyNames": { + "type": "string", + "pattern": "^[a-z0-9._/-]+$" + }, + "additionalProperties": { + "minItems": 1, + "type": "array", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "pattern": "^[A-Z][A-Z0-9_]*$" + }, + "layer": { + "type": "string", + "enum": [ + "server", + "defaults", + "install", + "generated" + ] + }, + "required": { + "default": false, + "type": "boolean" + }, + "default": { + "type": "string", + "maxLength": 4000 + }, + "from": { + "type": "string", + "maxLength": 400 + }, + "description": { + "type": "string", + "maxLength": 400 + } + }, + "required": [ + "name", + "layer" + ] + } + } + } + }, + "required": [ + "schema", + "product", + "files" + ] +} diff --git a/packages/contracts/schemas/script-report.json b/packages/contracts/schemas/script-report.json new file mode 100644 index 0000000..21378f0 --- /dev/null +++ b/packages/contracts/schemas/script-report.json @@ -0,0 +1,104 @@ +{ + "$id": "https://c-git.crosscode.co.za/joshua/crosscode-platform/raw/branch/main/packages/contracts/schemas/script-report.json", + "$schema": "https://json-schema.org/draft/2020-12/schema", + "type": "object", + "properties": { + "status": { + "type": "string", + "enum": [ + "succeeded", + "failed", + "rolled-back", + "refused", + "expired" + ] + }, + "startedAt": { + "type": "string", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" + }, + "finishedAt": { + "type": "string", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" + }, + "steps": { + "maxItems": 200, + "type": "array", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "maxLength": 200 + }, + "startedAt": { + "type": "string", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" + }, + "finishedAt": { + "anyOf": [ + { + "type": "string", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" + }, + { + "type": "null" + } + ] + }, + "outcome": { + "type": "string", + "enum": [ + "ok", + "failed", + "skipped", + "rolled-back" + ] + }, + "detail": { + "type": "string", + "maxLength": 2000 + } + }, + "required": [ + "name", + "startedAt", + "finishedAt", + "outcome" + ] + } + }, + "result": { + "default": {}, + "type": "object", + "propertyNames": { + "type": "string" + }, + "additionalProperties": {} + }, + "message": { + "type": "string", + "maxLength": 2000 + }, + "schema": { + "type": "string", + "const": "crosscode.script-report/1" + }, + "command": { + "type": "string", + "maxLength": 40 + } + }, + "required": [ + "status", + "startedAt", + "finishedAt", + "steps", + "schema", + "command" + ] +} diff --git a/packages/contracts/scripts/json-schemas.cjs b/packages/contracts/scripts/json-schemas.cjs index 5464e4e..671dc53 100644 --- a/packages/contracts/scripts/json-schemas.cjs +++ b/packages/contracts/scripts/json-schemas.cjs @@ -41,6 +41,17 @@ function contracts(c) { "hub-ai-complete-response": c.hub.aiCompleteResponseSchema, "hub-error": c.hub.hubErrorSchema, "health": c.hub.healthSchema, + "agent-job": c.agent.agentJobSchema, + "agent-report": c.agent.agentReportSchema, + "script-report": c.agent.scriptReportSchema, + "agent-stats": c.agent.agentStatsSchema, + "agent-join-request": c.agent.joinRequestSchema, + "agent-join-response": c.agent.joinResponseSchema, + "agent-poll-request": c.agent.pollRequestSchema, + "agent-poll-response": c.agent.pollResponseSchema, + "agent-job-config": c.agent.jobConfigSchema, + "env-template": c.agent.envTemplateSchema, + "church-export": c.churchExportSchema, }; } diff --git a/packages/contracts/src/agent.ts b/packages/contracts/src/agent.ts new file mode 100644 index 0000000..b12639d --- /dev/null +++ b/packages/contracts/src/agent.ts @@ -0,0 +1,320 @@ +import { z } from "zod"; +import { dateTimeSchema, productSchema } from "./common"; + +/** + * The server agent (docs/AGENT-1.0-PLAN.md, ROADMAP-v3 phase 1d): what the Hub and the agent on + * each server send each other. The agent only polls (it listens on nothing), runs only the + * `crosscode` script, and only for jobs of the fixed types below, signed by the Hub. + * + * Signing and encryption (Node only) are in `@crosscode/contracts/signing`: + * - jobs: Ed25519 by the Hub over `canonicalJson(job without "signature")`; + * - agent → Hub requests: Ed25519 by the agent over `timestamp + "." + rawBody` ({@link AGENT_HEADERS}); + * - the job's `config`: sealed to the server's X25519 key (X25519 + HKDF-SHA256 + AES-256-GCM). + */ + +export const AGENT_API_VERSION = 1; + +/** Headers on every agent → Hub request (after joining). */ +export const AGENT_HEADERS = { + server: "x-crosscode-server", + timestamp: "x-crosscode-timestamp", + signature: "x-crosscode-signature", +} as const; + +// --------------------------------------------------------------------------------------------- +// Building blocks +// --------------------------------------------------------------------------------------------- + +/** A church's short name: folders, PM2 names, database names, tunnel names (`hope`, `cross-roads`). */ +export const shortNameSchema = z.string().regex(/^[a-z][a-z0-9-]{1,30}$/, "Expected a short name: a-z, 0-9 and -, starting with a letter"); + +/** A release tag, `@x.y.z` (no prereleases: jobs only install releases). */ +export const releaseTagSchema = z.string().regex(/^(accounts|events|website|app)@\d+\.\d+\.\d+$/, "Expected @x.y.z"); + +/** An agent release tag, `agent@x.y.z`. */ +export const agentTagSchema = z.string().regex(/^agent@\d+\.\d+\.\d+$/, "Expected agent@x.y.z"); + +/** A host name (no scheme, no path): `events.hope.co.za`. */ +export const domainSchema = z.string().max(253).regex(/^(?=.{1,253}$)([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,}$/, "Expected a domain like events.hope.co.za"); + +/** A TCP port the Hub hands out (frp tunnels use the same number on both ends). */ +export const portSchema = z.int().min(1024).max(65535); + +/** An absolute path on the server without `..`, spaces or shell characters. */ +export const serverPathSchema = z.string().max(255).regex(/^\/(?!.*\/\.\.?(\/|$))[A-Za-z0-9._/-]+$/, "Expected an absolute path"); + +export const productPortsSchema = z.object({ web: portSchema, api: portSchema }).refine((p) => p.web !== p.api, "web and api must differ"); +export type ProductPorts = z.infer; + +export const AGENT_MODES = ["church", "central"] as const; +export const agentModeSchema = z.enum(AGENT_MODES); +export type AgentMode = z.infer; + +// --------------------------------------------------------------------------------------------- +// Jobs (crosscode.agent-job/1) +// --------------------------------------------------------------------------------------------- + +/** Each job type and the arguments it takes. Unknown keys are refused, not stripped. */ +export const jobArgsSchemas = { + /** `crosscode install --products … --frp --json` */ + install: z.strictObject({ + church: shortNameSchema, + products: z.array(productSchema).min(1).max(4), + /** Per product: the release (default: the latest). */ + versions: z.partialRecord(productSchema, releaseTagSchema).optional(), + /** Per product: where it's served. */ + domains: z.partialRecord(productSchema, domainSchema), + /** Per product: the ports from the Hub's port list. */ + ports: z.partialRecord(productSchema, productPortsSchema), + }), + /** `crosscode add ` (from phase 3). */ + "add-product": z.strictObject({ church: shortNameSchema, product: productSchema, version: releaseTagSchema.optional(), domain: domainSchema, ports: productPortsSchema }), + /** `crosscode deploy [products] [--version …] --json` */ + deploy: z.strictObject({ + church: shortNameSchema, + products: z.array(productSchema).min(1).max(4), + versions: z.array(releaseTagSchema).max(4).optional(), + check: z.boolean().optional(), + }), + /** `crosscode adopt --events-dir [--version …] [--address …] --json` */ + adopt: z.strictObject({ church: shortNameSchema, eventsDir: serverPathSchema, version: releaseTagSchema.optional(), address: domainSchema.optional() }), + "adopt-undo": z.strictObject({ church: shortNameSchema }), + /** `crosscode restart [product] --json` (PM2 reload) */ + restart: z.strictObject({ church: shortNameSchema, product: productSchema.optional() }), + /** `crosscode export --out --json`; the agent encrypts the ZIP and uploads it under `exportId`. */ + export: z.strictObject({ church: shortNameSchema, exportId: z.string().regex(/^exp_[A-Za-z0-9_-]{8,64}$/) }), + /** `crosscode uninstall --json` */ + uninstall: z.strictObject({ church: shortNameSchema }), + /** `crosscode purge --json` (deletes what uninstall kept for 30 days) */ + purge: z.strictObject({ church: shortNameSchema }), + /** The agent updates itself to that tag. */ + "update-agent": z.strictObject({ version: agentTagSchema }), + /** Central server only: are these ports allowed, open and bound to 127.0.0.1? */ + "check-ports": z.strictObject({ ports: z.array(portSchema).min(1).max(50) }), + /** `crosscode status [] --json` */ + status: z.strictObject({ church: shortNameSchema.optional() }), +} as const; + +export type JobType = keyof typeof jobArgsSchemas; +export const JOB_TYPES = Object.keys(jobArgsSchemas) as JobType[]; +export const jobTypeSchema = z.enum(JOB_TYPES as [JobType, ...JobType[]]); +export type JobArgs = z.infer<(typeof jobArgsSchemas)[T]>; + +/** The only jobs a central agent runs (§3). */ +export const CENTRAL_JOB_TYPES: readonly JobType[] = ["check-ports", "status", "update-agent"]; + +/** Time limits per job type, in minutes (§3). A job past it is stopped and reported as failed. */ +export const JOB_TIME_LIMIT_MINUTES: Record = { + install: 30, "add-product": 30, deploy: 20, adopt: 30, "adopt-undo": 15, restart: 5, export: 20, + uninstall: 20, purge: 10, "update-agent": 15, "check-ports": 2, status: 3, +}; + +/** Config sealed to the server's X25519 key (`sealConfig` in `@crosscode/contracts/signing`). */ +export const sealedSchema = z.strictObject({ + alg: z.literal("x25519-hkdf-sha256-aes-256-gcm"), + /** The sender's one-time X25519 public key, base64url (raw 32 bytes). */ + epk: z.string().regex(/^[A-Za-z0-9_-]{43}$/), + /** 12-byte nonce, base64url. */ + iv: z.string().regex(/^[A-Za-z0-9_-]{16}$/), + /** Ciphertext with the 16-byte GCM tag appended, base64url. */ + ciphertext: z.string().regex(/^[A-Za-z0-9_-]+$/).max(200_000), +}); +export type Sealed = z.infer; + +/** + * What a job's sealed `config` holds once opened (§5): `.env` values by layer, each keyed by the + * variable name. `generated` values are never sent: the server makes them. + */ +export const jobConfigSchema = z.strictObject({ + server: z.record(z.string().regex(/^[A-Z][A-Z0-9_]*$/), z.string().max(4000)).default({}), + defaults: z.record(z.string().regex(/^[A-Z][A-Z0-9_]*$/), z.string().max(4000)).default({}), + /** Per product: the install's own values (URLs, timezone, licence key, PORT). */ + install: z.partialRecord(productSchema, z.record(z.string().regex(/^[A-Z][A-Z0-9_]*$/), z.string().max(4000))).default({}), +}); +export type JobConfig = z.infer; + +const jobBase = { + schema: z.literal("crosscode.agent-job/1"), + id: z.string().regex(/^job_[A-Za-z0-9_-]{8,64}$/), + serverId: z.string().regex(/^srv_[A-Za-z0-9_-]{8,64}$/), + config: sealedSchema.nullable().optional(), + notBefore: dateTimeSchema, + expiresAt: dateTimeSchema, + /** Ed25519 over `canonicalJson(job without "signature")`, base64url. */ + signature: z.string().regex(/^[A-Za-z0-9_-]{86}$/), +}; + +function jobOf(type: T) { + return z.strictObject({ ...jobBase, type: z.literal(type), args: jobArgsSchemas[type] }); +} + +export const agentJobSchema = z.discriminatedUnion("type", [ + jobOf("install"), jobOf("add-product"), jobOf("deploy"), jobOf("adopt"), jobOf("adopt-undo"), jobOf("restart"), + jobOf("export"), jobOf("uninstall"), jobOf("purge"), jobOf("update-agent"), jobOf("check-ports"), jobOf("status"), +]); +export type AgentJob = z.infer; +export type UnsignedAgentJob = Omit; + +// --------------------------------------------------------------------------------------------- +// Reports (crosscode.agent-report/1) +// --------------------------------------------------------------------------------------------- + +export const JOB_STATUSES = ["succeeded", "failed", "rolled-back", "refused", "expired"] as const; +export const jobStatusSchema = z.enum(JOB_STATUSES); +export type JobStatus = z.infer; + +export const reportStepSchema = z.object({ + name: z.string().max(200), + startedAt: dateTimeSchema, + finishedAt: dateTimeSchema.nullable(), + outcome: z.enum(["ok", "failed", "skipped", "rolled-back"]), + detail: z.string().max(2000).optional(), +}); +export type ReportStep = z.infer; + +/** + * A job's result. The `crosscode … --json` output is the report without `jobId`, `serverId` and + * `log`; the agent adds those (the log's last 200 lines, filtered for secrets) and signs the request. + */ +export const agentReportSchema = z.object({ + schema: z.literal("crosscode.agent-report/1"), + jobId: z.string().regex(/^job_[A-Za-z0-9_-]{8,64}$/), + serverId: z.string().regex(/^srv_[A-Za-z0-9_-]{8,64}$/), + type: jobTypeSchema, + status: jobStatusSchema, + startedAt: dateTimeSchema, + finishedAt: dateTimeSchema, + steps: z.array(reportStepSchema).max(200), + /** What the command found or did, by type (versions, ports, the export's size …). */ + result: z.record(z.string(), z.unknown()).default({}), + /** Why a job was refused or failed, in a sentence. */ + message: z.string().max(2000).optional(), + log: z.array(z.string().max(1000)).max(200), +}); +export type AgentReport = z.infer; + +/** What `crosscode … --json` prints: the report's own part. */ +export const scriptReportSchema = agentReportSchema.omit({ schema: true, jobId: true, serverId: true, type: true, log: true }).extend({ + schema: z.literal("crosscode.script-report/1"), + command: z.string().max(40), +}); +export type ScriptReport = z.infer; + +// --------------------------------------------------------------------------------------------- +// Stats (crosscode.agent-stats/1), every 60 s +// --------------------------------------------------------------------------------------------- + +const bytes = z.number().nonnegative(); + +export const processStatSchema = z.object({ + name: z.string().max(100), + church: shortNameSchema.nullable(), + product: productSchema.nullable(), + status: z.string().max(40), + memoryBytes: bytes, + cpuPercent: z.number().nonnegative(), + restarts: z.int().nonnegative(), + uptimeSeconds: z.number().nonnegative(), +}); + +export const centralStatSchema = z.object({ + /** `proxy_bind_addr` in frps.ini, null when it isn't set (tunnels then open on every address). */ + proxyBindAddr: z.string().max(100).nullable(), + /** `allow_ports` in frps.ini as written, e.g. `20000-29999`. */ + allowPorts: z.string().max(2000).nullable(), + frpsRunning: z.boolean().nullable(), +}); + +export const agentStatsSchema = z.object({ + schema: z.literal("crosscode.agent-stats/1"), + at: dateTimeSchema, + ram: z.object({ totalBytes: bytes, usedBytes: bytes, availableBytes: bytes, swapTotalBytes: bytes, swapUsedBytes: bytes }), + cpu: z.object({ percent: z.number().min(0).max(100), load1: z.number().nonnegative(), load5: z.number().nonnegative(), load15: z.number().nonnegative(), cores: z.int().positive() }), + disks: z.array(z.object({ mount: z.string().max(255), totalBytes: bytes, usedBytes: bytes, freeBytes: bytes })).max(30), + uptimeSeconds: z.number().nonnegative(), + versions: z.object({ os: z.string().max(200), node: z.string().max(40), postgres: z.string().max(40).nullable(), frpc: z.string().max(40).nullable(), agent: z.string().max(40) }), + frpcRunning: z.boolean().nullable(), + processes: z.array(processStatSchema).max(200), + central: centralStatSchema.nullable().optional(), +}); +export type AgentStats = z.infer; + +// --------------------------------------------------------------------------------------------- +// Agent API (/api/agent/v1/*) +// --------------------------------------------------------------------------------------------- + +const base64urlKey = z.string().regex(/^[A-Za-z0-9_-]{43}$/, "Expected a raw 32-byte key, base64url"); + +/** POST /api/agent/v1/join (unsigned: the one-time token is the proof). */ +export const joinRequestSchema = z.object({ + agentApiVersion: z.literal(AGENT_API_VERSION), + token: z.string().regex(/^[A-Za-z0-9_-]{32,128}$/), + mode: agentModeSchema, + hostname: z.string().max(253), + agentVersion: z.string().max(40), + /** The agent's Ed25519 key (signs its requests) and X25519 key (receives config). */ + publicKeys: z.object({ ed25519: base64urlKey, x25519: base64urlKey }), +}); +export const joinResponseSchema = z.object({ + serverId: z.string().regex(/^srv_[A-Za-z0-9_-]{8,64}$/), + /** The Hub's job-signing Ed25519 key, pinned by the agent. */ + hubJobKey: base64urlKey, + pollSeconds: z.int().min(5).max(600), + statsSeconds: z.int().min(15).max(3600), +}); + +/** POST /api/agent/v1/poll (signed). */ +export const pollRequestSchema = z.object({ + agentApiVersion: z.literal(AGENT_API_VERSION), + agentVersion: z.string().max(40), + mode: agentModeSchema, + /** The job being run now, if any (the Hub won't hand out another). */ + runningJobId: z.string().regex(/^job_[A-Za-z0-9_-]{8,64}$/).nullable(), +}); +export const pollResponseSchema = z.object({ + jobs: z.array(z.unknown()).max(10), // each checked with agentJobSchema and the signature by the agent + pollSeconds: z.int().min(5).max(600), +}); + +/** POST /api/agent/v1/stats (signed): an {@link agentStatsSchema} body. → 204 */ +/** POST /api/agent/v1/report (signed): an {@link agentReportSchema} body. → 204 */ +/** PUT /api/agent/v1/exports/:exportId (signed): the encrypted ZIP, `application/octet-stream`. → 204 */ + +// --------------------------------------------------------------------------------------------- +// Env template (crosscode.env-template/1): apps//env.template.json +// --------------------------------------------------------------------------------------------- + +export const ENV_LAYERS = ["server", "defaults", "install", "generated"] as const; +export const envLayerSchema = z.enum(ENV_LAYERS); + +export const envVariableSchema = z.object({ + name: z.string().regex(/^[A-Z][A-Z0-9_]*$/), + layer: envLayerSchema, + required: z.boolean().default(false), + /** Used when no layer gives a value. */ + default: z.string().max(4000).optional(), + /** Built from the install's values: `https://{domain}`, `{apiPort}`. */ + from: z.string().max(400).optional(), + description: z.string().max(400).optional(), +}); +export type EnvVariable = z.infer; + +export const envTemplateSchema = z.object({ + schema: z.literal("crosscode.env-template/1"), + product: productSchema, + /** Relative to the product's folder (`apps/`): `backend/.env`, `frontend/.env.production`. */ + files: z.record(z.string().regex(/^[a-z0-9._/-]+$/), z.array(envVariableSchema).min(1)), +}); +export type EnvTemplate = z.infer; + +/** The variables a layer must provide for a template, that it doesn't (the Hub's check before a job). */ +export function missingRequired(template: EnvTemplate, layer: "server" | "defaults", values: Record): string[] { + const missing: string[] = []; + for (const vars of Object.values(template.files)) { + for (const v of vars) { + if (v.layer !== layer || !v.required || v.default !== undefined) continue; + if (!values[v.name] || !String(values[v.name]).trim()) missing.push(v.name); + } + } + return [...new Set(missing)]; +} diff --git a/packages/contracts/src/canonical.ts b/packages/contracts/src/canonical.ts new file mode 100644 index 0000000..34044f6 --- /dev/null +++ b/packages/contracts/src/canonical.ts @@ -0,0 +1,24 @@ +/** + * Canonical JSON for signatures: object keys sorted (by UTF-16 code units, as JavaScript sorts), + * no whitespace, `undefined` properties left out. Arrays keep their order. Only plain JSON values + * (no Dates, Maps or functions: convert them first). + */ +export function canonicalJson(value: unknown): string { + if (value === null || typeof value === "boolean" || typeof value === "string") return JSON.stringify(value); + if (typeof value === "number") { + if (!Number.isFinite(value)) throw new Error("canonicalJson: numbers must be finite"); + return JSON.stringify(value); + } + if (Array.isArray(value)) return `[${value.map((v) => (v === undefined ? "null" : canonicalJson(v))).join(",")}]`; + if (typeof value === "object") { + const proto = Object.getPrototypeOf(value) as unknown; + if (proto !== Object.prototype && proto !== null) throw new Error("canonicalJson: only plain objects"); + const obj = value as Record; + const entries = Object.keys(obj) + .filter((k) => obj[k] !== undefined) + .sort() + .map((k) => `${JSON.stringify(k)}:${canonicalJson(obj[k])}`); + return `{${entries.join(",")}}`; + } + throw new Error(`canonicalJson: can't encode a ${typeof value}`); +} diff --git a/packages/contracts/src/church-export.ts b/packages/contracts/src/church-export.ts new file mode 100644 index 0000000..99606cd --- /dev/null +++ b/packages/contracts/src/church-export.ts @@ -0,0 +1,85 @@ +import { z } from "zod"; +import { dateTimeSchema, productSchema, timezoneSchema } from "./common"; + +/** + * crosscode.church-export/1: a church's data when it leaves (docs/AGENT-1.0-PLAN.md §9). Written + * for people, in plain terms with our own field names: no database tables, Prisma models or + * internal ids. Records point at each other with references made for the export (`p12`, `e3`, + * `r40`), which mean nothing outside the file. + * + * Shipped as a ZIP: `export.json` (this), `uploads/` (the files in `files`) and `README.txt`. + */ + +const ref = (prefix: string) => z.string().regex(new RegExp(`^${prefix}[0-9]+$`)); +const text = (max = 20000) => z.string().max(max); +const when = dateTimeSchema.nullable(); +const cents = z.int(); + +export const exportPersonSchema = z.object({ + ref: ref("p"), + name: text(300), + email: text(254).nullable(), + phone: text(40).nullable(), + role: text(40), + createdAt: when, + consent: z.object({ email: z.boolean().nullable(), whatsapp: z.boolean().nullable(), privacyNoticeAcceptedAt: when }), +}); + +export const exportEventSchema = z.object({ + ref: ref("e"), + title: text(500), + description: text().nullable(), + startsAt: when, + endsAt: when, + location: text(500).nullable(), + sessions: z.array(z.object({ label: text(300).nullable(), startsAt: when, endsAt: when })), + ticketTypes: z.array(z.object({ ref: ref("t"), name: text(300), priceCents: cents, currency: z.string().length(3) })), + capacity: z.int().nullable(), + published: z.boolean(), +}); + +export const exportRegistrationSchema = z.object({ + ref: ref("r"), + eventRef: ref("e"), + personRef: ref("p").nullable(), + status: text(40), + createdAt: when, + attendees: z.array(z.object({ name: text(300), email: text(254).nullable(), ticketTypeRef: ref("t").nullable(), checkedInAt: when })), + answers: z.array(z.object({ question: text(500), answer: text(5000) })).default([]), +}); + +export const exportPaymentSchema = z.object({ + registrationRef: ref("r").nullable(), + amountCents: cents, + currency: z.string().length(3), + method: text(40), + status: text(40), + paidAt: when, + reference: text(200).nullable(), +}); + +export const exportCheckInSchema = z.object({ eventRef: ref("e"), personRef: ref("p").nullable(), name: text(300).nullable(), at: when }); + +export const exportRosterSchema = z.object({ eventRef: ref("e").nullable(), role: text(200), personRef: ref("p").nullable(), startsAt: when, endsAt: when }); + +export const churchExportSchema = z.object({ + schema: z.literal("crosscode.church-export/1"), + exportedAt: dateTimeSchema, + product: productSchema, + productVersion: z.string().max(40), + church: z.object({ name: text(300), timezone: timezoneSchema.nullable() }), + people: z.array(exportPersonSchema), + events: z.array(exportEventSchema), + registrations: z.array(exportRegistrationSchema), + payments: z.array(exportPaymentSchema), + checkIns: z.array(exportCheckInSchema), + rosters: z.array(exportRosterSchema), + /** The site's own settings that matter to a church (name, contact, branding), never secrets. */ + settings: z.record(z.string().max(100), z.string().max(5000)), + /** Uploaded files in the ZIP's `uploads/` folder. */ + files: z.array(z.object({ path: z.string().regex(/^uploads\/[A-Za-z0-9._/-]+$/), bytes: z.int().nonnegative() })), +}); +export type ChurchExport = z.infer; + +/** Keys that look like internal ids anywhere in an export (the export test fails on any). */ +export const INTERNAL_ID_KEYS = /^(id|.*Id|uuid|_id)$/; diff --git a/packages/contracts/src/index.ts b/packages/contracts/src/index.ts index 970ca6e..edeeaef 100644 --- a/packages/contracts/src/index.ts +++ b/packages/contracts/src/index.ts @@ -9,3 +9,6 @@ export * from "./church"; export * from "./identity"; export * from "./return-to"; export * as hub from "./hub"; +export * as agent from "./agent"; +export * from "./church-export"; +export { canonicalJson } from "./canonical"; diff --git a/packages/contracts/src/signing.ts b/packages/contracts/src/signing.ts index e559d98..e18e230 100644 --- a/packages/contracts/src/signing.ts +++ b/packages/contracts/src/signing.ts @@ -1,4 +1,22 @@ -import { createHmac, timingSafeEqual } from "node:crypto"; +import { + createCipheriv, + createDecipheriv, + createHmac, + createPrivateKey, + createPublicKey, + diffieHellman, + generateKeyPairSync, + hkdfSync, + randomBytes, + sign as edSign, + timingSafeEqual, + verify as edVerify, + type KeyObject, +} from "node:crypto"; +import { AGENT_HEADERS, type Sealed } from "./agent"; +import { canonicalJson } from "./canonical"; + +export { canonicalJson } from "./canonical"; /** * Signed requests between Cross Code installs (Node only: `@crosscode/contracts/signing`). @@ -74,3 +92,145 @@ export function verify(opts: { secret: string; timestamp: unknown; signature: un const given = Buffer.from(signature, "hex"); return timingSafeEqual(expected, given) ? { ok: true } : { ok: false, code: "BAD_SIGNATURE" }; } + +// --------------------------------------------------------------------------------------------- +// Server agent (docs/AGENT-1.0-PLAN.md §3–4): Ed25519 signatures, sealed config, export files. +// Keys travel as raw 32-byte base64url strings; private keys stay on their machine as PKCS#8 PEM. +// --------------------------------------------------------------------------------------------- + +const b64u = (buf: Uint8Array): string => Buffer.from(buf).toString("base64url"); +const unb64u = (s: string): Buffer => Buffer.from(s, "base64url"); +const bytesOf = (data: RawBody): Buffer => (typeof data === "string" ? Buffer.from(data) : Buffer.from(data)); + +export interface KeyPair { + /** Raw 32-byte public key, base64url. */ + publicKey: string; + /** PKCS#8 PEM. Never leaves the machine that made it. */ + privateKeyPem: string; +} + +function rawPublic(key: KeyObject): string { + const jwk = key.export({ format: "jwk" }); + if (!jwk.x) throw new Error("Not an OKP key"); + return jwk.x; +} + +export function generateEd25519(): KeyPair { + const { publicKey, privateKey } = generateKeyPairSync("ed25519"); + return { publicKey: rawPublic(publicKey), privateKeyPem: privateKey.export({ format: "pem", type: "pkcs8" }).toString() }; +} + +export function generateX25519(): KeyPair { + const { publicKey, privateKey } = generateKeyPairSync("x25519"); + return { publicKey: rawPublic(publicKey), privateKeyPem: privateKey.export({ format: "pem", type: "pkcs8" }).toString() }; +} + +/** The raw public key of a PKCS#8 private key (to check a configured key pair matches). */ +export function publicKeyOf(privateKeyPem: string): string { + return rawPublic(createPublicKey(createPrivateKey(privateKeyPem))); +} + +const okpPublic = (crv: "Ed25519" | "X25519", x: string): KeyObject => createPublicKey({ key: { kty: "OKP", crv, x }, format: "jwk" }); + +/** Ed25519 signature of some bytes, base64url (86 characters). */ +export function ed25519Sign(privateKeyPem: string, data: RawBody): string { + return b64u(edSign(null, bytesOf(data), createPrivateKey(privateKeyPem))); +} + +export function ed25519Verify(publicKey: string, data: RawBody, signature: unknown): boolean { + if (typeof signature !== "string" || !/^[A-Za-z0-9_-]{86}$/.test(signature)) return false; + try { + return edVerify(null, bytesOf(data), okpPublic("Ed25519", publicKey), unb64u(signature)); + } catch { + return false; + } +} + +/** The bytes a job's signature covers: the job without `signature`, as canonical JSON. */ +export function jobSigningInput(job: Record): string { + const rest = { ...job }; + delete rest.signature; + return canonicalJson(rest); +} + +/** The Hub signs a job (with its job-signing key, not the licence key). */ +export function signJob>(job: T, hubPrivateKeyPem: string): T & { signature: string } { + return { ...job, signature: ed25519Sign(hubPrivateKeyPem, jobSigningInput(job)) }; +} + +/** The agent checks a job against the Hub key it pinned when it joined. */ +export function verifyJob(job: Record, hubPublicKey: string): boolean { + return ed25519Verify(hubPublicKey, jobSigningInput(job), job.signature); +} + +/** Headers for an agent → Hub request. `now` is for tests. */ +export function signAgentRequest(opts: { serverId: string; privateKeyPem: string; rawBody: RawBody; now?: Date }): Record { + const timestamp = (opts.now ?? new Date()).toISOString(); + return { + [AGENT_HEADERS.server]: opts.serverId, + [AGENT_HEADERS.timestamp]: timestamp, + [AGENT_HEADERS.signature]: ed25519Sign(opts.privateKeyPem, Buffer.concat([Buffer.from(`${timestamp}.`), bytesOf(opts.rawBody)])), + }; +} + +/** The Hub checks an agent request against the key the server joined with. */ +export function verifyAgentRequest(opts: { publicKey: string; timestamp: unknown; signature: unknown; rawBody: RawBody; now?: Date; maxSkewMs?: number }): VerifyResult { + if (typeof opts.timestamp !== "string") return { ok: false, code: "BAD_SIGNATURE" }; + const sentAt = Date.parse(opts.timestamp); + const now = (opts.now ?? new Date()).getTime(); + if (!Number.isFinite(sentAt) || Math.abs(now - sentAt) > (opts.maxSkewMs ?? MAX_CLOCK_SKEW_MS)) return { ok: false, code: "STALE_REQUEST" }; + return ed25519Verify(opts.publicKey, Buffer.concat([Buffer.from(`${opts.timestamp}.`), bytesOf(opts.rawBody)]), opts.signature) + ? { ok: true } + : { ok: false, code: "BAD_SIGNATURE" }; +} + +const SEAL_INFO = Buffer.from("crosscode.agent-config/1"); + +function sealKey(shared: Buffer, epk: string, recipient: string): Buffer { + return Buffer.from(hkdfSync("sha256", shared, Buffer.concat([unb64u(epk), unb64u(recipient)]), SEAL_INFO, 32)); +} + +/** Seal a JSON value to a server's X25519 key: only that server can open it. */ +export function sealConfig(value: unknown, recipientX25519: string): Sealed { + const eph = generateKeyPairSync("x25519"); + const epk = rawPublic(eph.publicKey); + const shared = diffieHellman({ privateKey: eph.privateKey, publicKey: okpPublic("X25519", recipientX25519) }); + const key = sealKey(shared, epk, recipientX25519); + const iv = randomBytes(12); + const cipher = createCipheriv("aes-256-gcm", key, iv); + const data = Buffer.concat([cipher.update(JSON.stringify(value), "utf8"), cipher.final(), cipher.getAuthTag()]); + return { alg: "x25519-hkdf-sha256-aes-256-gcm", epk, iv: b64u(iv), ciphertext: b64u(data) }; +} + +/** Open a sealed value with the server's X25519 private key. Throws if it was changed or isn't for this key. */ +export function openConfig(sealed: Sealed, x25519PrivateKeyPem: string): unknown { + const priv = createPrivateKey(x25519PrivateKeyPem); + const recipient = rawPublic(createPublicKey(priv)); + const shared = diffieHellman({ privateKey: priv, publicKey: okpPublic("X25519", sealed.epk) }); + const key = sealKey(shared, sealed.epk, recipient); + const data = unb64u(sealed.ciphertext); + if (data.length < 17) throw new Error("Sealed data is too short"); + const decipher = createDecipheriv("aes-256-gcm", key, unb64u(sealed.iv)); + decipher.setAuthTag(data.subarray(data.length - 16)); + const plain = Buffer.concat([decipher.update(data.subarray(0, data.length - 16)), decipher.final()]); + return JSON.parse(plain.toString("utf8")) as unknown; +} + +/** + * An export ZIP encrypted with a fresh random key (§9): `iv (12) ‖ ciphertext ‖ tag (16)`, + * AES-256-GCM, which the browser decrypts with WebCrypto. The key only goes in the link's `#…`. + */ +export function encryptExport(zip: Uint8Array): { key: string; file: Buffer } { + const key = randomBytes(32); + const iv = randomBytes(12); + const cipher = createCipheriv("aes-256-gcm", key, iv); + const file = Buffer.concat([iv, cipher.update(zip), cipher.final(), cipher.getAuthTag()]); + return { key: b64u(key), file }; +} + +export function decryptExport(file: Uint8Array, key: string): Buffer { + const buf = Buffer.from(file); + const decipher = createDecipheriv("aes-256-gcm", unb64u(key), buf.subarray(0, 12)); + decipher.setAuthTag(buf.subarray(buf.length - 16)); + return Buffer.concat([decipher.update(buf.subarray(12, buf.length - 16)), decipher.final()]); +} diff --git a/packages/contracts/tests/agent.test.ts b/packages/contracts/tests/agent.test.ts new file mode 100644 index 0000000..2aef475 --- /dev/null +++ b/packages/contracts/tests/agent.test.ts @@ -0,0 +1,174 @@ +import { agent, canonicalJson, churchExportSchema, INTERNAL_ID_KEYS } from "../src"; +import { + decryptExport, + encryptExport, + generateEd25519, + generateX25519, + openConfig, + publicKeyOf, + sealConfig, + signAgentRequest, + signJob, + verifyAgentRequest, + verifyJob, +} from "../src/signing"; +import { sample } from "./helpers"; + +const hubKeys = generateEd25519(); +const serverKeys = { ed: generateEd25519(), x: generateX25519() }; + +function unsignedJob(over: Record = {}) { + return { + schema: "crosscode.agent-job/1", + id: "job_abcdefgh12", + serverId: "srv_abcdefgh12", + type: "deploy", + args: { church: "hope", products: ["events"], versions: ["events@2.4.1"] }, + config: null, + notBefore: "2026-11-20T12:00:00.000Z", + expiresAt: "2026-11-20T12:15:00.000Z", + ...over, + }; +} + +describe("canonical JSON", () => { + it("sorts keys at every level and drops undefined", () => { + expect(canonicalJson({ b: 1, a: { d: [3, { z: 1, y: 2 }], c: undefined } })).toBe('{"a":{"d":[3,{"y":2,"z":1}]},"b":1}'); + }); + it("refuses values that don't round-trip", () => { + expect(() => canonicalJson({ a: new Date() })).toThrow(); + expect(() => canonicalJson(Number.NaN)).toThrow(); + }); +}); + +describe("jobs", () => { + it("a signed job parses and verifies with the pinned Hub key", () => { + const job = signJob(unsignedJob(), hubKeys.privateKeyPem); + expect(agent.agentJobSchema.safeParse(job).success).toBe(true); + expect(verifyJob(job, hubKeys.publicKey)).toBe(true); + }); + + it("key order doesn't matter, but any change to the content does", () => { + const job = signJob(unsignedJob(), hubKeys.privateKeyPem); + const reordered = Object.fromEntries(Object.entries(job).reverse()); + expect(verifyJob(reordered, hubKeys.publicKey)).toBe(true); + expect(verifyJob({ ...job, args: { ...job.args, church: "other" } }, hubKeys.publicKey)).toBe(false); + expect(verifyJob({ ...job, expiresAt: "2026-12-20T12:15:00.000Z" }, hubKeys.publicKey)).toBe(false); + }); + + it("a job signed by another key is refused", () => { + const forged = signJob(unsignedJob(), generateEd25519().privateKeyPem); + expect(verifyJob(forged, hubKeys.publicKey)).toBe(false); + expect(verifyJob({ ...unsignedJob(), signature: "x".repeat(86) }, hubKeys.publicKey)).toBe(false); + }); + + it.each([ + ["shell characters in a name", { args: { church: "hope; rm -rf /", products: ["events"] } }], + ["an unknown product", { args: { church: "hope", products: ["shop"] } }], + ["a version that isn't a release tag", { args: { church: "hope", products: ["events"], versions: ["main"] } }], + ["an unknown argument", { args: { church: "hope", products: ["events"], command: "id" } }], + ["an unknown type", { type: "run", args: { command: "id" } }], + ])("refuses %s", (_label, over) => { + const job = signJob(unsignedJob(over), hubKeys.privateKeyPem); + expect(agent.agentJobSchema.safeParse(job).success).toBe(false); + }); + + it("adopt only takes a plain absolute folder", () => { + const ok = signJob(unsignedJob({ type: "adopt", args: { church: "hope", eventsDir: "/var/www/hope-events" } }), hubKeys.privateKeyPem); + expect(agent.agentJobSchema.safeParse(ok).success).toBe(true); + for (const eventsDir of ["/var/www/../etc", "relative/dir", "/var/www/a b", "/var/www/$(id)"]) { + const bad = signJob(unsignedJob({ type: "adopt", args: { church: "hope", eventsDir } }), hubKeys.privateKeyPem); + expect(agent.agentJobSchema.safeParse(bad).success).toBe(false); + } + }); + + it("install needs different web and api ports", () => { + const args = { church: "hope", products: ["events"], domains: { events: "events.hope.co.za" }, ports: { events: { web: 20010, api: 20010 } } }; + expect(agent.jobArgsSchemas.install.safeParse(args).success).toBe(false); + expect(agent.jobArgsSchemas.install.safeParse({ ...args, ports: { events: { web: 20010, api: 20011 } } }).success).toBe(true); + }); +}); + +describe("agent requests", () => { + const body = JSON.stringify({ agentApiVersion: 1, agentVersion: "1.0.0", mode: "church", runningJobId: null }); + const now = new Date("2026-11-20T12:00:00Z"); + + it("verify with the server's key, within five minutes", () => { + const h = signAgentRequest({ serverId: "srv_abcdefgh12", privateKeyPem: serverKeys.ed.privateKeyPem, rawBody: body, now }); + const check = (over: Partial[0]>) => + verifyAgentRequest({ publicKey: serverKeys.ed.publicKey, timestamp: h[agent.AGENT_HEADERS.timestamp], signature: h[agent.AGENT_HEADERS.signature], rawBody: body, now, ...over }); + expect(check({})).toEqual({ ok: true }); + expect(check({ rawBody: `${body} ` })).toEqual({ ok: false, code: "BAD_SIGNATURE" }); + expect(check({ publicKey: generateEd25519().publicKey })).toEqual({ ok: false, code: "BAD_SIGNATURE" }); + expect(check({ now: new Date(now.getTime() + 6 * 60 * 1000) })).toEqual({ ok: false, code: "STALE_REQUEST" }); + }); +}); + +describe("sealed config", () => { + const config = { server: { TRUST_PROXY: "loopback", DB_HOST: "10.0.0.5" }, defaults: { HUB_URL: "https://hub.crosscode.co.za" }, install: { events: { FRONTEND_URL: "https://events.hope.co.za" } } }; + + it("only the server's key opens it", () => { + const sealed = sealConfig(config, serverKeys.x.publicKey); + expect(agent.sealedSchema.safeParse(sealed).success).toBe(true); + expect(JSON.stringify(sealed)).not.toContain("loopback"); + expect(openConfig(sealed, serverKeys.x.privateKeyPem)).toEqual(config); + expect(() => openConfig(sealed, generateX25519().privateKeyPem)).toThrow(); + }); + + it("a changed ciphertext is refused", () => { + const sealed = sealConfig(config, serverKeys.x.publicKey); + const bytes = Buffer.from(sealed.ciphertext, "base64url"); + bytes[0] = (bytes[0] ?? 0) ^ 1; + expect(() => openConfig({ ...sealed, ciphertext: bytes.toString("base64url") }, serverKeys.x.privateKeyPem)).toThrow(); + }); + + it("the opened config parses", () => { + expect(agent.jobConfigSchema.safeParse(config).success).toBe(true); + }); + + it("publicKeyOf matches the generated pair", () => { + expect(publicKeyOf(serverKeys.x.privateKeyPem)).toBe(serverKeys.x.publicKey); + expect(publicKeyOf(serverKeys.ed.privateKeyPem)).toBe(serverKeys.ed.publicKey); + }); +}); + +describe("exports", () => { + it("encrypt and decrypt with the link's key", () => { + const zip = Buffer.from("PK\u0003\u0004 pretend zip"); + const { key, file } = encryptExport(zip); + expect(file.includes(zip)).toBe(false); + expect(decryptExport(file, key).equals(zip)).toBe(true); + expect(() => decryptExport(file, encryptExport(zip).key)).toThrow(); + }); + + it("the sample has no internal ids", () => { + const data = sample("church-export.json"); + expect(churchExportSchema.safeParse(data).success).toBe(true); + const keys: string[] = []; + const walk = (v: unknown): void => { + if (Array.isArray(v)) v.forEach(walk); + else if (v && typeof v === "object") for (const [k, x] of Object.entries(v)) { keys.push(k); walk(x); } + }; + walk(data); + expect(keys.filter((k) => INTERNAL_ID_KEYS.test(k))).toEqual([]); + }); +}); + +describe("env templates", () => { + it("lists the required server and defaults values that are missing", () => { + const template = agent.envTemplateSchema.parse({ + schema: "crosscode.env-template/1", + product: "events", + files: { + "backend/.env": [ + { name: "TRUST_PROXY", layer: "server", required: true }, + { name: "DB_HOST", layer: "server", required: true }, + { name: "BACKUP_ENABLED", layer: "defaults", required: true, default: "true" }, + { name: "HUB_URL", layer: "defaults", required: true }, + ], + }, + }); + expect(agent.missingRequired(template, "server", { TRUST_PROXY: "loopback" })).toEqual(["DB_HOST"]); + expect(agent.missingRequired(template, "defaults", {})).toEqual(["HUB_URL"]); + }); +}); diff --git a/packages/contracts/tests/json-schemas.test.ts b/packages/contracts/tests/json-schemas.test.ts index ab557e5..e951b27 100644 --- a/packages/contracts/tests/json-schemas.test.ts +++ b/packages/contracts/tests/json-schemas.test.ts @@ -35,6 +35,7 @@ const SAMPLE_SCHEMA: Record = { "hub-heartbeat-accounts.json": "hub-heartbeat-request", "hub-heartbeat-response.json": "hub-heartbeat-response", "hub-licence-payload.json": "hub-licence-payload", + "church-export.json": "church-export", }; describe("JSON Schema (schemas/)", () => { diff --git a/packages/contracts/tests/samples.test.ts b/packages/contracts/tests/samples.test.ts index f246670..196930d 100644 --- a/packages/contracts/tests/samples.test.ts +++ b/packages/contracts/tests/samples.test.ts @@ -2,6 +2,7 @@ import { readdirSync } from "node:fs"; import type { z } from "zod"; import { accountsCallSchema, + churchExportSchema, churchSchema, eventChangedSchema, eventFeedSchema, @@ -34,6 +35,7 @@ const SCHEMAS: Record = { "hub-heartbeat-accounts.json": hub.heartbeatRequestSchema, "hub-heartbeat-response.json": hub.heartbeatResponseSchema, "hub-licence-payload.json": hub.licencePayloadSchema, + "church-export.json": churchExportSchema, }; describe("samples", () => {