@deque/axe-auth 1.1.0-next.97bcb8e6 → 1.1.0-next.9bc60204

package/docs/callback-page.md

@@ -0,0 +1,24 @@
+# Callback response page
+
+The HTML the browser renders after Keycloak redirects to the loopback URL, produced by `src/oauth/renderHtml.ts`.
+
+## Approach
+
+Visually match Deque's billing-service frontend (palette, typography, centered layout) so developers recognise the page as Deque-owned, but ship no external assets — everything is inline. The logo lives at `assets/logo.png` and is embedded as a base64 data URI via the generated `src/oauth/logo.generated.ts`; regenerate with `node scripts/encode-logo.js` after replacing the PNG.
+
+## Security considerations
+
+**No external stylesheets or images.** billing-service pulls Roboto from Google Fonts. The callback page deliberately does not. Loading any external resource from `http://127.0.0.1:<port>/callback?code=...&state=...` causes the browser to send a `Referer` header containing the full callback URL — leaking the auth code to the third-party origin. A `<meta name="referrer" content="no-referrer">` would suppress the header, but relying on it is brittle; avoiding external references entirely is defense in depth. The `Roboto → Helvetica → Arial` fallback renders indistinguishably on developer machines.
+
+**Content Security Policy.** Every response sets:
+
+```
+Content-Security-Policy: default-src 'none'; img-src data:; style-src 'sha256-<digest>'
+X-Content-Type-Options: nosniff
+```
+
+`default-src 'none'` blocks everything by default. `img-src data:` allows only the inlined logo. `style-src 'sha256-...'` allows only a `<style>` block whose contents match a digest computed at module load — stricter than `'unsafe-inline'`, and any drift between the rendered CSS and the committed hash causes the browser to refuse the stylesheet. Inline `style=""` attributes are avoided entirely (they require separate `style-src-attr` / `'unsafe-hashes'` machinery). The `renderHtml` test suite asserts the hash matches the rendered `<style>` contents to prevent silent drift.
+
+**Auth code not echoed.** The success page deliberately does not render the received `code` in the HTML (RFC 8252 §8.1 interception mitigation).
+
+**XSS escape.** The only untrusted input rendered into the page is `error_description` from the IdP. It is HTML-escaped before interpolation; a regression test feeds `<script>alert(1)</script>` and asserts the escaped form.

package/docs/callback-server.md

@@ -0,0 +1,21 @@
+# Callback server
+
+The loopback HTTP listener that receives the OAuth authorization code redirect, per [RFC 8252 §7.3](https://datatracker.ietf.org/doc/html/rfc8252#section-7.3). Lives in `src/oauth/callbackServer.ts`; the public surface is defined by the module's exported types.
+
+## Loopback bind
+
+RFC 8252 §7.3 says clients SHOULD NOT assume a particular IP version is available and RECOMMENDS trying both. Implementation: bind `127.0.0.1` on an ephemeral port; on `EAFNOSUPPORT` / `EADDRNOTAVAIL` (no IPv4 loopback configured on this host) fall back to `[::1]` on a fresh ephemeral port. The returned `redirectUri` uses whichever literal actually got bound, so the browser connects to exactly what the authorization server redirects it to — no reliance on `localhost` DNS resolution.
+
+Request handling additionally rejects non-loopback `remoteAddress` values with `403` as defense in depth against DNS-rebinding-style pivots — the listener only binds to a loopback interface, but enforcing it at the handler costs nothing.
+
+## RFC 8252 conformance
+
+| Clause | Requirement                                | Handled by                                                                                                 |
+| ------ | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------- |
+| §7.3   | IP literal, not `localhost`                | Binds `127.0.0.1` or `[::1]`; redirect URI uses the literal.                                               |
+| §7.3   | Ephemeral OS-assigned port                 | `listen(0, ...)`; port read from `listening` event.                                                        |
+| §7.3   | Attempt both IPv4 and IPv6                 | IPv4-first, IPv6 fallback when the IPv4 family is unavailable.                                             |
+| §8.3   | Open the port only during the auth request | One-shot: closed on first consuming request, timeout, or abort.                                            |
+| §8.3   | Listen on loopback only                    | IP literal only; `remoteAddress` check as defense in depth.                                                |
+| §8.1   | PKCE                                       | Out of scope — owned by the auth-URL + token-exchange layer.                                               |
+| §8.1   | Auth code interception mitigation          | Success HTML does not echo `code`; CSP locks the page down (see [`callback-page.md`](./callback-page.md)). |

package/docs/oauth-flow.md

@@ -0,0 +1,15 @@
+# OAuth flow — context
+
+`@deque/axe-auth` is the native half of a browser-based OAuth 2.0 Authorization Code + PKCE flow for enterprise customers whose security policies prohibit static API keys. The MCP server itself runs in Docker with no display or interactive terminal, so per [RFC 8252 §7.3](https://datatracker.ietf.org/doc/html/rfc8252#section-7.3) authentication is delegated to this CLI on the developer's host — it opens a browser, receives the redirect on a loopback port, exchanges the code for tokens, and stores a refresh token in the system keychain. The container reads access tokens from the CLI via an environment variable.
+
+## Scope of this module
+
+This package currently implements only the loopback listener and its response page (internal issue #418). PKCE, auth URL construction, browser launch, token exchange, and keychain storage are owned by sibling issues under internal epic #410.
+
+See [`callback-server.md`](./callback-server.md) for the listener API and [`callback-page.md`](./callback-page.md) for the HTML response.
+
+## References
+
+- [RFC 8252 — OAuth 2.0 for Native Apps](https://datatracker.ietf.org/doc/html/rfc8252)
+- [RFC 7636 — PKCE](https://datatracker.ietf.org/doc/html/rfc7636)
+- Internal epic #410

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deque/axe-auth",
-  "version": "1.1.0-next.97bcb8e6",
+  "version": "1.1.0-next.9bc60204",
   "description": "CLI authentication utility for Deque services",
   "license": "SEE LICENSE IN LICENSE",
   "type": "commonjs",
@@ -11,7 +11,9 @@
   },
   "files": [
     "dist",
-    "!dist/**/*.test.*"
+    "!dist/**/*.test.*",
+    "docs",
+    "credits.json"
   ],
   "publishConfig": {
     "access": "public",
@@ -20,13 +22,24 @@
   "engines": {
     "node": ">=22.13.0"
   },
+  "dependencies": {
+    "@napi-rs/keyring": "^1.2.0",
+    "remove-trailing-slash": "^0.1.1",
+    "ts-dedent": "^2.2.0"
+  },
   "devDependencies": {
     "@types/node": "^22.13.10",
+    "c8": "^10.1.3",
     "tsx": "^4.20.6",
     "typescript": "^5.9.3"
   },
   "scripts": {
     "build": "tsc",
-    "test": "tsx --test 'src/**/*.test.ts'"
+    "test": "tsx --test 'src/**/*.test.ts'",
+    "coverage": "c8 pnpm test",
+    "register-dev-client": "tsx scripts/registerDevClient.ts",
+    "smoke-authorize": "tsx scripts/smokeAuthorize.ts",
+    "smoke-cli": "tsx scripts/smokeCLI.ts",
+    "manual-authorize": "tsx scripts/manualAuthorize.ts"
   }
 }