Skip to content

feat: instance operator controls (WI-2175) - #509

Merged
stefan-ernst merged 3 commits into
mainfrom
feat/wi-2175-operator-controls
Nov 16, 2026
Merged

stefan-ernst merged 3 commits into
mainfrom
feat/wi-2175-operator-controls

Conversation

@stefan-ernst

@stefan-ernst stefan-ernst commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Implement immutable operator controls for WI-2175 and WI-2176–WI-2183, keeping one public application implementation and customer-instance isolation. Production policies, credentials, fleet decisions and qualification remain outside core.

Companion tests: https://github.com/Windshiftapp/core-tests-internal/pull/52 (merge together).

Main integration

Updated to current application main (f496f1a9), preserving the security and seamless-time-tracking changes. Resolved the appended migration catalog conflict by retaining both sets of migrations and regenerated canonical metadata/OpenAPI. Application merge head: 13d21077. The companion test head includes existing time-tracking test PR #50 commits because that API is already on application main; merge that test PR first if desired to keep the review diff focused. No upstream test implementation was rewritten.

Post-integration operator/script -race coverage, serial PostgreSQL operator coverage, full pre-commit checks and policy-enabled Chromium (setup + 2 tests) passed again. GitHub reports the application branch mergeable; hosted CI checks are still in progress.

  • Explicit --operator-policy / WINDSHIFT_OPERATOR_POLICY startup JSON; no tenant policy-write API or privileged operator account.
  • Effective policy is separate from persisted organization preferences; omitted policy preserves existing behavior.
  • Read-only /api/v2/operator-controls and /rest/api/v2/operator-controls, admin permission + bearer scope, generated contract, shell discovery and admin UI.

Story coverage / merge closure checklist

Item Application delivery
WI-2176 Policy validation/immutability; lifecycle, maintenance, runtime diagnostics and plugin command authority; ordinary admin/audit access retained
WI-2177 LDAP writes/tests/sync denied before dependencies; restored configuration retained; SAML/SCIM discovery unchanged
WI-2178 Script authoring/import/application/execution gates; alternate service construction; timeout/concurrency; bounded blocker inventory
WI-2179 Local/S3 per-object + cumulative blob ceilings, physical inventory, serialized writes/deletes, restart/failure reconciliation, effective preferences/usage
WI-2180 Aggregate HTTP request/stream concurrency, durable fixed-interval counters, per-dispatched-step item/asset/nested automation admission
WI-2181 Bounded import admission wait/status, lease handling, process-death-safe local-host permits, injectable admission, non-secret estimate context and alternative-importer gates
WI-2182 Managed fixed-sender relay, transport authority, suspension, durable recipient-attempt allowance, generic SMTP/IMAP gate independent of OAuth intake
WI-2183 Connection/model/feature controls, shared completion + paid health-probe admission, durable qualified-envelope reservation and conservative unknown usage

Operational authority matrix, configuration examples, accounting semantics and external prerequisites: internal/operatorcontrols/README.md.

  • Application implementation and regression coverage supplied for all eight stories.
  • Operator-control, affected backend, PostgreSQL, race, rendered frontend and focused Chromium validation recorded below.
  • Merge the companion private test PR on the same branch as this application PR.
  • Complete acceptance review, then close the eight stories and epic after both merges. Do not mark them complete merely because this PR was opened.

Validation

All Go commands use the companion test repository overlay. Passed:

../core-tests/overlay.sh . -- -tags=test -count=1 ./internal/operatorcontrols/... ./internal/blobstore/... ./internal/llm/... ./internal/smtp/... ./internal/middleware/... ./internal/restapi/v2/...
../core-tests/overlay.sh . -- -tags=test -count=1 -run 'Test(Operator|Script|Condition|Attachment|.*LDAP|.*Action|.*Import|.*Channel|.*Setup)' ./internal/services/... ./internal/handlers/... ./internal/repository/... ./internal/server/...
../core-tests/overlay.sh . -- -tags=test -race -count=1 -run 'TestOperator|TestScriptEngine' ./internal/operatorcontrols/... ./internal/blobstore/... ./internal/services/... ./internal/handlers/... ./internal/repository/... ./internal/middleware/... ./internal/llm/... ./internal/smtp/... ./internal/ldap/... ./internal/restapi/v2/...
../core-tests/overlay.sh . -- -tags=test -count=1 ./internal/auth/... ./internal/ldap/...
  • PostgreSQL TestOperator suites passed across repository/services/handlers/SMTP/LLM/middleware with TEST_DB_TYPE=postgres, a local disposable-schema DSN and -p=1. Parallel schema creation initially exhausted local PostgreSQL shared lock memory (53200); serial package execution passed without weakening assertions. Final script-blocker inventory also passed on both SQLite and PostgreSQL.
  • make lint and all pre-commit checks passed: Go/static/architecture guards, canonical metadata/OpenAPI reproducibility and client smoke compilation, full frontend checks, locale parity and Svelte check. Initial Svelte validation had zero errors/warnings; after main integration it has zero errors and two upstream warnings.
  • Rendered Vitest: OperatorControls, SecuritySettings, AttachmentSettings — 8 tests passed, via VITEST_RUNTIME=bun ../core-tests/run-overlay-script.sh . scripts/run-frontend-tests.sh ....
  • Policy-enabled Chromium: WINDSHIFT_OPERATOR_POLICY=<test-fixture> E2E_KEEP_ARTIFACTS=1 ../core-tests/run-e2e.sh tests/operator-controls.spec.ts — setup + 2 browser tests passed, including reload and restricted direct navigation. The runner builds app, embed bundle and Go binary.
  • Browser validation found and fixed a missing bearer scope and SQLite blocker-inventory ordering; targeted regressions cover both.

Not claimed: full repository Go/frontend/browser suites, fleet stress/capacity testing or production provider qualification.

Deployment safety / external gates

The restrictive example keeps unqualified AI, mail and imports disabled. Enabling optional services still requires operator qualification:

  • Actual relay suppression/bounce/complaint enforcement. The explicit relay confirmation is not a substitute for testing the provider account.
  • Per-model AI envelope including retries, media, framing and hidden tokens. Serialized byte bounds are not a universal tokenizer or spend guarantee.
  • Exclusive single-writer ownership of the storage root/S3 prefix; backups/version history and database/WAL/temp space need external hard limits.
  • Shared local-host lock mount for imports, or an injected qualified fleet implementation. File locks are not cross-host fencing; unknown readiness totals are not zero-cost estimates.
  • Existing network/TLS/plugin opt-ins, CPU/I/O/memory and provisioning controls remain deployment responsibilities. Script timeout/concurrency is not memory isolation.

No production policy file, relay credentials, internal admission directory or planning documents are committed.

@github-actions

Copy link
Copy Markdown

Size Change: 0 B 🆕

Total Size: 0 B

compressed-size-action

@github-actions

Copy link
Copy Markdown

This PR has merge conflicts that need to be resolved before it can be merged. Please rebase on the latest main branch.

@stefan-ernst

Copy link
Copy Markdown
Contributor Author

Re-review at 13d21077

Blocker: needs another main integration

main is now 23 commits ahead of this branch's integration base (f496f1a9), and GitHub reports the PR CONFLICTING/DIRTY again. The conflicts are the usual append-only pair:

  • internal/database/migrations.go — branch adds 20261113_operator_usage, main adds 20261125_session_remember_me.
  • internal/restapi/v2/router.go — branch adds OperatorControls to Deps, main adds PasskeyLogin / PasskeyLoginLimiter.

I resolved both locally by keeping both sides (no semantic overlap), and after that:

  • go build ./internal/... ./cmd/... passes.
  • go run ./scripts/openapi-v2-metadata -check and go run ./scripts/openapi-v2-generate -spec api/openapi-v2.json -check are both reproducible, so the generated metadata/OpenAPI survive the merge once the conflicts are resolved.

Please do the integration on the branch and re-run the recorded validation. main moved through passkey login, design-system accessibility remediation and new migrations, so the earlier validation does not cover the new base.

Companion tests also need a test-main re-integration

The test branch (3363cec5) does not compile against current app main: internal/restapi/v2/router_test.go fakes are missing fakeComments.CreateContext and fakeActions.GetRevision, which test-main added. I merged current test-main into the test branch, resolved the fakeTimers.StopActiveTimer conflict, and then the focused operator packages pass against the merged app tree:

./internal/operatorcontrols/... ./internal/blobstore/... ./internal/llm/...
./internal/smtp/... ./internal/middleware/... ./internal/restapi/v2/...   → all ok

Note: ./internal/services/... cannot currently build with -tags=test on the merged test branch due to a pre-existing import cycle on test-main — internal/services/user_preferences_week_start_test.go (package services) imports internal/testutils/factory, which imports internal/services. I confirmed the same failure on a clean test-main checkout, so it is upstream of this PR, but it means the "broader affected services" command in the PR body is not reproducible right now and that claim should be re-verified once the cycle is fixed.

Finding: /api/features is public and now returns the full operator snapshot

FeaturesHandler.Snapshot() sets OperatorControls: h.controls.Snapshot(), and GET /api/features is registered without auth in internal/routes/admin.go. Snapshot includes limits (concurrent requests/streams, requests/min, script timeout, attachment/blob ceilings, daily automation/mail/AI token ceilings), ai_models and ai_denied_features — not just the deny list the shell UI needs.

If the intent is only "which capabilities are restricted", consider exposing deny + mail mode/suspension on the public response and keeping the numeric limits and model allowlists on the authenticated /api/v2/operator-controls (or the authenticated shell-bootstrap). Otherwise this is an intentional capacity disclosure and should be called out explicitly in internal/operatorcontrols/README.md.

Looks good

  • The v2 endpoint is correctly gated by requireSystemAdmin plus the admin:operator-controls:read bearer scope, and the scope is registered in the catalog.
  • DeniedError/LimitError are mapped to 403/429/413 in both the legacy respondInternalError and v2 writeError, with Retry-After on 429.
  • The budget and quota SQL is fail-closed: atomic ON CONFLICT ... WHERE used <= ceiling - amount reservation, refund guarded by used >= amount, and reconciliation re-inventory on ambiguous writes.
  • Diagnostics/plugin/AI/LDAP/mail gates are enforced server-side, not just in the UI.

Once the two rebases land and the full recorded suite is re-run, I don't see anything else blocking.

@github-actions github-actions Bot removed the conflict label Nov 16, 2026
@github-actions

Copy link
Copy Markdown

Merge conflicts have been resolved.

@stefan-ernst

Copy link
Copy Markdown
Contributor Author

Review findings addressed

Pushed both existing branches to origin: application 6f6f3c75, companion tests 1b23db17 (PR #52). Application PR: #509.

  • Integrated application main (b5a35add) and companion test main (21c39ce0); preserved both migrations, passkey dependencies, operator controls, and current timer/comment/action fakes. Both branches now include their current base without rewriting history.
  • /api/features and its shell-bootstrap projection now expose only effective deny plus mail mode/suspension. A dedicated public response type excludes numeric ceilings, AI model/feature policy, output bounds, and import admission status. The system-admin-only v2 endpoint retains the complete policy on both mounts.
  • Added exact public JSON regression coverage for omitted, empty, configured, and disabled-mail policies. Confirmed it failed on the original exposure before applying the fix. Strengthened both authenticated mounts' coverage to compare the complete policy while retaining exact non-admin 403 assertions.
  • Fixed the reported upstream services-test import cycle using an external test package. Compilation then exposed two stale action-service constructor calls; aligned those calls with current production interfaces and retained the rollback test's injected-failure assertion.

Revalidated after integration

All passed:

go build ./internal/... ./cmd/...
make lint
make openapi-v2-check

../core-tests/overlay.sh . -- -tags=test -count=1 ./internal/operatorcontrols/... ./internal/blobstore/... ./internal/llm/... ./internal/smtp/... ./internal/middleware/... ./internal/restapi/v2/...

../core-tests/overlay.sh . -- -tags=test -count=1 -run 'Test(Operator|Script|Condition|Attachment|.*LDAP|.*Action|.*Import|.*Channel|.*Setup)' ./internal/services/... ./internal/handlers/... ./internal/repository/... ./internal/server/...

../core-tests/overlay.sh . -- -tags=test -race -count=1 -run 'TestOperator|TestScriptEngine' ./internal/operatorcontrols/... ./internal/blobstore/... ./internal/services/... ./internal/handlers/... ./internal/repository/... ./internal/middleware/... ./internal/llm/... ./internal/smtp/... ./internal/ldap/... ./internal/restapi/v2/...

TEST_DB_TYPE=postgres TEST_POSTGRES_DSN="$LOCAL_DISPOSABLE_SCHEMA_DSN" ../core-tests/overlay.sh . -- -tags=test -p=1 -count=1 -run TestOperator ./internal/repository/... ./internal/services/... ./internal/handlers/... ./internal/smtp/... ./internal/llm/... ./internal/middleware/... ./internal/restapi/v2/...

../core-tests/overlay.sh . -- -tags=test -count=1 ./internal/auth/... ./internal/ldap/...

../core-tests/overlay.sh . -- -tags=test -count=1 -run 'Test(WeekStartPreferences|ActionDefinitionServiceResolvesCapabilitiesByType|ApplyActionTemplateRollsBackOnGraphWriteFailure)' ./internal/services/...

VITEST_RUNTIME=bun ../core-tests/run-overlay-script.sh . scripts/run-frontend-tests.sh src/lib/settings/OperatorControls.test.js src/lib/settings/SecuritySettings.test.js src/lib/settings/AttachmentSettings.test.js

WINDSHIFT_OPERATOR_POLICY="$PWD/../core-tests/e2e/fixtures/operator-policy.json" E2E_KEEP_ARTIFACTS=1 ../core-tests/run-e2e.sh tests/operator-controls.spec.ts
  • Frontend bun run check, bun run check:inline-styles, and bun run typecheck passed. Biome excludes Svelte files; Svelte check has zero errors and three warnings.
  • All application pre-commit checks passed, including schema/migration pairing, Go/static guards, OpenAPI generation/reproducibility/client smoke, frontend checks and inline-style guard.
  • Rendered frontend: 8 tests passed. Chromium: setup + 2 tests passed, no skips or retries, with both frontend bundles and the embedded Go server rebuilt.
  • The initial browser build/typecheck found a stale local dependency installation after integrating main; refreshing from the committed npm lockfile resolved the missing tailwind-merge package. No lockfile migration was made.

Not run/claimed: full repository Go/frontend/browser suites, fleet/load testing, or production relay/AI/storage/import qualification. Both PRs still need to merge together; no epic/story closure is claimed.

@stefan-ernst
stefan-ernst merged commit e7b2944 into main Nov 16, 2026
22 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant