TenantAtlas/specs/104-provider-permission-posture/contracts/internal-services.md

Internal Contracts: Provider Permission Posture (Spec 104)

Date: 2026-02-21 | Branch: 104-provider-permission-posture

This feature does NOT expose external HTTP APIs. All contracts are internal service interfaces.

---

Contract 1: PermissionPostureFindingGenerator

Service: App\Services\PermissionPosture\PermissionPostureFindingGenerator

generate(Tenant $tenant, array $permissionComparison, ?OperationRun $operationRun = null): PostureResult

Input:

• $tenant: The tenant being evaluated
• $permissionComparison: Output of TenantPermissionService::compare() — see schema below
• $operationRun: Optional OperationRun for tracking (created by caller if not provided)

Input schema ($permissionComparison):

array{
    overall_status: 'granted'|'missing'|'error',
    permissions: array<int, array{
        key: string,
        type: string,
        description: ?string,
        features: array<int, string>,
        status: 'granted'|'missing'|'error',
        details: ?array,
    }>,
    last_refreshed_at: ?string,
}

Output (PostureResult value object):

PostureResult {
    int $findingsCreated,
    int $findingsResolved,
    int $findingsReopened,
    int $findingsUnchanged,
    int $errorsRecorded,
    int $postureScore,
    int $storedReportId,
}

Side effects:

1. Creates/updates/resolves Finding records (type: permission_posture)
2. Creates a StoredReport (type: permission_posture)
3. Dispatches alert events for new/reopened findings via the alert pipeline

Idempotency: Fingerprint-based. Same input produces same findings (no duplicates).

---

Contract 2: PostureScoreCalculator

Service: App\Services\PermissionPosture\PostureScoreCalculator

calculate(array $permissionComparison): int

Input: $permissionComparison — same schema as Contract 1 input.

Output: Integer 0–100 representing round(granted_count / required_count * 100). Returns 100 if required_count is 0.

Pure function: No side effects, no DB access.

---

Contract 3: GeneratePermissionPostureFindingsJob

Job: App\Jobs\GeneratePermissionPostureFindingsJob

Constructor

public function __construct(
    public readonly int $tenantId,
    public readonly array $permissionComparison,
)

handle(PermissionPostureFindingGenerator $generator): void

Flow:

1. Load Tenant (fail if not found)
2. Skip if tenant has no active provider connection (FR-016)
3. Create OperationRun (type = permission_posture_check)
4. Call $generator->generate($tenant, $permissionComparison, $run)
5. Record summary counts on OperationRun
6. Complete OperationRun

Queue: default (same queue as health checks)

Dispatch point: ProviderConnectionHealthCheckJob::handle() after TenantPermissionService::compare() returns, when $permissionComparison['overall_status'] !== 'error'.

---

Contract 4: Alert Event Schema (EVENT_PERMISSION_MISSING)

Event array (passed to AlertDispatchService::dispatchEvent()):

[
    'event_type'      => 'permission_missing',
    'tenant_id'       => int,
    'severity'        => 'low'|'medium'|'high'|'critical',
    'fingerprint_key' => "permission_missing:{tenant_id}:{permission_key}",
    'title'           => "Missing permission: {permission_key}",
    'body'            => "Tenant {tenant_name} is missing {permission_key}. Blocked features: {feature_list}.",
    'metadata'        => [
        'permission_key' => string,
        'permission_type' => string,
        'blocked_features' => array<string>,
        'posture_score' => int,
    ],
]

Produced by: PermissionPostureFindingGenerator for each newly created or re-opened finding. Not produced for: Auto-resolved findings, existing unchanged findings, error findings.

---

Contract 5: EvaluateAlertsJob Extension

New method: permissionMissingEvents(): array

Query: Finding where:

• finding_type = 'permission_posture'
• status IN ('new') (only new/re-opened, not acknowledged or resolved)
• severity >= minimum severity threshold from alert rule
• created_at or updated_at >= window start

Output: Array of event arrays matching Contract 4 schema.

---

Contract 6: StoredReport Retention

PruneStoredReportsCommand (Artisan command)

Signature: stored-reports:prune {--days=90}

Behavior: Deletes stored_reports where created_at < now() - days. Outputs count of deleted records.

Schedule: Daily via routes/console.php.