ahmido a23131cdbc feat: add Exchange evidence capture adapter guard (#501 )

Summary: add Spec 434 Exchange PowerShell evidence capture adapter and prerequisite/identity/content-only guards; cap Exchange evidence at content_backed while preserving Graph capture. Validation: php artisan test --filter=Spec434 --compact; ./vendor/bin/pint --dirty --test; git diff --cached --check. Product Surface: N/A - no rendered UI surface changed; no deployment impact.
Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de>
Reviewed-on: #501

2026-07-08 10:46:05 +00:00

37 KiB

Raw Permalink Blame History

Feature Specification: Exchange Evidence Capture Adapter and Content-Only Guard

Feature Branch: 434-exchange-evidence-capture-adapter-content-only-guard Created: 2026-07-08 Status: Draft Input: User-provided draft Spec 434 - Exchange Evidence Capture Adapter & Content-Only Guard.

Preparation Selection

Selected candidate: Spec 434 - Exchange Evidence Capture Adapter and Content-Only Guard.
Source location: User-provided attachment /Users/ahmeddarrazi/.codex/attachments/0d15249e-465b-40bd-b2c6-307e6c0f895a/pasted-text.txt.
Why selected: The user supplied a direct P0 draft and current repo truth has no existing specs/434-* package. Specs 429-433 already establish the Exchange PowerShell sequence, and Spec 433 explicitly leaves content-backed Exchange evidence capture/promotion to Spec 434 or later. The draft correctly narrows the next slice from full evidence promotion to the adapter and guard infrastructure required before promotion can be honest.
Roadmap relationship: Continues the Coverage v2 / Microsoft 365 / Exchange sequence after Specs 429-433. It prepares Spec 435-style target evidence promotion by creating a safe Exchange capture adapter path and preventing unsafe evidence append or over-promotion.
Close alternatives deferred: The older "Exchange Content-Backed Evidence Promotion Slice 1" is deferred because current repo truth still needs adapter, identity, and content-only guard work first. Exchange comparable/renderable promotion, certification, restore, customer output, Teams PowerShell support, broader Exchange target types, and M365 claim guard remain follow-up candidates.
Completed-spec guardrail result: Specs 429-433 are completed or implementation-closed context only and were not modified. Spec 433 records PASS WITH CONDITIONS; the condition concerns an existing broader provider-readiness card, while Exchange-specific capability slots and safety checks are canonical/redacted. That condition is not merge-blocking for this adapter-only prep, but implementation must carry it forward and must not create new UI or customer claims. No existing Spec 434 package or branch was found.
Smallest viable implementation slice: Build an internal trusted Exchange PowerShell capture adapter boundary that accepts only transportRule, remoteDomain, and inboundConnector; reuses tenant_configuration.capture; consumes Spec 433 readiness, Spec 432 runner boundary, and Spec 430 verified command contracts; hard-stops unsafe identity before evidence append; limits the Exchange path to content_backed; records safe zero-item outcomes without fake evidence; and proves generic Graph capture remains unchanged.
Feature description fed into Spec Kit: Prepare an internal Exchange PowerShell evidence capture adapter and content-only evidence guard for transportRule, remoteDomain, and inboundConnector, reusing tenant_configuration.capture, requiring existing readiness and runner gates, blocking unsafe identity before evidence append, preventing promotion beyond content_backed, keeping empty collections from becoming fake evidence, preserving sanitized OperationRun context, and adding no UI, routes, jobs, schedules, listeners, migrations, customer claims, restore, compare/render, certification, or tenant_id ownership truth.

Activated Skills and Gates

spec-kit-next-best-prep: selected because this is a preparation-only Spec Kit request.
TenantPilot repo skills used as planning gates: spec readiness, workspace-scope safety, RBAC/action safety, OperationRun truth, evidence-anchor contract, provider freshness semantics, Product Surface gate, customer-output gate, and temporary TCM cutover guard.
Hard-gate stop conditions at preparation time: none. Runtime implementation must stop if it introduces unscoped evidence, raw payload leakage, direct OperationRun status/outcome writes, unsafe provider readiness, UI/customer output, tenant_id ownership truth, legacy shims, fallback readers, or over-promotion beyond content_backed.

Spec Candidate Check (mandatory - SPEC-GATE-001)

Problem: TenantPilot has verified Exchange PowerShell contracts, invocation gates, production runner safety, and credential/permission readiness, but it does not yet have a safe evidence capture adapter path from Exchange runner output into Coverage v2 evidence storage.
Today's failure: A later implementation could treat Exchange command contracts as Graph contracts, append evidence after unsafe identity, create fake empty evidence, leak raw PowerShell output into OperationRun context, or let CoverageEvidenceWriter promote Exchange evidence to renderable/comparable/certified/customer-ready states before target-specific promotion is proven.
User-visible improvement: Operators and reviewers get an honest internal safety boundary: Exchange capture infrastructure may produce only guarded internal content-backed fixture evidence, or it blocks with safe reasons. It does not create customer claims, UI readiness, compare/render support, restore readiness, or certification.
Smallest enterprise-capable version: Add a trusted internal adapter and narrowly scoped guards around existing Coverage v2 resource/evidence paths. Do not add a new OperationRun type, schema, customer output, product surface, trigger, or Exchange mini-platform.
Explicit non-goals: No full content-backed promotion for transportRule, remoteDomain, or inboundConnector; no live Exchange provider calls in tests; no arbitrary PowerShell; no compare/render/certification/restore/customer claim; no UI/routes/navigation/Filament/Livewire/assets/global search; no jobs/schedules/listeners/triggers; no Teams; no Exchange Admin API; no broader Exchange targets; no Exchange-specific evidence tables; no tenant_id; no legacy shim; no fallback reader.
Permanent complexity imported: New internal service/guard classes or repo-canonical equivalents, focused unit/feature tests, and possibly one provider-neutral eligibility representation. No new persisted entity, table, customer-visible vocabulary, Product Surface runtime framework, or OperationRun type.
Why now: Spec 433 closed the credential/permission readiness prerequisite. The next safe step is to bridge Exchange runner output into Coverage v2 without overclaiming evidence, identity, product readiness, or customer proof.
Why not local: A local patch inside the generic Graph capture service or writer would either make Exchange look Graph-shaped or hide security-critical guard logic inside an existing path. The adapter boundary must be explicit and testable so future target promotion can stay small and safe.
Approval class: Core Enterprise.
Red flags triggered: New abstraction and limited outcome vocabulary. Defense: the abstraction is security/evidence-boundary critical and replaces an unsafe implicit bridge; outcome labels change blocking behavior and test proof rather than adding presentation taxonomy.
Score: Nutzen: 2 | Dringlichkeit: 2 | Scope: 2 | Komplexitaet: 1 | Produktnaehe: 1 | Wiederverwendung: 2 | Gesamt: 10/12
Decision: approve as a narrow backend safety prerequisite for later Exchange content-backed evidence promotion.

Spec Scope Fields (mandatory)

Scope: workspace + managed-environment + provider-connection scoped internal evidence capture path.
Primary Routes: N/A - no route, page, navigation, panel, action, report, download, browser-rendered surface, or customer surface changes.
Data Ownership: Existing Coverage v2 ownership remains workspace_id, managed_environment_id, and provider_connection_id. tenant_configuration.capture is the evidence-owning OperationRun. No tenant_id ownership truth and no Exchange-specific evidence table.
RBAC: No new user-facing action is added. The internal adapter must only run inside trusted application flow after existing capture operation authorization/scope has already established workspace, managed environment, and provider connection entitlement. Any future start surface must be a separate or amended spec.

For canonical-view specs:

Default filter behavior when tenant-context is active: N/A - no canonical route or rendered query change.
Explicit entitlement checks preventing cross-tenant leakage: Adapter and writer path must reject mismatched workspace_id, managed_environment_id, or provider_connection_id before capture, identity evaluation, or evidence append.

No Legacy / No Backward Compatibility Constraint (mandatory)

TenantPilot is pre-production unless this spec explicitly records a compatibility exception.

Compatibility posture: canonical addition only.
Legacy aliases, fallback readers, hidden routes, duplicate UI, old labels, or historical fixtures kept?: no.
Why clean replacement is safe now: Exchange evidence capture is not shipped as customer-facing proof. Unsafe or unproven states must block rather than be bridged through compatibility behavior.

UI Surface Impact (mandatory - UI-COV-001)

Does this spec add, remove, rename, or materially change any reachable UI surface?

No UI surface impact
Existing page changed
New page/route added
Navigation changed
Filament panel/provider surface changed
New modal/drawer/wizard/action added
New table/form/state added
Customer-facing surface changed
Dangerous action changed
Status/evidence/review presentation changed
Workspace/environment context presentation changed

No-impact rationale: Spec 434 is backend adapter and guard infrastructure only. It must not edit runtime UI files, route files, Filament resources/pages/widgets, Livewire components, navigation, reports, downloads, customer outputs, or browser-rendered diagnostics.

UI/Productization Coverage (mandatory when UI Surface Impact is not "No UI surface impact"; otherwise write `N/A - no reachable UI surface impact` plus rationale)

N/A - no reachable UI surface impact. Any future UI, readiness status, trigger, customer output, report, Review Pack, or evidence viewer change must amend this spec or use a separate spec and satisfy the Product Surface Contract.

Product Surface Impact (mandatory for UI-affecting specs; otherwise write `N/A - no rendered product surface changed` plus rationale)

Reference: docs/product/standards/product-surface-contract.md.

Product Surface Contract applies?: no - no rendered product surface changes.
Page archetype: N/A.
Primary user question: N/A.
Primary action: N/A.
Surface budget result: N/A.
Technical Annex / deep-link demotion: N/A for rendered UI. OperationRun context, raw evidence, source keys, command metadata, provider diagnostics, stdout/stderr, payloads, and logs must remain internal and must not become default product content.
Canonical status vocabulary: N/A for UI.
Visible complexity impact: neutral; no visible surface changes.
Product Surface exceptions: none.

Browser Verification Plan (mandatory)

Browser proof required?: no.
No-browser rationale: N/A - no rendered UI surface changed.
Focused path when required: N/A.
Primary interaction to execute: N/A.
Console, Livewire, Filament, network, and 500-error checks: N/A.
Full-suite failure triage: N/A.

Human Product Sanity Check (mandatory)

Required?: no.
No-human-sanity rationale: N/A - no product surface changed.
Reviewer questions: N/A.
Planned result location: N/A.

Product Surface Merge Gate Checklist (mandatory)

No-legacy posture or approved exception recorded.
Product Surface Impact is completed or N/A is justified.
Browser proof is completed or N/A - no rendered UI surface changed is justified.
Human Product Sanity is completed or not applicable with rationale.
Product Surface exceptions are documented or none.
Implementation report will state Livewire v4 compliance, provider registration location, global search posture, destructive/high-impact action posture, asset strategy, tests/browser result, deployment impact, visible complexity outcome, and no completed-spec rewrite assertion.

Cross-Cutting / Shared Pattern Reuse (mandatory when the feature touches notifications, status messaging, action links, header actions, dashboard signals/cards, alerts, navigation entry points, evidence/report viewers, or any other existing shared operator interaction family; otherwise write `N/A - no shared interaction family touched`)

Cross-cutting feature?: yes, backend shared evidence/operation/provider infrastructure only.
Interaction class(es): OperationRun execution truth, Coverage v2 evidence writing, provider readiness, identity evaluation, capture outcome summarization. No operator interaction family or rendered surface changes.
Systems touched: Existing GenericContentEvidenceCaptureService, CoverageSourceContractResolver, CoverageResourceUpserter, CoverageEvidenceWriter, ExchangePowerShellCommandContracts, ExchangePowerShellCommandRunner, ExchangePowerShellInvocationResult, ExchangePowerShellProductionRunner, ExchangePowerShellInvocationReadinessEvaluator, ProviderCapabilityEvaluator, OperationSummaryKeys, SummaryCountsNormalizer, and tenantpilot Exchange PowerShell config.
Existing pattern(s) to extend: Coverage v2 resource/evidence storage, tenant_configuration.capture, Spec 430 command contract metadata, Spec 432 runner boundary, Spec 433 combined readiness, exchange_powershell_invoke provider capability evaluation, OperationSummaryKeys, and sanitized OperationRun context conventions.
Shared contract / presenter / builder / renderer to reuse: No UI presenter/renderer. Reuse existing OperationRun service/lifecycle conventions, Coverage v2 evidence models, provider capability/readiness gates, existing CaptureOutcome values, and generic capture redaction/normalization helpers where safe.
Why the existing shared path is sufficient or insufficient: Existing Graph capture is sufficient for Graph-backed contracts and must remain unchanged. It is insufficient for Exchange PowerShell runner output because Exchange has no Graph endpoint and requires an explicit provider-owned adapter boundary.
Allowed deviation and why: A provider-owned Exchange adapter and local guard classes are allowed because they protect evidence correctness and avoid Graph-shaped fake contracts. Broad provider frameworks, UI semantics, customer-output frameworks, and Exchange mini-platforms are forbidden.
Consistency impact: Later target promotion must reuse this adapter/guard path instead of adding a second Exchange evidence path.
Review focus: Verify no raw provider payload leaks, no over-promotion, no fake empty evidence, no new operation type, and no generic Graph capture regression.

OperationRun UX Impact (mandatory when the feature creates, queues, deduplicates, resumes, blocks, completes, or deep-links to an `OperationRun`; otherwise write `N/A - no OperationRun start or link semantics touched`)

Touches OperationRun start/completion/link UX?: no rendered UX. It touches internal OperationRun type/context requirements for the capture path.
Shared OperationRun UX contract/layer reused: N/A for UI. Runtime must use existing tenant_configuration.capture operation truth and existing OperationRun lifecycle conventions.
Delegated start/completion UX behaviors: N/A - no toast, run link, artifact link, browser event, queued DB notification, or rendered surface.
Local surface-owned behavior that remains: none.
Queued DB-notification policy: N/A.
Terminal notification path: unchanged central lifecycle behavior for tenant_configuration.capture.
Exception required?: none. If implementation needs a new OperationRun type, queued notification, start surface, or run link behavior, stop and amend/split the spec.