dynamic

package
v1.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 31, 2026 License: MPL-2.0 Imports: 6 Imported by: 0

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

View Source
const MaxTTLSeconds int64 = math.MaxInt64 / int64(time.Second)

MaxTTLSeconds is the largest whole-second TTL representable by time.Duration.

Variables

View Source
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

func GeneratePassword() (string, error)

GeneratePassword returns a high-entropy alphanumeric credential. Rejection sampling keeps the distribution uniform over the alphabet.

func RoleName

func RoleName(leaseID string) string

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

func TTLDuration(seconds int64) (time.Duration, error)

TTLDuration validates a positive lease TTL before converting seconds to a duration. Callers handle an omitted renewal ceiling before calling this helper.

func ValidPassword

func ValidPassword(s string) bool

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

func ValidRoleName(s string) bool

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

type CreateRoleRequest struct {
	Name       string
	Password   string
	GrantRole  string
	ValidUntil time.Time
}

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

type Factory func(kind Kind, origin, tlsMode, credential string) (Provider, error)

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"

func ParseKind

func ParseKind(s string) (Kind, error)

ParseKind rejects an unknown provider kind rather than defaulting one.

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

type RoleStatus struct {
	Exists     bool
	ValidUntil time.Time
}

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.

Directories

Path Synopsis
Package postgres implements the dynamic-secret Provider seam over a PostgreSQL engine.
Package postgres implements the dynamic-secret Provider seam over a PostgreSQL engine.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL