ahmido
9b58a5696d
Spec 430: Exchange PowerShell adapter contract slice 1. Validation was not rerun during PR creation handoff; branch contains implementation report and tests. Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de> Reviewed-on: #497
181 lines
13 KiB
Markdown
181 lines
13 KiB
Markdown
# Tasks: Exchange PowerShell Adapter Contract Slice 1
|
|
|
|
**Input**: `specs/430-exchange-powershell-adapter-contract-slice-1/spec.md` and `plan.md`
|
|
**Prerequisites**: Spec 429 completed and current repo truth confirms no existing Spec 430 package.
|
|
**Tests**: Pest tests are required because the implementation changes runtime source-contract behavior.
|
|
|
|
## Test Governance Checklist
|
|
|
|
- [x] Lane assignment is named and is the narrowest sufficient proof for the changed behavior.
|
|
- [x] New or changed tests stay in the smallest honest family; no heavy-governance or browser family is added accidentally.
|
|
- [x] Shared helpers, factories, seeds, fixtures, provider setup, workspace context, and session defaults stay cheap by default.
|
|
- [x] Planned validation commands cover the change without pulling in unrelated lane cost.
|
|
- [x] Browser proof is explicitly `N/A - no rendered UI surface changed`.
|
|
- [x] Human Product Sanity is `N/A - no product surface changed`.
|
|
- [x] Any material budget, baseline, trend, or escalation note is recorded in the implementation report.
|
|
|
|
## Phase 1: Preflight And Repo Truth
|
|
|
|
**Purpose**: Confirm current state and prevent implementation drift before runtime edits.
|
|
|
|
- [x] T001 Capture current branch, HEAD, and `git status --short` in `specs/430-exchange-powershell-adapter-contract-slice-1/implementation-report.md`.
|
|
- [x] T002 Confirm Spec 429 completion and source path from `specs/429-exchange-teams-source-surface-catalog-adapter-strategy/implementation-report.md`.
|
|
- [x] T003 Inspect current Coverage v2 source-contract surfaces before editing, decide exact support/config file paths from sibling conventions, and record the choice before runtime edits: `apps/platform/app/Services/TenantConfiguration/CoverageSourceContractResolver.php`, `ResourceTypeRegistry.php`, `CoverageIdentityStrategyRegistry.php`, and nearby Spec 426-429 tests.
|
|
- [x] T004 Confirm exact included types: `transportRule`, `remoteDomain`, `inboundConnector`.
|
|
- [x] T005 Confirm excluded types: `acceptedDomain`, `organizationConfig`, `mailboxPlan`, `outboundConnector`, `sharingPolicy`, Teams policy types, `externalAccessPolicy`, and the rest of Cohort 1.
|
|
- [x] T006 Confirm no live provider execution, no evidence promotion, no OperationRun, no UI, no customer claim, no `tenant_id`, no fallback reader, no legacy shim, and no Exchange mini-platform are planned.
|
|
|
|
**Checkpoint**: Preflight evidence exists and scope remains the three-type adapter-contract slice.
|
|
|
|
## Phase 2: Contract Shape And Command Boundary
|
|
|
|
**Purpose**: Introduce or reuse the narrow structured command boundary before target-specific contracts.
|
|
|
|
- [x] T007 Add or reuse a structured Exchange PowerShell command contract shape in the repo-canonical TenantConfiguration/Coverage v2 support path.
|
|
- [x] T008 Add or reuse fields for source surface, adapter pattern, command name, command contract version, allowed parameters, response shape, identity handoff, permission model, redaction rules, and normalization handoff.
|
|
- [x] T009 Add or reuse structured result/failure objects or arrays for command-runner responses without creating a broad framework.
|
|
- [x] T010 Add a fake command runner boundary for tests that accepts structured command contracts only.
|
|
- [x] T011 Ensure any production runner implementation introduced by this slice is disabled/inert and not wired to UI, jobs, commands, capture services, or provider execution.
|
|
|
|
**Checkpoint**: The command boundary can represent structured read-only commands without shell execution.
|
|
|
|
## Phase 3: Command Allowlist And Safety Tests
|
|
|
|
**Purpose**: Prove only safe commands can be represented or run through the fake boundary.
|
|
|
|
- [x] T012 Add `Spec430ExchangePowerShellCommandAllowlistTest` covering the static allowlist.
|
|
- [x] T013 Allow `Get-TransportRule`, `Get-RemoteDomain`, and `Get-InboundConnector`.
|
|
- [x] T014 Reject `Set-*`, `New-*`, `Remove-*`, `Enable-*`, `Disable-*`, `Update-*`, `Start-*`, `Stop-*`, `Invoke-*`, `Search-*`, `Export-*`, and `Import-*`.
|
|
- [x] T015 Reject raw command strings, user-supplied arbitrary parameter names, script blocks, pipeline fragments, semicolon-separated commands, redirection, file writes, module installation, and unknown parameters.
|
|
- [x] T016 Ensure tests prove no unit test executes a real shell and no test calls Microsoft services.
|
|
|
|
**Checkpoint**: Only the three read-only command contracts are representable in this slice.
|
|
|
|
## Phase 4: Target Type Contracts
|
|
|
|
**Purpose**: Add the three target contracts with complete metadata.
|
|
|
|
- [x] T017 Add `transportRule` contract metadata for `Get-TransportRule`, collection shape, identity candidates, permission notes, response shape, redaction, normalization handoff, claim boundary, and restore tier.
|
|
- [x] T018 Add `remoteDomain` contract metadata for `Get-RemoteDomain`, collection shape, default-vs-custom identity concerns, permission notes, response shape, redaction, normalization handoff, claim boundary, and restore tier.
|
|
- [x] T019 Add `inboundConnector` contract metadata for `Get-InboundConnector`, collection shape, connector identity concerns, permission notes, response shape, redaction, normalization handoff, claim boundary, and restore tier.
|
|
- [x] T020 Add `Spec430TransportRuleCommandContractTest`.
|
|
- [x] T021 Add `Spec430RemoteDomainCommandContractTest`.
|
|
- [x] T022 Add `Spec430InboundConnectorCommandContractTest`.
|
|
- [x] T023 Ensure display name alone cannot be treated as stable identity for any included type.
|
|
- [x] T024 Ensure permission metadata is marked pending runtime validation unless repo evidence proves least privilege.
|
|
|
|
**Checkpoint**: Each included target type has complete contract metadata and focused tests.
|
|
|
|
## Phase 5: Resolver Integration
|
|
|
|
**Purpose**: Make resolver state deterministic without promoting evidence/readiness.
|
|
|
|
- [x] T025 Update `CoverageSourceContractResolver.php` or repo-equivalent resolver integration so included types no longer return missing adapter/missing contract blockers.
|
|
- [x] T026 Return repo-equivalent `contract_verified_pending_capture` and `adapter_contract_available` for `transportRule`, `remoteDomain`, and `inboundConnector`.
|
|
- [x] T027 Preserve blocked/deferred states for explicitly excluded Exchange and Teams types.
|
|
- [x] T028 Add `Spec430ExchangePowerShellResolverTest` covering included and excluded types.
|
|
- [x] T029 Add or update feature-level resolver tests only if the existing resolver path needs DB-backed proof.
|
|
|
|
**Checkpoint**: Resolver state changes only for the three included types.
|
|
|
|
## Phase 6: Metadata, Redaction, And Response Shape Proof
|
|
|
|
**Purpose**: Prove capture prerequisites are explicit before any capture exists.
|
|
|
|
- [x] T030 Add `Spec430ExchangePowerShellPermissionMetadataTest`.
|
|
- [x] T031 Add `Spec430ExchangePowerShellIdentityHandoffTest`.
|
|
- [x] T032 Add `Spec430ExchangePowerShellRedactionRulesTest`.
|
|
- [x] T033 Add response-shape tests covering collection item path, required identity candidate fields, safe fields, sensitive fields, volatile fields, unsupported fields, empty collection, permission denied, command unavailable, adapter unavailable, malformed response, and unexpected object shape.
|
|
- [x] T034 Ensure redaction metadata forbids tokens, secrets, authorization headers, cookies, certificate private material, passwords, raw transcripts, raw shell stdout/stderr, mail body/content, mailbox content, file content, and Teams transcript/content.
|
|
- [x] T035 Ensure protected configuration examples are classified for email addresses, domains, IP ranges, certificate names, header names, rule patterns, and connector routing metadata.
|
|
- [x] T036 Ensure provider-owned source-detail metadata keeps Exchange cmdlets and response fields inside adapter/source-contract internals, not platform-core ownership truth, customer vocabulary, customer-safe labels, or product surface copy.
|
|
- [x] T037 Ensure future execution handoff metadata preserves workspace, managed-environment, and provider-connection scope and treats provider-native tenant identifiers as metadata only.
|
|
|
|
**Checkpoint**: Metadata is sufficient for later capture validation, preserves provider/scope boundaries, and does not create capture.
|
|
|
|
## Phase 7: No-Promotion And Architecture Guard Tests
|
|
|
|
**Purpose**: Keep the adapter contract from becoming evidence, readiness, or customer truth.
|
|
|
|
- [x] T038 Add `Spec430ExchangePowerShellNoEvidencePromotionTest`.
|
|
- [x] T039 Add `Spec430ExchangePowerShellNoClaimPromotionTest`.
|
|
- [x] T040 Add no-OperationRun proof that no run record is created or required by this slice.
|
|
- [x] T041 Add no-provider-call proof that no Exchange, Graph, PowerShell, or Microsoft service call happens.
|
|
- [x] T042 Add no-compare/render/certification/restore/customer-ready proof for the included types.
|
|
- [x] T043 Add no-UI/no-route/no-navigation proof or static assertions if current repo guard patterns support it.
|
|
- [x] T044 Add no-`tenant_id`, no provider-native tenant ownership, no Exchange-specific evidence table, no legacy shim, no fallback reader, and no mini-platform proof.
|
|
|
|
**Checkpoint**: Spec 430 remains an adapter-contract slice with no product-readiness promotion.
|
|
|
|
## Phase 8: Regression Coverage
|
|
|
|
**Purpose**: Preserve fail-safe behavior from prerequisite specs.
|
|
|
|
- [x] T045 Run or update focused Spec 426 fail-safe/source-contract regression tests.
|
|
- [x] T046 Run or update focused Spec 427 source contract state regression tests.
|
|
- [x] T047 Run or document Spec 428 no-op/no-evidence proof if test-backed.
|
|
- [x] T048 Run focused Spec 417 identity regression tests relevant to Exchange target types.
|
|
- [x] T049 Run focused Spec 420 generic evidence/capture eligibility regression tests.
|
|
- [x] T050 Document exact commands, pass counts, assertions, and any unrelated failures in the implementation report.
|
|
|
|
**Checkpoint**: Existing Exchange/Teams fail-safe guarantees remain intact.
|
|
|
|
## Phase 9: Product Surface And Filament Close-Out
|
|
|
|
**Purpose**: Record explicit N/A results required by repo gates.
|
|
|
|
- [x] T051 Confirm no rendered UI surface changed.
|
|
- [x] T052 Record browser status as `N/A - no rendered UI surface changed`.
|
|
- [x] T053 Record Livewire v4 compliance as N/A/no UI change while preserving repo baseline.
|
|
- [x] T054 Record panel provider registration as no panel change; providers remain in `apps/platform/bootstrap/providers.php`.
|
|
- [x] T055 Record global search posture as no resource changed.
|
|
- [x] T056 Record destructive/high-impact action posture as none.
|
|
- [x] T057 Record asset strategy as no assets and no `filament:assets` requirement.
|
|
- [x] T058 Record deployment impact as no env vars, migrations, queues, scheduler, storage, or assets unless implementation evidence says otherwise.
|
|
|
|
**Checkpoint**: Product Surface Contract close-out is explicit and not faked with browser work.
|
|
|
|
## Phase 10: Validation And Implementation Report
|
|
|
|
**Purpose**: Finish with reviewable proof.
|
|
|
|
- [x] T059 Run `cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent`.
|
|
- [x] T060 Run focused Spec 430 tests with `cd apps/platform && ./vendor/bin/sail artisan test --filter=Spec430 --compact`.
|
|
- [x] T061 If Spec 430 tests are split across files that the filter misses, run each direct file and record the file list, pass count, and assertions.
|
|
- [x] T062 Run selected Spec 426/427/428 regressions.
|
|
- [x] T063 Run selected Spec 417/420 regressions.
|
|
- [x] T064 Run `git diff --check`.
|
|
- [x] T065 Run `git status --short`.
|
|
- [x] T066 Create `specs/430-exchange-powershell-adapter-contract-slice-1/implementation-report.md` with candidate gate, branch/head, dirty state before/after, files changed, target types, excluded types, command allowlist proof, resolver proof, permission/response/identity/redaction proof, provider-owned source-detail proof, workspace/managed-environment/provider-connection scope proof, provider-native tenant metadata-only proof, no shell/provider/evidence/OperationRun/compare/render/certification/customer/restore/tenant_id/mini-platform proof, Product Surface result, tests run, and deferred work.
|
|
|
|
**Checkpoint**: Implementation report is complete and ready for review.
|
|
|
|
## Dependencies & Execution Order
|
|
|
|
- Phase 1 blocks all runtime edits.
|
|
- Phase 2 blocks Phases 3-6.
|
|
- Phase 3 command safety should be test-first before target contract implementation where practical.
|
|
- Phase 4 target contracts can be implemented in parallel after the shared contract shape exists.
|
|
- Phase 5 depends on target contracts.
|
|
- Phases 6 and 7 can run alongside resolver work after metadata exists.
|
|
- Phase 8 depends on resolver/no-promotion behavior.
|
|
- Phase 9 and Phase 10 close out after code and tests are complete.
|
|
|
|
## Stop Conditions
|
|
|
|
Stop and amend/split the spec if implementation requires:
|
|
|
|
- live Exchange connection or provider execution
|
|
- production PowerShell runner wiring
|
|
- OperationRun creation
|
|
- content-backed evidence
|
|
- compare/render/certification/restore/customer claims
|
|
- UI, routes, navigation, reports, downloads, or customer output
|
|
- Teams adapter
|
|
- Exchange Admin API adapter
|
|
- more than `transportRule`, `remoteDomain`, and `inboundConnector`
|
|
- database migration or `tenant_id`
|
|
- legacy shim, fallback reader, dual truth, or Exchange mini-platform
|
|
- Exchange cmdlets or response fields promoted to platform-core ownership truth, customer vocabulary, customer-safe labels, or product surface copy
|
|
- provider-native tenant identifiers promoted to ownership truth or used to bypass workspace/managed-environment/provider-connection scope
|