Skip to content

Guardian package: SSO and SCIM moved from Roster - #1

Merged
jayjfletcher merged 38 commits into
mainfrom
ring-master/2026-10-29-2038-guardian-package
Oct 30, 2026
Merged

jayjfletcher merged 38 commits into
mainfrom
ring-master/2026-10-29-2038-guardian-package

Conversation

@jayjfletcher

Copy link
Copy Markdown
Member

Risk: high

What changed

  • New package refactor-circus/guardian: auth and security for the suite. Its first features are SSO (OIDC, SAML, Entra ID) and SCIM 2.0 provisioning, moved out of Roster with their actions, data, events, models, policies, HTTP API, MCP tools (seven SSO, three SCIM) and routes.
  • Suite rules: Keystone is the only required suite package. Roster, Atrium, Keen and laravel/mcp are suggested. conflict on refactor-circus/atrium <0.1.0. Without Roster, Guardian boots inert and its about line says "Inactive: install refactor-circus/roster" (D-023).
  • Roster integration: Guardian talks to Roster through the auth-extension seams (Roster::requireSignIn(), externalSignInFor(), provisionedStatus(), Resources, PermissionCatalogue, MembershipSources) plus Roster's public domain API (D-024). RosterBoundaryTest denies Roster's internals.
  • Atrium UI: guardian.sso and guardian.scim tabs and the guardian.sso-identities aside are placed on Roster's screens from config/guardian.php atrium.screens. There is also a guardian.sso-connection screen. A WithoutAtrium suite and CI lane prove Guardian runs without Atrium.
  • Transition from Roster: a runtime Handover gate means no SSO/SCIM routes, morph aliases or table rename until Roster's SSO code is gone (D-022). guardian:upgrade-from-roster and the 2026_11_01_000000 migration rename the tables and merge the roster.sso.* / roster.scim.* grants. Stranded tables are reported, never enforced (D-029).
  • Changed from Roster (D-039): OIDC sign-in links an account by email, or creates one, only when the id_token's email_verified claim is true.

Why

SSO and SCIM are security features with their own lifecycle. Moving them into Guardian keeps Roster focused on users and organizations, and gives MFA, session policies and IP rules a home.

Look at

  • src/Upgrade/RosterUpgrade.php: the table rename and grant merge, plan-then-act.
  • src/Domains/Sso/Actions/SsoLoginAction.php: linkOrCreate() with the D-039 email check.
  • src/Domains/Sso/Concerns/JoinsOrganizations.php: writes Roster's membership models directly, because Roster has no public action that takes a membership source (recorded in standards-feedback.md).
  • src/Support/Integration.php: the Roster and Atrium detection that gates everything.
  • database/migrations/2026_11_01_000001_create_guardian_sso_tables.php: down() refuses to drop tables with rows unless forced (D-031, D-040).

Tested

  • composer test: PHPStan, Pint, 100% type coverage and 546 Pest tests pass.
  • Tested against the open PR branches of Roster (#13, which contains #11 and #12), Atrium #16 and Keen #8.
  • Moved tests come from Roster at a pinned SHA (tests/moved-tests.json). Comparisons with Roster's config and MCP tools use fixtures captured at that SHA.
  • Browser tests and the MySQL upgrade lane (--group=upgrade-mysql) run only in CI and have not run yet.

Risks

  • Guardian is new and depends on four open PRs. Merge Atrium #16, Keen #8 and Roster #11, #12 and #13 first, then tag Guardian.
  • Until Guardian is installed after Roster's removal, SSO enforcement fails open (Roster D-017). README and CHANGELOG say so in bold.
  • Recorded departures (build.md, standards-feedback.md):
    • the real-migration upgrade test inserts rows directly;
    • HandoverPending uses a stand-in check next to a Roster without SSO;
    • the upgrade calls Permissions::forgetCache();
    • read actions keep their event pairs (D-041).

Prerequisites and merge order

Guardian requires Refactor-Circus/Roster#11 (auth extension seams) and #13 (SSO and SCIM removed from Roster, which also contains #12), plus Refactor-Circus/Atrium#16 and Refactor-Circus/Keen#8, all merged before Guardian is tagged.

Decisions taken during the build

  • D-037: Support\Integration::rosterPresent() is public and marked @internal.
  • D-038: guardian.ui.enabled config key; the plugin registers through Keystone's registerAtriumPlugin().
  • D-039: OIDC requires email_verified (a change from Roster).
  • D-040: each create migration's down() checks only the tables it drops.
  • D-041: read actions keep their event pairs.

Remaining nits

  • SsoLoginRefused uses a public constructor rather than a forX() named constructor.
  • Bulk.php reads one config value without casting it.
  • SsoLoginFailedActionEvent is dispatched from the web controller.
  • Services\Sso is not final.

Spec: docs/agent/specs/2026-10-29-2038-guardian-package/

🤖 Generated with Claude Code

jayjfletcher and others added 30 commits October 30, 2026 00:53
…uite

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…uite

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…gration, models and create migrations (salvaged)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…gration, models and create migrations

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…d MCP (salvaged)

Move Roster's SSO domain source (actions, data, events, exceptions, HTTP,
MCP, resources, services, routes) into Guardian and register the seven
SSO tools on GuardianServer.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…d MCP

Scope SSO audit entries to their organization as Roster did (SsoAudit on
Keystone's AuditHooks), test the guardian.mcp web and local servers, move
Roster's connection-secret redaction case, apply Pint, tick group 3 and
record it in build.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…d MCP

Retry: every group 3 task was already committed; record the re-check in build.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…nd MCP

Fix the salvaged SCIM move: ScimException no longer redeclares Keystone's
protected $status as readonly, the SCIM domain names guardian.scim. as the
scim audit surface as Roster did, the ten-tool listing browses the catalog
through search_tools, and the scim.enabled route test refreshes name
lookups. Drop a test for an audit entry Roster never wrote.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…nd MCP

Retry: no code change. Record that the one failing test came from vendor Keen being linked to an unmerged Keen job branch; the link is restored to ../Keen as composer.local.lock records.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…llers, views)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…er application

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… script and browser workflow

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…uild

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…on Roster's tables and permissions at the pinned SHA

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…s with Roster's at the pinned SHA

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ecture/dependencies departure

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…nt fails open until Guardian is installed

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…uild

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…'s public API, publish views, record the provider deviation

- SsoLoginAction and ScimUsers join through Guardian's JoinsOrganizations,
  not Roster's internal ManagesMemberships trait
- ScimQuery keeps its own case-insensitive eq instead of Roster's
  Support\CaseInsensitive
- SsoIdentityResource nests Guardian's UserSummaryResource, held equal to
  Roster's by a test
- RosterBoundaryTest denies Roster domain Concerns and Resources and every
  Support class but Users, Statuses, UserKey and Tables
- views publish under guardian and guardian-views
- standards-feedback rows for the booting() domain provider registration
  and the two departures the boundary fix brings

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…'s rollback check to its own tables

D-040: the sso migration checks only guardian_sso_*, the scim migration
only guardian_scim_*, so SCIM rows no longer block a targeted SSO rollback.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…r OIDC link and just-in-time sign-in

D-039: Sso::claims() sets IdentityClaims::emailVerified from the id_token's
email_verified claim (only a literal true) for OIDC connections; SAML and
Entra ID leave it true. SsoLoginAction refuses link-by-email and JIT
creation with reason unverified_email and its own lang string; identities
already linked still sign in. The moved OidcFlowTest now sends
email_verified true. README, the Boost skill and CHANGELOG record the
change from Roster.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…lback test to D-040

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…uild

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
jayjfletcher and others added 8 commits October 30, 2026 04:34
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…oster

The workbench User used Roster's HasRoster unconditionally, so package:discover
fatalled once the job uninstalled Roster. UsesRoster wraps it when Roster exists.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- PermissionsTest compares forward-slash paths, so Windows skips src/Upgrade.
- The test job restores the committed composer.json after the matrix pins,
  which PackageWiringTest reads.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The MCP tool snapshots carry the title annotation laravel/mcp 1.1 added, so
the prefer-lowest jobs failed on 1.0.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- CHANGELOG: the Unreleased notes become v0.1.0 (2026-10-30).
- Suite packages are required as ^0.1 instead of dev-main; PackageWiringTest
  expects them.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@jayjfletcher
jayjfletcher merged commit ee8f84f into main Oct 30, 2026
8 checks passed
@jayjfletcher
jayjfletcher deleted the ring-master/2026-10-29-2038-guardian-package branch November 11, 2026 04:13
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant