git.stella-ops.org/src/Signer/__Libraries/StellaOps.Signer.KeyManagement/ITrustAnchorManager.cs

using System;
using System.Collections.Generic;
using System.Threading;
using System.Threading.Tasks;

namespace StellaOps.Signer.KeyManagement;

/// <summary>
/// Manages trust anchors and their key bindings.
/// Implements advisory §8.3 trust anchor structure.
/// </summary>
public interface ITrustAnchorManager
{
    /// <summary>
    /// Get a trust anchor by ID.
    /// </summary>
    /// <param name="anchorId">The anchor ID.</param>
    /// <param name="ct">Cancellation token.</param>
    /// <returns>The trust anchor or null.</returns>
    Task<TrustAnchorInfo?> GetAnchorAsync(
        Guid anchorId,
        CancellationToken ct = default);

    /// <summary>
    /// Find a trust anchor matching a PURL.
    /// Uses pattern matching (e.g., pkg:npm/* matches pkg:npm/lodash@4.17.21).
    /// </summary>
    /// <param name="purl">The PURL to match.</param>
    /// <param name="ct">Cancellation token.</param>
    /// <returns>The matching trust anchor or null.</returns>
    Task<TrustAnchorInfo?> FindAnchorForPurlAsync(
        string purl,
        CancellationToken ct = default);

    /// <summary>
    /// Create a new trust anchor.
    /// </summary>
    /// <param name="request">The creation request.</param>
    /// <param name="ct">Cancellation token.</param>
    /// <returns>The created trust anchor.</returns>
    Task<TrustAnchorInfo> CreateAnchorAsync(
        CreateTrustAnchorRequest request,
        CancellationToken ct = default);

    /// <summary>
    /// Update a trust anchor.
    /// </summary>
    /// <param name="anchorId">The anchor ID.</param>
    /// <param name="request">The update request.</param>
    /// <param name="ct">Cancellation token.</param>
    /// <returns>The updated trust anchor.</returns>
    Task<TrustAnchorInfo> UpdateAnchorAsync(
        Guid anchorId,
        UpdateTrustAnchorRequest request,
        CancellationToken ct = default);

    /// <summary>
    /// Deactivate a trust anchor (soft delete).
    /// </summary>
    /// <param name="anchorId">The anchor ID.</param>
    /// <param name="ct">Cancellation token.</param>
    Task DeactivateAnchorAsync(
        Guid anchorId,
        CancellationToken ct = default);

    /// <summary>
    /// Verify a signature against a trust anchor's allowed keys.
    /// Supports temporal verification for historical proofs.
    /// </summary>
    /// <param name="anchorId">The anchor ID.</param>
    /// <param name="keyId">The key ID that signed.</param>
    /// <param name="signedAt">When the signature was created.</param>
    /// <param name="predicateType">The predicate type (if restricted).</param>
    /// <param name="ct">Cancellation token.</param>
    /// <returns>The verification result.</returns>
    Task<TrustVerificationResult> VerifySignatureAuthorizationAsync(
        Guid anchorId,
        string keyId,
        DateTimeOffset signedAt,
        string? predicateType = null,
        CancellationToken ct = default);

    /// <summary>
    /// Get all active trust anchors.
    /// </summary>
    /// <param name="ct">Cancellation token.</param>
    /// <returns>List of active anchors.</returns>
    Task<IReadOnlyList<TrustAnchorInfo>> GetActiveAnchorsAsync(
        CancellationToken ct = default);
}

/// <summary>
/// Full trust anchor information including key history.
/// </summary>
public sealed record TrustAnchorInfo
{
    /// <summary>
    /// The anchor ID.
    /// </summary>
    public required Guid AnchorId { get; init; }

    /// <summary>
    /// PURL glob pattern.
    /// </summary>
    public required string PurlPattern { get; init; }

    /// <summary>
    /// Currently allowed key IDs.
    /// </summary>
    public required IReadOnlyList<string> AllowedKeyIds { get; init; }

    /// <summary>
    /// Allowed predicate types (null = all).
    /// </summary>
    public IReadOnlyList<string>? AllowedPredicateTypes { get; init; }

    /// <summary>
    /// Policy reference.
    /// </summary>
    public string? PolicyRef { get; init; }

    /// <summary>
    /// Policy version.
    /// </summary>
    public string? PolicyVersion { get; init; }

    /// <summary>
    /// Revoked key IDs (still valid for historical proofs).
    /// </summary>
    public required IReadOnlyList<string> RevokedKeyIds { get; init; }

    /// <summary>
    /// Full key history.
    /// </summary>
    public required IReadOnlyList<KeyHistoryEntry> KeyHistory { get; init; }

    /// <summary>
    /// Whether the anchor is active.
    /// </summary>
    public bool IsActive { get; init; } = true;

    /// <summary>
    /// When the anchor was created.
    /// </summary>
    public required DateTimeOffset CreatedAt { get; init; }

    /// <summary>
    /// When the anchor was last updated.
    /// </summary>
    public required DateTimeOffset UpdatedAt { get; init; }
}

/// <summary>
/// Request to create a trust anchor.
/// </summary>
public sealed record CreateTrustAnchorRequest
{
    /// <summary>
    /// PURL glob pattern.
    /// </summary>
    public required string PurlPattern { get; init; }

    /// <summary>
    /// Initial allowed key IDs.
    /// </summary>
    public required IReadOnlyList<string> AllowedKeyIds { get; init; }

    /// <summary>
    /// Allowed predicate types (null = all).
    /// </summary>
    public IReadOnlyList<string>? AllowedPredicateTypes { get; init; }

    /// <summary>
    /// Policy reference.
    /// </summary>
    public string? PolicyRef { get; init; }

    /// <summary>
    /// Policy version.
    /// </summary>
    public string? PolicyVersion { get; init; }
}

/// <summary>
/// Request to update a trust anchor.
/// </summary>
public sealed record UpdateTrustAnchorRequest
{
    /// <summary>
    /// Updated predicate types.
    /// </summary>
    public IReadOnlyList<string>? AllowedPredicateTypes { get; init; }

    /// <summary>
    /// Updated policy reference.
    /// </summary>
    public string? PolicyRef { get; init; }

    /// <summary>
    /// Updated policy version.
    /// </summary>
    public string? PolicyVersion { get; init; }
}

/// <summary>
/// Result of trust verification.
/// </summary>
public sealed record TrustVerificationResult
{
    /// <summary>
    /// Whether the signature is authorized.
    /// </summary>
    public required bool IsAuthorized { get; init; }

    /// <summary>
    /// Reason for authorization failure (if applicable).
    /// </summary>
    public string? FailureReason { get; init; }

    /// <summary>
    /// The key status at the time of signing.
    /// </summary>
    public required KeyStatus KeyStatus { get; init; }

    /// <summary>
    /// Whether the predicate type was allowed.
    /// </summary>
    public bool? PredicateTypeAllowed { get; init; }
}