Clearance Laravel Package

Product Decisions This Supports

• Whether access control is a product artifact or an implementation detail. Clearance turns authorization config into a committed, diffable clearance.lock.json. That's a decision to make permission changes reviewable at PR time rather than discoverable in production incidents.
• Build vs. buy for authorization guardrails. If engineering has proposed a bespoke "grep the policies" CI script or an internal permissions-diff tool, this package plus a baseline ref is the off-the-shelf version. Compare against policy engines (Oso, Cerbos, SpiceDB, Aserto) — those give runtime enforcement; this gives review evidence.
• Risk acceptance on the v1.0.0 bypass. v1.0.1 discloses that a PR could widen access, rewrite its own lock, and pass the check. Any team that adopted v1.0.0 has been operating with a false sense of assurance. This is a "who is affected and do we re-audit" decision, not a changelog footnote.
• Rollout scoping. Upgrading alone does not close the bypass — it requires a workflow change (fetch-depth: 0, --baseline=origin/main), CODEOWNERS protection on the lock/workflow/verification config, and required code-owner review. Budget this as a ~1-sprint platform/security workstream, not a dependency bump.
• Policy definition. The release makes an explicit rule enforceable: any change expanding clearance requires approval from outside the PR's own lock. That's a written policy you can now attach a control to.
• Release-gating standards for internal tooling. Exit code 3 for missing refs and invalid baselines is fail-closed behavior. Decide the org convention: alert and block, never retry-and-ignore.
• Monorepo topology. Regression coverage for monorepo paths supports deciding how permission config is partitioned across services ahead of a split.

When to Consider This Package

Adopt when:

• You're on Laravel/PHP with authorization expressed as code (Gates/Policies) that changes often and spans multiple teams.
• You already have PR CI, branch protection, and CODEOWNERS — the security value is entirely load-bearing on these. Without required code-owner review, the v1.0.1 mitigation is close to inert.
• You need an audit trail for access changes (SOC 2 / ISO access-change-control evidence) but not a full IGA or authorization SaaS.
• Permission drift in a monorepo is a demonstrated failure mode, not a hypothetical.
• You can absorb a merge-conflict-prone lockfile with an agreed regenerate-on-rebase convention.

Look elsewhere or defer when:

• Permission state lives in a database or admin UI rather than in code — the lockfile model doesn't map.
• You need runtime policy decisions, dynamic attributes (ABAC/ReBAC), central audit logging, or denied-request telemetry. Clearance is a CI-time gate, not a policy enforcement point.
• Your CI can't fetch full history (fork PRs, restricted refs). Baseline checks then add a new failure mode rather than removing one.
• Single-team, pre-compliance, high-velocity product — the workflow overhead exceeds the risk being managed.
• You're still on v1.0.0 and can't patch CI this cycle: recognize you're knowingly running a bypassable gate.

How to Pitch It (Stakeholders)

Executives. "Today an access-widening change gets the same review weight as a typo fix. Clearance makes permission changes an explicit, reviewed artifact and blocks PRs that try to approve their own expansion. Investment is roughly a sprint of CI and CODEOWNERS work; the return is a control that maps directly to access-change-control requirements in our compliance narrative." Flag honestly that v1.0.0 shipped with a self-approval bypass — the recommended adoption path is v1.0.1 with --baseline plus code-owner review, not "upgrade and move on."

Engineering. "Upgrade to v1.0.1, then add php artisan clearance:check --baseline=origin/main to PR CI with fetch-depth: 0 on actions/checkout. Protect clearance.lock.json, the workflow, and verification config with CODEOWNERS and required code-owner review. Missing refs and invalid baselines exit 3 — treat as fail-closed and page on it rather than retry. Warden and Advisor integrations still use checkout-lock semantics, so run the Git-baseline command alongside them, not instead of them."

Security. Frame the threat model precisely: pre-1.0.1, a pull request could widen access, update or approve its own lock, and pass clearance:check. Post-fix, approvals committed in the PR's lock cannot override the trusted baseline; checkout lock changes surface as review warnings with baseline_ref and lock_changed JSON fields. Regression coverage now includes self-approved widening, unchanged locks, invalid baselines, monorepo paths, and symlink redirection. Validate the control by attempting a deliberately self-approving PR after rollout — the gate is only proven when it fails.