feat!: complete the Connect Applications contract

[danielloader]

Applications was the emulator's most incomplete surface in SUPPORTED.md: 4/5 read and 5/8 write. This implements the four endpoints the spec defines and the emulator did not, and closes the gaps the existing routes had against the same contract.

Spec source throughout: @workos/openapi-spec@0.80.0, the version this repo pins (see #120 on why that pin is stale — this PR deliberately stays inside 0.80.0, and none of the Applications operations differ in 0.107.0).

New endpoints

Method	Path	Notes
GET	/connect/applications/{id}/client_secrets	The spec returns a bare array here, not the list envelope every other collection route uses
PUT	/connect/applications/{id}	UpdateOAuthApplicationDto: absent leaves a field alone, explicit null clears
DELETE	/connect/applications/{id}	204, and drains the application's children
POST	/client/token	201 { token }, signed with the emulator key so it verifies against /sso/jwks

Applications is now ✅ 5/5 read, ✅ 8/8 write. Repo coverage 180 → 184 of 250 (73.6%).

Contract gaps fixed in the existing routes

• A third-party OAuth application was unrepresentable. ConnectApplication's oauth branch is a three-way oneOf on how the application came to exist, but the formatter hardcoded is_first_party: true and dropped organization_id. Creating one with {is_first_party: false, organization_id: …} returned it as first-party with no owner. The entity now carries is_first_party, was_dynamically_registered and uses_pkce, and the formatter emits the matching arm.
• uses_pkce was a documented create field that was discarded and then contradicted as false in every response.
• GET /connect/applications ignored its documented filters. organization_id and registration_types are implemented, including the spec's "defaults to authenticated only when not specified".
• Create accepted redirect_uris on m2m applications, which CreateM2MApplicationDto does not define and no route reads — and the m2m formatter never serialized them, so the value was invisible and unclearable.
• A blank redirect URI locked out every callback. /oauth2/authorize treats a non-empty list as an allow-list, so a single "" entry turned every authorize into invalid_request. Blank entries are now rejected.
• PUT with no body returned 400. It is a no-op now, matching api-keys.ts and widgets.ts.

Cascade and credential lifetime

DELETE drains the application's client secrets and any in-flight Standalone Connect session or authorization code bound to its client_id. Without that, a browser mid-login still completed at /oauth2/authorize/complete, created a user, and landed on the callback holding a code that /oauth2/token could never redeem.

last_used_at is stamped when an exchange actually produces a token — not when the secret is merely presented. A request rejected on grant type, code or scope no longer records the credential as used.

Test and conformance work

• The client secret resource joins the generated shape-conformance harness (OBJECT_SCHEMA_MAP), which brings it under the secret-leak guard. Verified by mutation: removing value from the exclude set fails two assertions.
• POST /client/token and POST …/client_secrets join ENVELOPE_SCHEMA_MAP, so their envelopes are checked against the spec rather than by hand.
• connect_application is deliberately not in the resource catalog — ConnectApplication is an allOf over a four-way oneOf, and that catalog models one flat shape per object. Flattening it would drop the discriminated fields, which is exactly what resolveSchema refuses to do. Each arm is pinned by a route test instead, and the reason is recorded where the entry would have gone.
• Four existing/new assertions that could not fail were rewritten: an aud compared against the constant that produced it, a list-order assertion that insertion order already satisfied (now back-dates a record so the two disagree), and two hints compared against their own response rather than the stored value.

BREAKING CHANGE

The client secret resource now matches the spec's NewConnectApplicationSecret:

Before	After
object: "client_secret"	object: "connect_application_secret"
last_four	secret_hint
value (plaintext, on create)	secret
—	last_used_at
application_id serialized	not serialized — it is the emulator's foreign key, not a spec field

ID prefixes now follow the spec's own examples: conn_app_… replaces connect_app_…, and secret_… replaces client_secret_….

WorkOSClientSecret is part of the published type surface via @workos/emulate/workos, so a consumer reading secret.last_four, switching on object === "client_secret", or inserting a client-secret literal will need updating. The connectApplications seed key — including client_secret — is unchanged, so seed files keep working.

The remaining ID-prefix divergences from the spec (evt_, inv_, auth_res_ and others) are deliberately not in this PR; they are unrelated to Applications and follow separately.

Verification

npm run typecheck, npm run lint, npm run fmt:check clean. bun test: 1313 pass, 1 fail — redirect-hosts.spec.ts's punycode case, which fails identically on clean main and is untouched here. gen:shapes and gen:supported re-run byte-identical, so there is no codegen drift.

🤖 Generated with Claude Code

[greptile-apps]

Confidence Score: 5/5

The PR appears safe to merge; no actionable new issue remains, and the previously reported ownerless third-party seed problem is resolved.

Summary

Completes the Connect Applications contract and strengthens its conformance coverage.

• Adds application update and deletion, client-secret listing, and Client API token creation.
• Correctly represents first- and third-party OAuth applications, PKCE configuration, filters, redirect URIs, and the revised client-secret resource contract.
• Cascades application deletion to credentials and in-flight standalone OAuth state.
• Records successful client-secret use while avoiding stamps for failed exchanges.
• Adds generated shape and envelope coverage plus focused route and lifecycle tests.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  App[Connect application] --> Secret[Client secrets]
  App --> Session[External auth sessions]
  App --> Code[Authorization codes]
  Secret --> Exchange[OAuth token exchange]
  Exchange -->|Success| Stamp[Stamp last_used_at]
  Exchange --> Token[Signed access token]
  Delete[Delete application] --> App
  Delete -->|Cascade| Secret
  Delete -->|Cascade| Session
  Delete -->|Cascade| Code

Loading

_{Reviews (3) · Last reviewed commit: "test(connect): cover the login cascade o..."}

[danielloader]

Heads-up on merge order: #122 corrects the remaining ID_PREFIXES divergences against the same spec, and ledgers this PR's two (connect_application, client_secret) as known-divergent because they still are on main today.

The branches merge cleanly — no textual conflict, verified with git merge-tree — but once both land, #122's drift guard correctly reports those two entries as stale and fails until they are deleted:

(fail) ID prefix conformance > has no stale divergence — a tracked divergence
       that now matches the spec must be deleted
  - []
  + [ "connect_application", "client_secret" ]

So whichever merges second needs a two-line follow-up deleting those entries from TRACKED_DIVERGENCES in src/workos/id-prefixes.spec.ts. I verified this by merging the two branches locally and running the suite, and I'm happy to push that follow-up once you've decided the order.

[gjtorikian]

thanks!