Changeset 0.29.1 (#196)

docs/ICD/extensions.md

@@ -2,7 +2,6 @@
 
 Plugin system with three tiers: Browser JS (client-side), Starlark
 sandbox (server-side, v0.29.0), Sidecar containers (server-side, future).
-Currently only Browser tier is implemented.
 
 ### User Extensions
 
@@ -26,6 +25,74 @@ GET  /extensions/tools              → {"data": [...tool schema objects]}
 - `GET /extensions/tools` returns raw tool schema JSON from all enabled
   browser extensions' `manifest.tools[]` arrays.
 
+### Extension API Routes (v0.29.1)
+
+Starlark packages serve custom JSON endpoints. Mounted at
+`/s/:slug/api/*path` with JWT authentication.
+
+**Auth:** Authenticated user (JWT — returns 401, not redirect)
+
+```
+ANY  /s/:slug/api/*path             → Starlark on_request(req) response
+```
+
+**Route:** `slug` is the package ID. `path` is matched against the
+manifest's `api_routes` declaration.
+
+**Manifest `api_routes` field:**
+
+```json
+{
+  "api_routes": [
+    {"method": "GET",  "path": "/status"},
+    {"method": "POST", "path": "/webhook"},
+    {"method": "*",    "path": "/proxy/*"}
+  ]
+}
+```
+
+- `method`: exact match (case-insensitive), or `"*"` for any method
+- `path`: exact match, or trailing `"*"` for prefix match
+- Boolean `true` shorthand: all routes forwarded
+- Missing or `false`: no routes served
+
+**Request dict passed to `on_request(req)`:**
+
+```python
+{
+    "method":   "POST",
+    "path":     "/webhook",
+    "headers":  {"content-type": "application/json", ...},
+    "query":    {"page": "1", ...},
+    "body":     "{...}",
+    "user_id":  "uuid"
+}
+```
+
+**Expected return dict:**
+
+```python
+{"status": 200, "headers": {"X-Custom": "val"}, "body": "{...}"}
+```
+
+- `status`: int (default 200). Return `None` for 204 No Content.
+- `headers`: dict (optional). Content-Type auto-detected if not set.
+- `body`: string (default "").
+
+**Validation pipeline:**
+1. Package exists and is enabled
+2. Status is `active` (not `pending_review` or `suspended`)
+3. Tier is `starlark`
+4. `api.http` permission is granted
+5. Method+path matches `api_routes` in manifest
+
+**Errors:**
+- `401` — no/invalid JWT
+- `403` — package suspended or missing `api.http` permission
+- `404` — package not found, disabled, or route not declared
+- `400` — package is not starlark tier
+- `500` — Starlark execution error
+
 ### Admin Extension Management
 
 **Auth:** Admin role
@@ -64,6 +131,46 @@ Returns the inline `_script` field from the extension's manifest.
 The `*path` segment is accepted but currently ignored (all requests
 return the same script). Disabled extensions return 404.
 
+### Extension Permissions (v0.29.0+)
+
+Starlark packages declare capabilities in `manifest.permissions`.
+Admin must grant each before the package activates.
+
+| Permission | Module | Description |
+|-----------|--------|-------------|
+| `secrets.read` | `secrets` | Read extension secrets via GlobalConfig |
+| `notifications.send` | `notifications` | Send in-app notifications |
+| `filters.pre_completion` | — | Register pre-completion filter |
+| `api.http` | `http` | Outbound HTTP requests (v0.29.0: module, v0.29.1: also required for API routes) |
+| `provider.complete` | `provider` | LLM completion calls via BYOK chain (v0.29.1) |
+| `db.read` | `db` | Read extension tables (future) |
+| `db.write` | `db` | Write extension tables (future) |
+
+### Starlark Modules (v0.29.0+)
+
+Modules injected into the script namespace based on granted permissions:
+
+**`secrets`** (requires `secrets.read`):
+- `secrets.get(key)` → string or None
+- `secrets.list()` → list of key names
+
+**`notifications`** (requires `notifications.send`):
+- `notifications.send(user_id, title, body?, type?)` → True
+
+**`http`** (requires `api.http`, v0.29.1):
+- `http.get(url, headers?)` → `{"status": int, "headers": dict, "body": string}`
+- `http.post(url, body?, headers?)` → response dict
+- `http.put(url, body?, headers?)` → response dict
+- `http.delete(url, headers?)` → response dict
+- `http.request(method, url, body?, headers?)` → response dict
+- SSRF protection: private/loopback/link-local IPs blocked after DNS
+- Manifest `network_access`: `{"allow": [...]}` or `{"block": [...]}`
+
+**`provider`** (requires `provider.complete`, v0.29.1):
+- `provider.complete(messages, model?, max_tokens?, temperature?)` → response dict
+- Response: `{"content", "model", "finish_reason", "input_tokens", "output_tokens"}`
+- Provider resolved via BYOK chain; pinnable via `requires_provider.provider_config_id`
+
 ### Builtin Seeding
 
 On startup, `SeedBuiltinExtensions()` scans `extensions/builtin/`