[Spec Kit] Implementation progress

specs/001-oidc-proxy-script/contracts/proxy-http.md

@@ -0,0 +1,113 @@
+# Contract: Proxy HTTP Responses
+
+**Feature**: 001-oidc-proxy-script  
+**File**: `src/proxyScripts/proxy.js`  
+**Endpoint**: Any path handled by the adapter (all requests delegated to proxy.js by server.js)  
+**Date**: 2025-07-17
+
+---
+
+## Overview
+
+`proxy.js` responds to every inbound HTTP request with exactly one of two outcomes:
+a success response (authentication succeeded) or an error response (authentication failed for
+any reason). The contract defines the exact shape of both outcomes.
+
+---
+
+## Success Response
+
+**Trigger**: OIDC token successfully obtained (fresh fetch or valid cached token).
+
+```
+HTTP/1.1 200 OK
+Content-Type: text/plain
+
+Authorized
+```
+
+| Property | Value |
+|----------|-------|
+| Status code | `200` |
+| Status text | `OK` |
+| `Content-Type` header | `text/plain` |
+| Body | Literal string `Authorized` (no trailing newline) |
+
+**Acceptance test** (FR-007, SC-001, SC-002):
+
+```javascript
+assert.strictEqual(res.statusCode, 200);
+assert.strictEqual(res.body, 'Authorized');
+```
+
+---
+
+## Error Response
+
+**Trigger**: Any of the following (FR-008, SC-004):
+- Token service returns HTTP 4xx or 5xx
+- Token service is unreachable (network error)
+- Token request times out after 5 seconds (FR-014)
+- Token service response is missing `id_token` or `expires_in`
+- `adapter_settings` is missing a required field
+
+```
+HTTP/1.1 401 Unauthorized
+Content-Type: text/plain
+
+Unauthorized: <descriptive message>
+```
+
+| Property | Value |
+|----------|-------|
+| Status code | `401` |
+| Status text | `Unauthorized` |
+| `Content-Type` header | `text/plain` |
+| Body prefix | `Unauthorized: ` (literal, followed by the error message) |
+| Body | Never empty; always includes a human-readable description |
+
+**Example bodies by error cause**:
+
+| Cause | Example body |
+|-------|-------------|
+| Invalid credentials (401 from token service) | `Unauthorized: HTTP 401` |
+| Token service unavailable | `Unauthorized: connect ECONNREFUSED 127.0.0.1:443` |
+| 5-second timeout | `Unauthorized: token service timeout` |
+| Response missing `id_token` | `Unauthorized: id_token missing from response` |
+| Response missing `expires_in` | `Unauthorized: expires_in missing from response` |
+| Missing `tokenUrl` in settings | `Unauthorized: missing required field: tokenUrl` |
+
+**Acceptance test** (FR-008):
+
+```javascript
+assert.strictEqual(res.statusCode, 401);
+assert.match(res.body, /^Unauthorized: .+/);
+```
+
+---
+
+## Invariants
+
+These MUST hold for every request, regardless of outcome:
+
+1. **One response per request**: `res.writeHead()` MUST be called exactly once;
+   `res.end()` MUST be called exactly once.
+2. **Never 500**: `proxy.js` MUST NOT emit a 500 or leave the connection open. All
+   errors, including unexpected runtime errors, MUST result in a `401` (not a crash or hang).
+3. **No imports/exports** (FR-009): The script MUST contain zero `import` or `export`
+   statements — verified by static analysis.
+4. **No forbidden globals** (FR-010): No `config`, `global.config`, or `process.env`
+   references — verified by static analysis.
+5. **Response within 5 seconds** (SC-001, FR-014): The HTTP timeout on the token POST
+   is 5 000 ms. Combined with synchronous error handling, every request resolves within
+   5 seconds under normal network conditions.
+
+---
+
+## Out of Scope
+
+- The proxy script does NOT validate the inbound request (method, path, headers, body).
+  Its sole responsibility is OIDC authentication.
+- The response does NOT include the OIDC token in the body. The `200 OK / Authorized`
+  body is sufficient to confirm authentication succeeded (spec assumption, line 106).
+- No `Authorization` response header is set. The adapter's caller does not require it.