@opensoha/contracts 0.1.23 → 0.1.25

package/agent/personal-environment-preflight-request.schema.json

@@ -0,0 +1,52 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://opensoha.dev/schemas/personal-environment-preflight-request.schema.json",
+  "title": "Personal Docker Node Preflight Request",
+  "description": "Trusted Core only. Uses an owned disposable quota probe and requires its cleanup before a ready receipt. Never provisions personal data or grants task execution.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "id",
+    "quota"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "const": "opensoha.dev/personal-environment-preflight-request/v1"
+    },
+    "id": {
+      "type": "string",
+      "pattern": "^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$"
+    },
+    "quota": {
+      "allOf": [
+        {
+          "$ref": "https://opensoha.dev/schemas/environment-lease.schema.json#/properties/quota"
+        },
+        {
+          "properties": {
+            "diskBytes": {
+              "minimum": 16777216,
+              "maximum": 1099511627776
+            },
+            "memoryBytes": {
+              "minimum": 33554432,
+              "maximum": 17179869184
+            },
+            "cpuUnits": {
+              "minimum": 1,
+              "maximum": 8000
+            },
+            "maxProcesses": {
+              "minimum": 4,
+              "maximum": 256
+            },
+            "networkEgress": {
+              "const": false
+            }
+          }
+        }
+      ]
+    }
+  }
+}

package/agent/personal-environment-preflight-result.schema.json

@@ -0,0 +1,69 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://opensoha.dev/schemas/personal-environment-preflight-result.schema.json",
+  "title": "Personal Docker Node Preflight Result",
+  "description": "Trusted Core only. Uses an owned disposable quota probe and requires its cleanup before a ready receipt. Never provisions personal data or grants task execution.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "id",
+    "quota",
+    "ready",
+    "cgroupVersion",
+    "diskMechanism",
+    "observedAt"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "const": "opensoha.dev/personal-environment-preflight-result/v1"
+    },
+    "id": {
+      "type": "string",
+      "pattern": "^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$"
+    },
+    "quota": {
+      "allOf": [
+        {
+          "$ref": "https://opensoha.dev/schemas/environment-lease.schema.json#/properties/quota"
+        },
+        {
+          "properties": {
+            "diskBytes": {
+              "minimum": 16777216,
+              "maximum": 1099511627776
+            },
+            "memoryBytes": {
+              "minimum": 33554432,
+              "maximum": 17179869184
+            },
+            "cpuUnits": {
+              "minimum": 1,
+              "maximum": 8000
+            },
+            "maxProcesses": {
+              "minimum": 4,
+              "maximum": 256
+            },
+            "networkEgress": {
+              "const": false
+            }
+          }
+        }
+      ]
+    },
+    "ready": {
+      "const": true
+    },
+    "cgroupVersion": {
+      "const": "2"
+    },
+    "diskMechanism": {
+      "const": "btrfs-qgroup"
+    },
+    "observedAt": {
+      "type": "string",
+      "format": "date-time"
+    }
+  }
+}

package/agent/personal-environment-request.schema.json

@@ -0,0 +1,137 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "additionalProperties": false,
+  "$id": "https://opensoha.dev/schemas/personal-environment-request.schema.json",
+  "title": "Personal Environment Agent Request",
+  "description": "POST /api/v1/runtime/personal-environments. Trusted Core bearer token and per-action allowlist required. Core derives owner/scope/quota and persists original lease identity. Acquire may recover the same original lease. Execute must never be automatically retried after a lost receipt; its outcome is unknown. Release stops only this lease and retains persistent data. Dispatch/observation has a 30 second deadline and cleanup an independent 30 second deadline; slow cleanup can outlast the HTTP receipt window; sandbox argv uses UTF-8 byte bounds. Export_data uses only POST /runtime/personal-environments/export: bounded framed TAR chunks and a final SHA-256 receipt; no ordinary JSON result, no extraction, no implicit wake.",
+  "required": [
+    "schemaVersion",
+    "action",
+    "lease"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "const": "opensoha.dev/personal-environment-request/v1"
+    },
+    "action": {
+      "enum": [
+        "acquire",
+        "inspect",
+        "execute",
+        "release",
+        "delete_data",
+        "export_data"
+      ]
+    },
+    "lease": {
+      "allOf": [
+        {
+          "$ref": "https://opensoha.dev/schemas/environment-lease.schema.json"
+        },
+        {
+          "properties": {
+            "workspacePath": {
+              "const": ""
+            },
+            "releasedAt": false,
+            "quota": {
+              "properties": {
+                "diskBytes": {
+                  "minimum": 16777216,
+                  "maximum": 1099511627776
+                },
+                "memoryBytes": {
+                  "minimum": 33554432,
+                  "maximum": 17179869184
+                },
+                "cpuUnits": {
+                  "minimum": 1,
+                  "maximum": 8000
+                },
+                "maxProcesses": {
+                  "minimum": 4,
+                  "maximum": 256
+                },
+                "networkEgress": {
+                  "const": false
+                }
+              }
+            }
+          }
+        }
+      ]
+    },
+    "argv": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 64,
+      "prefixItems": [
+        {
+          "type": "string",
+          "pattern": "^/[^\\u0000]*$",
+          "maxLength": 4096
+        }
+      ],
+      "items": {
+        "type": "string",
+        "maxLength": 4096,
+        "pattern": "^[^\\u0000]*$"
+      }
+    },
+    "taskId": {
+      "type": "string",
+      "pattern": "^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$",
+      "description": "Execute-only server-owned task UUID. Selects a private temporary task directory inside /workspace; never a host path or persistent-data owner. Omission retains legacy command working directory."
+    },
+    "createData": {
+      "type": "boolean",
+      "default": false,
+      "description": "Core permits true only during first provisioning, before any ready receipt or task execution. Restore/restart must require existing data; a missing volume or subvolume is an error."
+    }
+  },
+  "allOf": [
+    {
+      "if": {
+        "properties": {
+          "action": {
+            "const": "execute"
+          }
+        }
+      },
+      "then": {
+        "required": [
+          "argv"
+        ]
+      },
+      "else": {
+        "properties": {
+          "argv": false,
+          "taskId": false
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "action": {
+            "enum": [
+              "inspect",
+              "execute",
+              "release",
+              "delete_data",
+              "export_data"
+            ]
+          }
+        }
+      },
+      "then": {
+        "properties": {
+          "createData": {
+            "const": false
+          }
+        }
+      }
+    }
+  ]
+}

package/agent/personal-environment-result.schema.json

@@ -0,0 +1,101 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "additionalProperties": false,
+  "$id": "https://opensoha.dev/schemas/personal-environment-result.schema.json",
+  "title": "Personal Environment Agent Result",
+  "description": "Agent API data envelope. Missing or stopped environments omit usage; no invented zero measurement. Active receipts include fresh hard-quota/cgroup observations. Docker handles, volume names, and provider failures are private.",
+  "required": [
+    "schemaVersion",
+    "leaseId",
+    "runId",
+    "state",
+    "observedAt"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "const": "opensoha.dev/personal-environment-result/v1"
+    },
+    "leaseId": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 128
+    },
+    "runId": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 128
+    },
+    "taskId": {
+      "type": "string",
+      "pattern": "^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$",
+      "description": "Echo the exact server-owned execute task identity when supplied. A result for another task is not a receipt for this command."
+    },
+    "state": {
+      "enum": [
+        "active",
+        "released",
+        "expired",
+        "missing",
+        "quota_exceeded",
+        "deleted"
+      ]
+    },
+    "snapshot": {
+      "$ref": "https://opensoha.dev/schemas/environment-snapshot.schema.json"
+    },
+    "output": {
+      "type": "string",
+      "maxLength": 65536
+    },
+    "observedAt": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "exitCode": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 255,
+      "description": "Confirmed bounded sandbox process exit status; absent for non-execute results."
+    }
+  },
+  "allOf": [
+    {
+      "if": {
+        "required": [
+          "taskId"
+        ]
+      },
+      "then": {
+        "required": [
+          "output"
+        ]
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "state": {
+            "enum": [
+              "active",
+              "quota_exceeded"
+            ]
+          }
+        }
+      },
+      "then": {
+        "required": [
+          "snapshot"
+        ]
+      },
+      "else": {
+        "properties": {
+          "snapshot": false,
+          "output": false,
+          "taskId": false,
+          "exitCode": false
+        }
+      }
+    }
+  ]
+}

package/agent/personal-guest-binding.schema.json

@@ -0,0 +1,92 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://opensoha.dev/schemas/personal-guest-binding.schema.json",
+  "title": "Personal VM Guest Frozen Binding",
+  "description": "Core-owned immutable binding delivered only to the registered guest over authenticated TLS. Version is the identity revision, not the environment operation CAS version. Compute/data refs are opaque resource UUIDs; no PVE credentials, node URL, host paths or provider disk handles. Runtime additionally enforces 0 < expiresAt-issuedAt <= 24 hours. Provider metadata is not proof that that provider supports personal guest execution.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "id",
+    "version",
+    "assistantId",
+    "ownerId",
+    "provider",
+    "computeRef",
+    "computeGeneration",
+    "providerIdentityHash",
+    "dataRef",
+    "dataDiskSerial",
+    "dataDiskBytes",
+    "policyRevision",
+    "issuedAt",
+    "expiresAt"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "const": "opensoha.dev/personal-guest-binding/v1"
+    },
+    "id": {
+      "type": "string",
+      "pattern": "^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$"
+    },
+    "version": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 9007199254740991
+    },
+    "assistantId": {
+      "type": "string",
+      "pattern": "^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$"
+    },
+    "ownerId": {
+      "type": "string",
+      "pattern": "^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$"
+    },
+    "provider": {
+      "enum": [
+        "pve",
+        "kubevirt"
+      ]
+    },
+    "computeRef": {
+      "type": "string",
+      "pattern": "^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$"
+    },
+    "computeGeneration": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 9007199254740991
+    },
+    "dataRef": {
+      "type": "string",
+      "pattern": "^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$"
+    },
+    "dataDiskSerial": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9_-]{1,20}$"
+    },
+    "dataDiskBytes": {
+      "type": "integer",
+      "minimum": 16777216,
+      "maximum": 1099511627776
+    },
+    "policyRevision": {
+      "type": "string",
+      "pattern": "^sha256:[a-f0-9]{64}$"
+    },
+    "issuedAt": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "expiresAt": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "providerIdentityHash": {
+      "type": "string",
+      "pattern": "^sha256:[a-f0-9]{64}$",
+      "description": "Core-derived SHA-256 of the provider, capacity source, provider VM ID, observed provider incarnation and exact provider data volume. Current provider and disk observation must match; the personal compute generation alone is not a provider incarnation. Provider disk handles are not disclosed."
+    }
+  }
+}

package/agent/personal-guest-data-plan.schema.json

@@ -0,0 +1,32 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://opensoha.dev/schemas/personal-guest-data-plan.schema.json",
+  "title": "Personal Guest Data Operation",
+  "description": "A fixed, privileged Core operation uses this plan. Core reserves operationId durably and current authorization before provider dispatch. GET /api/personal-guest/v1/bindings/{id}/data-operations/{operationId} requires registered pinned mTLS and returns a plan only while the matching task and reservation are running. Owner, current access, frozen VM/disk identity, quota, actor permissions and resource scope are rechecked; a binding GET or heartbeat grants no data mutation. The Linux initializer accepts only a root-owned plan and formats only a positively blank independent disk once. No arbitrary command, path or provider credential is accepted. XFS project 49 covers the fixed workspace; the project hard limit must be enforced and read back before a success receipt. Completed receipts follow stable workspace identity across explicit certificate renewal. Lost format results retain the original dispatch marker and cannot cause another format.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "operationId",
+    "binding",
+    "diskQuotaBytes"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "const": "opensoha.dev/personal-guest-data-plan/v1"
+    },
+    "operationId": {
+      "type": "string",
+      "pattern": "^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$"
+    },
+    "binding": {
+      "$ref": "personal-guest-binding.schema.json"
+    },
+    "diskQuotaBytes": {
+      "type": "integer",
+      "minimum": 16777216,
+      "maximum": 1099511627775,
+      "multipleOf": 1024
+    }
+  }
+}

package/agent/personal-guest-enrollment.schema.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://opensoha.dev/schemas/personal-guest-enrollment.schema.json",
+  "title": "Personal VM Guest Enrollment",
+  "description": "New personal-guest/v1 protocol; never sent to Docker v1 or a Network Control enrollment route. A guest-specific mTLS certificate and a short one-time challenge in Authorization are required. Core derives assistant, owner, VM generation, data identity, policy and binding from the pending registration. Atomic one-time challenge consumption and current owner/access checks are server duties. This request grants registration and heartbeat only; no Docker/PVE/SSH/network management or task execution rights. POST /api/personal-guest/v1/bindings/{bindingId}/enroll returns 201 with the binding. Authorization is exactly Bearer followed by a canonical, unpadded base64url 32-byte crypto/rand challenge (43 characters), issued for 60–600 seconds and pinned to the binding plus certificate fingerprint; only its SHA256 hash is persisted. A consumed challenge cannot be replayed: 401. After a lost response, GET the same binding with the pinned certificate; this does not issue new authority. Missing/wrong certificate, challenge, enrollment or expired registration: 401; current owner/access, superseded binding or policy rejection: 403. Reject duplicate JSON keys and noncanonical field casing; no credential is accepted in a query or forwarded header.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "enrollmentId"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "const": "opensoha.dev/personal-guest-enrollment/v1"
+    },
+    "enrollmentId": {
+      "type": "string",
+      "pattern": "^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$"
+    }
+  }
+}

package/agent/personal-guest-heartbeat.schema.json

@@ -0,0 +1,44 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://opensoha.dev/schemas/personal-guest-heartbeat.schema.json",
+  "title": "Personal VM Guest Heartbeat",
+  "description": "Guest-specific mTLS certificate required. Core checks pinned credential, current owner/access, unrevoked binding, validity, identity revision, compute generation and strictly increasing sequence atomically. Observation must fall within binding validity and 30 seconds of server time. Heartbeat is liveness only: provider, data mount/UUID/hard quota, command/file/browser probes remain independent; this message has no readiness or arbitrary capabilities field. POST /api/personal-guest/v1/bindings/{bindingId}/heartbeats returns 204 only after atomic monotonic sequence storage, current authority and pinned mTLS checks. Replayed/stale sequence or mismatched binding/generation: 409; rejected current authority: 403; wrong/expired certificate registration: 401. Body is bounded to 4096 UTF-8 bytes; duplicate keys and noncanonical field casing are rejected. Heartbeat never sets environment/data/tool readiness.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "bindingId",
+    "bindingVersion",
+    "computeGeneration",
+    "sequence",
+    "observedAt"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "const": "opensoha.dev/personal-guest-heartbeat/v1"
+    },
+    "bindingId": {
+      "type": "string",
+      "pattern": "^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$"
+    },
+    "bindingVersion": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 9007199254740991
+    },
+    "computeGeneration": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 9007199254740991
+    },
+    "sequence": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 9007199254740991
+    },
+    "observedAt": {
+      "type": "string",
+      "format": "date-time"
+    }
+  }
+}

package/agent/personal-guest-provisioning.schema.json

@@ -0,0 +1,71 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://opensoha.dev/schemas/personal-guest-provisioning.schema.json",
+  "title": "Fixed Personal Guest Provisioning",
+  "description": "Core-derived, encrypted durable task content delivered only to the fixed QGA installer on the frozen owned VM. The private key remains in that VM at /home/soha/.soha-personal-guest/bootstrap.key. No arbitrary command or path is accepted. Artifact download requires the current dedicated mTLS identity, returns an octet stream with no-store, and is pinned to the Core configured SHA256. Certificate/private key and one-time challenge material must not enter task responses, audits or logs. The guest unit runs as soha UID1000, with frozen cgroup and network limits. A separate root oneshot only reconciles a completed protected data receipt using GET /bindings/{id}/data-lease and can never format. The data lease requires a current registered identity, current owner/access/VM mutation permissions, initialized data and no competing reservation.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "plan",
+    "endpoint",
+    "enrollmentId",
+    "challenge",
+    "certificatePEM",
+    "clientCAPEM",
+    "artifactSHA256",
+    "cpuQuotaMilli",
+    "memoryBytes",
+    "pidsLimit",
+    "network"
+  ],
+  "properties": {
+    "plan": {
+      "$ref": "personal-guest-data-plan.schema.json"
+    },
+    "endpoint": {
+      "type": "string",
+      "format": "uri",
+      "maxLength": 512
+    },
+    "enrollmentId": {
+      "type": "string",
+      "format": "uuid"
+    },
+    "challenge": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9_-]{43}$"
+    },
+    "certificatePEM": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 4096
+    },
+    "clientCAPEM": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 8192
+    },
+    "artifactSHA256": {
+      "type": "string",
+      "pattern": "^[a-f0-9]{64}$"
+    },
+    "cpuQuotaMilli": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 8000
+    },
+    "memoryBytes": {
+      "type": "integer",
+      "minimum": 33554432,
+      "maximum": 17179869184
+    },
+    "pidsLimit": {
+      "type": "integer",
+      "minimum": 4,
+      "maximum": 256
+    },
+    "network": {
+      "const": false
+    }
+  }
+}

package/agent/personal-guest-renewal.schema.json

@@ -0,0 +1,33 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://opensoha.dev/schemas/personal-guest-renewal.schema.json",
+  "title": "Personal Guest Certificate Renewal",
+  "description": "POST /api/personal-guest/v1/bindings/{bindingId}/renewals uses the current pinned mTLS certificate and returns requestId, binding, certificatePEM and clientCAPEM and commitBefore. A durable requestId and identical CSR recover a lost response. POST /renewals/{requestId}/commit uses the pending new certificate; repeats recover a lost commit. Core rechecks current owner/access/provider identity on both steps. Only commit promotes binding version and certificate; heartbeat sequence is preserved. Expired pending requests return 410 only after authenticating the still-current certificate and owner. The client must verify the unchanged current binding before durably replacing its expired request ID. Expired certificates cannot renew. Duplicate keys, unknown fields and noncanonical casing are rejected. The new certificate grants liveness only, never data or execution readiness.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "requestId",
+    "bindingVersion",
+    "csrPEM"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "const": "opensoha.dev/personal-guest-renewal/v1"
+    },
+    "requestId": {
+      "type": "string",
+      "pattern": "^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$"
+    },
+    "bindingVersion": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 9007199254740990
+    },
+    "csrPEM": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 2048
+    }
+  }
+}