Fork: 0
yangyangxie / cortex-hub
Transfer to URL with SHA Find file
Newer
Older
cortex-hub / docs / auth_tls_todo.md
@Antigravity AI Antigravity AI 22 hours ago 3 KB feat(auth): bootstrap Day 1 local auth fallback, migrations, and sandbox node
Raw Blame History

Cortex Hub: Authentication & TLS Implementation Tracking

This document serves as the master checklist for implementing the Day 1 / Day 2 Securitization Journey.

Phase 1: Pre-Release UX Blockers

These tasks ensure the out-of-the-box local developer experience functions fully.

  • Infrastructure: Fix the .env override trap in docker-compose.yml.
  • Setup Script: Update setup.sh to accept optional config.yaml to cure the "Brain Dead" state.
  • Infrastructure: Include a bundled sandbox-node container in docker-compose.yml so the Hub isn't an "Empty Shell" on startup.

Phase 2: Day 1 Local Auth Fallback

Enable local authentication using the CORTEX_ADMIN_PASSWORD generated by the setup script.

  • Database Model: Update User model (app/db/models/user.py) to include a nullable password_hash column.
  • Configuration: Update Settings (app/config.py) to make OIDC settings optional and add an oidc_enabled: bool flag.
  • Backend Initialization: If CORTEX_ADMIN_PASSWORD is present in the environment for the SUPER_ADMINS initialization, hash it and assign it to the admin account.
  • API Routes: Create local login endpoints (POST /api/v1/users/login/local to issue JWTs) and (PUT /api/v1/users/password for password resets).
  • Frontend: Redesign the Auth/Login page to display a Username/Password default form.

Phase 3: Day 1 Swarm Control (Insecure/Local Status)

Support running the mesh over internal loopbacks but strictly warn the end-user.

  • Backend Configuration: Add GRPC_TLS_ENABLED, GRPC_EXTERNAL_ENDPOINT to config.py.
  • Backend API: Expose a /api/v1/status or equivalent endpoint providing the current TLS/Hostname state to the frontend.
  • Frontend UI: Add persistent "Insecure Mode" and "Missing External Hostname" warning banners to the Swarm Dashboard frontend when running in Day 1 mode.

Phase 4: Day 2 Single Sign-On (OIDC Linking)

Allow transition to Enterprise SSO without breaking or duplicate accounting.

  • Backend Service: Update app/core/services/auth.py (handle_callback) to search for existing local users via email and safely link the incoming OIDC sub payload.
  • Admin API: Create PUT /api/v1/admin/config/oidc for UI-based toggling and configuration of SSO parameters without restarting.
  • Frontend Login: Dynamically query /api/v1/auth/config. If enabled, render the "Log in with SSO" button instead of or alongside local Auth.
  • Frontend Settings: Create an Admin Settings UI panel for OIDC Configuration.

Phase 5: Day 2 Swarm Control (Encrypted Mesh)

Wrap the gRPC nodes with SSL definitions.

  • Backend gRPC Server: Update serve_grpc in app/core/grpc/services/grpc_server.py. If GRPC_TLS_ENABLED, load generic server certs and call server.add_secure_port().
  • Admin API: Create PUT /api/v1/admin/config/swarm for UI-based configuration of GRPC_EXTERNAL_ENDPOINT and SSL Cert paths.
  • Node Provisioning: Update the script generator _generate_node_config_yaml (app/api/routes/nodes.py) to inject the GRPC_EXTERNAL_ENDPOINT and toggle grpc.ssl_channel_credentials() for python clients.
  • Frontend Settings: Add a prompt to the Settings UI stating that "Updating SSL/Endpoint will disconnect all nodes!" upon saving.