Here is the technical documentation for the Core framework packages.

# Core Framework Documentation

## Package: pkg/log

### 1. Overview
`pkg/log` acts as the central observability and error handling primitive for the framework. It combines structured logging with a rich error type system (`Err`), allowing operational context (Operations, Codes) to travel with errors up the stack. It is designed to be used both standalone and as an injectable service within the Core framework.

### 2. Public API

**Error Types & Functions**
*   `type Err`: Struct implementing `error` with fields for `Op` (operation), `Msg` (message), `Err` (wrapped error), and `Code` (machine-readable code).
*   `func E(op, msg string, err error) error`: Creates a new error with operational context.
*   `func Wrap(err error, op, msg string) error`: Wraps an existing error, preserving existing codes if present.
*   `func WrapCode(err error, code, op, msg string) error`: Wraps an error and assigns a specific error code.
*   `func NewCode(code, msg string) error`: Creates a sentinel error with a code.
*   `func Is(err, target error) bool`: Wrapper for `errors.Is`.
*   `func As(err error, target any) bool`: Wrapper for `errors.As`.
*   `func Join(errs ...error) error`: Wrapper for `errors.Join`.
*   `func Op(err error) string`: Extracts the operation name from an error chain.
*   `func ErrCode(err error) string`: Extracts the error code from an error chain.
*   `func StackTrace(err error) []string`: Returns a slice of operations leading to the error.
*   `func LogError(err error, op, msg string) error`: Logs an error and returns it wrapped (reduces boilerplate).
*   `func LogWarn(err error, op, msg string) error`: Logs a warning and returns it wrapped.
*   `func Must(err error, op, msg string)`: Panics if error is not nil, logging it first.

**Logging Types & Functions**
*   `type Logger`: The main logging struct.
*   `type Level`: Integer type for log verbosity (`LevelQuiet` to `LevelDebug`).
*   `type Options`: Configuration struct for Logger (Level, Output, Rotation).
*   `type RotationOptions`: Config for log file rotation (Size, Age, Backups, Compression).
*   `func New(opts Options) *Logger`: Constructor.
*   `func Default() *Logger`: Returns the global default logger.
*   `func SetDefault(l *Logger)`: Sets the global default logger.
*   `func (l *Logger) Debug/Info/Warn/Error/Security(msg string, keyvals ...any)`: Leveled logging methods.

**Service Integration**
*   `type Service`: Wraps `Logger` for framework integration.
*   `func NewService(opts Options) func(*framework.Core) (any, error)`: Factory for dependency injection.
*   `type QueryLevel`, `type TaskSetLevel`: Message types for runtime management.

### 3. Internal Design
*   **Contextual Errors**: The `Err` struct forms a linked list via the `Err` field (inner error), allowing the reconstruction of a logical stack trace (`op` sequence) distinct from the runtime stack trace.
*   **Concurrency**: The `Logger` uses a `sync.RWMutex` to guard configuration and writes, ensuring thread safety.
*   **Rotation Strategy**: The `RotatingWriter` implements `io.WriteCloser`. It lazily opens files and checks size thresholds on every write, leveraging `pkg/io` to abstract the filesystem.
*   **Framework Integration**: The `Service` struct embeds `framework.ServiceRuntime`, utilizing the Actor pattern (Queries and Tasks) to allow dynamic log level adjustment at runtime without restarting the application.

### 4. Dependencies
*   `forge.lthn.ai/core/cli/pkg/io`: Used by `rotation.go` to handle file operations (renaming, deleting, writing) abstractly.
*   `forge.lthn.ai/core/cli/pkg/framework`: Used by `service.go` to hook into the application lifecycle and message bus.
*   Standard Lib: `errors`, `fmt`, `os`, `sync`, `time`.

### 5. Test Coverage Notes
*   **Error Unwrapping**: Verify `errors.Is` and `errors.As` work correctly through deep chains of `log.Err`.
*   **Logical Stack Traces**: Ensure `StackTrace()` returns the correct order of operations `["app.Run", "db.Query", "net.Dial"]`.
*   **Log Rotation**: Critical to test the boundary conditions of `MaxSize` and `MaxBackups` using a Mock Medium to avoid actual disk I/O.
*   **Concurrency**: Race detection on `Logger` when changing levels while logging is active.

### 6. Integration Points
*   **Application-wide**: This is the most imported package. All other packages should use `log.E` or `log.Wrap` instead of `fmt.Errorf` or `errors.New`.
*   **Core Framework**: The `Service` is designed to be passed to `core.New()`.

---

## Package: pkg/config

### 1. Overview
`pkg/config` provides 12-factor app configuration management. It layers configuration sources in a specific precedence (Environment > Config File > Defaults) and exposes them via a typed API or a dot-notation getter. It abstracts the underlying storage, allowing configs to be loaded from disk or memory.

### 2. Public API
*   `type Config`: The main configuration manager.
*   `type Option`: Functional option pattern for configuration.
*   `func New(opts ...Option) (*Config, error)`: Constructor.
*   `func LoadEnv(prefix string) map[string]any`: Helper to parse environment variables into a map.
*   `func (c *Config) Get(key string, out any) error`: Unmarshals a key (or root) into a struct.
*   `func (c *Config) Set(key string, v any) error`: Sets a value and persists it to storage.
*   `func (c *Config) LoadFile(m coreio.Medium, path string) error`: Merges a file into the current config.
*   `type Service`: Framework service wrapper for `Config`.
*   `func NewConfigService(c *core.Core) (any, error)`: Factory for dependency injection.

### 3. Internal Design
*   **Engine**: Uses `spf13/viper` as the underlying configuration engine for its merging and unmarshalling logic.
*   **Abstraction**: Unlike standard Viper usage, this package decouples the filesystem using `pkg/io.Medium`. This allows the config system to work in sandboxed environments or with mock filesystems.
*   **Persistence**: The `Set` method triggers an immediate write-back to the storage medium, making the config file the source of truth for runtime changes.
*   **Environment Mapping**: Automatically maps `CORE_CONFIG_FOO_BAR` to `foo.bar` using a `strings.Replacer`.

### 4. Dependencies
*   `github.com/spf13/viper`: Core logic for map merging and unmarshalling.
*   `gopkg.in/yaml.v3`: For marshalling data when saving.
*   `forge.lthn.ai/core/cli/pkg/io`: For reading/writing config files.
*   `forge.lthn.ai/core/cli/pkg/framework/core`: For service integration and error handling.

### 5. Test Coverage Notes
*   **Precedence**: Verify that Environment variables override File values.
*   **Persistence**: Test that `Set()` writes valid YAML back to the `Medium`.
*   **Type Safety**: Ensure `Get()` correctly unmarshals into complex structs and returns errors on type mismatches.

### 6. Integration Points
*   **Bootstrap**: Usually the first service initialized in `core.New()`.
*   **Service Configuration**: Other services (like `auth` or `log`) should inject `config.Service` to retrieve their startup settings.

---

## Package: pkg/io

### 1. Overview
`pkg/io` provides a filesystem abstraction layer (`Medium`). Its philosophy is to decouple business logic from the `os` package, facilitating easier testing (via mocks) and security (via sandboxing).

### 2. Public API
*   `type Medium`: Interface defining filesystem operations (`Read`, `Write`, `List`, `Stat`, `Open`, `Create`, `Delete`, `Rename`, etc.).
*   `var Local`: A pre-initialized `Medium` for the host root filesystem.
*   `func NewSandboxed(root string) (Medium, error)`: Returns a `Medium` restricted to a specific directory.
*   `type MockMedium`: In-memory implementation of `Medium` for testing.
*   `func NewMockMedium() *MockMedium`: Constructor for the mock.
*   **Helpers**: `Read`, `Write`, `Copy`, `EnsureDir`, `IsFile`, `ReadStream`, `WriteStream` (accept `Medium` as first arg).

### 3. Internal Design
*   **Interface Segregation**: The `Medium` interface mimics the capabilities of `os` and `io/fs` but bundles them into a single dependency.
*   **Mocking**: `MockMedium` uses `map[string]string` for files and `map[string]bool` for directories. It implements manual path logic to simulate filesystem behavior (e.g., verifying a directory is empty before deletion) without touching the disk.
*   **Sandboxing**: The `local` implementation (imported internally) enforces path scoping to prevent traversal attacks when using `NewSandboxed`.

### 4. Dependencies
*   Standard Lib: `io`, `io/fs`, `os`, `path/filepath`, `strings`, `time`.
*   `forge.lthn.ai/core/cli/pkg/io/local`: (Implied) The concrete implementation for OS disk access.

### 5. Test Coverage Notes
*   **Mock fidelity**: The `MockMedium` must behave exactly like the OS. E.g., `Rename` should fail if the source doesn't exist; `Delete` should fail if a directory is not empty.
*   **Sandboxing**: Verify that `..` traversal attempts in `NewSandboxed` cannot access files outside the root.

### 6. Integration Points
*   **Universal Dependency**: Used by `log` (rotation), `config` (loading), and `auth` (user DB).
*   **Testing**: Application code should accept `io.Medium` in constructors rather than using `os.Open` directly, enabling unit tests to use `NewMockMedium()`.

---

## Package: pkg/crypt

### 1. Overview
`pkg/crypt` provides "batteries-included," opinionated cryptographic primitives. It abstracts away the complexity of parameter selection (salt length, iteration counts, nonce generation) to prevent misuse of crypto algorithms.

### 2. Public API
*   **Hashing**: `HashPassword` (Argon2id), `VerifyPassword`, `HashBcrypt`, `VerifyBcrypt`.
*   **Symmetric**: `Encrypt`/`Decrypt` (ChaCha20-Poly1305), `EncryptAES`/`DecryptAES` (AES-GCM).
*   **KDF**: `DeriveKey` (Argon2), `DeriveKeyScrypt`, `HKDF`.
*   **Checksums**: `SHA256File`, `SHA512File`, `SHA256Sum`, `SHA512Sum`.
*   **HMAC**: `HMACSHA256`, `HMACSHA512`, `VerifyHMAC`.

### 3. Internal Design
*   **Safe Defaults**: Uses Argon2id for password hashing with tuned parameters (64MB memory, 3 iterations).
*   **Container Format**: Symmetric encryption functions return a concatenated byte slice: `[Salt (16b) | Nonce (Variable) | Ciphertext]`. This ensures the decryption function has everything it needs without separate state management.
*   **Randomness**: Automatically handles salt and nonce generation using `crypto/rand`.

### 4. Dependencies
*   `golang.org/x/crypto`: For Argon2, ChaCha20, HKDF, Scrypt.
*   Standard Lib: `crypto/aes`, `crypto/cipher`, `crypto/rand`, `crypto/sha256`.

### 5. Test Coverage Notes
*   **Interoperability**: Ensure `Encrypt` output can be read by `Decrypt`.
*   **Tamper Resistance**: manually modifying a byte in the ciphertext or nonce must result in a decryption failure (AuthTag check).
*   **Vectors**: Validate hashing against known test vectors where possible.

### 6. Integration Points
*   **Auth**: Heavily used by `pkg/auth` for password storage and potentially for encrypted user data.
*   **Data Protection**: Any service requiring data at rest encryption should use `crypt.Encrypt`.

---

## Package: pkg/auth

### 1. Overview
`pkg/auth` implements a persistent user identity system based on OpenPGP challenge-response authentication. It supports a unique "Air-Gapped" workflow where challenges and responses are exchanged via files, alongside standard online methods. It manages user lifecycles, sessions, and key storage.

### 2. Public API
*   `type Authenticator`: Main logic controller.
*   `type User`: User metadata struct.
*   `type Session`: Active session token struct.
*   `func New(m io.Medium, opts ...Option) *Authenticator`: Constructor.
*   `func (a *Authenticator) Register(username, password string) (*User, error)`: Creates new user and PGP keys.
*   `func (a *Authenticator) Login(userID, password string) (*Session, error)`: Password-based fallback login.
*   `func (a *Authenticator) CreateChallenge(userID string) (*Challenge, error)`: Starts PGP auth flow.
*   `func (a *Authenticator) ValidateResponse(userID string, signedNonce []byte) (*Session, error)`: Completes PGP auth flow.
*   `func (a *Authenticator) ValidateSession(token string) (*Session, error)`: Checks token validity.
*   `func (a *Authenticator) WriteChallengeFile(userID, path string) error`: For air-gapped flow.
*   `func (a *Authenticator) ReadResponseFile(userID, path string) (*Session, error)`: For air-gapped flow.

### 3. Internal Design
*   **Storage Layout**: Uses a flat-file database approach on `io.Medium`:
    *   `users/{id}.pub`: Public Key.
    *   `users/{id}.key`: Encrypted Private Key.
    *   `users/{id}.lthn`: Password Hash.
    *   `users/{id}.json`: Encrypted metadata.
*   **Identity**: User IDs are hashes of usernames to anonymize storage structure.
*   **Flow**:
    1.  Server generates random nonce.
    2.  Server encrypts nonce with User Public Key.
    3.  User decrypts nonce (client-side) and signs it.
    4.  Server validates signature against User Public Key.

### 4. Dependencies
*   `forge.lthn.ai/core/cli/pkg/io`: For user database storage.
*   `forge.lthn.ai/core/cli/pkg/crypt/lthn`: (Implied) Specific password hashing.
*   `forge.lthn.ai/core/cli/pkg/crypt/pgp`: (Implied) OpenPGP operations.
*   `forge.lthn.ai/core/cli/pkg/framework/core`: Error handling.

### 5. Test Coverage Notes
*   **Flow Verification**: Full integration test simulating a client: Register -> Get Challenge -> Decrypt/Sign (Mock Client) -> Validate -> Get Token.
*   **Security**: Ensure `server` user cannot be deleted. Ensure expired sessions are rejected.
*   **Persistence**: Ensure user data survives an `Authenticator` restart (i.e., data is actually written to medium).

### 6. Integration Points
*   **API Gateways**: HTTP handlers would call `ValidateSession` on every request.
*   **CLI Tools**: Would use `WriteChallengeFile`/`ReadResponseFile` for offline authentication.
