A deterministic in-process Microsoft OIDC mock authority ships in @authfx/microsoft as the protocol fixture kit

Context

This issue delivers MicrosoftOidcFixture: a deterministic, in-process mock of the Microsoft Entra authority that lets every AuthFX test — and later the Plus-One migration acceptance flow — exercise the Microsoft authenticator without live credentials or network access. The kit covers discovery metadata, the authorization redirect/callback pair, one-time code exchange with PKCE verification, JWKS publication and rotation, valid organizational identities, every adversarial variant (wrong tenant, issuer, audience, nonce, signature, expiry, replay), and configurable latency and provider failures.

The load-bearing design property: the fixture provides its own effect/unstable/http HttpClient routing requests by URL to in-memory handlers, so the production Discovery/Jwks/TokenClient modules (#11) run unmodified against it — the code path the independent security review (#6) audits is the one under test.

Spec grounding (relative paths in this repo):

• docs/spec/08-microsoft-oidc-provider.md — "support a configurable authority for deterministic local testing" (the AUTHFX_MICROSOFT_AUTHORITY override is the seam this kit plugs into).
• docs/spec/03-non-functional-requirements.md (Testability) — "Provider packages include protocol fixtures for success, denial, malformed responses, key rotation, replay, and timeout."
• docs/spec/12-testing-and-security-verification.md — mandates "Microsoft OIDC protocol fixture tests" and "end-to-end local mock-provider tests"; "No test waits on wall-clock time."
• docs/spec/decisions/ ADR-0005 — Microsoft test fixtures and mock-authority support are required from the first implementation, not deferred.
• docs/spec/13-plusone-migration.md — the kit is reused by the Plus-One migration acceptance flow (Phase 6: create Plus-One AuthFX migration adapter #8).

Governing decisions

• D3 (foundations) — protocol code lives in the provider package, never core; jose is a package-boundary dependency wrapped behind Effect services; PKCE S256 only, 32-byte state/nonce — the fixture enforces exactly these algorithm choices at its endpoints.
• D8 (foundations) — sign-in registration only: the fixture token endpoint serves only the authorization_code grant, and its response carries decoy access_token/refresh_token values so downstream conformance proves production code drops them.
• D9 (foundations) — naming law: service tag "@authfx/microsoft/MicrosoftOidcFixture", env prefix AUTHFX_, kebab-case files, one namespace per file, Schema.TaggedErrorClass errors, zero code comments.
• D10 (foundations) — provider fixtures live inside the provider package; a hard environment gate keeps mock authorities out of production composition (the m365-mock discipline); determinism via the TokenCrypto test layer and TestClock.
• D13 (foundations) — designed from the Microsoft case only; no generic multi-provider fixture abstraction.
• Architecture §5.7 — normative fixture design: the Interface/Service/FixtureTamper shapes, the dual-provision fixtureLayer, fixture-keys.ts keypair ownership, the AUTHFX_MICROSOFT_FIXTURE=1 gate, and serveLayer for out-of-process use.
• Architecture §1.5 — package layout and the constraint that jose appears in exactly two src/ call sites: oidc/jwks.ts (Phase 3: implement Microsoft Entra OIDC authenticator #11) and fixture/fixture-keys.ts (this issue).
• Architecture §5.4/§5.6 + review log feat(docs): add FoldKit documentation site #13/Phase 1: scaffold workspace packages and @authfx/testing foundations #14/#19/#20 — the fixture must let tests exercise the amended verification semantics: RS256-only signing, exact single-audience aud (and azp when present), per-tenant issuer substitution via tid, xms_edov as the only verified-email signal, and retryable-outage classification distinct from terminal proof failure.
• Architecture §9.2/§9.3/§10.2 — the authenticator conformance harness runs under this fixture; determinism comes from DeterministicTokenCrypto; the all-memory composition wires MicrosoftOidcFixture.fixtureLayer as the only HttpClient in test graphs.

Deliverables

packages/microsoft/
  package.json
  tsconfig.json
  AGENTS.md
  src/
    index.ts
    fixture/
      fixture.ts
      fixture-keys.ts
      fixture-http-client.ts
  test/
    fixture.test.ts

Modified files:

• root package.json — add jose to the workspace catalog, pinned exact (architecture §12 open question 3: exact pin, renovate review lane).
• packages/microsoft/package.json — dependencies effect (catalog), @authfx/core (workspace), jose (catalog); devDependencies @authfx/testing (workspace), @effect/vitest (catalog).
• packages/microsoft/src/index.ts — barrel adds export * as MicrosoftOidcFixture from "./fixture/fixture" and the microsoftPackage marker constant (full barrel shape per architecture §1.5; the other namespace exports land with Phase 3: implement Microsoft Entra OIDC authenticator #11 — do not create their files here).

This issue owns src/fixture/** and test/fixture.test.ts only. It must not create src/oidc/**, src/authenticator.ts, src/microsoft-config.ts, src/tenant-policy.ts, or src/errors.ts — those are #11 deliverables in the same package.

Contracts

The fixture service, copied exactly from the architecture doc (§5.7):

export interface Interface {
  readonly issueLogin: (input: {
    readonly authorize_url: string
    readonly subject: string
    readonly tenant_id: string
    readonly email?: string | undefined
    readonly display_name?: string | undefined
    readonly email_verified?: boolean | undefined
  }) => Effect.Effect<{ readonly state: string; readonly code: string }, FixtureError>
  readonly tamper: (mutation: FixtureTamper) => Effect.Effect<void>
  readonly rotateSigningKey: (options: { readonly publishPrior: boolean }) => Effect.Effect<void>
  readonly failNext: (target: "discovery" | "jwks" | "token", failure: FixtureFailure) => Effect.Effect<void>
  readonly latency: (target: "discovery" | "jwks" | "token", duration: Duration.Duration) => Effect.Effect<void>
}

export class Service extends Context.Service<Service, Interface>()("@authfx/microsoft/MicrosoftOidcFixture") {}

export type FixtureTamper =
  | { readonly _tag: "WrongIssuer" }
  | { readonly _tag: "WrongAudience" }
  | { readonly _tag: "WrongNonce" }
  | { readonly _tag: "WrongTenant"; readonly tenant_id: string }
  | { readonly _tag: "ExpiredToken"; readonly expiredByMillis: number }
  | { readonly _tag: "BadSignature" }

The layer signature, copied exactly (§5.7) — it provides both the fixture service and the HttpClient the production protocol modules consume:

export const fixtureLayer: Layer.Layer<Service | HttpClient.HttpClient, never, TokenCrypto.Service> =
  Layer.effect(...)

FixtureError and FixtureFailure are referenced but not defined in the architecture doc; complete them minimally, house style (Schema.TaggedErrorClass, fully qualified tag):

export class FixtureError extends Schema.TaggedErrorClass<FixtureError>()(
  "@authfx/microsoft/FixtureError",
  { detail: Schema.String },
) {}

export type FixtureFailure =
  | { readonly _tag: "Unavailable"; readonly status: number }
  | { readonly _tag: "NetworkError" }
  | { readonly _tag: "MalformedBody" }

The dependency this kit consumes — the @authfx/core TokenCrypto port (D6, architecture §4.1, already shipped by earlier phases; copied exactly, do not re-derive):

export interface Interface {
  readonly randomBytes: (size: number) => Effect.Effect<Uint8Array, TokenCryptoError>
  readonly sha256Base64Url: (input: Redacted.Redacted<string>) => Effect.Effect<string, TokenCryptoError>
  readonly constantTimeEquals: (a: string, b: string) => Effect.Effect<boolean>
  readonly randomUUIDv7: Effect.Effect<string, TokenCryptoError>
}

export class Service extends Context.Service<Service, Interface>()("@authfx/core/TokenCrypto") {}

Beta.93 API facts the implementation relies on (verified against node_modules/.bun/effect@4.0.0-beta.93/.../effect/src): HttpClient.make takes a request runner (request, url, signal, fiber) => Effect<HttpClientResponse, HttpClientError>; synthetic responses are built with HttpClientResponse.fromWeb(request, new Response(...)); HttpRouter (for serveLayer) lives in effect/unstable/http.

Implementation steps

1. Catalog and package wiring. Add jose to the root package.json workspace catalog pinned to an exact version. In packages/microsoft/package.json declare dependencies effect, @authfx/core, jose and devDependencies @authfx/testing, @effect/vitest. Verify: bun install succeeds; bun run build still passes.
2. src/fixture/fixture-keys.ts — key custody and the only jose call site in this issue. Generate an RS256 keypair per fixture instance via jose.generateKeyPair("RS256") (RSA keygen cannot be seeded; determinism comes from the fixture owning both signing and publication, per §5.7). Export: make (scoped key-state construction with a generated kid), a JWKS-document builder (jose.exportJWK on active plus optionally prior public keys, each carrying its kid), and a signIdToken helper (jose.SignJWT, alg: "RS256", honoring an option to sign with a corrupted signature or an unpublished key for the BadSignature tamper). No other fixture file may import jose (§1.5 constraint; enforceable by ast-grep).
3. src/fixture/fixture.ts — authority state. Model mutable authority state in Refs inside Layer.effect: recorded logins keyed by state (holding nonce, code_challenge, client_id, redirect_uri, and the issueLogin identity inputs), a one-time code registry (code → login, consumed flag), the signing-key state from step 2, a one-shot tamper queue, per-target one-shot failure injections, and per-target latencies. Export a fixtureAuthority constant (a fixed non-resolvable base such as https://login.fixture.authfx.test) that consumers use to build their MicrosoftConfig test layer; the discovery document, issuer claims, and URL routing all derive from it.
4. issueLogin. Parse input.authorize_url with URL; fail FixtureError unless it targets the fixture authority's authorize path and carries response_type=code, client_id, redirect_uri, response_mode=query, scope exactly openid profile email, state, nonce, code_challenge, and code_challenge_method=S256 (the D3 normative table). Record the login, mint a single-use code from TokenCrypto.randomBytes (base64url), and return { state, code } — exactly what a browser redirect would deliver to the callback.
5. Protocol handlers. Implement three pure-ish handlers over the state from step 3:
   • Discovery: serves ${fixtureAuthority}/${tenant}/v2.0/.well-known/openid-configuration returning issuer (template form with the tenant segment), authorization_endpoint, token_endpoint, jwks_uri, all under fixtureAuthority (matches the production Discovery fetch shape in §5.4).
   • JWKS: serves the document from step 2; after rotateSigningKey({ publishPrior: true }) it contains the prior public key alongside the new one; with publishPrior: false the prior key is absent (drives R-SEC-25 both ways).
   • Token: accepts form-encoded POSTs; validates grant_type === "authorization_code", known single-use code (second use answers HTTP 400 {"error":"invalid_grant"} — replay), client_id and redirect_uri matching the recorded login, and PKCE: SHA-256(code_verifier) base64url via TokenCrypto.sha256Base64Url must equal the recorded code_challenge. On success mint an id_token with claims iss (${fixtureAuthority}/${tid}/v2.0), aud (recorded client_id), sub, tid, oid (derived stably from subject), nonce (recorded), iat/nbf/exp from Clock.currentTimeMillis, plus email/name when provided, and xms_edov: true only when email_verified: true was requested (§5.6 claims mapping, review log Phase 1: scaffold workspace packages and @authfx/testing foundations #14). The JSON response carries id_token plus decoy access_token, refresh_token, and expires_in fields — production TokenClient must discard them (D8), and the §9.2 conformance case asserts they never surface.
6. Tamper application. Before signing, drain the one-shot tamper queue and apply mutations: WrongIssuer sets iss to a value that fails the tid-template substitution check; WrongAudience sets aud to a different client id; WrongNonce replaces the nonce claim; WrongTenant re-mints the token for mutation.tenant_id with consistent tid and iss (the token stays protocol-valid so it reaches the tenant policy and exercises AssertionRejectedByPolicy, distinct from protocol failure — R-SEC-11); ExpiredToken sets exp to now minus expiredByMillis; BadSignature signs via the corrupted-signature path from step 2. Tampers affect exactly one issuance, then clear.
7. Failure and latency controls. failNext(target, failure) arms a one-shot response for that endpoint: Unavailable answers the given 5xx status, NetworkError fails the HttpClient effect with a request-transport error, MalformedBody returns 200 with undecodable JSON. latency(target, duration) prepends Effect.sleep(duration) to the handler so TestClock.adjust controls it — no wall-clock waits (spec 12).
8. src/fixture/fixture-http-client.ts — in-memory transport. Export a route table mapping URL prefixes under fixtureAuthority to the step-5 handlers, and a constructor building the HttpClient via HttpClient.make whose runner matches url against the table and returns HttpClientResponse.fromWeb(request, new Response(body, { status, headers })). Unmatched URLs fail with a request error (the fixture never proxies to the network). Also export the same handler table shaped as effect/unstable/http HttpRouter routes; serveLayer (exported from fixture.ts, composing this module) mounts them for out-of-process mode — the consumer supplies the platform server layer (BunHttpServer in the Plus-One harness, Phase 6: create Plus-One AuthFX migration adapter #8), keeping @authfx/microsoft's dependency list at effect + @authfx/core + jose (§1.5).
9. fixtureLayer with the hard environment gate. Layer.effect reads AUTHFX_MICROSOFT_FIXTURE from configuration and Effect.dies unless it equals "1" (D10 m365-mock discipline: a mock authority can never build in a production composition by accident). On success it constructs the state, the service implementation, and the in-memory HttpClient, providing both tags per the §5.7 signature.
10. Barrel. src/index.ts exports MicrosoftOidcFixture and export const microsoftPackage = "@authfx/microsoft". Verify the wordmark/naming law (D9): no AuthFx/authFX spellings, tag strings fully qualified.
11. test/fixture.test.ts — self-tests. See Testing below. Set AUTHFX_MICROSOFT_FIXTURE=1 inside the test setup, provide DeterministicTokenCrypto.layer(seed) from @authfx/testing, and use it.effect throughout (no it.scoped in beta.93).

Testing

All tests live in packages/microsoft/test/fixture.test.ts, run with @effect/vitest idioms locked by architecture §9.5: it.effect everywhere, Effect.flip for error-channel assertions, layers via .pipe(Effect.provide(...)), TestClock.adjust for every timing case. Tests may import jose directly to verify wire-level effects (the §1.5 two-call-site constraint governs src/, and jose is already a package dependency).

Required cases:

• issueLogin accepts a compliant authorize URL and returns { state, code }; it fails FixtureError for a missing code_challenge, a non-S256 method, a wrong scope list, or a foreign authority.
• Happy path: exchanging the code at the token handler returns an id_token that verifies against the fixture JWKS with expected iss/aud/sub/tid/nonce claims; xms_edov present only when email_verified: true was requested; decoy access_token/refresh_token/expires_in fields present in the raw response.
• Replay: a second exchange with the same code answers invalid_grant (one-time enforcement).
• PKCE: a wrong code_verifier is rejected; the recorded code_challenge equals SHA-256(code_verifier) base64url.
• Each FixtureTamper produces exactly its intended defect and only for the next issuance: WrongIssuer (iss/tid template mismatch), WrongAudience (aud ≠ client_id), WrongNonce, WrongTenant (protocol-valid token, different consistent tid+iss), ExpiredToken (exp in the past by expiredByMillis against the virtual clock), BadSignature (fails JWKS verification).
• rotateSigningKey({ publishPrior: true }): JWKS serves both keys; tokens minted before rotation still verify. With publishPrior: false: prior key absent; pre-rotation tokens no longer verify against the served set (the R-SEC-25 raw material).
• failNext for each of discovery/jwks/token produces the armed failure exactly once, then the endpoint recovers; all three FixtureFailure variants covered at least once.
• latency delays a handler by the configured duration under TestClock.adjust; no test sleeps in real time.
• Environment gate: building fixtureLayer without AUTHFX_MICROSOFT_FIXTURE=1 dies (assert via Effect.exit on layer construction).
• Determinism: two runs with the same DeterministicTokenCrypto.layer(seed) produce identical state and code sequences.

Security catalog note (D10, architecture §9.4): R-SEC-23 (nonce mismatch), R-SEC-24 (wrong issuer or audience), and R-SEC-25 (stale signing keys) are owned by @authfx/microsoft but their named adversarial tests exercise the authenticator's complete path and therefore land with #11, consuming the WrongNonce/WrongIssuer/WrongAudience tampers and rotateSigningKey controls this issue ships. This issue must leave those controls behaving exactly as the §9.4 test names assume.

Commands (repo AGENTS.md gates — all must pass at root):

bun install
bun run format:check
bun run lint
bun run typecheck
bun run test
bun run test:coverage
bun run build

Coverage thresholds 90/65/90/90 apply to this package from its first source file (D10).

Acceptance criteria

• packages/microsoft/src/fixture/{fixture,fixture-keys,fixture-http-client}.ts exist with the exact Interface, Service tag "@authfx/microsoft/MicrosoftOidcFixture", FixtureTamper union, and fixtureLayer: Layer.Layer<Service | HttpClient.HttpClient, never, TokenCrypto.Service> signatures from architecture §5.7.
• fixtureLayer provides a working in-memory HttpClient serving discovery, JWKS, and token endpoints under the exported fixtureAuthority, with zero network sockets opened in the in-process mode.
• The token endpoint enforces single-use codes, client_id/redirect_uri binding, and PKCE S256 verification, and answers OAuth-shaped errors (invalid_grant on replay).
• Issued id_tokens are RS256-signed, carry iss/aud/sub/tid/oid/nonce/iat/nbf/exp (plus email/name/xms_edov as requested), and verify against the fixture JWKS.
• All six FixtureTamper variants, rotateSigningKey with and without prior publication, failNext for all three targets, and TestClock-driven latency are implemented and covered by test/fixture.test.ts.
• WrongTenant yields a protocol-valid token (consistent tid/iss) so tenant-policy rejection is distinguishable from protocol failure (R-SEC-11).
• The token response includes decoy access_token/refresh_token/expires_in fields so D8 discard behavior is testable downstream.
• fixtureLayer dies at construction unless AUTHFX_MICROSOFT_FIXTURE=1.
• serveLayer exposes the same handlers over effect/unstable/http routing with the platform server supplied by the consumer; @authfx/microsoft dependencies remain exactly effect, @authfx/core, jose.
• jose appears in src/ only inside fixture/fixture-keys.ts; it is pinned exact in the root catalog.
• With the same DeterministicTokenCrypto seed, state/code sequences are reproducible across runs; no test waits on wall-clock time.
• No files owned by Phase 3: implement Microsoft Entra OIDC authenticator #11 (src/oidc/**, authenticator.ts, microsoft-config.ts, tenant-policy.ts, errors.ts) are created; no Plus-One vocabulary appears in any exported name.
• bun run format:check, bun run lint, bun run typecheck, bun run test, bun run test:coverage, and bun run build all pass at the repo root.

Dependencies

Blocked by:

• Phase 1: scaffold workspace packages and @authfx/testing foundations #14 — provides the packages/microsoft workspace skeleton and @authfx/testing with DeterministicTokenCrypto.
• Phase 1: define core schemas, ids, and tagged errors #1 — core branded ids and shared scalar schemas the package imports.
• Phase 2: implement opaque session service #4 — the @authfx/core TokenCrypto port (architecture §4.1, D6), fixtureLayer's only requirement.

Blocks:

• Phase 3: implement Microsoft Entra OIDC authenticator #11 — the Microsoft authenticator's fixture-driven protocol tests and the R-SEC-23/24/25 adversarial suite consume this kit (inventory: Phase 3: implement Microsoft Entra OIDC authenticator #11 depends on Phase 3: build Microsoft OIDC mock and protocol fixture kit #5).
• Phase 6: create Plus-One AuthFX migration adapter #8 — Plus-One migration acceptance points AUTHFX_MICROSOFT_AUTHORITY at a serveLayer instance.
• Phase 7: complete independent authentication security review #6 — the security review audits fixture-driven coverage of the Microsoft adversarial catalog rows.
• Add an AuthFX + ConnectFX co-embedding smoke test #18 — its login leg runs against this fixture.

Coordination constraint: this issue and #11 modify the same package. The file-ownership split above is the contract; land this issue first so #11's tests can consume the kit from day one.

Out of scope

• The Microsoft authenticator itself and all protocol modules (oidc/discovery.ts, oidc/jwks.ts, oidc/pkce.ts, oidc/token-client.ts, oidc/challenge.ts, oidc/claims.ts, microsoft-config.ts, tenant-policy.ts, errors.ts) — Phase 3: implement Microsoft Entra OIDC authenticator #11 per docs/spec/08-microsoft-oidc-provider.md and ADR-0005.
• The named R-SEC-23/24/25 adversarial tests — they exercise Authenticator.complete and land in Phase 3: implement Microsoft Entra OIDC authenticator #11's test/security/microsoft-adversarial.test.ts (D10 placement, architecture §9.4).
• HTTP begin/callback endpoint testing — @authfx/http, Phase 4: implement Effect HTTP authentication adapter #7 (docs/spec/07-http-security-and-framework-boundaries.md, ADR-0006).
• The Plus-One migration harness and cutover flow — Phase 6: create Plus-One AuthFX migration adapter #8 (docs/spec/13-plusone-migration.md); this issue only ships the reusable serveLayer.
• Live Microsoft integration tests — opt-in only and never in the default suite (D10; docs/spec/12-testing-and-security-verification.md).
• Any refresh-token, client-credentials, or admin-consent grant support in the fixture — the sign-in registration exchanges a code exactly once (D8); operational Microsoft flows belong to ConnectFX (CONTEXT.md boundary).
• A generic multi-provider fixture framework or shared standards package — D3/D13 and ADR-0003 forbid pre-generalizing from one provider; @connectfx/microsoft carries its own fixtures.
• Deterministic RSA key seeding — impossible for RSA keygen; determinism is scoped to token/state/code material via TokenCrypto (architecture §5.7 rationale).