Explorer docs
planuai-explorerredacted view

UAI Explorer Enterprise Public-Safe v1 Plan

Synced UAI Explorer plan documentation from docs/plans/enterprise-public-safe-v1.md.

Updated 2026-06-21·Freshness: Reference·Sensitive tokens or credentials were hidden before display.

UAI Explorer Enterprise Public-Safe v1 Plan

Created: 2026-06-20

Status: superseded by production cutover evidence on 2026-06-21. This plan is historical design lineage for public-safe v1. Current operating truth starts with [REDACTED:high-entropy].md, [REDACTED:high-entropy].md, and [REDACTED:high-entropy].md.

Objective

Turn UAI Explorer from a mesh-only file browser into a professional, public-safe documentation and context portal with real user separation, tag-based access, redaction, auditability, and distinct human and AI experiences.

This plan originally stopped at migration-ready and did not authorize production cutover. Production CT 121 was later cut over internally to public-safe 0.2.3 under separate operator authority and backup evidence.

Enterprise Product Standard

UAI Explorer v1 should feel like a restrained enterprise knowledge portal:

  • Calm login and session experience.
  • Curated project catalog instead of a raw filesystem tree.
  • Clear document summaries, metadata, tags, freshness, and sensitivity state.
  • Professional reader UI with navigation, search, context notes, and redaction indicators.
  • Admin console for users, tags, catalog entries, audit review, and migration readiness.
  • Separate AI context API with bounded, redacted packets and audit IDs.
  • No public ambiguity around what a user is allowed to see.

Architecture

Keep FastAPI for v1 and add internal modules around the existing app:

  • auth: local users, password hashing, sessions, roles, and tag grants.
  • catalog: allowlisted content registry and source path resolution.
  • redaction: shared redaction engine used before UI, AI, audit, and download paths.
  • audit: append-only access and decision log.
  • human_ui: catalog, reader, context notes, admin screens.
  • ai_api: bounded context endpoints for AI users only.
  • ops: health, readiness, migration status, and sandbox verification.

Use SQLite for v1 persistence. It is enough for the expected operator-managed user count and keeps the first hardened release simple to deploy and back up.

Data Model

Required tables:

  • users: id, username, display_name, password_hash, role, disabled, created_at, updated_at.
  • user_tags: user_id, tag.
  • sessions: id, user_id, token_hash, expires_at, created_at, last_seen_at.
  • catalog_items: id, slug, title, project, kind, source_path, summary, sensitivity, allow_code, human_visible, ai_visible, created_at, updated_at.
  • catalog_tags: catalog_item_id, required_tag.
  • context_notes: id, catalog_item_id, audience, body, created_at, updated_at.
  • audit_events: id, user_id, actor_type, action, target, decision, redaction_state, ip_hash, user_agent_hash, created_at.
  • migration_checks: id, check_name, status, evidence, checked_at.

Access rule:

  • Active users only.
  • Admin users bypass tags.
  • Human users can view only human-visible catalog items where all required tags are granted.
  • AI users can view only AI-visible catalog items through /api/ai/*.
  • Code access requires the project tag and the code tag.

Public Interfaces

Auth:

  • POST /api/auth/login
  • POST /api/auth/logout
  • GET /api/auth/me

Human:

  • GET /api/catalog
  • GET /api/catalog/{slug}
  • GET /api/content/{slug}
  • GET /api/context-notes/{slug}

AI:

  • GET /api/ai/catalog
  • GET /api/ai/context/{slug}

Admin:

  • GET /api/admin/users
  • POST /api/admin/users
  • PATCH /api/admin/users/{id}
  • GET /api/admin/catalog
  • POST /api/admin/catalog
  • PATCH /api/admin/catalog/{id}
  • GET /api/admin/audit
  • GET /api/admin/migration-readiness

Ops:

  • GET /health
  • GET /ready

The existing raw path endpoints remain development-only until replaced or wrapped by catalog authorization. Non-admin raw download is disabled in public-safe mode.

Redaction Policy

Redaction runs before response construction, rendering, AI packet creation, audit details, and download decisions.

Redact:

  • Private key blocks.
  • Bearer tokens and session cookies.
  • API-key-shaped values.
  • Webhook URLs.
  • Database URLs and credential-bearing URLs.
  • Env var values whose names include KEY, TOKEN, SECRET, PASSWORD, COOKIE, AUTH, or WEBHOOK.
  • High-entropy token-like strings.

Every content response includes redaction_state:

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

If redaction confidence is low for a file, refuse the response for non-admin users and log the refusal.

Human UX

Required screens:

  • Login.
  • Project catalog.
  • Project detail.
  • Document reader.
  • Code redacted view.
  • Denied access.
  • Admin user management.
  • Admin catalog management.
  • Admin audit log.
  • Migration readiness panel.

QoL requirements:

  • Search catalog by title, summary, project, and tag.
  • Filter by project and content kind.
  • Show recent docs and last updated state.
  • Preserve reader scroll position inside a session.
  • Mobile layout must keep navigation usable without overlapping content.
  • Redaction labels must explain what happened without exposing hidden details.

AI UX

AI users are not browser users. They receive structured context packets:

  • slug
  • title
  • project
  • summary
  • allowed_tags
  • redaction_state
  • excerpts
  • context_notes
  • source_metadata
  • audit_event_id

Caps:

  • Default context cap: 24,000 characters per request.
  • Max excerpt count: 12.
  • No raw file downloads.
  • No uploads.
  • No admin endpoints.
  • No hidden filesystem paths in denied responses.

Implementation Sequence

  1. Add SQLite persistence and startup migration runner.
  2. Add auth, sessions, roles, and admin bootstrap from env.
  3. Add catalog tables and seed a small curated catalog.
  4. Replace public tree/file reads with catalog-authorized content reads.
  5. Add redaction engine and tests.
  6. Add audit logging across auth, content, denial, AI, and admin paths.
  7. Build polished human UI.
  8. Add AI context endpoints and caps.
  9. Add admin catalog/user/audit/migration screens.
  10. Add sandbox deploy script for container 126.
  11. Run QA/QC/QoL loop and record evidence.
  12. Prepare migration package and stop before production cutover.

Migration-Ready Definition

Historical definition from the pre-cutover phase:

Migration-ready means:

  • Sandbox container 126 is provisioned and healthy.
  • Production container 121 is untouched and healthy.
  • Auth, catalog, redaction, AI separation, audit, admin UI, and migration checks pass in sandbox.
  • A backup and rollback path are documented and tested against sandbox.
  • The migration runbook has current evidence.
  • Operator can decide whether to cut over production in a separate step.

Current Result

As of 2026-06-21:

  • Production CT 121 runs UAI Explorer 0.2.3 in public-safe mode.
  • Sandbox CT 126 remains the staging and verification lane on 0.2.3.
  • No DNS, TLS, firewall, reverse proxy, NetBird, or public-route changes were made.
  • Public-safe v1 has no open UAI Explorer decisions.
  • Future public exposure, additional user/tag rollout, real-content promotion, storage cleanup, and node onboarding are separate runbook-driven work.