HTTP middleware

Keep the generated outer route stack and authorize each operation against its actual target. The minimal example shows the order; the alias table defines arguments and refusal responses. Organization context supplies coordinates, while the permission guard decides whether the actor may perform the action.

Signature

An App never imports App\Http\Middleware. The SDK publishes the stable names that cross the package boundary in packages/app-sdk/packages/laravel/src/Http/Middleware.php:

final class Middleware
{
    public const AGENT_DELEGATION = 'agent.delegation';
    public const APP_INSTALLED = 'app.installed';
    public const AUTHENTICATED_LOCALE = 'nexia.locale';
    public const LEGAL_ENTITY_CONTEXT = 'nexia.context.legal_entity';
    public const WORKSPACE_CONTEXT = 'nexia.context.workspace';
}12345678

Parameterized authorization and structural guards remain string signatures registered by the host. Use only the signatures in this page; the existence of a Core middleware class does not make that class an App dependency.

Minimal example

This is the complete outer stack emitted from stubs/package-app/empty-routes.stub, with a concrete App key. It identifies the tenant, scopes the session, authenticates either a human or delegated Agent, narrows delegated authority, checks App availability, then hydrates view and organization context.

use Illuminate\Support\Facades\Route;
use Nexia\Http\Middleware;
use Stancl\Tenancy\Middleware\InitializeTenancyByDomainOrSubdomain;
use Stancl\Tenancy\Middleware\PreventAccessFromUnwantedDomains;
use Stancl\Tenancy\Middleware\ScopeSessions;

Route::middleware([
    'web',
    InitializeTenancyByDomainOrSubdomain::class,
    PreventAccessFromUnwantedDomains::class,
    ScopeSessions::class,
    'auth:sanctum,agent',
    'agent.delegation',
    'app.installed:workshop',
    Middleware::LEGAL_ENTITY_CONTEXT,
    Middleware::WORKSPACE_CONTEXT,
])->group(function (): void {
    // Register Workshop routes here.
});12345678910111213141516171819

Authorize each concrete operation inside the group. Tenant-owned generated routes use can.tenant_wide; canonical Legal Entity routes authorize in the controller using explicit request targets or the stored record owner. Use can.scope when the URL carries the target. The outer stack establishes identity and context only.

Parameters

Generated outer stack

Order is part of the contract. Authentication cannot safely run before tenant identification, and a delegated request must be narrowed before a capability guard or controller executes.

Registered Nexia aliases

bootstrap/app.php registers fourteen custom aliases. Ten are used by App routes; four belong to platform-only entry points.

Options: choosing guards and order

Choose a capability guard from the operation's real data owner, not from the screen that happens to call it.

Keep app.installed outside individual CRUD routes so every App endpoint fails closed consistently. Put can.* at the smallest concrete operation. A Policy still checks the loaded record, a list predicate excludes out-of-scope rows in SQL, and the domain service enforces transition rules. Middleware does not replace any of those layers.

Output or return

A passing middleware returns the next response. Context middleware may add request-local data for downstream contracts; none of these values is evidence of authority by itself.

The generated App stack follows this sequence (authorization may run in a route guard or the controller):

tenant identification
  -> tenant-scoped session
  -> human or Agent authentication
  -> delegated-authority narrowing
  -> App operational check
  -> request context hydration
  -> route capability guard
  -> Policy and list predicate
  -> domain transition123456789

The Core routes/api.php root group explicitly adds authorization-denial auditing, throttle:api, and the password-session check. Package routes load through their own provider: an /api URL does not inherit this root group. Attach any required rate limit explicitly. The shared api limiter allows 300 requests per minute for normal traffic, keyed by tenant plus user id or IP. Delegated Agent traffic uses a separate 240-per-minute bucket keyed by tenant plus Agent id, so it does not consume the user's browser bucket. Endpoint-specific limits still apply on top. The API root also runs Laravel's password-hash session check against the stateful web guard; stateless delegated traffic passes through. The web and api groups re-check a redeemed support session on every request. Those automatic host concerns are not aliases an App copies into its package route file.

Errors

Real usage

packages/quality/routes/routes.php retains the generated outer group with tenant initialization, authentication, App installation, Legal Entity context, and Workspace context. Add an operation-specific permission guard when adding a Resource route. packages/people/routes/routes.php adds nexia.context.operating_unit and operating_unit.affiliated where the URL carries both organization coordinates. packages/payroll/routes/routes.php combines human.only with a can.scope guard whose fourth parameter is self for personal payroll lines.

Inspect the registered chain without changing state:

task artisan -- route:list --path=quality
task artisan -- route:list --path=legal-entities --json12

Focused source-backed behavior is covered by tests/Feature/AppRuntime/TenantAppInstallationRuntimeTest.php, tests/Feature/Authorization/CanTenantWideMiddlewareTest.php, tests/Feature/Access/RouteOperatingUnitContextTest.php, tests/Feature/Agent/AgentDelegationGuardTest.php, and tests/Feature/WorkspaceContextTest.php.

Related

• SDK contracts — the PHP boundary that publishes middleware names without exposing Core classes
• Permissions and roles — how capability, Grant scope, and subject population form the decision behind can.*
• Add a protected API — apply the guards, Policy, list predicate, and denial tests to one App operation
• Tenant and context — distinguish tenant, actor, organization, and Workspace context before choosing a guard
• Agent Resource Data Runtime — see how generic Agent writes return through the same authorized App routes