crewli/api/bootstrap/app.php

<?php

declare(strict_types=1);

use Illuminate\Auth\Access\AuthorizationException;
use Illuminate\Auth\AuthenticationException;
use Illuminate\Database\QueryException;
use Illuminate\Foundation\Application;
use Illuminate\Foundation\Configuration\Exceptions;
use Illuminate\Foundation\Configuration\Middleware;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Log;
use Illuminate\Validation\ValidationException;
use Symfony\Component\HttpKernel\Exception\HttpException;
use Symfony\Component\HttpKernel\Exception\NotFoundHttpException;

return Application::configure(basePath: dirname(__DIR__))
    ->withRouting(
        web: __DIR__.'/../routes/web.php',
        api: __DIR__.'/../routes/api.php',
        commands: __DIR__.'/../routes/console.php',
        // Per RFC-WS-6 §Q1 v1.3 addition 2 — broadcast channel auth callbacks
        // live in routes/channels.php. Registers Laravel's broadcasting auth
        // middleware so private/presence channel subscriptions reach the
        // closures defined there.
        channels: __DIR__.'/../routes/channels.php',
        health: '/up',
        apiPrefix: 'api/v1',
    )
    // Listener auto-discovery uitgeschakeld — observability listeners (en
    // alle andere listeners) worden expliciet geregistreerd in
    // AppServiceProvider::boot(). Reden: silent double-registration is
    // mogelijk wanneer auto-discovery + explicit listen samen lopen, en
    // expliciete registratie is grep-baar / IDE-navigeerbaar / direct
    // zichtbaar bij code review. Onder enterprise-grade observability is
    // impliciete discovery een stille fault-mode (RFC-WS-7 §3.6, OBS-8).
    ->withEvents(discover: false)
    ->withMiddleware(function (Middleware $middleware): void {
        // API uses token-based auth, no CSRF needed

        $middleware->append(\App\Http\Middleware\SecurityHeaders::class);

        // Read httpOnly auth cookie and inject as Authorization header (before Sanctum)
        $middleware->api(prepend: [
            \App\Http\Middleware\CookieBearerToken::class,
            // RFC-WS-7 §3.13 — structured logging context + X-Request-Id
            // round-trip. Runs early so unauthenticated 4xx responses
            // still carry a request_id header.
            \App\Http\Middleware\BindRequestLogContext::class,
            // RFC-WS-7 §3.6 — route-scope Sentry tags (app/route_name/
            // http.method). Auth-scope tags (user_id/actor_type/
            // organisation_id/actor_scope/impersonation.*) bind in
            // AuthScopeContextListener on the Authenticated event,
            // not in middleware. See the listener for rationale.
            \App\Http\Middleware\BindSentryRouteContext::class,
        ]);

        $middleware->alias([
            'portal.token' => \App\Http\Middleware\PortalTokenMiddleware::class,
            'role' => \Spatie\Permission\Middleware\RoleMiddleware::class,
            'impersonation' => \App\Http\Middleware\HandleImpersonation::class,
            // RFC-TIMETABLE v0.2 R1 — 60s Redis idempotency window for
            // POST /timetable/move. Narrow scope by design.
            'idempotency.60s' => \App\Http\Middleware\IdempotencyKey60sRedis::class,
        ]);
    })
    ->withExceptions(function (Exceptions $exceptions): void {
        // RFC-WS-7 §3.10 — bridge Laravel's exception handler into
        // sentry-laravel so report($e) and Laravel's automatic
        // report-before-render flow reach GlitchTip. sentry-laravel 4.x
        // does NOT auto-register this; the README installation snippet
        // requires the host application to wire it explicitly.
        // Filtering happens downstream of this hook: ignore_exceptions in
        // config/sentry.php drops Validation/Auth/AuthZ; SentryEventScrubber
        // drops sub-500 HttpExceptions via the before_send hook.
        \Sentry\Laravel\Integration::handles($exceptions);

        // Public Form Builder standardised error envelope (S2c D6).
        $exceptions->render(function (\App\Exceptions\FormBuilder\PublicFormApiException $e, Request $request) {
            $body = [
                'message' => $e->getMessage(),
                'code' => $e->publicCode,
            ];
            if ($e->fieldErrors !== null) {
                $body['errors'] = $e->fieldErrors;
            }

            return response()->json($body, $e->status, $e->headers);
        });

        // FormRequest validation on /api/v1/public/forms/* → rewrap into
        // the D6 envelope so every public endpoint error looks identical
        // regardless of which layer surfaced it.
        $exceptions->render(function (ValidationException $e, Request $request) {
            if (! $request->is('api/v1/public/forms/*')) {
                return null;
            }

            return response()->json([
                'message' => $e->getMessage(),
                'code' => 'VALIDATION_FAILED',
                'errors' => $e->errors(),
            ], $e->status);
        });

        // Database connection / query errors → 503
        $exceptions->render(function (QueryException|PDOException $e, Request $request) {
            if ($request->expectsJson() || $request->is('api/*')) {
                Log::error('Database error', [
                    'exception' => get_class($e),
                    'message' => $e->getMessage(),
                    'trace' => $e->getTraceAsString(),
                ]);

                $response = ['message' => 'Service temporarily unavailable. Please try again later.'];

                if (config('app.debug')) {
                    $response['debug'] = [
                        'exception' => get_class($e),
                        'message' => $e->getMessage(),
                    ];
                }

                return response()->json($response, 503);
            }
        });

        // 404 Not Found → friendly message
        $exceptions->render(function (NotFoundHttpException $e, Request $request) {
            if ($request->expectsJson() || $request->is('api/*')) {
                return response()->json([
                    'message' => 'Resource not found.',
                ], 404);
            }
        });

        // Authorization failures → log with user context
        $exceptions->render(function (AuthorizationException $e, Request $request) {
            if ($request->expectsJson() || $request->is('api/*')) {
                Log::warning('Authorization denied', [
                    'user_id' => auth()->id(),
                    'ip' => $request->ip(),
                    'path' => $request->path(),
                    'method' => $request->method(),
                ]);
            }

            return null; // Let Laravel handle the 403 response normally
        });

        // All other unhandled exceptions → 500
        // (ValidationException, AuthenticationException, and HttpException are handled by Laravel)
        $exceptions->render(function (Throwable $e, Request $request) {
            if ($request->expectsJson() || $request->is('api/*')) {
                if ($e instanceof ValidationException
                    || $e instanceof AuthenticationException
                    || $e instanceof HttpException) {
                    return null; // Let Laravel handle these normally
                }

                Log::error('Unhandled exception', [
                    'exception' => get_class($e),
                    'message' => $e->getMessage(),
                    'trace' => $e->getTraceAsString(),
                ]);

                $response = ['message' => 'An unexpected error occurred.'];

                if (config('app.debug')) {
                    $response['debug'] = [
                        'exception' => get_class($e),
                        'message' => $e->getMessage(),
                    ];
                }

                return response()->json($response, 500);
            }
        });
    })->create();