Laravel Sanctum — Token ID Omission Causes 800ms Logins

<?php

namespace App\IO\TheCodeForge\Auth;

/**
 * FILE: Understanding Sanctum's request lifecycle
 * Run: php artisan tinker  (paste each block to inspect)
 *
 * This isn't a controller — it's annotated pseudocode that mirrors
 * what Sanctum's Guard::user() does internally on every request.
 */

// ── Step 1: Sanctum checks if the request is "stateful" ──────────────────────
// config/sanctum.php  →  'stateful' => explode(',', env('SANCTUM_STATEFUL_DOMAINS', ...))
// Sanctum compares the request's Origin / Referer header against this list.
$requestOrigin  = 'https://my-spa.com';          // Comes from the browser request
$statefulHosts  = ['my-spa.com', 'localhost'];    // From your .env / config

$isStatefulRequest = in_array(
    parse_url($requestOrigin, PHP_URL_HOST),
    $statefulHosts
);

if ($isStatefulRequest) {
    // ── Path A: SPA Session Auth ──────────────────────────────────────────
    // Sanctum delegates entirely to the 'web' guard.
    // The session cookie (laravel_session) carries the user ID.
    // No token is involved. CSRF protection via X-XSRF-TOKEN header.
    echo "Authenticating via session cookie (web guard delegation)" . PHP_EOL;
} else {
    // ── Path B: Token Auth ────────────────────────────────────────────────
    // Sanctum reads the raw token from the Authorization header.
    $rawToken = 'your-app|AbCdEf123456...'; // Format: {tokenId}|{rawSecret}

    // Splits on the pipe to get the token ID (avoids full-table scans).
    [$tokenId, $rawSecret] = explode('|', $rawToken, 2);

    // Hashes the secret portion with SHA-256.
    $hashedSecret = hash('sha256', $rawSecret);

    // Queries: SELECT * FROM personal_access_tokens WHERE id = ? AND token = ?
    // This single indexed query is why Sanctum performs well under load.
    echo "Looking up token ID: {$tokenId} with hash: {$hashedSecret}" . PHP_EOL;

    // If found, Sanctum calls $tokenModel->tokenable to get the User via
    // a polymorphic relationship — so one token table serves ALL model types.
    echo "User resolved via polymorphic tokenable() relationship" . PHP_EOL;
}

<?php

namespace App\IO\TheCodeForge\Http\Controllers\Api;

use App\IO\TheCodeForge\Http\Controllers\Controller;
use App\IO\TheCodeForge\Models\User;
use Illuminate\Http\JsonResponse;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Hash;
use Illuminate\Validation\ValidationException;

class ApiAuthController extends Controller
{
    /**
     * Register a new user and immediately issue a scoped token.
     * Real-world: a mobile app's "Sign Up" screen calls this.
     */
    public function register(Request $request): JsonResponse
    {
        $validated = $request->validate([
            'name'     => ['required', 'string', 'max:255'],
            'email'    => ['required', 'email', 'unique:users'],
            'password' => ['required', 'string', 'min:12', 'confirmed'],
            'device_name' => ['required', 'string', 'max:100'], // e.g. "iPhone 15 Pro"
        ]);

        $newUser = User::create([
            'name'     => $validated['name'],
            'email'    => $validated['email'],
            // Always hash — never store plain text passwords
            'password' => Hash::make($validated['password']),
        ]);

        // createToken() returns a NewAccessToken object.
        // The PLAIN TEXT token is only available RIGHT NOW via ->plainTextToken.
        // After this response, it cannot be retrieved again — store it client-side.
        $newAccessToken = $newUser->createToken(
            name: $validated['device_name'],          // Human-readable label
            abilities: ['invoices:read', 'profile:update'], // Scope this token
            expiresAt: now()->addDays(30)             // Expires in 30 days
        );

        return response()->json([
            'user'  => $newUser->only(['id', 'name', 'email']),
            // Send this ONCE. The client must store it securely (Keychain, Keystore)
            'token' => $newAccessToken->plainTextToken,
            'abilities' => $newAccessToken->accessToken->abilities,
        ], 201);
    }

    /**
     * Login: validate credentials, issue a new token per device.
     * Using per-device tokens means users can revoke individual sessions.
     */
    public function login(Request $request): JsonResponse
    {
        $validated = $request->validate([
            'email'       => ['required', 'email'],
            'password'    => ['required', 'string'],
            'device_name' => ['required', 'string', 'max:100'],
        ]);

        $existingUser = User::where('email', $validated['email'])->first();

        // Deliberate: we give the same error for 'user not found' AND 'wrong password'.
        // This prevents user enumeration attacks.
        if (! $existingUser || ! Hash::check($validated['password'], $existingUser->password)) {
            throw ValidationException::withMessages([
                'email' => ['The credentials you provided do not match our records.'],
            ]);
        }

        // Optional: revoke all tokens for this device name before issuing a new one.
        // Prevents token accumulation if users log in repeatedly on the same device.
        $existingUser->tokens()
            ->where('name', $validated['device_name'])
            ->delete();

        $freshToken = $existingUser->createToken(
            name: $validated['device_name'],
            abilities: ['*'], // Wildcard = all abilities (use sparingly)
        );

        return response()->json([
            'token' => $freshToken->plainTextToken,
        ]);
    }

    /**
     * Logout: revoke ONLY the token used for this request.
     * The user stays logged in on all other devices.
     */
    public function logout(Request $request): JsonResponse
    {
        // currentAccessToken() returns the PersonalAccessToken model
        // that authenticated this request.
        // Delete it immediately — this is the actual revocation.
        $request->user()->currentAccessToken()->delete();

        return response()->json(['message' => 'Token revoked successfully.']);
    }

    /**
     * Get the authenticated user's profile.
     * Protected by auth:sanctum middleware.
     */
    public function profile(Request $request): JsonResponse
    {
        return response()->json([
            'user' => $request->user()->only(['id', 'name', 'email']),
        ]);
    }
}

// ── SPA (React/Axios) ───────────────────────────────────────────────────────
// File: services/api.js
import axios from 'axios';

// Configure Axios to send cookies with every request.
const apiClient = axios.create({
    baseURL: 'https://api.myapp.com',
    withCredentials: true,                    // Required — sends cookies from the browser
    xsrfCookieName: 'XSRF-TOKEN',             // Default, reads the cookie set by sanctum
    xsrfHeaderName: 'X-XSRF-TOKEN',           // Default, sends the CSRF token as a header
});

/**
 * Authenticate the SPA user via Sanctum's cookie-based session.
 * This is called once when the user logs in.
 */
export async function loginWithSanctum(email, password) {
    // Step 1: Fetch CSRF cookie from Sanctum.
    // This sets the XSRF-TOKEN cookie (accessible to JS) and starts a session.
    await apiClient.get('/sanctum/csrf-cookie');

    // Step 2: Post credentials to the Laravel login route (web guard).
    // Laravel validates, authenticates, and sets the laravel_session cookie.
    await apiClient.post('/login', { email, password });

    // Step 3: Now all subsequent requests are automatically authenticated.
    // The browser sends the session cookie; Sanctum reads it.
    const { data } = await apiClient.get('/api/user');
    return data;
}

/*
 * If you use fetch() instead of Axios:
 *   fetch('/sanctum/csrf-cookie', { credentials: 'include' })
 *   .then(() => fetch('/login', { method: 'POST', credentials: 'include', headers: {...} }))
 *   .then(() => fetch('/api/user', { credentials: 'include' }));
 */

// ── Laravel side: routes/api.php ──────────────────────────────────────────────
// Route::middleware('auth:sanctum')->get('/user', function (Request $request) {
//     return $request->user();
// });

// ── Laravel side: config/cors.php ─────────────────────────────────────────────
// return [
//     'paths' => ['api/*', 'sanctum/csrf-cookie', 'login'],
//     'allowed_methods' => ['*'],
//     'allowed_origins' => ['https://app.myapp.com'],   // Your SPA's exact origin
//     'supports_credentials' => true,                     // Required for cookies
// ];

// ── Laravel side: .env ────────────────────────────────────────────────────────
// SANCTUM_STATEFUL_DOMAINS=app.myapp.com,localhost
// SESSION_DOMAIN=.myapp.com
// SESSION_DRIVER=cookie

// ── Laravel side: app/Http/Kernel.php ─────────────────────────────────────────
// 'api' => [
//     \Laravel\Sanctum\Http\Middleware\EnsureFrontendRequestsAreStateful::class,
//     'throttle:api',
//     \Illuminate\Routing\Middleware\SubstituteBindings::class,
// ],

/*
 * ── Flow Summary ──
 * 1. GET /sanctum/csrf-cookie  →  Set-Cookie: XSRF-TOKEN=..., laravel_session=...
 * 2. POST /login {email,password}  →  Laravel authenticates, session cookie remains.
 * 3. GET /api/user  →  Browser sends cookies, Sanctum reads session, returns user.
 */

<?php

namespace App\IO\TheCodeForge\Http\Controllers\Api;

use App\IO\TheCodeForge\Models\RefreshToken;
use App\IO\TheCodeForge\Models\User;
use Illuminate\Http\JsonResponse;
use Illuminate\Http\Request;

class TokenRefreshController extends Controller
{
    public function refresh(Request $request): JsonResponse
    {
        $validated = $request->validate([
            'refresh_token' => ['required', 'string', 'size:64'],
        ]);

        $hashedToken = hash('sha256', $validated['refresh_token']);

        $refreshTokenRecord = RefreshToken::where('token', $hashedToken)
            ->where('expires_at', '>', now())
            ->first();

        if (! $refreshTokenRecord) {
            return response()->json(['message' => 'Invalid or expired refresh token.'], 401);
        }

        $user = $refreshTokenRecord->user;

        $oldAccessTokenId = $refreshTokenRecord->access_token_id;
        $refreshTokenRecord->delete();
        $user->tokens()->where('id', $oldAccessTokenId)->delete();

        $newAccessToken = $user->createToken(
            name: 'refreshed-session',
            abilities: ['*'],
            expiresAt: now()->addHour(),
        );

        $newRawRefreshToken = bin2hex(random_bytes(32));
        RefreshToken::create([
            'user_id'         => $user->id,
            'access_token_id' => $newAccessToken->accessToken->id,
            'token'           => hash('sha256', $newRawRefreshToken),
            'expires_at'      => now()->addDays(30),
        ]);

        return response()->json([
            'access_token'  => $newAccessToken->plainTextToken,
            'refresh_token' => $newRawRefreshToken,
            'expires_in'    => 3600,
        ]);
    }
}

<?php

namespace App\IO\TheCodeForge\Console;

// ── FILE 1: app/Console/Kernel.php — Scheduled token pruning ─────────────────
use Illuminate\Console\Scheduling\Schedule;
use Illuminate\Foundation\Console\Kernel as ConsoleKernel;

class Kernel extends ConsoleKernel
{
    protected function schedule(Schedule $schedule): void
    {
        // Prune tokens that expired more than 24 hours ago.
        // Runs every day at 3:00 AM — low traffic window.
        $schedule->command('sanctum:prune-expired --hours=24')
                 ->dailyAt('03:00')
                 ->onOneServer()         // Prevents duplicate runs in multi-server setups
                 ->runInBackground();    // Doesn't block other scheduled tasks

        // Also prune refresh tokens if you implemented the refresh pattern
        $schedule->call(function () {
            \App\IO\TheCodeForge\Models\RefreshToken::where('expires_at', '<', now())
                ->delete();
        })->dailyAt('03:15');
    }
}

// ── FILE 2: Token lookup caching (performance optimization) ───────────────────
namespace App\IO\TheCodeForge\Extensions;

use Illuminate\Support\Facades\Cache;
use Laravel\Sanctum\PersonalAccessToken;

class CachedPersonalAccessToken extends PersonalAccessToken
{
    /**
     * Override Sanctum's token finder to cache the result.
     * Laravel Sanctum calls PersonalAccessToken::findToken($rawToken) internally.
     * By extending the model and registering it, we inject caching transparently.
     */
    public static function findToken(string $token): ?static
    {
        if (! str_contains($token, '|')) {
            return parent::findToken($token);
        }

        [$tokenId] = explode('|', $token, 2);

        $cacheKey = "sanctum_token_{$tokenId}";

        // Cache for 5 minutes. Short enough that revoked tokens expire quickly.
        // After logout (token deletion), the cached record will cause a 401
        // only if someone uses the revoked token within the 5-min window —
        // acceptable trade-off for most apps. Use 0 TTL for banking/medical.
        return Cache::remember($cacheKey, now()->addMinutes(5), function () use ($token) {
            return parent::findToken($token);
        });
    }

    /**
     * When a token is deleted (logout), bust the cache immediately.
     */
    protected static function boot(): void
    {
        parent::boot();

        static::deleted(function (self $accessToken) {
            Cache::forget("sanctum_token_{$accessToken->id}");
        });
    }
}

// ── FILE 3: AppServiceProvider.php — Tell Sanctum to use your cached model ────
namespace App\IO\TheCodeForge\Providers;

use Laravel\Sanctum\Sanctum;

class AppServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        Sanctum::usePersonalAccessTokenModel(
            \App\IO\TheCodeForge\Extensions\CachedPersonalAccessToken::class
        );
    }
}

// ── FILE 4: Database migration — Add missing index for multi-model auth ───────
use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

return new class extends Migration
{
    public function up(): void
    {
        Schema::table('personal_access_tokens', function (Blueprint $table) {
            $table->index(
                ['tokenable_type', 'tokenable_id'],
                'pat_tokenable_type_tokenable_id_index'
            );
        });
    }

    public function down(): void
    {
        Schema::table('personal_access_tokens', function (Blueprint $table) {
            $table->dropIndex('pat_tokenable_type_tokenable_id_index');
        });
    }
};

// ── FILE 5: routes/api.php — Rate limiting auth endpoints ─────────────────────
use Illuminate\Cache\RateLimiting\Limit;
use Illuminate\Support\Facades\RateLimiter;

RateLimiter::for('api-auth', function (Request $request) {
    return Limit::perMinute(5)
                ->by($request->ip())
                ->response(function () {
                    return response()->json(
                        ['message' => 'Too many login attempts. Try again in 60 seconds.'],
                        429
                    );
                });
});

Route::middleware('throttle:api-auth')->group(function () {
    Route::post('/login',    [ApiAuthController::class, 'login']);
    Route::post('/register', [ApiAuthController::class, 'register']);
});

<?php

namespace App\IO\TheCodeForge\Tests\Feature;

use App\IO\TheCodeForge\Models\User;
use Illuminate\Foundation\Testing\RefreshDatabase;
use Laravel\Sanctum\Sanctum;
use Tests\TestCase;

class ApiAuthTest extends TestCase
{
    use RefreshDatabase;

    /**
     * PATTERN 1: Sanctum::actingAs() — most common, use this.
     * Creates a token with the given abilities and authenticates the user.
     */
    public function test_authenticated_user_can_access_profile(): void
    {
        $user = User::factory()->create();

        Sanctum::actingAs(
            $user,
            ['profile:read'] // Token abilities — optional
        );

        $response = $this->getJson('/api/user');

        $response->assertOk()
                 ->assertJson(['id' => $user->id]);
    }

    /**
     * PATTERN 2: Real token for testing ability enforcement.
     * Useful when you need to verify that tokens without a specific ability get a 403.
     */
    public function test_token_without_ability_gets_403(): void
    {
        $user = User::factory()->create();

        $token = $user->createToken(
            name: 'test-token',
            abilities: ['profile:read']  // NOT 'invoices:read'
        );

        $response = $this->withHeaders([
            'Authorization' => 'Bearer ' . $token->plainTextToken,
        ])->getJson('/api/invoices');  // This route requires 'invoices:read'

        $response->assertForbidden();
    }

    /**
     * PATTERN 3: SPA cookie auth test — full flow with CSRF.
     * Tests that the CSRF cookie is set and that credentials authenticate the session.
     */
    public function test_spa_login_flow(): void
    {
        $user = User::factory()->create([
            'email'    => 'alice@example.com',
            'password' => bcrypt('secret123!'),
        ]);

        // Step 1: Get CSRF cookie
        $csrfResponse = $this->get('/sanctum/csrf-cookie');
        $csrfResponse->assertNoContent();

        // Extract the XSRF-TOKEN from the cookie
        $xsrfToken = $csrfResponse->getCookie('XSRF-TOKEN', false)->getValue();

        // Step 2: Login with credentials and CSRF token
        $loginResponse = $this->postJson('/login', [
            'email'    => 'alice@example.com',
            'password' => 'secret123!',
        ], [
            'X-XSRF-TOKEN' => $xsrfToken,
            'Referer'      => 'http://localhost',  // Must match stateful domain
        ]);

        $loginResponse->assertOk();

        // Step 3: Access protected API endpoint
        $profileResponse = $this->withHeader('Referer', 'http://localhost')
                                ->getJson('/api/user');
        $profileResponse->assertOk()
                        ->assertJson(['email' => 'alice@example.com']);
    }

    /**
     * Ensure that bare actingAs() is NOT used — it defaults to 'web' guard.
     * This test would fail if we accidentally used it.
     */
    public function test_bare_actingAs_does_not_work_for_api(): void
    {
        $user = User::factory()->create();

        $this->actingAs($user);  // Default 'web' guard — this will NOT authenticate API requests

        $response = $this->getJson('/api/user');
        $response->assertUnauthorized();  // Expect 401, not 200
    }
}

// io.thecodeforge — php tutorial

$ php artisan tinker

// Peek at what Sanctum actually stores
use Laravel\Sanctum\PersonalAccessToken;

$token = PersonalAccessToken::first();

dd([
    'id' => $token->id,
    'tokenable_type' => $token->tokenable_type,
    'tokenable_id' => $token->tokenable_id,
    'name' => $token->name,
    'abilities' => $token->abilities,
    'last_used_at' => $token->last_used_at,
    'expires_at' => $token->expires_at,
]);

// io.thecodeforge — php tutorial

// Correct middleware order for Sanctum SPA auth in Laravel 11/12
return Application::configure(basePath: dirname(__DIR__))
    ->withRouting(
        api: __DIR__.'/../routes/api.php',
        health: '/up',
    )
    ->withMiddleware(function (Middleware $middleware) {
        // Register BEFORE token auth - this is the trap
        $middleware->api(prepend: [
            \Laravel\Sanctum\Http\Middleware\EnsureFrontendRequestsAreStateful::class,
        ]);
        
        // Group-specific middleware must come AFTER
        $middleware->alias([
            'abilities' => \Laravel\Sanctum\Http\Middleware\CheckAbilities::class,
        ]);
    })->create();

// io.thecodeforge — php tutorial

// 1. Migration: add tenant_id to personal_access_tokens
Schema::table('personal_access_tokens', function (Blueprint $table) {
    $table->foreignId('tenant_id')->constrained()->after('tokenable_id');
});

// 2. Extend Sanctum's PersonalAccessToken model
use Laravel\Sanctum\PersonalAccessToken as SanctumToken;

class TenantScopedToken extends SanctumToken
{
    // Override token resolution to enforce tenant isolation
    public static function findToken($token)
    {
        $record = parent::findToken($token);
        
        if (!$record || !app()->has('current_tenant')) {
            return $record;
        }
        
        return $record->tenant_id === app('current_tenant')->id 
            ? $record 
            : null;
    }
}

// 3. Register in AppServiceProvider
$this->app->bind(
    PersonalAccessToken::class,
    TenantScopedToken::class
);

// io.thecodeforge — php tutorial

// Sanctum does NOT enforce this for you.
// You must check scopes manually in every guarded action.

use Illuminate\Http\Request;

class UserController
{
    public function destroy(Request $request, User $user)
    {
        if (!$request->user()->tokenCan('users:delete')) {
            abort(403, 'Token missing required scope');
        }

        $user->delete();
    }
}

// io.thecodeforge — php tutorial

// bootstrap/app.php — Laravel 11/12 way

use Illuminate\Auth\AuthenticationException;
use Illuminate\Auth\Access\AuthorizationException;
use Laravel\Sanctum\Exceptions\TokenMismatchException;

return Application::configure(basePath: dirname(__DIR__))
    ->withExceptions(function (Exceptions $exceptions) {
        $exceptions->render(function (AuthenticationException $e) {
            return response()->json([
                'message' => 'Token missing or expired',
                'code' => 'AUTH_REQUIRED',
            ], 401);
        });

        $exceptions->render(function (TokenMismatchException $e) {
            return response()->json([
                'message' => 'Token does not match the required ability',
                'code' => 'TOKEN_MISMATCH',
            ], 403);
        });
    });