diff --git a/docs/saml-federation.md b/docs/saml-federation.md new file mode 100644 index 00000000..f221e21e --- /dev/null +++ b/docs/saml-federation.md @@ -0,0 +1,64 @@ +# SAML federation through a trusted broker + +The gateway accepts a signed identity token from an operator-run SAML broker. The broker validates the IdP response, XML signatures, destination, audience, timing and SAML request correlation. The gateway does not download IdP metadata, parse XML or implement native SAML validation. `/auth/saml/acs` and `/auth/saml/metadata` return JSON HTTP 503 `saml_native_unavailable` when federation is enabled. They do not publish an ACS descriptor. + +Federation is off by default. `SAML_ENABLED=false` or an empty value makes every `/auth/saml/*` and subject-link endpoint return HTTP 404 before session, CSRF or storage work. Existing gateway requests keep their behavior. Malformed configuration disables federation and emits one warning without configuration values. + +## Configuration + +Use an HTTPS broker URL without credentials or a fragment. Its query may contain broker-specific settings, but cannot contain `nonce`, `state` or `recipient`. Configure a fixed HTTPS callback URL ending in `/auth/saml/callback`, without a query or fragment. It is never derived from caller headers or a redirect parameter. + +```text +SAML_ENABLED=true +SAML_BROKER_URL=https://broker.example/login +SAML_CALLBACK_URL=https://gateway.example/auth/saml/callback +``` + +`SAML_TRUST_CONFIG_JSON` defaults to `{}`. An enabled deployment must supply exactly these fields: + +```json +{ + "issuer": "https://broker.example/issuer", + "audience": "gateway.example", + "keys": [ + {"kid": "broker-2026", "alg": "EdDSA", "public_key_pem": ""} + ], + "max_age_seconds": 300 +} +``` + +Each key pins one unique `kid` and exact algorithm: `RS256` with an RSA public key of at least 2048 bits, or `EdDSA` with an Ed25519 public key. There may be at most 16 keys. No private key belongs in gateway configuration. Symmetric algorithms, unsigned tokens, mismatched key types and remotely supplied key URLs are rejected. Rotate keys by temporarily pinning both public keys, then remove the old key after all assertions issued under it expire. `max_age_seconds` must be an integer from 1 to 300. The callback URL may instead be supplied as the Flask application's `SAML_CALLBACK_URL` configuration. + +## Login and callback + +`GET /auth/saml/login` stores SHA-256 digests of a random nonce, random request state and recipient with a five-minute expiry, then redirects HTTP 302 only to the configured broker. It also binds the state digest to the browser's signed dashboard session. A new login replaces that browser's active state. Caller `next` parameters are ignored. + +The broker returns one compact JWS in `token` and the request state in `state`, using `GET /auth/saml/callback` or a URL-encoded POST. Use exactly one of each field. A token must include `iss`, `aud`, `sub`, integer `iat` and `exp`, `nonce`, `state` and `recipient`. `aud` is one exact string. `state` is the original request ID; `nonce` and recipient must match the original login. A token's lifetime cannot exceed `max_age_seconds`; a fixed five-second clock skew is allowed by signature verification. Durable requests still expire at five minutes without extending their claim lifetime. + +The callback must retain the original browser session cookie. A top-level GET is compatible with a SameSite=Lax dashboard cookie; a cross-site POST requires an operator-reviewed secure cookie policy or a same-site broker. State binding replaces CSRF form-token validation only on the broker callback. GET tokens can appear in browser history and intermediary access logs: configure the broker and gateway edge to suppress or redact callback query strings. The gateway adds `Cache-Control: no-store` and `Referrer-Policy: no-referrer` and never stores assertion contents. + +The nonce is claimed atomically once. A replay or expired durable request returns HTTP 400 `saml_assertion_replayed`. Invalid signature, issuer, audience, key, algorithm, recipient or browser binding returns HTTP 400 `saml_assertion_invalid`. Unknown or duplicate callback fields return HTTP 400 `saml_request_invalid`. + +After verification, an active `(issuer, subject)` link must name an existing, unrevoked, unexpired gateway account. No link returns HTTP 403 `saml_subject_unlinked`; the gateway never creates accounts from broker attributes. Assertion roles, administrator flags and organisation names grant nothing. The stored link supplies organisation, team and grants revision; the injected `IdentityAuthority` must return that exact `TenantContext`. Its `IdentityAssertion` uses digests for identifiers so arbitrary broker subjects fit the enterprise opaque-ID contract. Account names outside that contract use `account:` as principal ID, while session issuance still receives the actual account name. + +The service requires a named dashboard session issuer that accepts `(account, TenantContext)` and returns `True` only after issuing the existing dashboard session. The default returns HTTP 503 `saml_session_unavailable`: API-key authentication has no separate session-creation function. The issuer must revalidate account permissions and populate the same session fields as dashboard login, using stored grants. The service uses the stored-link authority by default; an organisation authority can be injected to revalidate current membership. An unavailable authority returns HTTP 503 `saml_identity_unavailable`, and a scope mismatch returns HTTP 403 `saml_identity_denied`. + +## Administrator subject links + +These routes require an administrator dashboard session. PUT and DELETE also require the existing dashboard CSRF token. + +- `GET /admin/saml/links?offset=0` lists up to 100 links, including inactive links; use `offset` to paginate. +- `GET /admin/saml/links/` reads one link. +- `PUT /admin/saml/links` creates or updates the stable subject link. +- `PUT /admin/saml/links/` edits the same issuer/subject binding. It cannot rebind that identifier to a different subject. +- `DELETE /admin/saml/links/` deactivates the link and retains its row and audit history. + +PUT accepts `issuer`, `subject`, `account`, and optional `org_id`, `team_id`, `grants_revision`. `issuer` must equal the configured issuer. A team requires an organisation. Tenant IDs use the enterprise opaque-ID format. Omitting scope fields selects the linked account's legacy scope. Account existence is checked by the service and again against durable dashboard accounts in the private handler. Link identifiers are stable 32-character hex digests. Only issuer and subject digests are persisted, so operators must retain their own subject-to-account mapping outside the gateway. + +## Storage, audit and operational bounds + +Apply `0035_saml_federation.sql` to D1 before enabling federation. It adds `saml_requests`, `saml_subject_links` and `saml_audit` and preserves existing accounts. The private handler is `handleSamlIdentityRequest` at `http://intelligence.internal/v1/managed-state/saml`. Its dispatcher and private client endpoint must be registered, and `register_saml_federation_routes(app, csrf)` must be mounted. The core login guard must include `SAML_PUBLIC_ENDPOINTS` in its public endpoint allowlist. The link routes retain their administrator guard. Until storage wiring is available, login fails closed. + +Every private operation validates the required tables and columns before changing state. Missing storage or a missing migration returns JSON HTTP 503 `saml_storage_unavailable` without admitting login. There is no local-memory identity fallback or automatic replay of uncertain writes. Login audit records contain an issuer digest, linked account if known, outcome and time. `authorized` means signature, link and authority checks passed before session issuance; a later session failure adds its failure outcome. Link changes also record the operator's digest. Neither audit nor nonce rows contain tokens, raw subjects, nonce or request state. + +Assertions are limited to 16 KiB; private RPC bodies to 8 KiB; trust configuration to 64 KiB; subjects to 1,024 characters. Expiry prevents reuse but does not delete request rows. No automatic audit or link pruning is performed: retention and database capacity are operator responsibilities. Retain inactive links and their audit history. D1 operations and external broker hosting may incur their normal charges; this feature makes no model-provider calls and defines no additional billing rate. Live IdP compatibility, deployment and native XML validation require separate operational verification. diff --git a/intelligence-migrations/0035_saml_federation.sql b/intelligence-migrations/0035_saml_federation.sql new file mode 100644 index 00000000..340b701a --- /dev/null +++ b/intelligence-migrations/0035_saml_federation.sql @@ -0,0 +1,36 @@ +CREATE TABLE IF NOT EXISTS saml_requests ( + state_digest TEXT PRIMARY KEY, + nonce_digest TEXT NOT NULL, + recipient_digest TEXT NOT NULL, + created_at INTEGER NOT NULL, + expires_at INTEGER NOT NULL, + claimed_at INTEGER, + CHECK(expires_at > created_at AND expires_at <= created_at + 300) +); +CREATE INDEX IF NOT EXISTS idx_saml_requests_expiry ON saml_requests(expires_at); + +CREATE TABLE IF NOT EXISTS saml_subject_links ( + id TEXT PRIMARY KEY, + issuer_digest TEXT NOT NULL, + subject_digest TEXT NOT NULL, + account TEXT NOT NULL REFERENCES control_users(username), + org_id TEXT, + team_id TEXT, + grants_revision INTEGER NOT NULL DEFAULT 0 CHECK(grants_revision >= 0), + active INTEGER NOT NULL DEFAULT 1 CHECK(active IN (0, 1)), + created_at INTEGER NOT NULL, + updated_at INTEGER NOT NULL, + CHECK(team_id IS NULL OR org_id IS NOT NULL), + UNIQUE(issuer_digest, subject_digest) +); +CREATE INDEX IF NOT EXISTS idx_saml_subject_links_account ON saml_subject_links(account, active); + +CREATE TABLE IF NOT EXISTS saml_audit ( + id TEXT PRIMARY KEY, + issuer_digest TEXT NOT NULL, + account TEXT, + actor_digest TEXT, + outcome TEXT NOT NULL, + occurred_at INTEGER NOT NULL +); +CREATE INDEX IF NOT EXISTS idx_saml_audit_time ON saml_audit(occurred_at); diff --git a/package.json b/package.json index f67d9891..ab0e00fa 100644 --- a/package.json +++ b/package.json @@ -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_governance_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_saml_federation_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", diff --git a/routes/saml_federation.py b/routes/saml_federation.py new file mode 100644 index 00000000..ca4f5cd4 --- /dev/null +++ b/routes/saml_federation.py @@ -0,0 +1,115 @@ +"""Broker callback and administrator-managed subject links.""" +from copy import deepcopy +from functools import wraps + +from flask import jsonify, redirect, request, session + +from services.saml_federation import MAX_TOKEN_BYTES, SamlError, SamlFederation, load_config + +SAML_PUBLIC_ENDPOINTS = frozenset({"saml_login", "saml_callback", "saml_acs", "saml_metadata"}) + + +def admin_dashboard_user(): + from services.auth_service import AuthService + if not AuthService.is_authenticated(): + raise SamlError("authentication_required", 401) + user = AuthService.get_current_user() + if not user or not user.get("is_admin"): + raise SamlError("admin_required", 403) + return user + + +def register_saml_federation_routes(app, csrf): + service = app.extensions.get("saml_federation") + if service is None: + service = SamlFederation(load_config(callback_url=app.config.get("SAML_CALLBACK_URL"))) + app.extensions["saml_federation"] = service + + def guarded(view): + @wraps(view) + def wrapped(*args, **kwargs): + try: + return view(*args, **kwargs) + except SamlError as error: + return jsonify(error.envelope()), error.status + return wrapped + + def gate(): + if request.path.startswith("/auth/saml/") or request.path == "/admin/saml/links" or request.path.startswith("/admin/saml/links/"): + if not service.config.enabled: + return jsonify({"error": "not_found"}), 404 + if request.content_length is not None and request.content_length > MAX_TOKEN_BYTES + 2048: + return jsonify(SamlError("saml_request_invalid").envelope()), 400 + return None + + app.before_request_funcs.setdefault(None, []).insert(0, gate) + + @app.after_request + def private_saml_response(response): + if request.path.startswith("/auth/saml/") or request.path.startswith("/admin/saml/links"): + response.headers["Cache-Control"] = "no-store" + response.headers["Referrer-Policy"] = "no-referrer" + return response + + @app.get("/auth/saml/login") + @guarded + def saml_login(): + destination, state_digest = service.begin() + session["saml_state_digest"] = state_digest + return redirect(destination, code=302) + + @app.route("/auth/saml/callback", methods=["GET", "POST"]) + @csrf.exempt + @guarded + def saml_callback(): + values = request.args if request.method == "GET" else request.form + if set(values) != {"token", "state"} or any(len(values.getlist(key)) != 1 for key in values): + raise SamlError("saml_request_invalid") + browser_state_digest = session.get("saml_state_digest", "") + original_session = deepcopy(dict(session)) + try: + service.complete(values["token"], values["state"], browser_state_digest) + except SamlError: + session.clear() + session.update(original_session) + raise + session["saml_state_digest"] = browser_state_digest + return redirect("/", code=302) + + @app.route("/auth/saml/acs", methods=["GET", "POST"]) + @csrf.exempt + @guarded + def saml_acs(): + raise SamlError("saml_native_unavailable", 503) + + @app.get("/auth/saml/metadata") + @guarded + def saml_metadata(): + raise SamlError("saml_native_unavailable", 503) + + @app.route("/admin/saml/links", methods=["GET", "PUT"]) + @guarded + def saml_links(): + user = admin_dashboard_user() + if request.method == "GET": + offset = request.args.get("offset", "0") + if not offset.isascii() or not offset.isdigit() or len(offset) > 6: + raise SamlError("saml_link_invalid") + return jsonify(service.list_links(int(offset))) + csrf.protect() + return jsonify(service.put_link(request.get_json(silent=True), user["username"])) + + @app.route("/admin/saml/links/", methods=["GET", "PUT", "DELETE"]) + @guarded + def saml_link(identifier): + user = admin_dashboard_user() + if request.method == "GET": + result = service.get_link(identifier) + linked = result.get("link") + if linked is None: + raise SamlError("saml_link_not_found", 404) + return jsonify({"version": 1, "link": linked}) + csrf.protect() + if request.method == "PUT": + return jsonify(service.put_link(request.get_json(silent=True), user["username"], identifier)) + return jsonify(service.deactivate_link(identifier, user["username"])) diff --git a/services/saml_federation.py b/services/saml_federation.py new file mode 100644 index 00000000..3ad1065e --- /dev/null +++ b/services/saml_federation.py @@ -0,0 +1,366 @@ +"""Pinned broker JWS verification and durable, explicitly linked identity.""" +from __future__ import annotations + +import base64 +import hashlib +import hmac +import json +import logging +import os +import re +import secrets +import time +from dataclasses import dataclass +from datetime import datetime, timezone +from functools import lru_cache +from typing import Callable, Mapping +from urllib.parse import parse_qsl, urlencode, urlsplit, urlunsplit + +from cryptography.exceptions import InvalidSignature, UnsupportedAlgorithm +from cryptography.hazmat.primitives import hashes, serialization +from cryptography.hazmat.primitives.asymmetric import ed25519, padding, rsa + +from services.enterprise_contract import AuthorityDenied, AuthorityOperation, IdentityAssertion, IdentityAuthority, TenantContext + +logger = logging.getLogger(__name__) +MAX_AGE = 300 +CLOCK_SKEW = 5 +MAX_TOKEN_BYTES = 16384 +PRIVATE_ENDPOINT = "saml" +OPAQUE = re.compile(r"[A-Za-z0-9_:.\-]{1,128}\Z") +RANDOM = re.compile(r"[A-Za-z0-9_-]{43}\Z") +DIGEST = re.compile(r"[a-f0-9]{64}\Z") +LINK_ID = re.compile(r"[a-f0-9]{32}\Z") + + +class SamlError(Exception): + def __init__(self, code: str, status: int = 400): + super().__init__(code) + self.code, self.status = code, status + + def envelope(self) -> dict: + return {"error": {"code": self.code, "message": "SAML federation request could not be completed.", "retryable": False}} + + +def digest(value: str) -> str: + return hashlib.sha256(value.encode("utf-8")).hexdigest() + + +def _text(value: object, maximum: int = 1024) -> bool: + if not isinstance(value, str) or not 0 < len(value) <= maximum or re.search(r"[\x00-\x1f\x7f]", value): + return False + try: + value.encode("utf-8") + return True + except UnicodeError: + return False + + +def _json(value: str) -> dict: + def unique(pairs): + result = {} + for key, item in pairs: + if key in result: + raise ValueError("Duplicate JSON key") + result[key] = item + return result + result = json.loads(value, object_pairs_hook=unique, parse_constant=lambda _: (_ for _ in ()).throw(ValueError("Invalid number"))) + if not isinstance(result, dict): + raise ValueError("JSON object required") + return result + + +def _https(value: object, *, callback: bool = False) -> str: + if not isinstance(value, str) or not _text(value, 2048) or any(character.isspace() for character in value) or "\\" in value: + raise ValueError("Invalid HTTPS target") + url = urlsplit(value) + if (url.scheme != "https" or not url.hostname or url.username is not None or url.password is not None + or url.fragment or url.port == 0): + raise ValueError("Invalid HTTPS target") + if callback: + if url.path != "/auth/saml/callback" or url.query: + raise ValueError("Invalid callback target") + elif any(key in {"nonce", "state", "recipient"} for key, _ in parse_qsl(url.query, keep_blank_values=True)): + raise ValueError("Reserved broker query parameter") + return value + + +@lru_cache(maxsize=1) +def _warn_once() -> None: + logger.warning("Invalid SAML federation configuration; federation disabled") + + +@dataclass(frozen=True) +class TrustKey: + alg: str + public_key: object + + +@dataclass(frozen=True) +class SamlConfig: + enabled: bool = False + broker_url: str = "" + callback_url: str = "" + issuer: str = "" + audience: str = "" + keys: Mapping[str, TrustKey] | None = None + max_age_seconds: int = MAX_AGE + + +def load_config(env: Mapping[str, str] | None = None, *, callback_url: str | None = None) -> SamlConfig: + env = os.environ if env is None else env + flag = env.get("SAML_ENABLED", "") + flag = flag.strip().lower() if isinstance(flag, str) else "invalid" + if flag in {"", "0", "false", "no", "off"}: + return SamlConfig() + if flag not in {"1", "true", "yes", "on"}: + _warn_once() + return SamlConfig() + try: + broker = _https(env.get("SAML_BROKER_URL", "")) + callback = _https(callback_url if callback_url is not None else env.get("SAML_CALLBACK_URL", ""), callback=True) + raw = env.get("SAML_TRUST_CONFIG_JSON", "") or "{}" + if not isinstance(raw, str) or len(raw) > 65536: + raise ValueError("Invalid trust document") + trust = _json(raw) + if set(trust) != {"issuer", "audience", "keys", "max_age_seconds"}: + raise ValueError("Invalid trust fields") + age = trust["max_age_seconds"] + if not _text(trust["issuer"]) or not _text(trust["audience"]) or type(age) is not int or not 1 <= age <= MAX_AGE: + raise ValueError("Invalid trust bounds") + if not isinstance(trust["keys"], list) or not 1 <= len(trust["keys"]) <= 16: + raise ValueError("Pinned keys required") + keys = {} + for entry in trust["keys"]: + if not isinstance(entry, dict) or set(entry) != {"kid", "alg", "public_key_pem"}: + raise ValueError("Invalid key fields") + pem = entry["public_key_pem"] + if (not _text(entry["kid"], 128) or entry["kid"] in keys or not isinstance(pem, str) + or not 1 <= len(pem) <= 8192): + raise ValueError("Invalid pinned key") + key = serialization.load_pem_public_key(entry["public_key_pem"].encode("ascii")) + alg = entry["alg"] + if not ((alg == "RS256" and isinstance(key, rsa.RSAPublicKey) and key.key_size >= 2048) + or (alg == "EdDSA" and isinstance(key, ed25519.Ed25519PublicKey))): + raise ValueError("Invalid pinned algorithm") + keys[entry["kid"]] = TrustKey(alg, key) + return SamlConfig(True, broker, callback, trust["issuer"], trust["audience"], keys, age) + except (ValueError, TypeError, UnicodeError, KeyError, RecursionError, UnsupportedAlgorithm): + _warn_once() + return SamlConfig() + + +def _decode(segment: str) -> bytes: + if not re.fullmatch(r"[A-Za-z0-9_-]+", segment): + raise ValueError("Invalid compact JWS") + result = base64.urlsafe_b64decode(segment + "=" * (-len(segment) % 4)) + if base64.urlsafe_b64encode(result).rstrip(b"=").decode() != segment: + raise ValueError("Noncanonical compact JWS") + return result + + +def verify_assertion(token: str, config: SamlConfig, now: int) -> dict: + """Verify only configured asymmetric keys; assertion attributes grant nothing.""" + try: + if not config.enabled or not isinstance(token, str) or len(token) > MAX_TOKEN_BYTES: + raise ValueError("Invalid token") + head, payload, signature = token.split(".") + header = _json(_decode(head).decode("utf-8")) + if set(header) - {"kid", "alg", "typ"} or header.get("typ", "JWT") != "JWT": + raise ValueError("Unsupported JWS header") + key = (config.keys or {}).get(header.get("kid")) + if key is None or header.get("alg") != key.alg: + raise ValueError("Unpinned key or algorithm") + signed_bytes = (head + "." + payload).encode("ascii") + if key.alg == "RS256" and isinstance(key.public_key, rsa.RSAPublicKey): + key.public_key.verify(_decode(signature), signed_bytes, padding.PKCS1v15(), hashes.SHA256()) + elif key.alg == "EdDSA" and isinstance(key.public_key, ed25519.Ed25519PublicKey): + key.public_key.verify(_decode(signature), signed_bytes) + else: + raise ValueError("Unsupported key") + claims = _json(_decode(payload).decode("utf-8")) + iat, exp = claims.get("iat"), claims.get("exp") + if (type(iat) is not int or type(exp) is not int or iat < 0 or exp >= 9007199254740991 + or not 0 < exp - iat <= config.max_age_seconds or iat > now + CLOCK_SKEW + or exp <= now - CLOCK_SKEW or now - iat > config.max_age_seconds + CLOCK_SKEW): + raise ValueError("Invalid assertion time") + if (claims.get("iss") != config.issuer or claims.get("aud") != config.audience + or claims.get("recipient") != config.callback_url or not _text(claims.get("sub")) + or not isinstance(claims.get("nonce"), str) or not RANDOM.fullmatch(claims["nonce"]) + or not isinstance(claims.get("state"), str) or not RANDOM.fullmatch(claims["state"])): + raise ValueError("Invalid assertion binding") + if "nbf" in claims and (type(claims["nbf"]) is not int or claims["nbf"] > now + CLOCK_SKEW): + raise ValueError("Assertion not active") + return claims + except (ValueError, TypeError, UnicodeError, KeyError, InvalidSignature, RecursionError): + raise SamlError("saml_assertion_invalid") from None + + +class SamlStore: + """Fixed private RPC operations, without volatile identity fallback or retries.""" + def __init__(self, call: Callable | None = None): + self._call = call + + def call(self, operation: str, **values) -> dict: + try: + body = {"version": 1, "operation": operation, **values} + if self._call is None: + from services.intelligence_d1_store import request_private_intelligence + result = request_private_intelligence(body, endpoint=PRIVATE_ENDPOINT) + else: + result = self._call(body) + if not isinstance(result, dict) or type(result.get("version")) is not int or result.get("version") != 1 or "error" in result: + raise ValueError("Invalid storage reply") + return result + except Exception: + raise SamlError("saml_storage_unavailable", 503) from None + + def ready(self) -> None: + if self.call("ready").get("ready") is not True: + raise SamlError("saml_storage_unavailable", 503) + + +def lookup_gateway_account(account: str) -> dict | None: + from services.auth_service import AuthService + return AuthService.get_user_record(account) + + +def issue_dashboard_session(account: str, context: TenantContext) -> bool: + """An explicit session collaborator is required when no standalone issuer exists.""" + raise SamlError("saml_session_unavailable", 503) + + +def _active_account(record: object, account: str, now: int) -> bool: + if not isinstance(record, dict) or record.get("username") != account or record.get("revoked_at"): + return False + expires = record.get("expires_at") + if expires: + try: + instant = datetime.fromisoformat(expires.replace("Z", "+00:00")) + if instant.tzinfo is None: + instant = instant.replace(tzinfo=timezone.utc) + return instant.timestamp() > now + except (TypeError, ValueError, AttributeError): + return False + return True + + +def stored_link_authority(assertion: IdentityAssertion, operation: AuthorityOperation) -> TenantContext: + """The caller constructs the context only from the active stored subject link.""" + if assertion.verified is not True: + raise AuthorityDenied("identity_unverified") + return operation.context + + +class SamlFederation: + def __init__(self, config: SamlConfig, store: SamlStore | None = None, *, + session_issuer: Callable = issue_dashboard_session, account_lookup: Callable = lookup_gateway_account, + identity_authority: IdentityAuthority = stored_link_authority, clock: Callable = time.time): + self.config, self.store = config, store or SamlStore() + self.session_issuer, self.account_lookup = session_issuer, account_lookup + self.identity_authority, self.clock = identity_authority, clock + + def begin(self) -> tuple[str, str]: + self.store.ready() + now, nonce, state = int(self.clock()), secrets.token_urlsafe(32), secrets.token_urlsafe(32) + result = self.store.call("create_request", state_digest=digest(state), nonce_digest=digest(nonce), + recipient_digest=digest(self.config.callback_url), now=now, expires_at=now + MAX_AGE) + if result.get("created") is not True: + raise SamlError("saml_storage_unavailable", 503) + url = urlsplit(self.config.broker_url) + query = parse_qsl(url.query, keep_blank_values=True) + [("nonce", nonce), ("state", state), ("recipient", self.config.callback_url)] + return urlunsplit((url.scheme, url.netloc, url.path, urlencode(query), "")), digest(state) + + def _audit(self, outcome: str, account: str | None = None) -> None: + result = self.store.call("audit", issuer_digest=digest(self.config.issuer), account=account, outcome=outcome, now=int(self.clock())) + if result.get("recorded") is not True: + raise SamlError("saml_storage_unavailable", 503) + + def complete(self, token: str, state: str, browser_state_digest: str) -> None: + self.store.ready() + account = None + try: + now = int(self.clock()) + claims = verify_assertion(token, self.config, now) + if (not isinstance(state, str) or state != claims["state"] or not isinstance(browser_state_digest, str) + or not DIGEST.fullmatch(browser_state_digest) or not hmac.compare_digest(digest(state), browser_state_digest)): + raise SamlError("saml_assertion_invalid") + claimed = self.store.call("claim_request", state_digest=digest(state), nonce_digest=digest(claims["nonce"]), + recipient_digest=digest(self.config.callback_url), now=now) + if claimed.get("claimed") is not True: + raise SamlError("saml_assertion_replayed") + linked = self.store.call("lookup_link", issuer_digest=digest(claims["iss"]), subject_digest=digest(claims["sub"])).get("link") + if not isinstance(linked, dict) or linked.get("active") != 1: + raise SamlError("saml_subject_unlinked", 403) + account = linked["account"] + if not _active_account(self.account_lookup(account), account, now): + raise SamlError("saml_subject_unlinked", 403) + principal = account if OPAQUE.fullmatch(account) else "account:" + digest(account) + context = TenantContext(principal, linked.get("org_id"), linked.get("team_id"), linked["grants_revision"]) + assertion = IdentityAssertion(digest(claims["iss"]), digest(claims["sub"]), digest(claims["aud"]), + digest(state), digest(claims["nonce"]), claims["exp"], True) + operation = AuthorityOperation(context, linked["id"], context.grants_revision, digest(state)) + try: + resolved = self.identity_authority(assertion, operation) + if type(resolved) is not TenantContext or resolved != context: + raise AuthorityDenied("authority_scope_mismatch") + except AuthorityDenied: + raise SamlError("saml_identity_denied", 403) from None + # Record permission before session mutation so an audit outage cannot admit a login. + self._audit("authorized", account) + try: + issued = self.session_issuer(account, context) + except Exception: + raise SamlError("saml_session_unavailable", 503) from None + if issued is not True: + raise SamlError("saml_session_unavailable", 503) + except SamlError as error: + if error.code != "saml_storage_unavailable": + self._audit(error.code, account) + raise + except Exception: + self._audit("saml_identity_unavailable", account) + raise SamlError("saml_identity_unavailable", 503) from None + + def list_links(self, offset: int = 0) -> dict: + self.store.ready() + return self.store.call("list_links", offset=offset) + + def get_link(self, identifier: str) -> dict: + self.store.ready() + if not LINK_ID.fullmatch(identifier): + raise SamlError("saml_link_invalid") + return self.store.call("get_link", id=identifier) + + def put_link(self, payload: object, actor: str, identifier: str | None = None) -> dict: + self.store.ready() + allowed = {"issuer", "subject", "account", "org_id", "team_id", "grants_revision"} + if not isinstance(payload, dict) or set(payload) - allowed or not {"issuer", "subject", "account"} <= set(payload): + raise SamlError("saml_link_invalid") + if payload["issuer"] != self.config.issuer or not _text(payload["subject"]) or not _text(payload["account"], 128): + raise SamlError("saml_link_invalid") + account = payload["account"] + try: + record = self.account_lookup(account) + except Exception: + raise SamlError("saml_identity_unavailable", 503) from None + if not _active_account(record, account, int(self.clock())): + raise SamlError("saml_subject_unlinked", 403) + try: + principal = account if OPAQUE.fullmatch(account) else "account:" + digest(account) + context = TenantContext(principal, payload.get("org_id"), payload.get("team_id"), payload.get("grants_revision", 0)) + if identifier is not None and not LINK_ID.fullmatch(identifier): + raise ValueError("Invalid link identifier") + except (ValueError, TypeError): + raise SamlError("saml_link_invalid") from None + # A subject has one stable link ID; edits retain its audit history. + identifier = identifier or digest(self.config.issuer + "\0" + payload["subject"])[:32] + linked = {"id": identifier, "issuer_digest": digest(payload["issuer"]), "subject_digest": digest(payload["subject"]), + "account": account, "org_id": context.org_id, "team_id": context.team_id, "grants_revision": context.grants_revision} + return self.store.call("put_link", link=linked, actor=actor, now=int(self.clock())) + + def deactivate_link(self, identifier: str, actor: str) -> dict: + self.store.ready() + if not LINK_ID.fullmatch(identifier): + raise SamlError("saml_link_invalid") + return self.store.call("deactivate_link", id=identifier, actor=actor, now=int(self.clock())) diff --git a/tests/fixtures/secret_firewall_coverage.json b/tests/fixtures/secret_firewall_coverage.json index 247914c7..a4b13a9f 100644 --- a/tests/fixtures/secret_firewall_coverage.json +++ b/tests/fixtures/secret_firewall_coverage.json @@ -161,6 +161,14 @@ "routes/responses_state.py": [ "app.route('/v1/responses/', methods=['GET', 'DELETE'])" ], + "routes/saml_federation.py": [ + "app.get('/auth/saml/login')", + "app.get('/auth/saml/metadata')", + "app.route('/admin/saml/links', methods=['GET', 'PUT'])", + "app.route('/admin/saml/links/', methods=['GET', 'PUT', 'DELETE'])", + "app.route('/auth/saml/acs', methods=['GET', 'POST'])", + "app.route('/auth/saml/callback', methods=['GET', 'POST'])" + ], "routes/shadow_eval.py": [ "app.get('/admin/workbench/shadow/league')", "app.get('/admin/workbench/shadow/samples')", @@ -410,6 +418,7 @@ "worker/roleplay/turn-trace.mjs", "worker/roleplay/validation.mjs", "worker/route-health-d1.mjs", + "worker/saml-identity.mjs", "worker/scheduled-maintenance.mjs", "worker/secret-digest.mjs", "worker/secret-firewall.mjs", diff --git a/tests/test_saml_federation.py b/tests/test_saml_federation.py new file mode 100644 index 00000000..e2a9a856 --- /dev/null +++ b/tests/test_saml_federation.py @@ -0,0 +1,408 @@ +"""Broker assertions are verified before durable identity or session work.""" +import base64 +import importlib +import json +import threading +from concurrent.futures import ThreadPoolExecutor +from urllib.parse import parse_qs, urlsplit +from unittest.mock import Mock, patch + +import pytest +from cryptography.hazmat.primitives import hashes, serialization +from cryptography.hazmat.primitives.asymmetric import ed25519, padding, rsa +from flask import Flask, Response, session +from flask_wtf.csrf import CSRFProtect, generate_csrf + +from services import saml_federation as saml +from services.enterprise_contract import TenantContext +from routes.saml_federation import SAML_PUBLIC_ENDPOINTS, register_saml_federation_routes + +NOW = 1_800_000_000 +CALLBACK = "https://gateway.example/auth/saml/callback" +ISSUER = "https://broker.example/issuer" +AUDIENCE = "gateway.example" + + +class Store: + def __init__(self): + self.requests, self.links, self.audit, self.calls = {}, {}, [], [] + self.lock = threading.Lock() + self.available = True + + def __call__(self, body): + with self.lock: + self.calls.append(body) + if not self.available: + raise RuntimeError("private storage detail") + op = body["operation"] + if op == "ready": + return {"version": 1, "ready": True} + if op == "create_request": + self.requests[body["state_digest"]] = {**body, "claimed_at": None} + return {"version": 1, "created": True} + if op == "claim_request": + row = self.requests.get(body["state_digest"]) + ok = row and row["nonce_digest"] == body["nonce_digest"] and row["recipient_digest"] == body["recipient_digest"] and row["expires_at"] > body["now"] and row["claimed_at"] is None + if ok: + row["claimed_at"] = body["now"] + return {"version": 1, "claimed": bool(ok)} + if op == "lookup_link": + link = next((row for row in self.links.values() if row["issuer_digest"] == body["issuer_digest"] and row["subject_digest"] == body["subject_digest"] and row["active"]), None) + return {"version": 1, "link": link} + if op == "list_links": + return {"version": 1, "links": list(self.links.values())} + if op == "get_link": + return {"version": 1, "link": self.links.get(body["id"])} + if op == "put_link": + self.links[body["link"]["id"]] = {**body["link"], "active": 1} + self.audit.append(body) + return {"version": 1, "link": self.links[body["link"]["id"]]} + if op == "deactivate_link": + link = self.links.get(body["id"]) + if link: + link["active"] = 0 + self.audit.append(body) + return {"version": 1, "deactivated": bool(link)} + if op == "audit": + self.audit.append(body) + return {"version": 1, "recorded": True} + raise AssertionError(op) + + +@pytest.fixture(params=["EdDSA", "RS256"]) +def signer(request): + key = ed25519.Ed25519PrivateKey.generate() if request.param == "EdDSA" else rsa.generate_private_key(public_exponent=65537, key_size=2048) + pem = key.public_key().public_bytes(serialization.Encoding.PEM, serialization.PublicFormat.SubjectPublicKeyInfo).decode() + return request.param, key, pem + + +def settings(signer, **changes): + alg, _, pem = signer + return {"SAML_ENABLED": "true", "SAML_BROKER_URL": "https://broker.example/login?realm=enterprise", "SAML_CALLBACK_URL": CALLBACK, + "SAML_TRUST_CONFIG_JSON": json.dumps({"issuer": ISSUER, "audience": AUDIENCE, "keys": [{"kid": "pinned", "alg": alg, "public_key_pem": pem}], "max_age_seconds": 300}), **changes} + + +def signed(signer, claims, **header_changes): + alg, key, _ = signer + encode = lambda value: base64.urlsafe_b64encode(json.dumps(value, separators=(",", ":")).encode()).rstrip(b"=") + data = encode({"alg": alg, "kid": "pinned", "typ": "JWT", **header_changes}) + b"." + encode(claims) + signature = key.sign(data) if alg == "EdDSA" else key.sign(data, padding.PKCS1v15(), hashes.SHA256()) + return (data + b"." + base64.urlsafe_b64encode(signature).rstrip(b"=")).decode() + + +@pytest.fixture +def registered(monkeypatch, signer): + env = settings(signer) + for key in ("SAML_ENABLED", "SAML_BROKER_URL", "SAML_CALLBACK_URL", "SAML_TRUST_CONFIG_JSON"): + monkeypatch.setenv(key, env[key]) + app = Flask(__name__) + app.config.update(SECRET_KEY="synthetic-saml-session", TESTING=True, WTF_CSRF_ENABLED=False) + csrf = CSRFProtect(app) + store, issue = Store(), Mock(return_value=True) + accounts = {"alice": {"username": "alice", "is_admin": False, "scopes": ["chat"], "revoked_at": None, "expires_at": None}} + service = saml.SamlFederation(saml.load_config(env), saml.SamlStore(store), session_issuer=issue, account_lookup=accounts.get, clock=lambda: NOW) + app.extensions["saml_federation"] = service + register_saml_federation_routes(app, csrf) + route_globals = register_saml_federation_routes.__globals__ + monkeypatch.setitem(route_globals, "admin_dashboard_user", lambda: {"username": "operator", "is_admin": True}) + app.add_url_rule("/csrf-fixture", view_func=lambda: {"token": generate_csrf()}) + return app, app.test_client(), service, store, issue, accounts, route_globals + + +def start(client): + response = client.get("/auth/saml/login?next=https://attacker.example") + assert response.status_code == 302 + url = urlsplit(response.location) + assert (url.scheme, url.netloc, url.path) == ("https", "broker.example", "/login") + query = parse_qs(url.query) + assert "next" not in query + return {"iss": ISSUER, "aud": AUDIENCE, "sub": "external:alice", "iat": NOW, "exp": NOW + 300, + "nonce": query["nonce"][0], "state": query["state"][0], "recipient": CALLBACK, "is_admin": True, "org_id": "foreign"} + + +def link(service, **changes): + return service.put_link({"issuer": ISSUER, "subject": "external:alice", "account": "alice", "org_id": "org:one", "team_id": "team:one", "grants_revision": 2, **changes}, "operator") + + +def callback(client, signer, claims, method="GET", **headers): + values = {"token": signed(signer, claims, **headers), "state": claims["state"]} + return client.get("/auth/saml/callback", query_string=values) if method == "GET" else client.post("/auth/saml/callback", data=values) + + +@pytest.mark.parametrize("flag", ["", "false", "0", "malformed"]) +def test_disabled_routes_before_auth_csrf_and_storage(registered, flag): + app, client, service, store, _, _, _ = registered + service.config = saml.load_config({"SAML_ENABLED": flag}) + app.config["WTF_CSRF_ENABLED"] = True + for path in ("login", "callback", "acs", "metadata", "unknown"): + for method in ("GET", "POST"): + assert client.open("/auth/saml/" + path, method=method).status_code == 404 + assert client.put("/admin/saml/links", json={}).status_code == 404 + assert store.calls == [] + + +def test_existing_response_is_unchanged(monkeypatch): + monkeypatch.setenv("SAML_ENABLED", "") + def baseline(): + app = Flask(__name__) + app.add_url_rule("/raw", view_func=lambda: Response(b"unchanged bytes", headers={"X-Existing": "same"})) + return app + before = baseline().test_client().get("/raw") + app = baseline() + register_saml_federation_routes(app, CSRFProtect()) + after = app.test_client().get("/raw") + assert (before.data, list(before.headers)) == (after.data, list(after.headers)) + + +@pytest.mark.parametrize("change", [{"SAML_BROKER_URL": "http://broker.example"}, {"SAML_BROKER_URL": "https://user:pass@broker.example"}, {"SAML_BROKER_URL": "https://broker.example/#fragment"}, {"SAML_BROKER_URL": "https://broker.example?nonce=bad"}, {"SAML_CALLBACK_URL": ""}, {"SAML_TRUST_CONFIG_JSON": "{}"}, {"SAML_TRUST_CONFIG_JSON": "private-invalid"}]) +def test_config_invalid_is_off_and_logs_once_without_values(signer, change, caplog): + saml._warn_once.cache_clear() + for _ in range(2): + assert not saml.load_config(settings(signer, **change)).enabled + assert len(caplog.records) == 1 + assert "private-invalid" not in caplog.text and "user:pass" not in caplog.text + + +@pytest.mark.parametrize("method", ["GET", "POST"]) +def test_valid_assertion_uses_only_existing_account_and_bound_authority(registered, signer, method): + _, client, service, store, issue, _, _ = registered + link(service) + claims = start(client) + authority = Mock(side_effect=lambda assertion, operation: operation.context) + service.identity_authority = authority + response = callback(client, signer, claims, method) + assert response.status_code == 302 and response.location == "/" + issue.assert_called_once_with("alice", TenantContext("alice", "org:one", "team:one", 2)) + assertion, operation = authority.call_args.args + assert assertion.verified and operation.context.org_id == "org:one" + assert response.headers["Cache-Control"] == "no-store" + content = json.dumps(store.requests) + json.dumps(store.audit) + assert claims["nonce"] not in content and claims["state"] not in content and "external:alice" not in content + assert callback(client, signer, claims).json["error"]["code"] == "saml_assertion_replayed" + assert issue.call_count == 1 + + +@pytest.mark.parametrize("change", [{"iss": "other"}, {"aud": "other"}, {"aud": [AUDIENCE, "other"]}, {"nonce": "wrong"}, {"recipient": "https://attacker.example"}, {"exp": NOW - 10}, {"iat": NOW + 20}, {"exp": NOW + 301}, {"iat": True}, {"exp": 1.2}, {"sub": ""}]) +def test_invalid_claims_never_issue_session(registered, signer, change): + _, client, service, _, issue, _, _ = registered + link(service) + response = callback(client, signer, {**start(client), **change}) + assert response.status_code == 400 + issue.assert_not_called() + + +@pytest.mark.parametrize("headers", [{"kid": "unknown"}, {"alg": "none"}, {"alg": "HS256"}, {"alg": "RS512"}, {"crit": ["private"]}, {"jku": "https://attacker.example"}]) +def test_untrusted_headers_are_rejected(registered, signer, headers): + _, client, service, _, issue, _, _ = registered + link(service) + assert callback(client, signer, start(client), **headers).status_code == 400 + issue.assert_not_called() + + +def test_signature_and_browser_binding_are_required(registered, signer): + app, client, service, store, issue, _, _ = registered + link(service) + claims = start(client) + token = signed(signer, claims) + head, body, sig = token.split(".") + assert client.get("/auth/saml/callback", query_string={"token": head + "." + body + "." + ("A" if sig[0] != "A" else "B") + sig[1:], "state": claims["state"]}).status_code == 400 + assert app.test_client().get("/auth/saml/callback", query_string={"token": token, "state": claims["state"]}).status_code == 400 + assert all(row["claimed_at"] is None for row in store.requests.values()) + issue.assert_not_called() + + +def test_unlinked_inactive_and_foreign_authority_cannot_grant(registered, signer): + _, client, service, store, issue, _, _ = registered + assert callback(client, signer, start(client)).json["error"]["code"] == "saml_subject_unlinked" + saved = link(service) + service.deactivate_link(saved["link"]["id"], "operator") + assert callback(client, signer, start(client)).status_code == 403 + link(service) + service.identity_authority = lambda *_: TenantContext("alice", "foreign") + assert callback(client, signer, start(client)).status_code == 403 + issue.assert_not_called() + assert store.links + + +def test_missing_storage_and_session_fail_closed(registered, signer): + _, client, service, store, issue, _, _ = registered + link(service) + claims = start(client) + store.available = False + for response in (client.get("/auth/saml/login"), callback(client, signer, claims), client.get("/admin/saml/links")): + assert response.status_code == 503 and response.json["error"]["code"] == "saml_storage_unavailable" + assert b"private storage" not in response.data + issue.assert_not_called() + store.available = True + service.session_issuer = saml.issue_dashboard_session + response = callback(client, signer, claims) + assert response.status_code == 503 and response.json["error"]["code"] == "saml_session_unavailable" + + +def test_revoked_or_missing_account_has_no_session(registered, signer): + _, client, service, _, issue, accounts, _ = registered + link(service) + accounts["alice"]["revoked_at"] = "2026-01-01" + assert callback(client, signer, start(client)).status_code == 403 + accounts.clear() + assert callback(client, signer, start(client)).status_code == 403 + issue.assert_not_called() + + +def test_admin_links_require_session_and_csrf_and_keep_history(registered): + app, client, _, store, _, _, route_module = registered + app.config["WTF_CSRF_ENABLED"] = True + payload = {"issuer": ISSUER, "subject": "external:alice", "account": "alice"} + assert client.put("/admin/saml/links", json=payload).status_code == 400 + token = client.get("/csrf-fixture").json["token"] + response = client.put("/admin/saml/links", json=payload, headers={"X-CSRFToken": token}) + assert response.status_code == 200 + identifier = response.json["link"]["id"] + assert client.delete("/admin/saml/links/" + identifier, headers={"X-CSRFToken": token}).json["deactivated"] + assert store.links[identifier]["active"] == 0 + route_module["admin_dashboard_user"] = Mock(side_effect=saml.SamlError("admin_required", 403)) + assert client.get("/admin/saml/links").status_code == 403 + assert len(store.audit) == 2 + + +def test_native_endpoints_never_claim_readiness(registered): + _, client, _, _, issue, _, _ = registered + for path in ("acs", "metadata"): + response = client.get("/auth/saml/" + path) + assert response.status_code == 503 and response.json["error"]["code"] == "saml_native_unavailable" + issue.assert_not_called() + + +def test_atomic_replay_claim(registered, signer): + _, client, service, _, issue, _, _ = registered + link(service) + claims = start(client) + def consume(_): + try: + service.complete(signed(signer, claims), claims["state"], saml.digest(claims["state"])) + return 200 + except saml.SamlError as error: + return error.status + with ThreadPoolExecutor(max_workers=2) as pool: + assert sorted(pool.map(consume, range(2))) == [200, 400] + assert issue.call_count == 1 + + +def test_session_issuer_failure_restores_browser_session(registered, signer): + _, client, service, _, _, _, _ = registered + link(service) + claims = start(client) + def partial_issue(*_): + session.clear() + session["authenticated"] = True + raise RuntimeError("private session detail") + service.session_issuer = partial_issue + response = callback(client, signer, claims) + assert response.status_code == 503 and response.json["error"]["code"] == "saml_session_unavailable" + with client.session_transaction() as saved: + assert "authenticated" not in saved and saved["saml_state_digest"] == saml.digest(claims["state"]) + assert b"private session detail" not in response.data + + +def test_audit_failure_prevents_session_issue(registered, signer): + _, client, service, store, issue, _, _ = registered + link(service) + original_call = store.__call__ + def failed_audit(body): + if body["operation"] == "audit": + raise RuntimeError("audit unavailable") + return original_call(body) + service.store = saml.SamlStore(failed_audit) + assert callback(client, signer, start(client)).json["error"]["code"] == "saml_storage_unavailable" + issue.assert_not_called() + + +def test_expired_request_cannot_use_fresh_token(registered, signer): + _, client, service, _, issue, _, _ = registered + link(service) + claims = start(client) + service.clock = lambda: NOW + 301 + claims.update(iat=NOW + 301, exp=NOW + 601) + response = callback(client, signer, claims) + assert response.json["error"]["code"] == "saml_assertion_replayed" + issue.assert_not_called() + + +def test_pinned_algorithm_mismatch_and_strict_trust_bounds(signer): + config = settings(signer) + trust = json.loads(config["SAML_TRUST_CONFIG_JSON"]) + for age in (0, 301, True, "300"): + assert not saml.load_config({**config, "SAML_TRUST_CONFIG_JSON": json.dumps({**trust, "max_age_seconds": age})}).enabled + for change in ({"alg": "HS256"}, {"alg": "none"}, {"alg": "RS256" if signer[0] == "EdDSA" else "EdDSA"}): + assert not saml.load_config({**config, "SAML_TRUST_CONFIG_JSON": json.dumps({**trust, "keys": [{**trust["keys"][0], **change}]})}).enabled + assert not saml.load_config({**config, "SAML_TRUST_CONFIG_JSON": json.dumps({**trust, "keys": trust["keys"] * 2})}).enabled + + +def test_request_binding_and_envelopes_cannot_be_spoofed(registered, signer): + _, client, service, _, issue, _, _ = registered + link(service) + claims = start(client) + token = signed(signer, claims) + assert client.get("/auth/saml/callback", query_string={"token": token, "state": "spoofed"}).status_code == 400 + assert client.post("/auth/saml/callback", json={"token": token, "state": claims["state"]}).status_code == 400 + assert client.get("/auth/saml/callback", query_string=[("token", token), ("token", token), ("state", claims["state"])]).status_code == 400 + assert client.get("/auth/saml/callback", query_string={"token": "x" * 17000, "state": claims["state"]}).status_code == 400 + issue.assert_not_called() + + +def test_admin_guard_requires_real_dashboard_administrator(monkeypatch): + routes = importlib.import_module(register_saml_federation_routes.__module__) + auth = importlib.import_module("services.auth_service").AuthService + monkeypatch.setattr(auth, "is_authenticated", lambda: False) + with pytest.raises(saml.SamlError) as failed: + routes.admin_dashboard_user() + assert failed.value.status == 401 + monkeypatch.setattr(auth, "is_authenticated", lambda: True) + monkeypatch.setattr(auth, "get_current_user", lambda: {"username": "alice", "is_admin": False}) + with pytest.raises(saml.SamlError) as failed: + routes.admin_dashboard_user() + assert failed.value.status == 403 + + +def test_application_callback_with_public_endpoint_registration(monkeypatch, tmp_path, signer): + env = {**settings(signer), "FLASK_SECRET_KEY": "synthetic-saml-session", "JWT_SECRET": "synthetic-saml-jwt", + "ADMIN_API_KEY": "synthetic-saml-admin", "AUTH_DB_PATH": str(tmp_path / "auth.sqlite3"), + "MODEL_REGISTRY_DB_PATH": str(tmp_path / "models.sqlite3"), "RATE_LIMIT_DB_PATH": str(tmp_path / "limits.sqlite3"), + "INTELLIGENCE_STORAGE_BACKEND": "", "CF_ACCESS_TEAM_DOMAIN": "", "CF_ACCESS_SSO_ONLY": "false"} + for key, value in env.items(): + monkeypatch.setenv(key, value) + with patch("config.load_runtime_env"), patch("env_loader.load_runtime_env"), patch("services.usage_ledger.start"), \ + patch("requests.Session.send", side_effect=AssertionError("No network")): + module = importlib.import_module("app") + with patch.object(module, "load_runtime_env"): + app = module.create_app() + app.config.update(TESTING=True, WTF_CSRF_ENABLED=True) + accounts = {"alice": {"username": "alice", "is_admin": False, "scopes": ["chat"], "api_key_prefix": "synthetic"}} + store = Store() + def issue(account, context): + assert context == TenantContext("alice") + session.clear() + session["authenticated"] = True + session["user"] = {"username": account, "is_admin": accounts[account]["is_admin"], "scopes": accounts[account]["scopes"], + "api_key_prefix": "synthetic", "session_id": "synthetic-session"} + return True + service = saml.SamlFederation(saml.load_config(env), saml.SamlStore(store), session_issuer=issue, account_lookup=accounts.get, clock=lambda: NOW) + app.extensions["saml_federation"] = service + register_saml_federation_routes(app, app.extensions["csrf"]) + link(service, org_id=None, team_id=None, grants_revision=0) + client = app.test_client() + # Exercise the existing guard first, then the required static allowlist integration. + blocked = client.get("/auth/saml/login") + assert blocked.status_code == 302 and urlsplit(blocked.location).path == "/login" + guard = next(hook for hook in app.before_request_funcs[None] if hook.__name__ == "handle_redirects") + monkeypatch.setitem(guard.__globals__, "PRODUCT_PUBLIC_ENDPOINTS", guard.__globals__["PRODUCT_PUBLIC_ENDPOINTS"] | SAML_PUBLIC_ENDPOINTS) + headers = next(hook for hook in app.after_request_funcs[None] if hook.__name__ == "add_response_headers") + for auth in {guard.__globals__["AuthService"], headers.__globals__["AuthService"]}: + monkeypatch.setattr(auth, "_load_user_by_username", accounts.get) + claims = start(client) + response = callback(client, signer, claims, "POST") + assert response.status_code == 302 + with client.session_transaction() as saved: + assert saved["authenticated"] is True and saved["user"]["is_admin"] is False + assert saved["user"]["scopes"] == ["chat"] + assert callback(client, signer, claims).json["error"]["code"] == "saml_assertion_replayed" diff --git a/tests/test_saml_federation_worker.mjs b/tests/test_saml_federation_worker.mjs new file mode 100644 index 00000000..e8db292f --- /dev/null +++ b/tests/test_saml_federation_worker.mjs @@ -0,0 +1,143 @@ +import assert from "node:assert/strict"; +import { readFile } from "node:fs/promises"; +import { DatabaseSync } from "node:sqlite"; +import test from "node:test"; +import { handleSamlIdentityRequest } from "../worker/saml-identity.mjs"; +import { loadWorkerModule } from "./helpers/load_cloudflare_worker.mjs"; + +const hash = character => character.repeat(64); +const now = Math.floor(Date.now() / 1000); +const request = (body, url = "http://intelligence.internal/v1/managed-state/saml", headers = {}) => new Request(url, { + method: "POST", headers: { "content-type": "application/json", ...headers }, body: JSON.stringify({ version: 1, ...body }) }); + +function database(sql) { + return { prepare(query) { + let values = []; + return { bind(...args) { values = args; return this; }, first() { return sql.prepare(query).get(...values) ?? null; }, + all() { const stmt = sql.prepare(query); return stmt.columns().length ? { results: stmt.all(...values), meta: { changes: 0 } } + : { results: [], meta: { changes: Number(stmt.run(...values).changes) } }; }, run() { return this.all(); } }; + }, async batch(statements) { + sql.exec("BEGIN IMMEDIATE"); + try { const result = statements.map(statement => statement.all()); sql.exec("COMMIT"); return result; } + catch (error) { sql.exec("ROLLBACK"); throw error; } + } }; +} + +async function fixture(t) { + const sql = new DatabaseSync(":memory:"); t.after(() => sql.close()); + sql.exec(await readFile(new URL("../intelligence-migrations/0003_control_users.sql", import.meta.url), "utf8")); + sql.prepare("INSERT INTO control_users(username,api_key_hash,api_key_prefix,scopes,created_at) VALUES(?,?,?,?,?)").run("alice", "synthetic", "synthetic", "chat", "2026-01-01"); + const migration = await readFile(new URL("../intelligence-migrations/0035_saml_federation.sql", import.meta.url), "utf8"); + sql.exec(migration); sql.exec(migration); + const env = { SAML_ENABLED: "true", INTELLIGENCE_DB: database(sql) }; + return { sql, env, call: (body, settings = env) => handleSamlIdentityRequest(request(body), settings) }; +} + +test("default-off private handler reads no body or storage", async () => { + for (const flag of [undefined, "", "false", "0"]) { + const response = await handleSamlIdentityRequest(request({ operation: "ready" }), { SAML_ENABLED: flag, + INTELLIGENCE_DB: { prepare() { assert.fail("disabled storage"); } } }); + assert.equal(response.status, 404); + } +}); + +test("nonce digests expire and concurrent claim is exactly once", async t => { + const { sql, call } = await fixture(t); + const body = { state_digest: hash("a"), nonce_digest: hash("b"), recipient_digest: hash("c"), now, expires_at: now + 300 }; + assert.equal((await call({ operation: "create_request", ...body })).status, 200); + const claim = { operation: "claim_request", state_digest: body.state_digest, nonce_digest: body.nonce_digest, recipient_digest: body.recipient_digest, now }; + assert.equal((await (await call({ ...claim, nonce_digest: hash("d") })).json()).claimed, false); + const responses = await Promise.all([call(claim), call(claim)]); + const claimed = await Promise.all(responses.map(async response => (await response.json()).claimed)); + assert.deepEqual(claimed.sort(), [false, true]); + assert.equal(sql.prepare("SELECT claimed_at FROM saml_requests").get().claimed_at, now); + assert.equal((await (await call(claim)).json()).claimed, false); + assert.equal((await call({ operation: "create_request", ...body, state_digest: hash("e"), expires_at: now + 301 })).status, 400); + await call({ operation: "create_request", ...body, state_digest: hash("f"), expires_at: now + 1 }); + assert.equal((await (await call({ ...claim, state_digest: hash("f"), now: now + 1 })).json()).claimed, false); +}); + +test("links refer to existing accounts, remain scoped and retain audit and tombstones", async t => { + const { sql, call } = await fixture(t); + const link = { id: "a".repeat(32), issuer_digest: hash("a"), subject_digest: hash("b"), account: "alice", org_id: "org:one", team_id: "team:one", grants_revision: 2 }; + const put = { operation: "put_link", link, actor: "operator", now }; + assert.equal((await call({ ...put, link: { ...link, account: "missing" } })).status, 403); + assert.equal((await call(put)).status, 200); + assert.equal((await (await call({ operation: "lookup_link", issuer_digest: hash("c"), subject_digest: hash("b") })).json()).link, null); + assert.equal((await (await call({ operation: "lookup_link", issuer_digest: hash("a"), subject_digest: hash("b") })).json()).link.team_id, "team:one"); + assert.equal((await call({ operation: "deactivate_link", id: link.id, actor: "operator", now })).status, 200); + assert.equal(sql.prepare("SELECT active FROM saml_subject_links").get().active, 0); + assert.equal(sql.prepare("SELECT COUNT(*) AS n FROM saml_audit").get().n, 2); + assert.match(sql.prepare("SELECT actor_digest FROM saml_audit LIMIT 1").get().actor_digest, /^[a-f0-9]{64}$/); + assert.equal(sql.prepare("SELECT COUNT(*) AS n FROM control_users").get().n, 1); + assert.equal((await (await call({ operation: "list_links", offset: 0 })).json()).links.length, 1); +}); + +test("missing any table fails before writes and hides storage details", async t => { + const { call } = await fixture(t); + const sql = new DatabaseSync(":memory:"); t.after(() => sql.close()); + const response = await call({ operation: "ready" }, { SAML_ENABLED: "true", INTELLIGENCE_DB: database(sql) }); + assert.equal(response.status, 503); assert.equal((await response.json()).error.code, "saml_storage_unavailable"); +}); + +for (const table of ["saml_requests", "saml_subject_links", "saml_audit"]) test("missing " + table + " refuses request creation before mutations", async t => { + const { sql, call } = await fixture(t); + sql.exec(`DROP TABLE ${table}`); + const response = await call({ operation: "create_request", state_digest: hash("a"), nonce_digest: hash("b"), recipient_digest: hash("c"), now, expires_at: now + 300 }); + assert.equal(response.status, 503); assert.equal((await response.json()).error.code, "saml_storage_unavailable"); + if (table !== "saml_requests") assert.equal(sql.prepare("SELECT COUNT(*) AS n FROM saml_requests").get().n, 0); +}); + +test("missing audit column fails before request creation", async t => { + const { sql, call } = await fixture(t); + sql.exec("ALTER TABLE saml_audit DROP COLUMN actor_digest"); + const response = await call({ operation: "create_request", state_digest: hash("a"), nonce_digest: hash("b"), recipient_digest: hash("c"), now, expires_at: now + 300 }); + assert.equal(response.status, 503); assert.equal((await response.json()).error.code, "saml_storage_unavailable"); + assert.equal(sql.prepare("SELECT COUNT(*) AS n FROM saml_requests").get().n, 0); +}); + +test("audit transaction failure rolls back a subject link and existing accounts survive migration", async t => { + const { sql, call } = await fixture(t); + sql.exec("CREATE TRIGGER refuse_audit BEFORE INSERT ON saml_audit BEGIN SELECT RAISE(ABORT, 'synthetic audit outage'); END"); + const link = { id: "a".repeat(32), issuer_digest: hash("a"), subject_digest: hash("b"), account: "alice", org_id: null, team_id: null, grants_revision: 0 }; + assert.equal((await call({ operation: "put_link", link, actor: "operator", now })).status, 503); + assert.equal(sql.prepare("SELECT COUNT(*) AS n FROM saml_subject_links").get().n, 0); + assert.equal(sql.prepare("SELECT username,scopes,is_admin FROM control_users").get().username, "alice"); + assert.equal(sql.prepare("SELECT scopes,is_admin FROM control_users").get().scopes, "chat"); + assert.equal(sql.prepare("SELECT is_admin FROM control_users").get().is_admin, 0); +}); + +test("changing a link binding cannot move its history or grant administrator attributes", async t => { + const { sql, call } = await fixture(t); + const link = { id: "a".repeat(32), issuer_digest: hash("a"), subject_digest: hash("b"), account: "alice", org_id: "org:one", team_id: null, grants_revision: 0 }; + assert.equal((await call({ operation: "put_link", link, actor: "operator", now })).status, 200); + assert.equal((await call({ operation: "put_link", link: { ...link, subject_digest: hash("c") }, actor: "operator", now })).status, 409); + assert.equal((await call({ operation: "put_link", link: { ...link, is_admin: true }, actor: "operator", now })).status, 400); + assert.equal((await call({ operation: "put_link", link: { ...link, org_id: null, team_id: "team:foreign" }, actor: "operator", now })).status, 400); + assert.equal(sql.prepare("SELECT subject_digest FROM saml_subject_links").get().subject_digest, hash("b")); + assert.equal(sql.prepare("SELECT COUNT(*) AS n FROM saml_audit").get().n, 1); +}); + +test("private target and strict bounded envelopes reject arbitrary operations", async t => { + const { call, env } = await fixture(t); + for (const url of ["https://intelligence.internal/v1/managed-state/saml", "http://other.internal/v1/managed-state/saml", "http://intelligence.internal/v1/managed-state/saml?sql=1"]) + assert.equal((await handleSamlIdentityRequest(request({ operation: "ready" }, url), env)).status, 404); + for (const body of [{ operation: "sql", statement: "DROP TABLE control_users" }, { operation: "ready", extra: true }, + { operation: "audit", issuer_digest: hash("a"), account: null, outcome: "raw assertion", now }, { operation: "list_links", offset: -1 }]) + assert.equal((await call(body)).status, 400); + const oversized = request({ operation: "ready", pad: "x".repeat(9000) }); + assert.equal((await handleSamlIdentityRequest(oversized, env)).status, 400); +}); + +test("the existing Worker forwards SAML URL, method, cookies and token body to the Container", async () => { + const { default: worker } = await loadWorkerModule(); + for (const [path, method, body] of [["/auth/saml/login?next=fixture", "GET", undefined], ["/auth/saml/callback?state=fixture", "POST", "token=synthetic&state=fixture"], ["/auth/saml/metadata", "GET", undefined]]) { + let forwarded; + const response = await worker.fetch(new Request("https://gateway.example" + path, { method, body, headers: { cookie: "session=synthetic", "content-type": "application/x-www-form-urlencoded" } }), { + MULTILLM_PROXY_CONTAINER: { getByName: () => ({ async fetch(req) { forwarded = req; return new Response("container-result", { status: 503 }); } }) } + }, {}); + assert.equal(response.status, 503); assert.equal(await response.text(), "container-result"); + assert.equal(forwarded.url, "https://gateway.example" + path); assert.equal(forwarded.method, method); + assert.equal(forwarded.headers.get("cookie"), "session=synthetic"); assert.equal(await forwarded.text(), body ?? ""); + } +}); diff --git a/worker/container-env.mjs b/worker/container-env.mjs index d402b5c7..d461dde9 100644 --- a/worker/container-env.mjs +++ b/worker/container-env.mjs @@ -41,6 +41,10 @@ const DIRECT_ENV_KEYS = [ "CONFIG_REVISION_SYNC_ENABLED", "CONFIG_SYNC_TTL_SECONDS", "ORGANISATIONS_ENABLED", + "SAML_BROKER_URL", + "SAML_CALLBACK_URL", + "SAML_ENABLED", + "SAML_TRUST_CONFIG_JSON", "TENANT_GOVERNANCE_ENABLED", "CONTEXT_CANARY_MODE", "CONTEXT_CANARY_POLICY_JSON", diff --git a/worker/d1-schema.mjs b/worker/d1-schema.mjs index d894e27a..bf6cb625 100644 --- a/worker/d1-schema.mjs +++ b/worker/d1-schema.mjs @@ -10,7 +10,7 @@ export const REQUIRED_D1_TABLES = Object.freeze(["intelligence_policy", "intelli "usage_events", "usage_daily", "usage_batches", "media_jobs", "media_job_items", "shadow_eval_samples", "shadow_eval_results", "shadow_eval_config", "shadow_eval_policy_backups", "prompt_templates", - "config_snapshot_revisions", "config_snapshots", "config_snapshot_applications", "control_revisions", "tool_grants", "generation_cache", "usage_reservation_budgets", "usage_reservations", "usage_reservation_transitions", "session_tiers", "gateway_alert_rules", "gateway_alert_events", "managed_idempotency", "context_pages", "canary_traffic", "semantic_generation_cache", "gateway_batch_files", "gateway_batches", "gateway_batch_items", "hosted_responses", "realtime_tickets", "realtime_sessions", "learned_cooldown", "usage_receipt_keys", "usage_receipt_heads", "usage_receipts", "tenant_organisations", "tenant_teams", "tenant_memberships", "tenant_bindings", "tenant_audit", "tenant_governance_policies", "tenant_governance_reservations", "tenant_governance_components", "tenant_governance_baselines", "tenant_governance_audit"]); + "config_snapshot_revisions", "config_snapshots", "config_snapshot_applications", "control_revisions", "tool_grants", "generation_cache", "usage_reservation_budgets", "usage_reservations", "usage_reservation_transitions", "session_tiers", "gateway_alert_rules", "gateway_alert_events", "managed_idempotency", "context_pages", "canary_traffic", "semantic_generation_cache", "gateway_batch_files", "gateway_batches", "gateway_batch_items", "hosted_responses", "realtime_tickets", "realtime_sessions", "learned_cooldown", "usage_receipt_keys", "usage_receipt_heads", "usage_receipts", "tenant_organisations", "tenant_teams", "tenant_memberships", "tenant_bindings", "tenant_audit", "tenant_governance_policies", "tenant_governance_reservations", "tenant_governance_components", "tenant_governance_baselines", "tenant_governance_audit", "saml_requests", "saml_subject_links", "saml_audit"]); /** * Readiness for the D1 schema. A deploy that skipped `wrangler d1 migrations apply` reports diff --git a/worker/saml-identity.mjs b/worker/saml-identity.mjs new file mode 100644 index 00000000..0a0d57c7 --- /dev/null +++ b/worker/saml-identity.mjs @@ -0,0 +1,167 @@ +/** Private durable broker request claims, explicit subject links and content-free audit. */ +const PATH = "/v1/managed-state/saml"; +const MAX_BYTES = 8192; +const HASH = /^[a-f0-9]{64}$/; +const ID = /^[a-f0-9]{32}$/; +const OPAQUE = /^[A-Za-z0-9_:.\-]{1,128}$/; +const OUTCOMES = new Set(["authorized", "link_put", "link_deactivated", "saml_assertion_invalid", "saml_assertion_replayed", + "saml_subject_unlinked", "saml_identity_denied", "saml_identity_unavailable", "saml_session_unavailable"]); +const LINK_COLUMNS = "id,issuer_digest,subject_digest,account,org_id,team_id,grants_revision,active,created_at,updated_at"; +const fields = (body, names) => Object.keys(body).length === names.length + 2 + && ["version", "operation", ...names].every(name => Object.hasOwn(body, name)); +const text = value => typeof value === "string" && value.length > 0 && value.length <= 128 && !/[\x00-\x1f\x7f]/.test(value); +const hash = value => typeof value === "string" && HASH.test(value); +const id = value => typeof value === "string" && ID.test(value); +const integer = value => Number.isSafeInteger(value) && value >= 0 && value < Number.MAX_SAFE_INTEGER; +const scope = value => value === null || (typeof value === "string" && OPAQUE.test(value)); +const actorDigest = async value => Array.from(new Uint8Array(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(value)))) + .map(byte => byte.toString(16).padStart(2, "0")).join(""); +const reply = (value, status = 200) => Response.json(value.error + ? { version: 1, error: { code: value.error, message: "SAML identity storage request could not be completed.", retryable: false } } + : { version: 1, ...value }, { status, headers: { "cache-control": "no-store" } }); +let warned = false; + +function enabled(env) { + const flag = typeof (env.SAML_ENABLED ?? "") === "string" ? (env.SAML_ENABLED ?? "").trim().toLowerCase() : "invalid"; + if (["", "false", "0", "off", "no"].includes(flag)) return false; + if (["true", "1", "on", "yes"].includes(flag)) return true; + if (!warned) { console.warn("Invalid SAML_ENABLED; federation disabled"); warned = true; } + return false; +} + +async function bodyDocument(request) { + if (request.headers.get("content-type")?.split(";", 1)[0].trim().toLowerCase() !== "application/json" || !request.body) + throw new Error("Invalid content type"); + const length = request.headers.get("content-length"); + if (length !== null && (!/^\d+$/.test(length) || Number(length) > MAX_BYTES)) throw new Error("Invalid length"); + const reader = request.body.getReader(), chunks = []; + let size = 0; + try { + while (true) { + const { done, value } = await reader.read(); + if (done) break; + size += value.byteLength; + if (size > MAX_BYTES) { void reader.cancel().catch(() => {}); throw new Error("Oversized request"); } + chunks.push(value); + } + } finally { reader.releaseLock(); } + const bytes = new Uint8Array(size); + let offset = 0; + for (const chunk of chunks) { bytes.set(chunk, offset); offset += chunk.byteLength; } + const body = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes)); + if (!body || typeof body !== "object" || Array.isArray(body) || body.version !== 1) throw new Error("Invalid envelope"); + return body; +} + +function validLink(link) { + return link && typeof link === "object" && !Array.isArray(link) + && Object.keys(link).length === 7 && ["id", "issuer_digest", "subject_digest", "account", "org_id", "team_id", "grants_revision"].every(key => Object.hasOwn(link, key)) + && id(link.id) && hash(link.issuer_digest) && hash(link.subject_digest) && text(link.account) + && scope(link.org_id) && scope(link.team_id) && (link.team_id === null || link.org_id !== null) && integer(link.grants_revision); +} + +function validOperation(body) { + switch (body.operation) { + case "ready": return fields(body, []); + case "create_request": return fields(body, ["state_digest", "nonce_digest", "recipient_digest", "now", "expires_at"]) + && hash(body.state_digest) && hash(body.nonce_digest) && hash(body.recipient_digest) && integer(body.now) && integer(body.expires_at) + && body.expires_at > body.now && body.expires_at <= body.now + 300; + case "claim_request": return fields(body, ["state_digest", "nonce_digest", "recipient_digest", "now"]) + && hash(body.state_digest) && hash(body.nonce_digest) && hash(body.recipient_digest) && integer(body.now); + case "lookup_link": return fields(body, ["issuer_digest", "subject_digest"]) && hash(body.issuer_digest) && hash(body.subject_digest); + case "get_link": return fields(body, ["id"]) && id(body.id); + case "list_links": return fields(body, ["offset"]) && integer(body.offset) && body.offset <= 999999; + case "put_link": return fields(body, ["link", "actor", "now"]) && validLink(body.link) && text(body.actor) && integer(body.now); + case "deactivate_link": return fields(body, ["id", "actor", "now"]) && id(body.id) && text(body.actor) && integer(body.now); + case "audit": return fields(body, ["issuer_digest", "account", "outcome", "now"]) && hash(body.issuer_digest) + && (body.account === null || text(body.account)) && OUTCOMES.has(body.outcome) && integer(body.now); + default: return false; + } +} + +async function ready(db) { + // Verify all columns before any mutation, including the audit destination. + for (const query of ["SELECT state_digest,nonce_digest,recipient_digest,created_at,expires_at,claimed_at FROM saml_requests LIMIT 0", + `SELECT ${LINK_COLUMNS} FROM saml_subject_links LIMIT 0`, "SELECT id,issuer_digest,account,actor_digest,outcome,occurred_at FROM saml_audit LIMIT 0", + "SELECT username,revoked_at FROM control_users LIMIT 0"]) await db.prepare(query).all(); +} + +async function putLink(db, body) { + const link = body.link; + const actor = await actorDigest(body.actor); + const account = await db.prepare("SELECT username FROM control_users WHERE username=? AND revoked_at IS NULL").bind(link.account).first(); + if (!account) return reply({ error: "saml_subject_unlinked" }, 403); + const results = await db.batch([ + db.prepare(`INSERT INTO saml_subject_links(${LINK_COLUMNS}) + SELECT ?,?,?,?,?,?,?,1,?,? FROM control_users WHERE username=? AND revoked_at IS NULL + ON CONFLICT(id) DO UPDATE SET account=excluded.account,org_id=excluded.org_id,team_id=excluded.team_id, + grants_revision=excluded.grants_revision,active=1,updated_at=excluded.updated_at + WHERE saml_subject_links.issuer_digest=excluded.issuer_digest AND saml_subject_links.subject_digest=excluded.subject_digest`) + .bind(link.id, link.issuer_digest, link.subject_digest, link.account, link.org_id, link.team_id, link.grants_revision, body.now, body.now, link.account), + db.prepare(`INSERT INTO saml_audit(id,issuer_digest,account,actor_digest,outcome,occurred_at) + SELECT ?,issuer_digest,account,?,'link_put',? FROM saml_subject_links + WHERE id=? AND issuer_digest=? AND subject_digest=? AND account=? AND updated_at=? AND active=1`) + .bind(crypto.randomUUID(), actor, body.now, link.id, link.issuer_digest, link.subject_digest, link.account, body.now) + ]); + if (results[0].meta.changes !== 1 || results[1].meta.changes !== 1) return reply({ error: "saml_link_conflict" }, 409); + return reply({ link: await db.prepare(`SELECT ${LINK_COLUMNS} FROM saml_subject_links WHERE id=?`).bind(link.id).first() }); +} + +async function deactivateLink(db, body) { + const actor = await actorDigest(body.actor); + const results = await db.batch([ + db.prepare(`INSERT INTO saml_audit(id,issuer_digest,account,actor_digest,outcome,occurred_at) + SELECT ?,issuer_digest,account,?,'link_deactivated',? FROM saml_subject_links WHERE id=? AND active=1`) + .bind(crypto.randomUUID(), actor, body.now, body.id), + db.prepare("UPDATE saml_subject_links SET active=0,updated_at=? WHERE id=? AND active=1").bind(body.now, body.id) + ]); + return reply({ deactivated: results[1].meta.changes === 1 }); +} + +async function execute(db, body) { + switch (body.operation) { + case "ready": return reply({ ready: true }); + case "create_request": { + const result = await db.prepare("INSERT INTO saml_requests(state_digest,nonce_digest,recipient_digest,created_at,expires_at) VALUES(?,?,?,?,?)") + .bind(body.state_digest, body.nonce_digest, body.recipient_digest, body.now, body.expires_at).run(); + return reply({ created: result.meta.changes === 1 }); + } + case "claim_request": { + const result = await db.prepare(`UPDATE saml_requests SET claimed_at=? WHERE state_digest=? AND nonce_digest=? + AND recipient_digest=? AND claimed_at IS NULL AND expires_at>? AND created_at<=?`) + .bind(body.now, body.state_digest, body.nonce_digest, body.recipient_digest, body.now, body.now + 5).run(); + return reply({ claimed: result.meta.changes === 1 }); + } + case "lookup_link": return reply({ link: await db.prepare(`SELECT ${LINK_COLUMNS} FROM saml_subject_links + WHERE issuer_digest=? AND subject_digest=? AND active=1`).bind(body.issuer_digest, body.subject_digest).first() }); + case "get_link": return reply({ link: await db.prepare(`SELECT ${LINK_COLUMNS} FROM saml_subject_links WHERE id=?`).bind(body.id).first() }); + case "list_links": return reply({ links: (await db.prepare(`SELECT ${LINK_COLUMNS} FROM saml_subject_links ORDER BY id LIMIT 100 OFFSET ?`).bind(body.offset).all()).results }); + case "put_link": return putLink(db, body); + case "deactivate_link": return deactivateLink(db, body); + case "audit": { + const result = await db.prepare("INSERT INTO saml_audit(id,issuer_digest,account,outcome,occurred_at) VALUES(?,?,?,?,?)") + .bind(crypto.randomUUID(), body.issuer_digest, body.account, body.outcome, body.now).run(); + return reply({ recorded: result.meta.changes === 1 }); + } + default: return reply({ error: "saml_request_invalid" }, 400); + } +} + +/** Register this handler at handleManagedStateRequest's fixed SAML domain. */ +export async function handleSamlIdentityRequest(request, env) { + const url = new URL(request.url); + if (url.origin !== "http://intelligence.internal" || url.pathname !== PATH || url.search || url.hash + || url.username || url.password || request.method !== "POST" || !enabled(env)) return reply({ error: "not_found" }, 404); + let body; + try { body = await bodyDocument(request); } + catch { return reply({ error: "saml_request_invalid" }, 400); } + if (!validOperation(body)) return reply({ error: "saml_request_invalid" }, 400); + if (!env.INTELLIGENCE_DB) return reply({ error: "saml_storage_unavailable" }, 503); + try { + await ready(env.INTELLIGENCE_DB); + return await execute(env.INTELLIGENCE_DB, body); + } catch (error) { + const conflict = /UNIQUE constraint failed/.test(String(error?.message)); + return reply({ error: conflict ? "saml_link_conflict" : "saml_storage_unavailable" }, conflict ? 409 : 503); + } +}