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

using System;
using System.Collections.Generic;
using System.Collections.ObjectModel;
using System.Linq;
using System.Reflection;

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 Advisory AI artefacts (summaries, remediation exports).
    /// </summary>
    public const string AdvisoryAiView = "advisory-ai:view";

    /// <summary>
    /// Scope permitting Advisory AI inference requests and workflow execution.
    /// </summary>
    public const string AdvisoryAiOperate = "advisory-ai:operate";

    /// <summary>
    /// Scope granting administrative control over Advisory AI configuration and profiles.
    /// </summary>
    public const string AdvisoryAiAdmin = "advisory-ai:admin";

    /// <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 seal or unseal an installation in air-gapped mode.
    /// </summary>
    public const string AirgapSeal = "airgap:seal";

    /// <summary>
    /// Scope granting permission to import offline bundles while in air-gapped mode.
    /// </summary>
    public const string AirgapImport = "airgap:import";

    /// <summary>
    /// Scope granting read-only access to air-gap status and sealing state endpoints.
    /// </summary>
    public const string AirgapStatusRead = "airgap:status:read";

    /// <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 publish approved policy versions with attested artefacts.
    /// </summary>
    public const string PolicyPublish = "policy:publish";

    /// <summary>
    /// Scope granting permission to promote policy attestations between environments.
    /// </summary>
    public const string PolicyPromote = "policy:promote";

    /// <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>
    [Obsolete("Use vuln:view (StellaOpsScopes.VulnView) instead.")]
    public const string VulnRead = "vuln:read";

    /// <summary>
    /// Scope granting read-only access to Vuln Explorer findings, reports, and dashboards.
    /// </summary>
    public const string VulnView = "vuln:view";

    /// <summary>
    /// Scope permitting triage actions (assign, comment, annotate) within Vuln Explorer.
    /// </summary>
    public const string VulnInvestigate = "vuln:investigate";

    /// <summary>
    /// Scope permitting state-changing operations (status transitions, remediation workflows) within Vuln Explorer.
    /// </summary>
    public const string VulnOperate = "vuln:operate";

    /// <summary>
    /// Scope permitting access to Vuln Explorer audit exports and immutable ledgers.
    /// </summary>
    public const string VulnAudit = "vuln:audit";

    /// <summary>
    /// Scope granting read-only access to observability dashboards and overlays.
    /// </summary>
    public const string ObservabilityRead = "obs:read";

    /// <summary>
    /// Scope granting read-only access to incident timelines and chronology data.
    /// </summary>
    public const string TimelineRead = "timeline:read";

    /// <summary>
    /// Scope granting permission to append events to incident timelines.
    /// </summary>
    public const string TimelineWrite = "timeline:write";

    /// <summary>
    /// Scope granting permission to create evidence packets in the evidence locker.
    /// </summary>
    public const string EvidenceCreate = "evidence:create";

    /// <summary>
    /// Scope granting read-only access to stored evidence packets.
    /// </summary>
    public const string EvidenceRead = "evidence:read";

    /// <summary>
    /// Scope granting permission to place or release legal holds on evidence packets.
    /// </summary>
    public const string EvidenceHold = "evidence:hold";

    /// <summary>
    /// Scope granting read-only access to attestation records and observer feeds.
    /// </summary>
    public const string AttestRead = "attest:read";

    /// <summary>
    /// Scope granting permission to activate or resolve observability incident mode controls.
    /// </summary>
    public const string ObservabilityIncident = "obs:incident";

    /// <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 read-only access to notifier channels, rules, and delivery history.
    /// </summary>
    public const string NotifyViewer = "notify.viewer";

    /// <summary>
    /// Scope permitting notifier rule management, delivery actions, and channel operations.
    /// </summary>
    public const string NotifyOperator = "notify.operator";

    /// <summary>
    /// Scope granting administrative control over notifier secrets, escalations, and platform-wide settings.
    /// </summary>
    public const string NotifyAdmin = "notify.admin";

    /// <summary>
    /// Scope granting read-only access to issuer directory catalogues.
    /// </summary>
    public const string IssuerDirectoryRead = "issuer-directory:read";

    /// <summary>
    /// Scope permitting creation and modification of issuer directory entries.
    /// </summary>
    public const string IssuerDirectoryWrite = "issuer-directory:write";

    /// <summary>
    /// Scope granting administrative control over issuer directory resources (delete, audit bypass).
    /// </summary>
    public const string IssuerDirectoryAdmin = "issuer-directory:admin";

    /// <summary>
    /// Scope required to issue or honour escalation actions for notifications.
    /// </summary>
    public const string NotifyEscalate = "notify.escalate";

    /// <summary>
    /// Scope granting read-only access to Task Packs catalogues and manifests.
    /// </summary>
    public const string PacksRead = "packs.read";

    /// <summary>
    /// Scope permitting publication or updates to Task Packs in the registry.
    /// </summary>
    public const string PacksWrite = "packs.write";

    /// <summary>
    /// Scope granting permission to execute Task Packs via CLI or Task Runner.
    /// </summary>
    public const string PacksRun = "packs.run";

    /// <summary>
    /// Scope granting permission to fulfil Task Pack approval gates.
    /// </summary>
    public const string PacksApprove = "packs.approve";

    /// <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 permission to manage Orchestrator quotas and elevated backfill tooling.
    /// </summary>
    public const string OrchQuota = "orch:quota";

    /// <summary>
    /// Scope granting permission to initiate orchestrator-controlled backfill runs.
    /// </summary>
    public const string OrchBackfill = "orch:backfill";

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

    /// <summary>
    /// Scope granting write access to Authority tenant management.
    /// </summary>
    public const string AuthorityTenantsWrite = "authority:tenants.write";

    /// <summary>
    /// Scope granting read-only access to Authority user management.
    /// </summary>
    public const string AuthorityUsersRead = "authority:users.read";

    /// <summary>
    /// Scope granting write access to Authority user management.
    /// </summary>
    public const string AuthorityUsersWrite = "authority:users.write";

    /// <summary>
    /// Scope granting read-only access to Authority role management.
    /// </summary>
    public const string AuthorityRolesRead = "authority:roles.read";

    /// <summary>
    /// Scope granting write access to Authority role management.
    /// </summary>
    public const string AuthorityRolesWrite = "authority:roles.write";

    /// <summary>
    /// Scope granting read-only access to Authority client registrations.
    /// </summary>
    public const string AuthorityClientsRead = "authority:clients.read";

    /// <summary>
    /// Scope granting write access to Authority client registrations.
    /// </summary>
    public const string AuthorityClientsWrite = "authority:clients.write";

    /// <summary>
    /// Scope granting read-only access to Authority token inventory.
    /// </summary>
    public const string AuthorityTokensRead = "authority:tokens.read";

    /// <summary>
    /// Scope granting permission to revoke Authority tokens.
    /// </summary>
    public const string AuthorityTokensRevoke = "authority:tokens.revoke";

    /// <summary>
    /// Scope granting read-only access to Authority branding configuration.
    /// </summary>
    public const string AuthorityBrandingRead = "authority:branding.read";

    /// <summary>
    /// Scope granting write access to Authority branding configuration.
    /// </summary>
    public const string AuthorityBrandingWrite = "authority:branding.write";

    /// <summary>
    /// Scope granting access to Console Admin UI and workflows.
    /// </summary>
    public const string UiAdmin = "ui.admin";

    /// <summary>
    /// Scope granting read-only access to Scanner scan results and metadata.
    /// </summary>
    public const string ScannerRead = "scanner:read";

    /// <summary>
    /// Scope granting permission to trigger Scanner scan operations.
    /// </summary>
    public const string ScannerScan = "scanner:scan";

    /// <summary>
    /// Scope granting permission to export Scanner results (SBOM, reports).
    /// </summary>
    public const string ScannerExport = "scanner:export";

    /// <summary>
    /// Scope granting write access to Scanner configuration.
    /// </summary>
    public const string ScannerWrite = "scanner:write";

    /// <summary>
    /// Scope granting read-only access to Scheduler job state and history.
    /// </summary>
    public const string SchedulerRead = "scheduler:read";

    /// <summary>
    /// Scope granting permission to operate Scheduler jobs (pause, resume, trigger).
    /// </summary>
    public const string SchedulerOperate = "scheduler:operate";

    /// <summary>
    /// Scope granting administrative control over Scheduler configuration.
    /// </summary>
    public const string SchedulerAdmin = "scheduler:admin";

    /// <summary>
    /// Scope granting permission to create attestations.
    /// </summary>
    public const string AttestCreate = "attest:create";

    /// <summary>
    /// Scope granting administrative control over Attestor configuration.
    /// </summary>
    public const string AttestAdmin = "attest:admin";

    /// <summary>
    /// Scope granting read-only access to Signer configuration and key metadata.
    /// </summary>
    public const string SignerRead = "signer:read";

    /// <summary>
    /// Scope granting permission to create signatures.
    /// </summary>
    public const string SignerSign = "signer:sign";

    /// <summary>
    /// Scope granting permission to rotate Signer keys.
    /// </summary>
    public const string SignerRotate = "signer:rotate";

    /// <summary>
    /// Scope granting administrative control over Signer configuration.
    /// </summary>
    public const string SignerAdmin = "signer:admin";

    /// <summary>
    /// Scope granting read-only access to SBOM documents.
    /// </summary>
    public const string SbomRead = "sbom:read";

    /// <summary>
    /// Scope granting permission to create or edit SBOM documents.
    /// </summary>
    public const string SbomWrite = "sbom:write";

    /// <summary>
    /// Scope granting permission to attest SBOM documents.
    /// </summary>
    public const string SbomAttest = "sbom:attest";

    /// <summary>
    /// Scope granting read-only access to Release metadata and workflows.
    /// </summary>
    public const string ReleaseRead = "release:read";

    /// <summary>
    /// Scope granting permission to create or edit Release metadata.
    /// </summary>
    public const string ReleaseWrite = "release:write";

    /// <summary>
    /// Scope granting permission to publish Releases.
    /// </summary>
    public const string ReleasePublish = "release:publish";

    /// <summary>
    /// Scope granting permission to bypass Release policy gates.
    /// </summary>
    public const string ReleaseBypass = "release:bypass";

    /// <summary>
    /// Scope granting read-only access to Zastava webhook observer state.
    /// </summary>
    public const string ZastavaRead = "zastava:read";

    /// <summary>
    /// Scope granting permission to trigger Zastava webhook processing.
    /// </summary>
    public const string ZastavaTrigger = "zastava:trigger";

    /// <summary>
    /// Scope granting administrative control over Zastava configuration.
    /// </summary>
    public const string ZastavaAdmin = "zastava:admin";

    /// <summary>
    /// Scope granting read-only access to exception records.
    /// </summary>
    public const string ExceptionsRead = "exceptions:read";

    /// <summary>
    /// Scope granting permission to create or edit exception records.
    /// </summary>
    public const string ExceptionsWrite = "exceptions:write";

    /// <summary>
    /// Scope granting permission to request exceptions (initiate approval workflow).
    /// </summary>
    public const string ExceptionsRequest = "exceptions:request";

    /// <summary>
    /// Scope granting administrative control over Graph resources.
    /// </summary>
    public const string GraphAdmin = "graph:admin";

    private static readonly IReadOnlyList<string> AllScopes = BuildAllScopes();
    private static readonly HashSet<string> KnownScopes = new(AllScopes, StringComparer.OrdinalIgnoreCase);

    /// <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 => AllScopes;

    private static IReadOnlyList<string> BuildAllScopes()
    {
        var values = typeof(StellaOpsScopes)
            .GetFields(BindingFlags.Public | BindingFlags.Static)
            .Where(static field => field is { IsLiteral: true, IsInitOnly: false } && field.FieldType == typeof(string))
            .Select(static field => (string)field.GetRawConstantValue()!)
            .Where(static value => !string.IsNullOrWhiteSpace(value))
            .Distinct(StringComparer.Ordinal)
            .OrderBy(static value => value, StringComparer.Ordinal)
            .ToArray();

        return new ReadOnlyCollection<string>(values);
    }
}