OpenRAG is a comprehensive, single package Retrieval-Augmented Generation platform built on Langflow, Docling, and Opensearch.
Python
chore: RBAC test scripts and sync roles (#1757)
Edwin Josece4e7277a9d0
diff --git a/.env.example b/.env.exampleindex e3e25326b..e259a7c86 100644--- a/.env.example+++ b/.env.example@@ -361,3 +361,12 @@ OPENRAG_STORAGE_MODE=db# overrides are also bypassed. Set to `true` to turn the permissions# system on for multi-user deployments. Available in all run modes.# OPENRAG_RBAC_ENFORCE=true++# Default role for new users (JWT role sync off). Does not change existing+# users unless OPENRAG_SYNC_DEFAULT_ROLE is also enabled.+# OPENRAG_DEFAULT_ROLE=user+# OPENRAG_NOAUTH_ROLE=admin++# Dev-only (OSS run mode): run scripts/sync_default_user_roles.py manually+# to migrate users when OPENRAG_DEFAULT_ROLE changes. Ignored in saas/on_prem.+# OPENRAG_SYNC_DEFAULT_ROLE=falsediff --git a/scripts/README.md b/scripts/README.mdnew file mode 100644index 000000000..c3e0dd321--- /dev/null+++ b/scripts/README.md@@ -0,0 +1,119 @@+# OpenRAG scripts++## Sync default user roles (`sync_default_user_roles.py`)++Dev-only helper for RBAC in **OSS run mode** (`OPENRAG_RUN_MODE=oss`): updates+existing users in the SQL DB when `OPENRAG_DEFAULT_ROLE` changes. Requires:++```env+OPENRAG_RUN_MODE=oss+OPENRAG_SYNC_DEFAULT_ROLE=true+OPENRAG_DEFAULT_ROLE=admin # target role: admin | developer | user | viewer+```++Ignored in `saas` and `on_prem` — those modes assign roles from JWT claims.++Uses the default SQLite DB at `data/openrag.db` unless `DATABASE_URL` is set.++### Promote all `user` roles to `OPENRAG_DEFAULT_ROLE`++Use this when users still have the `user` role but you want them on whatever+role is set in `OPENRAG_DEFAULT_ROLE` (for example `admin`):++```bash+OPENRAG_SYNC_DEFAULT_ROLE=true \+OPENRAG_DEFAULT_ROLE=admin \+uv run python scripts/sync_default_user_roles.py --from-role user+```++### Explicit from → to (ignores env target)++When both roles are on the CLI, the target comes from `--to-role`, not+`OPENRAG_DEFAULT_ROLE`:++```bash+OPENRAG_SYNC_DEFAULT_ROLE=true \+uv run python scripts/sync_default_user_roles.py --from-role admin --to-role user+```++Migrates every user whose **only** role is `admin` to `user`, regardless of+what `OPENRAG_DEFAULT_ROLE` is set to.++What it does:++- Finds every user whose **only** role is `user`+- Assigns them the role from `OPENRAG_DEFAULT_ROLE` (here: `admin`)+- Skips users with multiple roles or a different single role+- Updates the stored baseline in `workspace_config.meta`++Preview without writing:++```bash+OPENRAG_SYNC_DEFAULT_ROLE=true \+OPENRAG_DEFAULT_ROLE=admin \+uv run python scripts/sync_default_user_roles.py --from-role user --dry-run+```++Replace `user` with any source role, and set `OPENRAG_DEFAULT_ROLE` to the+target role you want.++### Other commands++| Command | Purpose |+| --- | --- |+| `uv run python scripts/sync_default_user_roles.py` | Sync when env default changed since last recorded baseline |+| `--dry-run` | Show changes without writing to the DB |+| `--from-role ROLE` | Source role for this run (overrides stored baseline) |+| `--to-role ROLE` | Target role (overrides `OPENRAG_DEFAULT_ROLE`; requires `--from-role`) |+| `--from-noauth-role ROLE` | Source role for the anonymous user |+| `--to-noauth-role ROLE` | Target role for anonymous user (overrides `OPENRAG_NOAUTH_ROLE`) |+| `--record-baseline` | Save current env defaults; do not change any user |++### After running++Restart the backend (or wait for `OPENRAG_PERM_CACHE_TTL`, default 60s) so+permission checks pick up the new roles. Verify with:++```bash+curl -b "auth_token=..." http://localhost:8000/users/me+```++### Notes++- Intended for local OSS dev workflows, not production role management.+- If the script reports stale users but updates none, use `--from-role` with+ the role those users currently have.++## Reset onboarding (`reset_onboarding.py`)++Re-triggers the onboarding wizard by resetting workspace config in the DB+(`OPENRAG_STORAGE_MODE=db` by default):++```bash+uv run python scripts/reset_onboarding.py+```++What it does:++- Sets `workspace_config.meta.edited` to `false` (`GET /api/onboarding-status` → `onboarded: false`)+- Clears `workspace_config.onboarding` (including `current_step` → `0`)+- In `hybrid` / `files` mode, also updates `config.yaml`++Optional flags:++| Flag | Purpose |+| --- | --- |+| `--dry-run` | Preview without writing |+| `--reset-models` | Also clear selected LLM and embedding models |++Example — full wizard reset including model picks:++```bash+uv run python scripts/reset_onboarding.py --reset-models+```++After running, **restart the backend** and reload the app.++This script does **not** delete ingested documents, knowledge filters, Langflow+flows, or conversations. For a full teardown, use the authenticated API endpoint+`POST /settings/rollback-onboarding` instead.diff --git a/scripts/reset_onboarding.py b/scripts/reset_onboarding.pynew file mode 100644index 000000000..d1c9ca1a2--- /dev/null+++ b/scripts/reset_onboarding.py@@ -0,0 +1,96 @@+#!/usr/bin/env python3+"""Reset onboarding state in the DB so the wizard shows again.++Sets ``meta.edited=false`` and clears the ``onboarding`` section in+``workspace_config``. In hybrid/files mode, config.yaml is updated too.++Does **not** remove ingested documents, knowledge filters, or Langflow+flow edits. For that, use POST /settings/rollback-onboarding via the API.++Usage:+ uv run python scripts/reset_onboarding.py+ uv run python scripts/reset_onboarding.py --dry-run+ uv run python scripts/reset_onboarding.py --reset-models+"""++from __future__ import annotations++import argparse+import asyncio+import sys+from pathlib import Path++ROOT = Path(__file__).resolve().parent.parent+SRC = ROOT / "src"+if str(SRC) not in sys.path:+ sys.path.insert(0, str(SRC))+++async def main() -> int:+ parser = argparse.ArgumentParser(+ description="Reset onboarding in workspace_config to re-trigger the wizard.",+ )+ parser.add_argument(+ "--dry-run",+ action="store_true",+ help="Show what would change without writing",+ )+ parser.add_argument(+ "--reset-models",+ action="store_true",+ help="Also clear selected LLM and embedding models (back to openai defaults)",+ )+ args = parser.parse_args()++ from config.storage_mode import db_writes_enabled, get_storage_mode+ from services.onboarding_reset import reset_onboarding++ mode = get_storage_mode()+ print(f"Storage mode: {mode}")++ session = None+ if db_writes_enabled():+ import db.engine as db_engine++ db_engine.init_engine()+ SessionLocal = db_engine.SessionLocal+ if SessionLocal is None:+ print("Database engine is not configured (check DATABASE_URL).", file=sys.stderr)+ return 1++ async with SessionLocal() as session:+ result = await reset_onboarding(+ session,+ reset_models=args.reset_models,+ dry_run=args.dry_run,+ )+ if not args.dry_run:+ await session.commit()+ else:+ result = await reset_onboarding(+ None,+ reset_models=args.reset_models,+ dry_run=args.dry_run,+ )++ if args.dry_run:+ print(+ f"Dry run — would set edited=false and onboarding.current_step=0 "+ f"(was edited={result.previous_edited!r}, step={result.previous_step!r})."+ )+ if args.reset_models:+ print("Would also clear LLM and embedding model selections.")+ else:+ targets = []+ if result.db_updated:+ targets.append("workspace_config (DB)")+ if result.yaml_updated:+ targets.append("config.yaml")+ print(f"Onboarding reset written to: {', '.join(targets) or 'nothing'}")+ print("Restart the backend, then reload the app to see the onboarding wizard.")++ return 0+++if __name__ == "__main__":+ raise SystemExit(asyncio.run(main()))diff --git a/scripts/sync_default_user_roles.py b/scripts/sync_default_user_roles.pynew file mode 100644index 000000000..a2c02809c--- /dev/null+++ b/scripts/sync_default_user_roles.py@@ -0,0 +1,147 @@+#!/usr/bin/env python3+"""Sync existing user roles when OPENRAG_DEFAULT_ROLE env values change.++Requires ``OPENRAG_SYNC_DEFAULT_ROLE=true``. OSS run mode only+(``OPENRAG_RUN_MODE=oss``). Run manually via ``scripts/sync_default_user_roles.py``.++Usage:+ OPENRAG_SYNC_DEFAULT_ROLE=true uv run python scripts/sync_default_user_roles.py+ OPENRAG_SYNC_DEFAULT_ROLE=true uv run python scripts/sync_default_user_roles.py --dry-run+ OPENRAG_SYNC_DEFAULT_ROLE=true uv run python scripts/sync_default_user_roles.py --record-baseline+ OPENRAG_SYNC_DEFAULT_ROLE=true uv run python scripts/sync_default_user_roles.py --from-role user+ OPENRAG_SYNC_DEFAULT_ROLE=true uv run python scripts/sync_default_user_roles.py --from-role admin --to-role user+"""++from __future__ import annotations++import argparse+import asyncio+import sys+from pathlib import Path++ROOT = Path(__file__).resolve().parent.parent+SRC = ROOT / "src"+if str(SRC) not in sys.path:+ sys.path.insert(0, str(SRC))+++async def main() -> int:+ parser = argparse.ArgumentParser(+ description="Sync DB user roles after OPENRAG_DEFAULT_ROLE / OPENRAG_NOAUTH_ROLE change.",+ )+ parser.add_argument(+ "--dry-run",+ action="store_true",+ help="Show eligible updates without writing to the DB",+ )+ parser.add_argument(+ "--record-baseline",+ action="store_true",+ help="Record current env defaults without updating any users",+ )+ parser.add_argument(+ "--from-role",+ metavar="ROLE",+ help=(+ "Treat ROLE as the previous default for this run only "+ "(fixes a baseline recorded before users were migrated)"+ ),+ )+ parser.add_argument(+ "--from-noauth-role",+ metavar="ROLE",+ help="Like --from-role but for the anonymous/no-auth user",+ )+ parser.add_argument(+ "--to-role",+ metavar="ROLE",+ help="Target role for regular users (overrides OPENRAG_DEFAULT_ROLE for this run)",+ )+ parser.add_argument(+ "--to-noauth-role",+ metavar="ROLE",+ help="Target role for the anonymous user (overrides OPENRAG_NOAUTH_ROLE for this run)",+ )+ args = parser.parse_args()++ if args.to_role is not None and args.from_role is None and not args.record_baseline:+ print(+ "--to-role requires --from-role so the script knows which users to migrate.",+ file=sys.stderr,+ )+ return 1++ import db.engine as db_engine+ from config.settings import is_default_role_sync_enabled+ from services.default_role_sync import sync_default_roles_if_changed++ if not is_default_role_sync_enabled():+ from utils.run_mode_utils import get_run_mode, is_run_mode_oss++ if not is_run_mode_oss():+ print(+ "Default role sync is only available when OPENRAG_RUN_MODE=oss "+ f"(current: {get_run_mode()!r}).",+ file=sys.stderr,+ )+ else:+ print(+ "OPENRAG_SYNC_DEFAULT_ROLE is not enabled. "+ "Set OPENRAG_SYNC_DEFAULT_ROLE=true and retry.",+ file=sys.stderr,+ )+ return 1++ db_engine.init_engine()+ SessionLocal = db_engine.SessionLocal+ if SessionLocal is None:+ print("Database engine is not configured.", file=sys.stderr)+ return 1++ if args.from_role or args.to_role:+ print(+ "Role migration:",+ f"{args.from_role or '(from baseline/env)'} -> {args.to_role or '(from env)'}",+ )+ else:+ print("Using OPENRAG_DEFAULT_ROLE and OPENRAG_NOAUTH_ROLE from the environment.")+ if args.dry_run:+ print("Dry run — no writes.")++ async with SessionLocal() as session:+ result = await sync_default_roles_if_changed(+ session,+ dry_run=args.dry_run,+ force_baseline=args.record_baseline,+ from_role=args.from_role,+ from_noauth_role=args.from_noauth_role,+ to_role=args.to_role,+ to_noauth_role=args.to_noauth_role,+ )+ if not args.dry_run:+ await session.commit()++ if result.baseline_recorded and not result.changes and args.record_baseline:+ print("Baseline recorded; no user rows changed.")+ elif result.updated_users == 0:+ print("No eligible users to update.")+ if result.stale_users:+ print(+ f"Found {result.stale_users} user(s) whose sole role differs from "+ "OPENRAG_DEFAULT_ROLE but the stored baseline already matches env. "+ "Re-run with:\n"+ " --from-role user # or whichever role they currently have"+ )+ else:+ verb = "Would update" if args.dry_run else "Updated"+ print(f"{verb} {result.updated_users} user(s):")+ for change in result.changes:+ print(f" - user {change['user_id']}: {change['from_role']} -> {change['to_role']}")+ if result.skipped_users:+ print(f"Skipped {result.skipped_users} user(s) (multi-role or non-default role).")++ return 0+++if __name__ == "__main__":+ raise SystemExit(asyncio.run(main()))diff --git a/src/config/settings.py b/src/config/settings.pyindex b12e59353..1516d430b 100644--- a/src/config/settings.py+++ b/src/config/settings.py@@ -197,6 +197,30 @@ def get_role_claim_viewer() -> str | None:return os.getenv("OPENRAG_ROLE_CLAIM_VIEWER")+def get_default_user_role() -> str:+ """Built-in role assigned to new users when JWT role sync is off."""+ return os.getenv("OPENRAG_DEFAULT_ROLE", "user")+++def get_noauth_user_role() -> str:+ """Built-in role for the synthetic anonymous user in no-auth mode."""+ return os.getenv("OPENRAG_NOAUTH_ROLE", "admin")+++def is_default_role_sync_enabled() -> bool:+ """When true, sync eligible existing users if default-role env vars change.++ Only active in ``OPENRAG_RUN_MODE=oss``. SaaS and on-prem assign roles+ via JWT sync; env-driven bulk migration is an OSS dev workflow.+ """+ from utils.run_mode_utils import is_run_mode_oss++ if not is_run_mode_oss():+ return False+ raw = os.getenv("OPENRAG_SYNC_DEFAULT_ROLE", "false").strip().lower()+ return raw in ("true", "1", "yes", "on")++def get_openrag_service_token() -> str | None:"""Platform-issued service JWT used at startup to bootstrap the OpenSearchsecurity context (admin role mapping). Read per-call — like the JWT-claimdiff --git a/src/services/default_role_sync.py b/src/services/default_role_sync.pynew file mode 100644index 000000000..69c79f737--- /dev/null+++ b/src/services/default_role_sync.py@@ -0,0 +1,307 @@+"""Sync DB user roles when OPENRAG_DEFAULT_ROLE / OPENRAG_NOAUTH_ROLE change.++Opt-in via ``OPENRAG_SYNC_DEFAULT_ROLE=true``. OSS run mode only+(``OPENRAG_RUN_MODE=oss``). Run manually via ``scripts/sync_default_user_roles.py``.++Only users with *exactly one* role matching the previously recorded env+default are updated. Users with multiple roles or a manually changed+single role are left untouched.+"""++from __future__ import annotations++from dataclasses import dataclass, field+from typing import Any++from sqlalchemy.ext.asyncio import AsyncSession++from config.settings import (+ get_default_user_role,+ get_noauth_user_role,+ is_default_role_sync_enabled,+)+from db.repositories import AuditRepo, RoleRepo, UserRepo+from db.repositories.workspace_config_repo import WorkspaceConfigRepo+from utils.logging_config import get_logger++logger = get_logger(__name__)++META_SECTION = "meta"+SYNC_STATE_KEY = "rbac_default_role_sync"+PAGE_SIZE = 100+# Code defaults when no baseline exists yet (matches user_service / settings).+IMPLICIT_DEFAULT_USER_ROLE = "user"+IMPLICIT_DEFAULT_NOAUTH_ROLE = "admin"+++@dataclass+class DefaultRoleSyncResult:+ enabled: bool+ dry_run: bool+ baseline_recorded: bool = False+ default_role_changed: bool = False+ noauth_role_changed: bool = False+ updated_users: int = 0+ skipped_users: int = 0+ stale_users: int = 0+ old_default_role: str | None = None+ new_default_role: str = ""+ old_noauth_role: str | None = None+ new_noauth_role: str = ""+ changes: list[dict[str, str]] = field(default_factory=list)++ def as_log_kwargs(self) -> dict[str, Any]:+ return {+ "enabled": self.enabled,+ "dry_run": self.dry_run,+ "baseline_recorded": self.baseline_recorded,+ "default_role_changed": self.default_role_changed,+ "noauth_role_changed": self.noauth_role_changed,+ "updated_users": self.updated_users,+ "skipped_users": self.skipped_users,+ "stale_users": self.stale_users,+ "old_default_role": self.old_default_role,+ "new_default_role": self.new_default_role,+ "old_noauth_role": self.old_noauth_role,+ "new_noauth_role": self.new_noauth_role,+ "change_count": len(self.changes),+ }+++def _read_sync_state(meta: dict[str, Any]) -> dict[str, str | None]:+ state = meta.get(SYNC_STATE_KEY) or {}+ return {+ "default_role": state.get("default_role"),+ "noauth_role": state.get("noauth_role"),+ }+++async def _write_sync_state(+ repo: WorkspaceConfigRepo,+ *,+ default_role: str,+ noauth_role: str,+ dry_run: bool,+) -> None:+ if dry_run:+ return+ meta = await repo.get_section(META_SECTION) or {}+ meta = dict(meta)+ meta[SYNC_STATE_KEY] = {+ "default_role": default_role,+ "noauth_role": noauth_role,+ }+ await repo.upsert(META_SECTION, meta)+++def _is_noauth_user(user) -> bool:+ return user.oauth_subject == "anonymous"+++async def _count_stale_default_users(+ session: AsyncSession,+ *,+ expected_role: str,+) -> int:+ """Users with a single role that differs from the current env default."""+ role_repo = RoleRepo(session)+ user_repo = UserRepo(session)+ stale = 0+ offset = 0+ while True:+ users = await user_repo.list_all(limit=PAGE_SIZE, offset=offset)+ if not users:+ break+ for user in users:+ if _is_noauth_user(user):+ continue+ roles = await role_repo.list_user_roles(user.id)+ if len(roles) == 1 and roles[0].name != expected_role:+ stale += 1+ offset += PAGE_SIZE+ return stale+++async def sync_default_roles_if_changed(+ session: AsyncSession,+ *,+ dry_run: bool = False,+ force_baseline: bool = False,+ from_role: str | None = None,+ from_noauth_role: str | None = None,+ to_role: str | None = None,+ to_noauth_role: str | None = None,+ enabled: bool | None = None,+) -> DefaultRoleSyncResult:+ """Apply env default-role changes to eligible existing users.++ When ``force_baseline`` is true, record the current env values without+ mutating any user rows (useful after enabling the flag on an existing DB).++ ``from_role`` / ``from_noauth_role`` override the stored baseline for one+ run — use when the baseline was recorded before users were migrated+ (e.g. baseline and env are both ``admin`` but users still have ``user``).++ ``to_role`` / ``to_noauth_role`` override ``OPENRAG_DEFAULT_ROLE`` /+ ``OPENRAG_NOAUTH_ROLE`` for this run when set explicitly on the CLI.+ """+ flag_enabled = is_default_role_sync_enabled() if enabled is None else enabled+ new_default = to_role if to_role is not None else get_default_user_role()+ new_noauth = to_noauth_role if to_noauth_role is not None else get_noauth_user_role()++ result = DefaultRoleSyncResult(+ enabled=flag_enabled,+ dry_run=dry_run,+ new_default_role=new_default,+ new_noauth_role=new_noauth,+ )++ if not flag_enabled:+ logger.debug("Default role sync skipped — OPENRAG_SYNC_DEFAULT_ROLE is off")+ return result++ config_repo = WorkspaceConfigRepo(session)+ meta = await config_repo.get_section(META_SECTION) or {}+ state = _read_sync_state(meta)+ stored_default = state["default_role"]+ stored_noauth = state["noauth_role"]++ if force_baseline:+ await _write_sync_state(+ config_repo,+ default_role=new_default,+ noauth_role=new_noauth,+ dry_run=dry_run,+ )+ result.baseline_recorded = True+ logger.info(+ "Recorded RBAC default-role baseline",+ default_role=new_default,+ noauth_role=new_noauth,+ dry_run=dry_run,+ )+ return result++ if from_role is not None:+ old_default = from_role+ elif stored_default is not None:+ old_default = stored_default+ else:+ old_default = IMPLICIT_DEFAULT_USER_ROLE+ result.baseline_recorded = True++ if from_noauth_role is not None:+ old_noauth = from_noauth_role+ elif stored_noauth is not None:+ old_noauth = stored_noauth+ else:+ old_noauth = IMPLICIT_DEFAULT_NOAUTH_ROLE+ result.baseline_recorded = True++ result.old_default_role = old_default+ result.old_noauth_role = old_noauth++ result.default_role_changed = old_default != new_default+ result.noauth_role_changed = old_noauth != new_noauth+ if not result.default_role_changed and not result.noauth_role_changed:+ result.stale_users = await _count_stale_default_users(session, expected_role=new_default)+ if stored_default is None or stored_noauth is None:+ await _write_sync_state(+ config_repo,+ default_role=new_default,+ noauth_role=new_noauth,+ dry_run=dry_run,+ )+ result.baseline_recorded = True+ logger.debug(+ "Default role sync: env defaults unchanged",+ stale_users=result.stale_users,+ )+ return result++ role_repo = RoleRepo(session)+ user_repo = UserRepo(session)+ audit_repo = AuditRepo(session)++ default_role_row = await role_repo.get_by_name(new_default)+ noauth_role_row = await role_repo.get_by_name(new_noauth)+ if result.default_role_changed and default_role_row is None:+ logger.warning(+ "Default role sync: target default role not found in DB",+ role_name=new_default,+ )+ if result.noauth_role_changed and noauth_role_row is None:+ logger.warning(+ "Default role sync: target no-auth role not found in DB",+ role_name=new_noauth,+ )++ offset = 0+ while True:+ users = await user_repo.list_all(limit=PAGE_SIZE, offset=offset)+ if not users:+ break++ for user in users:+ is_noauth = _is_noauth_user(user)+ if is_noauth:+ if not result.noauth_role_changed:+ continue+ old_role_name = old_noauth+ new_role_name = new_noauth+ target_role = noauth_role_row+ else:+ if not result.default_role_changed:+ continue+ old_role_name = old_default+ new_role_name = new_default+ target_role = default_role_row++ if not old_role_name or old_role_name == new_role_name or target_role is None:+ result.skipped_users += 1+ continue++ roles = await role_repo.list_user_roles(user.id)+ if len(roles) != 1 or roles[0].name != old_role_name:+ result.skipped_users += 1+ continue++ change = {+ "user_id": user.id,+ "oauth_provider": user.oauth_provider or "",+ "oauth_subject": user.oauth_subject or "",+ "from_role": old_role_name,+ "to_role": new_role_name,+ }+ result.changes.append(change)++ if dry_run:+ result.updated_users += 1+ continue++ await role_repo.revoke_role(user.id, roles[0].id)+ await role_repo.assign_role(user.id, target_role.id)+ await audit_repo.write(+ event="user.roles_synced",+ actor_user_id=None,+ target_type="user",+ target_id=user.id,+ audit_metadata={+ "added": [new_role_name],+ "removed": [old_role_name],+ "source": "default_role_env_sync",+ },+ )+ result.updated_users += 1++ offset += PAGE_SIZE++ await _write_sync_state(+ config_repo,+ default_role=new_default,+ noauth_role=new_noauth,+ dry_run=dry_run,+ )++ logger.info("Default role sync finished", **result.as_log_kwargs())+ return resultdiff --git a/src/services/onboarding_reset.py b/src/services/onboarding_reset.pynew file mode 100644index 000000000..9031bf43f--- /dev/null+++ b/src/services/onboarding_reset.py@@ -0,0 +1,151 @@+"""Reset workspace onboarding state so the wizard shows again.++Updates ``workspace_config`` (and config.yaml in hybrid/files mode).+Does not delete OpenSearch documents, Langflow flows, or conversations —+use the API ``rollback_onboarding`` endpoint for a full teardown.+"""++from __future__ import annotations++from dataclasses import asdict, dataclass+from typing import Any++from sqlalchemy.ext.asyncio import AsyncSession++from config.config_manager import OnboardingState, config_manager+from config.storage_mode import db_writes_enabled, file_writes_enabled, get_storage_mode+from db.repositories.workspace_config_repo import WorkspaceConfigRepo+from utils.logging_config import get_logger++logger = get_logger(__name__)+++@dataclass+class OnboardingResetResult:+ dry_run: bool+ reset_models: bool+ storage_mode: str+ db_updated: bool = False+ yaml_updated: bool = False+ previous_edited: bool | None = None+ previous_step: Any = None++ def as_log_kwargs(self) -> dict[str, Any]:+ return {+ "dry_run": self.dry_run,+ "reset_models": self.reset_models,+ "storage_mode": self.storage_mode,+ "db_updated": self.db_updated,+ "yaml_updated": self.yaml_updated,+ "previous_edited": self.previous_edited,+ "previous_step": self.previous_step,+ }+++def _fresh_onboarding_dict() -> dict[str, Any]:+ return asdict(OnboardingState())+++def _apply_model_reset(section: dict[str, Any], *, llm: bool) -> dict[str, Any]:+ updated = dict(section or {})+ if llm:+ updated["llm_model"] = ""+ updated["llm_provider"] = "openai"+ else:+ updated["embedding_model"] = ""+ updated["embedding_provider"] = "openai"+ return updated+++async def reset_onboarding_in_db(+ session: AsyncSession,+ *,+ reset_models: bool = False,+ dry_run: bool = False,+) -> OnboardingResetResult:+ result = OnboardingResetResult(+ dry_run=dry_run,+ reset_models=reset_models,+ storage_mode=get_storage_mode(),+ )++ repo = WorkspaceConfigRepo(session)+ rows = await repo.list_all()++ meta = dict(rows.get("meta") or {})+ onboarding = dict(rows.get("onboarding") or {})+ result.previous_edited = bool(meta.get("edited", False))+ result.previous_step = onboarding.get("current_step")++ meta["edited"] = False+ fresh_onboarding = _fresh_onboarding_dict()++ if not dry_run:+ await repo.upsert("meta", meta)+ await repo.upsert("onboarding", fresh_onboarding)+ if reset_models:+ await repo.upsert(+ "agent",+ _apply_model_reset(rows.get("agent") or {}, llm=True),+ )+ await repo.upsert(+ "knowledge",+ _apply_model_reset(rows.get("knowledge") or {}, llm=False),+ )+ result.db_updated = True++ logger.info("Onboarding reset in DB", **result.as_log_kwargs())+ return result+++def reset_onboarding_yaml(*, reset_models: bool = False, dry_run: bool = False) -> bool:+ """Reset onboarding flags in config.yaml (hybrid / files mode)."""+ if dry_run:+ return False++ config = config_manager.load_config()+ config.edited = False+ config.onboarding = OnboardingState()+ if reset_models:+ config.agent.llm_model = ""+ config.agent.llm_provider = "openai"+ config.knowledge.embedding_model = ""+ config.knowledge.embedding_provider = "openai"++ config_manager._config = config+ return config_manager.save_config_file(config)+++async def reset_onboarding(+ session: AsyncSession | None = None,+ *,+ reset_models: bool = False,+ dry_run: bool = False,+) -> OnboardingResetResult:+ """Reset onboarding across the active storage backend(s)."""+ mode = get_storage_mode()+ result = OnboardingResetResult(+ dry_run=dry_run,+ reset_models=reset_models,+ storage_mode=mode,+ )++ if db_writes_enabled():+ if session is None:+ raise ValueError("session is required when DB writes are enabled")+ db_result = await reset_onboarding_in_db(+ session,+ reset_models=reset_models,+ dry_run=dry_run,+ )+ result.db_updated = db_result.db_updated+ result.previous_edited = db_result.previous_edited+ result.previous_step = db_result.previous_step++ if file_writes_enabled():+ result.yaml_updated = reset_onboarding_yaml(+ reset_models=reset_models,+ dry_run=dry_run,+ )++ return resultdiff --git a/tests/unit/services/test_default_role_sync.py b/tests/unit/services/test_default_role_sync.pynew file mode 100644index 000000000..38850524b--- /dev/null+++ b/tests/unit/services/test_default_role_sync.py@@ -0,0 +1,218 @@+"""Tests for env-driven default role sync."""++import sys+from pathlib import Path++import pytest+import pytest_asyncio+from sqlalchemy.ext.asyncio import async_sessionmaker, create_async_engine+from sqlmodel import SQLModel++ROOT = Path(__file__).resolve().parent.parent.parent.parent+SRC = ROOT / "src"+if str(SRC) not in sys.path:+ sys.path.insert(0, str(SRC))++import db.models # noqa: E402,F401+from db.repositories import RoleRepo, WorkspaceConfigRepo # noqa: E402+from db.seed import seed_roles_and_permissions # noqa: E402+from services.default_role_sync import sync_default_roles_if_changed # noqa: E402+from services.user_service import ensure_user_row # noqa: E402+from session_manager import User # noqa: E402+++@pytest_asyncio.fixture+async def session():+ engine = create_async_engine(+ "sqlite+aiosqlite:///:memory:",+ connect_args={"check_same_thread": False},+ )+ async with engine.begin() as conn:+ await conn.run_sync(SQLModel.metadata.create_all)+ SessionLocal = async_sessionmaker(engine, expire_on_commit=False)+ async with SessionLocal() as s:+ await seed_roles_and_permissions(s)+ await s.commit()+ yield s+ await engine.dispose()+++def _user(uid: str) -> User:+ return User(user_id=uid, email=f"{uid}@example.com", name=uid, provider="google")+++async def test_sync_skipped_outside_oss(session, monkeypatch):+ monkeypatch.setenv("OPENRAG_SYNC_DEFAULT_ROLE", "true")+ monkeypatch.setenv("OPENRAG_DEFAULT_ROLE", "user")+ user_row = await ensure_user_row(session, _user("u1"))+ await session.commit()++ monkeypatch.setenv("OPENRAG_RUN_MODE", "saas")+ monkeypatch.setenv("OPENRAG_DEFAULT_ROLE", "admin")+ result = await sync_default_roles_if_changed(session)+ roles = await RoleRepo(session).list_user_roles(user_row.id)++ assert result.enabled is False+ assert result.updated_users == 0+ assert [r.name for r in roles] == ["user"]+++async def test_sync_disabled_is_noop(session, monkeypatch):+ monkeypatch.setenv("OPENRAG_SYNC_DEFAULT_ROLE", "false")+ monkeypatch.setenv("OPENRAG_DEFAULT_ROLE", "user")+ row = await ensure_user_row(session, _user("u1"))+ await session.commit()++ result = await sync_default_roles_if_changed(session, enabled=False)+ roles = await RoleRepo(session).list_user_roles(row.id)++ assert result.updated_users == 0+ assert [r.name for r in roles] == ["user"]+++async def test_first_run_with_unchanged_env_records_baseline(session, monkeypatch):+ monkeypatch.setenv("OPENRAG_SYNC_DEFAULT_ROLE", "true")+ monkeypatch.setenv("OPENRAG_DEFAULT_ROLE", "user")+ user_row = await ensure_user_row(session, _user("u1"))+ await session.commit()++ result = await sync_default_roles_if_changed(session, enabled=True)+ await session.commit()++ roles = await RoleRepo(session).list_user_roles(user_row.id)+ meta = await WorkspaceConfigRepo(session).get_section("meta")++ assert result.baseline_recorded is True+ assert result.updated_users == 0+ assert [r.name for r in roles] == ["user"]+ assert meta["rbac_default_role_sync"]["default_role"] == "user"+++async def test_first_run_migrates_from_implicit_user_default(session, monkeypatch):+ monkeypatch.setenv("OPENRAG_SYNC_DEFAULT_ROLE", "true")+ monkeypatch.setenv("OPENRAG_DEFAULT_ROLE", "user")+ user_row = await ensure_user_row(session, _user("u1"))+ await session.commit()++ monkeypatch.setenv("OPENRAG_DEFAULT_ROLE", "admin")+ result = await sync_default_roles_if_changed(session, enabled=True)+ await session.commit()++ roles = await RoleRepo(session).list_user_roles(user_row.id)+ meta = await WorkspaceConfigRepo(session).get_section("meta")++ assert result.updated_users == 1+ assert [r.name for r in roles] == ["admin"]+ assert meta["rbac_default_role_sync"]["default_role"] == "admin"+++async def test_from_role_overrides_wrong_baseline(session, monkeypatch):+ monkeypatch.setenv("OPENRAG_SYNC_DEFAULT_ROLE", "true")+ monkeypatch.setenv("OPENRAG_DEFAULT_ROLE", "user")+ user_row = await ensure_user_row(session, _user("u1"))+ await session.commit()++ meta_repo = WorkspaceConfigRepo(session)+ await meta_repo.upsert(+ "meta",+ {"rbac_default_role_sync": {"default_role": "admin", "noauth_role": "admin"}},+ )+ await session.commit()++ monkeypatch.setenv("OPENRAG_DEFAULT_ROLE", "admin")+ result = await sync_default_roles_if_changed(session, enabled=True, from_role="user")+ await session.commit()++ roles = await RoleRepo(session).list_user_roles(user_row.id)+ assert result.updated_users == 1+ assert [r.name for r in roles] == ["admin"]+++async def test_env_change_updates_single_role_users(session, monkeypatch):+ monkeypatch.setenv("OPENRAG_SYNC_DEFAULT_ROLE", "true")+ monkeypatch.setenv("OPENRAG_DEFAULT_ROLE", "user")+ user_row = await ensure_user_row(session, _user("u1"))+ await sync_default_roles_if_changed(session, enabled=True)+ await session.commit()++ monkeypatch.setenv("OPENRAG_DEFAULT_ROLE", "admin")+ result = await sync_default_roles_if_changed(session, enabled=True)+ await session.commit()++ roles = await RoleRepo(session).list_user_roles(user_row.id)++ assert result.updated_users == 1+ assert [r.name for r in roles] == ["admin"]+++async def test_skips_multi_role_users(session, monkeypatch):+ monkeypatch.setenv("OPENRAG_SYNC_DEFAULT_ROLE", "true")+ monkeypatch.setenv("OPENRAG_DEFAULT_ROLE", "user")+ user_row = await ensure_user_row(session, _user("u1"))+ role_repo = RoleRepo(session)+ dev_role = await role_repo.get_by_name("developer")+ await role_repo.assign_role(user_row.id, dev_role.id)+ await sync_default_roles_if_changed(session, enabled=True)+ await session.commit()++ monkeypatch.setenv("OPENRAG_DEFAULT_ROLE", "admin")+ result = await sync_default_roles_if_changed(session, enabled=True)+ await session.commit()++ roles = await RoleRepo(session).list_user_roles(user_row.id)++ assert result.updated_users == 0+ assert result.skipped_users == 1+ assert {r.name for r in roles} == {"user", "developer"}+++async def test_explicit_to_role_overrides_env(session, monkeypatch):+ monkeypatch.setenv("OPENRAG_SYNC_DEFAULT_ROLE", "true")+ monkeypatch.setenv("OPENRAG_DEFAULT_ROLE", "admin")+ user_row = await ensure_user_row(session, _user("u1"))+ role_repo = RoleRepo(session)+ user_role = await role_repo.get_by_name("user")+ admin_role = await role_repo.get_by_name("admin")+ await role_repo.revoke_role(user_row.id, user_role.id)+ await role_repo.assign_role(user_row.id, admin_role.id)+ await WorkspaceConfigRepo(session).upsert(+ "meta",+ {"rbac_default_role_sync": {"default_role": "admin", "noauth_role": "admin"}},+ )+ await session.commit()++ result = await sync_default_roles_if_changed(+ session, enabled=True, from_role="admin", to_role="user"+ )+ await session.commit()++ roles = await RoleRepo(session).list_user_roles(user_row.id)+ assert result.updated_users == 1+ assert [r.name for r in roles] == ["user"]+++async def test_dry_run_does_not_write(session, monkeypatch):+ monkeypatch.setenv("OPENRAG_SYNC_DEFAULT_ROLE", "true")+ monkeypatch.setenv("OPENRAG_DEFAULT_ROLE", "user")+ user_row = await ensure_user_row(session, _user("u1"))+ await sync_default_roles_if_changed(session, enabled=True)+ await session.commit()++ monkeypatch.setenv("OPENRAG_DEFAULT_ROLE", "viewer")+ result = await sync_default_roles_if_changed(session, enabled=True, dry_run=True)++ roles = await RoleRepo(session).list_user_roles(user_row.id)+ meta = await WorkspaceConfigRepo(session).get_section("meta")++ assert result.updated_users == 1+ assert [r.name for r in roles] == ["user"]+ assert meta is None or meta.get("rbac_default_role_sync", {}).get("default_role") == "user"diff --git a/tests/unit/services/test_onboarding_reset.py b/tests/unit/services/test_onboarding_reset.pynew file mode 100644index 000000000..643b15d8d--- /dev/null+++ b/tests/unit/services/test_onboarding_reset.py@@ -0,0 +1,101 @@+"""Tests for onboarding reset."""++import sys+from pathlib import Path++import pytest+import pytest_asyncio+from sqlalchemy.ext.asyncio import async_sessionmaker, create_async_engine+from sqlmodel import SQLModel++ROOT = Path(__file__).resolve().parent.parent.parent.parent+SRC = ROOT / "src"+if str(SRC) not in sys.path:+ sys.path.insert(0, str(SRC))++import db.models # noqa: E402,F401+from db.repositories import WorkspaceConfigRepo # noqa: E402+from services.onboarding_reset import reset_onboarding_in_db # noqa: E402+++@pytest_asyncio.fixture+async def session():+ engine = create_async_engine(+ "sqlite+aiosqlite:///:memory:",+ connect_args={"check_same_thread": False},+ )+ async with engine.begin() as conn:+ await conn.run_sync(SQLModel.metadata.create_all)+ SessionLocal = async_sessionmaker(engine, expire_on_commit=False)+ async with SessionLocal() as s:+ yield s+ await engine.dispose()+++async def test_reset_onboarding_clears_edited_and_step(session, monkeypatch):+ monkeypatch.setenv("OPENRAG_STORAGE_MODE", "db")+ repo = WorkspaceConfigRepo(session)+ await repo.upsert("meta", {"edited": True})+ await repo.upsert(+ "onboarding",+ {"current_step": 4, "selected_nudge": "docs", "openrag_docs_filter_id": "kf-1"},+ )+ await repo.upsert("agent", {"llm_model": "gpt-4o", "llm_provider": "openai"})+ await session.commit()++ result = await reset_onboarding_in_db(session)+ await session.commit()++ meta = await repo.get_section("meta")+ onboarding = await repo.get_section("onboarding")+ agent = await repo.get_section("agent")++ assert result.previous_edited is True+ assert result.previous_step == 4+ assert meta["edited"] is False+ assert onboarding["current_step"] == 0+ assert onboarding.get("selected_nudge") is None+ assert onboarding.get("openrag_docs_filter_id") is None+ assert agent["llm_model"] == "gpt-4o"+++async def test_reset_models_clears_llm_and_embedding(session, monkeypatch):+ monkeypatch.setenv("OPENRAG_STORAGE_MODE", "db")+ repo = WorkspaceConfigRepo(session)+ await repo.upsert("meta", {"edited": True})+ await repo.upsert("onboarding", {"current_step": 4})+ await repo.upsert("agent", {"llm_model": "gpt-4o", "llm_provider": "anthropic"})+ await repo.upsert(+ "knowledge",+ {"embedding_model": "text-embedding-3-small", "embedding_provider": "anthropic"},+ )+ await session.commit()++ await reset_onboarding_in_db(session, reset_models=True)+ await session.commit()++ agent = await repo.get_section("agent")+ knowledge = await repo.get_section("knowledge")++ assert agent["llm_model"] == ""+ assert agent["llm_provider"] == "openai"+ assert knowledge["embedding_model"] == ""+ assert knowledge["embedding_provider"] == "openai"+++async def test_dry_run_does_not_write(session, monkeypatch):+ monkeypatch.setenv("OPENRAG_STORAGE_MODE", "db")+ repo = WorkspaceConfigRepo(session)+ await repo.upsert("meta", {"edited": True})+ await repo.upsert("onboarding", {"current_step": 2})+ await session.commit()++ await reset_onboarding_in_db(session, dry_run=True)++ meta = await repo.get_section("meta")+ onboarding = await repo.get_section("onboarding")+ assert meta["edited"] is True+ assert onboarding["current_step"] == 2