accountlinking

type Account = account.Account

type AccountLinkedPayload struct {
	UserID       string    `json:"user_id"`
	AccountID    string    `json:"account_id"`
	Provider     string    `json:"provider"`
	ProviderID   string    `json:"provider_id"`
	ActorSubject string    `json:"actor_subject,omitempty"`
	Timestamp    time.Time `json:"timestamp"`
}

type AccountLinking interface {
	// LinkAccount securely attaches an external provider account to a target User.
	// It participates in a Store transaction, enforces caller authorization, prevents
	// silent merging across distinct users (detecting collisions), and emits audit events.
	LinkAccount(ctx context.Context, in LinkAccountInput) (*account.Account, error)

	// UnlinkAccount detaches an external provider account from a User by provider and providerID.
	// Fails with ErrCannotUnlinkFinalAuthMethod if this is the user's sole authentication method
	// unless AllowOrphan is explicitly enabled.
	UnlinkAccount(ctx context.Context, in UnlinkAccountInput) error

	// UnlinkAccountByID detaches an external provider account from a User by Core Account ID.
	// Enforces ownership and final authentication method protection.
	UnlinkAccountByID(ctx context.Context, in UnlinkAccountByIDInput) error

	// CreateLinkingTicket issues a single-use, time-limited, cryptographically random ticket
	// for two-step linking flows (e.g. initiating linking in session, completing after OAuth/WebAuthn redirect).
	CreateLinkingTicket(ctx context.Context, in CreateTicketInput) (*LinkingTicketResult, error)

	// CompleteLinkingTicket redeems a linking ticket, validating expiration, single-use redemption,
	// and provider restrictions, before linking the account within a Store transaction.
	CompleteLinkingTicket(ctx context.Context, in CompleteTicketInput) (*account.Account, error)

	// GetLinkingTicket inspects a linking ticket by its plain token without consuming it.
	GetLinkingTicket(ctx context.Context, ticketToken string) (*LinkingTicket, error)

	// RevokeLinkingTicket cancels an active linking ticket before expiration.
	RevokeLinkingTicket(ctx context.Context, ticketToken string) error

	// ListLinkedAccounts returns all authentication accounts currently attached to a user.
	ListLinkedAccounts(ctx context.Context, userID string) ([]*account.Account, error)

	// GetAccount retrieves a specific linked account by provider and provider ID.
	GetAccount(ctx context.Context, provider, providerID string) (*account.Account, error)

	// CanUnlinkAccount evaluates whether the specified account can be safely unlinked
	// without leaving the user without any authentication methods.
	CanUnlinkAccount(ctx context.Context, userID, accountID string) (bool, error)
}

type AccountUnlinkedPayload struct {
	UserID       string    `json:"user_id"`
	AccountID    string    `json:"account_id"`
	Provider     string    `json:"provider"`
	ProviderID   string    `json:"provider_id"`
	ActorSubject string    `json:"actor_subject,omitempty"`
	Timestamp    time.Time `json:"timestamp"`
}

type CompleteTicketInput struct {
	// TicketToken is the unhashed token issued during CreateLinkingTicket.
	TicketToken string `json:"ticket_token"`

	// Provider identifies the authentication provider being linked.
	Provider string `json:"provider"`

	// ProviderID identifies the user within the provider.
	ProviderID string `json:"provider_id"`

	// Metadata contains optional provider claims.
	Metadata map[string]string `json:"metadata,omitempty"`
}

type Config struct {
	// DefaultTicketTTL is the default validity duration for linking tickets. Defaults to 15 minutes.
	DefaultTicketTTL time.Duration

	// AllowOrphanByDefault controls whether removing the final authentication method is allowed by default. Defaults to false.
	AllowOrphanByDefault bool

	// Clock provides time abstraction for deterministic testing. Defaults to time.Now().UTC.
	Clock func() time.Time
}

type CreateTicketInput struct {
	// UserID identifies the authenticated User initiating the linking flow.
	UserID string `json:"user_id"`

	// TargetProvider restricts the ticket to a specific provider if specified (optional).
	TargetProvider string `json:"target_provider,omitempty"`

	// TTL defines the ticket expiration window. Defaults to plugin configuration if zero.
	TTL time.Duration `json:"ttl,omitempty"`

	// Metadata holds arbitrary state to roundtrip with the ticket (e.g. redirect URI).
	Metadata map[string]string `json:"metadata,omitempty"`
}

type LinkAccountInput struct {
	// UserID identifies the canonical Core User.
	UserID string `json:"user_id"`

	// Provider identifies the authentication provider (e.g. "google", "github", "passkey", "password").
	Provider string `json:"provider"`

	// ProviderID identifies the user uniquely inside the provider (e.g. subject, sub, email, or credential ID).
	ProviderID string `json:"provider_id"`

	// Metadata contains optional provider-specific claims or attributes.
	Metadata map[string]string `json:"metadata,omitempty"`
}

type LinkFailedPayload struct {
	UserID       string    `json:"user_id"`
	Provider     string    `json:"provider"`
	ProviderID   string    `json:"provider_id"`
	Reason       string    `json:"reason"`
	ActorSubject string    `json:"actor_subject,omitempty"`
	Timestamp    time.Time `json:"timestamp"`
}

type LinkingTicket struct {
	ID             string            `json:"id"`
	TokenHash      string            `json:"token_hash"`
	UserID         string            `json:"user_id"`
	TargetProvider string            `json:"target_provider,omitempty"`
	Metadata       map[string]string `json:"metadata,omitempty"`
	ConsumedAt     *time.Time        `json:"consumed_at,omitempty"`
	ExpiresAt      time.Time         `json:"expires_at"`
	CreatedAt      time.Time         `json:"created_at"`
}

type LinkingTicketResult struct {
	// TicketID is the internal identifier.
	TicketID string `json:"ticket_id"`

	// TicketToken is the unhashed bearer token to present when completing the linking ceremony.
	TicketToken string `json:"ticket_token"`

	// UserID is the bound user ID.
	UserID string `json:"user_id"`

	// TargetProvider is the optional restricted provider.
	TargetProvider string `json:"target_provider,omitempty"`

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

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

type Option func(*Config)

type Principal = auth.Principal

type TicketCreatedPayload struct {
	TicketID       string    `json:"ticket_id"`
	UserID         string    `json:"user_id"`
	TargetProvider string    `json:"target_provider,omitempty"`
	ExpiresAt      time.Time `json:"expires_at"`
	ActorSubject   string    `json:"actor_subject,omitempty"`
	Timestamp      time.Time `json:"timestamp"`
}

type UnlinkAccountByIDInput struct {
	// UserID identifies the target canonical Core User.
	UserID string `json:"user_id"`

	// AccountID identifies the specific Core Account record to delete.
	AccountID string `json:"account_id"`

	// AllowOrphan overrides the lockout protection, permitting removal of the user's sole remaining auth method.
	AllowOrphan bool `json:"allow_orphan,omitempty"`
}

type UnlinkAccountInput struct {
	// UserID identifies the target canonical Core User.
	UserID string `json:"user_id"`

	// Provider identifies the authentication provider to unlink.
	Provider string `json:"provider"`

	// ProviderID identifies the account to unlink within the provider.
	ProviderID string `json:"provider_id"`

	// AllowOrphan overrides the lockout protection, permitting removal of the user's sole remaining auth method.
	AllowOrphan bool `json:"allow_orphan,omitempty"`
}

type UnlinkFailedPayload struct {
	UserID       string    `json:"user_id"`
	AccountID    string    `json:"account_id,omitempty"`
	Provider     string    `json:"provider,omitempty"`
	ProviderID   string    `json:"provider_id,omitempty"`
	Reason       string    `json:"reason"`
	ActorSubject string    `json:"actor_subject,omitempty"`
	Timestamp    time.Time `json:"timestamp"`
}

type User = user.User