authmaterial

package
v0.4.1 Latest Latest
Warning

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

 Go to latest Published: Oct 26, 2026 License: GPL-2.0 Imports: 21 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	UpgradeStagePrepared         = "prepared"
	UpgradeStageCookiesRewrapped = "cookies_rewrapped"
	UpgradeStageDataRewrapped    = "data_rewrapped"
)
View Source 
const (
	// AuthPasswordMinLength defines the minimum web auth password length.
	AuthPasswordMinLength = 12
)
View Source 
const (
	WebAuthFileName = "web-auth.json"
)

Variables

View Source 
var ErrUnavailable = errors.New("web auth material unavailable")

ErrUnavailable classifies missing, unusable, or insecurely permissioned web auth material. Callers should test it with errors.Is.

Functions

func AuthFilePath 

func AuthFilePath(dbPath string) string

AuthFilePath returns the web-auth.json path beside dbPath without touching the filesystem.

func BootstrapAuthFile 

func BootstrapAuthFile(dbPath string, username string, password string) error

BootstrapAuthFile creates the initial auth record and refuses to overwrite an existing record.

func GenerateSeed 

func GenerateSeed() (string, error)

GenerateSeed returns 32 cryptographically random bytes encoded as unpadded URL-safe base64.

func HashPassword 

func HashPassword(password string) (string, error)

HashPassword validates the minimum length and returns an Argon2id encoded hash with a new random salt.

func VerifyPassword 

func VerifyPassword(password string, encoded string) bool

VerifyPassword reports whether password matches a supported Argon2id encoding.

func VerifyPasswordWithUpgrade 

func VerifyPasswordWithUpgrade(password string, encoded string) (bool, bool)

VerifyPasswordWithUpgrade reports both password validity and whether the matched encoding uses the legacy three-part format.

Types

type APIKeyRecord added in v0.3.0 

type APIKeyRecord struct {
	ID         string           `json:"id"`
	Name       string           `json:"name"`
	OwnerID    string           `json:"owner_id"`
	APIKeyHash string           `json:"api_key_hash"`
	Scopes     []apitoken.Scope `json:"scopes"`
	CreatedAt  time.Time        `json:"created_at"`
	RevokedAt  *time.Time       `json:"revoked_at,omitempty"`
}

APIKeyRecord is one persisted bearer-key hash plus safe operator metadata. APIKeyHash is a one-way SHA-256 digest of a high-entropy generated token.

type Material 

type Material struct {
	Username               string `json:"username"`
	PasswordHash           string `json:"password_hash"`
	EncryptionKeySeed      string `json:"encryption_key_seed,omitempty"`
	AllowUnencryptedExport bool   `json:"allow_unencrypted_export,omitempty"`
}

Material contains the web-auth values used to derive stable or legacy encryption helpers. It does not contain the plaintext password.

func LoadFromDBPath 

func LoadFromDBPath(dbPath string) (Material, error)

LoadFromDBPath loads usable auth material from web-auth.json beside dbPath. Missing or incomplete material returns ErrUnavailable.

func (Material) IsUsable 

func (m Material) IsUsable() bool

IsUsable reports whether both the username and password hash are non-blank.

func (Material) LegacyHelper 

func (m Material) LegacyHelper() (string, string, error)

LegacyHelper derives the compatibility helper and its SHA-256 fingerprint from username and password hash. Missing inputs return ErrUnavailable.

func (Material) PrimaryHelper 

func (m Material) PrimaryHelper() (string, string, error)

PrimaryHelper returns the stable username-and-seed helper when available, otherwise the legacy username-and-password-hash helper.

func (Material) StableHelper 

func (m Material) StableHelper() (string, string, bool)

StableHelper derives the preferred helper and its SHA-256 fingerprint. The boolean is false when username or encryption-key seed is blank.

func (Material) WithSeed 

func (m Material) WithSeed(seed string) Material

WithSeed returns a copy with a trimmed encryption-key seed.

type PendingUpgrade 

type PendingUpgrade struct {
	Stage     string    `json:"stage"`
	Target    Record    `json:"target"`
	UpdatedAt time.Time `json:"updated_at"`
}

PendingUpgrade stores the target auth record and the last completed rewrap stage while the active record remains unchanged.

type Record 

type Record struct {
	Username                string          `json:"username"`
	PasswordHash            string          `json:"password_hash"`
	EncryptionKeySeed       string          `json:"encryption_key_seed,omitempty"`
	APIKeys                 []APIKeyRecord  `json:"api_keys,omitempty"`
	AllowUnencryptedExport  bool            `json:"allow_unencrypted_export,omitempty"`
	BrowseRoot              string          `json:"browse_root,omitempty"`
	AllowUnrestrictedBrowse bool            `json:"allow_unrestricted_browse,omitempty"`
	PendingUpgrade          *PendingUpgrade `json:"pending_upgrade,omitempty"`
	CreatedAt               time.Time       `json:"created_at"`
}

Record is the persisted web-auth state. PendingUpgrade makes auth-dependent data rewrap resumable without replacing the active credentials early.

func LoadRecordFromDBPath 

func LoadRecordFromDBPath(dbPath string) (Record, error)

LoadRecordFromDBPath loads the complete auth record from web-auth.json beside dbPath. On non-Windows systems, only modes 0400, 0440, 0600, and 0640 are accepted; unavailable or unusable records return ErrUnavailable.

func (Record) AuthMaterial 

func (r Record) AuthMaterial() Material

AuthMaterial returns a trimmed projection of the record's helper inputs.

type Store 

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

Store serializes operations performed through one web-auth file handle. Writes use a same-directory temporary file, sync it, set mode 0600, then rename it over the active record.

func NewStore 

func NewStore(dbPath string) (*Store, error)

NewStore targets web-auth.json beside dbPath and creates its parent directory.

func (*Store) AdvancePendingUpgrade 

func (s *Store) AdvancePendingUpgrade(username string, stage string) error

AdvancePendingUpgrade sets any recognized upgrade stage. It validates the stage name but does not enforce forward-only transitions.

func (*Store) BeginPendingUpgrade 

func (s *Store) BeginPendingUpgrade(current Record, target Record) error

BeginPendingUpgrade records target at the prepared stage only if current still matches the active auth and browse settings.

func (*Store) Bootstrap 

func (s *Store) Bootstrap(username string, password string) error

Bootstrap hashes the password, generates a stable encryption seed, and creates a new record. It refuses to replace an existing auth file.

func (*Store) ClearPendingUpgrade 

func (s *Store) ClearPendingUpgrade(username string) error

ClearPendingUpgrade removes pending upgrade state without changing active auth or browse settings.

func (*Store) CreateAPIToken added in v0.3.0 

func (s *Store) CreateAPIToken(ctx context.Context, stored apitoken.StoredRecord) error

CreateAPIToken appends one generated-key hash to web-auth.json.

func (*Store) CreateBackup added in v0.3.2 

func (s *Store) CreateBackup() (string, error)

CreateBackup copies the current auth file bytes to a unique secure file beside it. Completed backups are never overwritten or removed.

func (*Store) Exists 

func (s *Store) Exists() (bool, error)

Exists reports whether the store's auth file currently exists.

func (*Store) FinalizePendingUpgrade 

func (s *Store) FinalizePendingUpgrade(username string) (Record, error)

FinalizePendingUpgrade replaces the active record with its pending target, clears pending state, and preserves the original creation time.

func (*Store) FindActiveAPITokenByHash added in v0.3.0 

func (s *Store) FindActiveAPITokenByHash(
	ctx context.Context,
	hash [sha256.Size]byte,
) (apitoken.Record, error)

FindActiveAPITokenByHash resolves active metadata with constant-time hash comparison.

func (*Store) InitializeBrowsePolicy added in v0.3.2 

func (s *Store) InitializeBrowsePolicy(username string, browseRoot string, allowUnrestricted bool) (bool, error)

InitializeBrowsePolicy atomically persists the first WebUI browse policy. It returns false without modifying a policy that was already configured.

func (*Store) ListAPITokens added in v0.3.0 

func (s *Store) ListAPITokens(ctx context.Context) ([]apitoken.Record, error)

ListAPITokens returns safe metadata newest first; hashes remain private.

func (*Store) Load 

func (s *Store) Load() (Record, error)

Load reads the persisted record without applying the stricter usability and permission checks performed by LoadRecordFromDBPath.

func (*Store) RevokeAPIToken added in v0.3.0 

func (s *Store) RevokeAPIToken(ctx context.Context, id string, revokedAt time.Time) (bool, error)

RevokeAPIToken marks one active key revoked while retaining audit metadata.

func (*Store) UpdatePasswordHash 

func (s *Store) UpdatePasswordHash(username string, currentPasswordHash string, passwordHash string) error

UpdatePasswordHash replaces only the hash when username and current hash still match the active record.

func (*Store) UpdateRecord 

func (s *Store) UpdateRecord(updated Record) error

UpdateRecord replaces mutable auth, export, browse, and upgrade fields while preserving the active username and creation time.

Source Files

View all Source files

Directories

Path Synopsis
Package authfixture writes web-auth material for tests that exercise encrypted persistence without exercising password hashing.
 Package authfixture writes web-auth material for tests that exercise encrypted persistence without exercising password hashing.

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.