Skip to content

Structured editing for ACL rules, tags and groups #607

Closed

Description

@albedev

Description

The Access Control page is currently a raw HuJSON editor. Everything an
operator does day to day — adding a rule, declaring a tag, putting a user in a
group — means hand-editing JSON and knowing the syntax by heart. A structured
editor on top of the existing file editor would make the common cases safe and
discoverable, while leaving the file editor for everything else.

Concretely, three things are missing:

  1. Editing rules without writing JSON. acls, ssh and hosts are lists
    of well-known shapes. They can be rendered as editable rows, with sources and
    destinations picked from the groups, tags, hosts and Headscale users that
    actually exist in the tailnet. Headscale rejects a destination without a port
    spec, which is an easy mistake to make by hand.

  2. Managing tags and groups where they are used. tagOwners and groups
    are the parts of the policy that change most often, and they are the parts
    that relate to objects Headplane already shows elsewhere. A tag's meaning is
    invisible from the Machines page, and a user's group membership is invisible
    from the Users page even though the ACL is what grants them access. A tag
    assigned to a node but missing from tagOwners will never match a rule, and
    nothing surfaces that today.

  3. Not losing what the editor doesn't understand. Any structured editing has
    to round-trip unknown top-level keys (autoApprovers, nodeAttrs, ...)
    untouched, and be explicit about what it cannot preserve (HuJSON comments).

Relationship to existing issues

This is the editing half of what #286 described, and is complementary to #603,
which is about visualizing reachability as a graph. It also overlaps with the
open PRs #548 / #549 / #550. I have an implementation ready and will link it
here; happy to close it in favour of that work, or to rebase on top of it — your
call on which direction you want to take.

Activity

  1. pullfrog commented on Aug 17, 2026

    @pullfrog

    Plan: Structured editing for ACL rules, tags and groups

    Context

    The ACL page (app/routes/acls/overview.tsx) is a raw HuJSON editor with three tabs — Edit file (CodeMirror via cm.client.tsx), Preview changes (diff), and Preview rules (placeholder). Policy is HuJSON containing acls, ssh, hosts, groups, tagOwners, autoApprovers, nodeAttrs, etc. The codebase already parses HuJSON via stripJsonCommentsAndTrailingCommas, but that helper is private to app/utils/node-info.ts and only reads tagOwners. There is no shared, typed, round-tripping policy parser.

    The issue's three asks map cleanly onto the existing architecture:

    1. Editing rules without JSON — render acls/ssh/hosts as editable rows, with src/dst picked from existing groups, tags, hosts, and Headscale users (api.users.list(), api.nodes.list() for tags, plus policy-declared groups/hosts).
    2. Managing tags/groups where used — first-class tagOwners and groups editors, surfacing the relationships Headplane already knows about (a node's tags, a user's group membership).
    3. Round-trip safety — preserve unknown top-level keys (autoApprovers, nodeAttrs, ...) and be explicit about HuJSON comments.

    Decision point for the maintainer (blocking)

    The author notes they have an implementation ready and will link it, and is happy to close in favour of, or rebase on top of, the open #548 / #549 / #550 PRs (a visual ACL editor by a different contributor). Those PRs already cover the bulk of asks 1 and 2 using comment-json and a generic ArraySection<T> / RecordSection<V> approach. The first action here is triage: either adopt #548/#549/#550 as the base for this work, or wait for the author's PR and rebase. The milestones below are written to be direction-agnostic — they assume whatever structured-editor implementation lands, and focus on the shared foundation plus the pieces the existing PRs don't fully address (round-trip guarantees, data-source wiring, tag/group surface).

    Milestone 1 — Shared, typed, round-tripping policy parser

    • Extract stripJsonCommentsAndTrailingCommas from node-info.ts into a shared module (e.g. app/utils/policy.ts) and re-export from node-info.ts so existing callers are unaffected.
    • Add a typed policy model for the sections the editor understands (acls with { action, src, dst, proto? }, ssh, hosts, groups, tagOwners) while treating unknown keys as opaque passthrough.
    • Introduce a round-tripping parse/serialize that preserves unknown top-level keys and, where possible, comments (e.g. comment-json, matching Add HuJSON policy parsing and manipulation utilities #548) — and that detects HuJSON comments it cannot preserve so the UI can warn.
    • Unit tests under tests/unit/utils/policy.test.ts (see tests/unit/utils/ for existing patterns).

    Milestone 2 — Data sources for the pickers

    • Extend acl-loader.ts to fetch the principals the structured editor needs: api.users.list() and api.nodes.list() (tags via existing sortNodeTags), joined with policy-declared groups/hosts/tagOwners.
    • Keep this lazy/behind the structured tab so the raw file editor path pays no extra cost.
    • Handle the synthetic tagged-devices user (already mapped to "Tag-owned" in app/utils/user.ts).

    Milestone 3 — Structured editor UI (rules, tags, groups)

    • Add a Structured tab to overview.tsx, client-only/lazy-loaded like the existing lazy(() => import(...)) pattern.
    • Rules section: editable rows for acls/ssh/hosts, src/dst as autocomplete from the data in Milestone 2; enforce the destination port spec (Headscale rejects a bare host without a port — the exact failure the issue calls out).
    • Tags/groups section: tagOwners and groups editors, plus two surfacing features: warn when a node carries a tag absent from tagOwners, and show group membership against the Users page.
    • Edits stay in-memory and sync with the code editor's codePolicy state; "Save" still goes through the existing acl-action.ts PATCH flow.

    Milestone 4 — Round-trip safety guarantees

    • Before saving from the structured tab, verify unknown top-level keys survived; if HuJSON comments would be dropped, show an explicit warning (don't silently clobber them).
    • Reuse the existing Preview changes diff tab so the operator sees exactly what the structured editor produced before committing.

    Milestone 5 — Docs + verification

    • Update docs (ACL editing is currently only referenced in docs/introduction.md) and CHANGELOG.md.
    • Run pnpm run typecheck, lint, format, test:unit.

    Open questions

    1. Base implementation: adopt Add HuJSON policy parsing and manipulation utilities #548/feat(acl): visual editor UI with generic section components #549/feat(acl): add autoApprovers and ACL tests to visual editor #550, or the author's forthcoming PR? (Resolves the triage decision above.)
    2. Comment preservation: is warning-and-dropping comments acceptable, or must they round-trip? (comment-json can preserve; confirm before locking in.)
    3. Scope of "users" in pickers: Headscale users only, or also the machine hostnames as host: entries?
    Task list (4/4 completed)

    Pullfrog  | Implement plan ➔ | View workflow run | via Pullfrog | Using DeepSeek Pro (free via Pullfrog for OSS) | 𝕏

  2. linear-code commented on Aug 17, 2026

    @linear-code
  3. moved this from Todo to In Progress in Headplaneon Aug 17, 2026
  4. added
    FeatureAdditions to Headplane
    UI/UXRelated to the frontend UI
    on Aug 17, 2026
  5. moved this from In Progress to Done in Headplaneon Aug 28, 2026
  6. albedev commented on Oct 13, 2026

    @albedev
    ContributorAuthor

    @tale Hi tale! Still not released... should I do something?

  7. tale commented on Oct 13, 2026

    @tale
    Owner

    Let me cut one today.

  8. bdrewery commented on Oct 13, 2026

    @bdrewery

    This is great! Is there a plan to add support for the currently recommended grants from https://tailscale.com/docs/features/access-control/acls?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    FeatureAdditions to HeadplaneUI/UXRelated to the frontend UI

    Projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions