docs(e2ee): add sequence diagrams, JSON schemas (manifest, capability), and PASETO payload example

Author: OneFineStarstuff

docs/examples/paseto-v4-public.json

@@ -0,0 +1,14 @@
+{
+  "v": 4,
+  "purpose": "public",
+  "claims": {
+    "sub": "device:9b1d2...",
+    "scope": "object:get",
+    "resource": "s3://brand-intel-eu/tenant123/objects/abc123",
+    "exp": 1723939200,
+    "iat": 1723935600,
+    "nbf": 1723935600,
+    "region": "eu",
+    "tid": "d7b2f0f8-7e2a-4d31-8b4e-7e7c2f0b9d51"
+  }
+}

docs/schemas/capability.schema.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://example.com/schemas/capability.schema.json",
+  "title": "Capability Claims (PASETO v4.public payload)",
+  "type": "object",
+  "required": ["sub", "scope", "resource", "exp", "region", "tid"],
+  "properties": {
+    "sub": {"type": "string"},
+    "scope": {"type": "string", "enum": ["object:get", "object:put", "room:read", "room:write", "membership:manage"]},
+    "resource": {"type": "string"},
+    "exp": {"type": "integer"},
+    "iat": {"type": "integer"},
+    "nbf": {"type": "integer"},
+    "region": {"type": "string", "description": "enforced data residency region (controls bucket/prefix routing)"},
+    "tid": {"type": "string"}
+  }
+}

docs/schemas/manifest.schema.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://example.com/schemas/manifest.schema.json",
+  "title": "E2EE File Manifest",
+  "type": "object",
+  "required": ["version", "algo", "chunk_size", "length", "blake3_file", "chunks", "sig"],
+  "properties": {
+    "version": {"type": "integer", "enum": [1]},
+    "algo": {"type": "string", "const": "aes-256-gcm"},
+    "chunk_size": {"type": "integer", "minimum": 262144, "maximum": 4194304},
+    "length": {"type": "integer", "minimum": 0},
+    "blake3_file": {"type": "string", "pattern": "^[0-9a-f]{64}$"},
+    "chunks": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["index", "offset", "size", "blake3"],
+        "properties": {
+          "index": {"type": "integer", "minimum": 0},
+          "offset": {"type": "integer", "minimum": 0},
+          "size": {"type": "integer", "minimum": 1},
+          "blake3": {"type": "string", "pattern": "^[0-9a-f]{64}$"}
+        }
+      }
+    },
+    "sig": {"type": "string", "description": "Ed25519 signature over canonicalized manifest without sig"}
+  }
+}