Documentation
¶
Overview ¶
Package auth is sign-in (ADR-0024, docs/architecture/auth.md): accounts, sign-in by email and one-time code, the browser (OAuth 2.0 + PKCE) and device (RFC 8628) flows, access and refresh tokens, sessions and JWKS. It knows no members, roles or workspaces: a workspace platform runs it for its own accounts and says who may sign in (Config.Allow); the site will run it for its buyers. There is no registration: the first sign-in of an email makes its account.
Index ¶
- Constants
- type Config
- type External
- type Service
- func (s *Service) AuthorizeVerified(ctx context.Context, email, ip string, authorize url.Values) (string, error)
- func (s *Service) ClientIP(peer string, h http.Header) string
- func (s *Service) CompleteEmailSignIn(ctx context.Context, req *connect.Request[authv1.CompleteEmailSignInRequest]) (*connect.Response[authv1.CompleteEmailSignInResponse], error)
- func (s *Service) ExchangeAuthorizationCode(ctx context.Context, ...) (*connect.Response[authv1.ExchangeAuthorizationCodeResponse], error)
- func (s *Service) GetMe(ctx context.Context, req *connect.Request[authv1.GetMeRequest]) (*connect.Response[authv1.GetMeResponse], error)
- func (s *Service) Handler() http.Handler
- func (s *Service) JWKS() token.JWKS
- func (s *Service) ListSessions(ctx context.Context, req *connect.Request[authv1.ListSessionsRequest]) (*connect.Response[authv1.ListSessionsResponse], error)
- func (s *Service) OpenVerified(ctx context.Context, email, device, ip, audience string) (*authv1.Tokens, error)
- func (s *Service) PollDeviceSignIn(ctx context.Context, req *connect.Request[authv1.PollDeviceSignInRequest]) (*connect.Response[authv1.PollDeviceSignInResponse], error)
- func (s *Service) Refresh(ctx context.Context, req *connect.Request[authv1.RefreshRequest]) (*connect.Response[authv1.RefreshResponse], error)
- func (s *Service) RevokeSession(ctx context.Context, req *connect.Request[authv1.RevokeSessionRequest]) (*connect.Response[authv1.RevokeSessionResponse], error)
- func (s *Service) RotateKeys(ctx context.Context, force bool) error
- func (s *Service) Run(ctx context.Context)
- func (s *Service) Sign(c token.Claims) (string, error)
- func (s *Service) SignAccess(userID, email, audience string) (string, error)
- func (s *Service) SignOut(ctx context.Context, req *connect.Request[authv1.SignOutRequest]) (*connect.Response[authv1.SignOutResponse], error)
- func (s *Service) StartDeviceSignIn(ctx context.Context, req *connect.Request[authv1.StartDeviceSignInRequest]) (*connect.Response[authv1.StartDeviceSignInResponse], error)
- func (s *Service) StartEmailSignIn(ctx context.Context, req *connect.Request[authv1.StartEmailSignInRequest]) (*connect.Response[authv1.StartEmailSignInResponse], error)
- func (s *Service) Verify(access string) (token.Claims, error)
Constants ¶
const ( AccessTTL = 15 * time.Minute SessionIdle = 30 * 24 * time.Hour // a session not refreshed for this long ends SessionMax = 90 * 24 * time.Hour // and any session ends after this CodeTTL = 10 * time.Minute // one-time codes in emails CodeAttempts = 5 AuthCodeTTL = time.Minute // authorization codes of the browser sign-in DeviceCodeTTL = 10 * time.Minute DeviceInterval = 5 * time.Second KeyRotation = 30 * 24 * time.Hour // a new signing key after this // Codes sent per hour. LimitPerEmail = 5 LimitPerIP = 30 LimitPerDevice = 10 )
Lifetimes and limits of docs/architecture/auth.md.
const ClientID = "devopus-cli"
ClientID is the only OAuth client: the devopus CLI.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Config ¶
type Config struct {
// Issuer is the public URL of the service: the iss of tokens and the base of the
// sign-in pages.
Issuer string
Mailer mail.Mailer
Log *slog.Logger
// Allow says whether an email may sign in: on a platform, its owner, its members
// and the invited. Others get the same answer and no email, and their code never
// works. nil lets everyone in.
Allow func(ctx context.Context, email string) (bool, error)
// External is a sign-in elsewhere the browser sign-in of the CLI offers; nil
// offers none.
External *External
// TrustProxy takes the client address from X-Forwarded-For: only behind a proxy
// that sets it.
TrustProxy bool
// Now is the clock; time.Now when nil.
Now func() time.Time
}
Config configures the service.
type External ¶ added in v0.4.0
type External struct {
// Label is the button's text: "Continue with your Devopus account".
Label string
// URL is where the button leads; authorize is the CLI's browser sign-in request,
// empty for the web.
URL func(authorize url.Values) string
}
External is a sign-in elsewhere the sign-in pages offer next to the email.
type Service ¶
type Service struct {
authv1connect.UnimplementedAuthServiceHandler
// contains filtered or unexported fields
}
Service is the Auth service.
func (*Service) AuthorizeVerified ¶ added in v0.4.0
func (s *Service) AuthorizeVerified(ctx context.Context, email, ip string, authorize url.Values) (string, error)
AuthorizeVerified ends the CLI's browser sign-in (the request in authorize) for a checked email: the URL of the CLI's callback with the authorization code.
func (*Service) ClientIP ¶ added in v0.4.0
clientIP is the caller's address: the peer, or the first X-Forwarded-For entry behind a trusted proxy. ClientIP is the address of a request's client, from X-Forwarded-For when the service trusts a proxy.
func (*Service) CompleteEmailSignIn ¶
func (*Service) ExchangeAuthorizationCode ¶
func (*Service) ListSessions ¶
func (*Service) OpenVerified ¶ added in v0.4.0
func (s *Service) OpenVerified(ctx context.Context, email, device, ip, audience string) (*authv1.Tokens, error)
OpenVerified opens a session for a checked email: the tokens of a browser that came from the site.
func (*Service) PollDeviceSignIn ¶
func (*Service) RevokeSession ¶
func (*Service) RotateKeys ¶
RotateKeys loads the signing keys and makes a new one when there is none, when the newest is older than KeyRotation, or when force is set.
func (*Service) Run ¶
Run does the background work until ctx ends: picks up keys other instances made, rotates the signing key, deletes what expired.
func (*Service) Sign ¶
Sign signs claims with the current key: for tests of the process sign-in runs in (a token about to expire, one for another address).
func (*Service) SignAccess ¶
SignAccess signs an access token for a user, with no session behind it: for the tests and tools of the process sign-in runs in. It cannot be refreshed.
func (*Service) StartDeviceSignIn ¶
func (*Service) StartEmailSignIn ¶
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package mail sends Auth's emails: the sign-in codes.
|
Package mail sends Auth's emails: the sign-in codes. |
|
Package store is the database of accounts and sign-in (schema auth): the schema (migrations), the queries (sqlc) and the migration runner.
|
Package store is the database of accounts and sign-in (schema auth): the schema (migrations), the queries (sqlc) and the migration runner. |
|
Package token signs and checks Devopus access tokens: JWTs signed with Ed25519 (alg EdDSA) whose public keys Auth publishes as JWKS.
|
Package token signs and checks Devopus access tokens: JWTs signed with Ed25519 (alg EdDSA) whose public keys Auth publishes as JWKS. |