auth

package
v1.46.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 20, 2026 License: AGPL-3.0 Imports: 22 Imported by: 0

Documentation

Index

Constants

View Source 
const (

	// AuthCookieName is the name of the HTTP session cookie.
	AuthCookieName = "cs_auth"
)
View Source 
const QRSize = 256

QRSize is the pixel dimension of the generated QR code PNG.

View Source 
const SetupTokenDir = "auth"

SetupTokenDir is the subdirectory inside the config dir that holds the setup token. Using a dedicated subdirectory keeps the fsnotify watcher away from the busy root state directory, eliminating spurious wakeups from unrelated session state writes.

View Source 
const SetupTokenFile = "setup-token.json"

SetupTokenFile is the well-known filename written by print-qr-codes and watched by the running server.

Variables

This section is empty.

Functions

func AuthTokenTTL 

func AuthTokenTTL() time.Duration

AuthTokenTTL returns the authentication token TTL for use in cookie Max-Age.

func GenerateQRPNG 

func GenerateQRPNG(url string) ([]byte, error)

GenerateQRPNG returns a PNG-encoded QR code for the given URL.

func PrintQRToTerminal 

func PrintQRToTerminal(url string) error

PrintQRToTerminal prints an ASCII-art QR code to stderr so the operator can scan it directly from the terminal.

func RegisterRoutes 

func RegisterRoutes(mux *http.ServeMux, waHandler *Handler, sessions *SessionManager, store *CredentialStore, setup *SetupManager, invites *InviteManager, tlsCAPath, primaryDomain string, remotePort int)

RegisterRoutes registers all /auth/* endpoints on mux. primaryDomain is the hostname used in the CA download filename so clients know which server issued the cert (e.g. "myhost.local"). remotePort is the HTTPS port used when building invite URLs.

Types

type CredentialStore 

type CredentialStore struct {
	// contains filtered or unexported fields
}

CredentialStore persists WebAuthn credentials to disk as JSON. Thread-safe via a mutex for in-process coordination and a file lock for multi-process safety (though stapler-squad runs as a single process).

func NewCredentialStore 

func NewCredentialStore() (*CredentialStore, error)

NewCredentialStore creates or loads the credential store from the workspace config directory.

func (*CredentialStore) AddCredential 

func (cs *CredentialStore) AddCredential(cred webauthn.Credential, displayName string) error

AddCredential persists a new credential atomically. displayName is stored as-is; callers may pass an empty string.

func (*CredentialStore) CredentialCount 

func (cs *CredentialStore) CredentialCount() int

CredentialCount returns the number of registered passkeys.

func (*CredentialStore) GetCredentials 

func (cs *CredentialStore) GetCredentials() []webauthn.Credential

GetCredentials returns a copy of all stored credentials.

func (*CredentialStore) HasCredentials 

func (cs *CredentialStore) HasCredentials() bool

HasCredentials reports whether any passkeys are registered.

func (*CredentialStore) ListCredentials added in v1.23.1 

func (cs *CredentialStore) ListCredentials() []StoredCredentialInfo

ListCredentials returns credential metadata for all stored credentials.

func (*CredentialStore) RemoveCredential 

func (cs *CredentialStore) RemoveCredential(credID []byte) error

RemoveCredential removes a credential by ID.

func (*CredentialStore) UpdateCredential 

func (cs *CredentialStore) UpdateCredential(cred webauthn.Credential) error

UpdateCredential updates the sign count and last-used timestamp of an existing credential.

type Handler 

type Handler struct {
	// contains filtered or unexported fields
}

Handler wraps the go-webauthn/webauthn library and provides dynamic RPID selection to support multiple hostnames.

func NewHandler 

func NewHandler(rpIDs []string, origins []string, store *CredentialStore, session *SessionManager) (*Handler, error)

NewHandler creates a new WebAuthn handler supporting multiple domains.

func (*Handler) BeginLogin 

func (h *Handler) BeginLogin(r *http.Request) (interface{}, string, error)

BeginLogin starts a passkey login ceremony.

func (*Handler) BeginRegistration 

func (h *Handler) BeginRegistration(r *http.Request) (*webauthn.SessionData, interface{}, string, error)

BeginRegistration starts a passkey registration ceremony.

func (*Handler) FinishLogin 

func (h *Handler) FinishLogin(ceremonyKey string, r *http.Request) (string, error)

FinishLogin completes the login ceremony.

func (*Handler) FinishRegistration 

func (h *Handler) FinishRegistration(ceremonyKey string, r *http.Request, displayName string) (string, error)

FinishRegistration completes the registration ceremony. displayName is the label provided during invite generation; empty string is accepted.

type InviteManager added in v1.23.1 

type InviteManager struct {
	// contains filtered or unexported fields
}

InviteManager issues short-lived one-time tokens that allow an unauthenticated device to register a passkey. Unlike SetupManager (bootstrap-only, file-backed), InviteManager is in-memory and requires an authenticated caller to generate tokens.

func NewInviteManager added in v1.23.1 

func NewInviteManager() *InviteManager

NewInviteManager creates an InviteManager.

func (*InviteManager) Consume added in v1.23.1 

func (m *InviteManager) Consume(candidate string) (label string, ok bool)

Consume validates and removes the token atomically. Returns the associated label if successful, empty string if not found or expired.

func (*InviteManager) Generate added in v1.23.1 

func (m *InviteManager) Generate(label string) (token string, expiresAt time.Time, err error)

Generate creates a new invite token with the given label, evicting the oldest entry if the slot limit is reached. Returns the token and its expiry time.

func (*InviteManager) IsValid added in v1.23.1 

func (m *InviteManager) IsValid(candidate string) bool

IsValid checks whether the candidate token is valid without consuming it.

type SessionManager 

type SessionManager struct {
	// contains filtered or unexported fields
}

SessionManager manages two distinct token spaces:

  1. WebAuthn ceremony sessions (short-lived, indexed by a random key stored in the browser session storage during the ceremony).
  2. Authenticated sessions (long-lived, persisted to disk so they survive server restarts).

func NewSessionManager 

func NewSessionManager(sessionsPath string) *SessionManager

NewSessionManager creates a SessionManager. If sessionsPath is non-empty, auth sessions are loaded from and persisted to that file so they survive server restarts (user stays logged in across rebuilds).

func (*SessionManager) CreateAuthSession 

func (sm *SessionManager) CreateAuthSession() (string, error)

CreateAuthSession issues a new authenticated session token.

func (*SessionManager) GetCeremony 

func (sm *SessionManager) GetCeremony(key string) (webauthn.SessionData, bool)

GetCeremony retrieves and removes the ceremony session data for the given key. Returns false if not found or expired.

func (*SessionManager) RevokeAllSessions 

func (sm *SessionManager) RevokeAllSessions()

RevokeAllSessions invalidates all authenticated sessions (force re-auth).

func (*SessionManager) RevokeAuthSession 

func (sm *SessionManager) RevokeAuthSession(token string)

RevokeAuthSession invalidates a specific session token (logout).

func (*SessionManager) StoreCeremony 

func (sm *SessionManager) StoreCeremony(kind ceremonyKind, data webauthn.SessionData) (string, error)

StoreCeremony stores the WebAuthn session data for an in-progress ceremony and returns a random key the client must echo back.

func (*SessionManager) ValidateAuthSession 

func (sm *SessionManager) ValidateAuthSession(token string) bool

ValidateAuthSession returns true if the token is valid and not expired.

type SetupManager 

type SetupManager struct {
	// contains filtered or unexported fields
}

SetupManager handles the bootstrap flow: a one-time setup token that allows the first passkey to be registered without existing auth.

Tokens are stored in-memory and can be refreshed from a file written by the print-qr-codes CLI command. The server watches the file via WatchFile.

func NewSetupManager 

func NewSetupManager() *SetupManager

NewSetupManager creates a SetupManager. Call Init() to generate a token.

func (*SetupManager) Consume 

func (s *SetupManager) Consume(candidate string) bool

Consume marks the setup token as used. Call after the full ceremony completes.

func (*SetupManager) GenerateToFile 

func (s *SetupManager) GenerateToFile(path string) (string, error)

GenerateToFile generates a new setup token, writes it to path, and loads it into the manager. Called by the print-qr-codes CLI command.

func (*SetupManager) Init 

func (s *SetupManager) Init() (string, error)

Init generates a new single-use setup token valid for setupTokenTTL and holds it in memory. Used at server startup when no passkeys are registered.

func (*SetupManager) IsActive 

func (s *SetupManager) IsActive() bool

IsActive returns true if a valid (unused, non-expired) setup token exists.

func (*SetupManager) IsValid 

func (s *SetupManager) IsValid(candidate string) bool

IsValid checks whether the candidate token is valid without consuming it.

func (*SetupManager) LoadFromFile 

func (s *SetupManager) LoadFromFile(path string) error

LoadFromFile reads a token from path and loads it into the manager.

func (*SetupManager) WatchFile 

func (s *SetupManager) WatchFile(ctx context.Context, path string)

WatchFile watches path for writes and reloads the token on each change. Blocks until ctx is cancelled; intended to be run in a goroutine.

type StoredCredentialInfo added in v1.23.1 

type StoredCredentialInfo struct {
	ID          string     `json:"id"`
	DisplayName string     `json:"display_name"`
	CreatedAt   *time.Time `json:"created_at,omitempty"`
	LastUsedAt  *time.Time `json:"last_used_at,omitempty"`
	SignCount   uint32     `json:"sign_count"`
}

StoredCredentialInfo is the public view of a stored credential for the HTTP API.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.