feat(auth): Doorkeeper route parity with the legacy Ruby auth service (PPT-2536)

[camreeves]

What & why

Makes the Crystal auth.cr service a drop-in replacement for the legacy Ruby/Rails Doorkeeper auth at the route level (PPT-2536). Building on the wire-parity work in #1, this adds the remaining Doorkeeper/OIDC endpoints so that every route the Rails service exposed is served here with matching behaviour.

./auth_migration/route_diff.sh reports route parity: OK — every Rails route is matched (the additive short-path /auth/* aliases are allowlisted).

Routes added

Discovery / OIDC

• /.well-known/oauth-authorization-server + the /auth/.well-known/{openid-configuration,oauth-authorization-server} mount variants, and webfinger at both roots
• GET /auth/oauth/discovery/keys — JWKS derived from the signing key (RFC 7638 thumbprint kid)
• POST /auth/oauth/userinfo (the OIDC §5.3 verb; the discovery doc now advertises the /auth/oauth/* mounts + jwks_uri + introspection_endpoint)

Token endpoints

• POST /auth/oauth/introspect (RFC 7662) — caller-authenticated (client credentials or bearer), Doorkeeper's cross-client visibility policy
• GET /auth/oauth/token/info

Authorization endpoint

• POST (consent submit) and DELETE (deny) on /auth/oauth/authorize, plus the native OOB code page

Application management

• /auth/oauth/applications CRUD (admin-gated) and /auth/oauth/authorized_applications

Misc

• POST /auth/signup (403 stub for route parity — see note), catch-all 404 parity

Parity notes / accepted divergences

Every deliberate difference from the Ruby service is documented in auth_migration/parity_matrix.md, per route. Highlights:

• userinfo returns a superset of Ruby's claims (Ruby effectively returned only sub because profile/email/phone were never registered as issuable scopes).
• Discovery advertises what auth.cr actually supports (honest capability lists) rather than Rails' aspirational ones. Note: at the Ruby service's pinned gem versions the discovery/webfinger endpoints actually 500 (a doorkeeper-openid_connect issuer-block arity regression) — this implements the intended behaviour.
• POST /auth/signup is served but always returns 403: auth.cr never issues the short-lived social cookie the Ruby signup required (OAuth users are auto-created in the callback), so 403 is the only reachable state in either service. The user-creation path stays intentionally dropped — resurrecting it is a separate product decision.
• Applications CRUD reproduces Doorkeeper's JSON quirks (204-empty index, plaintext secret in owner records, {"errors":[…]} on 422) but serves JSON rather than the gem's HTML admin views — in the platform these are managed via rest-api's /oauth_apps + Backoffice.

Testing

• Full spec suite: 114 examples, 0 failures (real Postgres + Redis via ./test)
• ameba clean over the whole tree, crystal tool format --check clean
• Live-binary smoke test: ran the compiled binary against Postgres+Redis; every route returns the expected status and the discovery/JWKS bodies are correct

An adversarial multi-lens self-review before opening this PR caught and fixed a token-introspection cross-client visibility bug (a bearer caller could introspect another application's token) and hardened several parity gaps; see the last two commits.

The auth_migration/ folder

Contains the parity artefacts: the Rails + auth.cr route dumps, parity_matrix.md, and route_diff.sh (a mechanical parity check that can run in CI). Happy to relocate these if a maintainer would prefer them elsewhere.

Open questions for reviewer

A few deliberate choices where I'd value @stakach's call — flagging them so they read as intentional rather than oversights:

1. auth_migration/ folder placement. It ships in the service repo (route dumps, parity_matrix.md, route_diff.sh — the last is a mechanical parity check that could run in CI). Happy to move it to a docs/investigation location or drop it from the service repo if you'd prefer.
2. POST /auth/signup. The route is served but always returns 403 — auth.cr never issues the social cookie the Ruby signup required, so 403 is the only reachable state. This is purely for route-table parity; the user-creation path stays dropped per the README. If you'd rather not carry a stub route at all, I'll remove it and record signup as an intentional route-level omission instead.
3. Applications management scope. /auth/oauth/applications (+ authorized_applications) is implemented for faithful parity, but it's superseded in the platform by rest-api's /oauth_apps + Backoffice. If parity here isn't worth the surface, I can drop it (and the placeholder new/edit HTML forms) and document it as a deliberate divergence.
4. Smaller judgment calls: the confidential-defaults-true fix lives in the controller rather than changing the oauth_applications model default (which is false); and the authorize endpoint's redirectable errors return a JSON 400 rather than a 302 back to redirect_uri?error=… (pre-existing GET-handler behaviour, now shared by the new POST alias). Both are documented in parity_matrix.md — say the word if either should change here.

🤖 Generated with Claude Code

[camreeves]

I also got Claude to break down what it's confident about and what might have issues:

What I'm genuinely confident about (low risk):

• No red CI — 114 specs pass against real Postgres+Redis, ameba's clean over the whole tree, format's clean, route parity checks out.
• No functional bugs on the paths the specs exercise, and the one real bug the review found (the introspection cross-client leak) is fixed and tested.
• The security-sensitive logic has been adversarially reviewed and hardened.

What Steve may well push back on (these aren't bugs — they're judgment/scope calls he's entitled to have opinions on):

1. The auth_migration/ folder living in the service repo. My own review flagged that a maintainer might want it moved to docs or dropped. You asked for it there, but Steve might disagree.
2. The hand-rolled DER/ASN.1 parser in jwks.cr. A reviewer could reasonably ask "why not a library?" — there may be an ecosystem shard he'd prefer for JWKS.
3. The signup 403 stub. He documented signup as deliberately dropped; I added the route back as a stub for route-table parity. He might say "don't add a fake route, leave it dropped." This is the one I'd most expect him to have a firm view on.
4. Serving the applications CRUD at all — it's fully superseded by rest-api's /oauth_apps. You said "full parity, change later," but Steve might question building a superseded admin surface (and the placeholder HTML forms).
5. Smaller ones: the confidential-default fix living in the controller vs the model, and whether the authorize redirectable-errors should return 302 rather than JSON (I documented it as pre-existing).`