Kickside Security

The admin surface for app-owned roles, scopes, and policy composition.

• A policy (security.policy) is a grant declared by its owning package. A policy tagged meta.private = true is internal and is never offered when composing a scope; only public policies are selectable.
• A scope (security.scope) is a named set of policy ids, resolved at runtime by security.named_scope. Built-in scopes are implicit groups (app.security:*); custom scopes are admin-authored, DB-backed, and projected into security.scope registry entries by the projection service.
• A role is a policy group; the roles surface composes groups from policies.

Internal/system scopes (e.g. app.security:ingress) and private policies are hidden from the admin UI.

Slice layout

Hexagonal layers under the kickside.security prefix; children import the root, never the reverse:

• kickside.security — shared vocabulary (consts, types), the requirement interface (api_router, ui_server, target_db, process_host), the DB resolver (db_config), and the UI mount.
• kickside.security.persist — scope_store: DB CRUD for custom scopes (kickside_security_scopes). The only layer that touches SQL.
• kickside.security.service — scope_projection.service: the supervised process that owns the DB → security.scope projection. Boot-reconciles and listens for admin write notifications, idempotently. The only layer that spawns and writes the registry; it runs under a dedicated trust group because wippy.security:process denies registry writes.
• kickside.security.api — scope_catalog (read model) plus the admin endpoints for scopes, policies, and roles.
• kickside.security.migrations — schema.

API (admin-only; firewalled api_router)

| Method | Path | Purpose | |---|---|---| | GET | /security/scopes | scope/role catalog (internal hidden unless ?include_internal) | | POST | /security/scopes | create/update a custom scope | | DELETE | /security/scopes?slug= | remove a custom scope | | GET | /security/policies | public policy catalog (?include_private to include private) | | GET | /security/roles | roles + policy assignments + user counts | | POST | /security/roles | create a role by assigning a group to policies |

Custom-scope writes hit the DB only; the projection service projects them into security.scope registry entries on its next reconcile.

Requirements

• target_db — required database backing kickside_security_scopes.
• process_host — required host for the projection service.
• api_router — required firewalled router for the endpoints.
• ui_server — required HTTP server for the UI bundle.