Documentation
¶
Overview ¶
Package security provides immutable authenticated principals and deny-by-default authorization policies for generated Spice guards.
Index ¶
- func Guard(authorizer *Authorizer, policy Policy, onWriteFailure WriteFailure) (web.Middleware, error)
- func ValidateExpression(source string) error
- func WithPrincipal(ctx context.Context, principal Principal) (context.Context, error)
- type Authorizer
- type Decision
- type Definition
- type DeniedError
- type Observer
- type Policy
- type PolicySpec
- type Principal
- type Reason
- type WriteFailure
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Guard ¶
func Guard( authorizer *Authorizer, policy Policy, onWriteFailure WriteFailure, ) (web.Middleware, error)
Guard constructs HTTP authorization middleware after validating its policy.
func ValidateExpression ¶
ValidateExpression checks one restricted authorization expression against the exact symbol schema used at runtime. Compilers use this function to fail at the annotation source before generated Go is rendered.
Types ¶
type Authorizer ¶
type Authorizer struct {
// contains filtered or unexported fields
}
Authorizer evaluates immutable policies without a global security context.
Example ¶
package main
import (
"context"
"fmt"
"github.com/spice-framework/spice/security"
)
func main() {
policy, err := security.NewPolicy(security.PolicySpec{
Definition: security.Definition{
ID: "orders.read",
Module: "example.com/shop/orders",
},
AllScopes: []string{"orders:read"},
})
principal, principalErr := security.NewPrincipal(
"user-1",
"https://issuer.example",
nil,
[]string{"orders:read"},
)
if err != nil || principalErr != nil {
fmt.Printf("construct: %v %v\n", err, principalErr)
return
}
ctx, err := security.WithPrincipal(context.Background(), principal)
authorizer, authorizerErr := security.NewAuthorizer()
if err == nil && authorizerErr == nil {
err = authorizer.Authorize(ctx, policy)
}
fmt.Printf("authorized=%v\n", err == nil)
}
Output: authorized=true
func NewAuthorizer ¶
func NewAuthorizer(observers ...Observer) (*Authorizer, error)
NewAuthorizer constructs an instance-owned evaluator.
type Decision ¶
type Decision struct {
Definition Definition
Allowed bool
Reason Reason
Duration time.Duration
}
Decision contains bounded policy metadata and no identity claims.
type Definition ¶
Definition identifies one compiler-owned authorization policy and module.
type DeniedError ¶
type DeniedError struct {
Definition Definition
Reason Reason
}
DeniedError is a safe authorization failure.
func (*DeniedError) Error ¶
func (err *DeniedError) Error() string
Error returns no principal or claim data.
type Policy ¶
type Policy struct {
// contains filtered or unexported fields
}
Policy is an immutable validated authorization policy.
func NewPolicy ¶
func NewPolicy(spec PolicySpec) (Policy, error)
NewPolicy validates and freezes one generated policy. A policy with no requirement is rejected so zero configuration can never grant access.
func (Policy) Definition ¶
func (policy Policy) Definition() Definition
Definition returns the policy's stable generated identity.
func (Policy) Expression ¶
Expression returns the compiler-validated restricted policy expression, if one was declared. It never contains runtime identity or claim values.
type PolicySpec ¶
type PolicySpec struct {
Definition Definition
Authenticated bool
AnyRoles []string
AllRoles []string
AllScopes []string
Expression string
}
PolicySpec is the inspectable generated input to NewPolicy. Role and scope names are exact and case-sensitive.
type Principal ¶
type Principal struct {
// contains filtered or unexported fields
}
Principal is an immutable identity created only after authentication.
func NewPrincipal ¶
NewPrincipal validates and freezes verified identity claims.
func PrincipalFromContext ¶
PrincipalFromContext returns the authenticated principal, if present.
type Reason ¶
type Reason string
Reason is a stable authorization decision class.
const ( // ReasonAllowed identifies a satisfied policy. ReasonAllowed Reason = "allowed" // ReasonUnauthenticated identifies a missing principal. ReasonUnauthenticated Reason = "unauthenticated" // ReasonRole identifies an unmet role requirement. ReasonRole Reason = "role" // ReasonScope identifies an unmet scope requirement. ReasonScope Reason = "scope" // ReasonExpression identifies a restricted policy expression that evaluated // to false. ReasonExpression Reason = "expression" )
type WriteFailure ¶
WriteFailure receives an HTTP response-write failure that cannot be returned through http.Handler.
Source Files