auth

type APIKey struct {
	// ID is the unique identifier for the API key (UUID).
	ID string `json:"id"`
	// Name is a human-readable name for the API key (required).
	Name string `json:"name"`
	// Description is an optional description of the API key's purpose.
	Description string `json:"description,omitempty"`
	// Role determines the API key's permissions.
	Role Role `json:"role"`
	// WorkspaceAccess restricts access to selected workspaces.
	// Nil is treated as all-workspaces for backward compatibility.
	WorkspaceAccess *WorkspaceAccess `json:"workspace_access,omitempty"`
	// AllowedSurfaces controls which public interfaces accept this key.
	// Empty is treated as REST API and MCP for backward compatibility.
	AllowedSurfaces []APIKeySurface `json:"allowed_surfaces,omitempty"`
	// AttributionClass determines whether the key is user-owned or a service account.
	AttributionClass APIKeyAttributionClass `json:"attribution_class,omitempty"`
	// OwnerUserID is populated when AttributionClass is user_owned.
	OwnerUserID string `json:"owner_user_id,omitempty"`
	// OwnerUsername is populated when AttributionClass is user_owned.
	OwnerUsername string `json:"owner_username,omitempty"`
	// ServiceAccountID is populated when AttributionClass is service_account.
	ServiceAccountID string `json:"service_account_id,omitempty"`
	// ServiceAccountName is populated when AttributionClass is service_account.
	ServiceAccountName string `json:"service_account_name,omitempty"`
	// MigratedAsServiceAccount is true when a legacy key had no attribution class
	// and was defaulted to service_account.
	MigratedAsServiceAccount bool `json:"migrated_as_service_account,omitempty"`
	// KeyHash is the bcrypt hash of the API key secret.
	// Excluded from JSON serialization for security.
	KeyHash string `json:"-"`
	// KeyDigest is the versioned digest used for API key lookup.
	// Excluded from JSON serialization for security.
	KeyDigest string `json:"-"`
	// KeyPrefix stores the first 8 characters of the key for identification.
	KeyPrefix string `json:"key_prefix"`
	// CreatedAt is the timestamp when the API key was created.
	CreatedAt time.Time `json:"created_at"`
	// UpdatedAt is the timestamp when the API key was last modified.
	UpdatedAt time.Time `json:"updated_at"`
	// CreatedBy is the user ID of the admin who created the API key.
	CreatedBy string `json:"created_by"`
	// LastUsedAt is the timestamp when the API key was last used for authentication.
	LastUsedAt *time.Time `json:"last_used_at,omitempty"`
}

type APIKeyAttributionClass string

type APIKeyForStorage struct {
	ID                       string                 `json:"id"`
	Name                     string                 `json:"name"`
	Description              string                 `json:"description,omitempty"`
	Role                     Role                   `json:"role"`
	WorkspaceAccess          *WorkspaceAccess       `json:"workspace_access,omitempty"`
	AllowedSurfaces          []APIKeySurface        `json:"allowed_surfaces,omitempty"`
	AttributionClass         APIKeyAttributionClass `json:"attribution_class,omitempty"`
	OwnerUserID              string                 `json:"owner_user_id,omitempty"`
	OwnerUsername            string                 `json:"owner_username,omitempty"`
	ServiceAccountID         string                 `json:"service_account_id,omitempty"`
	ServiceAccountName       string                 `json:"service_account_name,omitempty"`
	MigratedAsServiceAccount bool                   `json:"migrated_as_service_account,omitempty"`
	KeyHash                  string                 `json:"key_hash"`
	KeyDigest                string                 `json:"key_digest,omitempty"`
	KeyPrefix                string                 `json:"key_prefix"`
	CreatedAt                time.Time              `json:"created_at"`
	UpdatedAt                time.Time              `json:"updated_at"`
	CreatedBy                string                 `json:"created_by"`
	LastUsedAt               *time.Time             `json:"last_used_at,omitempty"`
}

type APIKeyStore interface {
	// Create stores a new API key.
	// Returns ErrAPIKeyAlreadyExists if an API key with the same name exists.
	Create(ctx context.Context, key *APIKey) error

	// GetByID retrieves an API key by its unique ID.
	// Returns ErrAPIKeyNotFound if the API key does not exist.
	GetByID(ctx context.Context, id string) (*APIKey, error)

	// GetByDigest retrieves an API key by its credential digest.
	// Returns ErrAPIKeyNotFound if the API key does not exist.
	GetByDigest(ctx context.Context, digest string) (*APIKey, error)

	// List returns all API keys in the store.
	List(ctx context.Context) ([]*APIKey, error)

	// Update modifies an existing API key.
	// Credential fields and a newer LastUsedAt value in storage are preserved.
	// Returns ErrAPIKeyNotFound if the API key does not exist.
	Update(ctx context.Context, key *APIKey) error

	// Delete removes an API key by its ID.
	// Returns ErrAPIKeyNotFound if the API key does not exist.
	Delete(ctx context.Context, id string) error

	// PromoteDigest atomically assigns a credential digest to an API key.
	// Repeating the promotion with the same digest is idempotent.
	PromoteDigest(ctx context.Context, id, digest string) error

	// UpdateLastUsed records recent API key use without persisting more than once per minute.
	UpdateLastUsed(ctx context.Context, id string) error
}

type APIKeySurface string

type AuthorizationSyncResult struct {
	// User is the current stored user.
	User *User
	// Changed reports whether the synchronization modified authorization.
	Changed bool
	// PreviousRole is the role observed immediately before synchronization.
	PreviousRole Role
	// PreviousWorkspaceAccess is the workspace policy observed immediately before synchronization.
	PreviousWorkspaceAccess *WorkspaceAccess
}

type AuthorizationSyncUserStore interface {
	UserStore

	// SyncAuthorization updates role and, when non-nil, workspace access on an enabled user.
	// It returns the current user and the authorization state observed under the same lock.
	SyncAuthorization(ctx context.Context, id string, role Role, workspaceAccess *WorkspaceAccess) (AuthorizationSyncResult, error)
}

type Role string

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

type TokenSecretProvider interface {
	Resolve(ctx context.Context) (TokenSecret, error)
}

type User struct {
	// ID is the unique identifier for the user (UUID).
	ID string `json:"id"`
	// Username is the unique login name.
	Username string `json:"username"`
	// PasswordHash is the bcrypt hash of the password.
	// Excluded from JSON serialization for security.
	PasswordHash string `json:"-"`
	// Role determines the user's permissions.
	Role Role `json:"role"`
	// WorkspaceAccess restricts access to selected workspaces.
	// Nil is treated as all-workspaces for backward compatibility.
	WorkspaceAccess *WorkspaceAccess `json:"workspace_access,omitempty"`
	// CreatedAt is the timestamp when the user was created.
	CreatedAt time.Time `json:"created_at"`
	// UpdatedAt is the timestamp when the user was last modified.
	UpdatedAt time.Time `json:"updated_at"`

	// AuthProvider indicates how the user authenticates.
	// Empty string is treated as "builtin" for backward compatibility.
	AuthProvider string `json:"auth_provider,omitempty"`
	// OIDCIssuer is the OIDC provider issuer URL (set when AuthProvider is "oidc").
	OIDCIssuer string `json:"oidc_issuer,omitempty"`
	// OIDCSubject is the unique subject identifier from the OIDC provider.
	OIDCSubject string `json:"oidc_subject,omitempty"`
	// TrustedProxySource identifies the proxy identity source.
	TrustedProxySource string `json:"trusted_proxy_source,omitempty"`
	// TrustedProxyUser is the opaque identity supplied by the authenticating proxy.
	TrustedProxyUser string `json:"trusted_proxy_user,omitempty"`
	// IsDisabled indicates if the user account is disabled.
	// Disabled users cannot log in.
	IsDisabled bool `json:"is_disabled,omitempty"`
	// PasswordChangedAt records when the password was last changed.
	// Tokens issued before this time are rejected. Nil means never changed.
	PasswordChangedAt *time.Time `json:"password_changed_at,omitempty"`
}

type UserForStorage struct {
	ID                 string           `json:"id"`
	Username           string           `json:"username"`
	PasswordHash       string           `json:"password_hash"`
	Role               Role             `json:"role"`
	WorkspaceAccess    *WorkspaceAccess `json:"workspace_access,omitempty"`
	CreatedAt          time.Time        `json:"created_at"`
	UpdatedAt          time.Time        `json:"updated_at"`
	AuthProvider       string           `json:"auth_provider,omitempty"`
	OIDCIssuer         string           `json:"oidc_issuer,omitempty"`
	OIDCSubject        string           `json:"oidc_subject,omitempty"`
	TrustedProxySource string           `json:"trusted_proxy_source,omitempty"`
	TrustedProxyUser   string           `json:"trusted_proxy_user,omitempty"`
	IsDisabled         bool             `json:"is_disabled,omitempty"`
	PasswordChangedAt  *time.Time       `json:"password_changed_at,omitempty"`
}

type UserPatch struct {
	Username        *string
	Role            *Role
	WorkspaceAccess *WorkspaceAccess
	PasswordHash    *string
	IsDisabled      *bool
}

type UserStore interface {
	// Create stores a new user.
	// Returns ErrUserAlreadyExists if a user with the same username exists.
	Create(ctx context.Context, user *User) error

	// GetByID retrieves a user by their unique ID.
	// Returns ErrUserNotFound if the user does not exist.
	GetByID(ctx context.Context, id string) (*User, error)

	// GetByUsername retrieves a user by their username.
	// Returns ErrUserNotFound if the user does not exist.
	GetByUsername(ctx context.Context, username string) (*User, error)

	// GetByOIDCIdentity retrieves a user by their OIDC identity (issuer + subject).
	// Returns ErrOIDCIdentityNotFound if no user exists with the given OIDC identity.
	GetByOIDCIdentity(ctx context.Context, issuer, subject string) (*User, error)

	// GetByTrustedProxyIdentity retrieves a user by their proxy identity source and user.
	// Returns ErrTrustedProxyIdentityNotFound if no user exists with the given identity.
	GetByTrustedProxyIdentity(ctx context.Context, source, user string) (*User, error)

	// List returns all users in the store.
	List(ctx context.Context) ([]*User, error)

	// Update modifies an existing user.
	// Returns ErrUserNotFound if the user does not exist.
	Update(ctx context.Context, user *User) error

	// Patch atomically applies the non-nil fields in patch to an existing user.
	// Returns the stored user after the update.
	Patch(ctx context.Context, id string, patch UserPatch) (*User, error)

	// Delete removes a user by their ID.
	// Returns ErrUserNotFound if the user does not exist.
	Delete(ctx context.Context, id string) error

	// Count returns the total number of users.
	Count(ctx context.Context) (int64, error)
}

type Webhook struct {
	// ID is the unique identifier for the webhook (UUID).
	ID string `json:"id"`
	// DAGName is the file name of the DAG this webhook triggers.
	// This serves as a unique constraint - one webhook per DAG.
	DAGName string `json:"dagName"`
	// TokenHash is the bcrypt hash of the webhook token secret.
	// Excluded from JSON serialization for security.
	TokenHash string `json:"-"`
	// TokenPrefix stores the first 8 characters of the token for identification.
	TokenPrefix string `json:"tokenPrefix"`
	// Enabled indicates whether the webhook is active.
	Enabled bool `json:"enabled"`
	// CreatedAt is the timestamp when the webhook was created.
	CreatedAt time.Time `json:"createdAt"`
	// UpdatedAt is the timestamp when the webhook was last modified.
	UpdatedAt time.Time `json:"updatedAt"`
	// CreatedBy is the user ID of the admin who created the webhook.
	CreatedBy string `json:"createdBy"`
	// LastUsedAt is the timestamp when the webhook was last triggered.
	LastUsedAt *time.Time `json:"lastUsedAt,omitempty"`
	// AuthMode controls which request authentication mode the webhook uses.
	AuthMode WebhookAuthMode `json:"-"`
	// HMACEnforcementMode controls whether HMAC failures block requests when HMAC is enabled.
	HMACEnforcementMode WebhookHMACEnforcementMode `json:"-"`
	// HMACSecret is stored decrypted in memory and encrypted at rest.
	HMACSecret string `json:"-"`
	// HMACSecretGeneratedAt records when the HMAC secret was last generated.
	HMACSecretGeneratedAt *time.Time `json:"-"`
}

type WebhookAuthMode string

type WebhookForStorage struct {
	ID                    string                     `json:"id"`
	DAGName               string                     `json:"dagName"`
	TokenHash             string                     `json:"tokenHash"`
	TokenPrefix           string                     `json:"tokenPrefix"`
	Enabled               bool                       `json:"enabled"`
	CreatedAt             time.Time                  `json:"createdAt"`
	UpdatedAt             time.Time                  `json:"updatedAt"`
	CreatedBy             string                     `json:"createdBy"`
	LastUsedAt            *time.Time                 `json:"lastUsedAt,omitempty"`
	AuthMode              WebhookAuthMode            `json:"authMode,omitempty"`
	HMACEnforcementMode   WebhookHMACEnforcementMode `json:"hmacEnforcementMode,omitempty"`
	HMACSecretEnc         string                     `json:"hmacSecretEnc,omitempty"`
	HMACSecretGeneratedAt *time.Time                 `json:"hmacSecretGeneratedAt,omitempty"`
}

type WebhookHMACEnforcementMode string

type WebhookStore interface {
	// Create stores a new webhook.
	// Returns ErrWebhookAlreadyExists if a webhook for the DAG already exists.
	Create(ctx context.Context, webhook *Webhook) error

	// GetByID retrieves a webhook by its unique ID.
	// Returns ErrWebhookNotFound if the webhook does not exist.
	GetByID(ctx context.Context, id string) (*Webhook, error)

	// GetByDAGName retrieves the webhook for a specific DAG.
	// Returns ErrWebhookNotFound if no webhook exists for the DAG.
	GetByDAGName(ctx context.Context, dagName string) (*Webhook, error)

	// List returns all webhooks in the store.
	List(ctx context.Context) ([]*Webhook, error)

	// Update modifies an existing webhook.
	// Returns ErrWebhookNotFound if the webhook does not exist.
	Update(ctx context.Context, webhook *Webhook) error

	// Delete removes a webhook by its ID.
	// Returns ErrWebhookNotFound if the webhook does not exist.
	Delete(ctx context.Context, id string) error

	// DeleteByDAGName removes a webhook by its DAG name.
	// Returns ErrWebhookNotFound if no webhook exists for the DAG.
	DeleteByDAGName(ctx context.Context, dagName string) error

	// UpdateLastUsed updates the LastUsedAt timestamp for a webhook.
	// This is called when the webhook is triggered.
	UpdateLastUsed(ctx context.Context, id string) error
}

type WorkspaceAccess struct {
	All    bool             `json:"all"`
	Grants []WorkspaceGrant `json:"grants,omitempty"`
}

type WorkspaceGrant struct {
	Workspace string `json:"workspace"`
	Role      Role   `json:"role"`
}