contracts 1.3.0: agent jobs, reports, stats, join/poll, env templates, church export

Jobs of fixed types with strict argument schemas, signed by the Hub with
Ed25519 over canonical JSON. Agent requests signed with the server's
Ed25519 key. Config sealed to the server's X25519 key (X25519 + HKDF +
AES-256-GCM; Node has no XSalsa20). Exports encrypted with a key that
only travels in the download link.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-17 12:02:24 +02:00
co-authored by Claude Opus 5.5
parent 53e15fdd69
commit 90a98a4306
22 changed files with 3645 additions and 2 deletions
+1 -1
View File
@@ -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",
@@ -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 }]
}
@@ -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
}
File diff suppressed because it is too large Load Diff
@@ -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"
]
}
@@ -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"
]
}
@@ -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"
]
}
@@ -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"
]
}
@@ -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"
]
}
+296
View File
@@ -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"
]
}
@@ -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"
]
}
@@ -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"
]
}
@@ -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"
]
}
@@ -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,
};
}
+320
View File
@@ -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, `<product>@x.y.z` (no prereleases: jobs only install releases). */
export const releaseTagSchema = z.string().regex(/^(accounts|events|website|app)@\d+\.\d+\.\d+$/, "Expected <product>@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<typeof productPortsSchema>;
export const AGENT_MODES = ["church", "central"] as const;
export const agentModeSchema = z.enum(AGENT_MODES);
export type AgentMode = z.infer<typeof agentModeSchema>;
// ---------------------------------------------------------------------------------------------
// Jobs (crosscode.agent-job/1)
// ---------------------------------------------------------------------------------------------
/** Each job type and the arguments it takes. Unknown keys are refused, not stripped. */
export const jobArgsSchemas = {
/** `crosscode install <church> --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 <church> <product>` (from phase 3). */
"add-product": z.strictObject({ church: shortNameSchema, product: productSchema, version: releaseTagSchema.optional(), domain: domainSchema, ports: productPortsSchema }),
/** `crosscode deploy <church> [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 <church> --events-dir <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 <church> [product] --json` (PM2 reload) */
restart: z.strictObject({ church: shortNameSchema, product: productSchema.optional() }),
/** `crosscode export <church> --out <zip> --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 <church> --json` */
uninstall: z.strictObject({ church: shortNameSchema }),
/** `crosscode purge <church> --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 [<church>] --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<T extends JobType> = 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<JobType, number> = {
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<typeof sealedSchema>;
/**
* 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<typeof jobConfigSchema>;
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<T extends JobType>(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<typeof agentJobSchema>;
export type UnsignedAgentJob = Omit<AgentJob, "signature">;
// ---------------------------------------------------------------------------------------------
// 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<typeof jobStatusSchema>;
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<typeof reportStepSchema>;
/**
* 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<typeof agentReportSchema>;
/** 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<typeof scriptReportSchema>;
// ---------------------------------------------------------------------------------------------
// 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<typeof agentStatsSchema>;
// ---------------------------------------------------------------------------------------------
// 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/<product>/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<typeof envVariableSchema>;
export const envTemplateSchema = z.object({
schema: z.literal("crosscode.env-template/1"),
product: productSchema,
/** Relative to the product's folder (`apps/<product>`): `backend/.env`, `frontend/.env.production`. */
files: z.record(z.string().regex(/^[a-z0-9._/-]+$/), z.array(envVariableSchema).min(1)),
});
export type EnvTemplate = z.infer<typeof envTemplateSchema>;
/** 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, string | undefined>): 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)];
}
+24
View File
@@ -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<string, unknown>;
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}`);
}
+85
View File
@@ -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<typeof churchExportSchema>;
/** 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)$/;
+3
View File
@@ -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";
+161 -1
View File
@@ -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, unknown>): 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<T extends Record<string, unknown>>(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<string, unknown>, 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<string, string> {
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()]);
}
+174
View File
@@ -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<string, unknown> = {}) {
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<Parameters<typeof verifyAgentRequest>[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"]);
});
});
@@ -35,6 +35,7 @@ const SAMPLE_SCHEMA: Record<string, string> = {
"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/)", () => {
+2
View File
@@ -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<string, z.ZodType> = {
"hub-heartbeat-accounts.json": hub.heartbeatRequestSchema,
"hub-heartbeat-response.json": hub.heartbeatResponseSchema,
"hub-licence-payload.json": hub.licencePayloadSchema,
"church-export.json": churchExportSchema,
};
describe("samples", () => {