You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Structured editing for ACL rules, tags and groups #607
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:
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.
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.
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.
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:
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).
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).
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).
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).
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.
Activity
pullfrog commentedon Aug 17, 2026
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 viacm.client.tsx), Preview changes (diff), and Preview rules (placeholder). Policy is HuJSON containingacls,ssh,hosts,groups,tagOwners,autoApprovers,nodeAttrs, etc. The codebase already parses HuJSON viastripJsonCommentsAndTrailingCommas, but that helper is private toapp/utils/node-info.tsand only readstagOwners. There is no shared, typed, round-tripping policy parser.The issue's three asks map cleanly onto the existing architecture:
acls/ssh/hostsas editable rows, withsrc/dstpicked from existing groups, tags, hosts, and Headscale users (api.users.list(),api.nodes.list()for tags, plus policy-declaredgroups/hosts).tagOwnersandgroupseditors, surfacing the relationships Headplane already knows about (a node's tags, a user's group membership).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-jsonand a genericArraySection<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
stripJsonCommentsAndTrailingCommasfromnode-info.tsinto a shared module (e.g.app/utils/policy.ts) and re-export fromnode-info.tsso existing callers are unaffected.aclswith{ action, src, dst, proto? },ssh,hosts,groups,tagOwners) while treating unknown keys as opaque passthrough.comment-json, matching Add HuJSON policy parsing and manipulation utilities #548) — and that detects HuJSON comments it cannot preserve so the UI can warn.tests/unit/utils/policy.test.ts(seetests/unit/utils/for existing patterns).Milestone 2 — Data sources for the pickers
acl-loader.tsto fetch the principals the structured editor needs:api.users.list()andapi.nodes.list()(tags via existingsortNodeTags), joined with policy-declaredgroups/hosts/tagOwners.tagged-devicesuser (already mapped to "Tag-owned" inapp/utils/user.ts).Milestone 3 — Structured editor UI (rules, tags, groups)
overview.tsx, client-only/lazy-loaded like the existinglazy(() => import(...))pattern.acls/ssh/hosts,src/dstas 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).tagOwnersandgroupseditors, plus two surfacing features: warn when a node carries a tag absent fromtagOwners, and show group membership against the Users page.codePolicystate; "Save" still goes through the existingacl-action.tsPATCH flow.Milestone 4 — Round-trip safety guarantees
Preview changesdiff tab so the operator sees exactly what the structured editor produced before committing.Milestone 5 — Docs + verification
docs/introduction.md) andCHANGELOG.md.pnpm run typecheck,lint,format,test:unit.Open questions
comment-jsoncan preserve; confirm before locking in.)host:entries?Task list (4/4 completed)
DeepSeek Pro(free via Pullfrog for OSS) | 𝕏linear-code commentedon Aug 17, 2026
HP-575
albedev commentedon Oct 13, 2026
@tale Hi tale! Still not released... should I do something?
tale commentedon Oct 13, 2026
Let me cut one today.
bdrewery commentedon Oct 13, 2026
This is great! Is there a plan to add support for the currently recommended
grantsfrom https://tailscale.com/docs/features/access-control/acls?