Update RFC based on codebase analysis

- Remove logger, healthcheck from Tier 1 (have ToolHive coupling)
- Add oauth, permissions to Tier 1 (verified zero coupling)
- Add Tier 2 with refactoring requirements (logger needs Viper decoupling)
- Add "Not Recommended" section for deeply coupled packages
- Remove verbose API signatures
- Remove Alternatives Considered section

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: JAORMX

rfcs/THV-0032-toolhive-core-shared-library.md

@@ -195,16 +195,16 @@ Based on analysis of the `toolhive` codebase:
 
 #### Tier 1: Immediate Graduation Candidates
 
-These packages meet all graduation criteria and should be included in the initial `toolhive-core` release:
+These packages meet all graduation criteria (zero ToolHive-specific coupling, well-tested, minimal dependencies) and should be included in the initial `toolhive-core` release:
 
 | Package | Current Location | Stability | Rationale |
 |---------|------------------|-----------|-----------|
-| **logger** | `pkg/logger/` | Stable (v1) | 185 imports, foundational utility |
-| **errors** | `pkg/errors/` | Stable (v1) | HTTP-aware error handling, minimal deps |
-| **validation** | `pkg/validation/` | Stable (v1) | Security-focused input validation |
-| **healthcheck** | `pkg/healthcheck/` | Stable (v1) | Standardized health responses |
-| **versions** | `pkg/versions/` | Stable (v1) | Build metadata, User-Agent |
-| **env** | `pkg/env/` | Stable (v1) | Testable environment access |
+| **errors** | `pkg/errors/` | Stable (v1) | HTTP-aware error handling, zero deps, 10mo stable |
+| **oauth** | `pkg/oauth/` | Stable (v1) | RFC-compliant OAuth/OIDC types, fosite dep only |
+| **env** | `pkg/env/` | Stable (v1) | Testable environment access, zero deps |
+| **permissions** | `pkg/permissions/` | Stable (v1) | Container permission profiles, stdlib-only, security validations |
+| **validation** | `pkg/validation/` | Stable (v1) | RFC 7230 HTTP header validation, security-focused |
+| **versions** | `pkg/versions/` | Stable (v1) | Build metadata, User-Agent generation |
 
 **Proposed `toolhive-core` structure:**
 
@@ -218,49 +218,62 @@ toolhive-core/
 │   ├── errors.go        # CodedError, WithCode, Code()
 │   ├── errors_test.go
 │   └── doc.go
-├── logger/
-│   ├── logger.go        # Initialize, logging functions
-│   ├── logger_test.go
+├── oauth/
+│   ├── oauth.go         # AuthorizationServerMetadata, OIDCDiscoveryDocument
+│   ├── oauth_test.go
+│   └── doc.go
+├── env/
+│   ├── env.go           # Reader interface, OSReader
+│   ├── env_test.go
+│   └── doc.go
+├── permissions/
+│   ├── profile.go       # Profile, NetworkPermissions, MountDeclaration
+│   ├── profile_test.go
 │   └── doc.go
 ├── validation/
 │   ├── validation.go    # HTTP header, URI, group name validators
 │   ├── validation_test.go
 │   └── doc.go
-├── healthcheck/
-│   ├── healthcheck.go   # HealthResponse, MCPStatus types
-│   ├── healthcheck_test.go
-│   └── doc.go
-├── versions/
-│   ├── version.go       # VersionInfo, GetUserAgent
-│   ├── version_test.go
-│   └── doc.go
-└── env/
-    ├── env.go           # Reader interface, OSReader
-    ├── env_test.go
+└── versions/
+    ├── version.go       # VersionInfo, GetUserAgent
+    ├── version_test.go
     └── doc.go
 ```
 
-#### Tier 2: Secondary Candidates (Future Releases)
+#### Tier 2: Minor Refactoring Required
 
-These packages are stable but require additional review before graduation:
+These packages have solid implementations but need minor changes to remove ToolHive-specific coupling:
 
-| Package | Current Location | Status | Graduation Considerations |
-|---------|------------------|--------|---------------------------|
-| **secrets** | `pkg/secrets/` | Beta | Multiple providers (1Password, keyring), needs interface review |
-| **auth/oauth** | `pkg/auth/oauth/` | Beta | PKCE support, token exchange - needs decoupling from transport |
-| **transport/types** | `pkg/transport/types/` | Beta | Middleware abstraction, widely used |
-| **mcp** | `pkg/mcp/` | Beta | MCP primitives, protocol-specific |
+| Package | Current Location | Status | Required Changes |
+|---------|------------------|--------|------------------|
+| **healthcheck** | `pkg/healthcheck/` | Beta | Remove unused logger import |
+| **logger** | `pkg/logger/` | Beta | Remove `viper.GetBool("debug")` coupling; accept config via parameters |
+| **auth/tokenexchange** | `pkg/auth/tokenexchange/` | Beta | Split core RFC 8693 logic from ToolHive middleware |
+| **networking** | `pkg/networking/` | Beta | Replace ToolHive logger with slog or interface |
+| **lockfile** | `pkg/lockfile/` | Beta | Accept logger interface instead of importing pkg/logger |
 
-#### Tier 3: Future Candidates (Requires Evolution)
+#### Tier 3: Partial Extraction or Future Work
 
-These packages need further stabilization before graduation consideration:
+These packages have useful components but require significant refactoring or are too coupled:
 
 | Package | Current Location | Status | Notes |
 |---------|------------------|--------|-------|
-| **authz** | `pkg/authz/` | Alpha | Cedar policy support still evolving |
-| **authserver** | `pkg/authserver/` | Beta | Complex, may warrant own module |
-| **vmcp** | `pkg/vmcp/` | Stable | Domain-specific, may stay in toolhive |
-| **config** | `pkg/config/` | Beta | Build-specific logic, needs refactoring |
+| **labels** | `pkg/labels/` | Beta | Extract K8s validation funcs only; keep ToolHive constants |
+| **secrets** | `pkg/secrets/` | Beta | Multiple providers, needs interface review |
+| **transport/types** | `pkg/transport/types/` | Beta | Middleware abstraction, widely used but coupled |
+| **mcp** | `pkg/mcp/` | Beta | MCP primitives, protocol-specific |
+
+#### Not Recommended for Extraction
+
+These packages are too coupled to ToolHive internals:
+
+| Package | Reason |
+|---------|--------|
+| **auth** (heavy pieces) | Product-level wiring: token.go, oauth/*, remote/*, secrets/* |
+| **runner**, **workloads** | Deep orchestration coupling, RunConfig migrations |
+| **config** | Viper global state, ToolHive-specific env vars |
+| **ignore** | Hardcoded `.thvignore`, ToolHive paths |
+| **process** | Hardcoded paths, imports pkg/container/runtime |
 
 ### Detailed Design
 
@@ -283,103 +296,18 @@ github.com/stacklok/toolhive-core
 └── [packages]/
 ```
 
-#### API Design: Logger Package
-
-```go
-// Package logger provides structured logging for ToolHive services.
-//
-// Stability: Stable (v1)
-// Since: v0.1.0
-package logger
-
-import (
-    "github.com/go-logr/logr"
-)
-
-// Logger is the interface for structured logging.
-type Logger interface {
-    logr.Logger
-}
-
-// Config holds logger configuration.
-type Config struct {
-    // Level is the minimum log level (debug, info, warn, error).
-    Level string
-    // Format is the output format (json, text).
-    Format string
-    // Development enables development-friendly output.
-    Development bool
-}
-
-// Initialize creates and configures the global logger.
-// This should be called once at application startup.
-func Initialize(cfg Config) error
-
-// Get returns the configured logger instance.
-// If Initialize has not been called, returns a no-op logger.
-func Get() Logger
-
-// WithName returns a logger with the specified name added.
-func WithName(name string) Logger
-
-// WithValues returns a logger with additional key-value pairs.
-func WithValues(keysAndValues ...interface{}) Logger
-```
-
-#### API Design: Errors Package
-
-```go
-// Package errors provides HTTP-aware error handling.
-//
-// Stability: Stable (v1)
-// Since: v0.1.0
-package errors
+#### Package Descriptions
 
-// CodedError wraps an error with an HTTP status code.
-type CodedError struct {
-    err  error
-    code int
-}
+| Package | Purpose | Key Exports |
+|---------|---------|-------------|
+| **errors** | HTTP-aware error wrapping | `CodedError`, `WithCode()`, `Code()` |
+| **oauth** | RFC 8414/OIDC discovery types | `AuthorizationServerMetadata`, `OIDCDiscoveryDocument`, redirect validation |
+| **env** | Testable environment access | `Reader` interface, `OSReader` |
+| **permissions** | Container security profiles | `Profile`, `NetworkPermissions`, `MountDeclaration`, security validations |
+| **validation** | RFC 7230 HTTP validation | Header name/value validators, group name, resource URI |
+| **versions** | Build metadata | `VersionInfo`, `GetUserAgent()` |
 
-// WithCode wraps an error with an HTTP status code.
-func WithCode(err error, code int) *CodedError
-
-// Code extracts the HTTP status code from an error.
-// Returns 500 if the error does not have a code.
-func Code(err error) int
-
-// Error implements the error interface.
-func (e *CodedError) Error() string
-
-// Unwrap returns the underlying error.
-func (e *CodedError) Unwrap() error
-```
-
-#### API Design: Validation Package
-
-```go
-// Package validation provides security-focused input validation.
-//
-// Stability: Stable (v1)
-// Since: v0.1.0
-package validation
-
-// ValidateHTTPHeaderName validates an HTTP header name per RFC 7230.
-func ValidateHTTPHeaderName(name string) error
-
-// ValidateHTTPHeaderValue validates an HTTP header value per RFC 7230.
-func ValidateHTTPHeaderValue(value string) error
-
-// ValidateGroupName validates a ToolHive group name.
-// Group names must be lowercase, cannot contain consecutive spaces,
-// and cannot contain null bytes.
-func ValidateGroupName(name string) error
-
-// ValidateResourceURI validates a resource URI per RFC 8707.
-func ValidateResourceURI(uri string) error
-```
-
-#### Configuration Changes
+#### Migration
 
 Consuming projects update their `go.mod`:
 
@@ -449,36 +377,6 @@ import "github.com/stacklok/toolhive-core/logger"
 | Credential exposure | Redaction functions, sensitive field markers |
 | Breaking changes | Semver, deprecation warnings, migration guides |
 
-## Alternatives Considered
-
-### Alternative 1: Go Workspace / Monorepo
-
-- **Description**: Use Go workspaces to share packages within a monorepo
-- **Pros**: Single repo, easier refactoring, atomic changes
-- **Cons**: Couples release cycles, complicates CI/CD, doesn't help external consumers
-- **Why not chosen**: ToolHive ecosystem already uses multiple repos; changing to monorepo is disruptive
-
-### Alternative 2: Git Submodules
-
-- **Description**: Share packages via git submodules
-- **Pros**: Direct source access, version pinning
-- **Cons**: Complex workflow, poor Go tooling support, merge conflicts
-- **Why not chosen**: Go modules provide better dependency management
-
-### Alternative 3: Internal Packages with Replace Directives
-
-- **Description**: Keep packages internal, use `replace` directives for sharing
-- **Pros**: No new repo, immediate availability
-- **Cons**: No stability guarantees, manual coordination, breaks `go get`
-- **Why not chosen**: Doesn't solve the core problems of stability and discoverability
-
-### Alternative 4: Copy-Paste with Attribution
-
-- **Description**: Manually copy code between projects
-- **Pros**: Full control, no external dependencies
-- **Cons**: Divergence over time, duplicated bug fixes, inconsistency
-- **Why not chosen**: Already causing problems; doesn't scale
-
 ## Compatibility
 
 ### Backward Compatibility
@@ -542,7 +440,7 @@ import "github.com/stacklok/toolhive-core/logger"
 
 ### Integration Tests
 
-- Cross-package integration tests (e.g., logger + errors)
+- Cross-package integration tests (e.g., validation + errors)
 - Import cycle detection in CI
 
 ### Compatibility Tests
@@ -552,7 +450,7 @@ import "github.com/stacklok/toolhive-core/logger"
 
 ### Performance Tests
 
-- Benchmark logger throughput
+- Benchmark validation functions
 - Memory allocation tests for hot paths
 
 ### Security Tests
@@ -572,8 +470,8 @@ import "github.com/stacklok/toolhive-core/logger"
 ## Open Questions
 
 1. **Release cadence**: Monthly minor releases, or release when ready?
-2. **Tier 2 timeline**: When should we start evaluating secrets/auth for graduation?
-3. **Logger choice**: Should toolhive-core use zap (current toolhive approach) or slog (stdlib, used by registry-server)? Or provide adapters for both?
+2. **Tier 2 timeline**: When should we start refactoring logger/healthcheck/tokenexchange for graduation?
+3. **Logger refactoring approach**: When decoupling logger from Viper, should we use zap with config injection, switch to slog, or provide an interface that supports both?
 
 ## References