HTTP 미들웨어

생성된 외부 route stack을 유지하고 동작에 필요한 권한 가드를 추가하세요. 최소 예시에서 순서를, alias 표에서 인자와 거부 응답을 확인할 수 있습니다. 조직 문맥은 좌표를 제공하고 권한 가드는 행위자의 실행 가능 여부를 판단합니다.

시그니처

App은 App\Http\Middleware를 import하지 않습니다. 패키지 경계를 건너는 안정된 이름은 packages/app-sdk/packages/laravel/src/Http/Middleware.php에서 SDK가 공개합니다.

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

인자가 있는 권한·구조 guard는 호스트가 등록한 문자열 시그니처입니다. 이 문서에 있는 시그니처만 사용하세요. Core에 미들웨어 클래스가 존재한다는 사실은 그 클래스를 App 의존성으로 만들지 않습니다.

최소 예시

다음은 stubs/package-app/empty-routes.stub이 만드는 바깥 stack에 실제 App 키를 넣은 전체 형태입니다. 테넌트를 찾고 세션을 격리한 다음, 사람 또는 위임된 Agent를 인증하고, 위임 권한을 좁히고, App 가용성을 확인한 뒤 화면과 조직 컨텍스트를 설정합니다.

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 {
    // Workshop 경로를 여기에 등록합니다.
});12345678910111213141516171819

그룹 안의 각 연산을 인가하세요. 생성된 tenant 경로는 can.tenant_wide를 사용합니다. 정식 Legal Entity 경로는 Controller에서 요청 대상 또는 저장된 소유자를 해석해 인가하고, URL에 대상이 있는 경로는 can.scope를 사용합니다. 바깥 stack은 신원과 문맥만 확립합니다.

인자

생성되는 바깥 stack

실행 순서도 계약의 일부입니다. 테넌트를 식별하기 전에 인증을 안전하게 평가할 수 없고, 위임 요청은 capability guard나 controller가 실행되기 전에 먼저 좁혀야 합니다.

등록된 Nexia 별칭

bootstrap/app.php는 커스텀 별칭 열네 개를 등록합니다. 열 개는 App Route에서 사용하고 네 개는 플랫폼 전용 진입점에 속합니다.

옵션: guard 선택과 순서

호출하는 화면이 아니라 실제 연산의 데이터 소유자를 기준으로 capability guard를 고릅니다.

app.installed는 개별 CRUD Route 바깥에 두어 App endpoint 전체가 같은 방식으로 닫히게 합니다. can.*는 가장 작은 구체 연산에 둡니다. Policy는 로드된 레코드를 다시 검사하고, 목록 술어는 범위 밖 행을 SQL에서 제외하며, 도메인 서비스는 전이 규칙을 강제합니다. 미들웨어는 어느 층도 대신하지 않습니다.

결과 또는 반환

통과한 미들웨어는 다음 응답을 반환합니다. 컨텍스트 미들웨어는 downstream 계약에 요청 로컬 값을 추가할 수 있지만, 그 값 자체는 권한의 증거가 아닙니다.

생성된 App 경로는 아래 순서로 처리합니다. 인가는 경로 guard 또는 Controller에서 수행합니다.

tenant 식별
  -> tenant 격리 session
  -> 사람 또는 Agent 인증
  -> 위임 권한 축소
  -> App operational 검사
  -> request context 설정
  -> Route capability guard
  -> Policy와 목록 술어
  -> 도메인 전이123456789

Core의 routes/api.php 루트 그룹에는 권한 거부 감사, throttle:api, 비밀번호 세션 검사가 명시적으로 붙습니다. 패키지 경로는 자체 provider에서 로드하므로 URL이 /api로 시작해도 이 그룹을 상속하지 않습니다. 필요한 rate limit은 경로에 명시하세요. 공유 api limiter는 일반 traffic을 tenant와 user id 또는 IP로 묶어 분당 300회 허용합니다. 위임 Agent traffic은 tenant와 Agent id로 묶은 별도 분당 240회 bucket을 사용하므로 사용자 browser bucket을 소모하지 않습니다. 더 엄격한 endpoint별 limit은 그 위에 계속 적용됩니다. API root는 stateful web guard로 Laravel password-hash session 검사도 실행하며, stateless 위임 traffic은 그대로 통과합니다. web과 api 그룹은 교환된 support session도 매 요청마다 다시 확인합니다. 이 자동 호스트 concern은 App이 패키지 Route 파일로 복사하는 별칭이 아닙니다.

오류

실제 사용

packages/quality/routes/routes.php는 테넌트 초기화, 인증, App 설치, Legal Entity 문맥, Workspace 문맥을 처리하는 생성된 외부 그룹을 유지합니다. Resource 경로를 추가할 때 동작에 맞는 권한 가드를 붙이세요. packages/people/routes/routes.php는 URL이 두 조직 좌표를 운반하는 곳에 nexia.context.operating_unit과 operating_unit.affiliated를 추가합니다. packages/payroll/routes/routes.php는 개인 급여 명세에 human.only와 네 번째 인자가 self인 can.scope를 함께 적용합니다.

상태를 바꾸지 않고 등록된 chain을 확인할 수 있습니다.

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

집중 동작 근거는 tests/Feature/AppRuntime/TenantAppInstallationRuntimeTest.php, tests/Feature/Authorization/CanTenantWideMiddlewareTest.php, tests/Feature/Access/RouteOperatingUnitContextTest.php, tests/Feature/Agent/AgentDelegationGuardTest.php, tests/Feature/WorkspaceContextTest.php에 있습니다.

관련 문서

• SDK 계약 — Core 클래스를 노출하지 않고 미들웨어 이름을 공개하는 PHP 경계
• 권한과 역할 — can.* 뒤에서 capability, Grant 범위, population이 판단을 만드는 방식
• 보호된 API 추가하기 — 한 App 연산에 guard, Policy, 목록 술어, 거부 테스트 적용
• 테넌트와 컨텍스트 — guard를 고르기 전에 tenant, actor, 조직, Workspace 컨텍스트 구분
• Agent Resource Data 런타임 — 일반 Agent 쓰기가 같은 권한 적용 App Route로 돌아오는 방식