Add provider identity resolution API

[ColeMurray]

Summary

• Add a shared canonical user ID validator for 32-character lowercase hex D1 user IDs.
• Add an internal HMAC-authenticated PUT /provider-identities/:provider/:providerUserId control-plane route that upserts provider identity metadata through UserStore.resolveOrCreateUser and returns the canonical userId.
• Add browser-facing GET /api/me, deriving GitHub identity from the server-side NextAuth session and returning only the canonical user ID.

Validation

• npm run build -w @open-inspect/shared
• npm test -w @open-inspect/shared -- user-id
• npm run typecheck -w @open-inspect/shared
• npm run lint -w @open-inspect/shared -- --quiet
• npm test -w @open-inspect/control-plane -- routes/provider-identities.test.ts router.provider-identities.test.ts
• npm run typecheck -w @open-inspect/control-plane
• npm run lint -w @open-inspect/control-plane -- --quiet
• npm test -w @open-inspect/web -- app/api/me/route.test.ts
• npm run typecheck -w @open-inspect/web
• npm run lint -w @open-inspect/web -- --quiet

Summary by CodeRabbit

• New Features

  • New API to return the authenticated user's GitHub-derived identity and canonical user ID.
  • New endpoints to upsert GitHub provider identities and return a canonical user ID.
  • Shared validator ensuring canonical 32-character lowercase hex user IDs.

• Bug Fixes

  • Improved input validation and explicit error responses for invalid provider-user IDs and malformed requests.
  • Better error handling when identity resolution returns unexpected values.

• Tests

  • Added integration and unit tests covering success, validation failures, and error paths.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 9dd0573a-fb49-4e14-9402-ad8aacecf50b

📥 Commits

Reviewing files that changed from the base of the PR and between e54a56a and be46fab.

📒 Files selected for processing (4)

• packages/control-plane/src/router.provider-identities.test.ts
• packages/control-plane/src/router.ts
• packages/control-plane/src/routes/provider-identities.test.ts
• packages/control-plane/src/routes/provider-identities.ts

💤 Files with no reviewable changes (1)

• packages/control-plane/src/router.provider-identities.test.ts

🚧 Files skipped from review as they are similar to previous changes (2)

• packages/control-plane/src/routes/provider-identities.ts
• packages/control-plane/src/router.ts

---

📝 Walkthrough

Walkthrough

This PR adds a GitHub provider identity resolution flow spanning the web and control-plane services. It introduces a canonical user ID validator, a control-plane route to upsert and resolve provider identities, router integration to serve the endpoint as SCM-agnostic, and a web API endpoint that invokes the control-plane to resolve the current authenticated user.

Changes

Provider Identity Resolution Implementation

Layer / File(s)	Summary
Canonical user ID validator packages/shared/src/user-id.ts, packages/shared/src/user-id.test.ts, packages/shared/src/index.ts	Exports isCanonicalUserId predicate to validate 32-character lowercase hex user IDs; tests accept canonical format and reject uppercase, non-hex, incorrect length, and null inputs; re-exports from package root.
Provider identity upsert route handler packages/control-plane/src/routes/provider-identities.ts, packages/control-plane/src/routes/provider-identities.test.ts	handleUpsertProviderIdentity parses PUT requests, validates GitHub-only provider, decodes path parameters, calls UserStore.resolveOrCreateUser, validates resolved user ID, and returns { userId } or error JSON; tests successful GitHub upserts with expected store calls and 400/500 validation/error cases.
Control-plane provider-identity tests & router integration packages/control-plane/src/router.ts, packages/control-plane/src/router.provider-identities.test.ts, packages/control-plane/src/routes/provider-identities.test.ts	Wires providerIdentityRoutes into main route array; extends isScmAgnosticRoute to treat /provider-identities/<segment>/<segment> as SCM-provider-agnostic; adds route-level and router integration tests including an authenticated integration that runs with SCM_PROVIDER set to a non-github value.
Web API current user endpoint packages/web/src/app/api/me/route.ts, packages/web/src/app/api/me/route.test.ts	GET /api/me validates next-auth session, requires GitHub user ID, calls control-plane PUT to upsert and resolve provider identity, validates returned userId with isCanonicalUserId, forwards control-plane errors, and returns 200 with { userId }; tests cover missing session (401), missing GitHub ID (409), successful resolution with display name fallback from name to login, error forwarding, invalid response shape (502), and exceptions (500).

Sequence Diagram

sequenceDiagram
  participant Client
  participant WebAPI as Web API
  participant Auth as AuthSession
  participant ControlPlane as Control-plane
  participant UserStore as User Store

  Client->>WebAPI: GET /api/me
  WebAPI->>Auth: getServerSession()
  Auth-->>WebAPI: session with GitHub user ID
  WebAPI->>ControlPlane: PUT /provider-identities/github/:login (login,email,displayName,avatarUrl)
  ControlPlane->>UserStore: resolveOrCreateUser(provider:"github", providerUserId, identity)
  UserStore-->>ControlPlane: { userId: canonical_32_char_hex }
  ControlPlane-->>WebAPI: { userId }
  WebAPI-->>Client: 200 { userId }

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• ColeMurray/background-agents#538: Introduces the UserStore schema and resolveOrCreateUser used by the new route.
• ColeMurray/background-agents#481: Related changes to isScmAgnosticRoute logic that this PR extends.

Suggested reviewers

• open-inspect
• amyragan3297

Poem

🐰 A rabbit hums, a tiny cheer,

GitHub ids now tidy here,
From web to plane they hop and flow,
Canonical hashes made to glow,
Resolved with care — hop, off we go!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 8.33% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and accurately summarizes the main change: adding a new provider identity resolution API across multiple packages.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch session-provider-identities

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[github-actions]

Terraform Validation Results

Step	Status
Format	✅
Init	✅
Validate	✅

Note: Terraform plan was skipped because secrets are not configured. This is expected for external contributors. See docs/GETTING_STARTED.md for setup instructions.

Pushed by: @ColeMurray, Action: pull_request

[open-inspect]

Summary

PR #686, "Add provider identity resolution API" by @ColeMurray adds canonical user ID validation, an HMAC-authenticated control-plane provider identity upsert endpoint, and a web /api/me route that resolves the current NextAuth GitHub user to the canonical D1 user ID. Overall the design is straightforward and well covered by targeted tests; I left one non-blocking inline comment about returning 400 instead of 500 for a JSON null request body.

Files changed: 9, +500/-1.

Critical Issues

None found.

Suggestions

• Error Handling packages/control-plane/src/routes/provider-identities.ts:41 - Validate that the parsed JSON body is a non-null object before reading optional metadata fields so valid-but-wrong JSON like null returns 400 instead of surfacing as an internal error.

Nitpicks

None.

Positive Feedback

• The new route remains behind the existing internal HMAC auth path and is explicitly SCM-provider agnostic only for this endpoint.
• The web route derives identity from the server-side NextAuth session rather than trusting client-supplied user identity.
• Tests cover auth/router integration, unsupported providers, path decoding failures, invalid canonical IDs, and web error forwarding.

Questions

None.

Verdict

Comment: feedback provided, no blocking issues found.

Validation note: I attempted to run npm test -w @open-inspect/shared -- user-id from a temporary PR worktree, but that worktree did not have dependencies installed (vitest unavailable), so I did not complete local test execution.

[github-actions]

Terraform Validation Results

Step	Status
Format	✅
Init	✅
Validate	✅

Note: Terraform plan was skipped because secrets are not configured. This is expected for external contributors. See docs/GETTING_STARTED.md for setup instructions.

Pushed by: @ColeMurray, Action: pull_request