1  # Gemini Feedback: A CTO's Playbook for the Auths v0.1.0 Launch
  2  
  3  **To:** Auths Leadership
  4  **From:** Gemini (CTO / DX Lead Persona)
  5  **Date:** 2026-03-06
  6  **Subject:** An Actionable Roadmap for the Auths v0.1.0 Launch
  7  
  8  ## 1. Executive Summary & Restructured Plan
  9  
 10  Our goal for the v0.1.0 launch is to establish `auths` as the most polished, trustworthy, and developer-obsessed identity platform on the market. Our current codebase is functionally powerful but lacks the stability and seamless developer experience (DX) required for a public launch.
 11  
 12  This document has been restructured from a simple list of issues into a **chronological, dependency-aware roadmap**. It is organized into four distinct phases of work. Each phase builds upon the last, ensuring that we solidify our foundation before building upon it. This is the critical path to a successful v0.1.0 launch.
 13  
 14  ---
 15  
 16  ## Phase 1: Solidify the Core (Rust SDK & Verifier)
 17  
 18  **Objective:** Create a stable, predictable, and secure foundation. All work in this phase is a prerequisite for subsequent phases.
 19  
 20  ### 1.1. Implement Native Commit Verification
 21  *   **Why:** The current Python-based commit verification shells out to `ssh-keygen`, which is slow, brittle, and not portable. This is our biggest reliability risk.
 22  *   **The Problem:**
 23      ```python
 24      # in packages/auths-python/python/auths/git.py
 25      proc = subprocess.run(
 26          ["ssh-keygen", "-Y", "verify", ...], ...
 27      )
 28      ```
 29  *   **Action:** Implement the entire commit signature verification logic in pure Rust within the `crates/auths-verifier` crate. This single change will dramatically improve performance and reliability for a key feature.
 30  
 31  ### 1.2. Refactor SDK Configuration for Compile-Time Safety
 32  *   **Why:** The SDK must be impossible to misconfigure. We can prevent entire classes of runtime errors at compile time.
 33  *   **The Problem:** The `AuthsContextBuilder` in `crates/auths-sdk/src/context.rs` uses a `NoopPassphraseProvider` that causes a runtime error if signing is attempted without a real provider.
 34      ```rust
 35      // This defers a configuration error to a runtime crash.
 36      passphrase_provider: self
 37          .passphrase_provider
 38          .unwrap_or_else(|| Arc::new(NoopPassphraseProvider)),
 39      ```
 40  *   **Action:** Eliminate the `Noop` providers. Use the typestate pattern to create distinct `AuthsContext` types, such as `AuthsContext<Unsigned>` and `AuthsContext<SigningReady>`. Workflows that require signing must take the `SigningReady` context as an argument, making it a compile-time error to call them without the correct configuration.
 41  
 42  ### 1.3. Eradicate Panics from the Public API
 43  *   **Why:** A library that can `panic` is a library that cannot be trusted in production. It is the most hostile behavior an SDK can exhibit.
 44  *   **The Problem:** The codebase is littered with `.unwrap()` and `.expect()` calls that can crash the host application.
 45      ```rust
 46      // in crates/auths-sdk/src/workflows/mcp.rs:80
 47      .expect("failed to build HTTP client") // Will crash if host TLS is misconfigured.
 48      ```
 49  *   **Action:** Audit and refactor every `.unwrap()` and `.expect()` in the `auths-sdk` crate's public-facing workflows. Replace them with proper, descriptive error variants (e.g., `McpAuthError::HttpClientBuildFailed`).
 50  
 51  ### 1.4. Unify and Seal the Public API Surface
 52  *   **Why:** We are making a promise of stability with `v0.1.0`. The API we launch with is the API we must support.
 53  *   **Action:**
 54      1.  **Unify:** Refactor the `initialize_developer`, `initialize_ci`, and `initialize_agent` functions in `crates/auths-sdk/src/setup.rs` into private helpers. The single public entry point must be `pub fn initialize(config: IdentityConfig, ...)`.
 55      2.  **Seal:** Run `cargo public-api` to generate a definitive list of our public API. Anything we are not ready to commit to for the long term must be hidden (`pub(crate)` or `#[doc(hidden)]`).
 56  
 57  ---
 58  
 59  ## Phase 2: Refine the Developer Experience (Python FFI & SDK)
 60  
 61  **Objective:** Create an idiomatic, robust, and effortless experience for Python developers. This phase depends heavily on the stability provided by Phase 1.
 62  
 63  ### 2.1. Implement Robust FFI Error Handling
 64  *   **Dependency:** Phase 1.3 (Eradicate Panics). The Rust layer must return errors, not panic.
 65  *   **Why:** The current error handling is based on string-matching messages from Rust, which is extremely fragile.
 66  *   **The Problem:**
 67      ```python
 68      # in packages/auths-python/python/auths/_client.py
 69      def _map_verify_error(exc: Exception) -> Exception:
 70          msg = str(exc)
 71          if "public key" in msg.lower(): # This will break silently.
 72              return CryptoError(msg, code="invalid_key")
 73      ```
 74  *   **Action:** Modify the Rust FFI layer to return a stable, machine-readable error code (a C-style enum or integer). The Python `_map_verify_error` function must be rewritten to dispatch on this reliable code.
 75  This MUST be consistent across all such files
 76  
 77  ### 2.2. Consume Native Commit Verification
 78  *   **Dependency:** Phase 1.1 (Native Commit Verification).
 79  *   **Why:** To eliminate the slow and brittle `subprocess` calls.
 80  *   **Action:** Remove the `verify_commit_range` implementation from `packages/auths-python/python/auths/git.py` and replace its body with a single call to the new native Rust function (exposed via the `auths._native` module).
 81  
 82  ### 2.3. Adopt Pythonic Types and Conventions
 83  *   **Why:** The Python SDK must respect the conventions of its ecosystem to feel natural to developers.
 84  *   **The Problem:** The API uses strings for timestamps and may not return idiomatic `dataclass` instances.
 85      ```python
 86      # in packages/auths-python/python/auths/_client.py
 87      def verify(self, ..., at: str | None = None) -> VerificationResult:
 88          # ...
 89      ```
 90  *   **Action:**
 91      1.  Modify methods like `verify` to accept `datetime.datetime` objects. The implementation can then convert them to Unix timestamps (integers) to pass to the Rust layer.
 92      2.  Audit all functions that return data from Rust. Ensure they return proper `@dataclass` instances, not raw dictionaries or tuples.
 93      3.  Ensure all public methods and parameters follow `snake_case` conventions.
 94  
 95  ---
 96  
 97  ## Phase 3: Polish the Public Integrations (JS Ecosystem)
 98  
 99  **Objective:** Ensure our integrations are seamless, easy to use, and inspire confidence. This can run in parallel with Phase 2.
100  
101  ### 3.1. Manage External Dependencies for Independent Repos
102  *   **Correction & Context:** My previous analysis incorrectly assumed a monorepo structure. Understanding these are independent repositories makes the dependency management even more critical. The current build scripts have hardcoded relative paths that will fail in any standard CI/CD environment or for any external contributor.
103  *   **Action (`auths-verify-widget`):** The `build:wasm` script in `package.json` (`"cd ../auths/crates/auths-verifier && wasm-pack build ..."`) is a critical flaw. It relies on a local file structure that will not exist in a clean checkout. The WASM verifier *must* be treated as a versioned, third-party dependency.
104      1.  The `auths/crates/auths-verifier` project must be configured to compile to WASM and be published to `npm` as a standalone package (e.g., `@auths/verifier-wasm`).
105      2.  The `auths-verify-widget` must remove the `build:wasm` script and add `@auths/verifier-wasm` as a standard `devDependency` in its `package.json`.
106      This ensures the widget can be built, tested, and released independently.
107  *   **Action (`auths-verify-github-action`):** The action correctly treats the `auths` CLI as an external dependency by downloading it at runtime. However, for a v0.1.0 launch, this introduces too much variability.
108      1.  For the v0.1.0 release, the action *must bundle a specific, known-good version* of the `auths` native binary for Linux x64 (the standard GitHub runner environment). This guarantees performance and reliability.
109      2.  This can be accomplished by adding a script to the `auths-verify-github-action` repo that downloads a specific versioned release of the `auths` CLI from its GitHub Releases page and places it in the `dist` directory as part of the build process.
110  
111  ### 3.2. Improve DX for Integrations
112  *   **Why:** These integrations are the "front door" to our product for many developers. The experience must be flawless.
113  *   **Action (`auths-verify-widget`):**
114      1.  **Clarify Variants:** The `README.md` must clearly explain the "full" vs. "slim" builds.
115      2.  **No-Build Option:** Create a UMD bundle and publish it to a CDN (`unpkg`, `jsdelivr`) so the widget can be used with a simple `<script>` tag.
116  *   **Action (`auths-verify-github-action`):**
117      1.  **Better Failure UX:** On verification failure, post a detailed PR comment explaining *which* commits failed and *how* to fix it. This turns failure into an educational moment.
118      2.  **Streamline `action.yml`:** Default the `github-token` to `${{ github.token }}` and add at least three copy-pasteable examples for common use cases to the `README.md`.
119  
120  ---
121  
122  ## Phase 4: Release Engineering & Documentation
123  
124  **Objective:** Ensure the product is easy to install and use. This is the final step before launch.
125  
126  ### 4.1. Guarantee Effortless Installation
127  *   **Dependency:** Phase 1, 2, and 3 must be complete.
128  *   **Why:** `pip install auths` and `npm install @auths-dev/verify` must *just work*. A difficult installation is our single biggest adoption blocker.
129  *   **Action (`auths-python`):** Ensure the CI/CD pipeline uses `maturin build --release` to build and publish binary wheels for all major platforms (manylinux, macOS x86_64/arm64, Windows amd64) to PyPI.
130  *   **Action (JS packages):** Ensure the CI/CD pipeline correctly publishes all public `npm` packages (`@auths/verifier-wasm`, `@auths-dev/verify`).
131  
132  ### 4.2. Write the "First Five Minutes" Guide
133  *   **Why:** A developer's first impression is formed in the first five minutes. We need a guide that makes them feel successful immediately.
134  *   **Action:** Create a "Getting Started" guide that takes a developer from zero to a successful signature verification in under 3 minutes. This guide should use the Python SDK as its primary example.
135  
136  ## Final Go/No-Go Checklist
137  
138  We are ready to launch v0.1.0 **if and only if** we can answer "Yes" to all of the following:
139  - [ ] Is all work in **Phase 1** complete and verified?
140  - [ ] Is all work in **Phase 2** complete and verified?
141  - [ ] Is all work in **Phase 3** complete and verified?
142  - [ ] Does `pip install auths` work on clean installs of macOS, Linux, and Windows without requiring a Rust toolchain?
143  - [ ] Do we have a "Getting Started" guide that takes a developer from zero to a successful signature verification in under 3 minutes?