Airlock Laravel Package

Technical Evaluation

Architecture fit

• The artifact under evaluation is labeled laravel/airlock, but the repository (laravel/sanctum) and every changelog entry describe Laravel Sanctum. The v2.0.0 changelog states plainly: "Renamed package to Sanctum." airlock is the pre-2.0 name and has not been the shipping package name for many major versions. Any decision must be made against laravel/sanctum; laravel/airlock is a stale identifier, not a separate product.
• Sanctum is first-party Laravel infrastructure and occupies the default auth slot in modern Laravel skeletons. It is not an optional add-on but a table-stakes capability — consistent with the near-zero opportunity score (0.24). There is no differentiation to be won here; the goal is avoiding misconfiguration.
• Two distinct architectures ship in one package and must be chosen deliberately up front:
  • Stateful SPA mode — session cookie auth, /sanctum/csrf-cookie bootstrap, EnsureFrontendRequestsAreStateful middleware, and a stateful domain allowlist. Fits first-party SPAs on shared or subdomains.
  • API token mode — personal_access_tokens table, HasApiTokens trait, bearer tokens with abilities, optional expiry. Fits mobile clients, third-party integrations, service-to-service.
• Fits cleanly into an existing Laravel app's auth.php guard configuration and coexists with policy/gate-based authorization. It is deliberately not a full OAuth2 server — if scopes, grants, refresh tokens, or delegated third-party consent are required, Sanctum is the wrong tool.

Integration feasibility

• Install is composer require laravel/sanctum, publish config and migration, run migrations, add HasApiTokens to the authenticatable model, set SANCTUM_STATEFUL_DOMAINS and session domain, register the sanctum guard, and wire CORS supports_credentials. On Laravel 11+ this is largely covered by php artisan install:api.
• Version compatibility is well-bounded and current: v4.0.0 added Laravel 11, v4.0.8 added Laravel 12, v4.3.1 added Laravel 13; v4.0.5 and v4.2.1 added PHP 8.4 and 8.5 support respectively. v3.x is the Laravel 9/10 branch. Support for Laravel 12.45+'s HMAC password hash format landed in v4.2.2, with nullable-hash follow-ups in v4.2.3/4.2.4 — evidence the maintainers track upstream security changes promptly.
• Migration cost is low for greenfield; for existing apps the real work is token migration and frontend cookie/CORS re-plumbing, not the package itself.
• One genuine schema consideration: v4.2.0 "Add indexes to personal_access_tokens" and v3.0.1 changed the migration's primary identifier. On an upgraded install the published migration is already applied, so index additions must be backfilled via a new migration — otherwise token lookups degrade at scale.

Technical risk

• Identity/supply-chain risk (medium). The manifest name does not match the repository, and airlock is a plausible typosquat target on Packagist. Enforce that only laravel/sanctum is required in composer.json, and pin via lockfile.
• Token format churn (low-medium). v3.0.0 shortened tokens; v3.2.6 added prefix + checksum; v3.3.0 reverted prefixing by default. Any code or logging that pattern-matches token strings must not assume a format.
• Stateful-domain misconfiguration (high likelihood, low severity). Mismatched SANCTUM_STATEFUL_DOMAINS / SESSION_DOMAIN / CORS credentials yields 401/419 with opaque causes. v4.1.0 and v4.1.1 specifically addressed same-domain stateful detection and host/port inconsistency — a signal this is a recurring production failure.
• Plaintext token disclosure. Tokens are returned once at creation and stored hashed; loss is unrecoverable by design. This must be an explicit UX contract.
• last_used_at write amplification. Per-request updates to the token row are a hot-write pattern; v4.3.0 added optional last_used_at tracking configuration specifically to let teams disable it.
• Data quality flags to resolve before sign-off: Dependents: 0 is clearly wrong for a package bundled in the Laravel skeleton, and the 2026-07-21 last-release date is future-dated relative to review — treat both as metadata defects, not product signals.

Key questions

1. Which auth mode is required — stateful SPA cookie, API bearer tokens, or both? Who owns the frontend domain topology?
2. What is the token lifetime and ability model? Is expiry enforced, and is sanctum:prune-expired scheduled?
3. Are third-party or machine clients in scope, and do they need OAuth2 semantics that Sanctum does not provide?
4. Does any existing Passport or custom auth live in the codebase, and what is the guard decommission plan?
5. Is last_used_at tracking needed for security forensics, or should it be disabled for write throughput?
6. Who accepts the residual risk of an MIT, community-supported, no-SLA dependency sitting on the primary auth path?

Integration Approach

Stack fit

• Optimal fit for Laravel 11/12/13 on PHP 8.2+ with a first-party SPA or first-party API consumers. Good fit for mobile apps needing simple revocable bearer tokens.
• Poor fit where: OAuth2 authorization-code flows with third-party delegation are required (use Passport), or the API is consumed by non-Laravel services expecting standard OIDC discovery.
• Requires a relational database for personal_access_tokens; the session driver must be non-null and shared across app instances (Redis or database) for stateful mode to work behind a load balancer.

Migration path

1. Confirm no laravel/airlock reference survives in composer.json or lockfile; replace with laravel/sanctum at the version matching the Laravel major.
2. composer require laravel/sanctum; publish config and migration; run migrations.
3. Add a follow-up migration for the v4.2.0 indexes if the original migration was already applied.
4. Add HasApiTokens to the user model; register the sanctum guard in config/auth.php.
5. From Passport: issue a token-cutover plan (Passport tokens are not readable by Sanctum), dual-run guards behind a feature flag, then remove Passport's tables and middleware.
6. From custom session/JWT auth: keep the existing guard active and introduce sanctum as an additional guard so routes can be flipped incrementally.

Compatibility

• Stateful mode: cookie domain, SANCTUM_STATEFUL_DOMAINS, config/cors.php supports_credentials => true, and withCredentials on the HTTP client must all agree. Same-site deployments are the low-risk path; cross-site requires SameSite=None; Secure.
• Ability middleware (CheckAbilities, CheckForAnyAbility) and the v4.0.7 tokenCant() helper cover the authorization surface; route-model authorization should stay in policies, not abilities.
• Testing: Sanctum::actingAs($user, ['ability']) replaces hand-rolled auth fakes. Adoption requires updating existing feature-test helpers.

Sequencing

1. Dependency and version pin → 2. Config/migration publication + index backfill → 3. Guard and trait wiring → 4. Domain/CORS/session alignment with frontend → 5. Token issuance endpoint and ability taxonomy → 6. Expiry policy + prune schedule → 7. Middleware swap on a low-traffic route group → 8. Full cutover and legacy guard removal → 9. Runbook and alerting.

Do steps 3–6 before touching production traffic; step 4 is the highest-probability failure point and should be validated in a staging environment that mirrors the real cookie topology.

Operational Impact

Maintenance

• Very low ongoing effort, and unusually well-governed for an MIT package: Dependabot with a 5-day cooldown, auto-merge enabled, GitHub Actions pinned to commit SHAs (v4.3.3), and a published security policy. Cadence is frequent patch releases rather than rare big-bang majors, which favors continuous small upgrades over scheduled migrations.
• Cost drivers are the major-version Laravel alignment (Sanctum majors track Laravel majors) and the config-file formatting changes (v4.3.2 restyled config/sanctum.php to the Pint skeleton format) — cosmetic, but they create diff noise on upgrade.

Support

• MIT, no vendor SLA. Support is Laravel's official documentation plus community channels. Deprecation hygiene is present (MissingScopeException annotated deprecated in v3.2.6) but the changelog style is terse — many entries are single-line PR titles with no upgrade guidance. Budget engineering time to read diffs, not release notes.
• Security response depends on Laravel's core team and the repo's security policy; there is no CVE-response commitment to negotiate.

Scaling

• Stateless verification at request time (single indexed token lookup), so horizontal scaling is bounded by database read capacity, not the package. The v4.2.0 index additions materially improve lookup performance at high token counts.
• Primary scaling hazard is the per-request last_used_at write. Disable it via the v4.3.0 configuration option on high-throughput APIs; if retained, expect write pressure concentrated on a single hot table.
• Token table growth: expired tokens are only reclaimed if sanctum:prune-expired (expiry pruning added in v3.0.1) is actually scheduled. This must be a shipped, monitored cron job, not a documentation footnote.

Failure modes

• 401 on stateful SPA requests — domain allowlist or CORS credentials mismatch; the most common production break.
• 419 CSRF failures — missing /sanctum/csrf-cookie bootstrap or wrong session domain.
• Silent token loss — plaintext returned once; no recovery path, support burden falls on the team.
• Logout that does not revoke — v4.0.2 and v3.3.0 both shipped logout/device-revocation fixes; pin above these and add an integration test asserting revocation.
• Proxy/TLS-termination host mismatches — addressed in v4.1.1 but configuration-sensitive; validate behind the real edge layer.
• Unbounded table growth — prune job absent or failing silently.
• Index regression on upgraded installs — published migration predates v4.2.0 indexes; token lookups degrade as the table grows.

Ramp-up

• Low for any engineer already fluent in Laravel — Sanctum is the default in the framework and the documentation is canonical. Expect well under a day for a mid-level Laravel developer to be productive in token mode.
• The real learning curve is the SPA cookie/CORS/stateful-domain triangle, which is conceptual rather than API-related and is best transferred via a written runbook plus a staging environment matching production cookie topology. Reserve focused review time there, not on the package API.
• Recommended adoption gate: a single spike proving stateful auth end-to-end from the real frontend origin through the real edge/proxy, plus a load test on token-authenticated endpoints with last_used_at both enabled and disabled.