Grant Laravel Package

Technical Evaluation

Architecture fit shipfastlabs/grant is a Laravel authorization package that hooks into the framework's Gate abstraction (the release notes reference a "stale Gate memo," which implies it registers or memoizes abilities through Laravel's Gate). The move to "model-backed writes" indicates permissions/grants are persisted via Eloquent rather than being defined purely in code or config, making it a fit for applications that need runtime-editable authorization (admin UI, tenant-scoped roles) layered on top of Laravel's native Gate::allows / policy checks. It is not a standalone service and assumes an Eloquent-backed Laravel app.

Integration feasibility Feasible for a greenfield Laravel service: composer install, publish config (PR #2 explicitly isolates "published files," so config/asset publishing exists), run migrations for the model-backed store, and continue calling Gate as normal. The package appears to be a thin layer rather than a framework replacement, which keeps blast radius small. v0.0.1 is the first tagged release, so integration cost is low but verification cost is high.

Technical risk

• Maturity: 0.0.1 carries no backwards-compatibility guarantee; the API may change without a major bump. Treat as experimental.
• First-release audit fixes: PR #1 addresses audit findings (stale memoization in workers, write path, config validation). That these were needed in the initial tag is a signal the codebase is young, not that it is unsafe — but it means we should re-audit rather than inherit trust.
• Worker/Octane staleness is security-relevant: a memoized Gate in a long-running process can serve stale allow/deny decisions after a permission change. This is the single highest-risk behavior for us.
• Bus factor: single contributor, single PR author, pre-1.0.

Key questions

1. Which Laravel and PHP versions are supported, and what is the declared composer.json constraint?
2. Does it replace, wrap, or supplement Gate/Policies — and can it coexist with existing policy classes?
3. What is the schema for model-backed grants (tables, indexes, tenant keys), and how are migrations published?
4. How is cross-process cache invalidation handled for queue workers and Octane — TTL, event-based, or none?
5. What is the read path cost per Gate::allows call (query per check vs. cached)?
6. License, test coverage, static analysis level, and security disclosure process.
7. Is there a documented migration path from spatie/laravel-permission or hand-rolled role tables?

Integration Approach

Stack fit Assumes Laravel with Eloquent and the default Gate/AuthServiceProvider wiring. Natural fit where authorization is already expressed as abilities and policies; poor fit for apps using a non-Eloquent or external authorization service.

Migration path Greenfield or additive only. There is no evidence of an importer or compatibility shim for existing role/permission packages, so assume a parallel-run period: keep current authorization as source of truth, mirror into grant, and diff decisions before cutover. Avoid a big-bang migration on a 0.0.x dependency.

Compatibility Pin the exact version (0.0.1) rather than a caret range, and vendor-lock via composer.lock. Because config is publishable, treat the published config file as deployable state: diff it on every upgrade and validate on boot (PR #1 added config validation, which we should exercise deliberately with a bad config in CI).

Sequencing

1. Spike (1 sprint): integrate in a non-production environment; confirm supported Laravel/PHP versions and schema.
2. Behavioral verification: write tests asserting permission changes are observed in (a) HTTP requests, (b) queue workers, (c) Octane workers, (d) scheduled commands. Specifically test revocation — the stale-memo class of bug.
3. Abstraction guard: route application code through our own authorization facade/adapter so the package can be swapped or forked without touching call sites.
4. Pilot: one low-risk, non-financial, non-PII-gating surface. Do not gate destructive or privileged operations in the pilot.
5. Production: only after a documented failure-mode runbook exists for permission propagation lag.

Operational Impact

Maintenance Pre-1.0 with a single maintainer means we own upgrade risk. Budget recurring effort per Laravel major upgrade and per package minor bump. Maintain an internal fork/patched-copy contingency; the package is small enough that forking is a credible fallback.

Support No maturity signal in the release notes beyond the changelog — no docs, no support policy, no LTS statement. Assume self-support. Assign one engineer as internal owner and record answers to the key questions above in our own docs.

Scaling Model-backed writes shift load to the database. The scaling question is the read path: if each Gate check queries, hot endpoints will multiply DB round-trips. Require a caching layer or per-request memo with a short, explicit TTL, and load-test a permission-heavy endpoint before broad rollout. For multi-tenant deployments, confirm tenant scoping is enforced in the query, not in application code.

Failure modes

• Stale authorization in long-running processes (queue workers, Octane): permission revoked in DB but still allowed in a warm worker. Highest severity; needs explicit invalidation and a documented max-staleness bound.
• Fail-open vs. fail-closed: if the grant store is unreachable, does Gate deny or fall through? Must be fail-closed for privileged actions.
• Config drift: published config diverging between environments; boot-time validation failure taking down the app if config is malformed.
• Publish collision: PR #2 hints published files were leaking across parallel test processes — verify our CI isolates published artifacts per process to avoid cross-test contamination.
• Migration collision with existing auth tables on upgrade.

Ramp-up Low for any Laravel developer — the mental model is standard Gate usage, and the package is additive. Moderate for whoever owns the invalidation semantics, since that requires understanding worker lifetimes and cache behavior. Plan a short internal walkthrough plus a written runbook for "permission changed but not taking effect."