@openwop/spec-artifacts 2.0.0-rc.0

package/schemas/v2/security-advisory.schema.json

@@ -0,0 +1,138 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openwop.dev/spec/v2/security-advisory.schema.json",
+  "title": "SecurityAdvisory",
+  "description": "Registry-owned security advisory for a published OpenWOP pack version. Sourced from registry/security/advisories.json. Every entry MUST be reviewed + merged via maintainer PR; the CI check-advisories gate refuses to deploy if any active advisory targets a pack version that is not already yanked.",
+  "type": "object",
+  "required": [
+    "id",
+    "publishedAt",
+    "severity",
+    "summary",
+    "affected"
+  ],
+  "properties": {
+    "id": {
+      "type": "string",
+      "description": "Stable advisory identifier. Format: `OPENWOP-YYYY-NNNN` (sequential, assigned by maintainers at PR merge time). MAY also include an aliased CVE ID via `cveIds[]`.",
+      "pattern": "^OPENWOP-[0-9]{4}-[0-9]{4}$"
+    },
+    "cveIds": {
+      "type": "array",
+      "description": "Aliased CVE identifiers if a CVE was reserved through Mitre or a CNA. Listed in cve.mitre.org format.",
+      "items": {
+        "type": "string",
+        "pattern": "^CVE-[0-9]{4}-[0-9]+$"
+      },
+      "uniqueItems": true
+    },
+    "publishedAt": {
+      "type": "string",
+      "format": "date",
+      "description": "Date the advisory was first published (ISO 8601 yyyy-mm-dd). Frozen at merge time; do not update on revision."
+    },
+    "updatedAt": {
+      "type": "string",
+      "format": "date",
+      "description": "Date of last advisory update. Bump when severity, affected, or fixedIn changes."
+    },
+    "severity": {
+      "type": "string",
+      "enum": [
+        "critical",
+        "high",
+        "medium",
+        "low"
+      ],
+      "description": "Severity per the rubric in docs/runbooks/INCIDENT-RESPONSE.md. critical=S0 (yank immediately), high=S1, medium=S2, low=S3."
+    },
+    "cvssV4Score": {
+      "type": "number",
+      "minimum": 0,
+      "maximum": 10,
+      "description": "Optional CVSS 4.0 base score. Informational; severity field is the authoritative classification."
+    },
+    "summary": {
+      "type": "string",
+      "description": "One-line human-readable summary of the vulnerability. Surfaces in tooling output.",
+      "minLength": 1,
+      "maxLength": 200
+    },
+    "details": {
+      "type": "string",
+      "description": "Long-form description: vulnerability mechanism, attack vector, impact, recommended consumer action. May reference external URLs via advisoryUrl."
+    },
+    "advisoryUrl": {
+      "type": "string",
+      "format": "uri",
+      "description": "External advisory link (e.g., GitHub Security Advisory, vendor security page, CVE detail page)."
+    },
+    "affected": {
+      "type": "array",
+      "description": "Pack versions impacted by this advisory. Each entry pins a pack name + a SemVer range. The check-advisories CI gate cross-references this list against every published version and fails if any non-yanked version matches.",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": [
+          "packName",
+          "versions"
+        ],
+        "properties": {
+          "packName": {
+            "type": "string",
+            "description": "Pack name (e.g., `vendor.myndhyve.ai`). MUST exist under registry/v1/packs/.",
+            "pattern": "^[a-z][a-z0-9-]*(\\.[a-z][a-z0-9-]*)+$"
+          },
+          "versions": {
+            "type": "string",
+            "description": "SemVer range using node-semver syntax (`<1.0.0`, `>=1.0.0 <1.0.3`, `1.0.0 || 1.0.1`). Matched against published version numbers via the check-advisories gate."
+          },
+          "fixedIn": {
+            "type": "string",
+            "description": "Earliest version that contains the fix. Consumers MUST upgrade to >= this version. Absent if no fix is available yet (defense-only).",
+            "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+(-[a-zA-Z0-9.-]+)?(\\+[a-zA-Z0-9.-]+)?$"
+          },
+          "fixedInRef": {
+            "type": "string",
+            "description": "PR or commit reference where the fix landed (e.g., `openwop/openwop#42`). Helps consumers audit the patch."
+          }
+        },
+        "additionalProperties": false
+      }
+    },
+    "credits": {
+      "type": "array",
+      "description": "Acknowledged reporters or researchers.",
+      "items": {
+        "type": "object",
+        "required": [
+          "name"
+        ],
+        "properties": {
+          "name": {
+            "type": "string",
+            "minLength": 1
+          },
+          "url": {
+            "type": "string",
+            "format": "uri"
+          },
+          "role": {
+            "type": "string",
+            "enum": [
+              "finder",
+              "reporter",
+              "analyst",
+              "coordinator",
+              "remediation-developer"
+            ],
+            "description": "Per CSAF role vocabulary. Defaults to `finder` when not specified."
+          }
+        },
+        "additionalProperties": false
+      }
+    }
+  },
+  "additionalProperties": false,
+  "x-openwop-seeded-from": "v1"
+}

package/schemas/v2/self-hosted-runner-dispatch-frame.schema.json

@@ -0,0 +1,119 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openwop.dev/spec/v2/self-hosted-runner-dispatch-frame.schema.json",
+  "title": "SelfHostedRunnerDispatchFrame",
+  "description": "RFC 0122 §Registration + channel. A single model/tool DISPATCH STEP the host routes to a registered runner over the runner↔host channel (`self-hosted-runner.md`). The host is the sole orchestration/persistence/replay authority; this frame carries ONE step's inputs, never a whole run. `inputs` is opaque model/tool input (messages, tool arguments) and MUST NOT contain runner-credential material — the runner holds its own credential locally (SECURITY invariant `runner-credential-non-transit`). `seq` is the per-runner monotonic DISPATCH cursor, a DISTINCT sequence from the run event-log `sequence` (they MUST NOT be conflated); a reconnecting runner resumes via `Last-Event-ID` at this cursor and the host drops any redelivered `{runId, stepId}` whose result is already persisted (at-most-once).",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "runId",
+    "stepId",
+    "seq",
+    "kind",
+    "inputs"
+  ],
+  "properties": {
+    "runId": {
+      "$ref": "ids.schema.json#/$defs/runId",
+      "description": "The backing OpenWOP run this dispatch belongs to. Host-owned run identity."
+    },
+    "stepId": {
+      "type": "string",
+      "minLength": 1,
+      "description": "The dispatch step within the run. The `{runId, stepId}` pair is the at-most-once idempotency key: a runner MUST return the result under the same pair, and the host MUST drop (not re-dispatch) a redelivered `{runId, stepId}` whose result is already persisted."
+    },
+    "seq": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "The per-runner monotonic dispatch cursor for the channel. DISTINCT from the run event-log `sequence` (MUST NOT be conflated — conflating them breaks resume dedup). A reconnecting runner resumes via the SSE `Last-Event-ID` at this cursor so a dispatch is never redelivered past it (`stream-modes.md §Resumption`)."
+    },
+    "kind": {
+      "type": "string",
+      "enum": [
+        "model",
+        "tool"
+      ],
+      "description": "Whether this step dispatches a model call (`model`) or a tool call (`tool`). A host MAY advertise only a subset via `selfHostedRunner.dispatchKinds` and route only those kinds to runners."
+    },
+    "provider": {
+      "type": "string",
+      "minLength": 1,
+      "description": "REQUIRED when `kind == 'model'`. The model provider id the runner dispatches to under its locally-held credential (e.g. a subscription CLI login, a private endpoint). Never a host-held credential."
+    },
+    "model": {
+      "type": "string",
+      "minLength": 1,
+      "description": "REQUIRED when `kind == 'model'`. The model id to run."
+    },
+    "tool": {
+      "type": "string",
+      "minLength": 1,
+      "description": "REQUIRED when `kind == 'tool'`. The tool the runner executes locally."
+    },
+    "inputs": {
+      "type": "object",
+      "description": "Opaque model/tool inputs for this step (messages, tool arguments). MUST NOT contain runner-credential material (`runner-credential-non-transit`). The host sends inputs and receives outputs; the credential stays on the runner.",
+      "additionalProperties": true
+    }
+  },
+  "allOf": [
+    {
+      "if": {
+        "properties": {
+          "kind": {
+            "const": "model"
+          }
+        }
+      },
+      "then": {
+        "required": [
+          "provider",
+          "model"
+        ]
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "kind": {
+            "const": "tool"
+          }
+        }
+      },
+      "then": {
+        "required": [
+          "tool"
+        ]
+      }
+    }
+  ],
+  "examples": [
+    {
+      "runId": "run_x",
+      "stepId": "step_3",
+      "seq": 12,
+      "kind": "model",
+      "provider": "anthropic",
+      "model": "claude-opus-4-8",
+      "inputs": {
+        "messages": [
+          {
+            "role": "user",
+            "content": "summarize the attached notes"
+          }
+        ]
+      }
+    },
+    {
+      "runId": "run_y",
+      "stepId": "step_1",
+      "seq": 0,
+      "kind": "tool",
+      "tool": "local.shell.readFile",
+      "inputs": {
+        "path": "/home/user/notes.txt"
+      }
+    }
+  ],
+  "x-openwop-seeded-from": "v1"
+}

package/schemas/v2/self-hosted-runner-registration.schema.json

@@ -0,0 +1,74 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openwop.dev/spec/v2/self-hosted-runner-registration.schema.json",
+  "title": "SelfHostedRunnerRegistration",
+  "description": "RFC 0122 §Registration + channel. The per-subject runtime record the host keeps for a registered runner after it dials in and authenticates with a host-minted, subject-scoped runner bearer (NEVER a provider credential). This record is per-subject runtime state and MUST NOT appear on `/.well-known/openwop` (only the `selfHostedRunner` capability block does). Work is addressed by `runnerId` (direct) or by capability-match; a capability match MUST filter on `subject` FIRST, then capability, so a subject's step is never routed to another subject's runner (subject-first match, SR-1-adjacent — a normative MUST in `self-hosted-runner.md` §Behavior verified by the gated conformance scenario).",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "runnerId",
+    "subject",
+    "capabilities"
+  ],
+  "properties": {
+    "runnerId": {
+      "type": "string",
+      "minLength": 1,
+      "description": "The host-assigned identifier for this runner connection. Used for direct dispatch addressing."
+    },
+    "subject": {
+      "type": "string",
+      "minLength": 1,
+      "description": "The owning principal — the stable RFC 0048 subject the host stamps on the backing run's `run.metadata`, NOT a fresh id. A runner is bound to exactly one owning subject; capability-match and fork-reroute MUST key on this subject FIRST."
+    },
+    "capabilities": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "What this runner can serve. Empty arrays / omitted keys mean the runner serves none of that kind; capability-match considers only runners whose declared capability covers the dispatch step.",
+      "properties": {
+        "providers": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "uniqueItems": true,
+          "description": "Model provider ids the runner can dispatch to under its locally-held credentials."
+        },
+        "models": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "uniqueItems": true,
+          "description": "Specific model ids the runner can run (a refinement of `providers`)."
+        },
+        "tools": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "uniqueItems": true,
+          "description": "Tool ids the runner can execute locally."
+        }
+      }
+    }
+  },
+  "examples": [
+    {
+      "runnerId": "runner_laptop_01",
+      "subject": "user_42",
+      "capabilities": {
+        "providers": [
+          "anthropic"
+        ],
+        "models": [
+          "claude-opus-4-8"
+        ]
+      }
+    }
+  ],
+  "x-openwop-seeded-from": "v1"
+}

package/schemas/v2/self-hosted-runner-result-frame.schema.json

@@ -0,0 +1,47 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openwop.dev/spec/v2/self-hosted-runner-result-frame.schema.json",
+  "title": "SelfHostedRunnerResultFrame",
+  "description": "RFC 0122 §Registration + channel. The runner's answer to one `SelfHostedRunnerDispatchFrame`, POSTed back to the host over ordinary HTTP. The `{runId, stepId}` pair MUST equal the dispatch it answers (the at-most-once idempotency key); `seq` echoes the dispatch cursor. `output` is the opaque model/tool output the host persists as a normal step record — replay reads from persistence and NEVER re-dispatches. `output` MUST NOT contain runner-credential material (`runner-credential-non-transit`), and the host MUST treat it as UNTRUSTED transport: content re-entering an agent loop is fenced `<UNTRUSTED>` (`runner-output-untrusted-transport`). A provider-side error is carried inside `output` (it is still a model/tool output); host-side liveness failure is signalled out-of-band as the retriable `runner_unavailable` error, NOT as a result frame.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "runId",
+    "stepId",
+    "seq",
+    "output"
+  ],
+  "properties": {
+    "runId": {
+      "$ref": "ids.schema.json#/$defs/runId",
+      "description": "The run this result answers. MUST equal the dispatch frame's `runId`."
+    },
+    "stepId": {
+      "type": "string",
+      "minLength": 1,
+      "description": "The dispatch step this result answers. MUST equal the dispatch frame's `stepId`. The host drops the frame if a result for this `{runId, stepId}` is already persisted (at-most-once)."
+    },
+    "seq": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Echoes the answered dispatch frame's per-runner cursor `seq`."
+    },
+    "output": {
+      "type": "object",
+      "description": "Opaque model/tool output for the step, persisted by the host as a normal step record. MUST NOT contain runner-credential material; the host fences it `<UNTRUSTED>` before it re-enters an agent loop (`runner-output-untrusted-transport`). A provider/tool error response is carried here (still an output).",
+      "additionalProperties": true
+    }
+  },
+  "examples": [
+    {
+      "runId": "run_x",
+      "stepId": "step_3",
+      "seq": 12,
+      "output": {
+        "role": "assistant",
+        "content": "Here is a summary of the notes: ..."
+      }
+    }
+  ],
+  "x-openwop-seeded-from": "v1"
+}

package/schemas/v2/subject-link.schema.json

@@ -0,0 +1,69 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openwop.dev/spec/v2/subject-link.schema.json",
+  "title": "SubjectLink (RFC 0170 §C.1)",
+  "description": "A tenant-scoped join of exactly two subjects whose issuers are bound to one IdP entityID (RFC 0163 §B.1). Never a legacy or anonymous subject. deniedAt deactivates; the SAML decision path consults it (RFC 0159/0164). A reference, not a merge.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "a",
+    "b",
+    "keyClass",
+    "issuer",
+    "tenant",
+    "formedAt"
+  ],
+  "properties": {
+    "a": {
+      "$ref": "#/$defs/subjectRef"
+    },
+    "b": {
+      "$ref": "#/$defs/subjectRef"
+    },
+    "keyClass": {
+      "type": "string",
+      "enum": [
+        "opaque-idp",
+        "configured-immutable"
+      ]
+    },
+    "issuer": {
+      "type": "string",
+      "minLength": 1,
+      "description": "The IdP entityID both issuers are bound to."
+    },
+    "tenant": {
+      "$ref": "ids.schema.json#/$defs/tenantId"
+    },
+    "formedAt": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "deniedAt": {
+      "type": "string",
+      "format": "date-time"
+    }
+  },
+  "$defs": {
+    "subjectRef": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "issuer",
+        "subjectId"
+      ],
+      "properties": {
+        "issuer": {
+          "type": "string",
+          "minLength": 1,
+          "not": {
+            "const": "urn:openwop:legacy"
+          }
+        },
+        "subjectId": {
+          "$ref": "ids.schema.json#/$defs/subjectId"
+        }
+      }
+    }
+  }
+}