git.stella-ops.org/docs/implplan/CLI_AUTH_MIGRATION_PLAN.md

CLI Auth.Client Migration Plan

Created: 2025-12-04 Status: COMPLETED Completed: 2025-12-04

Problem Statement

The CLI services used an older IStellaOpsTokenClient API that no longer exists. This document outlines the migration strategy and tracks completion.

Summary of Changes

Files Created

• src/Cli/StellaOps.Cli/Extensions/StellaOpsTokenClientExtensions.cs - Compatibility shim methods

Files Modified

Service Files (Auth.Client API Migration)

1. OrchestratorClient.cs - Updated scope references
2. VexObservationsClient.cs - Updated to use GetAccessTokenAsync(string) extension, removed IsSuccess check
3. SbomerClient.cs - Fixed GetTokenAsync to use AccessToken property
4. ExceptionClient.cs - Updated token acquisition pattern
5. NotifyClient.cs - Updated token acquisition pattern
6. ObservabilityClient.cs - Updated token acquisition pattern
7. PackClient.cs - Updated token acquisition pattern
8. SbomClient.cs - Updated token acquisition pattern

Command Handlers (Signature Fixes)

9. CommandHandlers.cs:

   • Fixed CreateLogger<CommandHandlers>() static type error (line 80)
   • Fixed PolicyDsl diagnostic rendering (removed Line/Column/Suggestion, added Path)

10. CommandFactory.cs:

    • Fixed HandleExceptionsListAsync argument order and count
    • Fixed HandleExceptionsCreateAsync argument order, expiration type conversion
    • Fixed HandleExceptionsPromoteAsync argument order
    • Fixed HandleExceptionsExportAsync argument order and count
    • Fixed HandleExceptionsImportAsync argument order

Model Updates

11. PolicyWorkspaceModels.cs - Updated PolicyDiagnostic class (replaced Line/Column/Span/Suggestion with Path)

Old API (Removed)

// Methods that no longer exist
Task<StellaOpsTokenResult> GetTokenAsync(StellaOpsTokenRequest request, CancellationToken ct);
Task<StellaOpsTokenResult> GetAccessTokenAsync(string[] scopes, CancellationToken ct);

// Types that no longer exist
class StellaOpsTokenRequest { string[] Scopes; }
static class StellaOpsScope { const string OrchRead = "orch:read"; }

// Properties removed from StellaOpsTokenResult
bool IsSuccess;

New API (Current)

interface IStellaOpsTokenClient
{
    Task<StellaOpsTokenResult> RequestClientCredentialsTokenAsync(
        string? scope = null,
        IReadOnlyDictionary<string, string>? additionalParameters = null,
        CancellationToken cancellationToken = default);

    ValueTask<StellaOpsTokenCacheEntry?> GetCachedTokenAsync(string key, CancellationToken ct);
    ValueTask CacheTokenAsync(string key, StellaOpsTokenCacheEntry entry, CancellationToken ct);
}

// StellaOpsTokenResult record properties:
// - AccessToken (string)
// - TokenType (string)
// - ExpiresAtUtc (DateTimeOffset)
// - Scopes (IReadOnlyList<string>)

Migration Approach

Extension Methods Created

public static class StellaOpsTokenClientExtensions
{
    // Single scope version
    public static async Task<StellaOpsTokenResult> GetAccessTokenAsync(
        this IStellaOpsTokenClient client,
        string scope,
        CancellationToken cancellationToken = default);

    // Multi-scope version
    public static async Task<StellaOpsTokenResult> GetAccessTokenAsync(
        this IStellaOpsTokenClient client,
        IEnumerable<string> scopes,
        CancellationToken cancellationToken = default);

    // Cached token version
    public static async Task<StellaOpsTokenCacheEntry> GetCachedAccessTokenAsync(
        this IStellaOpsTokenClient client,
        string scope,
        CancellationToken cancellationToken = default);

    // Parameterless version
    public static async Task<StellaOpsTokenResult> GetTokenAsync(
        this IStellaOpsTokenClient client,
        CancellationToken cancellationToken = default);
}

Scope Constants

Used StellaOpsScopes from StellaOps.Auth.Abstractions namespace (e.g., StellaOpsScopes.OrchRead, StellaOpsScopes.VexRead).

Build Results

Build succeeded with 0 errors, 6 warnings:

• 3x CS8629 nullable warnings in OutputRenderer.cs
• 1x CS0618 obsolete warning (VulnRead → VulnView)
• 1x SYSLIB0057 obsolete X509Certificate2 constructor
• 1x CS0219 unused variable warning

Implementation Checklist

• Create StellaOpsTokenClientExtensions.cs
• Verify StellaOpsScopes exists in Auth.Abstractions
• Update OrchestratorClient.cs
• Update VexObservationsClient.cs
• Update SbomerClient.cs
• Update ExceptionClient.cs
• Update NotifyClient.cs
• Update ObservabilityClient.cs
• Update PackClient.cs
• Update SbomClient.cs
• Fix CommandHandlers static type error
• Fix PolicyDsl API changes (PolicyIssue properties)
• Fix HandleExceptionsListAsync signature
• Fix HandleExceptionsCreateAsync signature
• Fix HandleExceptionsPromoteAsync signature
• Fix HandleExceptionsExportAsync signature
• Fix HandleExceptionsImportAsync signature
• Update PolicyDiagnostic model
• Build verification passed