@crvouga/mockingbird-service-workos 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog — @crvouga/mockingbird-service-workos
+
+## 0.1.0 (2026-10-05)
+
+Initial release.

package/DISCOVERY.md

@@ -0,0 +1,55 @@
+# @crvouga/mockingbird-service-workos discovery
+
+This is the installed-package index for coding agents and tooling. All relative links resolve
+inside `node_modules/@crvouga/mockingbird-service-workos/`; no repository checkout is needed to discover the mock's
+supported surface or documented behavior.
+
+## Capability and behavior sources
+
+| Question | Authoritative file | What it contains |
+| --- | --- | --- |
+| Behaviour and integration | [`README.md`](README.md) | Routes, state transitions, auth, webhooks, controls, presets and deliberate omissions. |
+| Exact capabilities | [`SUPPORT.md`](SUPPORT.md) | Supported, unsupported and parity-covered operations or commands, including reasons for gaps. |
+| Wire contract | [`openapi.yaml`](openapi.yaml) | Machine-readable paths, methods, schemas, responses and parity annotations. |
+| Public API | [`dist/index.d.ts`](dist/index.d.ts) | The installed package's exact TypeScript exports and signatures. |
+| Package metadata | [`package.json`](package.json) | Runtime/entry-point claims, vendor links, parity scope/tier and `mockingbird.discovery`. |
+
+Read these together: the contract/capability matrix says *what* is available, while the README
+defines stateful behavior, lifecycle rules, test controls, and intentional oracle differences.
+If prose and an executable surface disagree, report a parity mismatch instead of adding a
+consumer-side workaround.
+
+## Parity and oracle
+
+- Declared parity surface: **AuthKit codes, signed sessions, refresh and user pagination**.
+- Parity tier: **cold** (the repository controls when live checks run).
+- Oracle: **Live vendor API or sandbox**.
+- Repository command: `bun run parity:service -- workos`.
+- Evidence model: Run from a Mockingbird checkout; credentials come only from .env.local or GitHub Actions secrets. Missing credentials exit 2.
+
+The npm package contains evidence summaries and the exact contract, not credentials or the
+repository-only parity harness. Self-parity/property and acceptance tests run in the Mockingbird
+repository; live parity is an additional oracle check, not a substitute for the packaged matrix.
+
+## Runtime introspection
+
+- `GET /__admin/health`
+- `GET /__admin`
+- `GET /__admin/state`
+- `GET /__admin/requests`
+- `GET /__admin/metrics`
+- `GET /__admin/faults/presets`
+- `GET /__admin/ui`
+
+For HTTP services, use `x-mockingbird-namespace` (or the documented credential/path carrier) so
+parallel tests do not share state. Admin state, journal, metrics and fault-preset endpoints are
+designed for assertions and diagnosis by consuming test suites.
+
+## Report a mismatch or missing capability
+
+Follow the [agent reporting contract](https://github.com/crvouga/mockingbird/blob/main/docs/REPORTING_ISSUES.md). Include package version,
+operation/command, a minimal redacted request, actual mock result, expected oracle result or vendor
+documentation, and whether the mismatch appears in the matrix. Never include keys, tokens,
+customer data, prompts, PHI, card data, or unredacted recordings.
+
+Service key: `workos`.

package/README.md

@@ -0,0 +1,77 @@
+# @crvouga/mockingbird-service-workos
+
+> Familiar calls. Faithful echoes. Part of [Mockingbird](https://github.com/crvouga/mockingbird).
+
+WIP WorkOS AuthKit mock: authorization redirects, single-use codes, signed JWT sessions,
+rotating refresh tokens, user metadata and pagination. Synthetic fixtures only.
+
+## Install
+
+```sh
+bun add -d @crvouga/mockingbird-service-workos
+```
+
+## Usage
+
+```ts
+import { createServer } from "@crvouga/mockingbird-service-workos/server"
+const server = await createServer()
+// Set AuthKit WORKOS_API_HOSTNAME/WORKOS_API_PORT from server.url and WORKOS_API_HTTPS=false.
+// WORKOS_API_KEY=mock_workos_key, WORKOS_CLIENT_ID=client_mock.
+// Register your callback in the clients seed and use a local WORKOS_COOKIE_PASSWORD.
+await server.close()
+```
+
+`createRuntime().fetch(Request)` supports in-process adapters. Raw user mirrors should use
+the server URL in place of `https://api.workos.com`. The default registered callback is
+`http://localhost:3000/callback`; authorization immediately chooses the client's seeded user.
+The exact `@workos-inc/node@9.3.1` and `@workos-inc/authkit-nextjs@4.1.0` SDKs are tested
+over HTTP, including PKCE, JWT signature validation and expired-session refresh.
+
+### Routes
+
+- `GET /user_management/authorize`: registered callback, code, state, optional organization/PKCE.
+- `POST /user_management/authenticate`: client secret with authorization_code or refresh_token.
+- `GET /user_management/users`: bearer API key, limit/after and email filtering.
+- `GET /sso/jwks/{clientId}`: public ephemeral RS256 verification key used by AuthKit.
+
+### State and controls
+
+Seed `users`, `clients` and `memberships` with runtime options. Options `accessTtlMs`,
+`refreshTtlMs` and `codeTtlMs` control expiry. The mock clock controls issued timestamps.
+The standard `/__admin/state` collections expose users, clients, memberships, codes, sessions
+and refreshTokens. Edit `sessions.revoked`, expiry fields or used flags for failure scenarios.
+Private signing keys are ephemeral and never journaled; resetting state invalidates refresh
+tokens, but offline JWT verification has no revocation lookup, just like the SDK.
+
+Standard `/__admin` reset, Timeline snapshots/branches, clock, faults and request journal
+are available. Journals store metadata, not client secrets or token request bodies.
+Header (`x-mockingbird-namespace`), path (`/__admin/ns/<name>/…`) and bearer credential
+namespaces isolate durable state. AuthKit applications should use one dedicated server per
+test namespace so the SDK's JWKS URL and issuer remain consistent. Configure `adminPrefix`
+to relocate the reserved tree. Presets: `auth_failure`, `rate_limited`, `server_error`,
+`connection_drop`; generic faults also support deterministic latency.
+
+### Verification
+
+`bun test` covers acceptance, independent OpenAPI walks, deliberate divergence and both
+pinned SDKs. `WORKOS_API_KEY=… bun run parity` runs a safe list-users shape probe; it performs
+no account mutations and prints no user data. Missing credentials exit 2.
+Oracle references: [authentication](https://workos.com/docs/reference/authkit/authentication),
+[users](https://workos.com/docs/reference/authkit/user), and the pinned official SDK sources.
+
+## Deliberately not modelled
+
+Enterprise SAML, directory synchronization, passwords, MFA, hosted AuthKit pages, logout,
+user mutations and webhooks. Authorization is a synthetic auto-login rather than a hosted UI.
+No third-party identities, network federation, exact production refresh-grace policies or
+distributed signing-key persistence. Error envelopes model common documented failures;
+vendor-specific diagnostic strings and undocumented claims are not guaranteed.
+
+## API
+
+Root runtime exports: `WorkOSAPI`, `WORKOS_NAMESPACE`, `DEFAULT_USERS`, `DEFAULT_CLIENTS`,
+`createRuntime`, `WORKOS_PRESETS`, `document`, `operationIds`, `supportedOperationIds`.
+Types include `WorkOSUser`, `WorkOSClient`, `Membership`, `WorkOSAPIOptions`,
+`WorkOSRuntimeOptions`, `WorkOSRuntime`, `OperationId`, `SupportedOperationId`.
+The `/server` entry exports `createServer`, `serveTarget`, `DEFAULT_PORT`.

package/SUPPORT.md

@@ -0,0 +1,14 @@
+# WorkOS AuthKit mock — operation support
+
+Generated from `openapi.yaml`; do not edit by hand.
+
+- operations in spec: **4**
+- supported by the mock: **4**
+- parity enabled: **3**
+
+| operationId | route | mock | parity | notes |
+| --- | --- | --- | --- | --- |
+| `Authorize` | `GET /user_management/authorize` | ✅ supported | ❌ disabled | Browser redirect requires registered client and callback |
+| `Authenticate` | `POST /user_management/authenticate` | ✅ supported | ⚠️ unsafe (opt-in) |  |
+| `ListUsers` | `GET /user_management/users` | ✅ supported | ✅ |  |
+| `GetJwks` | `GET /sso/jwks/{clientId}` | ✅ supported | ✅ |  |