Documentation
¶
Overview ¶
Package auth implements cuxdeck's device pairing and request authentication. The model is deliberately small:
- Pairing codes are short-lived, single-use, and only ever shown on the machine itself (QR or terminal). Scanning one is the single mandatory security step of the whole product.
- A successful pairing mints a long random per-device token. Only its SHA-256 lands on disk; the token itself lives on the device.
- Any device can be revoked from the panel at any time.
The tunnel URL is never the secret — this package is why a leaked URL is a dead end.
Index ¶
- Constants
- Variables
- type Device
- type DeviceInfo
- type Store
- func (s *Store) Authenticate(token string) bool
- func (s *Store) DeviceList() []DeviceInfo
- func (s *Store) Devices() []Device
- func (s *Store) NewPairingCode(role string) string
- func (s *Store) NewRepairCode(deviceID string) string
- func (s *Store) Pair(code, name string) (token string, err error)
- func (s *Store) Revoke(id string)
- func (s *Store) Role(token string) string
Constants ¶
const ( RoleControl = "control" RoleView = "view" )
RoleControl is full access; RoleView is read-only (watch, but no switch/spawn/terminal/invite). A blank role means control, so devices paired before roles existed keep full access.
Variables ¶
var ErrBadPairing = errors.New("auth: invalid or expired pairing code")
ErrBadPairing is returned for unknown, expired, or reused codes.
Functions ¶
This section is empty.
Types ¶
type Device ¶
type Device struct {
ID string `json:"id"`
Name string `json:"name"`
TokenHash string `json:"tokenHash"` // sha256 hex; the token never touches disk
Role string `json:"role,omitempty"` // "view" | "control"; "" == control (pre-roles devices)
CreatedAt time.Time `json:"createdAt"`
LastSeen time.Time `json:"lastSeen"`
}
Device is one paired client (a phone, a tablet, a browser).
type DeviceInfo ¶ added in v0.1.9
DeviceInfo is the token-free view of a paired device.
type Store ¶
type Store struct {
// contains filtered or unexported fields
}
Store holds paired devices on disk and pairing state in memory.
func (*Store) Authenticate ¶
Authenticate reports whether token belongs to a paired device, and applies a linear backoff to consecutive failures so brute force is pointless. It updates the device's LastSeen on success.
func (*Store) DeviceList ¶ added in v0.1.9
func (s *Store) DeviceList() []DeviceInfo
DeviceList returns the paired devices without their token hashes, for callers that need to enumerate them (e.g. to address each by name).
func (*Store) NewPairingCode ¶
NewPairingCode returns a fresh single-use code (~80 bits, mostly used via QR/link but still typable by hand). Multiple codes can be outstanding at once: the menu bar, the panel's "add a phone" card, and the tunnel banner each mint their own, and a fresh mint must NOT invalidate a code a phone is mid-scan on.
func (*Store) NewRepairCode ¶ added in v0.1.9
NewRepairCode mints a single-use code bound to an existing device: using it renews that device's token (same id/name/role) rather than creating a new one. Returns "" if the device is unknown. Used to hand each paired device its own reconnect link when the tunnel address changes.
Source Files