securityx

package
v0.3.0 Latest Latest
Warning

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

Go to latest
Published: Jul 7, 2026 License: MIT Imports: 12 Imported by: 0

Documentation

Overview

Package securityx groups framework-level security configuration and runtime construction for authn, access shortcuts, authz and audit.

securityx is not a middleware assembly layer. serverx/autowire remains the only service middleware assembly entrypoint. securityx turns config.yaml into provider-neutral runtime values consumed by serverx.RuntimeProviders.

Package securityx provides a small shared configuration shape for Kernel security components.

Recommended responsibility split:

  • authn/casdoor verifies users and provisions the identity-side projection of organizations, applications and groups.
  • authz/spicedb owns ReBAC relationships and permission checks.
  • auditx records security-relevant decisions.

Keep business facts in Kernel IAM DB. Sync Casdoor and SpiceDB as projections.

Index

Constants

View Source
const (
	// AuthnModeCasdoorJWT verifies the inbound Casdoor/OIDC JWT locally with
	// OIDC discovery + JWKS. Use it at Gateway and for high-security services
	// that intentionally verify the bearer token again.
	AuthnModeCasdoorJWT = "casdoor_jwt"

	// AuthnModeOIDCJWT is the provider-neutral spelling of casdoor_jwt.
	AuthnModeOIDCJWT = "oidc_jwt"

	// AuthnModePrincipalJWT verifies an IAM-issued Principal assertion JWT from
	// X-Aisphere-Principal-JWT. This is the preferred backend mode when Envoy
	// Gateway ExternalAuth delegates external authentication to IAM.
	AuthnModePrincipalJWT = "principal_jwt"

	// AuthnModeGatewayTrusted trusts Principal headers injected by Gateway, but
	// only after validating the Gateway -> backend internal-service-token.
	AuthnModeGatewayTrusted = "gateway_trusted"

	// AuthnModeHybrid first tries bearer JWT verification, then falls back to
	// Gateway trusted headers. It is useful during migration, not as the final
	// strict production default.
	AuthnModeHybrid = "hybrid"

	// AuthnModeDisabled installs no authn middleware.
	AuthnModeDisabled = "disabled"
)
View Source
const DefaultConfigKey = "security"

Variables

This section is empty.

Functions

This section is empty.

Types

type AuditConfig

type AuditConfig struct {
	Enabled bool   `json:"enabled" yaml:"enabled"`
	Backend string `json:"backend" yaml:"backend"`
	DSN     string `json:"dsn" yaml:"dsn"`
}

type AuthnBoundaryConfig added in v0.2.4

type AuthnBoundaryConfig struct {
	Enabled bool   `json:"enabled" yaml:"enabled"`
	Mode    string `json:"mode" yaml:"mode"`

	// Provider is descriptive. For Casdoor deployments use provider=casdoor and
	// mode=casdoor_jwt. The actual JWT verifier is OIDC/JWKS based and does not
	// require Casdoor client_secret.
	Provider string `json:"provider" yaml:"provider"`

	OIDC oidcx.Config `json:"oidc" yaml:"oidc"`

	// PrincipalJWT verifies IAM-issued Gateway -> backend identity assertions.
	// Business services only need mode=principal_jwt plus this shared secret.
	PrincipalJWT authn.PrincipalJWTConfig `json:"principal_jwt" yaml:"principal_jwt"`

	// InternalCall is required in gateway_trusted mode and is injected by
	// Gateway before forwarding requests to backend services.
	InternalCall authn.InternalServiceTokenConfig `json:"internal_call" yaml:"internal_call"`

	// CacheTTL enables optional token-hash -> Principal caching when a cache is
	// supplied. TTL is always capped by the JWT exp claim by authn.CachedAuthenticator.
	CacheTTL time.Duration `json:"cache_ttl_ns" yaml:"cache_ttl_ns"`

	AllowAnonymous bool `json:"allow_anonymous" yaml:"allow_anonymous"`
}

AuthnBoundaryConfig is the framework-level AuthN contract shared by Gateway and backend services. Business services should expose this structure in their config.yaml and then call NewAuthnBoundaryRuntime instead of manually parsing JWTs, trusted headers or internal-service-token headers.

func (AuthnBoundaryConfig) Normalized added in v0.2.4

type AuthnBoundaryRuntime added in v0.2.4

type AuthnBoundaryRuntime struct {
	Config              AuthnBoundaryConfig
	Authenticator       authn.Authenticator
	CredentialExtractor authnmw.CredentialExtractor
}

AuthnBoundaryRuntime is the auto-wired AuthN result used by server boot. Gateway code uses Authenticator directly; backend services normally install Middleware so Principal is injected into context before business handlers run.

func NewAuthnBoundaryRuntime added in v0.2.4

func NewAuthnBoundaryRuntime(ctx context.Context, cfg AuthnBoundaryConfig, cache cachex.Cache) (*AuthnBoundaryRuntime, error)

NewAuthnBoundaryRuntime builds the framework AuthN runtime from config. cache is optional; pass nil to use only the built-in JWKS cache.

func (AuthnBoundaryRuntime) Enabled added in v0.2.4

func (r AuthnBoundaryRuntime) Enabled() bool

func (AuthnBoundaryRuntime) ServerMiddleware added in v0.2.4

func (r AuthnBoundaryRuntime) ServerMiddleware() []middleware.Middleware

ServerMiddleware returns the complete AuthN middleware for backend services. In principal_jwt mode it verifies IAM-issued Principal JWTs. In gateway_trusted mode it validates internal-service-token and restores Principal from trusted headers. In casdoor_jwt mode it verifies bearer/cookie-forwarded JWTs with OIDC/JWKS.

type AuthnConfig deprecated

type AuthnConfig = AuthnBoundaryConfig

AuthnConfig is kept as a type alias for older code that imported securityx.AuthnConfig.

Deprecated: use AuthnBoundaryConfig. This alias remains only as a short-term migration shim and must not be used by new generated code or examples.

type AuthzConfig

type AuthzConfig struct {
	Enabled     bool           `json:"enabled" yaml:"enabled"`
	Provider    string         `json:"provider" yaml:"provider"`
	DevAllowAll bool           `json:"dev_allow_all" yaml:"dev_allow_all"`
	SpiceDB     spicedb.Config `json:"spicedb" yaml:"spicedb"`
}

type Config

type Config struct {
	// Authn describes how inbound callers become authn.Principal values. It is
	// consumed by NewRuntime to build AuthnBoundaryRuntime.
	Authn AuthnBoundaryConfig `json:"authn" yaml:"authn"`

	// InternalCall is the Gateway -> backend trust-boundary secret. It is kept as
	// a top-level field because existing configs use security.internal_call. When
	// Authn.InternalCall is empty, NewRuntime copies this value into Authn.
	InternalCall authn.InternalServiceTokenConfig `json:"internal_call" yaml:"internal_call"`

	// Access controls per-operation short-circuits such as public endpoints and
	// bootstrap/self-service endpoints that skip SpiceDB but still require authn.
	Access accessx.AccessConfig `json:"access" yaml:"access"`

	Authz AuthzConfig `json:"authz" yaml:"authz"`
	Audit AuditConfig `json:"audit" yaml:"audit"`
}

Config is the canonical security subtree shared by Gateway and backend services. Business projects may embed this type directly or map their legacy config structs into it during boot.

func Scan

func Scan(cfg configx.Config) (Config, error)

func ScanKey

func ScanKey(cfg configx.Config, key string) (Config, error)

func (Config) Normalized

func (c Config) Normalized() Config

type Runtime added in v0.2.4

type Runtime struct {
	Config Config

	AuthnBoundary      *AuthnBoundaryRuntime
	SkipPolicyResolver accessx.SkipPolicyResolver
}

Runtime is the security material produced from Config and consumed by serverx.RuntimeProviders. It deliberately contains provider-neutral runtime objects, not transport middleware, so serverx/autowire remains the single middleware assembly layer.

func NewRuntime added in v0.2.4

func NewRuntime(ctx context.Context, cfg Config, cache cachex.Cache) (*Runtime, error)

NewRuntime builds the security runtime from the canonical security config. cache is optional and is only used by JWT/OIDC authenticators when CacheTTL is configured.

Jump to

Keyboard shortcuts

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