Documentation
¶
Overview ¶
Package passkeyauth provides application-neutral WebAuthn authentication primitives for first-party term-llm servers. It owns relying-party protocol handling, a versioned single-user credential store, browser sessions, ceremonies, and host-controlled enrollment grants.
Callers supply product policy such as the public endpoint, relying-party and user display names, store location, HTTP routes, cookie names, and UI. The package deliberately contains no Hub routing, branding, or proxy behavior so serve variants can share one authentication engine.
Index ¶
- Constants
- Variables
- func GenerateBootstrapSecret(r io.Reader) ([]byte, string, error)
- func NormalizeCredentialName(name string) (string, error)
- func ReadPrivateSecretFile(path string) ([]byte, error)
- func ValidateHostSecret(secret []byte) error
- type Ceremonies
- type Ceremony
- type CeremonyKind
- type Credential
- type Endpoint
- type EndpointOptions
- type GrantKind
- type GrantSession
- type Grants
- type IssuedSession
- type Principal
- type RelyingParty
- func (r *RelyingParty) BeginLogin(user User) (*protocol.CredentialAssertion, webauthn.SessionData, error)
- func (r *RelyingParty) BeginRegistration(user User) (*protocol.CredentialCreation, webauthn.SessionData, error)
- func (r *RelyingParty) FinishLogin(user User, session webauthn.SessionData, request *http.Request) (webauthn.Credential, error)
- func (r *RelyingParty) FinishRegistration(user User, session webauthn.SessionData, request *http.Request) (webauthn.Credential, error)
- type RelyingPartyOptions
- type SessionInfo
- type Sessions
- func (s *Sessions) Authenticate(token string) (Principal, error)
- func (s *Sessions) Close() error
- func (s *Sessions) ConsumeRecentAuth(p Principal) error
- func (s *Sessions) Count() int
- func (s *Sessions) Create(credentialRecordID string) (IssuedSession, error)
- func (s *Sessions) GrantRecentAuth(p Principal) error
- func (s *Sessions) HasRecentAuth(p Principal) bool
- func (s *Sessions) Info(p Principal) (SessionInfo, error)
- func (s *Sessions) Logout(p Principal) error
- func (s *Sessions) RevokeCredential(recordID string) (int, error)
- func (s *Sessions) RevokeOthers(p Principal) (int, error)
- type SessionsOptions
- type Store
- func (s *Store) AddCredential(raw webauthn.Credential, name string) (Credential, error)
- func (s *Store) CommitFirstCredential(raw webauthn.Credential, name string) (Credential, error)
- func (s *Store) CredentialCount() int
- func (s *Store) Credentials() []Credential
- func (s *Store) DeleteCredential(recordID string) (Credential, error)
- func (s *Store) HasCredential(recordID string) bool
- func (s *Store) Path() string
- func (s *Store) RenameCredential(recordID, name string) (Credential, error)
- func (s *Store) UpdateAfterAssertion(validated webauthn.Credential, reportedSignCount ...uint32) (Credential, error)
- func (s *Store) User() User
- type StoreOptions
- type User
Constants ¶
const ( HostGrantLifetime = 10 * time.Minute GrantSessionLifetime = 5 * time.Minute CeremonyLifetime = 5 * time.Minute MaxGrantSessions = 8 MaxCeremonies = 512 MaxCeremoniesPerPeer = 16 )
const ( StoreVersion = 1 DefaultUserName = "Passkey user" DefaultCredentialName = "Primary passkey" )
Variables ¶
var ( ErrInvalidGrant = errors.New("invalid or expired host grant") ErrGrantConsumed = errors.New("host grant already consumed") ErrCapacity = errors.New("authentication capacity reached") ErrInvalidCeremony = errors.New("invalid or expired ceremony") )
Functions ¶
func NormalizeCredentialName ¶
func ReadPrivateSecretFile ¶
ReadPrivateSecretFile reads an operator-managed bootstrap/recovery secret without following symlinks or accepting broadly accessible Unix files.
func ValidateHostSecret ¶
Types ¶
type Ceremonies ¶
type Ceremonies struct {
// contains filtered or unexported fields
}
func NewCeremonies ¶
func NewCeremonies(now func() time.Time, random io.Reader) *Ceremonies
func (*Ceremonies) Consume ¶
func (c *Ceremonies) Consume(token string, kind CeremonyKind, grantID, sessionID string) (Ceremony, error)
func (*Ceremonies) Create ¶
func (c *Ceremonies) Create(kind CeremonyKind, peer, grantID, sessionID, meta string, userHandle []byte, data webauthn.SessionData) (Ceremony, error)
type Ceremony ¶
type Ceremony struct {
ID, CookieToken, Peer string
Kind CeremonyKind
GrantID, SessionID, Meta string
UserHandle []byte
Data webauthn.SessionData
ExpiresAt time.Time
}
type CeremonyKind ¶
type CeremonyKind string
const ( CeremonyLogin CeremonyKind = "login" CeremonyReauth CeremonyKind = "reauth" CeremonyBootstrap CeremonyKind = "bootstrap" CeremonyRecovery CeremonyKind = "recovery" CeremonyAddCredential CeremonyKind = "add_credential" )
type Credential ¶
type Credential struct {
RecordID string `json:"-"`
DisplayName string `json:"-"`
WebAuthn webauthn.Credential `json:"-"`
CreatedAt time.Time `json:"-"`
LastUsedAt time.Time `json:"-"`
}
Credential wraps protocol state in an application-owned, versioned on-disk representation. WebAuthn is deliberately excluded from default JSON encoding; MarshalJSON and UnmarshalJSON below enumerate every persisted protocol field.
func (Credential) MarshalJSON ¶
func (c Credential) MarshalJSON() ([]byte, error)
func (*Credential) UnmarshalJSON ¶
func (c *Credential) UnmarshalJSON(data []byte) error
type Endpoint ¶
type Endpoint struct {
URL *url.URL
Origin string
RPID string
BasePath string
CookiePath string
Secure bool
}
Endpoint is the browser-visible WebAuthn relying-party configuration.
func ParseEndpoint ¶
func ParseEndpoint(opts EndpointOptions) (Endpoint, error)
ParseEndpoint validates a browser-visible URL without consulting request-controlled Host or forwarding headers.
func (Endpoint) SafeReturnPath ¶
SafeReturnPath accepts only a root-relative browser path beneath the configured mount.
type EndpointOptions ¶
type GrantSession ¶
type IssuedSession ¶
type IssuedSession struct {
Token string
Info SessionInfo
}
type RelyingParty ¶
type RelyingParty struct {
// contains filtered or unexported fields
}
RelyingParty pins WebAuthn validation to the configured public origin and RP ID.
func NewRelyingParty ¶
func NewRelyingParty(opts RelyingPartyOptions) (*RelyingParty, error)
func (*RelyingParty) BeginLogin ¶
func (r *RelyingParty) BeginLogin(user User) (*protocol.CredentialAssertion, webauthn.SessionData, error)
func (*RelyingParty) BeginRegistration ¶
func (r *RelyingParty) BeginRegistration(user User) (*protocol.CredentialCreation, webauthn.SessionData, error)
func (*RelyingParty) FinishLogin ¶
func (r *RelyingParty) FinishLogin(user User, session webauthn.SessionData, request *http.Request) (webauthn.Credential, error)
func (*RelyingParty) FinishRegistration ¶
func (r *RelyingParty) FinishRegistration(user User, session webauthn.SessionData, request *http.Request) (webauthn.Credential, error)
type RelyingPartyOptions ¶
RelyingPartyOptions contains application policy needed to construct a WebAuthn relying party. Endpoint validation remains independent so callers can share it with cookie and request-origin handling.
type SessionInfo ¶
type Sessions ¶
type Sessions struct {
// contains filtered or unexported fields
}
func NewSessions ¶
NewSessions returns an in-memory session registry. Hub runtimes should use OpenSessions so authenticated browser sessions survive process restarts.
func OpenSessions ¶ added in v0.9.0
func OpenSessions(opts SessionsOptions) (*Sessions, error)
OpenSessions opens or creates a private durable session registry. Only token hashes are persisted; raw browser cookie tokens remain known only to clients.
func (*Sessions) ConsumeRecentAuth ¶
func (*Sessions) Create ¶
func (s *Sessions) Create(credentialRecordID string) (IssuedSession, error)
func (*Sessions) GrantRecentAuth ¶
func (*Sessions) HasRecentAuth ¶
func (*Sessions) RevokeCredential ¶
type SessionsOptions ¶ added in v0.9.0
type Store ¶
type Store struct {
// contains filtered or unexported fields
}
func OpenStore ¶
func OpenStore(opts StoreOptions) (*Store, error)
func (*Store) AddCredential ¶
func (s *Store) AddCredential(raw webauthn.Credential, name string) (Credential, error)
func (*Store) CommitFirstCredential ¶
func (s *Store) CommitFirstCredential(raw webauthn.Credential, name string) (Credential, error)
func (*Store) CredentialCount ¶
func (*Store) Credentials ¶
func (s *Store) Credentials() []Credential
func (*Store) DeleteCredential ¶
func (s *Store) DeleteCredential(recordID string) (Credential, error)
func (*Store) HasCredential ¶ added in v0.9.0
func (*Store) RenameCredential ¶
func (s *Store) RenameCredential(recordID, name string) (Credential, error)
func (*Store) UpdateAfterAssertion ¶
func (s *Store) UpdateAfterAssertion(validated webauthn.Credential, reportedSignCount ...uint32) (Credential, error)
type StoreOptions ¶
type User ¶
type User struct {
ID string `json:"id"`
Name string `json:"name"`
Credentials []Credential `json:"credentials"`
}
User is the single logical WebAuthn identity managed by a Store.
func (User) WebAuthnCredentials ¶
func (a User) WebAuthnCredentials() []webauthn.Credential