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" )
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.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
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 tenant membership and session context.
|
Package organization provides optional PostgreSQL tenant membership and session context. |
|
Package passkey provides user-verified discoverable WebAuthn credentials.
|
Package passkey provides user-verified discoverable WebAuthn credentials. |
|
Package totp implements optional password-plus-TOTP authentication on PostgreSQL.
|
Package totp implements optional password-plus-TOTP authentication on PostgreSQL. |