Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
76 changes: 76 additions & 0 deletions docs/tenant-governance.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,76 @@
# Tenant governance

`TENANT_GOVERNANCE_ENABLED` is off by default. Empty values are off. Invalid values
produce one warning without logging the value and are treated as off. When disabled,
key controls, budgets, routing and usage keep their existing behaviour; the governance
administration endpoints return 404. Legacy principals keep that behaviour when enabled.

The server supplies a verified `TenantContext` through a registered `tenant_resolver`
and an organisation role through `membership_role(principal_id, org_id)`. The default
resolver uses the enterprise legacy authority; the default membership role grants no
permissions. Request headers and JSON fields cannot choose an organisation or role.

## Grants and permissions

The key grant, organisation grant and team grant must all allow a model or tool.
A missing ancestor row or a null grant adds no restriction. An empty array denies
everything at that level. Patterns are case insensitive; `*` matches any characters.
The same model intersection applies to automatic route candidates and model-free
provider calls. A provider call without a model requires a whole-provider grant.

Organisation administrators can edit grants and budgets and read workspace usage.
Billing members can read budgets and workspace usage. Members can read their own
workspace usage. These endpoints cannot edit roles or memberships.

`GET /admin/organisations/<org_id>/governance` and
`GET /admin/organisations/<org_id>/teams/<team_id>/governance` require an administrator
dashboard session and an appropriate organisation membership. Their `PUT` counterparts
also require CSRF and the quoted revision in `If-Match`. Missing revisions return 428;
stale revisions return 412. Responses expose the successor revision as `ETag`.

Example policy body with governance enabled:

```json
{"models":["openai:*"],"tools":["search"],"daily":1000000,"monthly":20000000}
```

Budget values are non-negative integer micro-USD, below 9,007,199,254,740,991.
`PUT` replaces the policy: omitted fields become null. It does not add to a grant.
Audits contain identifiers, revision, operation kind and time, without policy content.

## Monetary reservations and usage

An enabled workspace admission reserves the estimate against the key, organisation
and team together. Daily periods use UTC dates; monthly periods use UTC calendar
months. A zero budget denies admission. Existing key spending seeds its period
baseline. Unpriced requests return 503 `unpriced_reservation`. An ancestor limit
returns 429 `tenant_budget_exceeded` with the rejecting level; a key limit keeps
`budget_exceeded`. Rejected admission creates no reservation or component.

Measured completion settles all components atomically. Unknown cost retains the
conservative estimate at every level, including across period changes; holds do
not expire automatically. Pre-dispatch cancellation can release a reservation.
Settlement is idempotent and cannot replace a settled cost with a different amount.
Actual cost can exceed the admission estimate; configure conservative pricing and
output bounds. Estimates and measured gateway costs are not provider invoices.

`GET /v1/usage` includes `workspace` only for enabled workspace callers. Its history,
model totals and daily totals use that verified workspace, without reading unscoped
legacy history. Members see their own records; administrators and billing members
see workspace totals plus organisation and selected-team totals. Model rows identify
the actual model, provider and price basis. Results have at most 200 model groups
and 90 daily groups. Usage and audits contain no prompts or response content.

Apply `0034_tenant_governance.sql` before enabling governance. The migration creates
only new tables and indexes and can be rehearsed against existing rows. A missing
table, column or unavailable authority returns JSON 503
`tenant_governance_unavailable` before admission. No permissive fallback is used.

The D1 domain is mounted only behind the authenticated private dispatcher at
`http://intelligence.internal/v1/tenant-governance`. Native admission uses
`createGovernanceLifecycle` with verified tenant and key decisions, integer price
estimates, dispatch and finalization hooks. Flask uses the same domain through
`D1GovernanceStore`; `SQLiteGovernanceStore` supports explicitly injected connection
factories and database transactions. Neither adapter applies migrations automatically.
Storage failure prevents new admissions; ambiguous settlement leaves the hold in place.
Retention and any reconciliation of unknown holds require an operator policy.
30 changes: 30 additions & 0 deletions intelligence-migrations/0034_tenant_governance.sql
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
CREATE TABLE IF NOT EXISTS tenant_governance_policies (
org_id TEXT NOT NULL, team_id TEXT NOT NULL DEFAULT '', revision INTEGER NOT NULL DEFAULT 0,
models TEXT, tools TEXT, daily INTEGER CHECK (daily IS NULL OR daily >= 0),
monthly INTEGER CHECK (monthly IS NULL OR monthly >= 0), PRIMARY KEY (org_id, team_id)
);
CREATE TABLE IF NOT EXISTS tenant_governance_reservations (
id TEXT PRIMARY KEY, principal_id TEXT NOT NULL, org_id TEXT NOT NULL, team_id TEXT NOT NULL DEFAULT '',
day TEXT NOT NULL, month TEXT NOT NULL, estimate INTEGER NOT NULL CHECK (estimate >= 0),
charged INTEGER, state TEXT NOT NULL CHECK (state IN ('reserved','dispatched','unknown','settled')),
revision INTEGER NOT NULL DEFAULT 0, provider TEXT, model TEXT, price_basis TEXT,
created_at TEXT NOT NULL, operation_id TEXT NOT NULL
);
CREATE TABLE IF NOT EXISTS tenant_governance_components (
reservation_id TEXT NOT NULL REFERENCES tenant_governance_reservations(id),
level TEXT NOT NULL, scope_org TEXT NOT NULL, scope_id TEXT NOT NULL,
period_kind TEXT NOT NULL, period TEXT NOT NULL, limit_units INTEGER,
PRIMARY KEY (reservation_id, level, scope_org, scope_id, period_kind)
);
CREATE INDEX IF NOT EXISTS tenant_governance_component_scope
ON tenant_governance_components(level, scope_org, scope_id, period_kind, period);
CREATE INDEX IF NOT EXISTS tenant_governance_usage_scope
ON tenant_governance_reservations(org_id, team_id, principal_id, day);
CREATE TABLE IF NOT EXISTS tenant_governance_baselines (
principal_id TEXT NOT NULL, period TEXT NOT NULL, amount INTEGER NOT NULL,
PRIMARY KEY (principal_id, period)
);
CREATE TABLE IF NOT EXISTS tenant_governance_audit (
operation_id TEXT PRIMARY KEY, actor TEXT NOT NULL, org_id TEXT NOT NULL, team_id TEXT NOT NULL DEFAULT '',
revision INTEGER NOT NULL, kind TEXT NOT NULL, at TEXT NOT NULL
);
2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@
"lint": "ruff check . --select E9,F63,F7,F82",
"typecheck": "mypy --ignore-missing-imports --follow-imports=skip --disable-error-code import-untyped --disable-error-code var-annotated --disable-error-code arg-type --disable-error-code assignment --disable-error-code operator app.py routes services providers streaming",
"test": "python -m pytest -q",
"test:worker": "node --test tests/test_cloudflare_worker.mjs tests/test_cascades_worker.mjs tests/test_cascades_dashboard.mjs tests/test_image_quality_worker.mjs tests/test_secret_scan_worker.mjs tests/test_secret_firewall_worker.mjs tests/test_secret_firewall_coverage_worker.mjs tests/test_roleplay_compaction_budget_worker.mjs tests/test_roleplay_compaction_model_worker.mjs tests/test_roleplay_stream_validation_worker.mjs tests/test_aihubmix_worker.mjs tests/test_gpt_image_moderation_worker.mjs tests/test_dashboard_scripts.mjs tests/test_operations_dashboard.mjs tests/test_opencode_reasoning_worker.mjs tests/test_opencode_thinking_worker.mjs tests/test_nanogpt_reasoning_worker.mjs tests/test_nanogpt_speed_routing_worker.mjs tests/test_sse_heartbeat_worker.mjs tests/test_roleplay_worker.mjs tests/test_roleplay_config_worker.mjs tests/test_roleplay_glm_failover_worker.mjs tests/test_roleplay_intelligence_worker.mjs tests/test_roleplay_memory_worker.mjs tests/test_roleplay_compatibility_worker.mjs tests/test_roleplay_history_reconciliation_worker.mjs tests/test_roleplay_output_contract_analysis.mjs tests/test_roleplay_output_contract_cleanup_worker.mjs tests/test_roleplay_output_contract_nonstream_worker.mjs tests/test_roleplay_output_contract_worker.mjs tests/test_roleplay_performance_worker.mjs tests/test_roleplay_quality_routing_worker.mjs tests/test_roleplay_reasoning_worker.mjs tests/test_roleplay_session_storage_worker.mjs tests/test_roleplay_transport_failure_worker.mjs tests/test_roleplay_unlimited_worker.mjs tests/test_roleplay_workbench_worker.mjs tests/test_roleplay_candidate_context_worker.mjs tests/test_roleplay_operator_worker.mjs tests/test_workbench_stream.mjs tests/test_intelligence_worker.mjs tests/test_intelligence_d1_worker.mjs tests/test_intelligence_auth_worker.mjs tests/test_intelligence_outbound_worker.mjs tests/test_intelligence_operator.mjs tests/test_control_users_worker.mjs tests/test_control_audit_worker.mjs tests/test_access_sso_worker.mjs tests/test_d1_schema_worker.mjs tests/test_shadow_eval_worker.mjs tests/test_auto_routes_worker.mjs tests/test_ai_outbound_worker.mjs tests/test_knowledge_*.mjs tests/test_control_state_worker.mjs tests/test_route_health_worker.mjs tests/test_gateway_mcp_worker.mjs tests/test_usage_ledger_worker.mjs tests/test_media_outbound_worker.mjs tests/test_media_files_worker.mjs tests/test_media_jobs_worker.mjs tests/test_tool_repair_worker.mjs tests/test_prometheus_worker.mjs tests/test_evaluation_noise_floor_worker.mjs tests/test_prompt_templates_worker.mjs tests/test_config_snapshots_worker.mjs tests/test_managed_idempotency_worker.mjs tests/test_wave3_hub_worker.mjs tests/test_wave3_transport_worker.mjs tests/test_admission_leases_worker.mjs tests/test_edge_request_metrics_worker.mjs tests/test_request_cancellation_worker.mjs tests/test_mcp_contract_drift_worker.mjs tests/test_zero_content_retention_worker.mjs tests/test_prompt_cache_cost_worker.mjs tests/test_config_revision_sync_worker.mjs tests/test_gateway_alerts_worker.mjs tests/test_session_tiers_worker.mjs tests/test_usage_reservations_worker.mjs tests/test_shared_generation_cache_worker.mjs tests/test_deferred_tools_worker.mjs tests/test_generation_deadline_worker.mjs tests/test_wave4_worker.mjs tests/test_responses_state_worker.mjs tests/test_gateway_batches_worker.mjs tests/test_semantic_generation_cache_worker.mjs tests/test_canary_traffic_worker.mjs tests/test_context_pages_worker.mjs tests/test_observability_exports_worker.mjs tests/test_prompt_injection_worker.mjs tests/test_pii_rehydration_worker.mjs tests/test_wave5_worker.mjs tests/test_usage_receipts_worker.mjs tests/test_learned_cooldown_worker.mjs tests/test_stream_cost_breaker_worker.mjs tests/test_realtime_worker.mjs tests/test_latency_slo_worker.mjs tests/test_context_canary_worker.mjs tests/test_enterprise_contracts_worker.mjs tests/test_wave6_worker.mjs tests/test_tenant_hierarchy_worker.mjs",
"test:worker": "node --test tests/test_cloudflare_worker.mjs tests/test_cascades_worker.mjs tests/test_cascades_dashboard.mjs tests/test_image_quality_worker.mjs tests/test_secret_scan_worker.mjs tests/test_secret_firewall_worker.mjs tests/test_secret_firewall_coverage_worker.mjs tests/test_roleplay_compaction_budget_worker.mjs tests/test_roleplay_compaction_model_worker.mjs tests/test_roleplay_stream_validation_worker.mjs tests/test_aihubmix_worker.mjs tests/test_gpt_image_moderation_worker.mjs tests/test_dashboard_scripts.mjs tests/test_operations_dashboard.mjs tests/test_opencode_reasoning_worker.mjs tests/test_opencode_thinking_worker.mjs tests/test_nanogpt_reasoning_worker.mjs tests/test_nanogpt_speed_routing_worker.mjs tests/test_sse_heartbeat_worker.mjs tests/test_roleplay_worker.mjs tests/test_roleplay_config_worker.mjs tests/test_roleplay_glm_failover_worker.mjs tests/test_roleplay_intelligence_worker.mjs tests/test_roleplay_memory_worker.mjs tests/test_roleplay_compatibility_worker.mjs tests/test_roleplay_history_reconciliation_worker.mjs tests/test_roleplay_output_contract_analysis.mjs tests/test_roleplay_output_contract_cleanup_worker.mjs tests/test_roleplay_output_contract_nonstream_worker.mjs tests/test_roleplay_output_contract_worker.mjs tests/test_roleplay_performance_worker.mjs tests/test_roleplay_quality_routing_worker.mjs tests/test_roleplay_reasoning_worker.mjs tests/test_roleplay_session_storage_worker.mjs tests/test_roleplay_transport_failure_worker.mjs tests/test_roleplay_unlimited_worker.mjs tests/test_roleplay_workbench_worker.mjs tests/test_roleplay_candidate_context_worker.mjs tests/test_roleplay_operator_worker.mjs tests/test_workbench_stream.mjs tests/test_intelligence_worker.mjs tests/test_intelligence_d1_worker.mjs tests/test_intelligence_auth_worker.mjs tests/test_intelligence_outbound_worker.mjs tests/test_intelligence_operator.mjs tests/test_control_users_worker.mjs tests/test_control_audit_worker.mjs tests/test_access_sso_worker.mjs tests/test_d1_schema_worker.mjs tests/test_shadow_eval_worker.mjs tests/test_auto_routes_worker.mjs tests/test_ai_outbound_worker.mjs tests/test_knowledge_*.mjs tests/test_control_state_worker.mjs tests/test_route_health_worker.mjs tests/test_gateway_mcp_worker.mjs tests/test_usage_ledger_worker.mjs tests/test_media_outbound_worker.mjs tests/test_media_files_worker.mjs tests/test_media_jobs_worker.mjs tests/test_tool_repair_worker.mjs tests/test_prometheus_worker.mjs tests/test_evaluation_noise_floor_worker.mjs tests/test_prompt_templates_worker.mjs tests/test_config_snapshots_worker.mjs tests/test_managed_idempotency_worker.mjs tests/test_wave3_hub_worker.mjs tests/test_wave3_transport_worker.mjs tests/test_admission_leases_worker.mjs tests/test_edge_request_metrics_worker.mjs tests/test_request_cancellation_worker.mjs tests/test_mcp_contract_drift_worker.mjs tests/test_zero_content_retention_worker.mjs tests/test_prompt_cache_cost_worker.mjs tests/test_config_revision_sync_worker.mjs tests/test_gateway_alerts_worker.mjs tests/test_session_tiers_worker.mjs tests/test_usage_reservations_worker.mjs tests/test_shared_generation_cache_worker.mjs tests/test_deferred_tools_worker.mjs tests/test_generation_deadline_worker.mjs tests/test_wave4_worker.mjs tests/test_responses_state_worker.mjs tests/test_gateway_batches_worker.mjs tests/test_semantic_generation_cache_worker.mjs tests/test_canary_traffic_worker.mjs tests/test_context_pages_worker.mjs tests/test_observability_exports_worker.mjs tests/test_prompt_injection_worker.mjs tests/test_pii_rehydration_worker.mjs tests/test_wave5_worker.mjs tests/test_usage_receipts_worker.mjs tests/test_learned_cooldown_worker.mjs tests/test_stream_cost_breaker_worker.mjs tests/test_realtime_worker.mjs tests/test_latency_slo_worker.mjs tests/test_context_canary_worker.mjs tests/test_enterprise_contracts_worker.mjs tests/test_wave6_worker.mjs tests/test_tenant_governance_worker.mjs tests/test_tenant_hierarchy_worker.mjs",
"db:migrate": "python scripts/validate_sqlite_schema.py --apply",
"db:validate": "python scripts/validate_sqlite_schema.py",
"security:secrets": "python scripts/check_static_secrets.py",
Expand Down
Loading
Loading