flows

package
v0.0.52 Latest Latest
Warning

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

Go to latest
Published: Nov 20, 2026 License: MIT Imports: 38 Imported by: 0

Documentation

Overview

Package flows turns Kratos's callbacks into Backplane hooks and events: the courier's messages (hook Deliver), the before/after points of the self-service flows (hooks Before<Flow>/After<Flow>) and the facts of completed flows (events).

Index

Constants

View Source
const (
	ChangeAdded    = "added"
	ChangeRemoved  = "removed"
	ChangeReplaced = "replaced"
)

Changes of a credential.

View Source
const (
	// SelfServicePath is the prefix of Kratos's self-service endpoints the
	// deployment routes to Public, all of it: any answer under it may
	// carry a session, and every one is admitted.
	SelfServicePath = "/self-service/"
	// OIDCStartPath is the hop a sign-in with a provider takes on its way
	// there: it sets the cookie that carries the client's flow to the
	// callback. It sits under Kratos's OIDC prefix, routed here with it.
	OIDCStartPath = "/self-service/methods/oidc/backplane/start"
)
View Source
const (
	// ChannelBrowser: a session cookie.
	ChannelBrowser = "browser"
	// ChannelAPI: a session token in the flow's answer.
	ChannelAPI = "api"
	// ChannelNativeExchange: a session token from /sessions/token-exchange.
	ChannelNativeExchange = "native_exchange"
)

Channels a new session's credential leaves by.

View Source
const LogoutPath = "/self-service/logout"

LogoutPath is the prefix of Kratos's self-service logout endpoints the deployment routes to this service instead of Kratos.

View Source
const NativeFlowHeader = "X-Kratos-Flow-Id"

NativeFlowHeader names the app's flow on a session token exchange; it reaches SessionIssued unverified.

View Source
const RecordMessage = 5000002

RecordMessage is shown when a change is refused because its security event cannot be recorded.

View Source
const SessionIssuedHook = "SessionIssued"

SessionIssuedHook admits a stored session before its credential leaves.

View Source
const TokenExchangePath = "/sessions/token-exchange"

TokenExchangePath is Kratos's session token exchange, the end of a native app's browser sign-in; the deployment routes it to this service instead of Kratos.

View Source
const UnavailableMessage = 5000001

UnavailableMessage is shown when a flow hook fails and is not fail-open.

Variables

This section is empty.

Functions

func CredentialTypes added in v0.0.47

func CredentialTypes() []string

CredentialTypes are the credentials a settings flow changes, read with their configurations to tell a change from none.

Types

type DeliverIn

type DeliverIn struct {
	// Channel is "email" or "sms".
	Channel   string `json:"channel"   validate:"oneof=email sms"`
	Recipient string `json:"recipient" schemapb:"description=Address or phone number"`
	// TemplateType is Kratos's message kind, e.g. verification_code_valid,
	// recovery_code_valid, login_code_valid, registration_code_valid.
	TemplateType string `json:"template_type"`
	// Code is the one-time code the message carries, if any.
	Code string `json:"code,omitempty" schemapb:"secret=true"`
	// Link is the link the message carries (verification, recovery), if any.
	Link             string `json:"link,omitempty"               schemapb:"secret=true"`
	ExpiresInMinutes int64  `json:"expires_in_minutes,omitempty"`
	// Identity the message is about, as Kratos sends it.
	Identity json.RawMessage `json:"identity,omitempty"`
	// Data is the rest of Kratos's template data.
	Data json.RawMessage `json:"data,omitempty"`
	// Rendered is Kratos's own rendering of the message.
	Rendered Rendered `json:"rendered"`
	// TransientPayload the flow carried.
	TransientPayload json.RawMessage `json:"transient_payload,omitempty"`
}

DeliverIn is a message Kratos's courier hands over: deliver it.

type DeliverOut

type DeliverOut struct{}

DeliverOut is empty: a returned error makes Kratos retry the message.

type Deny

type Deny struct {
	Messages []Message `json:"messages"`
}

Deny stops a flow.

type FlowEvent

type FlowEvent = *kratoseventsv1.FlowEvent

FlowEvent is a completed flow: Registered, LoggedIn, SettingsChanged, Recovered, Verified.

type FlowIn

type FlowIn struct {
	// Flow is registration, login, settings, recovery or verification.
	Flow string `json:"flow"`
	// Method is the method the flow completed with (after points); "any"
	// where Kratos does not tell.
	Method string `json:"method,omitempty"`
	// FlowID and FlowType ("api" or "browser").
	FlowID   string `json:"flow_id,omitempty"`
	FlowType string `json:"flow_type,omitempty"`
	// ClientFlowID is the flow the client submitted or started, as this
	// service's proxy vouches for it. It differs from FlowID only when Kratos
	// converted the flow: an OIDC login of an unknown subject completes as a
	// new registration flow, an OIDC registration of a known one as a new
	// login flow. Empty when the request did not pass the proxy.
	ClientFlowID string `json:"client_flow_id,omitempty"`
	// Identity of the flow (after points). At AfterRegistration it is not
	// stored yet and has no id; AfterRegistrationStored has the final one.
	Identity json.RawMessage `json:"identity,omitempty"`
	// Session acting in the flow, as Kratos sends it: at BeforeSettings and
	// AfterSettings the signed-in one; after login and registration the new
	// one, which Kratos stores only after the hooks, so its id (and its
	// devices' ids) are empty there. Absent where Kratos sends none. No
	// token or cookie.
	Session          ory.Session     `json:"session,omitzero"`
	TransientPayload json.RawMessage `json:"transient_payload,omitempty"`
	RequestURL       string          `json:"request_url,omitempty"`
	RequestMethod    string          `json:"request_method,omitempty"`
	// RequestHeaders Kratos forwards (its allowlist); never cookies.
	RequestHeaders map[string]string `json:"request_headers,omitempty"`
}

FlowIn is a self-service flow at a before or after point.

type FlowOut

type FlowOut struct {
	// Deny stops the flow and shows these messages.
	Deny *Deny `json:"deny,omitempty"`
	// Identity replaces parts of the identity (registration and settings).
	Identity *IdentityPatch `json:"identity,omitempty"`
}

FlowOut is the hook's verdict: nothing lets the flow continue.

type Flows

type Flows struct {
	deps.Component
	// contains filtered or unexported fields
}

Flows declares the hooks and events and serves Kratos's callbacks.

func New

func New(parent deps.Scope, key string, failOpen config.Live[[]string], sessions Sessions, box Outbox) *Flows

New declares the hooks and events under parent; key authenticates Kratos; hooks named in failOpen let the flow continue when they fail; sessions reads Kratos's sessions and identities; box keeps the security events with what they report.

func (*Flows) BindingChanges

func (f *Flows) BindingChanges(ctx context.Context) <-chan struct{}

BindingChanges signals when the set of bound hooks changes.

func (*Flows) Bound

func (f *Flows) Bound(name string) bool

Bound reports whether a hook (short name) is bound.

func (*Flows) DeliverRef

func (f *Flows) DeliverRef() hook.Ref[DeliverIn, DeliverOut]

DeliverRef, Point and Event are the declared refs (tests, wiring code).

func (*Flows) Event

func (f *Flows) Event(flow string) event.Ref[FlowEvent]

Event is a flow's completion event.

func (*Flows) Handler

func (f *Flows) Handler() http.Handler

Handler serves the callbacks: /courier/{channel}, /hooks/{when}/{flow}/{method}, /events/{flow}/{method}.

func (*Flows) Hooks

func (f *Flows) Hooks() []string

Hooks are the declared hook names, Deliver first, SessionIssued last.

func (*Flows) LoggedOut added in v0.0.30

func (f *Flows) LoggedOut() event.Ref[FlowEvent]

LoggedOut is the event of a self-service logout.

func (*Flows) Logout added in v0.0.30

func (f *Flows) Logout(public *url.URL, headers map[string]string) http.Handler

Logout serves Kratos's logout endpoints (LogoutPath and below) in front of Kratos at public: Kratos ends the session as always, and when it has, LoggedOut is published with it. Kratos itself has no logout hooks. headers go with every request to Kratos (a proxy's authorization).

func (*Flows) Point

func (f *Flows) Point(name string) hook.Ref[FlowIn, FlowOut]

Point is a flow hook by name, e.g. AfterRegistration.

func (*Flows) Public added in v0.0.41

func (f *Flows) Public(
	public *url.URL, headers map[string]string, exchangeMaxAge time.Duration, settings config.Live[overlay.Settings],
) http.Handler

Public serves Kratos's public API in front of Kratos at public: logout, the session token exchange, the OIDC callbacks and start hop, and every other request, passed on. Every request to Kratos with a client flow carries FlowHeader for it; every session an answer issues is admitted by SessionIssued before its credential leaves. Settings and verification issue none: Kratos sets the cookie of a session that exists already. headers go with every request to Kratos; settings give the flows' lifespans and error page.

func (*Flows) SessionIssued added in v0.0.41

func (f *Flows) SessionIssued() hook.Ref[SessionIssuedIn, SessionIssuedOut]

SessionIssued is the hook that admits a new session.

func (*Flows) Stats

func (f *Flows) Stats() []Stat

Stats of every point called since start, by point.

func (*Flows) TokenExchange added in v0.0.41

func (f *Flows) TokenExchange(public *url.URL, headers map[string]string, maxAge time.Duration) http.Handler

TokenExchange serves Kratos's session token exchange in front of Kratos at public. Kratos answers a code pair again and again, at any age, even for a session that has ended; this answers only for an active session authenticated within maxAge, else 404 as for an unknown pair, and only once SessionIssued admitted the session. Answers before the session exists (a polling app) pass unchanged. headers go with every request to Kratos.

type IdentityPatch

type IdentityPatch struct {
	Traits         json.RawMessage `json:"traits,omitempty"`
	MetadataPublic json.RawMessage `json:"metadata_public,omitempty"`
	MetadataAdmin  json.RawMessage `json:"metadata_admin,omitempty"`
}

IdentityPatch replaces whole parts of an identity; absent parts stay.

type Message

type Message struct {
	// Field is the form field, e.g. "traits.email"; empty: the whole form.
	Field string `json:"field,omitempty"`
	// ID lets a UI translate the message.
	ID   int64  `json:"id,omitempty"`
	Text string `json:"text"`
	// Type is error (default), info or success.
	Type    string          `json:"type,omitempty"    validate:"omitempty,oneof=error info success"`
	Context json.RawMessage `json:"context,omitempty"`
}

Message shown to the user.

type Outbox added in v0.0.47

type Outbox interface {
	Register(topic string, p outbox.Publisher)
	Enqueue(ctx context.Context, m outbox.Message) error
}

Outbox keeps the security events until the broker took them (README, Security events).

type Rendered

type Rendered struct {
	Subject string `json:"subject,omitempty" schemapb:"secret=true"`
	Body    string `json:"body,omitempty"    schemapb:"secret=true"`
	HTML    string `json:"html,omitempty"    schemapb:"secret=true"`
}

Rendered is a message as Kratos's templates render it; it holds the code.

type SessionDeny added in v0.0.41

type SessionDeny struct {
	// Code is the machine reason the client gets (error.reason).
	Code     string    `json:"code"               validate:"required"`
	Messages []Message `json:"messages,omitempty"`
}

SessionDeny refuses a new session.

type SessionIssuedIn added in v0.0.41

type SessionIssuedIn struct {
	// Flow is login, registration or recovery: the flow the client
	// submitted; empty for an OIDC callback whose start is unknown.
	Flow string `json:"flow,omitempty"`
	// Method is the session's latest authentication method (password, code,
	// oidc, webauthn, passkey, totp, lookup_secret, code_recovery, ...).
	Method string `json:"method"`
	// FlowID is the client's flow, the ClientFlowID of the after hooks: the
	// submit's ?flow=, for an OIDC sign-in the flow that started it, for the
	// native exchange the app's X-Kratos-Flow-Id header (unverified). Empty
	// when unknown.
	FlowID string `json:"flow_id,omitempty"`
	// Channel is browser, api or native_exchange.
	Channel string `json:"channel"`
	// Identity of the session, stored.
	Identity ory.Identity `json:"identity"`
	// Session as Kratos stored it, without its identity, token or cookie.
	Session ory.Session `json:"session"`
	// TransientPayload of the submit that issued the session; empty for an
	// OIDC callback and the native exchange (the after hooks had it).
	TransientPayload json.RawMessage `json:"transient_payload,omitempty"`
}

SessionIssuedIn is a session Kratos has stored whose credential has not left yet.

type SessionIssuedOut added in v0.0.41

type SessionIssuedOut struct {
	Deny *SessionDeny `json:"deny,omitempty"`
}

SessionIssuedOut: nothing lets the credential go; Deny revokes the session and refuses the client.

type Sessions added in v0.0.17

type Sessions interface {
	ListIdentitySessions(ctx context.Context, id string, f ory.SessionFilter) (ory.Page[ory.Session], error)
	// WhoAmI is the session of a token or a cookie header.
	WhoAmI(ctx context.Context, token, cookie string) (ory.Session, error)
	GetSession(ctx context.Context, id string) (ory.Session, error)
	// DisableSession revokes a session.
	DisableSession(ctx context.Context, id string) error
	// GetIdentity reads an identity, with the configurations of the
	// credential types named.
	GetIdentity(ctx context.Context, id string, includeCredential ...string) (ory.Identity, error)
}

Sessions reads sessions from Kratos.

type Stat

type Stat struct {
	Point       string
	Calls       uint64
	Failures    uint64
	LastAt      time.Time
	LastOutcome string
	LastError   string
	LastLatency time.Duration
}

Stat is how one callback point has been doing since start.

Jump to

Keyboard shortcuts

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