ott

type Config struct {
	// ExpiresIn specifies the validity duration for generated OTT tokens (default: 3 minutes).
	ExpiresIn time.Duration

	// DisableClientRequest when true rejects token generation requests originating directly from client-side HTTP callers.
	DisableClientRequest bool

	// DisableSetSessionCookie when true prevents setting the session HTTP cookie upon token verification.
	DisableSetSessionCookie bool

	// SetOttHeaderOnNewSession when true enables automatically attaching the set-ott header on new session creation.
	SetOttHeaderOnNewSession bool

	// StoreTokenMode defines token persistence security ("plain" or "hashed", default: "plain").
	StoreTokenMode StoreTokenMode

	// CustomHasher overrides the default SHA-256 base64url token hasher.
	CustomHasher HasherFunc

	// CustomGenerator overrides the default crypto/rand random token generator.
	CustomGenerator TokenGeneratorFunc
}

type GenerateTokenParams struct {
	// SessionToken is the raw token string of the active session to bind to the OTT.
	SessionToken string `json:"session_token"`

	// IsClientReq indicates whether the token generation request originated directly from a client HTTP request.
	IsClientReq bool `json:"is_client_req"`
}

type GenerateTokenResponse struct {
	// Token is the issued single-use token.
	Token string `json:"token"`
}

type HasherFunc func(token string) (string, error)

type OTTGeneratedPayload struct {
	// SessionToken is the target session token bound to the generated OTT.
	SessionToken string `json:"session_token"`

	// Token is the issued OTT token string (or hashed token representation).
	Token string `json:"token"`

	// ExpiresAt is the timestamp when the generated token expires.
	ExpiresAt time.Time `json:"expires_at"`
}

type OTTVerifiedPayload struct {
	// SessionID is the unique identifier of the active session retrieved upon verification.
	SessionID string `json:"session_id"`

	// UserID is the unique identifier of the user owning the session.
	UserID string `json:"user_id"`

	// Token is the raw OTT token string that was verified.
	Token string `json:"token"`
}

type Option func(*Config)

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

type Repository interface {
	// CreateVerificationValue stores a new OTT verification record in storage.
	CreateVerificationValue(ctx context.Context, record *VerificationRecord) error

	// ConsumeVerificationValue atomically retrieves and deletes an OTT verification record by identifier.
	// This operation MUST be atomic to protect against replay attacks and race conditions.
	ConsumeVerificationValue(ctx context.Context, identifier string) (*VerificationRecord, error)

	// GetSessionByToken retrieves an active session entity matching the specified session token string.
	GetSessionByToken(ctx context.Context, token string) (*entity.Session, error)

	// GetUserByID retrieves a user entity matching the specified user identifier.
	GetUserByID(ctx context.Context, userID string) (*entity.User, error)
}

type StoreTokenMode string

type TokenGeneratorFunc func(length int) (string, error)

type VerificationRecord struct {
	// ID is the unique database record identifier.
	ID string `json:"id"`

	// Identifier is the lookup key (e.g. "one-time-token:<stored_token>").
	Identifier string `json:"identifier"`

	// Value stores the target session token string.
	Value string `json:"value"`

	// ExpiresAt specifies the exact timestamp after which this token record is invalid.
	ExpiresAt time.Time `json:"expires_at"`

	// CreatedAt records when the token record was created.
	CreatedAt time.Time `json:"created_at"`

	// UpdatedAt records when the token record was last updated.
	UpdatedAt time.Time `json:"updated_at"`
}

type VerifyTokenParams struct {
	// Token is the raw One-Time Token string to verify and consume.
	Token string `json:"token"`
}

type VerifyTokenResponse struct {
	// Session is the retrieved active session associated with the consumed token.
	Session *entity.Session `json:"session"`

	// User is the account entity owning the active session.
	User *entity.User `json:"user"`
}