Documentation
¶
Overview ¶
Package extension provides the Forge extension adapter for Shield.
It implements the forge.Extension interface to integrate Shield into a Forge application with automatic dependency discovery, route registration, and lifecycle management.
Configuration can be provided programmatically via Option functions or via YAML configuration files under "extensions.shield" or "shield" keys.
Index ¶
- Constants
- type Config
- type Extension
- func (e *Extension) Engine() *engine.Engine
- func (e *Extension) Health(ctx context.Context) error
- func (e *Extension) Register(fapp forge.App) error
- func (e *Extension) RegisterContractContributor(d *dispatcher.Dispatcher, reg dashcontract.Registry, ...) error
- func (e *Extension) Start(ctx context.Context) error
- func (e *Extension) Stop(ctx context.Context) error
- type Option
- func WithBasePath(path string) Option
- func WithConfig(cfg Config) Option
- func WithDashboardActorResolver(resolve shieldcontract.ActorResolver) Option
- func WithDashboardAudit(audit admin.Audit) Option
- func WithDisableMigrate() Option
- func WithDisableRoutes() Option
- func WithEngineOption(opt engine.Option) Option
- func WithGroveDatabase(name string) Option
- func WithPlugin(p plugin.Plugin) Option
- func WithRequireConfig(require bool) Option
- func WithStore(s store.Store) Option
Constants ¶
const ExtensionDescription = "Human-centric AI safety and governance"
ExtensionDescription is the human-readable description.
const ExtensionName = "shield"
ExtensionName is the name registered with Forge.
const ExtensionVersion = "0.1.0"
ExtensionVersion is the semantic version.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Config ¶
type Config struct {
// DisableRoutes prevents HTTP route registration.
DisableRoutes bool `json:"disable_routes" mapstructure:"disable_routes" yaml:"disable_routes"`
// DisableMigrate prevents auto-migration on start.
DisableMigrate bool `json:"disable_migrate" mapstructure:"disable_migrate" yaml:"disable_migrate"`
// BasePath is the URL prefix for shield routes (default: "/shield").
BasePath string `json:"base_path" mapstructure:"base_path" yaml:"base_path"`
// DefaultProfile is the safety profile to use when none is specified.
DefaultProfile string `json:"default_profile" mapstructure:"default_profile" yaml:"default_profile"`
// ShutdownTimeout is the maximum time to wait for graceful shutdown.
ShutdownTimeout time.Duration `json:"shutdown_timeout" mapstructure:"shutdown_timeout" yaml:"shutdown_timeout"`
// ScanConcurrency controls how many scan operations can run in parallel.
ScanConcurrency int `json:"scan_concurrency" mapstructure:"scan_concurrency" yaml:"scan_concurrency"`
// EnableShortCircuit allows layers to stop execution when a block decision
// is reached, skipping deeper layers.
EnableShortCircuit bool `json:"enable_short_circuit" mapstructure:"enable_short_circuit" yaml:"enable_short_circuit"`
// MaxScanBytes is the largest text a scan accepts (default 1 MiB).
MaxScanBytes int `json:"max_scan_bytes" mapstructure:"max_scan_bytes" yaml:"max_scan_bytes"`
// ProfileCacheTTL is how long a compiled safety profile is reused
// (default 30s). A negative value disables the cache.
ProfileCacheTTL time.Duration `json:"profile_cache_ttl" mapstructure:"profile_cache_ttl" yaml:"profile_cache_ttl"`
// StoreRedacted keeps the redacted text on persisted scans.
StoreRedacted bool `json:"store_redacted" mapstructure:"store_redacted" yaml:"store_redacted"`
// ModelJudge lets the model assessor call a judge registered through
// WithEngineOption(engine.WithJudge(...)). Off by default.
ModelJudge bool `json:"model_judge" mapstructure:"model_judge" yaml:"model_judge"`
// JudgeTimeout bounds one judge call (default 5s).
JudgeTimeout time.Duration `json:"judge_timeout" mapstructure:"judge_timeout" yaml:"judge_timeout"`
// JudgeConcurrency caps the judge calls in flight (default 8).
JudgeConcurrency int `json:"judge_concurrency" mapstructure:"judge_concurrency" yaml:"judge_concurrency"`
// GroveDatabase is the name of a grove.DB registered in the DI container.
// When set, the extension resolves this named database and auto-constructs
// the appropriate store based on the driver type (pg/sqlite/mongo).
// When empty and WithGroveDatabase was called, the default (unnamed) DB is used.
GroveDatabase string `json:"grove_database" mapstructure:"grove_database" yaml:"grove_database"`
// RequireConfig requires config to be present in YAML files.
// If true and no config is found, Register returns an error.
RequireConfig bool `json:"-" yaml:"-"`
}
Config holds the Shield extension configuration. Fields can be set programmatically via Option functions or loaded from YAML configuration files (under "extensions.shield" or "shield" keys).
func DefaultConfig ¶
func DefaultConfig() Config
DefaultConfig returns a Config with sensible defaults.
type Extension ¶
type Extension struct {
*forge.BaseExtension
// contains filtered or unexported fields
}
Extension adapts Shield as a Forge extension.
func (*Extension) Engine ¶
Engine returns the underlying Shield engine. This is nil until Register is called.
func (*Extension) Health ¶
Health implements forge.Extension.
func (*Extension) Register ¶
Register implements forge.Extension. It loads configuration, initializes the engine, and registers it in the DI container.
func (*Extension) RegisterContractContributor ¶
func (e *Extension) RegisterContractContributor(d *dispatcher.Dispatcher, reg dashcontract.Registry, wreg dashcontract.WardenRegistry) error
RegisterContractContributor implements the Forge discovery interface.
func (*Extension) Start ¶
Start implements forge.Extension.
type Option ¶
type Option func(*Extension)
Option configures the Shield Forge extension.
func WithBasePath ¶
WithBasePath sets the URL prefix for shield routes.
func WithConfig ¶
WithConfig sets the Forge extension configuration.
func WithDashboardActorResolver ¶
func WithDashboardActorResolver(resolve shieldcontract.ActorResolver) Option
WithDashboardActorResolver installs a host authorization adapter. It must authenticate the principal and authorize every returned scope and permission.
func WithDashboardAudit ¶
WithDashboardAudit installs the audit sink required by PII retention commands.
func WithDisableMigrate ¶
func WithDisableMigrate() Option
WithDisableMigrate prevents auto-migration on start.
func WithDisableRoutes ¶
func WithDisableRoutes() Option
WithDisableRoutes prevents HTTP route registration.
func WithEngineOption ¶
WithEngineOption passes an engine option through.
func WithGroveDatabase ¶
WithGroveDatabase sets the name of the grove.DB to resolve from the DI container. The extension will auto-construct the appropriate store backend (postgres/sqlite/mongo) based on the grove driver type. Pass an empty string to use the default (unnamed) grove.DB.
func WithRequireConfig ¶
WithRequireConfig requires config to be present in YAML files. If true and no config is found, Register returns an error.