deviceauth

type AuthorizeInput struct {
	// UserCode is the target user code being authorized. Required.
	UserCode string `json:"user_code"`

	// Principal identifies the authenticated user approving the request. Required.
	Principal auth.Principal `json:"principal"`

	// Scope specifies approved scopes (can be subset of requested).
	Scope string `json:"scope,omitempty"`
}

type Capability = DeviceAuthorization

type Config struct {
	VerificationURI         string
	VerificationURIComplete string
	ExpiresIn               time.Duration
	PollingInterval         time.Duration
	SlowDownIncrement       time.Duration
	MaxFailedAttempts       int
	RateLimitPerMinute      int64
}

type DenyInput struct {
	// UserCode is the target user code being denied. Required.
	UserCode string `json:"user_code"`

	// Principal identifies the authenticated user denying the request. Required.
	Principal auth.Principal `json:"principal"`
}

type DeviceAuthAuthorizedPayload struct {
	GrantID      string    `json:"grant_id"`
	ClientID     string    `json:"client_id"`
	UserCode     string    `json:"user_code"`
	UserID       string    `json:"user_id"`
	AuthorizedAt time.Time `json:"authorized_at"`
}

type DeviceAuthConsumedPayload struct {
	GrantID    string    `json:"grant_id"`
	ClientID   string    `json:"client_id"`
	UserID     string    `json:"user_id"`
	ConsumedAt time.Time `json:"consumed_at"`
}

type DeviceAuthDeniedPayload struct {
	GrantID  string    `json:"grant_id"`
	ClientID string    `json:"client_id"`
	UserCode string    `json:"user_code"`
	DeniedAt time.Time `json:"denied_at"`
}

type DeviceAuthStartedPayload struct {
	GrantID         string    `json:"grant_id"`
	ClientID        string    `json:"client_id"`
	UserCode        string    `json:"user_code"`
	ExpiresAt       time.Time `json:"expires_at"`
	PollingInterval int       `json:"polling_interval"`
	CreatedAt       time.Time `json:"created_at"`
}

type DeviceAuthorization interface {
	// Start initiates the device flow and returns device and user codes.
	Start(ctx context.Context, in DeviceAuthorizationRequestInput) (*DeviceAuthorizationResponse, error)

	// Poll checks device authorization status and issues tokens upon user approval.
	Poll(ctx context.Context, in PollInput) (*PollResponse, error)

	// VerifyUserCode inspects a user code submitted by the user on the verification page.
	VerifyUserCode(ctx context.Context, in VerifyUserCodeInput) (*UserCodeVerificationResult, error)

	// Authorize records user consent and associates the grant with the authorizing user.
	Authorize(ctx context.Context, in AuthorizeInput) error

	// Deny records user rejection of the authorization request.
	Deny(ctx context.Context, in DenyInput) error
}

type DeviceAuthorizationRequestInput struct {
	// ClientID identifies the client application running on the device. Required.
	ClientID string `json:"client_id"`

	// Scope indicates the requested permission scopes.
	Scope string `json:"scope,omitempty"`

	// Metadata carries optional device or client properties (e.g. model, OS).
	Metadata map[string]string `json:"metadata,omitempty"`
}

type DeviceAuthorizationResponse struct {
	// DeviceCode is the high-entropy verification code for device polling.
	DeviceCode string `json:"device_code"`

	// UserCode is the human-friendly code entered by the user on the verification page.
	UserCode string `json:"user_code"`

	// VerificationURI is the web URL where the end user enters the UserCode.
	VerificationURI string `json:"verification_uri"`

	// VerificationURIComplete is the optional URL containing pre-filled user_code.
	VerificationURIComplete string `json:"verification_uri_complete,omitempty"`

	// ExpiresIn is the lifetime in seconds for the device_code and user_code.
	ExpiresIn int `json:"expires_in"`

	// Interval is the minimum polling interval in seconds that the device must respect.
	Interval int `json:"interval"`
}

type DeviceGrant struct {
	ID              string            `json:"id"`
	ClientID        string            `json:"client_id"`
	DeviceCodeHash  string            `json:"device_code_hash"`
	UserCode        string            `json:"user_code"`
	Status          DeviceStatus      `json:"status"`
	UserID          string            `json:"user_id,omitempty"`
	Scope           string            `json:"scope,omitempty"`
	Metadata        map[string]string `json:"metadata,omitempty"`
	ExpiresAt       time.Time         `json:"expires_at"`
	LastPolledAt    *time.Time        `json:"last_polled_at,omitempty"`
	PollingInterval int               `json:"polling_interval"`
	FailedAttempts  int               `json:"failed_attempts"`
	AuthorizedAt    *time.Time        `json:"authorized_at,omitempty"`
	ConsumedAt      *time.Time        `json:"consumed_at,omitempty"`
	CreatedAt       time.Time         `json:"created_at"`
	UpdatedAt       time.Time         `json:"updated_at"`
}

type DeviceStatus string

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

type Option func(*Config)

type PollInput struct {
	// DeviceCode is the secret code issued to the device. Required.
	DeviceCode string `json:"device_code"`

	// ClientID is the client application ID. Required.
	ClientID string `json:"client_id"`

	// Session holds optional metadata (IP address, User Agent) recorded with the created session.
	Session auth.SessionOptions `json:"session,omitempty"`
}

type PollResponse struct {
	// Status indicates the current lifecycle status of the authorization request.
	Status DeviceStatus `json:"status"`

	// UserID is the subject identifier of the authorizing user when Status == StatusAuthorized or StatusConsumed.
	UserID string `json:"user_id,omitempty"`

	// Session is the newly established session when authorization is fulfilled.
	Session *session.Session `json:"session,omitempty"`

	// Token is the plaintext session token returned exactly once upon successful completion.
	Token string `json:"token,omitempty"`
}

type UserCodeVerificationResult struct {
	// GrantID is the internal grant identifier.
	GrantID string `json:"grant_id"`

	// ClientID is the client requesting authorization.
	ClientID string `json:"client_id"`

	// UserCode is the normalized user code.
	UserCode string `json:"user_code"`

	// Scope indicates requested permissions.
	Scope string `json:"scope,omitempty"`

	// Metadata contains additional context for display.
	Metadata map[string]string `json:"metadata,omitempty"`

	// ExpiresAt is the expiration instant.
	ExpiresAt time.Time `json:"expires_at"`
}

type VerifyUserCodeInput struct {
	// UserCode is the code entered by the user. Required.
	UserCode string `json:"user_code"`

	// ClientIP is the caller's IP address used for rate limiting brute-force protection.
	ClientIP string `json:"client_ip,omitempty"`
}