git.stella-ops.org/src/StellaOps.Authority/StellaOps.Auth.Abstractions/StellaOpsScopes.cs

using System;
using System.Collections.Generic;

namespace StellaOps.Auth.Abstractions;

/// <summary>
/// Canonical scope names supported by StellaOps services.
/// </summary>
public static class StellaOpsScopes
{
    /// <summary>
    /// Scope required to trigger Concelier jobs.
    /// </summary>
    public const string ConcelierJobsTrigger = "concelier.jobs.trigger";

    /// <summary>
    /// Scope required to manage Concelier merge operations.
    /// </summary>
    public const string ConcelierMerge = "concelier.merge";

    /// <summary>
    /// Scope granting administrative access to Authority user management.
    /// </summary>
    public const string AuthorityUsersManage = "authority.users.manage";

    /// <summary>
    /// Scope granting administrative access to Authority client registrations.
    /// </summary>
    public const string AuthorityClientsManage = "authority.clients.manage";

    /// <summary>
    /// Scope granting read-only access to Authority audit logs.
    /// </summary>
    public const string AuthorityAuditRead = "authority.audit.read";

    /// <summary>
    /// Synthetic scope representing trusted network bypass.
    /// </summary>
    public const string Bypass = "stellaops.bypass";

    /// <summary>
    /// Scope granting read-only access to console UX features.
    /// </summary>
    public const string UiRead = "ui.read";

    /// <summary>
    /// Scope granting permission to approve exceptions.
    /// </summary>
    public const string ExceptionsApprove = "exceptions:approve";

    /// <summary>
    /// Scope granting read-only access to raw advisory ingestion data.
    /// </summary>
    public const string AdvisoryRead = "advisory:read";

    /// <summary>
    /// Scope granting write access for raw advisory ingestion.
    /// </summary>
    public const string AdvisoryIngest = "advisory:ingest";

    /// <summary>
    /// Scope granting read-only access to raw VEX ingestion data.
    /// </summary>
    public const string VexRead = "vex:read";

    /// <summary>
    /// Scope granting write access for raw VEX ingestion.
    /// </summary>
    public const string VexIngest = "vex:ingest";

    /// <summary>
    /// Scope granting permission to execute aggregation-only contract verification.
    /// </summary>
    public const string AocVerify = "aoc:verify";

    /// <summary>
    /// Scope granting read-only access to reachability signals.
    /// </summary>
    public const string SignalsRead = "signals:read";

    /// <summary>
    /// Scope granting permission to write reachability signals.
    /// </summary>
    public const string SignalsWrite = "signals:write";

    /// <summary>
    /// Scope granting administrative access to reachability signal ingestion.
    /// </summary>
    public const string SignalsAdmin = "signals:admin";

    /// <summary>
    /// Scope granting permission to create or edit policy drafts.
    /// </summary>
    public const string PolicyWrite = "policy:write";

    /// <summary>
    /// Scope granting permission to author Policy Studio workspaces.
    /// </summary>
    public const string PolicyAuthor = "policy:author";

    /// <summary>
    /// Scope granting permission to edit policy configurations.
    /// </summary>
    public const string PolicyEdit = "policy:edit";

    /// <summary>
    /// Scope granting read-only access to policy metadata.
    /// </summary>
    public const string PolicyRead = "policy:read";

    /// <summary>
    /// Scope granting permission to review Policy Studio drafts.
    /// </summary>
    public const string PolicyReview = "policy:review";

    /// <summary>
    /// Scope granting permission to submit drafts for review.
    /// </summary>
    public const string PolicySubmit = "policy:submit";

    /// <summary>
    /// Scope granting permission to approve or reject policies.
    /// </summary>
    public const string PolicyApprove = "policy:approve";

    /// <summary>
    /// Scope granting permission to operate Policy Studio promotions and runs.
    /// </summary>
    public const string PolicyOperate = "policy:operate";

    /// <summary>
    /// Scope granting permission to audit Policy Studio activity.
    /// </summary>
    public const string PolicyAudit = "policy:audit";

    /// <summary>
    /// Scope granting permission to trigger policy runs and activation workflows.
    /// </summary>
    public const string PolicyRun = "policy:run";

    /// <summary>
    /// Scope granting permission to activate policies.
    /// </summary>
    public const string PolicyActivate = "policy:activate";

    /// <summary>
    /// Scope granting read-only access to effective findings materialised by Policy Engine.
    /// </summary>
    public const string FindingsRead = "findings:read";

    /// <summary>
    /// Scope granting permission to run Policy Studio simulations.
    /// </summary>
    public const string PolicySimulate = "policy:simulate";

    /// <summary>
    /// Scope granted to Policy Engine service identity for writing effective findings.
    /// </summary>
    public const string EffectiveWrite = "effective:write";

    /// <summary>
    /// Scope granting read-only access to graph queries and overlays.
    /// </summary>
    public const string GraphRead = "graph:read";

    /// <summary>
    /// Scope granting read-only access to Vuln Explorer resources and permalinks.
    /// </summary>
    public const string VulnRead = "vuln:read";

    /// <summary>
    /// Scope granting read-only access to export center runs and bundles.
    /// </summary>
    public const string ExportViewer = "export.viewer";

    /// <summary>
    /// Scope granting permission to operate export center scheduling and run execution.
    /// </summary>
    public const string ExportOperator = "export.operator";

    /// <summary>
    /// Scope granting administrative control over export center retention, encryption keys, and scheduling policies.
    /// </summary>
    public const string ExportAdmin = "export.admin";

    /// <summary>
    /// Scope granting permission to enqueue or mutate graph build jobs.
    /// </summary>
    public const string GraphWrite = "graph:write";

    /// <summary>
    /// Scope granting permission to export graph artefacts (GraphML/JSONL/etc.).
    /// </summary>
    public const string GraphExport = "graph:export";

    /// <summary>
    /// Scope granting permission to trigger what-if simulations on graphs.
    /// </summary>
    public const string GraphSimulate = "graph:simulate";

    /// <summary>
    /// Scope granting read-only access to Orchestrator job state and telemetry.
    /// </summary>
    public const string OrchRead = "orch:read";

    /// <summary>
    /// Scope granting permission to execute Orchestrator control actions.
    /// </summary>
    public const string OrchOperate = "orch:operate";

    /// <summary>
    /// Scope granting read-only access to Authority tenant catalog APIs.
    /// </summary>
    public const string AuthorityTenantsRead = "authority:tenants.read";

    private static readonly HashSet<string> KnownScopes = new(StringComparer.OrdinalIgnoreCase)
    {
        ConcelierJobsTrigger,
        ConcelierMerge,
        AuthorityUsersManage,
        AuthorityClientsManage,
        AuthorityAuditRead,
        Bypass,
        UiRead,
        ExceptionsApprove,
        AdvisoryRead,
        AdvisoryIngest,
        VexRead,
        VexIngest,
        AocVerify,
        SignalsRead,
        SignalsWrite,
        SignalsAdmin,
        PolicyWrite,
        PolicyAuthor,
        PolicyEdit,
        PolicyRead,
        PolicyReview,
        PolicySubmit,
        PolicyApprove,
        PolicyOperate,
        PolicyAudit,
        PolicyRun,
        PolicyActivate,
        PolicySimulate,
        FindingsRead,
        EffectiveWrite,
        GraphRead,
        VulnRead,
        ExportViewer,
        ExportOperator,
        ExportAdmin,
        GraphWrite,
        GraphExport,
        GraphSimulate,
        OrchRead,
        OrchOperate,
        AuthorityTenantsRead
    };

    /// <summary>
    /// Normalises a scope string (trim/convert to lower case).
    /// </summary>
    /// <param name="scope">Scope raw value.</param>
    /// <returns>Normalised scope or <c>null</c> when the input is blank.</returns>
    public static string? Normalize(string? scope)
    {
        if (string.IsNullOrWhiteSpace(scope))
        {
            return null;
        }

        return scope.Trim().ToLowerInvariant();
    }

    /// <summary>
    /// Checks whether the provided scope is registered as a built-in StellaOps scope.
    /// </summary>
    public static bool IsKnown(string scope)
    {
        ArgumentNullException.ThrowIfNull(scope);
        return KnownScopes.Contains(scope);
    }

    /// <summary>
    /// Returns the full set of built-in scopes.
    /// </summary>
    public static IReadOnlyCollection<string> All => KnownScopes;
}