Auth: Add "photoprism show scopes" command to list all supported scopes

Signed-off-by: Michael Mayer <michael@photoprism.app>

internal/auth/acl/scope_descriptions.go

@@ -0,0 +1,36 @@
+package acl
+
+// ScopeDescriptions maps supported authorization scopes to human-readable summaries for CLI help and docs.
+var ScopeDescriptions = map[string]string{
+	"*":                        "Wildcard granting full access to every resource and permission.",
+	ScopeRead.String():         "Read-only access across all resources (search, view, download).",
+	ScopeWrite.String():        "Write access across all resources (create, update, delete) without implicit read permissions.",
+	ResourceFiles.String():     "Full access to original and derived files on disk.",
+	ResourceFolders.String():   "Manage virtual folders derived from the filesystem.",
+	ResourceShares.String():    "Manage share links and published collections.",
+	ResourcePhotos.String():    "Operate on photo library items and metadata.",
+	ResourceVideos.String():    "Operate on video library items and metadata.",
+	ResourceFavorites.String(): "Manage the favorites collection.",
+	ResourceAlbums.String():    "Create and manage albums.",
+	ResourceMoments.String():   "Access automatically grouped moments and events.",
+	ResourceCalendar.String():  "Access calendar-based timelines.",
+	ResourcePeople.String():    "Manage people records and face assignments.",
+	ResourcePlaces.String():    "Access maps, locations, and place clusters.",
+	ResourceLabels.String():    "Manage subject labels and keywords.",
+	ResourceConfig.String():    "Read configuration reports and summaries.",
+	ResourceSettings.String():  "Read and update application settings.",
+	ResourcePasscode.String():  "Manage app passcodes and guest access codes.",
+	ResourcePassword.String():  "Manage user password change and reset endpoints.",
+	ResourceServices.String():  "Manage connected services and integrations.",
+	ResourceUsers.String():     "Administer user accounts and profiles.",
+	ResourceSessions.String():  "Inspect and revoke active sessions and tokens.",
+	ResourceLogs.String():      "Read system, audit, and application logs.",
+	ResourceApi.String():       "Call generic API endpoints outside other scopes.",
+	ResourceWebDAV.String():    "Access the WebDAV interface for syncing files.",
+	ResourceWebhooks.String():  "Manage webhook subscriptions and deliveries.",
+	ResourceMetrics.String():   "Read operational metrics for monitoring.",
+	ResourceVision.String():    "Use AI vision endpoints and related queues.",
+	ResourceCluster.String():   "Manage cluster registration and node state.",
+	ResourceFeedback.String():  "Submit and review feedback or support reports.",
+	ResourceDefault.String():   "Fallback for endpoints without a dedicated resource tag.",
+}

internal/commands/show.go

@@ -14,6 +14,7 @@ var ShowCommands = &cli.Command{
 		ShowConfigYamlCommand,
 		ShowSearchFiltersCommand,
 		ShowFileFormatsCommand,
+		ShowScopesCommand,
 		ShowSourcesCommand,
 		ShowThumbSizesCommand,
 		ShowVideoSizesCommand,

internal/commands/show_json_test.go

@@ -52,6 +52,29 @@ func TestShowSources_JSON(t *testing.T) {
 	}
 }
 
+func TestShowScopes_JSON(t *testing.T) {
+	out, err := RunWithTestContext(ShowScopesCommand, []string{"scopes", "--json"})
+
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	var v []map[string]string
+
+	if err = json.Unmarshal([]byte(out), &v); err != nil {
+		t.Fatalf("invalid json: %v\n%s", err, out)
+	}
+	if len(v) == 0 {
+		t.Fatalf("expected at least one item")
+	}
+	if _, ok := v[0]["scope"]; !ok {
+		t.Fatalf("expected key 'scope' in first item")
+	}
+	if _, ok := v[0]["description"]; !ok {
+		t.Fatalf("expected key 'description' in first item")
+	}
+}
+
 func TestShowMetadata_JSON(t *testing.T) {
 	out, err := RunWithTestContext(ShowMetadataCommand, []string{"metadata", "--json"})
 

internal/commands/show_scopes.go

@@ -0,0 +1,57 @@
+package commands
+
+import (
+	"fmt"
+
+	"github.com/urfave/cli/v2"
+
+	"github.com/photoprism/photoprism/internal/auth/acl"
+	"github.com/photoprism/photoprism/pkg/txt/report"
+)
+
+// ShowScopesCommand configures the CLI command that lists supported authorization scopes.
+var ShowScopesCommand = &cli.Command{
+	Name:   "scopes",
+	Usage:  "Displays supported authorization scopes",
+	Flags:  append(report.CliFlags),
+	Action: showScopesAction,
+}
+
+// showScopesAction renders the list of supported authorization scopes.
+func showScopesAction(ctx *cli.Context) error {
+	rows, cols := scopesReport()
+	format, formatErr := report.CliFormatStrict(ctx)
+	if formatErr != nil {
+		return formatErr
+	}
+
+	result, err := report.RenderFormat(rows, cols, format)
+	fmt.Println(result)
+
+	return err
+}
+
+// scopesReport returns the table rows and columns for the scope listing.
+func scopesReport() (rows [][]string, cols []string) {
+	cols = []string{"scope", "description"}
+
+	rows = make([][]string, 0, len(acl.ScopeDescriptions))
+
+	for _, scope := range []string{"*", acl.ScopeRead.String(), acl.ScopeWrite.String()} {
+		if desc, ok := acl.ScopeDescriptions[scope]; ok {
+			rows = append(rows, []string{scope, desc})
+		}
+	}
+
+	for _, resource := range acl.ResourceNames {
+		name := resource.String()
+		desc, ok := acl.ScopeDescriptions[name]
+		if !ok {
+			// Should never happen, but keep the command resilient.
+			desc = "Resource available for use in authorization scopes."
+		}
+		rows = append(rows, []string{name, desc})
+	}
+
+	return rows, cols
+}