sdk

package
v0.0.0-...-a502854 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 13, 2025 License: Apache-2.0 Imports: 15 Imported by: 0

Documentation

Index

Constants

View Source
const (
	RouteHealth = "/healthz"

	// Authentication endpoints
	RouteV1Login              = "/v1/login"
	RouteV1Logout             = "/v1/logout"
	RouteV1Refresh            = "/v1/refresh"
	RouteV1Register           = "/v1/register"
	RouteV1VerifyEmail        = "/v1/verify-email"
	RouteV1ResendVerification = "/v1/resend-verification"
	RouteV1ForgotPassword     = "/v1/forgot-password"
	RouteV1ResetPassword      = "/v1/reset-password"

	// OAuth/SSO endpoints
	RouteV1OAuthLogin    = "/v1/oauth/login" // Individual OAuth (Google, GitHub, etc.)
	RouteV1SSOLogin      = "/v1/sso/login"   // Corporate SSO (domain-based routing)
	RouteV1OAuthLinks    = "/v1/oauth/links"
	RouteV1OAuthLink     = "/v1/oauth/links/{providerID}"
	RouteV1OAuthCallback = "/v1/oauth/callback"

	// OAuth provider configuration (authenticated)
	RouteV1OAuthProviders      = "/v1/oauth/providers"
	RouteV1OAuthProvider       = "/v1/oauth/providers/{providerID}"
	RouteV1OAuthSupportedTypes = "/v1/oauth/supported-types" // Public endpoint
)

API route constants shared between server and SDK clients

Variables

This section is empty.

Functions

This section is empty.

Types

type CreateOIDCProviderRequest

type CreateOIDCProviderRequest struct {
	ProviderName             string   `json:"provider_name"`
	IssuerURL                string   `json:"issuer_url"`
	ClientID                 string   `json:"client_id,omitempty"`     // Optional: for manual registration
	ClientSecret             string   `json:"client_secret,omitempty"` // Optional: for manual registration
	AccessToken              string   `json:"access_token,omitempty"`  // Optional: for authenticated dynamic registration
	Scopes                   []string `json:"scopes,omitempty"`
	Enabled                  bool     `json:"enabled"`
	AllowedDomains           []string `json:"allowed_domains"`
	AutoCreateUsers          bool     `json:"auto_create_users"`
	RequireEmailVerification bool     `json:"require_email_verification"`
}

CreateOIDCProviderRequest represents the request to create an OIDC provider

func (*CreateOIDCProviderRequest) Validate

func (r *CreateOIDCProviderRequest) Validate() error

Validate validates the create OIDC provider request

type CreateUserRequest

type CreateUserRequest struct {
	Email    string    `json:"email"`
	TenantID uuid.UUID `json:"tenant_id"`
}

CreateUserRequest represents the request to create a user

func (*CreateUserRequest) Validate

func (r *CreateUserRequest) Validate() error

Validate validates the create user request

type CreateUserResponse

type CreateUserResponse struct {
	UserID            uuid.UUID `json:"user_id"`
	Email             string    `json:"email"`
	TenantID          uuid.UUID `json:"tenant_id"`
	TemporaryPassword string    `json:"temporary_password"`
}

CreateUserResponse represents the response from creating a user

type DeleteOIDCProviderRequest

type DeleteOIDCProviderRequest struct {
	ProviderID uuid.UUID `json:"-"` // From URL parameter
}

DeleteOIDCProviderRequest represents the request to delete an OIDC provider

func (*DeleteOIDCProviderRequest) Validate

func (r *DeleteOIDCProviderRequest) Validate() error

Validate validates the delete OIDC provider request

type ForgotPasswordRequest

type ForgotPasswordRequest struct {
	Email string `json:"email"`
}

ForgotPasswordRequest represents the forgot password request body

func (*ForgotPasswordRequest) Validate

func (r *ForgotPasswordRequest) Validate() error

Validate validates the forgot password request

type ForgotPasswordResponse

type ForgotPasswordResponse struct {
	Message string `json:"message"`
}

ForgotPasswordResponse represents the forgot password response

type GRPCClient

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

GRPCClient is a gRPC client for the heimdall API

func NewGRPCClient

func NewGRPCClient(address string, opts ...GRPCClientOption) (*GRPCClient, error)

NewGRPCClient creates a new gRPC client for the heimdall API address should be in the format "host:port" (e.g., "localhost:9090")

func (*GRPCClient) Close

func (c *GRPCClient) Close() error

Close closes the gRPC connection

func (*GRPCClient) CreateUser

CreateUser creates a new user for a tenant

type GRPCClientOption

type GRPCClientOption func(*grpcClientConfig)

GRPCClientOption is a functional option for configuring the gRPC client

func WithDialOptions

func WithDialOptions(opts ...grpc.DialOption) GRPCClientOption

WithDialOptions allows setting custom gRPC dial options

func WithTimeout

func WithTimeout(timeout time.Duration) GRPCClientOption

WithTimeout sets the default timeout for gRPC calls

type GetOIDCProviderRequest

type GetOIDCProviderRequest struct {
	ProviderID uuid.UUID `json:"-"` // From URL parameter
}

GetOIDCProviderRequest represents the request to get an OIDC provider by ID

func (*GetOIDCProviderRequest) Validate

func (r *GetOIDCProviderRequest) Validate() error

Validate validates the get OIDC provider request

type HTTPClient

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

HTTPClient is an HTTP client for the heimdall API

func NewHTTPClient

func NewHTTPClient(baseURL string, logger logger, opts ...Option) (*HTTPClient, error)

NewHTTPClient creates a new heimdall API client The client automatically handles cookies for refresh token management

func (*HTTPClient) ForgotPassword

ForgotPassword initiates the password reset process

func (*HTTPClient) Health

func (c *HTTPClient) Health(ctx context.Context) (*HealthResponse, error)

Health checks the health of the heimdall API

func (*HTTPClient) Login

func (c *HTTPClient) Login(ctx context.Context, req LoginRequest) (*LoginResponse, error)

Login authenticates a user and returns an access token The refresh token is automatically stored in the client's cookie jar

func (*HTTPClient) Logout

func (c *HTTPClient) Logout(ctx context.Context) (*LogoutResponse, error)

Logout logs out the current user by clearing the refresh token cookie

func (*HTTPClient) OAuthLogin

func (c *HTTPClient) OAuthLogin(ctx context.Context, req OIDCLoginRequest) (*OIDCAuthResponse, error)

OAuthLogin initiates an OAuth login flow Returns the authorization URL that the user should be redirected to

func (*HTTPClient) RefreshToken

func (c *HTTPClient) RefreshToken(ctx context.Context) (*LoginResponse, error)

RefreshToken refreshes the access token using the refresh token cookie The refresh token cookie must have been set by a previous Login call

func (*HTTPClient) Register

func (c *HTTPClient) Register(ctx context.Context, req RegisterRequest) (*RegisterResponse, error)

Register registers a new user account

func (*HTTPClient) ResendVerification

ResendVerification resends the verification email to a user

func (*HTTPClient) ResetPassword

ResetPassword resets a user's password using the reset token

func (*HTTPClient) SetAccessToken

func (c *HTTPClient) SetAccessToken(token string)

SetAccessToken sets the access token for authenticated requests

func (*HTTPClient) VerifyEmail

func (c *HTTPClient) VerifyEmail(ctx context.Context, req VerifyEmailRequest) (*LoginResponse, error)

VerifyEmail verifies a user's email address using the verification token Returns a LoginResponse with access token on successful verification

type HealthResponse

type HealthResponse struct {
	Status string `json:"status"`
}

HealthResponse represents the health check response

type ListOIDCProvidersResponse

type ListOIDCProvidersResponse struct {
	Providers []OIDCProvider `json:"providers"`
}

ListOIDCProvidersResponse represents the response with list of OIDC providers

type ListSupportedOIDCProvidersResponse

type ListSupportedOIDCProvidersResponse struct {
	Providers []SupportedOIDCProviderType `json:"providers"`
}

ListSupportedOIDCProvidersResponse represents the response with supported provider types

type LoginRequest

type LoginRequest struct {
	Email    string `json:"email"`
	Password string `json:"password"`
}

LoginRequest represents the login request body

func (*LoginRequest) Validate

func (r *LoginRequest) Validate() error

Validate validates the login request

type LoginResponse

type LoginResponse struct {
	AccessToken string `json:"access_token"`
	TokenType   string `json:"token_type"`
	ExpiresIn   int    `json:"expires_in"` // seconds until access token expires
}

LoginResponse represents the login response Note: refresh_token is sent via HTTP-only cookie, not in JSON body

type LogoutResponse

type LogoutResponse struct {
	Message string `json:"message"`
}

LogoutResponse represents the logout response

type OIDCAuthResponse

type OIDCAuthResponse struct {
	AuthorizationURL string `json:"authorization_url"`
}

OIDCAuthResponse represents the OIDC authentication response with authorization URL

type OIDCLoginRequest

type OIDCLoginRequest struct {
	ProviderType OIDCProviderType `json:"provider_type"`
}

OIDCLoginRequest represents the individual OAuth login request body

func (*OIDCLoginRequest) Validate

func (r *OIDCLoginRequest) Validate() error

Validate validates the OIDC login request

type OIDCProvider

type OIDCProvider struct {
	ID                       uuid.UUID              `json:"id"`
	ProviderName             string                 `json:"provider_name"`
	IssuerURL                string                 `json:"issuer_url"`
	ClientID                 string                 `json:"client_id"`
	Scopes                   []string               `json:"scopes"`
	Enabled                  bool                   `json:"enabled"`
	AllowedDomains           []string               `json:"allowed_domains"`
	AutoCreateUsers          bool                   `json:"auto_create_users"`
	RequireEmailVerification bool                   `json:"require_email_verification"`
	RegistrationMethod       OIDCRegistrationMethod `json:"registration_method"`
	ClientIDIssuedAt         *time.Time             `json:"client_id_issued_at,omitempty"`
	ClientSecretExpiresAt    *time.Time             `json:"client_secret_expires_at,omitempty"`
	CreatedAt                time.Time              `json:"created_at"`
	UpdatedAt                time.Time              `json:"updated_at"`
}

OIDCProvider represents an OIDC provider configuration (includes secrets)

type OIDCProviderResponse

type OIDCProviderResponse struct {
	Provider OIDCProvider `json:"provider"`
}

OIDCProviderResponse represents the response with OIDC provider details

type OIDCProviderType

type OIDCProviderType string

OIDCProviderType represents an OIDC provider type

const (
	OIDCProviderTypeGoogle    OIDCProviderType = "google"
	OIDCProviderTypeMicrosoft OIDCProviderType = "microsoft"
	OIDCProviderTypeGitHub    OIDCProviderType = "github"
	OIDCProviderTypeOkta      OIDCProviderType = "okta"
)

func (OIDCProviderType) DisplayName

func (p OIDCProviderType) DisplayName() string

DisplayName returns a human-readable name for the provider

func (OIDCProviderType) IsValid

func (p OIDCProviderType) IsValid() bool

IsValid checks if the provider type is one of the defined valid types

func (OIDCProviderType) String

func (p OIDCProviderType) String() string

String returns the string representation of the provider type

type OIDCRegistrationMethod

type OIDCRegistrationMethod string

OIDCRegistrationMethod represents how an OIDC provider was registered

const (
	OIDCRegistrationMethodManual  OIDCRegistrationMethod = "manual"
	OIDCRegistrationMethodDynamic OIDCRegistrationMethod = "dynamic"
)

type Option

type Option func(*HTTPClient)

Option is a functional option for configuring the HTTPClient

func WithHTTPClient

func WithHTTPClient(httpClient *http.Client) Option

WithHTTPClient allows setting a custom http.Client Note: If you provide a custom client for refresh token support, ensure it has a cookie jar configured

func WithInsecureSkipVerify

func WithInsecureSkipVerify() Option

WithInsecureSkipVerify configures the client to skip TLS certificate verification This is useful for development with self-signed certificates

type RegisterRequest

type RegisterRequest struct {
	Email    string `json:"email"`
	Password string `json:"password"`
}

RegisterRequest represents the registration request body

func (*RegisterRequest) Validate

func (r *RegisterRequest) Validate() error

Validate validates the registration request

type RegisterResponse

type RegisterResponse struct {
	UserID  uuid.UUID `json:"user_id"`
	Email   string    `json:"email"`
	Message string    `json:"message"`
}

RegisterResponse represents the registration response

type ResendVerificationRequest

type ResendVerificationRequest struct {
	Email string `json:"email"`
}

ResendVerificationRequest represents the resend verification email request body

func (*ResendVerificationRequest) Validate

func (r *ResendVerificationRequest) Validate() error

Validate validates the resend verification request

type ResendVerificationResponse

type ResendVerificationResponse struct {
	Message string `json:"message"`
}

ResendVerificationResponse represents the response from resending verification email

type ResetPasswordRequest

type ResetPasswordRequest struct {
	Token       string `json:"token"`
	NewPassword string `json:"new_password"`
}

ResetPasswordRequest represents the reset password request body

func (*ResetPasswordRequest) Validate

func (r *ResetPasswordRequest) Validate() error

Validate validates the reset password request

type ResetPasswordResponse

type ResetPasswordResponse struct {
	Message string `json:"message"`
}

ResetPasswordResponse represents the reset password response

type SSOLoginRequest

type SSOLoginRequest struct {
	Email string `json:"email"`
}

SSOLoginRequest represents the corporate SSO login request body

func (*SSOLoginRequest) Validate

func (r *SSOLoginRequest) Validate() error

Validate validates the SSO login request

type SupportedOIDCProviderType

type SupportedOIDCProviderType struct {
	Type        OIDCProviderType `json:"type"`
	DisplayName string           `json:"display_name"`
}

SupportedOIDCProviderType represents a supported OAuth provider type

type UpdateOIDCProviderRequest

type UpdateOIDCProviderRequest struct {
	ProviderID               uuid.UUID `json:"-"`                                    // From URL parameter, not JSON body
	ProviderName             *string   `json:"provider_name,omitempty"`              // Optional: update display name
	ClientSecret             *string   `json:"client_secret,omitempty"`              // Optional: rotate secret
	Scopes                   []string  `json:"scopes,omitempty"`                     // Optional: nil = keep, [] = clear, non-empty = update
	Enabled                  *bool     `json:"enabled,omitempty"`                    // Optional: update enabled status
	AllowedDomains           []string  `json:"allowed_domains,omitempty"`            // Optional: nil = keep, non-nil = update
	AutoCreateUsers          *bool     `json:"auto_create_users,omitempty"`          // Optional: update auto-create users flag
	RequireEmailVerification *bool     `json:"require_email_verification,omitempty"` // Optional: update email verification requirement
}

UpdateOIDCProviderRequest represents the request to update an OIDC provider All fields are optional pointers to support partial updates

func (*UpdateOIDCProviderRequest) Validate

func (r *UpdateOIDCProviderRequest) Validate() error

Validate validates the update OIDC provider request

type User

type User struct {
	ID       uuid.UUID `json:"id"`
	TenantID uuid.UUID `json:"tenant_id"`
	Email    string    `json:"email"`
	Status   string    `json:"status"`
}

User represents a user in API responses

type VerifyEmailRequest

type VerifyEmailRequest struct {
	Token string `json:"token"`
}

VerifyEmailRequest represents the email verification request body

func (*VerifyEmailRequest) Validate

func (r *VerifyEmailRequest) Validate() error

Validate validates the verify email request

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL