Documentation
¶
Overview ¶
Package security provides fine-grained authorization for Scheme runtime operations. It defines the Authorizer interface and context helpers that gate primitives like file I/O, code loading, and process control.
The package depends only on werr/ for error types and can be imported with minimal dependencies.
Index ¶
- Constants
- Variables
- func Check(ctx context.Context, req AccessRequest) errordeprecated
- func CheckWithAuthorizer(auth Authorizer, req AccessRequest) error
- func ConfinementRootOf(auth Authorizer) (string, bool)
- func WithAuthorizer(ctx context.Context, auth Authorizer) context.Context
- type AccessRequest
- type Authorizer
- func All(authorizers ...Authorizer) Authorizer
- func ConsoleAuthorizer() Authorizer
- func ConsoleWithLoadAuthorizer() Authorizer
- func DenyAll() Authorizer
- func FilesystemRoot(root string) Authorizer
- func FromContext(ctx context.Context) Authorizer
- func ReadOnly() Authorizer
- func ReadOnlyWithLoad() Authorizer
- func SandboxAuthorizer(envPrefix string) Authorizer
- type AuthorizerFunc
- type RootConfined
Constants ¶
const ( ResourceFile = "file" ResourceCode = "code" ResourceEnv = "env" ResourceProcess = "process" )
Well-known resource constants. Extensions may define additional resources without modifying this package.
const ( ActionRead = "read" ActionWrite = "write" ActionDelete = "delete" ActionStat = "stat" ActionLoad = "load" // load+run code from a resolved file path ActionEval = "eval" // compile+run code from an in-memory datum (eval/compile) ActionExit = "exit" ActionExec = "exec" // structured process execution (process-spawn) ActionExecShell = "exec-shell" // shell command execution (system) )
Well-known action constants. Extensions may define additional actions without modifying this package.
Variables ¶
var ErrAccessDenied = werr.NewStaticError("access denied")
ErrAccessDenied is the sentinel error returned when an Authorizer denies an operation. Use errors.Is to check for it. See the Authorizer doc for the deny-error wrapping convention.
Functions ¶
func Check
deprecated
func Check(ctx context.Context, req AccessRequest) error
Check authorizes req against the Authorizer in ctx.
Deprecated: The authorizer now lives on Namespace, not context. Production gate sites use CheckWithAuthorizer(mc.Authorizer(), req). This function remains for backward compatibility but will always find nil (open by default) unless the caller explicitly injects an authorizer via WithAuthorizer(ctx, auth).
New code should use CheckWithAuthorizer directly.
func CheckWithAuthorizer ¶ added in v1.7.0
func CheckWithAuthorizer(auth Authorizer, req AccessRequest) error
CheckWithAuthorizer checks authorization using an explicit authorizer. Returns nil if auth is nil (open by default).
On denial it wraps the authorizer's error with the operation's action, resource, and target — supplying the context that lets authorizers return the bare ErrAccessDenied sentinel (see the Authorizer deny-error wrapping convention).
func ConfinementRootOf ¶ added in v1.17.0
func ConfinementRootOf(auth Authorizer) (string, bool)
ConfinementRootOf reports the filesystem confinement root that applies to auth, if any. It unwraps All() composites, returning the first member that confines to a root.
This is a defense-in-depth bound, not the exact confinement. A composite is an intersection, so the true confinement is the intersection of every member's root, which is always a subset of the first member's root. The os.Root layer this drives is therefore never wider than that member's subtree, but for a multi-root composite it may be looser than the full intersection. That is safe: the policy layer (Authorize) enforces the full intersection and runs before any open, so returning the first root cannot widen access. (If multi-root composites ever need exact os.Root containment, return the deepest containing root for nested members and ok=false for disjoint ones — the profiles currently construct only single-root composites, so first-member-wins suffices.)
Returns ok=false when nothing confines auth to a root — callers then fall back to unconfined os operations, still gated by the policy layer.
func WithAuthorizer ¶
func WithAuthorizer(ctx context.Context, auth Authorizer) context.Context
WithAuthorizer returns a child context carrying the given Authorizer. Primitives retrieve it via FromContext or Check.
Types ¶
type AccessRequest ¶
AccessRequest describes an operation that requires authorization. Resource and Action use well-known string constants defined below. Target is operation-specific (e.g., a file path, environment variable name, or library name).
type Authorizer ¶
type Authorizer interface {
Authorize(req AccessRequest) error
}
Authorizer decides whether an operation is allowed. Implementations must be safe for concurrent use.
Authorize returns nil to allow the operation, or an error wrapping ErrAccessDenied to deny it. Returning a non-nil error that does not wrap ErrAccessDenied is treated as a deny with an unexpected cause.
Deny-error wrapping convention: an Authorizer should return the bare ErrAccessDenied sentinel. CheckWithAuthorizer wraps every denial with the operation's action, resource, and target, so that context is always present without each authorizer repeating it. An Authorizer should add an inner reason (still wrapping ErrAccessDenied) only when the reason is not derivable from action+resource+target — for example FilesystemRoot reports the confining root ("path %q outside root %q"), which the operation fields alone cannot convey. errors.Is(err, ErrAccessDenied) matches either form.
func All ¶
func All(authorizers ...Authorizer) Authorizer
All returns an Authorizer that requires every authorizer in the list to allow the operation. The first denial short-circuits and its error is returned. An empty list allows everything.
func ConsoleAuthorizer ¶ added in v1.14.244
func ConsoleAuthorizer() Authorizer
ConsoleAuthorizer returns an Authorizer for the Console profile. File operations are restricted to /tmp. Environment variable reads are allowed (the envvars primitive handles virtual-vs-OS routing). Code loading and process execution are denied.
Containment is symlink-resolved (see containedInRoot), so a symlink staged inside /tmp that points outside /tmp does not escape the sandbox. The authorizer also reports /tmp as its ConfinementRoot, so file primitives open through os.Root for race-free containment.
func ConsoleWithLoadAuthorizer ¶ added in v1.14.244
func ConsoleWithLoadAuthorizer() Authorizer
ConsoleWithLoadAuthorizer returns an Authorizer for the ConsoleWithLoad profile. File operations and code loading are both restricted to /tmp. Environment variable reads are allowed. Process execution is denied.
This is the security envelope wile-goast and similar embedders use to run sandboxed (eval ...) and (load ...) on Scheme files staged in /tmp.
Containment is symlink-resolved (see containedInRoot), so a symlink staged inside /tmp that points outside /tmp does not escape the sandbox. Dynamic code evaluation (code:eval, from (eval <datum>)/(compile <datum>)) has no path to restrict and is allowed here so the profile's documented sandboxed (eval ...) keeps working; the side effects of evaluated code remain gated at their own file/process/env sinks.
func FilesystemRoot ¶
func FilesystemRoot(root string) Authorizer
FilesystemRoot returns an Authorizer that restricts file and code operations to paths under root. Non-file/code resources are allowed.
Containment is symlink-resolved (see containedInRoot): both root and target are canonicalised, so a symlink under root that points outside it is followed and rejected, while the root itself may legitimately be a symlink. Paths that do not exist yet (e.g. a file about to be created) are still admitted as long as their existing ancestry stays within root.
func FromContext ¶
func FromContext(ctx context.Context) Authorizer
FromContext returns the Authorizer stored in ctx, or nil if none.
func ReadOnly ¶
func ReadOnly() Authorizer
ReadOnly returns an Authorizer that allows read and stat operations but denies everything else — including write, delete, exit, and code load.
ReadOnly does NOT permit ActionLoad: loading a file compiles and runs its contents, which is not a read-only operation. Callers that genuinely need to load code under an otherwise read-only policy should use ReadOnlyWithLoad.
ReadOnly applies NO path confinement — it allows reads of any path the host process can reach. Compose it with FilesystemRoot via All(...) to bound which paths may be read.
func ReadOnlyWithLoad ¶ added in v1.17.0
func ReadOnlyWithLoad() Authorizer
ReadOnlyWithLoad returns an Authorizer identical to ReadOnly but also permitting ActionLoad (loading and running code from a resolved file path).
Like ReadOnly it applies NO path confinement; compose it with FilesystemRoot via All(...) to bound which paths may be read or loaded.
func SandboxAuthorizer ¶ added in v1.14.244
func SandboxAuthorizer(envPrefix string) Authorizer
SandboxAuthorizer returns an Authorizer that allows read-only file access, env reads with a prefix filter, and denies code loading and process execution.
Intended as a restrictive modifier that can be composed with a profile's built-in authorizer via All() to produce an intersection (most-restrictive-wins).
type AuthorizerFunc ¶
type AuthorizerFunc func(AccessRequest) error
AuthorizerFunc adapts a plain function to the Authorizer interface.
func (AuthorizerFunc) Authorize ¶
func (p AuthorizerFunc) Authorize(req AccessRequest) error
Authorize implements Authorizer.
type RootConfined ¶ added in v1.17.0
type RootConfined interface {
// ConfinementRoot returns the directory file access is confined to, and
// ok=true, when this authorizer is root-confining. ok=false means the
// authorizer imposes no single-root file confinement.
ConfinementRoot() (root string, ok bool)
}
RootConfined is implemented by authorizers that confine filesystem access to a single directory subtree. When an authorizer reports a confinement root, file primitives open paths through os.Root, giving race-free, syscall-level containment that closes the TOCTOU gap between the policy check (Authorize) and the open.
Source Files