[Spec Kit] Implementation progress

2026-04-22 19:57:03 -05:00
parent a763582bc4
commit 49a6b2e4e7
3 changed files with 146 additions and 1 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,112 @@
+# kme-content-adapter
+
+An HTTP proxy adapter that authenticates against KME and proxies content requests through an isolated VM sandbox, mirroring the IVA Studio proxy script execution environment.
+
+## Requirements
+
+- Node.js ≥ 18
+- Redis (used for token caching)
+- `jq` (optional — used by `npm start` for log pretty-printing)
+
+## Setup
+
+```bash
+npm install
+cp src/globalVariables/kme_CSA_settings.json.example src/globalVariables/kme_CSA_settings.json
+# Edit kme_CSA_settings.json with real credentials
+```
+
+## Configuration
+
+### `src/globalVariables/kme_CSA_settings.json`
+
+Credentials and OIDC settings — **never commit this file**.
+
+```json
+{
+  "tokenUrl": "https://<host>/oidc-token-service/<env>/token",
+  "username": "<username>",
+  "password": "<password>",
+  "clientId": "default",
+  "scope": "openid tags content_entitlements"
+}
+```
+
+### `config/default.json`
+
+Infrastructure settings (port, host, log level). Override with environment variables:
+
+| Variable | Default | Description |
+|---|---|---|
+| `PORT` | `3000` | HTTP server port |
+| `HOST` | `0.0.0.0` | Bind address |
+| `LOG_LEVEL` | `debug` | Log level: `DEBUG`, `INFO`, `WARN`, `ERROR` |
+
+## Running
+
+```bash
+npm run dev      # Development — auto-restart on file changes
+npm start        # Production — logs piped through jq
+```
+
+## Testing
+
+```bash
+npm test                    # All tests
+npm run test:unit           # Unit tests only
+npm run test:integration    # Integration tests only
+npm run test:contract       # Contract tests only
+
+# Single test file
+node --test tests/unit/proxy.test.js
+```
+
+Tests use the Node.js built-in `node:test` runner. No external test framework.
+
+## Architecture
+
+The server loads `src/proxyScripts/kmeContentSourceAdapter.js` once at startup via `vm.Script`, then executes it in a **fresh isolated VM context per request** via `vm.createContext`.
+
+```
+src/
+├── proxyScripts/
+│   └── kmeContentSourceAdapter.js   # All business logic (zero imports/exports)
+├── globalVariables/
+│   ├── kme_CSA_settings.json        # OIDC credentials (gitignored)
+│   └── adapterHelper.js             # Pure utilities (optional)
+├── logger.js                        # Structured JSON logger
+└── server.js                        # HTTP server bootstrap only
+config/
+└── default.json                     # Infrastructure settings
+```
+
+### VM Context Globals
+
+All dependencies are injected into each request's sandbox:
+
+| Variable | Source |
+|---|---|
+| `console` | Structured logger |
+| `crypto` | Node.js Web Crypto API |
+| `axios` | HTTP client |
+| `jwt` | `jsonwebtoken` |
+| `uuidv4` | UUID v4 generator |
+| `xmlBuilder` | `xmlbuilder2` `create` |
+| `redis` | Connected Redis client |
+| `URLSearchParams`, `URL` | Node.js globals |
+| `kme_CSA_settings` | Loaded from `src/globalVariables/kme_CSA_settings.json` |
+| `req`, `res` | Node.js HTTP request/response |
+
+### Key Constraints for `kmeContentSourceAdapter.js`
+
+- **Zero `import`/`export`** — runs in a VM with no module system
+- **No `config`, `global.config`, or `process.env`** — use injected globals only
+- Routing metadata is available via `req.params` (set by `server.js`)
+
+## Token Caching
+
+OIDC tokens are cached in Redis under the hash key `authorization` (fields `token` and `expiry`). The cache survives adapter restarts. Token expiry is stored as an absolute Unix epoch timestamp.
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md).