service

type AllStatements interface {
	ManagedIDGenerator
	ProjectStatements
	FlowDefinitionStatements
	CryptoKeyStatements
	JSONSchemaStatements
	EnvironmentStatements
	TeamStatements
	TeamMembershipStatements
	TokenStatements
	SessionStatements
	AuthAttemptStatements
	UserStatements
	UserPasswordStatements
	UserTOTPStatements
	UserPasskeyStatements
	UserRecoveryCodesStatements
	BrandingStatements
	ClaimStatements
	ResourceScopeStatements
	AuthzAssignmentStatements
	AuthzMembershipEdgeStatements
	AuthzCatalogStatements
	AuthzResolverStatements
	EventStatements
	Statements
}

type AuthAttemptService interface {
	// Create and store a new auth attempt.
	//
	// If input.SessionID is set, the existing session's verified checks are copied
	// into the attempt for step-up authentication against an existing session.
	//
	// If input.RequiredChecks are nil, the project's default required checks are used.
	//
	// errors: domain.ErrAuthAttemptInvalidRequest, domain.ErrInternal
	Create(ctx context.Context, input CreateAuthAttemptInput) (*domain.AuthAttempt, error)

	// GetByID retrieves an auth attempt including all factors and challenges by its ID.
	//
	// errors: domain.ErrAuthAttemptNotFound, domain.ErrInternal
	GetByID(ctx context.Context, projectID, attemptID string) (*domain.AuthAttempt, error)

	// IssueChallenge creates and returns a new challenge for the given check type.
	// An existing challenge of the same type will be overwritten.
	//
	// For passkey challenges, the user check must already be verified, so the user ID is known
	// for retrieving registered credentials.
	//
	// errors: domain.ErrAuthAttemptNotFound, domain.ErrAuthAttemptInvalidRequest, domain.ErrAuthAttemptInvalidState, domain.ErrAuthAttemptAlreadyHandedOff, domain.ErrInternal
	IssueChallenge(ctx context.Context, input IssueChallengeInput) (*domain.AuthAttempt, error)

	// VerifyProof verifies the submitted proof against the challenge identified by ChallengeID.
	//
	// On success, it persists the verification and marks the attempt complete if all
	// required checks are now satisfied.
	//
	// On failure, it records the failed attempt for rate-limiting purposes.
	//
	// The ChallengeID must match the ID returned by IssueChallenge to prevent use of
	// stale proofs after a challenge is re-issued.
	//
	// errors: domain.ErrAuthAttemptNotFound, domain.ErrAuthAttemptStaleChallenge, domain.ErrAuthAttemptInvalidRequest, domain.ErrAuthAttemptProofRejected, domain.ErrAuthAttemptInvalidState, domain.ErrAuthAttemptAlreadyHandedOff, domain.ErrInternal
	VerifyProof(ctx context.Context, input VerifyProofInput) (*domain.AuthAttempt, error)

	// Handoff mints a single-use handoff token for a completed attempt.
	//
	// The client exchanges the token at POST /sessions/exchange to create
	// a new session or add factors to an existing session.
	//
	// The attempt must be in a completed state and not expired.
	//
	// errors: domain.ErrAuthAttemptNotFound, domain.ErrAuthAttemptInvalidState, domain.ErrAuthAttemptNotCompleted, domain.ErrAuthAttemptAlreadyHandedOff, domain.ErrInternal
	Handoff(ctx context.Context, input HandoffInput) (*domain.AuthAttempt, error)

	// BeginPasskeyEnrollment starts a management-plane enrollment ceremony on
	// an internal attempt: the target user is pinned as a verified user
	// factor and a registration challenge is issued. RegistrationID is the
	// internal attempt's id, but the attempt is invisible on the attempt
	// surface — internal attempts cannot be read, handed off, or exchanged.
	//
	// errors: domain.ErrAuthAttemptInvalidRequest, domain.ErrInternal
	BeginPasskeyEnrollment(ctx context.Context, input BeginPasskeyEnrollmentInput) (*BeginPasskeyEnrollmentOutput, error)

	// FinishPasskeyEnrollment verifies the attestation against the ceremony
	// and persists the credential; the internal attempt is consumed in the
	// same transaction, so a completed ceremony cannot be replayed and no
	// best-effort cleanup is needed.
	//
	// errors: domain.ErrAuthAttemptNotFound, domain.ErrAuthAttemptStaleChallenge, domain.ErrAuthAttemptInvalidRequest, domain.ErrAuthAttemptProofRejected, domain.ErrInternal
	FinishPasskeyEnrollment(ctx context.Context, input FinishPasskeyEnrollmentInput) (*FinishPasskeyEnrollmentOutput, error)
}

type AuthAttemptStatements interface {
	Statements
	CreateAuthAttempt(ctx context.Context, entity *domain.AuthAttempt) error
	GetAuthAttemptByID(ctx context.Context, projectID, authAttemptID string) (*domain.AuthAttempt, error)
	GetAuthAttemptByHandoffToken(ctx context.Context, projectID string, handoffToken []byte) (*domain.AuthAttempt, error)
	DeleteAuthAttemptByID(ctx context.Context, projectID, authAttemptID string) error
	HandoffAuthAttempt(ctx context.Context, attempt *domain.AuthAttempt) error
	SetAuthAttemptChallenge(ctx context.Context, projectID, authAttemptID string, challenge domain.AuthChallenge) error
	// SetAuthAttemptFactor upserts a verified factor directly, without a
	// challenge/proof cycle: the caller has already established the fact by
	// other means (e.g. the user row was just created in the same transaction).
	// An existing check row of the same type is overwritten and its challenge
	// state cleared. Returns the check row's id for audit emits.
	SetAuthAttemptFactor(ctx context.Context, projectID, authAttemptID string, factor domain.AuthFactor) (checkID string, err error)
	AuthAttemptChallengeSucceeded(ctx context.Context, projectID, authAttemptID string, factor domain.AuthFactor, challengeID string) error
	AuthAttemptChallengeFailed(ctx context.Context, projectID, authAttemptID string, challenge domain.AuthChallenge) error
}

type AuthzAssignmentStatements interface {
	Statements
	CreateAuthzAssignment(ctx context.Context, assignment *domain.AuthzAssignment) error
	GetAuthzAssignment(ctx context.Context, projectID, id string) (*domain.AuthzAssignment, error)
	ListAuthzAssignments(ctx context.Context, projectID string, principalType domain.AuthzPrincipalType, principalID string, includeRevoked bool) ([]*domain.AuthzAssignment, error)
	RevokeAuthzAssignment(ctx context.Context, projectID, id string) error
	// GetActiveOwningTeamGrant returns the project's active owning-team grant
	// (object project, relation team) or NoRowFoundError when the project is
	// unclaimed. The unique active grant is the claim source of truth
	// (ADR 046 / ADR 054 §2); at most one active row exists per project,
	// enforced by authz_assignments_one_owning_team.
	GetActiveOwningTeamGrant(ctx context.Context, projectID string) (*domain.AuthzAssignment, error)
	// ListClaimedProjectIDs returns project ids holding an active owning-team
	// grant (ADR 049 export visibility), ordered by project_id after afterID
	// (empty starts at the beginning).
	ListClaimedProjectIDs(ctx context.Context, afterID string, limit uint32) ([]string, error)
}

type AuthzCatalogStatements interface {
	Statements
	PersistCatalogVersion(ctx context.Context, meta domain.AuthzCatalogVersion, mutations compiler.CatalogMutations) error
	GetAuthzCatalog(ctx context.Context, catalogID string) (*domain.AuthzCatalog, error)
	LoadCatalogMutations(ctx context.Context, catalogID string) (compiler.PersistedCatalog, error)
}

type AuthzListFilter = domain.AuthzListObjectsParams

type AuthzMembershipEdgeStatements interface {
	Statements
	UpsertAuthzMembershipEdge(ctx context.Context, edge *domain.AuthzMembershipEdge) error
	GetAuthzMembershipEdge(ctx context.Context, key domain.AuthzMembershipEdgeKey) (*domain.AuthzMembershipEdge, error)
	ListAuthzMembershipEdgesByMember(ctx context.Context, projectID string, memberType domain.AuthzMemberType, memberID string) ([]*domain.AuthzMembershipEdge, error)
	DeleteAuthzMembershipEdges(ctx context.Context, filter database.Filter[domain.AuthzMembershipEdgeField]) error
	DeleteAuthzMembershipEdgesForTeamDeactivate(ctx context.Context, projectID, teamID string) error
}

type AuthzResolverStatements interface {
	Statements
	ActiveSystemCatalogID(ctx context.Context) (string, error)
	HasAuthzProjectFoothold(ctx context.Context, projectID string, principalType domain.AuthzPrincipalType, principalID string) (bool, error)
	CheckAuthz(ctx context.Context, params domain.AuthzCheckParams) (allowed bool, foothold bool, err error)
	ListAuthzObjectIDs(ctx context.Context, params domain.AuthzListObjectsParams) ([]string, error)
}

type BeginPasskeyEnrollmentInput struct {
	ProjectID   string
	UserID      string
	Username    string
	DisplayName string
	RPID        string
	RPOrigins   []url.URL
}

type BeginPasskeyEnrollmentOutput struct {
	// RegistrationID identifies the ceremony on finish.
	RegistrationID string
	// Options is the PublicKeyCredentialCreationOptions JSON.
	Options []byte
}

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

type BrandingStatements interface {
	Statements
	CreateBranding(ctx context.Context, entity *domain.Branding) error
	GetBrandingByID(ctx context.Context, projectID, id string) (*domain.Branding, error)
	ListBrandings(ctx context.Context, filter *database.ListOptions[domain.BrandingField]) (*database.ListResult[*domain.Branding], error)
}

type BuiltinSchemaProvider interface {
	GetBuiltinSchema(uri string) (*jsonschema.Schema, error)
	LatestSchemaURI(kind domain.KnownSchemaKind) (string, error)
}

type Challenge interface {
	ChallengeCheckType() domain.AuthCheckType
}

type ClaimCompleteResult struct {
	ProjectID string
	TeamID    string
	ClaimedAt time.Time
}

type ClaimInitResult struct {
	// ClaimURL is the browser URL the developer opens; it embeds the plaintext
	// challenge token so the browser leg never needs the project secret.
	ClaimURL string
	// ChallengeID is the plaintext challenge token the CLI polls with.
	ChallengeID string
	ExpiresAt   time.Time
}

type ClaimService interface {
	// Init mints a single-use challenge for an unclaimed project. secretHash
	// is the hex SHA-256 of the presented project-secret bearer, computed by
	// the handler; it is stored so Status can verify proof of possession.
	Init(ctx context.Context, projectID, secretHash string) (*ClaimInitResult, error)
	// Status reports the challenge state. challengeID is the plaintext token
	// from Init; secretHash must match the initiating secret's hash.
	Status(ctx context.Context, projectID, challengeID, secretHash string) (*ClaimStatusResult, error)
	// Complete spends the challenge and attaches the project to userID's
	// personal team in one transaction. userID comes from the platform-session
	// check (verifyClaimSession, C2).
	Complete(ctx context.Context, projectID, challengeID, userID string) (*ClaimCompleteResult, error)
}

type ClaimStatements interface {
	Statements
	// CreateChallenge inserts a pending claim challenge; entity.ID is the
	// SHA-256 hash of the challenge token, minted by the caller.
	CreateChallenge(ctx context.Context, entity *domain.ClaimChallenge) error
	GetChallengeByID(ctx context.Context, projectID, id string) (*domain.ClaimChallenge, error)
	// MarkChallengeCompleted flips pending -> completed; a challenge that is
	// absent, in another project, or already completed returns NoRowFoundError.
	MarkChallengeCompleted(ctx context.Context, projectID, id string) error
	// GetPersonalTeamForUser resolves the user's earliest membership as the
	// personal team and returns NoRowFoundError when that membership or its team
	// is not active. It never falls back to a later membership: a deactivated
	// personal team is not silently replaced by another team the user belongs to.
	GetPersonalTeamForUser(ctx context.Context, projectID, userID string) (*domain.Team, error)
	// GetEarliestTeamMembership returns the same earliest membership
	// GetPersonalTeamForUser resolves from, but regardless of its status and
	// without joining the team. It exists to tell apart the two states
	// GetPersonalTeamForUser deliberately collapses into NoRowFoundError:
	// a user who holds no membership at all (NoRowFoundError here too) from one
	// whose personal team is deactivated (a row with a non-active status).
	// Provisioning must create a team for the first and leave the second alone.
	GetEarliestTeamMembership(ctx context.Context, projectID, userID string) (*domain.TeamMembership, error)
}

type ClaimStatusResult struct {
	Status domain.ClaimChallengeStatus
	// TeamID, ClaimedAt, and DashboardURL are set only when Status is
	// completed, reconstructed from the grant (claim state lives in the
	// permission engine, ADR 046 §1).
	TeamID       string
	ClaimedAt    time.Time
	DashboardURL string
}

type CreateAuthAttemptInput struct {
	ProjectID string
	// SessionID is set for step-up auth against an existing session.
	SessionID *string
	// RequiredChecks overrides the project's default policy.
	// Used by the OIDC adapter (acr_values) and flow engine.
	// If nil the project's DefaultRequiredChecks are used.
	RequiredChecks []domain.AuthCheckType
	// Internal marks a server-orchestrated ceremony (see
	// [domain.AuthAttempt.Internal]). Never settable through the REST surface.
	Internal bool
}

type CreateBrandingInput struct {
	ProjectID      string
	Layout         string
	LiquidTemplate string
	LogoURL        string
	FontURL        string
	HeroURL        string
}

type CreateGrantInput struct {
	ProjectID     string
	PrincipalType domain.AuthzPrincipalType
	PrincipalID   string
	Relation      string
	ExpiresAt     *time.Time
}

type CreateSchemaByURLInput struct {
	ProjectID string
	TeamID    string
	URL       url.URL
}

type CreateSchemaInput struct {
	ProjectID string
	TeamID    string
	Schema    []byte
}

type CreateSessionInput struct {
	ProjectID string
	UserAgent *domain.UserAgent
}

type CreateTeamInput struct {
	ProjectID string
	Name      string
}

type CreateUserAction struct {
	CreateUserInput

	CreateUser *domain.CreateUser
	// contains filtered or unexported fields
}

type CreateUserInput struct {
	ProjectID string
	TeamID    *string
	// SchemaURL names the schema Attributes is validated against.
	SchemaURL string
	// Attributes is the schema-defined content only, without envelope fields.
	Attributes map[string]any
	ID         string
}

type CryptoKeyStatements interface {
	Statements
	GetEncryptionKey(ctx context.Context, filter database.Filter[domain.EncryptionKeyField]) (*domain.EncryptionKey, error)
	ListEncryptionKeys(ctx context.Context, opts *database.ListOptions[domain.EncryptionKeyField]) (*database.ListResult[*domain.EncryptionKey], error)
	CreateEncryptionKey(ctx context.Context, key *domain.EncryptionKey) error
	UpdateKey(ctx context.Context, id string, key string) error
	GetSigningKey(ctx context.Context, filter database.Filter[domain.SigningKeyField]) (*domain.SigningKey, error)
	CreateSigningKey(ctx context.Context, key *domain.SigningKey) error
}

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

type DeleteSessionInput struct {
	ProjectID string
	SessionID string
}

type DeleteUserAction struct {
	DeleteUserInput
}

type DeleteUserInput struct {
	ProjectID string
	UserID    string
}

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

type EnvironmentStatements interface {
	Statements
	CreateEnvironment(ctx context.Context, entity *domain.Environment) error
	GetEnvironmentByName(ctx context.Context, projectID, name string) (*domain.Environment, error)
	ListEnvironments(ctx context.Context, filter *database.ListOptions[domain.EnvironmentField]) (*database.ListResult[*domain.Environment], error)
}

type EventExportAdapter struct {
	Pool *DB
}

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

type EventStatements interface {
	Statements
	InsertEvent(ctx context.Context, event *domain.Event) error
	GetEventByID(ctx context.Context, projectID, id string) (*domain.Event, error)
	ListEvents(ctx context.Context, filter *database.ListOptions[domain.EventField]) (*database.ListResult[*domain.Event], error)
	// DeleteEventsOlderThan removes events with created_at before cutoff across
	// all projects (retention job; includes orphaned project_id rows).
	DeleteEventsOlderThan(ctx context.Context, createdBefore time.Time) (int64, error)
	EnsureEventSink(ctx context.Context, sink *domain.EventSink) error
	// GetEventSinkCursor returns (nil, nil) when no cursor row exists.
	GetEventSinkCursor(ctx context.Context, sinkID, projectID string) (*domain.EventSinkCursor, error)
	UpsertEventSinkCursor(ctx context.Context, cursor *domain.EventSinkCursor) error
	ListEventsAfterCursor(ctx context.Context, projectID string, afterCreatedAt time.Time, afterID string, limit uint32) ([]*domain.Event, error)
}

type ExchangeInput struct {
	ProjectID      string
	HandoffToken   string
	IdempotencyKey *string
	// TTL is optional; nil uses the configured default.
	TTL *time.Duration
}

type Filter struct {
	Field     string
	Operation string
	Value     any
}

type FinishPasskeyEnrollmentInput struct {
	ProjectID      string
	RegistrationID string
	// UserID must match the user the ceremony was begun for.
	UserID      string
	Attestation []byte
	// Name optionally labels the credential; empty derives a name.
	Name string
}

type FinishPasskeyEnrollmentOutput struct {
	PasskeyID string
	Name      string
	CreatedAt time.Time
}

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

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

type FlowDefinitionRequest struct {
	FlowDefinitionID string
	ProjectID        string
	Name             string
	Status           string
	SchemaVersion    string // todo (grvijayan): currently empty as the request does not contain schema version
	FlowSchemaURI    string // todo (grvijayan): schema_version (semver) stored in the db vs schema_uri needed for validation
	UserSchema       string
	Purposes         map[string]string
	Audience         domain.FlowDefinitionAudience
	Steps            []domain.FlowDefinitionStep
}

type FlowDefinitionService interface {
	Create(ctx context.Context, req FlowDefinitionRequest) (*domain.FlowDefinition, error)
	Update(ctx context.Context, req FlowDefinitionRequest) (*domain.FlowDefinition, error)
	Get(ctx context.Context, projectID, id string) (*domain.FlowDefinition, error)
	List(ctx context.Context, req ListFlowDefinitionsRequest) (*ListFlowDefinitionsResponse, error)
	Delete(ctx context.Context, projectID string, id string) error
}

type FlowDefinitionStatements interface {
	Statements
	CreateFlowDefinition(ctx context.Context, entity *domain.FlowDefinition) error
	GetFlowDefinitionByID(ctx context.Context, projectID, id string) (*domain.FlowDefinition, error)
	UpdateFlowDefinition(ctx context.Context, entity *domain.FlowDefinition) error
	ListFlowDefinitions(ctx context.Context, filter *database.ListOptions[domain.FlowDefinitionField]) (*database.ListResult[*domain.FlowDefinition], error)
	DeleteFlowDefinitionByID(ctx context.Context, projectID, id string) error
}

type FlowService interface {
	// Resolve returns the [domain.FlowDefinition] to run. Direct lookup
	// when Name is set; audience match otherwise.
	Resolve(ctx context.Context, req ResolveFlowRequest) (*domain.FlowDefinition, error)
	// Start mints a fresh flow on the resolved definition.
	Start(ctx context.Context, req StartFlowRequest) (domain.FlowStepResult, error)
	// Submit advances the state machine. Re-fetches the definition
	// from FlowState.DefinitionID.
	Submit(ctx context.Context, req SubmitFlowRequest) (domain.FlowStepResult, error)
	// GetStep re-emits the current step without advancing.
	GetStep(ctx context.Context, req GetFlowStepRequest) (domain.FlowStepResult, error)
}

type GetFlowStepRequest struct {
	State *domain.FlowState
}

type GetMyUserInput struct {
	// SessionToken is the parsed session token, already verified at the API
	// security boundary.
	SessionToken *domain.Token
}

type GetSessionInput struct {
	ProjectID string
	SessionID string
	// WithUserIdentity resolves the linked user's reference (ADR 058 §3)
	// onto Session.User. Set by reads that render the signed-in identity.
	WithUserIdentity bool
}

type GetUserInput struct {
	ProjectID string
	TeamID    *string
	UserID    string
}

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

type HandoffInput struct {
	ProjectID      string
	AttemptID      string
	IdempotencyKey *string
}

type IssueChallengeInput struct {
	ProjectID string
	AttemptID string
	// Challenge is a discriminated union — use one of the Challenge* types below.
	Challenge Challenge
}

type JSONSchemaQueryOptions struct {
	// LatestRevisionPerObjectType keeps only the newest revision of each
	// object_type. Rows without an object_type are revisions of nothing and
	// pass through untouched.
	LatestRevisionPerObjectType bool
}

type JSONSchemaStatements interface {
	Statements
	CreateJSONSchema(ctx context.Context, entity *domain.JSONSchema) error
	GetJSONSchemaByID(ctx context.Context, projectID, schemaID string) (*domain.JSONSchema, error)
	ListJSONSchemas(ctx context.Context, filter *database.ListOptions[domain.JSONSchemaField], opts JSONSchemaQueryOptions) (*database.ListResult[*domain.JSONSchema], error)
	DeleteJSONSchemaByID(ctx context.Context, projectID, schemaID string) error
}

type KeyService interface {
	GetEncryptionKey(ctx context.Context, keyID string, algorithm jose.ContentEncryption) (*domain.EncryptionKey, error)
	GetCrypter(ctx context.Context, keyID string, algorithm jose.ContentEncryption) (op.Crypto, error)
	GetProjectEncryptionKey(ctx context.Context, projectID string, purpose domain.EncryptionKeyPurpose) (*domain.EncryptionKey, error)
	GetProjectCrypter(ctx context.Context, projectID string, purpose domain.EncryptionKeyPurpose) (op.Crypto, error)
	GetProjectSigningKey(ctx context.Context, projectID string, purpose domain.SigningKeyPurpose) (*domain.SigningKey, error)
	GetProjectSigner(ctx context.Context, projectID string, purpose domain.SigningKeyPurpose) (jose.Signer, error)
	GetMasterKeyCrypter(ctx context.Context) (op.Crypto, error)
	MigrateToLatestMasterKey(ctx context.Context) error
}

type ListEnvironmentsInput struct {
	ProjectID string
	PageToken string
	Limit     int
}

type ListEnvironmentsOutput struct {
	Items         []*domain.Environment
	NextPageToken string
}

type ListEventsRequest struct {
	ProjectID     string
	Categories    []string
	EventTypes    []string
	ActorID       string
	ClientID      string
	SessionID     string
	FlowID        string
	RequestID     string
	Fingerprint   string
	EntityType    string
	EntityID      string
	TeamID        string
	CreatedAfter  *time.Time
	CreatedBefore *time.Time
	Order         string
	Limit         int
	PageToken     string
}

type ListEventsResponse struct {
	Events        []*domain.Event
	NextPageToken string
}

type ListFlowDefinitionsRequest struct {
	ProjectID string
	Purpose   string
	Limit     int
	PageToken string
}

type ListFlowDefinitionsResponse struct {
	Items         []*domain.FlowDefinition
	NextPageToken string
}

type ListPasskeysInput struct {
	ProjectID string
	UserID    string
	PageToken string
	Limit     int
}

type ListProjectsRequest struct {
	// ProjectID restricts results to that single project. Handlers set it from
	// the caller's scope, and every credential today is bound to one project.
	// Required.
	ProjectID string
	Limit     int
	PageToken string
	Sorting   *Sorting // optional; defaults to createdAt asc
	Filters   []Filter
}

type ListProjectsResponse struct {
	Projects      []*domain.Project
	NextPageToken string
}

type ListSchemasInput struct {
	ProjectID string
	// IDs narrows the list to the given schema ids. Empty means no id filter.
	// Not exposed on the wire: it serves in-process batch resolution, such as
	// the flow-definition expand hydrator.
	IDs        []string
	ObjectType string
	// Kind is nil when the caller did not filter by one. It is a pointer rather
	// than a zero value because JSONSchemaKindUnknown is a real stored kind, so
	// it cannot double as "no filter".
	Kind *domain.JSONSchemaKind
	// LatestRevisionPerObjectType asks for the newest revision of each object
	// type instead of the full revision history.
	LatestRevisionPerObjectType bool
	PageToken                   string
	Limit                       int
}

type ListSchemasOutput struct {
	Items         []*domain.JSONSchema
	NextPageToken string
}

type ListSessionInput struct {
	// ProjectID restricts results to that single project. Handlers set it from
	// the caller's scope. Required.
	ProjectID string
	Limit     int
	PageToken string
	Sorting   *Sorting // optional; defaults to createdAt desc (newest first)
	Filters   []Filter
}

type ListSessionsResponse struct {
	Sessions      []*domain.Session
	NextPageToken string
}

type ListTeamsRequest struct {
	// ProjectID restricts results to that project. Required: a team only has
	// meaning inside its project, so an unscoped team list is never valid.
	ProjectID string
	Limit     int
	PageToken string
	Sorting   *Sorting // optional; defaults to createdAt asc
	Filters   []Filter
}

type ListTeamsResponse struct {
	Teams         []*domain.Team
	NextPageToken string
}

type ListUserTeamsInput struct {
	ProjectID string
	UserID    string
	PageToken string
	Limit     int
}

type ListUserTeamsOutput struct {
	Items         []*domain.UserTeam
	NextPageToken string
}

type ListUsersInput struct {
	ProjectID string
	PageToken string
	Limit     int
	Sorting   *Sorting // optional; defaults to createdAt desc
	Filters   []Filter
	// IncludeTeams embeds each user's team memberships (ADR 059).
	IncludeTeams bool
	// IncludeLifecycleOwnerTeam embeds the team that owns each user's
	// lifecycle (ADR 059).
	IncludeLifecycleOwnerTeam bool
}

type ListUsersOutput struct {
	Items         []*domain.User
	NextPageToken string
}

type ManagedIDGenerator interface {
	NewManagedID(prefix string) (string, error)
}

type PasskeyChallenge struct {
	UserVerification string
	RPID             string
	RPOrigins        []url.URL
}

type PasskeyProof struct {
	AssertionResponse []byte
}

type PasskeyRegistrationChallenge struct {
	UserID      string
	Username    string
	DisplayName string
	RPID        string
	RPOrigins   []url.URL
}

type PasskeyRegistrationProof struct {
	AttestationResponse []byte
	// Name labels the credential in passkey management surfaces. Optional:
	// when empty, a name is derived from the credential itself
	// ([domain.GeneratePasskeyCredentialName]).
	Name string
	// CreateUser, when set, builds the actions that create the ceremony's
	// user inside the success transaction, so user creation, credential
	// persistence, and check success land atomically. The service invokes it
	// with the stored challenge's authoritative user handle — a caller cannot
	// create a row under a different id than the credential binds to. Only
	// consulted for provisional ceremonies.
	CreateUser func(userID string) []UserAction
}

type PasswordChallenge struct{}

type PasswordProof struct {
	Password string
}

type PersonalTeamEnsurer interface {
	// EnsurePersonalTeam is a no-op outside the platform project and for users
	// that already hold an active membership. Otherwise it creates the team
	// and its membership in one transaction.
	EnsurePersonalTeam(ctx context.Context, projectID, userID string) error
}

type Pool interface {
	Transactioner[AllStatements]
	Statementer[AllStatements]
}

type ProjectService interface {
	// Create generates a new project with server-minted secrets and persists it.
	// If seedDefaults is true, server fallback schema and flow resources are
	// created with the project for non-CLI creation paths.
	// Returns the stored project including timestamps.
	Create(ctx context.Context, name string, previewOrigins []string, seedDefaults bool) (*domain.Project, error)

	// CreateWithID is Create under a caller-supplied id, for the one project
	// whose id the server owns rather than mints: the platform project
	// (domain.PlatformProjectID). Reports the same already-exists error as
	// Create when the id is taken.
	CreateWithID(ctx context.Context, id, name string, previewOrigins []string, seedDefaults bool) (*domain.Project, error)

	// Get retrieves a project by ID.
	// Returns [database.NoRowFoundError] when no project with the given ID exists.
	Get(ctx context.Context, id string) (*domain.Project, error)

	// DefaultProject resolves the transitional standalone default retained by
	// Console ADR 0004 §2's bootstrap cutover rule: the configured project when
	// cfgProjectID is set — which must exist; a missing configured project is a
	// configuration error — otherwise the deployment's first-created
	// project. Returns (nil, nil) while no project exists yet: the server
	// never creates the default project, the customer's integration
	// (`zitadel setup` → POST /projects) does.
	DefaultProject(ctx context.Context, cfgProjectID string) (*domain.Project, error)

	// Update updates the name of a project.
	// Returns domain.ErrProjectMissingID or domain.ErrProjectNameInvalid for validation failures.
	// Returns domain.ErrProjectNotFound when no project with the given ID exists; other failures return domain.ErrInternal.
	Update(ctx context.Context, id, name string) (*domain.Project, error)

	// List returns projects matching the request, ordered and paginated with an
	// opaque cursor token. The returned NextPageToken is empty when the last page
	// has been reached.
	// Returns domain.ErrProjectMissingID when the request carries no project.
	List(ctx context.Context, req ListProjectsRequest) (*ListProjectsResponse, error)

	// Delete hard-deletes a project, cascading to its child resources through the
	// storage delete. Deleting a project that does not exist is a no-op.
	Delete(ctx context.Context, id string) error
}

type ProjectStatements interface {
	Statements
	CreateProject(ctx context.Context, entity *domain.Project) error
	GetProjectByID(ctx context.Context, id string) (*domain.Project, error)
	UpdateProject(ctx context.Context, entity *domain.Project) error
	ListProjects(ctx context.Context, filter *database.ListOptions[domain.ProjectField]) (*database.ListResult[*domain.Project], error)
	// DeleteProjectByID removes the project. changed is false when no row matched.
	DeleteProjectByID(ctx context.Context, id string) (changed bool, err error)
}

type Proof interface {
	// contains filtered or unexported methods
}

type ResolveFlowHint struct {
	AppID        *string
	TeamID       *string
	UserSchemaID *string
}

type ResolveFlowRequest struct {
	ProjectID     string
	Purpose       domain.FlowDefinitionPurpose
	Name          *string // direct-lookup slug
	SchemaVersion *string // nil = latest active
	AuthRequestID *string
	// Hint scopes audience resolution (ignored when Name is set) — see
	// resolveByAudience for the scoring rules.
	Hint ResolveFlowHint
}

type ResourceScopeStatements interface {
	Statements
	UpsertResourceScope(ctx context.Context, scope *domain.ResourceScope) error
	GetResourceScope(ctx context.Context, resourceID string) (*domain.ResourceScope, error)
	GetResourceScopeInProject(ctx context.Context, kind domain.ResourceKind, projectID, resourceID string) (*domain.ResourceScope, error)
	GetResourceScopeByIDInProject(ctx context.Context, projectID, resourceID string) (*domain.ResourceScope, error)
	ExistsResourceScopeElsewhere(ctx context.Context, kind domain.ResourceKind, resourceID, excludeProjectID string) (bool, error)
	DeleteResourceScope(ctx context.Context, kind domain.ResourceKind, projectID, resourceID string) error
}

type SchemaGetter interface {
	GetSchema(ctx context.Context, projectID string, teamID string, schemaID string) (*domain.JSONSchema, error)
}

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

type SessionConfig struct {
	DefaultTTL time.Duration `mapstructure:"default_ttl"`
	MaxTTL     time.Duration `mapstructure:"max_ttl"`
}

type SessionResolver interface {
	Get(ctx context.Context, projectID, sessionID string) (*domain.Session, error)
}

type SessionService interface {
	Create(ctx context.Context, input CreateSessionInput) (*domain.Session, error)
	Exchange(ctx context.Context, input ExchangeInput) (*domain.Session, error)
	// Get retrieves a session by ID within a project. When the input sets
	// WithUserIdentity, the linked user's resolved reference (ADR 058 §3) is
	// hydrated onto Session.User (absent users degrade to a session without
	// a ref). errors: domain.ErrSessionNotFound, domain.ErrInternal
	Get(ctx context.Context, input GetSessionInput) (*domain.Session, error)
	// List returns the project's sessions matching the input's filters,
	// errors: domain.ErrProjectMissingID, domain.ErrRequestInvalid, domain.ErrNotImplemented, domain.ErrInternal
	List(ctx context.Context, input ListSessionInput) (*ListSessionsResponse, error)
	Delete(ctx context.Context, input DeleteSessionInput) error
}

type SessionStatements interface {
	Statements
	// CreateSession inserts user_agent (optional), session, and session token.
	// It wraps the multi-write steps in withTransaction.
	CreateSession(ctx context.Context, entity *domain.Session) error
	// ExchangeSession promotes verified auth-attempt checks onto a session
	// (create or upgrade), rotates the session token, and deletes the attempt.
	// It wraps the multi-write steps in withTransaction.
	// idempotencyKey is accepted for API compatibility and currently ignored.
	ExchangeSession(ctx context.Context, projectID, handoffToken string, idempotencyKey *string, ttl time.Duration) (*domain.Session, error)
	GetSessionByID(ctx context.Context, projectID, sessionID string) (*domain.Session, error)
	ListSessions(ctx context.Context, filter *database.ListOptions[domain.SessionField]) (*database.ListResult[*domain.Session], error)
	DeleteSessionByID(ctx context.Context, projectID, sessionID string) error
}

type SessionStatementsResolver struct {
	Pool StatementPool
}

type SetPasswordInput struct {
	ProjectID                string
	UserID                   string
	Password                 string
	IsPasswordChangeRequired bool
}

type SetPasswordUserAction struct {
	SetPasswordInput
	// contains filtered or unexported fields
}

type Sorting struct {
	Field     string
	Direction string
}

type StartFlowRequest struct {
	Definition    *domain.FlowDefinition
	Purpose       domain.FlowDefinitionPurpose
	RedirectURI   *string
	AuthRequestID *string
	SessionID     *string
	UserAgent     *domain.UserAgent
}

type StatementPool interface {
	Statementer[AllStatements]
	Transactioner[AllStatements]
}

type Statementer[S any] interface {
	Statements() S
}

type Statements interface {
	IsStatements()
}

type StatementsUserRefResolver struct {
	Pool StatementPool
}

type SubmitFlowRequest struct {
	State         *domain.FlowState
	Action        string
	Fields        map[string]any
	GateProofs    map[string]string
	SSOProviderID *string
	// ChallengeResponse carries the client's answer to a pending ceremony
	// (e.g. a passkey assertion). Nil unless the step issued a challenge.
	ChallengeResponse *domain.FlowChallengeResponse
	// PasskeyRP carries the WebAuthn relying-party params derived from the
	// request, needed when issuing a passkey challenge.
	PasskeyRP *domain.FlowPasskeyRP
}

type TeamMembershipStatements interface {
	Statements
	CreateTeamMembership(ctx context.Context, membership *domain.TeamMembership) error
	GetTeamMembership(ctx context.Context, projectID, teamID, userID string) (*domain.TeamMembership, error)
	ListTeamMemberships(ctx context.Context, filter *database.ListOptions[domain.TeamMembershipField]) (*database.ListResult[*domain.TeamMembership], error)
	ListUserTeams(ctx context.Context, filter *database.ListOptions[domain.UserTeamField]) (*database.ListResult[*domain.UserTeam], error)
	UpdateTeamMembershipStatus(ctx context.Context, projectID, teamID, userID string, status domain.MembershipStatus) error
}

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

type TeamStatements interface {
	Statements
	CreateTeam(ctx context.Context, entity *domain.Team) error
	GetTeamByID(ctx context.Context, projectID, id string) (*domain.Team, error)
	GetTeam(ctx context.Context, filter database.Filter[domain.TeamField]) (*domain.Team, error)
	UpdateTeam(ctx context.Context, entity *domain.Team) error
	ListTeams(ctx context.Context, filter *database.ListOptions[domain.TeamField]) (*database.ListResult[*domain.Team], error)
	// DeactivateTeam tombs the team and cascades membership/user lifecycle
	// updates. It wraps the multi-write steps in withTransaction (opens a tx
	// via Statements(), joins an outer pool.Transaction when already nested).
	//
	// Only an active team is deactivated: the team UPDATE is guarded on the status,
	// and a zero-row result skips the cascade and reports success with changed=false.
	// An unknown or already-deactivated team is therefore a no-op;
	// updated_at records when the team was first deactivated.
	DeactivateTeam(ctx context.Context, projectID, id string) (changed bool, err error)
}

type TokenService interface {
	GenerateJWE(ctx context.Context, data *domain.Token) (string, error)
	RevokeToken(ctx context.Context, projectID, tokenID string) error
	IntrospectToken(ctx context.Context, token string) (*domain.Token, error)
	GetActivePreviewToken(ctx context.Context, projectID string) (*domain.Token, error)
}

type TokenStatements interface {
	Statements
	CreateToken(ctx context.Context, entity *domain.Token) error
	GetTokenByID(ctx context.Context, projectID, tokenID string) (*domain.Token, error)
	ListTokens(ctx context.Context, filter *database.ListOptions[domain.TokenField]) (*database.ListResult[*domain.Token], error)
	DeleteTokenByID(ctx context.Context, projectID, tokenID string) error
	DeleteTokensBySessionID(ctx context.Context, projectID, sessionID string) error
}

type Transactioner[S any] interface {
	Transaction(ctx context.Context, fn func(ctx context.Context, tx Statementer[S]) error) error
}

type UpdateTeamInput struct {
	ProjectID string
	TeamID    string
	Name      *string
}

type UserAction interface {
	Prepare(ctx context.Context) error
	Apply(ctx context.Context, stmts AllStatements) error
}

type UserChallenge struct{}

type UserLookup interface {
	GetByAttributes(ctx context.Context, projectID string, attrs []domain.Attribute) (*domain.User, error)
}

type UserPasskeyStatements interface {
	Statements
	CreateUserPasskey(ctx context.Context, passkey *domain.CreateUserPasskey) error
	GetUserPasskey(ctx context.Context, filter database.Filter[domain.UserPasskeyField]) (*domain.UserPasskey, error)
	ListUserPasskeys(ctx context.Context, filter *database.ListOptions[domain.UserPasskeyField]) (*database.ListResult[*domain.UserPasskey], error)
	UpdateUserPasskey(ctx context.Context, filter database.Filter[domain.UserPasskeyField], updates ...domain.UserPasskeyUpdate) error
	DeleteUserPasskey(ctx context.Context, filter database.Filter[domain.UserPasskeyField]) error
}

type UserPasswordStatements interface {
	Statements
	SetUserPassword(ctx context.Context, pw *domain.SetUserPassword) error
	GetUserPassword(ctx context.Context, filter database.Filter[domain.UserPasswordField]) (*domain.UserPassword, error)
	ListUserPasswords(ctx context.Context, filter *database.ListOptions[domain.UserPasswordField]) (*database.ListResult[*domain.UserPassword], error)
	UpdateUserPassword(ctx context.Context, filter database.Filter[domain.UserPasswordField], updates ...domain.UserPasswordUpdate) error
	DeleteUserPassword(ctx context.Context, filter database.Filter[domain.UserPasswordField]) error
}

type UserProof struct {
	AttributeName string
	LoginName     string
}

type UserQueryOptions struct {
	// AttributeKeys limits hydrated EAV keys; empty means all attributes.
	AttributeKeys []string
	// Attributes, when non-empty, restricts to users matching all key/value pairs.
	Attributes []domain.Attribute
	// UniqueAttributesOnly restricts Attributes matching to values recorded
	// in the unique-attributes registry. Identifier lookups set it so an
	// equal value in a non-unique property of another user (for example a
	// notification address) cannot make the lookup ambiguous.
	UniqueAttributesOnly bool
	// MembershipTeamID, when set, requires an active team membership.
	MembershipTeamID *string
	// IncludeTeams hydrates each user's team memberships (ADR 059). The list is loaded
	// by a batched second query keyed on the page's ids, never by joining it
	// into the user query: a join multiplies rows, which would make LIMIT
	// count memberships instead of users and corrupt the keyset cursor.
	IncludeTeams bool
	// TeamsLimit caps how many membership entries each user carries when
	// IncludeTeams is set. Zero means [DefaultUserTeamsLimit].
	TeamsLimit int
	// IncludeLifecycleOwnerTeam hydrates the team that owns each user's
	// lifecycle (ADR 059). Like IncludeTeams it is a batched second query,
	// keyed on the distinct owner ids the page returned; self-owned users
	// contribute no id and stay nil.
	IncludeLifecycleOwnerTeam bool
}

type UserRecoveryCodesStatements interface {
	Statements
	CreateUserRecoveryCodes(ctx context.Context, codes *domain.CreateRecoveryCodes) error
	GetUserRecoveryCodes(ctx context.Context, filter database.Filter[domain.UserRecoveryCodesField]) (*domain.UserRecoveryCodes, error)
	ListUserRecoveryCodes(ctx context.Context, filter *database.ListOptions[domain.UserRecoveryCodesField]) (*database.ListResult[*domain.UserRecoveryCodes], error)
	UpdateUserRecoveryCodes(ctx context.Context, filter database.Filter[domain.UserRecoveryCodesField], updates ...domain.UserRecoveryCodesUpdate) error
	DeleteUserRecoveryCodes(ctx context.Context, filter database.Filter[domain.UserRecoveryCodesField]) error
}

type UserRefResolver interface {
	ResolveUserRefs(ctx context.Context, projectID string, userIDs []string) (map[string]domain.UserRef, error)
	// ResolveRefsForUsers resolves refs for users the caller already holds
	// fully hydrated (ADR 058 §3a) — one schema-list query, no user query.
	ResolveRefsForUsers(ctx context.Context, projectID string, users []*domain.User) (map[string]domain.UserRef, error)
}

type UserService interface {
	ApplyActions(ctx context.Context, actions ...UserAction) (err error)
	CreateUser(ctx context.Context, input CreateUserInput) (*domain.User, error)
	DeleteUser(ctx context.Context, input DeleteUserInput) error
	ListUsers(ctx context.Context, input ListUsersInput) (*ListUsersOutput, error)
	ListPasskeys(ctx context.Context, input ListPasskeysInput) (passkeys []*domain.UserPasskey, nextPage string, err error)
	ListUserTeams(ctx context.Context, input ListUserTeamsInput) (*ListUserTeamsOutput, error)
	GetUserByID(ctx context.Context, input GetUserInput) (*domain.User, error)
	SetPassword(ctx context.Context, input SetPasswordInput) (err error)
	GetMyUser(ctx context.Context, input GetMyUserInput) (*domain.User, error)
}

type UserStatements interface {
	Statements
	CreateUser(ctx context.Context, user *domain.CreateUser) error
	GetUser(ctx context.Context, filter database.Filter[domain.UserField], opts UserQueryOptions) (*domain.User, error)
	ListUsers(ctx context.Context, filter *database.ListOptions[domain.UserField], opts UserQueryOptions) (*database.ListResult[*domain.User], error)
	DeactivateUser(ctx context.Context, projectID, userID string) error
	DeleteUserByID(ctx context.Context, projectID, userID string) error
	UserExists(ctx context.Context, projectID, userID string) (bool, error)
}

type UserStatementsLookup struct {
	Pool StatementPool
}

type UserTOTPStatements interface {
	Statements
	CreateUserTOTP(ctx context.Context, totp *domain.CreateUserTOTP) error
	GetUserTOTP(ctx context.Context, filter database.Filter[domain.UserTOTPField]) (*domain.UserTOTP, error)
	ListUserTOTPs(ctx context.Context, filter *database.ListOptions[domain.UserTOTPField]) (*database.ListResult[*domain.UserTOTP], error)
	UpdateUserTOTP(ctx context.Context, filter database.Filter[domain.UserTOTPField], updates ...domain.UserTOTPUpdate) error
	DeleteUserTOTP(ctx context.Context, filter database.Filter[domain.UserTOTPField]) error
}

type VerifyProofInput struct {
	ProjectID string
	AttemptID string
	// ChallengeID must match the ID returned by IssueChallenge.
	// Prevents use of stale proofs after a challenge is re-issued.
	ChallengeID string
	// Proof is a discriminated union — use one of the Proof* types below.
	Proof Proof
}