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)

opusrTables — list tables in OPUSR schema (→ main menu)
opusrColumns — list columns for a table (→ selection panel)
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:

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

When adding a new feature:

Plan in tasks/todo.md
Define types in src/models/
Write tests first (TDD)
Implement
Run full cycle
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

4.3 KiB Raw Blame History