Documentation
¶
Overview ¶
Package permissions defines client roles and the capability lookup that gates privileged API methods.
Three orthogonal properties describe a request's authority:
- Locality: a connection from the device itself (loopback). Local means "physically at the device" — anyone with OS access owns the whole system anyway, so local connections default to admin.
- Role: the identity of a paired client, chosen at pairing approval.
- Session role: a voluntary downgrade a client declares for its own connection (e.g. a kiosk frontend restricting the UI it exposes). Reserved — nothing sets it yet, but the check honors it so kiosk support can land without touching handlers.
Handlers never compare roles directly; they require a capability, and roles map to capability sets. Finer-grained roles later are new map entries, not handler changes.
A remote request with no authenticated identity is legacy. Legacy access is admitted only on explicitly grandfathered appliance platforms and never inherits admin authority.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func LegacyEnabled ¶
LegacyEnabled reports whether platformID admits unauthenticated legacy API clients at all.
Types ¶
type Capability ¶
type Capability string
Capability names an operation whose availability varies by authority or legacy platform policy.
const ( // CapProfilesManage covers creating, updating, and deleting device // profiles, and reading profile switch IDs (bearer credentials that // authorize PIN-free switching). CapProfilesManage Capability = "profiles.manage" // CapSettingsWrite covers device settings changes, which include // disabling playtime limits and the require-profile launch gate. CapSettingsWrite Capability = "settings.write" // CapScreenshot covers capturing and returning the device display. CapScreenshot Capability = "screenshot" // CapInput covers injecting keyboard and gamepad input. CapInput Capability = "input" // CapUpdateApply covers replacing the running binary and restarting // the service. It is the one capability that is not about weakening // someone's limits: an update decides what code the device runs from // then on, and it stops whatever is playing to do it. Checking for an // update needs no capability. Legacy and member roles do not receive it. CapUpdateApply Capability = "update.apply" )
type Grant ¶
type Grant struct {
// Role is the paired client's stored role, RoleRemote for internal remote
// operations, or empty when no role-bearing identity exists.
Role Role
// SessionRole is a voluntary downgrade declared by the client for this
// session. Empty means no downgrade. Reserved for kiosk mode.
SessionRole Role
// PlatformID selects the audited legacy compatibility policy.
PlatformID string
// IsLocal is true for loopback connections.
IsLocal bool
// APIKeyAuthenticated is true after successful static API-key validation.
APIKeyAuthenticated bool
}
Grant describes the authority of a single request.
func (Grant) Access ¶
Access returns the request's effective public authority. AccessRemote is reserved for the internal Online dispatcher.
func (Grant) Authenticated ¶
Authenticated reports whether the request came from localhost, a valid API key, a paired client, or the internal remote dispatcher.
func (Grant) Capabilities ¶
func (g Grant) Capabilities() []Capability
Capabilities returns the effective grant's enabled capabilities in stable lexical order. The returned slice is always non-nil.
func (Grant) EffectiveRole ¶
EffectiveRole resolves the authority-bearing role. Localhost and API-key authentication are admin, paired unknown roles degrade to member, and an identityless remote request is legacy.
func (Grant) Has ¶
func (g Grant) Has(capability Capability) bool
Has reports whether the request may perform the given capability.
type Role ¶
type Role string
Role is a paired client's permission level.
const ( // RoleAdmin grants every capability. RoleAdmin Role = "admin" // RoleMember grants day-to-day use (browse, launch, switch profile // with PIN) but none of the capabilities that could weaken another // person's limits. RoleMember Role = "member" // RoleLegacy represents an unauthenticated compatibility client. It is // derived from request context and can never be selected during pairing. RoleLegacy Role = "legacy" // RoleRemote is assigned only by the device's own remote-operations // dispatcher, never by pairing (it is deliberately excluded from // ValidRole). It grants nothing today and never inherits whatever // RoleMember grows into later — the capability an allowlisted remote // operation runs with must always be visible in roleCapabilities, not // borrowed from a role that can change independently. RoleRemote Role = "remote" )
Source Files