docs: document Builder, Scorch, and Tunneler permissions and roles

[GhostofGoes]

Description

tl;dr: Documents the new Builder, Scorch, and Tunneler permissions and roles, and moves roles and permissions to their own page.

Changes

• New Roles and Permissions page, under Administration:
  • How permission checks work: wildcards, named and unnamed checks, lists, live updates, and users holding a copy of their role.
  • Scoping a role to experiments with resource names.
  • The built-in roles, including the new Scorch Viewer, Scorch Admin, and Builder roles. It has a Builder, Scorch, and Tunneler access table, the scorch/terminals security warning, and the upgrade migration. The role YAML is copied verbatim from phēnix.
  • Custom roles, with an example and guidance on permissions that let a user gain more access.
  • Every resource and verb phēnix checks, grouped by area, with what each allows and what the check is named with.
    This includes the new users/tokens create permission, and notes that the configs API never returns User config password hashes or tokens.
• Users and Authentication page, which replaces "User Authn/Authz". Roles moved out, and the page was corrected against the phēnix code:
  • The UI build variable is VITE_AUTH, not VUE_APP_AUTH.
  • The API header is X-Phenix-Auth-Token: Bearer <token>, not a bare token.
  • Self sign-up creates a Disabled account and doesn't notify administrators.
  • The token dialog takes a lifetime in days or a Go duration.
  • The Users dialog has no "Experiment Names" field.
  • Creating a token for another user needs users/tokens create, and phēnix doesn't show a user's tokens.
  • Added: both proxy setups and a proxy security warning; the default admin@foo.com user; ui.users sources, format, precedence, and startup-only behavior; password requirements; signing in, logout, and API login; token revocation; editing and deleting users.
• Other pages:
  • API: corrected the auth header format and linked sign-in and tokens.
  • Scorch: an Access Control section, and the break and Scorch table text follow the new permissions.
  • Tunneler: the permissions needed.
  • Configuration: the Builder's permissions, and a link instead of the out-of-date default role count.

Background

sandialabs/sceptre-phenix#385 puts the Builder, Scorch, and Tunneler under access control and adds built-in roles, so the permissions docs needed updating. Reviewing the page against the code also showed it was out of date. It had the old UI build variable and a wrong API header format, described sign-up and token behavior that no longer exists, and was missing 21 checked resource/verb pairs.

Related Issues/PRs

• feat(rbac): protect Scorch, Builder, and Tunneler sceptre-phenix#385

Type of Change

• Bugfix (fix)
• Feature (feat)
• Documentation (docs)
• Refactor (refactor)
• Chore (CI, build, dependencies, etc.) (chore)
• Other (please describe):

Checklist

• This PR conforms to the process detailed in the Contributing Guide.
• I have included no proprietary/sensitive information in my code or the PR.
• I have commented my code, particularly in hard-to-understand areas.
• I have made corresponding changes to the documentation.
• I have tested my code (describe below).

Testing

• mkdocs build --strict passes.
• Every #anchor link in every docs page resolves in the rendered HTML (0 broken).
• prek run passes on the changed files.
• Every statement on both pages was checked against the phēnix code at feat(rbac): protect Scorch, Builder, and Tunneler sceptre-phenix#385. The built-in role YAML is byte-identical to src/go/api/config/default.
• ui.users behavior was checked on a running phēnix. Users added to a users file while phēnix is running are not picked up, so the page says the list is read at startup.

Additional Notes

Draft until sandialabs/sceptre-phenix#385 settles the default role permissions.

🤖 Generated with Claude Code