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", () => {