application

type AuthRequest struct {
	AuthURL      string
	State        string
	CodeVerifier string
	Nonce        string
	Provider     string
}

type AuthResult struct {
	AccessToken  string
	RefreshToken string
	IDToken      string
	TokenType    string
	ExpiresIn    int
	UserInfo     UserInfo
}

type AuthServiceOption func(*DefaultAuthenticationService)

type AuthenticationService interface {
	// InitiateAuthFlow generates PKCE parameters and returns the authorization URL.
	InitiateAuthFlow(ctx context.Context, provider string, redirectURI string) (*AuthRequest, error)

	// ExchangeCode exchanges an authorization code for tokens (server-to-server).
	ExchangeCode(ctx context.Context, code string, codeVerifier string, provider string, redirectURI string) (*AuthResult, error)

	// ValidateState verifies the OAuth state parameter matches the stored state.
	ValidateState(ctx context.Context, receivedState string, storedState string) error

	// FindOrCreateAgent looks up an agent by provider credentials, creates if not found.
	// For new users, a personal Account is also created with the agent as owner.
	FindOrCreateAgent(ctx context.Context, userInfo UserInfo) (*entities.Agent, *entities.Credential, *entities.Account, error)

	// RegisterPassword creates a new Agent + personal Account + Credential
	// (provider="password") + PasswordCredential. Returns ErrEmailAlreadyTaken
	// when a password credential for the email already exists.
	RegisterPassword(ctx context.Context, email, displayName, plaintext string) (*entities.Agent, *entities.Credential, *entities.Account, error)

	// VerifyPassword authenticates an email + plaintext pair against a stored
	// PasswordCredential and returns the associated Agent, Credential and
	// (optional) personal Account on success. To prevent account enumeration,
	// both wrong-password and unknown-email cases return ErrInvalidPassword.
	VerifyPassword(ctx context.Context, email, plaintext string) (*entities.Agent, *entities.Credential, *entities.Account, error)

	// ImportPasswordCredential imports an already-hashed legacy bcrypt blob
	// against a caller-supplied agentID/accountID. Idempotent on
	// (provider="password", lower(email)). Used for bulk migration where
	// existing foreign keys must remain valid. Pass ImportWithSalt(salt)
	// for legacy systems that applied an extra application-layer salt
	// suffix on top of bcrypt.
	ImportPasswordCredential(ctx context.Context, email, displayName, bcryptHash, agentID, accountID string, opts ...ImportOption) error

	// UpdatePassword rotates the stored password for the given agent.
	// Verifies oldPlaintext before applying the change.
	UpdatePassword(ctx context.Context, agentID, oldPlaintext, newPlaintext string) error

	// IssueIdentityToken issues a signed JWT for the given agent.
	// Returns ("", nil) if no JWTService is configured.
	IssueIdentityToken(ctx context.Context, agent *entities.Agent, activeAccountID string) (string, error)

	// RefreshIdentityToken re-snapshots claims for an existing agent and
	// returns a freshly signed JWT. Re-runs the ClaimsEnricher and
	// re-fetches subscription state — unlike TokenReissuer.ReissueToken,
	// which copies existing extras + subscription verbatim. Takes an
	// agent ID instead of doing an OAuth round-trip or password verify,
	// so the caller owns the trust decision (typically: validated a
	// still-valid session/JWT before calling). Use after a server-side
	// change that affects authorization claims (subscription purchased,
	// role granted, feature flag flipped). Returns ErrJWTServiceNotConfigured
	// when no JWTService is wired (a misconfiguration if you reached
	// this method) — distinct from IssueIdentityToken's ("", nil) shape,
	// which exists to support opaque-session-only flows that refresh
	// does not.
	RefreshIdentityToken(ctx context.Context, agentID string, activeAccountID string) (string, error)

	// CreateSession creates an authenticated session for an agent.
	CreateSession(ctx context.Context, agentID string, credentialID string, ipAddress string, userAgent string, duration time.Duration) (*entities.AuthSession, error)

	// ValidateSession validates and returns session info.
	ValidateSession(ctx context.Context, sessionID string) (*SessionInfo, error)

	// RefreshTokens refreshes OAuth tokens for a credential.
	RefreshTokens(ctx context.Context, credentialID string) (*AuthResult, error)

	// RevokeSession revokes an active session.
	RevokeSession(ctx context.Context, sessionID string) error

	// RevokeAllSessions revokes all sessions for an agent.
	RevokeAllSessions(ctx context.Context, agentID string) error
}

type AuthorizationChecker interface {
	// IsAuthorized checks whether the given agent is authorized to perform
	// the specified action on the target resource.
	// It evaluates all applicable policies, considering:
	// - Direct agent permissions
	// - Role-based permissions (via agent's assigned roles)
	// - Prohibitions (which override permissions per ODRL semantics)
	IsAuthorized(ctx context.Context, agentID, action, target string) (bool, error)

	// IsAuthorizedInAccount checks whether the given agent is authorized within
	// a specific account context. It considers:
	// - Direct agent permissions
	// - Global role-based permissions (via agent's assigned roles)
	// - Account-scoped role-based permissions (via agent's role in the account)
	// - Prohibitions (which override permissions per ODRL semantics)
	IsAuthorizedInAccount(ctx context.Context, agentID, accountID, action, target string) (bool, error)

	// GetPermissions returns all effective permissions for the given agent,
	// including permissions inherited through role assignments.
	GetPermissions(ctx context.Context, agentID string) ([]Permission, error)

	// GetProhibitions returns all effective prohibitions for the given agent,
	// including prohibitions inherited through role assignments.
	GetProhibitions(ctx context.Context, agentID string) ([]Permission, error)
}

type ClaimsEnricher func(ctx context.Context, agent *entities.Agent, accounts []*entities.Account, activeAccountID string) (map[string]any, error)

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

type ImportOption func(*importConfig)

type InviteClaims struct {
	jwt.RegisteredClaims
	InviteID string `json:"invite_id"`
}

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

type InviteServiceOption func(*InviteService)

type InviteTokenService interface {
	// IssueInviteToken creates a signed JWT for the given invite.
	IssueInviteToken(ctx context.Context, inviteID string, expiry time.Duration) (string, error)

	// ValidateInviteToken parses and validates an invite token string, returning the claims.
	ValidateInviteToken(ctx context.Context, tokenString string) (*InviteClaims, error)
}

type JWTService interface {
	// IssueToken creates a signed JWT for the given agent and accounts.
	// A non-nil subscription is embedded as the "subscription" claim;
	// nil omits the claim. extras adds app-specific top-level claims;
	// nil/empty omits any extras. Reserved claim names in extras must
	// be rejected with a wrapped ErrReservedClaim.
	IssueToken(ctx context.Context, agent *entities.Agent, accounts []*entities.Account, activeAccountID string, subscription *auth.SubscriptionClaim, extras map[string]any) (string, error)

	// ValidateToken parses and validates a JWT string, returning the claims.
	// Non-reserved top-level claims are exposed via PericarpClaims.Extras.
	ValidateToken(ctx context.Context, tokenString string) (*PericarpClaims, error)
}

type Logger interface {
	Info(ctx context.Context, msg string, keysAndValues ...interface{})
	Warn(ctx context.Context, msg string, keysAndValues ...interface{})
	Error(ctx context.Context, msg string, keysAndValues ...interface{})
}

type NoOpLogger struct{}

type OAuthProvider interface {
	// Name returns the provider identifier (e.g., "google", "github").
	Name() string

	// AuthCodeURL generates the authorization URL with PKCE parameters.
	AuthCodeURL(state string, codeChallenge string, nonce string, redirectURI string) string

	// Exchange exchanges an authorization code for tokens.
	Exchange(ctx context.Context, code string, codeVerifier string, redirectURI string) (*AuthResult, error)

	// RefreshToken refreshes an access token using a refresh token.
	RefreshToken(ctx context.Context, refreshToken string) (*AuthResult, error)

	// RevokeToken revokes a token at the provider.
	RevokeToken(ctx context.Context, token string) error

	// ValidateIDToken validates the ID token and extracts user claims.
	ValidateIDToken(ctx context.Context, idToken string, nonce string) (*UserInfo, error)
}

type OAuthProviderRegistry map[string]OAuthProvider

type PericarpClaims struct {
	jwt.RegisteredClaims
	AgentID         string                  `json:"agent_id"`
	AccountIDs      []string                `json:"account_ids"`
	ActiveAccountID string                  `json:"active_account_id,omitempty"`
	Subscription    *auth.SubscriptionClaim `json:"subscription,omitempty"`
	Extras          map[string]any          `json:"-"`
}

type Permission struct {
	Assignee string // Agent or Role ID that holds this permission
	Action   string // ODRL action IRI (e.g., odrl:read)
	Target   string // Asset/resource identifier or wildcard "*"
}

type PermissionStore interface {
	// GetPermissionsForAssignee returns all permissions for a specific assignee (agent or role).
	GetPermissionsForAssignee(ctx context.Context, assigneeID string) ([]Permission, error)

	// GetProhibitionsForAssignee returns all prohibitions for a specific assignee.
	GetProhibitionsForAssignee(ctx context.Context, assigneeID string) ([]Permission, error)

	// GetRolesForAgent returns all global role IDs currently assigned to the given agent.
	GetRolesForAgent(ctx context.Context, agentID string) ([]string, error)

	// GetRolesForAgentInAccount returns role IDs assigned to the agent within a specific account.
	GetRolesForAgentInAccount(ctx context.Context, agentID, accountID string) ([]string, error)
}

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

type SessionInfo struct {
	SessionID   string
	AgentID     string
	AccountID   string
	Permissions []Permission
	ExpiresAt   time.Time
}

type SubscriptionService interface {
	GetSubscription(ctx context.Context, agentID, accountID string) (*auth.SubscriptionClaim, error)
}

type TokenReissuer interface {
	ReissueToken(ctx context.Context, claims *PericarpClaims, activeAccountID string) (string, error)
}

type TokenStore interface {
	// StoreTokens stores OAuth tokens for a credential.
	StoreTokens(ctx context.Context, credentialID string, accessToken, refreshToken, idToken string, expiresAt time.Time) error

	// GetTokens retrieves stored OAuth tokens for a credential.
	GetTokens(ctx context.Context, credentialID string) (accessToken, refreshToken string, expiresAt time.Time, err error)

	// DeleteTokens removes all stored tokens for a credential.
	DeleteTokens(ctx context.Context, credentialID string) error

	// NeedsRefresh checks if the stored access token needs refreshing.
	NeedsRefresh(ctx context.Context, credentialID string) (bool, error)
}

type UserInfo struct {
	ProviderUserID string
	Email          string
	DisplayName    string
	AvatarURL      string
	Provider       string
}