Documentation
¶
Overview ¶
Package auth provides shared authentication primitives for the stackkit CLI and supporting libraries: the HS256 service-auth JWT signer and the HS256/EdDSA verifier for inbound service-to-service calls.
Wire-format mirrors kombify-go-common/servicecall.IssueToken byte-for-byte so admin's tryServiceAuth verifier accepts our tokens. Kept inline (not pulled from go-common) because servicekit cannot import go-common as a module without changing the repo's external-dependency posture.
Index ¶
Constants ¶
const ( EnvEd25519PublicKeys = "SERVICE_AUTH_ED25519_PUBLIC_KEYS" EnvRequireEd25519 = "SERVICE_AUTH_REQUIRE_ED25519" )
Per-caller Ed25519 service identity, wire-compatible with kombify-go-common/servicecall (kept inline for the same reason as SignServiceToken). A receiver holds only public keys, each bound to one caller service, so it can neither mint tokens nor let one caller speak for another. HS256 stays accepted until SERVICE_AUTH_REQUIRE_ED25519=true.
const DefaultTokenTTL = 5 * time.Minute
DefaultTokenTTL is the default expiry duration for a minted token. Short by design: replays are bounded to 5 minutes.
const HeaderServiceAuth = "X-Kombify-Service-Auth"
HeaderServiceAuth is the HTTP header that carries the signed token. Must equal kombify-Administration's HEADER_SERVICE_AUTH constant.
Variables ¶
var ErrInvalidKeyMaterial = errors.New("auth: invalid Ed25519 key material")
ErrInvalidKeyMaterial reports a malformed public key set.
Functions ¶
func LoadEd25519FromEnv ¶ added in v0.54.8
func LoadEd25519FromEnv() (map[string]CallerPublicKey, bool, error)
LoadEd25519FromEnv reads SERVICE_AUTH_ED25519_PUBLIC_KEYS and SERVICE_AUTH_REQUIRE_ED25519. Absent variables yield no keys and false.
func ParseCallerPublicKeys ¶ added in v0.54.8
func ParseCallerPublicKeys(raw string) (map[string]CallerPublicKey, error)
ParseCallerPublicKeys parses "<svc>:<kid>=<base64url key>,...". A malformed entry or a duplicate kid fails the whole set, so a typo never silently disables verification.
func SignServiceToken ¶
SignServiceToken mints an HS256 service-auth JWT.
svc service slug (the caller; e.g. "stackkits") target service slug being called (e.g. "administration") secret shared signing secret (SERVICE_AUTH_SECRET from the deployment's secret store) ttl token lifetime; <=0 falls back to DefaultTokenTTL
Returns "header.payload.signature" with each part base64url-encoded without padding. Admin's tryServiceAuth verifies signature + audience (kombify-<target>) + caller-allowlist (svc).
Types ¶
type CallerPublicKey ¶ added in v0.54.8
CallerPublicKey is a verification key bound to one caller service id.
type Claims ¶
type Claims struct {
Iss string `json:"iss"`
Aud string `json:"aud"`
Iat int64 `json:"iat"`
Exp int64 `json:"exp"`
Svc string `json:"svc"`
RequestID string `json:"reqId,omitempty"`
}
Claims is the JSON shape inside the JWT payload. Kept minimal — admin only inspects iss/aud/iat/exp/svc.
func VerifyServiceToken ¶
func VerifyServiceToken(token string, opts VerifyOptions) (*Claims, error)
VerifyServiceToken verifies a service-auth JWT minted by SignServiceToken or kombify-go-common/servicecall.IssueToken: EdDSA against the caller-bound public keys, HS256 against the shared secrets unless RequireEd25519 is set.
type VerifyOptions ¶
type VerifyOptions struct {
Target string
Secrets []string
AllowedCallers []string
Now func() time.Time
Leeway time.Duration
// CallerPublicKeys verifies EdDSA tokens by kid; each key speaks only for
// its bound caller service (SERVICE_AUTH_ED25519_PUBLIC_KEYS).
CallerPublicKeys map[string]CallerPublicKey
// RequireEd25519 rejects HS256 tokens (SERVICE_AUTH_REQUIRE_ED25519).
RequireEd25519 bool
}
VerifyOptions configures service-auth JWT verification for inbound calls.
Source Files