conductor(setup): Add conductor setup files

conductor/code_styleguides/general.md

@@ -0,0 +1,23 @@
+# General Code Style Principles
+
+This document outlines general coding principles that apply across all languages and frameworks used in this project.
+
+## Readability
+- Code should be easy to read and understand by humans.
+- Avoid overly clever or obscure constructs.
+
+## Consistency
+- Follow existing patterns in the codebase.
+- Maintain consistent formatting, naming, and structure.
+
+## Simplicity
+- Prefer simple solutions over complex ones.
+- Break down complex problems into smaller, manageable parts.
+
+## Maintainability
+- Write code that is easy to modify and extend.
+- Minimize dependencies and coupling.
+
+## Documentation
+- Document *why* something is done, not just *what*.
+- Keep documentation up-to-date with code changes.

conductor/code_styleguides/go.md

@@ -0,0 +1,48 @@
+# Effective Go Style Guide Summary
+
+This document summarizes key rules and best practices from the official "Effective Go" guide for writing idiomatic Go code.
+
+## 1. Formatting
+- **`gofmt`:** All Go code **must** be formatted with `gofmt` (or `go fmt`). This is a non-negotiable, automated standard.
+- **Indentation:** Use tabs for indentation (`gofmt` handles this).
+- **Line Length:** Go has no strict line length limit. Let `gofmt` handle line wrapping.
+
+## 2. Naming
+- **`MixedCaps`:** Use `MixedCaps` or `mixedCaps` for multi-word names. Do not use underscores.
+- **Exported vs. Unexported:** Names starting with an uppercase letter are exported (public). Names starting with a lowercase letter are not exported (private).
+- **Package Names:** Short, concise, single-word, lowercase names.
+- **Getters:** Do not name getters with a `Get` prefix. A getter for a field named `owner` should be named `Owner()`.
+- **Interface Names:** One-method interfaces are named by the method name plus an `-er` suffix (e.g., `Reader`, `Writer`).
+
+## 3. Control Structures
+- **`if`:** No parentheses around the condition. Braces are mandatory. Can include an initialization statement (e.g., `if err := file.Chmod(0664); err != nil`).
+- **`for`:** Go's only looping construct. Unifies `for` and `while`. Use `for...range` to iterate over slices, maps, strings, and channels.
+- **`switch`:** More general than in C. Cases do not fall through by default (use `fallthrough` explicitly). Can be used without an expression to function as a cleaner `if-else-if` chain.
+
+## 4. Functions
+- **Multiple Returns:** Functions can return multiple values. This is the standard way to return a result and an error (e.g., `value, err`).
+- **Named Result Parameters:** Return parameters can be named. This can make code clearer and more concise.
+- **`defer`:** Schedules a function call to be run immediately before the function executing `defer` returns. Use it for cleanup tasks like closing files.
+
+## 5. Data
+- **`new` vs. `make`:**
+  - `new(T)`: Allocates memory for a new item of type `T`, zeroes it, and returns a pointer (`*T`).
+  - `make(T, ...)`: Creates and initializes slices, maps, and channels only. Returns an initialized value of type `T` (not a pointer).
+- **Slices:** The preferred way to work with sequences. They are more flexible than arrays.
+- **Maps:** Use the "comma ok" idiom to check for the existence of a key: `value, ok := myMap[key]`.
+
+## 6. Interfaces
+- **Implicit Implementation:** A type implements an interface by implementing its methods. No `implements` keyword is needed.
+- **Small Interfaces:** Prefer many small interfaces over one large one. The standard library is full of single-method interfaces (e.g., `io.Reader`).
+
+## 7. Concurrency
+- **Share Memory By Communicating:** This is the core philosophy. Do not communicate by sharing memory; instead, share memory by communicating.
+- **Goroutines:** Lightweight, concurrently executing functions. Start one with the `go` keyword.
+- **Channels:** Typed conduits for communication between goroutines. Use `make` to create them.
+
+## 8. Errors
+- **`error` type:** The built-in `error` interface is the standard way to handle errors.
+- **Explicit Error Handling:** Do not discard errors with the blank identifier (`_`). Check for errors explicitly.
+- **`panic`:** Reserved for truly exceptional, unrecoverable situations. Generally, libraries should not panic.
+
+*Source: [Effective Go](https://go.dev/doc/effective_go)*

conductor/index.md

@@ -0,0 +1,14 @@
+# Project Context
+
+## Definition
+- [Product Definition](./product.md)
+- [Product Guidelines](./product-guidelines.md)
+- [Tech Stack](./tech-stack.md)
+
+## Workflow
+- [Workflow](./workflow.md)
+- [Code Style Guides](./code_styleguides/)
+
+## Management
+- [Tracks Registry](./tracks.md)
+- [Tracks Directory](./tracks/)

conductor/product-guidelines.md

@@ -0,0 +1,24 @@
+# Product Guidelines: Secrets
+
+## UX Principles
+- **Security-First Defaults:** All default configurations prioritize the highest security settings. Convenience never overrides system integrity.
+- **High-Visibility Feedback:** Both CLI and API provide immediate, unambiguous feedback for all operations. Success/failure states are clearly indicated with actionable context.
+- **Simplified Setup Experience:** Minimize "day-zero" friction. The system is designed to be operational with minimal required configuration, using sensible defaults where security isn't compromised.
+
+## Error Handling & Messaging
+- **Concise & Safe Tone:** Error messages are direct and technical. They must never leak internal system state, sensitive credentials, or detailed stack traces to the end-user.
+- **Remediation-Oriented:** Where possible, provide clear next steps for the user to resolve the error without compromising security.
+
+## Engineering Standards
+- **Modular Clean Architecture:** Strict adherence to the architecture defined in the `internal/` directory (Domain, Usecase, Service, Repository, HTTP). Cross-layer leaks are prohibited.
+- **Test-Driven Development Culture:** Every new feature or bug fix MUST be accompanied by relevant unit and integration tests. No code is merged without verified test coverage.
+- **Security-Focused CI/CD:** Mandatory security scanning (`gosec`, `govulncheck`) and linting (`golangci-lint`) on every commit. Vulnerabilities are treated as blockers.
+
+## API & Interface Design
+- **URL-Based Versioning:** All API endpoints are versioned in the URL path (e.g., `/v1/secrets`). Breaking changes require a new major version.
+- **RESTful Consistency:** Standard HTTP methods (GET, POST, PUT, DELETE) and status codes are used consistently across all resources.
+- **Unified Response Format:** All API responses follow a standardized envelope structure to ensure predictability for client integrations.
+
+## Documentation Style (Extended from docs-style-guide.md)
+- **Action-Oriented:** Documentation prioritizes "how-to" guides and practical examples over theoretical explanations.
+- **Copy-Safe Examples:** All examples use clearly synthetic values (e.g., `<client-id>`, `example.com`) to prevent accidental leaks.

conductor/product.md

@@ -0,0 +1,29 @@
+# Initial Concept
+
+A lightweight secrets manager designed for simplicity and security. It provides envelope encryption, transit encryption, API authentication, and cryptographic audit logs. Inspired by HashiCorp Vault, it focuses on ease of use and deployment for modern application stacks.
+
+# Product Definition: Secrets
+
+## Core Mission
+To provide a secure, developer-friendly, and lightweight secrets management platform that ensures the confidentiality, integrity, and availability of application secrets through modern cryptographic practices.
+
+## Target Audience
+- **Developers:** Who need simple, high-performance APIs for secret retrieval and encryption services (EaaS).
+- **Security Compliance Teams:** Who require tamper-resistant audit trails for compliance audits (PCI-DSS, SOC2).
+
+## Core Features
+- **Secret Management (Storage):** Versioned, envelope-encrypted storage with support for arbitrary key-value pairs.
+- **Transit Engine (EaaS):** On-the-fly encryption/decryption of application data without database storage.
+- **Tokenization Engine:** Format-preserving tokens for sensitive data types like credit card numbers.
+- **Audit Logs:** HMAC-signed audit trails capturing every access attempt and policy evaluation.
+- **KMS Integration:** Native support for AWS KMS, Google Cloud KMS, Azure Key Vault, and HashiCorp Vault.
+
+## Strategic Priorities
+- **v1.0.0 Stability:** Achieving an API freeze and production-ready stability for mission-critical deployments.
+- **PCI-DSS Alignment:** Ensuring the cryptographic model and audit trails meet the requirements for handling payment card data.
+- **Kubernetes-Native Deployment:** Optimized Docker images and Helm-ready configurations for cloud-native orchestration.
+
+## Success Metrics
+- **Performance:** Sub-millisecond latency for secret retrieval and transit encryption operations.
+- **Reliability:** 99.9% availability for key retrieval services.
+- **Security:** Zero unauthenticated or unauthorized access to secret material.

conductor/setup_state.json

@@ -0,0 +1 @@
+{"last_successful_step": "3.3_initial_track_generated"}

conductor/tech-stack.md

@@ -0,0 +1,31 @@
+# Tech Stack: Secrets
+
+## Core Technologies
+- **Language:** [Go](https://go.dev/) (v1.26.0+) - Chosen for its high concurrency, strong typing, and performance.
+- **Web Framework:** [Gin](https://github.com/gin-gonic/gin) - A high-performance HTTP web framework with a fast HTTP router and custom middleware support.
+- **CLI Framework:** [urfave/cli/v3](https://github.com/urfave/cli) - A library for building command-line applications in Go.
+
+## Data Persistence
+- **PostgreSQL:** Primary relational database for production environments. Supported via `lib/pq`.
+- **MySQL:** Alternative relational database support for broader infrastructure compatibility. Supported via `go-sql-driver/mysql`.
+- **Migrations:** [golang-migrate/migrate](https://github.com/golang-migrate/migrate) - Versioned database migrations for both PostgreSQL and MySQL.
+
+## Cryptography & Security
+- **Envelope Encryption:** [gocloud.dev/secrets](https://gocloud.dev/howto/secrets/) - Abstracted access to various KMS providers for root-of-trust encryption.
+- **Password Hashing:** [go-pwdhash](https://github.com/allisson/go-pwdhash) - Argon2id hashing for secure storage of client secrets and passwords.
+- **Audit Signing:** HMAC-SHA256 for tamper-evident cryptographic audit logs.
+
+## KMS Providers (Native Support)
+- **Google Cloud KMS**
+- **AWS KMS**
+- **Azure Key Vault**
+- **HashiCorp Vault** (via transit engine)
+
+## Observability & Monitoring
+- **OpenTelemetry:** Native instrumentation for metrics using `go.opentelemetry.io/otel`.
+- **Prometheus Export:** Standardized metrics endpoints compatible with Prometheus scrapers.
+
+## Testing & Quality Assurance
+- **Unit Testing:** [Testify](https://github.com/stretchr/testify) for assertions and mocks.
+- **Database Mocking:** [go-sqlmock](https://github.com/DATA-DOG/go-sqlmock) for repository-level unit tests.
+- **Static Analysis:** [golangci-lint](https://golangci-lint.run/) with `gosec` and `govulncheck` for security scanning.

conductor/tracks.md

@@ -0,0 +1,8 @@
+# Project Tracks
+
+This file tracks all major tracks for the project. Each track has its own detailed plan in its respective folder.
+
+---
+
+- [ ] **Track: Implement Authenticated Encryption with Associated Data (AEAD) Context in Transit Engine**
+  *Link: [./tracks/implement_aead_context_20260305/](./tracks/implement_aead_context_20260305/)*

conductor/tracks/implement_aead_context_20260305/index.md

@@ -0,0 +1,5 @@
+# Track implement_aead_context_20260305 Context
+
+- [Specification](./spec.md)
+- [Implementation Plan](./plan.md)
+- [Metadata](./metadata.json)

conductor/tracks/implement_aead_context_20260305/metadata.json

@@ -0,0 +1,8 @@
+{
+  "track_id": "implement_aead_context_20260305",
+  "type": "feature",
+  "status": "new",
+  "created_at": "2026-03-05T14:00:00Z",
+  "updated_at": "2026-03-05T14:00:00Z",
+  "description": "Implement Authenticated Encryption with Associated Data (AEAD) Context in Transit Engine to prevent ciphertext substitution attacks."
+}

conductor/tracks/implement_aead_context_20260305/plan.md

@@ -0,0 +1,30 @@
+# Implementation Plan: AEAD Context in Transit Engine
+
+## Phase 1: Use Case Layer Update
+- [ ] Task: Update `TransitKeyUseCase` interface and implementation signatures
+    - [ ] Update `internal/transit/usecase/interface.go` to add `context []byte` to `Encrypt` and `Decrypt`
+    - [ ] Update `internal/transit/usecase/transit_key_usecase.go` signatures to match interface
+    - [ ] Update existing callers in tests to pass `nil` for context
+- [ ] Task: Implement AEAD context support in `TransitKeyUseCase` (TDD)
+    - [ ] Write failing unit tests in `internal/transit/usecase/transit_key_usecase_test.go` for encryption/decryption with context
+    - [ ] Implement logic in `internal/transit/usecase/transit_key_usecase.go` to pass context as `aad` to cipher
+    - [ ] Verify tests pass and coverage is >80%
+- [ ] Task: Conductor - User Manual Verification 'Phase 1: Use Case Layer' (Protocol in workflow.md)
+
+## Phase 2: HTTP Layer Update
+- [ ] Task: Update `EncryptRequest` and `DecryptRequest` DTOs
+    - [ ] Update `internal/transit/http/dto/request.go` to add optional `context` (base64)
+- [ ] Task: Implement AEAD context support in `CryptoHandler` (TDD)
+    - [ ] Write failing unit tests in `internal/transit/http/crypto_handler_test.go` for API calls with context
+    - [ ] Update `internal/transit/http/crypto_handler.go` to decode base64 context and pass to use case
+    - [ ] Verify tests pass and coverage is >80%
+- [ ] Task: Conductor - User Manual Verification 'Phase 2: HTTP Layer' (Protocol in workflow.md)
+
+## Phase 3: Integration and Documentation
+- [ ] Task: Verify end-to-end flow with integration tests
+    - [ ] Update `test/integration/transit_flow_test.go` to include AEAD context scenarios
+    - [ ] Run all transit integration tests and verify they pass
+- [ ] Task: Update Documentation
+    - [ ] Update OpenAPI spec in `docs/openapi.yaml`
+    - [ ] Update transit engine guide in `docs/engines/transit.md` with AEAD context examples
+- [ ] Task: Conductor - User Manual Verification 'Phase 3: Integration and Documentation' (Protocol in workflow.md)

conductor/tracks/implement_aead_context_20260305/spec.md

@@ -0,0 +1,22 @@
+# Specification: Implement AEAD Context in Transit Engine
+
+## Overview
+Authenticated Encryption with Associated Data (AEAD) allows providing additional, non-encrypted data (context) that is cryptographically bound to the ciphertext. This prevents ciphertext substitution attacks where a valid ciphertext for one context is used in another.
+
+## Requirements
+- Update `TransitKeyUseCase.Encrypt` and `Decrypt` to accept an optional `context` parameter (as `[]byte`).
+- Update `TransitKeyUseCase` implementation to pass this `context` as `aad` to the `AEAD` cipher.
+- Update `transit.http` handlers to accept an optional `context` field (base64-encoded) in the request body.
+- Maintain backward compatibility: if `context` is not provided, it should behave as before (equivalent to empty/nil `aad`).
+
+## Affected Components
+- `internal/transit/usecase/interface.go`: Update `TransitKeyUseCase` interface.
+- `internal/transit/usecase/transit_key_usecase.go`: Update `Encrypt` and `Decrypt` methods.
+- `internal/transit/http/dto/request.go`: Add `Context` field to `EncryptRequest` and `DecryptRequest`.
+- `internal/transit/http/crypto_handler.go`: Pass `context` from request to use case.
+- `internal/transit/usecase/transit_key_usecase_test.go`: Add tests for AEAD context.
+- `internal/transit/http/crypto_handler_test.go`: Add tests for AEAD context in API.
+
+## Design Decisions
+- **Context Encoding:** In the API, the `context` will be base64-encoded, consistent with `plaintext`.
+- **Naming:** The API field will be named `context` to be more user-friendly, although it maps to `aad` in cryptographic terms.