@crvouga/mockingbird-service-vanta 0.1.0

package/CHANGELOG.md

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

package/DISCOVERY.md

@@ -0,0 +1,55 @@
+# @crvouga/mockingbird-service-vanta discovery
+
+This is the installed-package index for coding agents and tooling. All relative links resolve
+inside `node_modules/@crvouga/mockingbird-service-vanta/`; 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: **OAuth, people, evidence uploads and offboarding**.
+- Parity tier: **cold** (the repository controls when live checks run).
+- Oracle: **Live vendor API or sandbox**.
+- Repository command: `bun run parity:service -- vanta`.
+- 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: `vanta`.

package/README.md

@@ -0,0 +1,93 @@
+# @crvouga/mockingbird-service-vanta
+
+> Familiar calls. Faithful echoes. Part of [Mockingbird](https://github.com/crvouga/mockingbird).
+
+WIP Manage Vanta OAuth, paginated compliance records, evidence metadata and offboarding.
+
+## Install
+
+```sh
+bun add @crvouga/mockingbird-service-vanta
+```
+
+## Usage
+
+```ts
+import { createRuntime } from "@crvouga/mockingbird-service-vanta"
+const vanta = createRuntime()
+const response = await vanta.fetch(new Request("http://vanta.test/v1/people?pageSize=10", {
+  headers: { authorization: "Bearer mock_vanta_token" },
+}))
+const { results } = await response.json()
+console.log(results.pageInfo)
+```
+
+Run `mockingbird-vanta serve --port 12129` and inject `http://localhost:12129` as the
+consumer's API origin. There is no universal Vanta SDK environment variable for this override;
+the requested consumer uses raw fetch. Credentials and records are synthetic only.
+
+### Contract
+
+- `POST /oauth/token`: JSON client_credentials with client_id, client_secret and scope.
+  Default clients: mock_read / mock_read_secret (read scope), mock_write / mock_write_secret
+  (read, write and documents:upload). Tokens last one hour; minting another token for a client
+  revokes its preceding token. mock_vanta_token is a seeded write-client bearer token.
+- `GET /v1/people`, `/v1/tests`, `/v1/controls`, `/v1/documents`: results.data and results.pageInfo,
+  pageSize (1–100, default 10), pageCursor. Follow endCursor while hasNextPage is true.
+  Fixture insertion order is stable; resource ids serve as opaque cursors.
+- `GET /v1/people/{personId}`, `/v1/documents/{documentId}`: seeded resource fields by id.
+- `POST /v1/documents/{documentId}/uploads`: multipart file plus optional description and
+  effectiveAtDate. Returns 201 uploaded-file metadata. Only metadata/byte length is retained,
+  never the evidence bytes. Requires documents:upload scope.
+- `POST /v1/documents/{documentId}/submit`: requires a pending upload and write scope;
+  returns **204**, marks pending uploads submitted and document uploadStatus OK. The formal
+  Manage Vanta OpenAPI specifies 204; a guide's 200 example is not followed.
+- `POST /v1/people/offboard`: updates[] containing id and acknowledgerId. Returns 200 with
+  ordered per-person SUCCESS/ERROR results. Only FORMER personnel with seeded eligibility
+  flags (monitoredAccountsInactive, customTasksComplete) and a known acknowledger succeed.
+  Failed items are unchanged. Successful items expose OFFBOARDING_COMPLETE in tasksSummary;
+  a separate admin offboardings collection records acknowledger and completion time.
+
+Read calls require all:read scope, submission/offboarding all:write, and upload documents:upload
+(each prefixed vanta-api.). Missing/invalid/expired resource bearer tokens return literal
+`Unauthorized` with application/json content type, matching an unauthenticated live probe.
+Consumers must not assume every error body is parseable JSON. Other documented failure classes
+use status plus message, with deterministic mock messages rather than exact vendor wording.
+
+### Controls and proof
+
+Seed clients, people, documents, tests and controls through constructor options. Shared
+`/__admin/state/{collection}` also exposes tokens, uploads, eligibility and offboardings.
+Token expiresAt, document metadata, eligibility and upload submitted flags are configurable.
+Shared clock, Timeline/snapshot, reset, faults and metadata-only journals apply. Reset restores
+constructor fixtures. Namespace carriers: header, mapped bearer token, `/__admin/ns/{name}`.
+Set adminPrefix to relocate all controls.
+
+Presets: unauthorized_once, rate_limited, server_error, upload_failed, submit_failed and
+connection_drop. Shared fault rules support latency. No webhook is required by this subset.
+
+Tests cover all issue #270 behaviors through raw fetch, per-person eligibility, scope and token
+revocation, metadata-only multipart handling, namespace/reset, failures and served HTTP.
+Self-parity covers every generated JSON operation; multipart uploads have explicit acceptance
+tests. `bun scripts/parity.ts --unauthenticated` verifies the observed non-JSON 401; it passed
+with no real credentials. The optional read-only pagination-envelope probe needs VANTA_ACCESS_TOKEN
+and has not run. Oracle: official Manage Vanta OpenAPI and authentication documentation.
+
+### Deliberately not modelled
+
+Real employee offboarding, accounts/integration task engines, evidence bytes/downloads, trust-center
+UI, browser OAuth/refresh, automatic compliance evaluation, full vendor resource schemas, list
+filter expressions and live quota accounting. Seed the fields the consumer reads; collections
+echo them without fabricating compliance conclusions. Eligibility flags are explicit test controls,
+not substitutes for real account deactivation. No real tenant mutation is ever necessary.
+
+## API
+
+- `VantaAPI`: FetchAPI, reset and collections.
+- `createRuntime`: shared namespace/admin/clock/fault contract.
+- `VANTA_NAMESPACE`, `VANTA_SCOPES`, `VANTA_PRESETS`: service constants.
+- `document`, `operationIds`, `supportedOperationIds`: generated contract metadata.
+- `createServer`, `serveTarget`, `DEFAULT_PORT` from `./server`: Node server and CLI targets.
+
+Public types: Resource, Client, Token, Upload, Eligibility, VantaAPIOptions, OperationId,
+SupportedOperationId; VantaServerOptions and VantaServer from ./server.

package/SUPPORT.md

@@ -0,0 +1,20 @@
+# Manage Vanta consumer subset — operation support
+
+Generated from `openapi.yaml`; do not edit by hand.
+
+- operations in spec: **10**
+- supported by the mock: **10**
+- parity enabled: **9**
+
+| operationId | route | mock | parity | notes |
+| --- | --- | --- | --- | --- |
+| `ListPeople` | `GET /v1/people` | ✅ supported | ✅ |  |
+| `ListTests` | `GET /v1/tests` | ✅ supported | ✅ |  |
+| `ListControls` | `GET /v1/controls` | ✅ supported | ✅ |  |
+| `ListDocuments` | `GET /v1/documents` | ✅ supported | ✅ |  |
+| `GetPerson` | `GET /v1/people/{personId}` | ✅ supported | ✅ |  |
+| `GetDocument` | `GET /v1/documents/{documentId}` | ✅ supported | ✅ |  |
+| `OAuthToken` | `POST /oauth/token` | ✅ supported | ⚠️ unsafe (opt-in) |  |
+| `UploadFileForDocument` | `POST /v1/documents/{documentId}/uploads` | ✅ supported | ❌ disabled | Multipart file uploads exercised through raw-fetch acceptance tests. |
+| `SubmitDocumentCollection` | `POST /v1/documents/{documentId}/submit` | ✅ supported | ⚠️ unsafe (opt-in) |  |
+| `OffboardPeople` | `POST /v1/people/offboard` | ✅ supported | ⚠️ unsafe (opt-in) |  |