identity

type BackupEncryptionKeyCredential struct {
	// Engine is the snapshot engine name. Always "kopia" today; here so a
	// future format change does not require a bundle break.
	Engine string

	// Passphrase is the cleartext value passed to Kopia at
	// repository-create time. Goes into the recovery bundle; never
	// logged. Same handling discipline as TinyAuthStaticCredential.PasswordPlain.
	Passphrase string

	// RepositoryHint is a human-readable pointer to where the data
	// lives ("b2://kombify-vault/host-a", "sftp://u@host:/repo", …).
	// Optional. Helps a recovery operator who has only the bundle find
	// the offsite repo.
	RepositoryHint string
}

type BackupEncryptionKeyGenerator struct {
	// Engine is recorded into the credential. Defaults to "kopia".
	Engine string

	// RepositoryHint is recorded verbatim. Optional.
	RepositoryHint string
}

type BackupEncryptionKeyPayload struct {
	// Engine is the snapshot engine that owns the passphrase. "kopia" today;
	// the field is here so a future engine swap (extremely unlikely given
	// ADR-0016) does not require a bundle-format break.
	Engine string `yaml:"engine"`

	// Passphrase is the cleartext value the operator (or stackkit apply)
	// generated. Treat as secret. Same handling rules as the TinyAuth
	// plaintext password on the same bundle.
	Passphrase string `yaml:"passphrase"`

	// RepositoryHint is a human-readable pointer to where the data lives
	// (e.g. "b2://kombify-vault/host-a"). Optional. The recovery
	// operator typically already knows this from out-of-band sources;
	// the hint is here so a recovery scenario starting from "I only have
	// the bundle" is still tractable.
	RepositoryHint string `yaml:"repositoryHint,omitempty"`
}

type BreakGlassCredential struct {
	// Username is the synthetic local handle, of the form
	// "bg-<nodename>@local". It is unique per node so multiple homelabs
	// don't collide on a shared PocketID.
	Username string

	// SetupToken is the raw one-time-access token issued by PocketID. It
	// is single-use and consumed when the recoverer registers a passkey.
	SetupToken string

	// SetupURL is the full URL the recoverer clicks to complete WebAuthn
	// enrollment, of the form "https://id.<domain>/lc/<t>?redirect=%2Fsettings%2Faccount".
	SetupURL string

	// Group is the PocketID group the account was added to (typically
	// "owners").
	Group string

	// UserID is the PocketID-assigned UUID for this account, used by later
	// rotation/revoke operations.
	UserID string
}

type BreakGlassGenerator struct {
	// Client is the PocketID admin-API client (real or fake). Reuses the
	// same PocketIDClient interface defined in owner.go.
	Client PocketIDClient

	// NodeName identifies the homelab firstnode this break-glass account
	// belongs to. Required.
	NodeName string

	// PocketIDURL is the public origin of the PocketID instance, used to
	// build SetupURL. Example: "https://id.example.com" (no trailing slash).
	PocketIDURL string

	// OwnersGroup is the name of the group the break-glass admin is added
	// to. Defaults to "owners" when empty.
	OwnersGroup string

	// TokenTTL controls how long the one-time-access token remains valid.
	// Defaults to 365 days when zero.
	TokenTTL time.Duration
}

type BreakGlassSection struct {
	PocketIDAdmin       PocketIDAdminPayload        `yaml:"pocketidAdmin"`
	TinyAuthStatic      TinyAuthStaticPayload       `yaml:"tinyauthStatic"`
	BackupEncryptionKey *BackupEncryptionKeyPayload `yaml:"backupEncryptionKey,omitempty"`
}

type BundleBuilder struct {
	// NodeName identifies the homelab node and drives the bundle's
	// filename ("break-glass-<nodename>.age"). Required.
	NodeName string

	// Hostname is the node's network hostname (FQDN or short name); a
	// purely-documentation field but useful during recovery for matching
	// the bundle to physical hardware.
	Hostname string

	// ClusterRole is one of "main", "worker", or "storage". Required.
	ClusterRole string

	// PocketIDURL is the public origin of the PocketID instance, mirrored
	// into the bundle so the recovery operator knows which install this
	// belongs to.
	PocketIDURL string

	// PocketIDAdmin is the Layer-1 break-glass credential from Task 7.
	// Required.
	PocketIDAdmin *BreakGlassCredential

	// TinyAuthStatic is the Layer-2 break-glass credential from Task 8.
	// Required.
	TinyAuthStatic *TinyAuthStaticCredential

	// BackupEncryptionKey escrows the Kopia repository passphrase used by
	// the snapshot repository. Optional — only populated when snapshot
	// encryption is enabled. nil leaves the BackupEncryptionKey field out of the
	// emitted YAML entirely (yaml:"...,omitempty").
	BackupEncryptionKey *BackupEncryptionKeyCredential

	// BundleDir is the directory the .age and .txt files are written to.
	// Defaults to "/var/lib/stackkit/recovery" when empty.
	BundleDir string

	// Now is injectable for deterministic tests. Defaults to time.Now.
	Now func() time.Time
}

type BundleNode struct {
	Name        string `yaml:"name"`
	Hostname    string `yaml:"hostname"`
	ClusterRole string `yaml:"clusterRole"` // "main"|"worker"|"storage"
	PocketIDURL string `yaml:"pocketidUrl"`
}

type BundlePaths struct {
	// EncryptedPath is the .age file. This is the disaster-recovery
	// artifact that must be backed up out-of-band; it is safe to copy
	// to cloud storage, USB sticks, paper QR codes, etc.
	EncryptedPath string

	// PlaintextPath is the .txt file (mode 0600). Convenience-only — a
	// root-on-the-node operator can read it without redecrypting. Lives
	// next to the encrypted file in the bundle directory.
	PlaintextPath string
}

type BundlePayload struct {
	Version             int               `yaml:"version"`
	GeneratedAt         string            `yaml:"generatedAt"`
	Node                BundleNode        `yaml:"node"`
	BreakGlass          BreakGlassSection `yaml:"breakGlass"`
	RestoreInstructions string            `yaml:"restoreInstructions"`
}

type HomeAccessProof struct {
	HumanSession     string `json:"humanSession"`
	DeviceCredential string `json:"deviceCredential"`
	DPoP             string `json:"dpop"`
}

type HomeAuthentication struct {
	Subject   string    `json:"subject"`
	Device    string    `json:"device"`
	ExpiresAt time.Time `json:"expiresAt"`
}

type HomeConfirmation struct {
	JWKThumbprint string `json:"jkt"`
}

type HomeDevice struct {
	ID           string     `json:"id"`
	Name         string     `json:"name"`
	OwnerSubject string     `json:"ownerSubject"`
	SerialNumber string     `json:"serialNumber"`
	EnrolledAt   time.Time  `json:"enrolledAt"`
	NotAfter     time.Time  `json:"notAfter"`
	Revoked      bool       `json:"revoked"`
	RevokedAt    *time.Time `json:"revokedAt,omitempty"`
}

type HomeDeviceIssuer func(ctx context.Context, csrPEM []byte, ttlSeconds int) ([]byte, error)

type HomeEnrollmentBootstrap struct {
	EnrollmentURL string `json:"enrollmentUrl"`
	TLSServerName string `json:"tlsServerName"`
	CARootSHA256  string `json:"caRootSha256"`
}

type HomeEnrollmentGrant struct {
	OwnerSubject         string
	DeviceKeyThumbprint  string
	DeviceCommonName     string
	CSRDER               []byte
	PairingExpiresAt     time.Time
	CredentialTTLSeconds int
}

type HomeEnrollmentRequest struct {
	Code   string
	CSRPEM []byte
	LAN    bool
}

type HomeOverlayNode struct {
	InterfaceName       string `json:"interfaceName"`
	PublicKey           string `json:"publicKey"`
	Address             string `json:"address"`
	ListenPort          int    `json:"listenPort"`
	KeepaliveSeconds    int    `json:"persistentKeepaliveSeconds"`
	PrivateKeyInCustody bool   `json:"privateKeyInLocalCustody"`
}

type HomeOverlayPeer struct {
	DeviceID  string `json:"deviceId"`
	PublicKey string `json:"publicKey"`
	Address   string `json:"address"`
}

type HomePairing struct {
	Code      string    `json:"code"`
	ExpiresAt time.Time `json:"expiresAt"`
}

type HomePocketIDTrust struct {
	Issuer   string             `json:"issuer"`
	ClientID string             `json:"clientId"`
	Subject  string             `json:"subject"`
	Keys     jose.JSONWebKeySet `json:"keys"`
}

type HomePublicTrust struct {
	Schema                        string                                  `json:"schema"`
	HomeSiteRef                   string                                  `json:"homeSiteRef"`
	PublicOrigin                  string                                  `json:"publicOrigin"`
	DeviceAuthorityRef            string                                  `json:"deviceAuthorityRef"`
	DeviceIssuer                  string                                  `json:"deviceIssuer"`
	DeviceAudiences               []string                                `json:"deviceAudiences"`
	DeviceKeySetRef               string                                  `json:"deviceKeySetRef"`
	DeviceCredentialTTLSeconds    int                                     `json:"deviceCredentialTTLSeconds"`
	DeviceSessionTTLSeconds       int                                     `json:"deviceSessionTTLSeconds"`
	HumanSessionTTLSeconds        int                                     `json:"humanSessionTTLSeconds"`
	RevocationMaxStalenessSeconds int                                     `json:"revocationMaxStalenessSeconds"`
	PartitionDenied               bool                                    `json:"partitionDenied"`
	PocketID                      HomePocketIDTrust                       `json:"pocketId"`
	DeviceKeys                    jose.JSONWebKeySet                      `json:"deviceKeys"`
	RevokedCredentialIDs          []string                                `json:"revokedCredentialIds"`
	RevokedSubjects               []string                                `json:"revokedSubjects"`
	IssuedAt                      time.Time                               `json:"issuedAt"`
	ExpiresAt                     time.Time                               `json:"expiresAt"`
	Signature                     localevidence.OwnerPolicyStateSignature `json:"signature"`
}

type OwnerProvisioner struct {
	// Client is the PocketID admin-API client (real or fake).
	Client PocketIDClient

	// PocketIDURL is the public origin of the PocketID instance, used to
	// build SetupURL. Example: "https://id.example.com" (no trailing slash).
	PocketIDURL string

	// OwnersGroup is the name of the group new owners are added to.
	// Defaults to "owners" when empty.
	OwnersGroup string
}

type OwnerSpec struct {
	// Source controls the provisioning path. This local provisioner supports
	// "local" only; "cloud" is handled by TechStack/kombify Cloud.
	Source string

	// Email is the owner's address (also used as the WebAuthn account label).
	Email string

	// Username is the PocketID login handle.
	Username string

	// DisplayName is what PocketID renders in the UI; defaults to Username
	// when empty. PocketID v2 stores this in the FirstName column on the
	// underlying user record.
	DisplayName string

	// ForeignSubjectID is the external IdP subject for Source=="cloud".
	// Ignored when Source=="local".
	ForeignSubjectID string
}

type PocketIDAdminPayload struct {
	Username   string `yaml:"username"`
	SetupToken string `yaml:"setupToken"`
	SetupURL   string `yaml:"setupUrl"`
	Group      string `yaml:"group"`
	UserID     string `yaml:"userId"`
}

type PocketIDClient interface {
	CreateUser(ctx context.Context, req pocketid.CreateUserRequest) (*pocketid.User, error)
	AddUserToGroup(ctx context.Context, userID, groupID string) error
	GetGroupIDByName(ctx context.Context, groupName string) (string, error)
	CreateOneTimeAccessToken(ctx context.Context, userID string, ttl time.Duration) (string, error)
}

type ProvisionResult struct {
	// UserID is the PocketID-assigned UUID for the new owner record.
	UserID string

	// SetupURL is the one-time link the owner clicks to enroll a WebAuthn
	// credential. It embeds a single-use token with a 24-hour TTL. Local
	// source only.
	SetupURL string
}

type TinyAuthStaticCredential struct {
	// Username is the synthetic local handle of the form
	// "bg-<nodename>-static". Distinct from the PocketID break-glass
	// username so logs/audit can tell the two layers apart.
	Username string

	// PasswordPlain is the human-typeable password (base64 of 32 random
	// bytes). Goes into the recovery bundle; never logged.
	PasswordPlain string

	// PasswordBcrypt is the bcrypt hash of PasswordPlain. Goes into the
	// TinyAuth container env via ToEnvValue.
	PasswordBcrypt string
}

type TinyAuthStaticGenerator struct {
	// NodeName identifies the homelab firstnode this credential belongs
	// to. Required.
	NodeName string

	// BcryptCost is the bcrypt cost factor. Defaults to 12 when zero.
	// Tests may pass a lower value to keep the suite fast.
	BcryptCost int
}

type TinyAuthStaticPayload struct {
	Username       string `yaml:"username"`
	PasswordPlain  string `yaml:"passwordPlain"`
	PasswordBcrypt string `yaml:"passwordBcrypt"`
}