Documentation
¶
Overview ¶
Package plugin defines explicitly registered, compiled extensions.
Plugins run with full application privileges; this is not a sandbox. The contract remains unstable until AUTH-045. See docs/plugins.md.
Index ¶
- Constants
- Variables
- type Authentication
- type Definition
- type Event
- type Operation
- type Registry
- func (r Registry) AfterCommit(ctx context.Context, event Event, report func(string))
- func (r Registry) BeforeCommit(ctx context.Context, tx storage.Tx, event Event) error
- func (r Registry) Contracts() []contract.Plugin
- func (r Registry) IDs() []string
- func (r Registry) Routes() []Route
- func (r Registry) Schemas() []storage.PluginSchema
- type Route
Examples ¶
Constants ¶
const ( Public = contract.Public Session = contract.Session AuthenticationFlow = contract.AuthenticationFlow RecentSession = contract.RecentSession // Authentication less than five minutes old. )
Variables ¶
var ErrHook = errors.New("plugin: transactional hook failed")
Functions ¶
This section is empty.
Types ¶
type Authentication ¶
type Authentication = contract.Authentication
Authentication must be explicit on every route. The zero value is invalid. It is the contract package's type so route declarations and the exported API description cannot disagree.
type Definition ¶
type Definition struct {
ID string
Dependencies []string
Routes []Route
// SchemaNames reserves owned relation names. Migrations explicitly create them.
SchemaNames []string
// Migrations are append-only, explicitly applied by the storage operator.
Migrations []storage.PluginMigration
// Components are named schemas the plugin's operations reference. Names
// must not collide with core or other plugins; prefix them with the plugin.
Components []contract.Component
// BeforeCommit runs AFTER core checks and mutations, in the same transaction.
// Return an error to roll back. Never retain Tx or perform external effects.
BeforeCommit func(context.Context, storage.Tx, Event) error
// AfterCommit is synchronous, best-effort notification after acknowledged
// commit. Failure cannot undo a commit or change the operation result.
AfterCommit func(context.Context, Event) error
}
Definition is declarative: New never calls plugin code. Dependencies order both hooks and events; unrelated IDs run lexicographically. Callback closures remain host-owned and must be concurrency-safe and honor cancellation.
Example ¶
package main
import (
"context"
"fmt"
"net/http"
"strings"
sigil "github.com/brewgenixapp/sigil"
"github.com/brewgenixapp/sigil/contract"
"github.com/brewgenixapp/sigil/plugin"
)
func main() {
status := plugin.Definition{
ID: "status",
// Components and Operation describe the route for the exported API
// contract (sigil.Describe); startup fails without them.
Components: []contract.Component{{Name: "StatusView", Schema: contract.Schema{Type: contract.Object, Properties: []contract.Property{
{Name: "enabled", Schema: contract.Schema{Type: contract.Boolean}},
}}}},
Routes: []plugin.Route{{
Method: "GET", Path: "/extension/status", Authentication: plugin.Public,
Operation: contract.Operation{
ID: "extensionStatus", Summary: "Report whether the extension is enabled",
Success: contract.Response{Status: 200, Description: "Current status.", Schema: &contract.Schema{Ref: "StatusView"}},
},
Handle: func(w http.ResponseWriter, r *http.Request) error {
_, err := w.Write([]byte(`{"enabled":true}`))
return err
},
}},
}
// Supply production storage, shared abuse storage and a deployment secret in
// the host. This startup-only example neither serves requests nor opens a DB.
a, err := sigil.New(context.Background(), sigil.Config{
BaseURL: "https://auth.example.com",
Secret: sigil.NewSecret(strings.Repeat("example-only-key-", 2)),
Plugins: []plugin.Definition{status},
})
if err != nil {
panic(err)
}
defer a.Close(context.Background())
fmt.Println(a.PluginIDs())
}
Output: [status]
type Event ¶
type Event struct{ Operation Operation }
Event describes a successful operation callback, including an intentional no-op. It contains no credentials or caller-controlled input.
type Operation ¶
type Operation string
const ( Registration Operation = "registration" PasswordSignIn Operation = "password.sign_in" Verification Operation = "email.verify" VerificationResend Operation = "email.verification_resend" EmailChangeRequest Operation = "email.change_request" EmailChangeConfirm Operation = "email.change_confirm" PasswordResetRequest Operation = "password.reset_request" PasswordReset Operation = "password.reset" PasswordChange Operation = "password.change" AccountLink Operation = "account.link" AccountUnlink Operation = "account.unlink" AccountDelete Operation = "account.delete" SessionIssue Operation = "session.issue" SessionStepUp Operation = "session.step_up" SessionRenew Operation = "session.renew" SessionRevoke Operation = "session.revoke" SessionsRevoke Operation = "sessions.revoke" AdminSessionsRevoke Operation = "admin.sessions_revoke" AdminSessionRevoke Operation = "admin.session_revoke" AdminUserSuspend Operation = "admin.user_suspend" AdminUserReinstate Operation = "admin.user_reinstate" // Impersonation start and end; see docs/impersonation.md. AdminImpersonationStart Operation = "admin.impersonation_start" AdminImpersonationEnd Operation = "admin.impersonation_end" )
type Registry ¶
type Registry struct {
// contains filtered or unexported fields
}
Registry is immutable. Its zero value is an empty registry.
func Compile ¶
func Compile(definitions []Definition, reservedPaths []string) (Registry, error)
Compile validates and snapshots declarations. reservedPaths belong to core for ALL methods; auth_* schema names and ID core are reserved for core.
func (Registry) AfterCommit ¶
AfterCommit attempts every subscriber, reporting only the failing plugin ID. report must not panic. Error text/panic payloads can contain secrets and are deliberately discarded. Notifications have no retries or durability guarantee.
func (Registry) BeforeCommit ¶
func (Registry) Contracts ¶
Contracts returns each plugin's API description in dependency order, for sigil.Describe and startup validation. Handlers are not included.
func (Registry) Schemas ¶
func (r Registry) Schemas() []storage.PluginSchema
Schemas returns independent copies in dependency order. Reservation-only declarations are included so operators can detect persisted ownership conflicts.
type Route ¶
type Route struct {
Method, Path string
Authentication Authentication
Operation contract.Operation
Handle func(http.ResponseWriter, *http.Request) error
}
Route is an exact, mount-relative path. GET handlers must have no side effects. All routes inherit core host, origin, body, CSRF and abuse policies. Operation describes the request, success response and endpoint-specific error codes for the exported API contract; a route without one fails startup.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package apikey provides optional PostgreSQL/SQLite scoped API keys: an authentication mode distinct from browser sessions, for non-interactive callers of the host's own API.
|
Package apikey provides optional PostgreSQL/SQLite scoped API keys: an authentication mode distinct from browser sessions, for non-interactive callers of the host's own API. |
|
Package authserver lets a host operate an OAuth 2.0 authorization server and OpenID Connect provider for its own users, on PostgreSQL and SQLite.
|
Package authserver lets a host operate an OAuth 2.0 authorization server and OpenID Connect provider for its own users, on PostgreSQL and SQLite. |
|
internal
|
|
|
idtoken
Package idtoken holds the OpenID Connect ID-token claim contract shared by the provider sign-in plugins, so provider sign-in and organization SSO accept exactly the same tokens.
|
Package idtoken holds the OpenID Connect ID-token claim contract shared by the provider sign-in plugins, so provider sign-in and organization SSO accept exactly the same tokens. |
|
Package magiclink provides optional, existing-account email sign-in using public plugin, storage, mail and session contracts.
|
Package magiclink provides optional, existing-account email sign-in using public plugin, storage, mail and session contracts. |
|
Package oauth implements optional authorization-code sign-in for already linked external identities.
|
Package oauth implements optional authorization-code sign-in for already linked external identities. |
|
github
Package github configures GitHub OAuth 2.0 sign-in for the oauth plugin.
|
Package github configures GitHub OAuth 2.0 sign-in for the oauth plugin. |
|
google
Package google configures Google OpenID Connect sign-in for the oauth plugin.
|
Package google configures Google OpenID Connect sign-in for the oauth plugin. |
|
internal/providertest
Package providertest is the PostgreSQL fixture shared by the provider adapter integration tests.
|
Package providertest is the PostgreSQL fixture shared by the provider adapter integration tests. |
|
Package organization provides optional PostgreSQL/SQLite tenant membership and session context.
|
Package organization provides optional PostgreSQL/SQLite tenant membership and session context. |
|
Package passkey provides user-verified discoverable WebAuthn credentials.
|
Package passkey provides user-verified discoverable WebAuthn credentials. |
|
Package portability holds the cross-engine plugin fixtures that keep the PostgreSQL and SQLite adapters honest about the same behavior: baseline migration, real factor/tenant/credential data preserved across disablement, and re-enablement after an upgrade.
|
Package portability holds the cross-engine plugin fixtures that keep the PostgreSQL and SQLite adapters honest about the same behavior: baseline migration, real factor/tenant/credential data preserved across disablement, and re-enablement after an upgrade. |
|
Package scim provides optional organization-bound SCIM 2.0 provisioning and deprovisioning for PostgreSQL and SQLite (RFC 7643 and RFC 7644).
|
Package scim provides optional organization-bound SCIM 2.0 provisioning and deprovisioning for PostgreSQL and SQLite (RFC 7643 and RFC 7644). |
|
Package sso provides optional organization-bound OpenID Connect and SAML 2.0 single sign-on for PostgreSQL and SQLite.
|
Package sso provides optional organization-bound OpenID Connect and SAML 2.0 single sign-on for PostgreSQL and SQLite. |
|
Package totp implements optional password-plus-TOTP authentication on PostgreSQL.
|
Package totp implements optional password-plus-TOTP authentication on PostgreSQL. |
|
Package userfields adds explicit, typed custom fields to user accounts.
|
Package userfields adds explicit, typed custom fields to user accounts. |