Documentation
¶
Overview ¶
Package machineauth is the machine-surface bearer token: where it comes from, how it is created, how a request is checked against it, and which bind addresses may carry it.
Purpose: P7-SURF-25 (EPIC SURF D4). The MCP server (and later the HTTP
control API) needs one token source with one set of safety rules, so no command re-implements them.
Inputs: the NSELF_MCP_TOKEN environment variable, the file
~/.nself/mcp-token, and the user's home directory.
Outputs: a token plus its source ("env", "file" or "generated"), an
http.Handler middleware, and bind-address checks. Every refusal is an errs E426 error.
Constraints: Lookup never writes anything; only Resolve creates the token
file, and only when Lookup finds none. A token value is never written to any stream (Resolve prints the file path only). Layer L1: this package imports only the standard library and internal/errs.
SPORT: CLI-CAP-MACHINE-AUTH-001
Index ¶
- Constants
- func CheckBind(host string, allowedHosts []string, source string) error
- func IsLoopback(host string) bool
- func Lookup() (tok, source string, err error)
- func Middleware(tok, realm string) func(http.Handler) http.Handler
- func Resolve() (tok, source string, generated bool, err error)
- func ResolveTo(notice io.Writer) (tok, source string, generated bool, err error)
- func TokenPath() (string, error)
Constants ¶
const ( SourceEnv = "env" SourceFile = "file" SourceGenerated = "generated" )
Token sources reported by Lookup and Resolve.
const EnvVar = "NSELF_MCP_TOKEN"
EnvVar is the environment variable that carries the machine token.
Variables ¶
This section is empty.
Functions ¶
func CheckBind ¶
CheckBind returns nil for a loopback host. A non-loopback host passes only with at least one non-empty allowedHosts entry and a configured token (source "env" or "file"); otherwise it is refused with E426.
func IsLoopback ¶
IsLoopback reports whether host is a loopback bind address: "localhost", any 127.0.0.0/8 address, or ::1 (with or without brackets). The empty host, 0.0.0.0 and :: bind every interface and are not loopback.
func Lookup ¶
Lookup finds the configured token without creating anything. The environment variable wins (source "env"); otherwise an existing token file is used (source "file"). With neither it returns "", "", nil. A token file that is a symlink, not a regular file, readable by group or others (non-Windows) or empty is refused with E426.
func Middleware ¶
Middleware returns a wrapper that serves the next handler only when the request presents "Authorization: Bearer <tok>". Otherwise it answers 401 with the body "unauthorized" and a WWW-Authenticate: Bearer realm header. An empty tok rejects every request (fail closed), and so does a request that carries more than one Authorization header.
func Resolve ¶
Resolve is Lookup, then token generation when nothing is configured. It reports the new file path (never the token) on standard error.
Types ¶
This section is empty.
Source Files