extension

package
v1.10.0 Latest Latest
Warning

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

Go to latest
Published: Nov 4, 2026 License: MIT Imports: 18 Imported by: 1

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

View Source
const ExtensionDescription = "Human-centric AI safety and governance"

ExtensionDescription is the human-readable description.

View Source
const ExtensionName = "shield"

ExtensionName is the name registered with Forge.

View Source
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 New

func New(opts ...Option) *Extension

New creates a new Shield Forge extension with the given options.

func (*Extension) Engine

func (e *Extension) Engine() *engine.Engine

Engine returns the underlying Shield engine. This is nil until Register is called.

func (*Extension) Health

func (e *Extension) Health(ctx context.Context) error

Health implements forge.Extension.

func (*Extension) Register

func (e *Extension) Register(fapp forge.App) error

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

func (e *Extension) Start(ctx context.Context) error

Start implements forge.Extension.

func (*Extension) Stop

func (e *Extension) Stop(ctx context.Context) error

Stop implements forge.Extension.

type Option

type Option func(*Extension)

Option configures the Shield Forge extension.

func WithBasePath

func WithBasePath(path string) Option

WithBasePath sets the URL prefix for shield routes.

func WithConfig

func WithConfig(cfg Config) Option

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

func WithDashboardAudit(audit admin.Audit) Option

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

func WithEngineOption(opt engine.Option) Option

WithEngineOption passes an engine option through.

func WithGroveDatabase

func WithGroveDatabase(name string) Option

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 WithPlugin

func WithPlugin(p plugin.Plugin) Option

WithPlugin registers a lifecycle plugin.

func WithRequireConfig

func WithRequireConfig(require bool) Option

WithRequireConfig requires config to be present in YAML files. If true and no config is found, Register returns an error.

func WithStore

func WithStore(s store.Store) Option

WithStore sets the composite store for the engine.

Directories

Path Synopsis
Package contract registers Shield's authenticated dashboard contract.
Package contract registers Shield's authenticated dashboard contract.

Jump to

Keyboard shortcuts

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