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
2 changes: 2 additions & 0 deletions app.py
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,7 @@
)
from routes.config_snapshots import register_config_snapshot_routes
from routes.enterprise_preview import register_enterprise_preview_routes
from routes.tenants import register_tenant_routes
from routes.core import register_core_routes
from routes.dashboard_security import register_dashboard_security_routes
from routes.intelligence_media import register_intelligence_media_routes
Expand Down Expand Up @@ -147,6 +148,7 @@ def create_app() -> Flask:
register_workbench_routes(app)
register_config_snapshot_routes(app)
register_enterprise_preview_routes(app)
register_tenant_routes(app, csrf=csrf)
register_shadow_eval_routes(app, csrf, AuthService, MetricsService, ProxyService)
register_knowledge_routes(app, csrf)
register_gateway_mcp_routes(app, csrf)
Expand Down
109 changes: 109 additions & 0 deletions docs/tenant-hierarchy.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,109 @@
# Organisations and teams

`ORGANISATIONS_ENABLED` is off by default. Empty values mean off. Malformed values
mean off and produce one warning without the value. With the feature off, the
organisation and workspace endpoints return JSON 404 with `Cache-Control: no-store`
before authentication, CSRF checks or JSON parsing. Existing accounts, key records,
provider traffic and storage formats remain unchanged. Every principal has the
legacy tenant context and an empty namespace.

Enable with `ORGANISATIONS_ENABLED=true` only after applying
`intelligence-migrations/0033_tenant_hierarchy.sql` to the configured account SQLite
database, or to D1 when `INTELLIGENCE_STORAGE_BACKEND=d1`. Missing tables or columns
return JSON 503 `tenant_storage_unavailable`, including for accounts without a
binding. There is no storage fallback or automatic account migration.

The hierarchy has exactly two levels: organisation and team. IDs are generated,
opaque and immutable. Names may have up to 200 characters. Status is `active` or
`deactivated`. Each organisation retains at most 100 teams and 1,000 memberships,
including deactivated rows. The limit returns 409 `tenant_limit_reached`.
Membership roles are `admin`, `billing` and `member`; these labels do not grant
access to the gateway administrator dashboard. Each membership links an existing
account to one organisation and optionally one team in that organisation.

## Administration

The existing administrator dashboard session and CSRF token protect these routes:

- `GET /admin/organisations` lists organisations; `POST` creates one with
`{"name":"Example"}` and returns 201.
- `GET /admin/organisations/<org_id>` reads one; `PATCH` changes its name or status.
- `GET /admin/organisations/<org_id>/teams` lists teams; `POST` creates one with a name.
- `PATCH /admin/organisations/<org_id>/teams/<team_id>` changes a team's name or status.
- `GET /admin/organisations/<org_id>/members` lists memberships.
- `PUT /admin/organisations/<org_id>/members/<principal>` sets role, team and status.

All updates require `If-Match: "<revision>"`. A new membership requires `"0"`;
existing resources start at revision 1. Missing revisions return 428
`revision_required`; malformed revisions return 400 `invalid_revision`; stale
revisions return 412 `revision_conflict`. Resource and binding responses expose
`ETag: "<revision>"`. Each successful update increments the revision. Team creation
does not change its parent organisation's revision.

For example, to grant a team membership and explicitly select it for that account,
PUT a membership with `If-Match: "0"` and this body, using IDs returned by creation:

```json
{"role":"member","team_id":"<team_id>","status":"active","bind":true,"binding_revision":0}
```

`binding_revision` is the account's current binding revision (zero when unbound).
The membership, binding and audit rows commit together. A stale binding revision
leaves both old records intact. Set `status` to `deactivated` to revoke access;
rows and IDs remain stored. There is no deletion endpoint. Every successful
mutation records actor, action, target IDs, old/new revisions and UTC time. Audit
records exclude names, request bodies, keys and provider content.

## Workspaces

`GET /v1/workspaces` uses a gateway key with the `models` scope and returns only
its active memberships plus its current binding. Administrators also hold this
scope. Unbound accounts have binding revision zero and remain in the legacy
namespace even when they have memberships.

`POST /v1/workspaces/switch` uses the same key and scope, requires
`If-Match: "<binding_revision>"`, and accepts exactly
`{"org_id":"<org_id>","team_id":"<team_id>"}`. Use `null` for an organisation-only
membership. The caller can select only its own active membership and its exact
team. The stored binding applies to the next request; existing request contexts
are unchanged. Dashboard CSRF applies to admin mutations; gateway-key workspace
selection uses the existing API CSRF exemption.

Knowledge and Realtime resolve the workspace only after verifying the credential
for one principal. Accounts sharing a key prefix do not resolve each other's
workspaces. Their authenticated principals carry the validated `tenant_context`;
with organisations off, resolution returns the legacy context without querying
tenant storage.

Resolution uses server storage and ignores `X-Org`, `X-Team`,
`X-MultiLLM-Workspace` and tenant fields in provider request bodies. A missing or
foreign organisation/team is 404 `workspace_not_found`; a deactivated
organisation/team, revoked membership or mismatched membership team is 403
`workspace_forbidden`. A rejected binding prevents provider dispatch and later
policy, cache, claim and admission hooks. An administrator can repair a revoked
binding through the members endpoint. No automatic reparenting takes place.

Python consumers use `current_tenant()` and `tenant_namespace()` from
`services.tenant_hierarchy`; native consumers use the validated `TenantContext`
from the tenant resolver. Namespaces are `org:<id>` or `org:<id>/team:<id>`; the
legacy namespace is the empty string. Resolution rereads authoritative revisions
every request and has no process-local tenant cache.

## Operational limits

The private D1 domain is POST-only at
`http://intelligence.internal/v1/managed-state/tenants`, with a maximum request
size of 8,192 bytes. Writes use conditional SQL and an atomic batch with their
audit rows. Private Flask calls have bounded concurrency and wall time and never
replay an uncertain write. Standalone SQLite uses the configured account database
and serializes writes with an immediate transaction.

Workspace identity does not introduce quotas, credits, payment collection, cost
allocation or provider discounts. Existing cache, idempotency, hosted-state and
usage ownership formats remain unchanged; a tenant binding alone does not isolate
those records. Consumers must incorporate the verified namespace before using
organisation isolation for shared records. Existing record ownership never moves
because an account selects a workspace. Audit and hierarchy rows are retained
indefinitely; content-retention policies do not erase them. Deactivation keeps
rows and continues to count toward the caps. There are no live-provider capability
or metering guarantees from these APIs.
30 changes: 30 additions & 0 deletions intelligence-migrations/0033_tenant_hierarchy.sql
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
-- Optional two-level hierarchy; existing accounts and owned records are unchanged.
CREATE TABLE IF NOT EXISTS tenant_organisations (
id TEXT PRIMARY KEY, name TEXT NOT NULL,
status TEXT NOT NULL CHECK (status IN ('active', 'deactivated')),
revision INTEGER NOT NULL CHECK (revision >= 1)
);
CREATE TABLE IF NOT EXISTS tenant_teams (
id TEXT PRIMARY KEY, org_id TEXT NOT NULL, name TEXT NOT NULL,
status TEXT NOT NULL CHECK (status IN ('active', 'deactivated')),
revision INTEGER NOT NULL CHECK (revision >= 1)
);
CREATE INDEX IF NOT EXISTS tenant_teams_org ON tenant_teams (org_id, id);
CREATE TABLE IF NOT EXISTS tenant_memberships (
org_id TEXT NOT NULL, principal TEXT NOT NULL, team_id TEXT,
role TEXT NOT NULL CHECK (role IN ('admin', 'billing', 'member')),
status TEXT NOT NULL CHECK (status IN ('active', 'deactivated')),
revision INTEGER NOT NULL CHECK (revision >= 1),
PRIMARY KEY (org_id, principal)
);
CREATE INDEX IF NOT EXISTS tenant_memberships_principal ON tenant_memberships (principal, org_id);
CREATE TABLE IF NOT EXISTS tenant_bindings (
principal TEXT PRIMARY KEY, org_id TEXT NOT NULL, team_id TEXT,
revision INTEGER NOT NULL CHECK (revision >= 1)
);
CREATE TABLE IF NOT EXISTS tenant_audit (
id TEXT PRIMARY KEY, actor TEXT NOT NULL, action TEXT NOT NULL,
org_id TEXT, team_id TEXT, principal TEXT,
old_revision INTEGER NOT NULL, new_revision INTEGER NOT NULL, at TEXT NOT NULL
);
CREATE INDEX IF NOT EXISTS tenant_audit_time ON tenant_audit (at, id);
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",
"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",
"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