TenantAtlas/specs/433-exchange-credential-permission-evidence-support/implementation-report.md

Implementation Report: Exchange Credential and Permission Evidence Support

Result

• Gate result: PASS WITH CONDITIONS.
• Active spec: specs/433-exchange-credential-permission-evidence-support/.
• Branch: 433-exchange-credential-permission-evidence-support.
• HEAD at implementation start: f4e34212 feat: add Exchange PowerShell production runner gate (#499).
• Initial dirty state: only untracked active Spec 433 package.
• Final dirty state: application/config/test changes plus the active Spec 433 package and this report.
• Condition: browser Product Surface sanity found an existing broader provider-readiness guidance card can still show a generic provider credential blocker next to the Exchange-specific capability result. The changed Exchange capability slots themselves were canonical and redacted. No UI code was changed because this spec forbids new UI/surface work.

Activated Skills and Gates

• spec-kit-implementation-loop: active implementation workflow.
• pest-testing: Pest 4 focused unit/feature coverage.
• Browser skills: browser:control-in-app-browser and repo browsertest for focused read-only browser proof.
• TenantPilot repo gates: spec readiness, workspace-scope safety, RBAC/action safety, provider freshness semantics, OperationRun truth, evidence-anchor contract, Product Surface gate, Filament/Livewire v5 change loop.

Implementation Summary

• Added ExchangePowerShellInvocationReadinessEvaluator as the shared readiness truth for exchange_powershell_invoke capability evaluation and the production runner gate.
• Kept the no-migration path. Existing ProviderCredential fields and ManagedEnvironmentPermission.details are sufficient when permission details explicitly match workspace, managed environment, provider, and provider connection.
• Tightened certificate readiness so certificate references require both rotation and expiry metadata.
• Extended ExchangePowerShellPermissionEvidenceEvaluator with supported-provider checks, status normalization, configurable currentness, safe source metadata, scoped provider-connection validation, and sanitized blocker states.
• Post-review hardening requires trusted permission evidence provenance: source=provider_verification, canonical, calendar-valid ISO/RFC3339 non-future observed_at/verified_at, verified_at >= observed_at, evaluator identity/version metadata, and current last_checked_at plus current observed/verified timestamps. Missing, malformed, relative, untrusted, or time-inconsistent metadata now fails closed as unvalidated evidence; stale row or provenance timestamps fail closed as stale evidence.
• Post-review scope hardening requires workspace_id, managed_environment_id, and provider_connection_id evidence metadata to be canonical positive integer values before any scope comparison. Numeric-prefix, decimal, scientific-notation, whitespace-padded, missing, or otherwise malformed scope IDs now fail closed as unvalidated evidence instead of passing through PHP integer coercion.
• Updated ProviderCapabilityEvaluator so exchange_powershell_invoke is Supported only when combined credential and permission readiness passes.
• Post-review hardening makes the shared Exchange readiness evaluator the single capability truth for exchange_powershell_invoke; the capability no longer applies a separate generic provider-readiness freshness precheck that can diverge from the Exchange evidence currentness config.
• Updated ExchangePowerShellProductionRunner to consume combined readiness before runtime checks or process execution.
• Added safe readiness_state and readiness_blocker propagation into OperationRun runner-result context.
• Added env/config defaults for TENANTPILOT_EXCHANGE_POWERSHELL_PERMISSION_EVIDENCE_CURRENTNESS_DAYS=30.

Data Model Decision

Area	Decision	Proof
Provider credential	No migration	provider_connection_id, credential_kind, source, last_rotated_at, and expires_at cover the observable readiness states for this slice.
Permission evidence	No migration	ManagedEnvironmentPermission remains one row per environment + permission key; details must match workspace, environment, provider, and provider connection or fail closed.
Provider connection scope	Existing model	Readiness requires matching workspace_id and managed_environment_id; wrong connection details block.
Secret material	No new storage	Existing encrypted payload remains hidden and is never returned in readiness/OperationRun context.
Migration lane	N/A	No schema file added; no PostgreSQL schema lane required.

Credential Matrix

Credential state	Result
Missing reference	Blocks as credential_blocked_missing_reference.
Client secret	Blocks as credential_blocked_secret_based_app.
Certificate missing rotation or expiry metadata	Blocks as credential_blocked_certificate_missing.
Expired certificate	Blocks as credential_blocked_certificate_expired.
Certificate unsupported by config	Blocks as credential_blocked_certificate_unsupported.
Certificate explicitly supported for readiness	Passes as certificate_supported.
Federated	Blocks unless future config/support is added.
Managed identity string	Blocks as unsupported/unknown.
Unknown kind	Blocks fail-closed.

Permission Matrix

Permission evidence state	Result
Missing row	Blocks as permission_evidence_blocked_missing.
Missing/absent/revoked status	Blocks as permission_evidence_blocked_absent.
Unknown/error status	Blocks as permission_evidence_blocked_unknown.
Granted without trusted source, observed/verified timestamps, evaluator identity, or evaluator version	Blocks as unvalidated.
Granted with malformed, relative, future, or time-inconsistent provenance metadata	Blocks as unvalidated.
Granted with malformed scope identifiers	Blocks as unvalidated before scope matching.
Stale row, observed timestamp, or verified timestamp beyond configured currentness	Blocks as permission_evidence_blocked_stale.
Wrong workspace/environment/provider/provider connection	Blocks with scoped failure code.
Current scoped Exchange.ManageAsApp	Passes as verified.

Capability and Runner Proof

• exchange_powershell_invoke uses the combined readiness evaluator and no longer relies on admin consent, generic provider freshness, or generic stored permission rows alone.
• Missing credential maps to Missing; stale/unknown/unvalidated permission evidence maps to Unknown; wrong-scope or unsupported readiness maps to Blocked.
• The production runner evaluates combined readiness before runtime readiness, command building, locks, or process execution.
• Successful runner context persists only safe state: runner mode, execution enabled, readiness state, runtime state, credential state, permission evidence state, command builder/output/concurrency state, counts, and duration.

No-Promotion Proof

• No TenantConfigurationResource or TenantConfigurationResourceEvidence rows are created.
• No raw or normalized Exchange payload, compare/render/certification/restore/customer-ready state, report output, Review Pack output, PDF output, route, Filament page/resource/widget/action, Livewire component, navigation, asset, global search change, job, schedule, listener, console trigger, Exchange-specific table, legacy shim, fallback reader, dual write, or tenant_id ownership path was introduced.
• Completed Specs 429-432 were read-only context and were not rewritten.

Product Surface and Filament Close-Out

• No-legacy posture: canonical addition only; no aliases, fallback readers, hidden routes, duplicate UI, or historical compatibility path.
• Product Surface Impact: existing provider capability/readiness surfaces can render changed evaluator output; no new surface budget introduced.
• UI Surface Impact: no UI files changed; existing provider connection and required-permissions surfaces render the changed status data.
• Browser proof: PASS WITH CONDITION. See browser section below.
• Human Product Sanity: PASS WITH CONDITION. Exchange capability slots are canonical/redacted; existing broader readiness card can still show a generic credential blocker beside Exchange-specific Supported.
• Visible complexity outcome: neutral; no new visible components, only more truthful existing status values.
• Livewire v4 compliance: unchanged repo baseline; no Livewire runtime code added.
• Provider registration location: no Filament panel provider registration changed; Laravel panel providers remain in apps/platform/bootstrap/providers.php.
• Global search: no Filament resources or global search behavior changed.
• Destructive/high-impact actions: no UI action added; runner remains behind existing Spec 432 gates and provider-run authorization.
• Asset strategy: no assets; filament:assets not required for this slice.
• Deployment impact: no migration, queue, schedule, storage, asset, or build impact. New env example key: TENANTPILOT_EXCHANGE_POWERSHELL_PERMISSION_EVIDENCE_CURRENTNESS_DAYS=30.

Browser Proof

• Sail was running and migrations were current. A local smoke fixture was seeded with:
  • ready environment + certificate credential + scoped current Exchange.ManageAsApp evidence + all normal required permission rows;
  • blocked environment + client-secret credential + stale permission evidence.
• A temporary ignored local .env override TENANTPILOT_EXCHANGE_POWERSHELL_SUPPORTED_REFERENCE_KINDS=certificate was used only during browser proof and removed afterward; config cache was cleared after removal.
• Provider connection view, ready fixture:
  • Exchange PowerShell invocation: Supported rendered in existing capability detail.
  • No raw grant, access token, private key, certificate password, or client secret sentinel rendered.
  • No browser console errors from the tab.
• Provider connection view, blocked fixture:
  • Exchange PowerShell invocation: Unknown rendered for the blocked client-secret/stale-evidence fixture.
  • No raw token/client-secret sentinel rendered.
  • No browser console errors from the tab.
• Required-permissions view, ready fixture:
  • Provider capabilities section rendered Exchange PowerShell invocation as Supported with 0 missing, 0 need review.
  • No raw grant, access token, private key, certificate password, or client secret sentinel rendered.
  • No browser console errors from the tab.
• Required-permissions view, blocked fixture:
  • Required-permissions/provider capability surface stayed non-supported and showed missing/stale guidance rather than ready.
  • No raw token/client-secret sentinel rendered.
  • No browser console errors from the tab.
• Laravel Boost browser log contained older unrelated June operation-page errors, not Spec 433 route errors.

Validation

• Post-review remediation:
  • cd apps/platform && php artisan test --filter=Spec433 --compact
    • Result: PASS, 48 tests, 211 assertions.
  • cd apps/platform && php artisan test --filter='Spec433|Spec432|Spec431' --compact
    • Result: PASS, 150 tests, 1057 assertions.
  • cd apps/platform && ./vendor/bin/pint --dirty
    • Result: PASS, 10 files.
  • git diff --check
    • Result: PASS.
• cd apps/platform && php artisan test --filter=Spec433 --compact
  • Result: PASS, 30 tests, 157 assertions.
• cd apps/platform && php artisan test --filter=Spec432 --compact
  • Result: PASS, 72 tests, 430 assertions.
• cd apps/platform && php artisan test --filter=Spec431 --compact
  • Result: PASS, 30 tests, 416 assertions.
• cd apps/platform && php artisan test --filter='Spec433|Spec432|Spec431' --compact
  • Result: PASS, 132 tests, 1003 assertions.
• cd apps/platform && php artisan test --filter='Spec433|Spec432|Spec431|Spec430|Spec427ExchangeTeamsNoEvidencePromotion|Spec427ExchangeTeamsNoCompareRenderCertification|Spec426ExchangeTeamsNoTenantId|Spec426ExchangeTeamsNoMiniPlatform|Spec417IdentityNoLegacyNoUiActivation|Spec419M365RegistryExpansion|Spec420M365NoOverclaim|ProviderCapabilityRegistryTest|ProviderCapabilityEvaluationTest' --compact
  • Result: PASS, 222 tests, 2028 assertions, 1 PostgreSQL-only skip.
• cd apps/platform && ./vendor/bin/pint --dirty
  • Result: PASS, 10 files.
• cd apps/platform && ./vendor/bin/pint app/Services/TenantConfiguration/ExchangePowerShellInvocationReadinessEvaluator.php tests/Feature/TenantConfiguration/Spec433ExchangePowerShellEvidenceReadinessTest.php tests/Feature/TenantConfiguration/Spec431ExchangePowerShellInvocationGateTest.php tests/Feature/TenantConfiguration/Spec432ExchangePowerShellProductionRunnerGateTest.php --format=txt
  • Result: PASS.
• git diff --check
  • Result: PASS.
• cd apps/platform && ./vendor/bin/sail artisan migrate --force
  • Result: PASS, nothing to migrate.
• cd apps/platform && ./vendor/bin/sail artisan config:clear
  • Result: PASS after browser override removal.

Deferred Work

• Content-backed Exchange evidence capture/promotion remains Spec 434 or later.
• Live Exchange execution success, customer claims, compare/render/certification/restore readiness, Teams, Exchange Admin API, broader Exchange targets, and UI productization remain out of scope.
• A future UI/product-surface cleanup should decide how to distinguish generic provider readiness from Exchange PowerShell-specific capability readiness on provider connection pages.