opusr-client/CLAUDE.md

OpusR-Client — Project Instructions

Project Overview

Rust CLI/TUI client for opusR Monitor (z/OS RACF security analysis). Connects to DB2 Native REST Services on z/OS via HTTPS. Designed for distribution to enterprise customers with z/OS RACF installations.

Architecture

OpusR-Client (Rust binary)
  │
  ├── Auth: RACF login → PassTicket (one-time, 10min TTL)
  ├── API:  HTTPS POST → DB2 DDF Native REST → JSON
  └── UI:   Terminal TUI (ratatui) or JSON stdout

• No middleware: direct HTTPS to DB2 DDF on z/OS
• Auth: Initial RACF login, then PassTicket-based (no password stored)
• Transport: TLS mandatory (DDF SECPORT), certificate validation
• Data: Read-only SELECT queries, JSON responses

z/OS Backend (3 REST Services)

1. opusrTables — list tables in OPUSR schema (→ main menu)
2. opusrColumns — list columns for a table (→ selection panel)
3. opusrQuery — dynamic query via Stored Procedure (→ data view)

All services use HTTP POST to DB2 DDF. Parameters are positional: P1, P2, P3... (DB2ServiceManager convention).

Tech Stack

• Rust 2021 edition, MSRV 1.75
• reqwest — HTTPS client with native-tls
• serde / serde_json — JSON serialization
• ratatui + crossterm — terminal UI
• clap — CLI argument parsing
• secrecy — password/token handling (zeroize on drop)
• keyring — OS keychain for session tokens (optional)
• tokio — async runtime

Security Requirements (CRITICAL)

• Passwords NEVER stored on disk, NEVER logged, NEVER in error messages
• Use secrecy::SecretString for all credential handling
• PassTickets stored only in memory, refreshed before expiry
• TLS certificate validation ON by default (--danger-accept-invalid-certs for dev only)
• No panics in production paths — use Result<T, E> everywhere
• Audit log: every REST call logged (without credentials)

Code Style

• cargo clippy -- -D warnings must pass
• cargo fmt applied before every commit
• No unwrap() or expect() except in tests
• Error types: use thiserror for library errors, anyhow in main
• Doc comments on all public items
• German comments OK for business logic, code identifiers in English

Development Workflow (Self-Steering Loop)

After every code change:

1. cargo fmt --check — formatting
2. cargo clippy -- -D warnings — lints
3. cargo test — all tests
4. cargo build --release — verify release build
5. If ANY step fails → fix immediately, restart from step 1
6. Only proceed when all 4 steps pass

When adding a new feature:

1. Plan in tasks/todo.md
2. Define types in src/models/
3. Write tests first (TDD)
4. Implement
5. Run full cycle
6. Mark complete in tasks/todo.md

After ANY correction from the user:

• Update tasks/lessons.md with what went wrong
• Write a rule that prevents the same mistake

DB2 REST Response Format

{
  "ResultSet Output": [
    {"COL1": "value", "COL2": 123},
    {"COL1": "value2", "COL2": 456}
  ]
}

• Column names are UPPERCASE
• CHAR fields are right-padded with spaces → always trim
• NULL values: field is absent from JSON object
• Errors: HTTP 400/401/403/500 with JSON error body

Project Structure

src/
  main.rs          — CLI entry point, argument parsing
  api/
    mod.rs         — REST client, request/response handling
    client.rs      — DB2RestClient struct
    services.rs    — opusrTables, opusrColumns, opusrQuery
  auth/
    mod.rs         — authentication module
    login.rs       — RACF login flow
    passticket.rs  — PassTicket management (refresh, expire)
  config/
    mod.rs         — configuration (host, port, schema, TLS)
    settings.rs    — CLI args + config file + env vars
  models/
    mod.rs         — data types
    table.rs       — TableInfo, ColumnInfo
    query.rs       — QueryFilter, QueryResult
    error.rs       — OpusrError enum
  tui/
    mod.rs         — terminal UI (ratatui)
    app.rs         — app state machine
    views/         — table list, column select, data view
tests/
  integration.rs   — integration tests with mock server
  api_tests.rs     — API client unit tests
docs/
  architecture.md  — design decisions
  security.md      — security model documentation
tasks/
  todo.md          — task tracker
  lessons.md       — learned mistakes