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.
	//
	// Function:
	//   Called when generating a single-use One-Time Token (OTT).
	//
	// Storage:
	//   Cache (Redis / In-Memory TTL) - Short-lived single-use OTT token.
	//
	// Arguments:
	//   - ctx: Request cancellation context.
	//   - record: VerificationRecord entity containing token identifier, session token value payload, and expiration timestamp.
	//
	// Returns:
	//   - error: Nil on success, or database error.
	//
	// Example SQL:
	//   INSERT INTO verification_tokens (id, identifier, value, expires_at, created_at, updated_at) VALUES ($1, $2, $3, $4, $5, $6);
	//
	// Example Cache (Redis):
	//   err := rdb.Set(ctx, "ott:" + record.Identifier, bytes, ttl).Err()
	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.
	//
	// Function:
	//   Called during OTT exchange endpoint to authenticate and consume the one-time token.
	//
	// Storage:
	//   Cache (Redis GETDEL / Memory) - Atomic read-and-delete single-use token consumption.
	//
	// Arguments:
	//   - ctx: Request cancellation context.
	//   - identifier: Composite token identifier key.
	//
	// Returns:
	//   - *VerificationRecord: Consumed record if found and not expired.
	//   - error: ErrInvalidToken if missing, or ErrTokenExpired if passed validity duration.
	//
	// Example SQL:
	//   DELETE FROM verification_tokens WHERE identifier = $1 AND expires_at > $2 RETURNING id, identifier, value, expires_at, created_at, updated_at;
	//
	// Example Cache (Redis):
	//   val, err := rdb.GetDel(ctx, "ott:" + identifier).Bytes()
	ConsumeVerificationValue(ctx context.Context, identifier string) (*VerificationRecord, error)

	// GetSessionByToken retrieves an active session entity matching the specified session token string.
	//
	// Function:
	//   Used after consuming an OTT token to verify and load the target session entity.
	//
	// Storage:
	//   Both (Cache-Aside Strategy) - Fast session retrieval by raw token string.
	//
	// Arguments:
	//   - ctx: Request cancellation context.
	//   - token: Raw session token string stored in OTT value.
	//
	// Returns:
	//   - *entity.Session: Active session entity if found.
	//   - error: ErrSessionNotFound if missing, or ErrSessionExpired if expired.
	//
	// Example SQL:
	//   SELECT id, user_id, token, expires_at, created_at, updated_at FROM sessions WHERE token = $1 LIMIT 1;
	//
	// Example Cache (Redis):
	//   val, err := rdb.Get(ctx, "session:" + token).Bytes()
	GetSessionByToken(ctx context.Context, token string) (*entity.Session, error)

	// GetUserByID retrieves a user entity matching the specified user identifier.
	//
	// Function:
	//   Used to verify user existence and populate user context after consuming an OTT.
	//
	// Storage:
	//   Database (GORM / SQL) - User primary key lookup.
	//
	// Arguments:
	//   - ctx: Request cancellation context.
	//   - userID: Target user primary key ID.
	//
	// Returns:
	//   - *entity.User: Matching user entity if found.
	//   - error: ErrUserNotFound if missing.
	//
	// Example SQL:
	//   SELECT id, email, name, email_verified, created_at, updated_at FROM users WHERE id = $1 LIMIT 1;
	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"`
}