[bordoni]

Summary

Replaces the redirect-to-WorkOS login flow with a WordPress-hosted React login shell backed by a full public REST surface. Adds Login Profiles so each entry point can offer its own set of auth methods, pin an organization server-side, and enforce an MFA policy.

• Custom AuthKit: React shell mounts on wp-login.php (takeover for action=login only — logout/register/lostpassword/confirmaction/postpass pass through), on the [workos_login_v2] shortcode, on a workos/login-form block, and on a dedicated /workos/login/{profile} rewrite. All WorkOS calls stay server-side via wp_remote_request + the admin API key. No WorkOS PHP SDK.
• Login Profiles: new non-public CPT + admin React editor (WorkOS → Login Profiles). Each profile picks enabled methods (password, magic code, social OAuth for Google/Microsoft/GitHub/Apple, passkey), pins an organization, toggles signup/invitation/password-reset, sets MFA enforce + factor allowlist, and carries branding (logo + primary color + heading/subheading). The reserved default profile drives wp-login.php takeover.
• Public REST surface at /wp-json/workos/v1/auth/*: password authenticate + reset, magic send/verify, signup create/verify, invitation lookup/accept, OAuth authorize-url, MFA challenge/verify/enroll/list/delete, session nonce/refresh/logout. Each mutation verifies a profile-scoped nonce, applies per-IP + per-email rate limits, and forwards the browser's WorkOS Radar action token to server-side calls.
• Profile routing rules: ordered redirect_to glob / referrer_host / user_role matchers pick which profile applies to a request when no explicit slug is passed. First match wins, falls back to default.
• Legacy AuthKit-redirect mode stays selectable per profile so SSO (SAML/OIDC) keeps working until the React shell gains a dedicated SSO launcher in 1.1.

TypeScript migration

All browser code is now TypeScript + TSX. @wordpress/scripts v30 transpiles .ts/.tsx natively via its default babel preset; tsc --noEmit (exposed as bun run lint:ts) provides strict type checking. Shared interfaces in src/js/authkit/types.ts mirror Profile::to_array() on the PHP side.

Security

Ran /security-review end-to-end on the branch. Surfaced four findings, all fixed in 82bbb63:

#	Severity	Fix
1	HIGH — JWT signature-verification bypass in TokenAuth lazy-refresh	Lazy-refresh removed; clients use /session/refresh (WP-cookie-authenticated)
2	HIGH — Invitation acceptance allowed account takeover	Switched to atomic grant_type=urn:workos:oauth:grant-type:invitation_token call; caller can no longer substitute email or force email_verified=true
3	HIGH — IDOR on MFA factor delete	Ownership check against list_auth_factors before delete; 404 on mismatch
4	MEDIUM — Profile mfa.enforce=always + factor allowlist unenforced	LoginCompleter denies single-step success on enforce=always profiles and rejects pending factors whose type is not in the profile's allowlist

Scope

• 62 files changed (+11,820 / −100)
• 9 commits on feature/custom-authkit
• 142 new WPUnit tests; 356 tests green (was 214 on main)
• bun run lint:ts clean under strict mode; bun run build emits authkit (17.5 KiB) + admin-profiles (7.3 KiB)

Documentation

• CHANGELOG.md — full 1.0.0 feature breakdown + Security section with the four review findings and their fixes
• README.md — expanded Features, rewritten Authentication section, new Login Profiles section, updated Architecture tree, bun + lint:ts in Development
• readme.txt — user-facing Custom AuthKit section, new FAQ entries, rewritten Changelog
• AGENTS.md — file inventory updated for AuthKit + Admin\LoginProfiles + REST\Auth trees, new TypeScript Browser section, full WPUnit list

Release target

Blocks the 1.0.0 WordPress.org launch (originally 2026-04-14). Memory updated. Out of scope for 1.0.0: SSO launcher in the React shell (use authkit_redirect mode), per-profile rich theme editor.

Test plan

Automated (all green on this branch):

• slic run wpunit — 356 / 356 pass
• /security-review on branch — 4 findings fixed, confirmed via new regression tests
• bun run lint:ts — clean under strict mode
• bun run build — authkit (17.5 KiB) + admin-profiles (7.3 KiB) bundles build clean

Manual E2E (pending reviewer verification on a live slic WP environment):

• wp-login.php renders the React shell; password login succeeds
• Magic-code login succeeds (WorkOS test-mode email)
• Google OAuth button redirects out, returns to /workos/callback, React shows success
• Signup → email-verification code → sign in
• Invitation email link → accept → signed in (verify the invitation is consumed in the WorkOS dashboard)
• TOTP enrollment: QR scan with an authenticator app; challenge verifies
• Logout revokes the WorkOS session (confirm via WorkOS dashboard sessions tab)
• Switching default profile mode to authkit_redirect restores the legacy hosted AuthKit flow
• EntitlementGate: user not in profile org gets a clean rejection screen
• Scripted 20 rapid /magic/send calls → 429 with Retry-After
• Test each of the four security-fix regressions manually: forged unsigned JWT → rejected; invitation accept with mismatched email → rejected; delete-other-users-factor → 404; mfa.enforce=always user without factors → rejected

[mauteri]

static function (): void {

[mauteri]

Maybe something like this (some Claude help)

/**
 * Validate and sanitize a CSS hex color for safe emission inside a <style> block.
 *
 * Returns the normalized color string (e.g. "#abc123") on success, or null if
 * the input is not a valid CSS hex color.
 */
private function css_hex_color( mixed $value ): ?string {
	$value = (string) $value;

	// Accept only the four valid CSS hex color lengths:
	//   #RGB       (3 digits, shorthand)
	//   #RGBA      (4 digits, shorthand with alpha)
	//   #RRGGBB    (6 digits, standard)
	//   #RRGGBBAA  (8 digits, standard with alpha)
	// Explicitly rejects 5 and 7 digit values, which are not valid CSS and
	// would be silently dropped by the browser. The alternation is used
	// instead of {3,8} so that the length check is exact, not a range.
	$pattern = '/^#(?:[0-9a-fA-F]{3,4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/';

	if ( ! preg_match( $pattern, $value ) ) {
		return null;
	}

	// Defense-in-depth: rebuild the value from an allowlist of hex characters
	// before returning. The regex above already guarantees this is safe, but
	// this renderer emits directly into a <style> context where esc_attr is
	// semantically wrong and there is no WordPress-native CSS escaper. If the
	// regex is ever loosened or bypassed by a future call site, the allowlist
	// strip still prevents a semicolon, closing brace, or </style> sequence
	// from reaching the output.
	return '#' . preg_replace( '/[^0-9a-fA-F]/', '', substr( $value, 1 ) );
}

/**
 * Render the inline <style> block that applies branding to the AuthKit root.
 *
 * Returns an empty string when no branding rules are applicable.
 */
private function render_branding_style( array $branding ): string {
	$rules = [];

	$primary = $this->css_hex_color( $branding['primary_color'] ?? '' );
	if ( null !== $primary ) {
		$rules[] = '--wa-primary: ' . $primary . ';';
	}

	// Future branding variables (secondary, accent, background, etc.) should
	// be added here using the same css_hex_color() helper so that validation
	// and escaping stay centralized.

	if ( empty( $rules ) ) {
		return '';
	}

	return '<style>#workos-authkit-root{' . implode( ' ', $rules ) . '}</style>';
}

[mauteri]

Would add to top of file use WorkOS\Auth\AuthKit\Nonce;

[mauteri]

Remove seemingly random line break.

[mauteri]

Claude's Code Review: integration-workos PR #1 — WorkOS AuthKit takeover

Summary

This PR replaces the hosted AuthKit page with a WordPress-native React shell and a large REST surface that proxies WorkOS: email/password, magic code, OAuth/SSO, MFA (TOTP/SMS), invitations, signup, password reset, session introspection, plus a CPT-backed Login Profile model with admin UI, routing rules, branding, and wp-login.php takeover.

The architecture is clean: an abstract BaseEndpoint centralizes profile resolution, nonce verification, rate limiting, and redirect sanitization; Profile is a validated immutable value object; Nonce is profile-scoped; LoginCompleter enforces a factor allowlist and MFA_ENFORCE_ALWAYS; Renderer does defense-in-depth regex validation before emitting inline CSS; Radar caps forwarded header size. Security was clearly a first-class concern — rate limits, CSRF nonces, a timing-floor on password/reset_start, enumeration-safe error messages, and atomic invitation acceptance are all present.

That said, there is one critical security bug in the API client (unencoded path segments enabling URL manipulation on identifier inputs), two high-severity issues that either break a security control behind proxies or lose profile context during OAuth callback, and a handful of medium/minor items worth addressing before merge.

Critical Issues

#	File	Line	Issue	Severity
1	src/WorkOS/Api/Client.php	list_auth_factors, get_invitation_by_token, delete_auth_factor, and other /{$id} interpolations	User- and token-supplied identifiers are interpolated into WorkOS API URL paths with string concatenation and no rawurlencode(). A user_id, factor_id, or invitation token containing .., /, ?, #, or spaces lets a caller pivot the request to a different WorkOS endpoint (e.g. GET /user_management/users/..%2Fauth_factors%2F<id> style path traversal, or ?foo=bar# query smuggling). The Invitation GET route regex [A-Za-z0-9_\-]+ defends one call site by coincidence; the MFA and signup paths have no such guard. Wrap every interpolated segment in rawurlencode(...) at the point of URL construction.	Critical
2	src/WorkOS/Auth/AuthKit/RateLimiter.php	client_ip()	The docstring says "Respects the standard WP proxy hint hierarchy" but the implementation only reads REMOTE_ADDR. Behind any reverse proxy (which is the typical production topology), every request will hash to the load-balancer's IP and the per-IP buckets (signup, password reset start, magic code send, MFA verify) collapse into a single shared counter that trips globally on the first attacker. Either implement the hierarchy (checking HTTP_X_FORWARDED_FOR/HTTP_X_REAL_IP behind a configurable trusted-proxy allowlist) or correct the docstring and add a README note — but the current mismatch between doc and behavior will silently ship a broken control.	High
3	src/WorkOS/Auth/Login.php (handle_callback)	state parsing	handle_callback splits the OAuth state into [nonce, redirect_to, profile_slug] via `explode('	', $state, 3), verifies the nonce against the slug, then discards the slug — downstream session creation and post-login redirect behavior run against the global default, not the profile that initiated the flow. The user sees profile A on the login page, clicks "Sign in with Google", and lands back under profile B's rules (redirects, branding on error, factor allowlist). Thread the resolved profile through to LoginCompleter. Also:

Suggestions

Security

#	File	Line	Suggestion
S1	src/WorkOS/REST/Auth/Mfa.php	verify()	The verify path is rate-limited per-IP at 10/min but has no per-pending-token bucket. An attacker with a valid pending-auth token can brute-force TOTP codes from a botnet (rotating IPs) at essentially unbounded rate. Add a per-pending-token counter (e.g. 5 attempts before the token is burned server-side) that's consumed atomically with the verify call.
S2	src/WorkOS/REST/Auth/MagicCode.php	send()	Password::reset_start() uses hrtime() + usleep_until_floor() to mask whether an email exists. MagicCode::send() takes the same email/no-email branch but ships without the floor, so the response-time side-channel that reset_start closes is reopened here. Apply the same RESPONSE_TIME_FLOOR_US pattern.
S3	src/WorkOS/REST/Auth/Signup.php	create()	No server-side password strength validation. Add a minimum-length check (12+ chars is reasonable) and reject obvious weak patterns before sending to WorkOS — the React shell's client-side check is not a security control.
S4	src/WorkOS/User.php	META_ACCESS_TOKEN, META_REFRESH_TOKEN	Access and refresh tokens are stored in usermeta as plaintext. usermeta is world-readable to anyone with a SQL-capable plugin compromise or a database backup dump. Consider encrypting at rest with SECURE_AUTH_KEY (or a dedicated WorkOS key), or document the threat model explicitly in the constant's docblock.
S5	src/WorkOS/Auth/Login.php	nonce verify	Legacy fallback wp_verify_nonce( $nonce, 'workos_auth' ) defeats the profile scoping — a nonce minted under profile A is accepted for a callback under profile B if the fallback path is taken. If this is transition-only, add a date/version comment and a deletion ticket. If it's permanent, drop it now and force a single path.
S6	src/WorkOS/REST/Auth/BaseEndpoint.php	sanitize_redirect()	Good use of wp_validate_redirect. Consider also rejecting redirects whose scheme is not http/https (e.g. javascript:, data:) as a belt-and-braces step — wp_validate_redirect generally handles this but the behavior has shifted across WP versions.

Correctness

#	File	Line	Suggestion
C1	src/WorkOS/Auth/AuthKit/LoginCompleter.php	wp_set_auth_cookie($user_id, true)	"Remember me" is hardcoded to true, which extends the session cookie to 14 days regardless of user preference. Plumb the user's actual "remember me" selection from the React shell through the REST payload.
C2	src/WorkOS/Admin/LoginProfiles/RestApi.php	update	array_replace_recursive is used for partial updates. For lists (e.g. methods, mfa.allowed_factors) this merges by numeric index rather than replacing — a PATCH that sends methods: ["password"] over an existing ["password","magic_code","sso"] returns ["password","magic_code","sso"] instead of ["password"]. Either document that lists are full-replace and special-case them, or switch to a field-by-field merge.
C3	src/WorkOS/Auth/AuthKit/ProfileRouter.php	path_matches_glob	The glob replaces \* with .* which is greedy and unanchored-internally. The pattern /wp-admin/* matches /wp-admin/edit.php as expected, but /admin/* also matches /public/admin/anything. Anchor more tightly (you already wrap in ^…$, which is correct), but note that * matching / may surprise admins who expect shell-style segment globs. Document the semantics in the admin UI helper text.
C4	src/WorkOS/REST/Auth/Signup.php	create() response	On success the endpoint calls send_verification_email but does not surface a failure from that call. If the email fails to send, the shell advances to the verify step with no code on the way. Either propagate the failure or schedule a retry.

Maintainability / Style

#	File	Line	Suggestion
M1	src/WorkOS/REST/Auth/Session.php	extract_exp	The intentional "decode without verifying signature" is correct for UI timing, but the method name doesn't convey that. Rename to extract_exp_unverified (or add a big warning block at the top of the method) so it can't be mistaken for an authorization primitive by a later contributor.
M2	src/WorkOS/REST/Auth/BaseEndpoint.php	constants	RATE_LIMIT_* constants are duplicated across Signup/Password/Mfa/MagicCode/OAuth endpoints with slightly different values. Consider hoisting them into a single config array on BaseEndpoint so a policy change is one edit.
M3	src/WorkOS/Auth/AuthKit/Renderer.php	render_full_page	echo $mount with a phpcs:ignore. The comment justifying the ignore is accurate, but the escape contract now lives implicitly across two methods. Consider a SafeHtml wrapper class (even a single-property struct) returned from render_mount() so the type system — not a comment — enforces "this has been escaped".
M4	src/WorkOS/Auth/AuthKit/Profile.php	immutability	to_array() returns the internal branding array by value, which is fine for scalars but methods / mfa.allowed_factors are lists; callers that mutate the returned array in place will not affect the profile, but readers don't know that without reading source. Worth a brief @return docblock note.
M5	src/WorkOS/Auth/AuthKit/ProfileRepository.php	CPT	The default profile is guarded against deletion at the repo layer. Also add a capability check at the admin delete endpoint to reject the request before it reaches the repo, so the admin UI can show a clean 403 rather than a generic error.

What Looks Good

• Layered security-by-default. Every state-changing REST endpoint goes through BaseEndpoint::resolve_profile → verify_nonce → rate_limit in the same order. It's easy to audit and hard to skip a step by accident.
• Profile-scoped nonces. workos_authkit_<slug> actions mean a nonce minted for profile A cannot be replayed against profile B, which is the right move for multi-tenant login surfaces on the same site.
• Timing-safe password/reset_start. The hrtime() + usleep_until_floor() pattern is the correct mitigation for email-enumeration via response time, and the 900ms floor is a reasonable balance between UX and side-channel coverage.
• Defense-in-depth in Renderer::branding_style_tag. Re-validating the primary_color hex regex at the emission site (where esc_attr is semantically wrong for CSS context) is exactly the right call — this is the kind of layered check that stops future refactors from silently reintroducing CSS injection.
• Atomic invitation acceptance. The authenticate_with_invitation atomic flow, with a comment calling out the account-takeover vuln in the legacy two-call path, is a great example of "fix the class of bug, don't just patch the instance" — plus the comment helps a future reader understand why the atomic path exists.
• Radar::extract_from_request header size cap. 2 KB upper bound on a forwarded fingerprint header is a small, cheap mitigation that prevents header-stuffing attacks from amplifying every outbound WorkOS call.
• Profile as an immutable value object with strict allowlist validation on construction. Modeling the config as a parsed-once, validated value rather than repeatedly get_option()'d arrays eliminates a whole class of "what if the admin wrote garbage" bugs at the boundaries.
• Escape hatches on LoginTakeover. Preserving ?workos=0, ?fallback=1, ?loggedout=1 means a misconfigured WorkOS tenant doesn't brick admin access — exactly the kind of operational foresight that prevents 3 a.m. pages.
• wp-login.php rendering without wp_head/wp_footer. The comment explaining why (no admin/theme chrome bleed) saves the next maintainer a head-scratch.

Verdict

Request changes. The critical rawurlencode omission in Api\Client is a must-fix before merge — it affects identifier paths that flow from user input through MFA/invitation/signup. The two high-severity findings (proxy-aware rate limiting, profile-slug threading through OAuth callback) are also ship-blockers in my view: both silently break intended security behavior in production topologies without any log or error to notice. The medium/minor items in the Suggestions section are worth a follow-up pass but don't need to gate this merge once the critical/high items are addressed.

Overall the PR's security posture is well above the WordPress-plugin average — the abstractions are coherent, the docblocks call out trade-offs honestly, and the code shows evidence of threat-model thinking (timing, enumeration, CSRF scoping, atomic operations). Fix the three items above and this is ready to go.