@ekka-ai/shelves 0.2.2

package/dist/contracts/shelves/protocol-v1.schema.json

@@ -0,0 +1,595 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://schemas.ekka.ai/shelves/protocol-v1.schema.json",
+  "title": "ShelfProtocolV1",
+  "description": "The shelf protocol v1 between an EKKA Enclave and a Business API (E1 v3.2, section 2; ekka-ai/.github#674). Three routes, mounted by the provider's `@ekka/shelves` plugin and nothing else: `GET /ekka/shelves/v1/ping` (public, answers `ping` below), `GET /ekka/shelves/v1/manifest` (bearer-authenticated, answers `manifest`), `POST /ekka/shelves/v1/invoke` (bearer-authenticated, takes `request`, answers `response`). The Enclave never learns another route, and a plan never supplies a URL, method or header. The bearer is the per-shelf principal key the provider issued; it is the provider's transport auth, not EKKA's authority. This file declares shapes; which definition a route uses is stated in each definition.",
+  "definitions": {
+    "shelf_id": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9_]{0,31}(\\.[a-z][a-z0-9_]{0,31})+$",
+      "maxLength": 200,
+      "description": "A shelf id: lowercase dotted segments. A predefined id (shelves/registry.json) has exactly two segments; a company's private shelf may be deeper and may never equal a predefined id (checked at import)."
+    },
+    "verb": {
+      "type": "string",
+      "enum": [
+        "read",
+        "list"
+      ],
+      "description": "v1 verbs. `write`, `update`, `delete` and `send` are reserved and refused."
+    },
+    "scalar": {
+      "type": [
+        "string",
+        "integer",
+        "boolean"
+      ],
+      "description": "No floats: a lookup value is a string, an integer or a boolean."
+    },
+    "by": {
+      "type": "object",
+      "maxProperties": 16,
+      "propertyNames": {
+        "pattern": "^[a-z][a-z0-9_]{0,31}$"
+      },
+      "additionalProperties": {
+        "$ref": "#/definitions/scalar"
+      },
+      "description": "Equality-only lookup. For `read` it names EXACTLY the shelf's unique key set; for `list` a subset of its declared keys. The provider refuses an undeclared key with `unknown_key`."
+    },
+    "page": {
+      "type": "object",
+      "properties": {
+        "limit": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 1000
+        },
+        "cursor": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "maxLength": 1024
+        }
+      },
+      "required": [
+        "limit"
+      ],
+      "additionalProperties": false,
+      "description": "`list` only. The provider returns at most min(limit, the shelf's page_cap) records."
+    },
+    "record": {
+      "type": "object",
+      "maxProperties": 64,
+      "description": "One record in the shelf's field set. Its exact shape is checked by the Enclave against the interface pinned for the run (SHELF_RECORD_INVALID), not by this schema."
+    },
+    "invocation_payload": {
+      "type": "object",
+      "properties": {
+        "tenant": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 64
+        },
+        "agent": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128
+        },
+        "run": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 64
+        },
+        "step": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128
+        },
+        "shelf": {
+          "$ref": "#/definitions/shelf_id"
+        },
+        "verb": {
+          "$ref": "#/definitions/verb"
+        },
+        "iat": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Issued at, whole seconds since the Unix epoch."
+        },
+        "exp": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Expiry, whole seconds; exactly iat + 60."
+        }
+      },
+      "required": [
+        "tenant",
+        "agent",
+        "run",
+        "step",
+        "shelf",
+        "verb",
+        "iat",
+        "exp"
+      ],
+      "additionalProperties": false,
+      "description": "What the Enclave asserts about one invocation. No person identity in v1: an automated run has none."
+    },
+    "invocation_assertion": {
+      "type": "object",
+      "properties": {
+        "alg": {
+          "type": "string",
+          "const": "ed25519"
+        },
+        "key_id": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128,
+          "description": "The Enclave node key's id, the same key that signs its receipts; its public key is published by govern and fetched once at import."
+        },
+        "payload_b64": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 4096,
+          "pattern": "^[A-Za-z0-9+/]+={0,2}$",
+          "description": "Standard base64 of the canonical JSON of `invocation_payload`."
+        },
+        "sig_b64": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 256,
+          "pattern": "^[A-Za-z0-9+/]+={0,2}$",
+          "description": "Standard base64 of the ed25519 signature over the SIGNED BYTES defined in this definition's description."
+        }
+      },
+      "required": [
+        "alg",
+        "key_id",
+        "payload_b64",
+        "sig_b64"
+      ],
+      "additionalProperties": false,
+      "description": "The signed invocation, carried as `request.auth`. DOMAIN-SEPARATED SIGNING, so these bytes can never be replayed as any other EKKA signature: SIGNED BYTES = the ASCII prefix `ekka.shelf.invocation.v1` followed by one newline (0x0A), followed by the canonical JSON of the payload. CANONICAL JSON is SECURITY.CANONICALIZE.V1: UTF-8, object keys sorted by code point at every level, no insignificant whitespace, integers only (the payload has no floats), strings escaped per RFC 8785. `payload_b64` carries exactly those canonical bytes (without the prefix), so a verifier: (1) base64-decodes `payload_b64`; (2) prepends `ekka.shelf.invocation.v1\\n`; (3) verifies `sig_b64` over the result with the public key for `key_id`; (4) parses the payload and checks `shelf` and `verb` equal the request's, `exp == iat + 60`, and now is within [iat - 5, exp]; it NEVER re-canonicalizes. v1 providers MAY skip verification; the field is always present so v2 row policy needs no protocol change."
+    },
+    "request": {
+      "type": "object",
+      "properties": {
+        "protocol": {
+          "const": 1
+        },
+        "request_id": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128
+        },
+        "shelf": {
+          "$ref": "#/definitions/shelf_id"
+        },
+        "interface_major": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "verb": {
+          "$ref": "#/definitions/verb"
+        },
+        "by": {
+          "$ref": "#/definitions/by"
+        },
+        "page": {
+          "$ref": "#/definitions/page"
+        },
+        "auth": {
+          "$ref": "#/definitions/invocation_assertion"
+        }
+      },
+      "required": [
+        "protocol",
+        "request_id",
+        "shelf",
+        "interface_major",
+        "verb",
+        "by",
+        "auth"
+      ],
+      "additionalProperties": false,
+      "description": "Body of `POST /ekka/shelves/v1/invoke`. `page` is for `list` only; a `read` carrying one is refused as `shape`."
+    },
+    "refusal": {
+      "type": "object",
+      "properties": {
+        "code": {
+          "type": "string",
+          "enum": [
+            "unknown_key",
+            "forbidden",
+            "not_implemented",
+            "shape",
+            "provider_error"
+          ]
+        },
+        "message": {
+          "type": "string",
+          "maxLength": 500,
+          "description": "For the operator. Never a record value."
+        }
+      },
+      "required": [
+        "code",
+        "message"
+      ],
+      "additionalProperties": false,
+      "description": "A typed refusal. `unknown_key`: `by` names a key the shelf does not declare. `forbidden`: the presenting principal may not use this shelf or verb. `not_implemented`: the verb is not served. `shape`: the request is malformed. `provider_error`: the provider failed."
+    },
+    "read_result": {
+      "oneOf": [
+        {
+          "type": "object",
+          "properties": {
+            "record": {
+              "$ref": "#/definitions/record"
+            }
+          },
+          "required": [
+            "record"
+          ],
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "properties": {
+            "not_found": {
+              "const": true
+            }
+          },
+          "required": [
+            "not_found"
+          ],
+          "additionalProperties": false
+        }
+      ]
+    },
+    "list_result": {
+      "type": "object",
+      "properties": {
+        "records": {
+          "type": "array",
+          "maxItems": 1000,
+          "items": {
+            "$ref": "#/definitions/record"
+          }
+        },
+        "next_cursor": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "maxLength": 1024
+        }
+      },
+      "required": [
+        "records",
+        "next_cursor"
+      ],
+      "additionalProperties": false
+    },
+    "response": {
+      "type": "object",
+      "properties": {
+        "protocol": {
+          "const": 1
+        },
+        "request_id": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128
+        },
+        "offer_version": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 64
+        },
+        "shelf": {
+          "$ref": "#/definitions/shelf_id"
+        },
+        "verb": {
+          "$ref": "#/definitions/verb"
+        },
+        "result": {
+          "oneOf": [
+            {
+              "$ref": "#/definitions/read_result"
+            },
+            {
+              "$ref": "#/definitions/list_result"
+            }
+          ]
+        },
+        "refusal": {
+          "$ref": "#/definitions/refusal"
+        }
+      },
+      "required": [
+        "protocol",
+        "request_id",
+        "offer_version",
+        "shelf",
+        "verb"
+      ],
+      "oneOf": [
+        {
+          "required": [
+            "result"
+          ]
+        },
+        {
+          "required": [
+            "refusal"
+          ]
+        }
+      ],
+      "additionalProperties": false,
+      "description": "Answer of `invoke`: exactly one of `result` or `refusal`. The Enclave also checks `request_id`, `shelf` and `verb` echo the request and `offer_version` equals the version pinned for the run."
+    },
+    "private_shape": {
+      "type": "object",
+      "properties": {
+        "keys": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 16,
+          "items": {
+            "type": "object",
+            "properties": {
+              "name": {
+                "type": "string",
+                "pattern": "^[a-z][a-z0-9_]{0,31}$"
+              },
+              "type": {
+                "type": "string",
+                "enum": [
+                  "string",
+                  "integer",
+                  "boolean",
+                  "month",
+                  "date",
+                  "currency_code",
+                  "money_minor"
+                ]
+              },
+              "unique": {
+                "type": "boolean"
+              }
+            },
+            "required": [
+              "name",
+              "type",
+              "unique"
+            ],
+            "additionalProperties": false
+          }
+        },
+        "fields": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 64,
+          "items": {
+            "type": "object",
+            "properties": {
+              "name": {
+                "type": "string",
+                "pattern": "^[a-z][a-z0-9_]{0,31}$"
+              },
+              "type": {
+                "type": "string",
+                "enum": [
+                  "string",
+                  "integer",
+                  "boolean",
+                  "month",
+                  "date",
+                  "currency_code",
+                  "money_minor"
+                ]
+              },
+              "required": {
+                "type": "boolean"
+              }
+            },
+            "required": [
+              "name",
+              "type",
+              "required"
+            ],
+            "additionalProperties": false
+          }
+        },
+        "page_cap": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 1000
+        }
+      },
+      "required": [
+        "keys",
+        "fields",
+        "page_cap"
+      ],
+      "additionalProperties": false,
+      "description": "A private shelf's declared shape: the same parts a predefined shelf has in shelves/registry.json."
+    },
+    "manifest_shelf": {
+      "type": "object",
+      "properties": {
+        "id": {
+          "$ref": "#/definitions/shelf_id"
+        },
+        "origin": {
+          "type": "string",
+          "enum": [
+            "predefined",
+            "private"
+          ]
+        },
+        "interface_major": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Predefined shelves: the registry major served."
+        },
+        "shape": {
+          "$ref": "#/definitions/private_shape"
+        },
+        "verbs": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": {
+            "$ref": "#/definitions/verb"
+          }
+        },
+        "required_role": {
+          "type": "object",
+          "propertyNames": {
+            "enum": [
+              "read",
+              "list"
+            ]
+          },
+          "additionalProperties": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9_]{0,31}$"
+          },
+          "description": "The provider role required per verb, imported as named; the org maps it to its own roles."
+        },
+        "probe_fixture": {
+          "type": "object",
+          "properties": {
+            "synthetic": {
+              "const": true
+            },
+            "read": {
+              "$ref": "#/definitions/by"
+            },
+            "list": {
+              "$ref": "#/definitions/by"
+            }
+          },
+          "required": [
+            "synthetic"
+          ],
+          "additionalProperties": false,
+          "description": "Synthetic lookups the import probe invokes, marked so no real person's data is ever a fixture."
+        }
+      },
+      "required": [
+        "id",
+        "origin",
+        "verbs",
+        "required_role",
+        "probe_fixture"
+      ],
+      "additionalProperties": false,
+      "allOf": [
+        {
+          "if": {
+            "properties": {
+              "origin": {
+                "const": "predefined"
+              }
+            }
+          },
+          "then": {
+            "required": [
+              "interface_major"
+            ],
+            "not": {
+              "required": [
+                "shape"
+              ]
+            }
+          }
+        },
+        {
+          "if": {
+            "properties": {
+              "origin": {
+                "const": "private"
+              }
+            }
+          },
+          "then": {
+            "required": [
+              "shape"
+            ],
+            "not": {
+              "required": [
+                "interface_major"
+              ]
+            }
+          }
+        }
+      ]
+    },
+    "manifest": {
+      "type": "object",
+      "properties": {
+        "protocol": {
+          "const": 1
+        },
+        "provider_id": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9-]{0,62}$"
+        },
+        "offer_version": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 64
+        },
+        "digest": {
+          "type": "string",
+          "pattern": "^sha256:[a-f0-9]{64}$",
+          "description": "Over the offer: a changed digest under the same version is refused at re-import."
+        },
+        "principal": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128,
+          "description": "The principal the presenting bearer belongs to. PER-PRINCIPAL LISTING: `shelves` names only the shelves this principal serves, never the provider's full list, because the shelf names themselves can be a client list."
+        },
+        "shelves": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 64,
+          "items": {
+            "$ref": "#/definitions/manifest_shelf"
+          }
+        }
+      },
+      "required": [
+        "protocol",
+        "provider_id",
+        "offer_version",
+        "digest",
+        "principal",
+        "shelves"
+      ],
+      "additionalProperties": false,
+      "description": "Answer of `GET /ekka/shelves/v1/manifest`, bearer-authenticated."
+    },
+    "ping": {
+      "type": "object",
+      "properties": {
+        "protocol": {
+          "const": 1
+        }
+      },
+      "required": [
+        "protocol"
+      ],
+      "additionalProperties": false,
+      "description": "Answer of the one public route, `GET /ekka/shelves/v1/ping`: the protocol version and nothing else, no names."
+    }
+  }
+}