Skip to content

Person identity: add self-service verified recovery credentials #6817

Open

Description

@bokelley

Problem

Admin credential linking exists, but a person cannot safely establish and manage their own durable recovery path before losing a work email. Job-change continuity still depends on manual intervention if the work credential disappears first.

Scope

  • Add a self-service account-settings flow to add a verified personal/recovery email as another WorkOS credential on the same identity.
  • Require proof of control of the current session and the target email; use step-up authentication for destructive credential changes.
  • List verified credentials, their primary/recovery state, and last-used metadata without exposing them publicly.
  • Allow a person to promote a verified credential and remove a non-primary credential.
  • Prevent removal of the last usable credential and handle pending, expired, replayed, and concurrently claimed links atomically.
  • Retire or reconcile the legacy user_email_aliases representation so the UI reflects real WorkOS credentials.
  • Surface a proactive reminder when a person has only a work-domain credential; do not wait until employer access is already gone.

Invariants

  • Email similarity, domain, name, or employer is never sufficient to link identities.
  • Credential linking never copies or grants organization memberships, seats, roles, or entitlements.
  • A target credential already bound to another identity requires the explicit, audited merge/split path in Admin identity merge/split: make credential linking genuinely reversible #6490.
  • Session and bearer-token caches are invalidated after bind, unlink, or promote.
  • Credential changes are fully audited without logging tokens or unnecessary personal data.

Acceptance criteria

  • A person can add and verify a personal recovery credential and subsequently sign in through it.
  • Both sides of an existing-account link prove control before identities are joined.
  • Removal refuses the primary/last usable credential until another is promoted.
  • Expiry, replay, TOCTOU, concurrent claim, and cross-account abuse tests pass.
  • Losing an organization membership removes organization access but leaves the verified personal sign-in and person-owned state intact.
  • The account UI and recovery messaging are covered by end-to-end tests.

Out of scope

  • Personal subscription purchase or fallback entitlements
  • Employment affiliation history
  • Fuzzy or automatic merging

Activity

  1. added this to the Evergreen milestone on Aug 24, 2026
  2. added
    enhancementNew feature or request
    websiteAny issues related to the website
    member-toolsAll member tools - profiles, dashboards, content management, working groups, events
    claude-triagingTriage routine is actively working on this issue (1-3 min)
    on Aug 24, 2026
  3. bokelley commented on Aug 24, 2026

    @bokelley
    ContributorAuthor

    Triage

    Classification: Feature request
    Bucket(s): security-sensitive, admin/ops tools (member-tools)
    Status: ready-for-human
    Milestone: Evergreen (already set)

    What the experts said:

    • security-reviewer-deep: Three blockers before design is final — (1) ADD must require step-up, not just session presence; (2) PUT /primary skips invalidateSessionsForUsers in current code, violating the stated invariant; (3) the 409 on cross-account claim enumerates alias membership. Significant concerns: MCP OAuth refresh tokens not covered by session invalidation; alias retirement needs per-user migration flag + dual-write strategy.
    • internal-tools-strategist: Real scaffolding exists in account-linking.ts; Admin identity merge/split: make credential linking genuinely reversible #6490 boundary already enforced in code. Alias retirement should be sequenced last as its own workstream. Proactive reminder needs a concrete surface decision before implementation.

    My take: The feature solves real pain and the code foundation is there. Three security design decisions need WG sign-off before work starts — particularly the step-up scope for ADD, which changes the security posture meaningfully.

    @bokelley, your call on each:

    Decision 1 — Step-up scope for ADD (highest risk):

    Option A — same step-up as REMOVE/PROMOTE (closes stolen-session backdoor):

    POST /api/me/recovery-credentials
    { "step_up_token": "<fresh WorkOS AuthKit challenge>",
      "target_email": "personal@example.com" }
    

    Option B — OTP to target email only, no re-auth challenge (matches most consumer recovery flows):

    POST /api/me/recovery-credentials
    { "verify_token": "<OTP sent to target email>",
      "target_email": "personal@example.com" }
    

    Option A is the safer default; B is acceptable only if a post-bind notification to the existing credential is mandatory.

    Decision 2 — Cross-account 409 shape (enumeration side-channel):

    - HTTP 409 { "error": "This email is already linked to another account" }
    + HTTP 200 { "message": "If this address is available, a verification link has been sent." }

    The current code path must become constant-time and non-disclosing.

    Decision 3 — MCP OAuth token scope on credential change:
    After bind or promote, should long-lived MCP OAuth refresh tokens issued to third-party agents be revoked or flagged for re-consent? Session-cookie invalidation does not reach these. (Check mcp_oauth_state_db.ts and migration 195/538.)


    Triaged by Claude Code. Session: https://claude.ai/code/session_01Fy9EXkXaFqCmfStgbn5wyq


    Generated by Claude Code

  4. added
    claude-triagedIssue has been triaged by the Claude Code triage routine. Remove to re-triage.
    needs-wg-reviewBlocked on a working-group decision — surface in WG meeting agendas
    and removed
    claude-triagingTriage routine is actively working on this issue (1-3 min)
    on Aug 24, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    claude-triagedIssue has been triaged by the Claude Code triage routine. Remove to re-triage.enhancementNew feature or requestmember-toolsAll member tools - profiles, dashboards, content management, working groups, eventsneeds-wg-reviewBlocked on a working-group decision — surface in WG meeting agendaswebsiteAny issues related to the website

    Type

    No type

    Projects

    No projects

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions