Documentation
¶
Overview ¶
Package dynamic defines the compiled-in dynamic-secret provider seam and the credential-material generator. A Provider mints, extends, probes, and drops a short-lived credential at an external engine; it never reads a secret back out. The first (and only v1) implementation is internal/dynamic/postgres.
Index ¶
Constants ¶
MaxTTLSeconds is the largest whole-second TTL representable by time.Duration.
Variables ¶
var ( // ErrUnreachable is a definite failure: the provider could not be reached // or authenticated, so no statement ran. ErrUnreachable = errors.New("dynamic: provider unreachable") // ErrAmbiguous is an uncertain outcome: a statement was sent but its result // is unknown. Never treated as success. ErrAmbiguous = errors.New("dynamic: provider outcome ambiguous") // ErrRefused is a DEFINITE failure the engine reported: a statement reached // the server and it answered with an error (a missing grant role, a // privilege refusal, a syntax error). The role state is known — the DDL did // not take effect — so the lease settles to a terminal failure, not unknown. ErrRefused = errors.New("dynamic: provider refused the request") )
Sentinel errors classify a provider outcome so the caller can decide state. A definite failure means nothing durable changed at the provider (a connect refusal before any statement); an ambiguous outcome means a statement may or may not have taken effect (a deadline or network error after send) and MUST NOT be reported as success: the lease enters `unknown` and reconcile settles it by re-probing.
Functions ¶
func GeneratePassword ¶
GeneratePassword returns a high-entropy alphanumeric credential. Rejection sampling keeps the distribution uniform over the alphabet.
func RoleName ¶
RoleName derives a stable, engine-safe role name from a lease id. The lease id is already unique, so the derived name is too.
func TTLDuration ¶
TTLDuration validates a positive lease TTL before converting seconds to a duration. Callers handle an omitted renewal ceiling before calling this helper.
func ValidPassword ¶
ValidPassword reports whether s is exactly the generated shape: the fixed length over the fixed alphabet. The provider refuses anything else before building SQL, so a value that somehow arrived off-charset never reaches the engine.
func ValidRoleName ¶
ValidRoleName reports whether s is a well-formed Hikyo role name: the fixed prefix followed by lowercase alphanumerics, within the identifier limit.
Types ¶
type CreateRoleRequest ¶
CreateRoleRequest is one lease mint at the provider. GrantRole is the parent role the minted role inherits (IN ROLE), so a lease role is not privilege- less; ValidUntil is enforced by the engine itself as a PASSWORD expiry: new logins are refused after it even if Hikyo is down, while sessions already open are not ended by it (see the postgres provider's createRoleSQL).
type Factory ¶
Factory builds a Provider for one operation from the sealed-then-opened admin credential and the provider's stored origin/tls_mode. The app supplies it, closing over the egress policy and connection deadline, so the service and worker never name a concrete engine package. The caller Closes the Provider when the operation ends.
type Kind ¶
type Kind string
Kind is the closed provider enum. A row or request naming anything else is refused by the default arm of every switch (fail-closed).
const KindPostgres Kind = "postgres"
type Provider ¶
type Provider interface {
CreateRole(ctx context.Context, req CreateRoleRequest) error
ExtendRole(ctx context.Context, name string, validUntil time.Time) error
DropRole(ctx context.Context, name string) error
RoleStatus(ctx context.Context, name string) (RoleStatus, error)
// Close releases pooled connections and forgets the admin credential.
Close()
}
Provider is the closed four-operation seam. No method reads a credential value back; there is no arbitrary-SQL escape hatch. A reflection test pins this interface so it cannot grow one silently.
type RoleStatus ¶
RoleStatus is what a re-probe learns: whether the role exists and, if so, until when it is valid. Reconcile uses ValidUntil to settle a renew, not just a mint or revoke.