Back to Explorer
runbookuai-explorerOperator truth

Public-Safe Access Runbook

Synced UAI Explorer runbook documentation from docs/runbooks/public-safe-access.md.

Updated 2026-06-21·Freshness: Current·No secret-like patterns were observed in this view.

Public-Safe Access Runbook

Created: 2026-06-20

Purpose

Guide the move from mesh-only UAI Explorer to a safer public-access-ready portal with login, tag-based authorization, redaction, audit logs, and separate human and AI access surfaces.

Current State

  • UAI Explorer is a FastAPI app with static HTML, CSS, and JavaScript.
  • The enterprise build has login, role and tag authorization, curated catalog access, redaction, audit logging, and separate human and AI surfaces.
  • Production CT 121 runs the public-safe 0.2.3 build internally at 10.0.0.121:8080.
  • Sandbox CT 126 remains the staging and verification lane at 10.0.0.126:8080.
  • In public-safe mode, legacy tree, file, raw download, upload, and upload listing endpoints are refused, including for admins.
  • Private lab file inspection can exist only when PUBLIC_SAFE_MODE=false.
  • No DNS, TLS, firewall, reverse proxy, NetBird, or public-route change was made during the internal production cutover.

Required Safety Gates Before External Exposure

These gates must remain true before any external route, public DNS, TLS, firewall, reverse-proxy, or NetBird exposure is added:

  • Login is required for all non-health content.
  • Users have roles and tags.
  • Catalog items are allowlisted with required tags.
  • File content is redacted before response rendering.
  • Raw download is disabled in public-safe mode, including for admins. Setting ALLOW_ADMIN_RAW_READ=true must not re-enable raw downloads while PUBLIC_SAFE_MODE=true.
  • Legacy filesystem and upload APIs are disabled in public-safe mode.
  • Human UI and AI API are separated.
  • Audit logging records access and denials.
  • Sandbox verification passes before promotion.
  • Production backup and rollback evidence are current.
  • /ready reports public_safe_mode=true, raw survey mounts absent, legacy file APIs disabled, raw downloads disabled, and uploads disabled.

User Model

Use local Explorer-managed users for v1:

  • admin: manages users, tags, catalog, and audit.
  • human: uses the professional reader UI.
  • ai: uses only bounded context APIs.

Tag examples:

  • cortex
  • uai-mesh
  • uai-web
  • uai-portal
  • docs
  • code

Access rule:

  • User must be active.
  • User must hold all tags required by a catalog item.
  • Admin can bypass tags.
  • Code access requires the project tag and the code tag.

Content Organization

Replace raw filesystem browsing with a curated catalog:

  • Project title and summary.
  • Source path.
  • Content kind: docs, code, runbook, evidence, handoff, public.
  • Required tags.
  • Sensitivity state.
  • Human visibility.
  • AI visibility.
  • Redaction state.

Do not expose arbitrary paths in public-safe mode.

Redaction Requirements

Redact before content reaches UI, AI JSON, logs, or audits:

  • Private key blocks.
  • Bearer tokens.
  • API-key-shaped values.
  • Webhook URLs.
  • Cookie and session values.
  • Database URLs and connection strings.
  • Env vars with names such as KEY, TOKEN, SECRET, PASSWORD, COOKIE, WEBHOOK, DATABASE_URL, and AUTH.
  • High-entropy token-like strings.

The response should include a redaction_state value:

  • no-secrets-observed
  • redacted
  • refused-secret-like-input

The response should also make the boundary explicit:

  • redaction_boundary=server-side
  • raw_available_to_client=false
  • category counts for redaction matches
  • a hash of the redacted artifact only
  • API headers such as X-UAI-Redaction-Boundary=server-side and X-UAI-Raw-Content=not-sent

Frontend redaction controls are usability aids, not the security boundary. Never rely on client-side script, CSS, or DOM state to protect raw content.

For public exposure, prefer an air-gapped pipeline:

  • raw survey zone for unclassified device/project material,
  • redaction worker for classification and sanitized output,
  • public Explorer zone mounted only to sanitized artifacts.

Hardening note:

  • While PUBLIC_SAFE_MODE=true, /api/tree, /api/file, /api/raw, /api/upload, and /api/uploads should return 403 after authentication.
  • Readiness checks should fail if raw downloads, legacy filesystem APIs, or upload APIs are enabled in a public-safe process.

Human UX Requirements

  • Login screen.
  • Project catalog, not raw file tree.
  • Reader view with clear metadata, summary, tags, and redaction indicators.
  • Context notes beside documents.
  • Denied-access view that does not reveal hidden file paths.
  • Admin user and catalog management views.
  • Responsive desktop and mobile layout.

AI API Requirements

AI users must not use human file, raw filesystem, upload, database, or admin endpoints.

Minimum endpoints:

  • POST /api/auth/login
  • POST /api/auth/logout
  • GET /api/auth/session
  • GET /api/ai/bootstrap
  • GET /api/ai/catalog
  • GET /api/ai/context/{slug}
  • POST /api/ai/feedback
  • GET /health
  • GET /ready

AI context responses must include:

  • Title.
  • Summary.
  • Redacted excerpts.
  • Source metadata.
  • Tags.
  • Redaction state.
  • Character cap.
  • Audit event id.
  • redaction_boundary=server-side.
  • raw_available_to_client=false.

MCP servers and local AI adapters must be narrow clients over these endpoints. They must not expose generic HTTP proxy, shell, filesystem, SQLite, admin, upload, or raw-download tools. Store AI service account credentials in an OS secret store or private environment variable; never write passwords or session cookies into docs, prompts, screenshots, logs, or evidence. Short-lived UAI_EXPLORER_AI_API_KEY values may appear only in transient task prompts and must not be persisted.

Public or AI-facing embeddings may use only content retrieved through /api/ai/context/{slug} by an authorized AI account. Do not embed raw-survey-zone, unapproved sanitized-exports, private selected-redaction input, raw file aliases, raw source hashes, direct DATA_ROOT reads, or device filesystem crawls.

Verification Checklist

  • Anonymous request to catalog returns 401.
  • Human without required tag receives 403.
  • Human with cortex can read Cortex docs.
  • Human with cortex but without code cannot view code.
  • AI user can call /api/ai/context/{slug} only for AI-visible items.
  • AI user can call /api/ai/bootstrap and optionally /api/ai/feedback.
  • Admin accounts cannot use the AI lane as adapter identity.
  • AI user cannot call raw, upload, admin, or human file endpoints.
  • Catalog source paths under raw-survey-zone, sanitized-exports, uploads, or other denied runtime lanes are refused.
  • Authenticated admin receives 403 for /api/tree, /api/file, /api/raw, /api/upload, and /api/uploads while PUBLIC_SAFE_MODE=true.
  • Setting ALLOW_ADMIN_RAW_READ=true does not re-enable raw downloads while PUBLIC_SAFE_MODE=true.
  • Context notes are redacted before human or AI delivery.
  • Readiness includes passing checks for raw_downloads_disabled, legacy_file_apis_disabled, and upload_apis_disabled.
  • Readiness includes raw_survey_zone_not_mounted=pass; if a raw survey zone is mounted under the public data root, /ready must stop reporting ready.
  • Redaction tests cover env files, bearer tokens, private keys, webhooks, and database URLs.
  • Audit rows are created for login, read, denial, and AI context access.