Supabase Auth Bundle Laravel Package

Technical Evaluation

Package under review: kyzegs/supabase-auth-bundle — a Laravel/PHP package for integrating Supabase Auth (GoTrue) into a Laravel application. Assessment is based on the package's stated scope, the v1.0.0 → v1.0.1 release signal, and standard Laravel package conventions; no source review, changelog detail, or prior assessment exists.

Architecture fit

• Fits the common pattern of a Laravel app using Supabase as the identity provider while keeping Eloquent as the system of record. Expected shape: a service provider with auto-discovery, a publishable config file, a custom Auth guard/middleware that validates Supabase JWTs, and an optional user-provisioning hook to map Supabase users onto a local users table.
• Value is highest where teams want Supabase Auth without adopting the Supabase JS SDK or a full BaaS rewrite — i.e. Laravel remains the API/rendering layer, Supabase is auth-only.
• Architectural concern: it introduces a second source of truth for identity. Any design where local user records, roles, or tenancy are derived from Supabase must define sync semantics (create-on-first-login vs. webhook vs. batch) up front, or the integration will accrete ad-hoc reconciliation code.

Integration feasibility

• Low ceiling on effort: composer require, publish config, set Supabase URL + keys, register the guard. A competent Laravel team can produce a working spike in under a day.
• Real unknowns that gate feasibility: supported Laravel/PHP version matrix, whether JWT verification is local (JWKS/shared secret) or a network call to Supabase per request, whether refresh-token handling is included or delegated, and whether the package touches authorization (RLS passthrough) or only authentication.
• The v1.0.1 release carries no substantive changelog — only a GitHub compare link. That is not a blocking issue, but it means this release provides zero evidence of stability, roadmap direction, or defect triage. Treat v1.0.1 as functionally equivalent to v1.0.0 until the diff is reviewed.

Technical risk

• Bus factor / maturity (high): single-maintainer, pre-1.x-history package at v1.0.1. No security policy, no published release narrative, no prior assessment in our records.
• Opaque change management (medium-high): an empty release body for a patch is a yellow flag. It prevents us from distinguishing a docs typo fix from a silent JWT-validation change. Pin exact versions and review the compare diff before bumping.
• Credential handling (high): the package will require a Supabase anon key and either a JWT secret or JWKS endpoint. Misconfiguration or secret leakage here is an auth-bypass class of failure, not a bug.
• Supabase platform drift (medium): Supabase has been moving toward asymmetric JWT signing keys / JWKS and away from the legacy shared JWT secret. A package that assumes the legacy shared secret will break at key rotation. This is the single highest-value question to resolve before commitment.
• Abstraction leakage (medium): auth packages that expose Supabase-specific claims tend to spread supabase_id and raw JWT payloads through controllers, policies, and gates, making later replacement expensive.

Key questions for the maintainer / spike

1. Supported Laravel and PHP version matrix? Explicitly tested on 10/11/12?
2. Is JWT verification performed locally (and against JWKS or a static secret), or via a Supabase round-trip per request?
3. How are token refresh, session revocation, and sign-out handled server-side?
4. Does it integrate as a native Auth guard (so auth()->user(), policies, and @can work unchanged), or is it a parallel auth path?
5. What is the user-provisioning story — create-on-login, events, webhooks, or manual?
6. Does it support Supabase's asymmetric signing keys / JWKS rotation, and what happens on rotation?
7. What is the actual diff in v1.0.1? Any change to token validation, config keys, or dependencies?
8. License, security disclosure path, and CI/test coverage?

Integration Approach

Stack fit

• Assumes a conventional Laravel app: Eloquent user model, session or token guard, middleware-driven route protection, optional Inertia/Livewire or SPA front end. Fits cleanly if Supabase is used only for identity; fits poorly if the team also expects Supabase RLS to be the authorization boundary for direct-from-client database access, since Laravel-side guards and Postgres RLS then become two authorization systems to keep aligned.
• Best fit: greenfield Laravel API or app where auth is the first Supabase touchpoint and there is no entrenched identity model to migrate.

Migration path

• Recommended as an additive auth provider, not a replacement. Register the Supabase guard alongside existing web/api guards so routes can be moved over incrementally and rolled back per-route.
• For existing apps with local password auth: run both paths behind a feature flag, mirror Supabase users into the local users table with an explicit supabase_id column, and defer password-migration decisions (forced reset vs. lazy migration on next login) until the spike proves the guard works.
• Do not migrate privileged/admin flows first. Start with a low-blast-radius surface (e.g. a read-only internal dashboard) to validate token refresh and revocation behaviour under real session churn.

Compatibility

• Must verify against the app's exact Laravel and PHP versions before committing; package constraint conflicts with laravel/framework, firebase/php-jwt, or lcobucci/jwt are the likeliest install-time blockers.
• Front-end compatibility matters: if the SPA uses supabase-js for login and passes the access token to Laravel, confirm the package accepts that token format and validates aud/iss/exp correctly.
• Pin the dependency ("kyzegs/supabase-auth-bundle": "1.0.1") with a committed composer.lock; avoid ^1.0 until release notes become substantive.

Sequencing

1. Diff review (0.5 day): read the v1.0.0...v1.0.1 compare directly; confirm whether the patch touches token validation, config keys, or composer constraints.
2. Timeboxed spike (1–3 days): install in a scratch Laravel app matching production versions; verify guard registration, login, token refresh, sign-out, revocation, and key rotation against asymmetric keys if available.
3. Abstraction pass: wrap the package behind a thin internal IdentityProvider/guard contract and a single SupabaseUserResolver, so no controller or policy references package classes directly.
4. Staging rollout on one non-critical auth surface with a fallback guard enabled.
5. Production rollout surface-by-surface; keep the legacy guard live for at least one full token-lifetime cycle.
6. Post-rollout hardening: monitoring, key-rotation runbook, and a fork/vendor decision if the package stalls.

Operational Impact

Maintenance

• Expect to own more than a "composer require" implies: version pinning, periodic review of upstream activity, and likely a vendored fork if the maintainer goes quiet. Budget a recurring, low-but-nonzero line item (roughly a few hours per quarter) for dependency review.
• The empty v1.0.1 changelog raises the per-upgrade cost: every bump requires diffing source rather than reading notes. That is manageable at current cadence but scales badly during a security incident when you need to know quickly whether you are affected.
• Keep the abstraction layer thin enough to swap to laravel/socialite-style custom guard or a first-party JWT implementation if the package is abandoned.

Support

• No vendor SLA. Support is the maintainer's goodwill plus the Supabase community. Internal runbook authorship is mandatory, not optional — the team must be able to debug JWT validation without upstream help.
• Escalation path for auth incidents must be defined before go-live, since auth is a hard-down failure mode with no graceful degradation.

Scaling

• If verification is local JWT validation, this scales horizontally with no added dependency on Supabase availability per request — the desirable case, and a strong argument for verifying JWKS locally with a cached key set.
• If the package calls Supabase on every request, it adds a synchronous third-party hop to the hot path; that changes the latency budget and the failure-mode analysis materially. Resolve this in the spike before any load assumptions are made.
• JWKS caching and clock-skew tolerance are the two details that determine whether auth survives a Supabase blip at scale.

Failure modes

• Supabase outage: logins and token refresh fail even if verification is local; sessions with valid unexpired tokens survive. Decide whether to allow existing sessions to continue (recommended) and communicate it.
• Key rotation without JWKS support: every issued token fails validation simultaneously — a total auth outage. Highest-severity, lowest-likelihood failure; mitigate with a rotation runbook and a staged test.
• Silent patch regression: a v1.0.1-style unannounced change to validation logic could weaken or break auth with no changelog to point at. Mitigated by pinned versions, staged promotion, and an auth-specific smoke test in CI.
• Config/secret mishandling: missing or wrong JWT secret/JWKS config can fail open if the guard is written permissively. Verify the guard denies by default on any validation error.
• User-provisioning drift: local user rows diverging from Supabase (deleted, disabled, or email-changed upstream) leaves stale access. Needs a periodic reconciliation job.

Ramp-up

• Low for a Laravel-fluent team: the guard/middleware pattern is idiomatic, so a mid-level engineer should be productive within a day of spike time.
• Non-trivial for whoever owns identity long-term: they must learn Supabase Auth semantics (GoTrue token lifecycle, refresh, revocation, key management) in addition to Laravel's guard system. Assign a named owner.
• Producing a one-page internal runbook — config keys, rotation procedure, known failure modes, rollback steps — is the highest-leverage ramp-up investment and should be treated as a go-live prerequisite.