Improve policy definition validation and description quality

docs/basic-auth/v0.1/docs/basic-authentication.md

@@ -0,0 +1,81 @@
+---
+title: "Overview"
+---
+# Basic Authentication
+
+## Overview
+
+The Basic Authentication policy protects APIs using HTTP Basic Authentication. It validates the `Authorization` header against configured credentials and either allows the request to continue or returns `401 Unauthorized`.
+
+The policy also writes authentication metadata to the request context for downstream policies:
+- `auth.success`
+- `auth.username` (on success)
+- `auth.method` (`"basic"`)
+
+## Features
+
+- Validates HTTP Basic credentials from `Authorization` header
+- Uses constant-time credential comparison
+- Optional `allowUnauthenticated` mode for soft-auth scenarios
+- Configurable `realm` for `WWW-Authenticate`
+- Request-phase only (no response-phase processing)
+
+## Configuration
+
+### User Parameters (API Definition)
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `username` | string | Yes | - | Expected username in Basic credentials. |
+| `password` | string | Yes | - | Expected password in Basic credentials. |
+| `allowUnauthenticated` | boolean | No | `false` | If `true`, failed authentication is recorded in metadata but request is still forwarded. |
+| `realm` | string | No | `Restricted` | Realm value used in `WWW-Authenticate` challenge. |
+
+### System Parameters
+
+This policy does not require system-level configuration.
+
+## Behavior Notes
+
+- Missing/invalid policy config (`username`/`password`) returns `500` with JSON error.
+- Missing/invalid credentials returns `401` with:
+  - `WWW-Authenticate: Basic realm="..."`
+  - JSON body: `{"error":"Unauthorized","message":"Authentication required"}`
+- If `allowUnauthenticated: true`, auth failures do not block the request.
+
+## API Definition Examples
+
+### Example 1: Enforce Basic Authentication
+
+```yaml
+policies:
+  - name: basic-auth
+    version: v0
+    params:
+      username: admin
+      password: s3cret
+```
+
+### Example 2: Custom Realm
+
+```yaml
+policies:
+  - name: basic-auth
+    version: v0
+    params:
+      username: gateway-user
+      password: strong-password
+      realm: Internal APIs
+```
+
+### Example 3: Soft Authentication (Allow Unauthenticated)
+
+```yaml
+policies:
+  - name: basic-auth
+    version: v0
+    params:
+      username: analytics-user
+      password: analytics-pass
+      allowUnauthenticated: true
+```

docs/modify-headers/v0.1/docs/modify-headers.md

@@ -0,0 +1,101 @@
+---
+title: "Overview"
+---
+# Modify Headers
+
+## Overview
+
+The Modify Headers policy updates request and/or response headers.
+It supports two actions:
+- `SET`: set/replace a header value
+- `DELETE`: remove a header
+
+Modifications can be applied in the request phase, response phase, or both.
+
+## Features
+
+- Modifies request headers before forwarding upstream
+- Modifies response headers before returning to client
+- Supports `SET` and `DELETE` actions
+- Case-insensitive header handling (internally normalized)
+- Independent request/response configuration
+
+## Configuration
+
+At least one of `requestHeaders` or `responseHeaders` should be provided.
+
+### User Parameters (API Definition)
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `requestHeaders` | array | No | Header modifications applied to request headers. |
+| `responseHeaders` | array | No | Header modifications applied to response headers. |
+
+### Header Modification Object
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `action` | string | Yes | `SET` or `DELETE`. |
+| `name` | string | Yes | Header name. |
+| `value` | string | Conditional | Required when `action` is `SET`. Ignored for `DELETE`. |
+
+### System Parameters
+
+This policy does not require system-level configuration.
+
+## Behavior Notes
+
+- Invalid `requestHeaders` configuration returns immediate `500` response.
+- Invalid `responseHeaders` configuration rewrites the upstream response to `500` with JSON error.
+- Unknown actions are ignored at execution time (no set/remove operation produced).
+
+## API Definition Examples
+
+### Example 1: Set Request Headers
+
+```yaml
+policies:
+  - name: modify-headers
+    version: v0
+    params:
+      requestHeaders:
+        - action: SET
+          name: X-Env
+          value: production
+        - action: SET
+          name: X-Gateway
+          value: apiplatform
+```
+
+### Example 2: Delete Response Headers
+
+```yaml
+policies:
+  - name: modify-headers
+    version: v0
+    params:
+      responseHeaders:
+        - action: DELETE
+          name: Server
+        - action: DELETE
+          name: X-Powered-By
+```
+
+### Example 3: Modify Both Request and Response
+
+```yaml
+policies:
+  - name: modify-headers
+    version: v0
+    params:
+      requestHeaders:
+        - action: SET
+          name: X-Trace-Source
+          value: gateway
+      responseHeaders:
+        - action: SET
+          name: Cache-Control
+          value: no-store
+        - action: DELETE
+          name: X-Internal-Debug
+```

docs/respond/v0.1/docs/respond.md

@@ -0,0 +1,89 @@
+---
+title: "Overview"
+---
+# Respond
+
+## Overview
+
+The Respond policy returns an immediate response from the gateway without forwarding the request to upstream.
+It is useful for short-circuiting flows, mocking APIs, and returning fixed responses.
+
+## Features
+
+- Immediate response in request phase
+- Configurable status code, body, and headers
+- No upstream call when policy is executed
+- Useful for mock endpoints and controlled error responses
+
+## Configuration
+
+### User Parameters (API Definition)
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `statusCode` | integer | No | `200` | HTTP status code returned to client. |
+| `body` | string | No | `""` | Response body content. |
+| `headers` | array | No | `[]` | Headers to include in immediate response. |
+
+### Header Object
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `name` | string | Yes | Header name. |
+| `value` | string | Yes | Header value. |
+
+### System Parameters
+
+This policy does not require system-level configuration.
+
+## Behavior Notes
+
+- If `headers` is not an array/object list with valid `name`/`value`, policy returns `500` configuration error.
+- Policy executes only in request flow; `OnResponse` is a no-op.
+- If no `body` is provided, an empty body is returned.
+
+## API Definition Examples
+
+### Example 1: Simple Mock Response
+
+```yaml
+policies:
+  - name: respond
+    version: v0
+    params:
+      statusCode: 200
+      body: '{"status":"ok"}'
+      headers:
+        - name: content-type
+          value: application/json
+```
+
+### Example 2: Controlled Error Response
+
+```yaml
+policies:
+  - name: respond
+    version: v0
+    params:
+      statusCode: 503
+      body: '{"error":"service unavailable"}'
+      headers:
+        - name: content-type
+          value: application/json
+        - name: retry-after
+          value: "30"
+```
+
+### Example 3: Plain Text Short-Circuit
+
+```yaml
+policies:
+  - name: respond
+    version: v0
+    params:
+      statusCode: 200
+      body: "pong"
+      headers:
+        - name: content-type
+          value: text/plain
+```

docs/token-based-ratelimit/v0.1/docs/token-based-ratelimit.md

@@ -0,0 +1,102 @@
+---
+title: "Overview"
+---
+# Token-Based Rate Limiting
+
+## Overview
+
+The Token-Based Rate Limiting policy limits LLM traffic using token usage (prompt, completion, total).
+It resolves token extraction paths from provider templates and delegates enforcement to the advanced rate limiting engine.
+
+## Features
+
+- Limits by `prompt`, `completion`, and/or `total` token buckets
+- Uses provider template token paths dynamically
+- Supports advanced rate limit backends and algorithms through delegation
+- Per-route key extraction (delegated quota key uses route name)
+- Request pre-check + post-response token consumption
+
+## Configuration
+
+At least one of `promptTokenLimits`, `completionTokenLimits`, or `totalTokenLimits` is required.
+
+### User Parameters (API Definition)
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `promptTokenLimits` | array | No | Limits for prompt/input tokens. |
+| `completionTokenLimits` | array | No | Limits for completion/output tokens. |
+| `totalTokenLimits` | array | No | Limits for total tokens. |
+
+Each limit item:
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `count` | integer | Yes | Max tokens allowed in the duration. |
+| `duration` | string | Yes | Time window (`1m`, `1h`, `24h`, etc.). |
+
+### System Parameters (Optional Override)
+
+These map to advanced rate-limit engine settings:
+- `algorithm` (`gcra` or `fixed-window`)
+- `backend` (`memory` or `redis`)
+- `redis` object
+- `memory` object
+
+If omitted, defaults are read from configured system defaults.
+
+## Behavior Notes
+
+- Policy depends on `provider_name` in shared metadata.
+- If provider metadata/mapping/template is missing, policy skips enforcement (no immediate failure).
+- Request phase performs quota pre-check.
+- Response phase extracts token usage and consumes quota.
+- Enforcement uses provider-specific delegated policy instances with template-change-aware caching.
+
+## API Definition Examples
+
+### Example 1: Limit Total Tokens
+
+```yaml
+policies:
+  - name: token-based-ratelimit
+    version: v0
+    params:
+      totalTokenLimits:
+        - count: 100000
+          duration: "1h"
+```
+
+### Example 2: Separate Prompt and Completion Limits
+
+```yaml
+policies:
+  - name: token-based-ratelimit
+    version: v0
+    params:
+      promptTokenLimits:
+        - count: 50000
+          duration: "1h"
+      completionTokenLimits:
+        - count: 20000
+          duration: "1h"
+      algorithm: gcra
+      backend: memory
+```
+
+### Example 3: Redis-Backed Token Rate Limiting
+
+```yaml
+policies:
+  - name: token-based-ratelimit
+    version: v0
+    params:
+      totalTokenLimits:
+        - count: 1000000
+          duration: "24h"
+      backend: redis
+      redis:
+        host: redis.example.com
+        port: 6379
+        keyPrefix: ratelimit:v1:
+```

docs/token-based-ratelimit/v0.1/metadata.json

@@ -0,0 +1,11 @@
+{
+  "name": "token-based-ratelimit",
+  "displayName": "Token Based Ratelimit",
+  "version": "0.1",
+  "provider": "WSO2",
+  "categories": [
+    "Security",
+    "AI"
+  ],
+  "description": "Rate-limits LLM traffic by token usage (prompt, completion, and total tokens).\nResolves token extraction paths from provider templates and delegates enforcement\nto the advanced rate-limit engine."
+}