Help us shape the future of Go! Take the 2026 Go Developer Survey

secrets

package
v1.4.15 Latest Latest
Warning

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

 Go to latest Published: Oct 19, 2026 License: MIT Imports: 19 Imported by: 0

Documentation

Overview

Package secrets — rotation scheduling, dual-key windows, and expiry alerts.

Package secrets implements encrypted secrets management for nSelf projects using age encryption (https://age-encryption.org).

Secrets are stored as age-encrypted JSON files per environment: 

.secrets/dev.age, .secrets/staging.age, .secrets/prod.age

Each file encrypts to one or more age recipients (public keys), allowing team-based access control.

Index

Constants

View Source 
const SecretsDir = ".secrets"

SecretsDir is the directory name under the project root.

Variables

This section is empty.

Functions

func AddSchedule added in v1.0.12 

func AddSchedule(projectRoot, secretName string, cadenceDays, windowDays int) error

AddSchedule adds or updates a named rotation schedule entry.

func AppendRotationEvent added in v1.0.12 

func AppendRotationEvent(projectRoot, secretName, status, note string) error

AppendRotationEvent adds a rotation event to the log.

func AuditResolve added in v1.4.14 

func AuditResolve(sink AuditFunc, req ResolveRequest, outcome string) error

AuditResolve is shared with command refusals; never pass values to the sink. A failed sink is deliberately not wrapped: sink errors are not trusted text.

func DecryptForDeploy 

func DecryptForDeploy(projectRoot, env string) (string, error)

DecryptForDeploy decrypts secrets and outputs them as KEY=VALUE lines suitable for .env.computed or CI/CD injection.

func DeployKeys added in v1.4.14 

func DeployKeys(projectRoot, env string) ([]string, error)

DeployKeys returns the sorted key names of the store DecryptForDeploy reads, on the same two paths (DEPLOY_AGE_KEY, else the local store). Callers that must name the keys without handling the values (the --json envelope) use this instead of parsing DecryptForDeploy's text, where a multi-line value can look like a KEY= line.

func EnsureAgeInstalled 

func EnsureAgeInstalled() error

EnsureAgeInstalled checks that the age CLI is available.

func FileFor added in v1.4.14 

func FileFor(projectRoot, home string, r Ref) (path, source string, err error)

FileFor revalidates Ref so manually constructed refs cannot escape a root.

func Get 

func Get(projectRoot, env, key string) (string, error)

Get retrieves a secret value.

func GetPublicKey 

func GetPublicKey(keyPath string) (string, error)

GetPublicKey extracts the public key from an age key file.

func Init 

func Init(projectRoot string) error

Init generates an age keypair if one does not exist and sets up the .secrets directory with a .gitignore.

func InitSchedules 

func InitSchedules(projectRoot string) error

InitSchedules ensures all default schedules are present in the rotation state, computing NextDue from LastRotated or setting to now if never rotated.

func List 

func List(projectRoot, env string) ([]string, map[string]SecretEntry, error)

List returns all secret keys with metadata for an environment.

func Recipients added in v1.4.14 

func Recipients(req RecipientsRequest, sink AuditFunc) ([]string, bool, error)

Recipients loads only after all guards, and sanitizes every store error.

func Rekey 

func Rekey(projectRoot, removePubKey string) error

Rekey re-encrypts all secret files, removing the specified public key from the recipients list. Used when a team member leaves.

func RetireOldKey 

func RetireOldKey(projectRoot, env, key string) error

RetireOldKey removes the _PREVIOUS variant of a secret after the dual-key window.

func Rotate 

func Rotate(projectRoot, env, key string) (string, error)

Rotate generates a new value for a secret based on its type/name pattern.

func RotateDualWindow 

func RotateDualWindow(projectRoot, env, key string) error

RotateDualWindow generates a new key while keeping the old one as _PREVIOUS. The current value moves to KEY_PREVIOUS, and a new value is set as KEY_CURRENT.

func SaveRotationState 

func SaveRotationState(projectRoot string, state *RotationState) error

SaveRotationState persists the rotation schedule state to disk.

func Set 

func Set(projectRoot, env, key, value string) error

Set adds or updates a secret. The value is validated before it ever touches the store — see ValidateSecretValue for the exact rules (empty values, unexpanded shell references, bracketed placeholder tokens, and implausibly short values are all rejected).

func ValidateSecretValue added in v1.3.6 

func ValidateSecretValue(key, value string) error

ValidateSecretValue rejects a candidate secret value that cannot be a literal, working credential. It never returns the value in its error — callers must not either.

func VerifySecretExists added in v1.0.12 

func VerifySecretExists(projectRoot, env, secretName string) error

VerifySecretExists checks whether a named secret is present in the store for an environment. It returns nil when the secret is found; an error when it is missing or the store cannot be read. This provides a lightweight "verify" surface (value check without decrypting to stdout).

Types

type AuditFinding 

type AuditFinding struct {
	Key      string
	Issue    string
	Severity string
}

AuditFinding represents a single audit finding.

func Audit 

func Audit(projectRoot, env string) ([]AuditFinding, error)

Audit checks for secrets that haven't been rotated in over 90 days.

type AuditFunc added in v1.4.14 

type AuditFunc func(event string, fields map[string]string) error

AuditFunc records value-free event fields and reports sink failures.

type LintFinding 

type LintFinding struct {
	File    string `json:"File"`
	Rule    string `json:"RuleID"`
	Message string `json:"Description"`
	Line    int    `json:"StartLine"`
}

LintFinding represents a detected secret in source code.

func LintSecrets 

func LintSecrets(projectRoot string) ([]LintFinding, error)

LintSecrets checks for plaintext secrets in git-tracked files.

type RecipientsRequest added in v1.4.14 

type RecipientsRequest struct {
	ProjectRoot, File, Action, Recipient string
	AllowReleaseClass                    bool
}

RecipientsRequest selects a store and an owner-authorized recipient operation.

type Ref added in v1.4.14 

type Ref struct{ Raw, Class, Env, Name string }

Ref contains a validated secret reference and its class, environment and name.

func ParseRef added in v1.4.14 

func ParseRef(s string) (Ref, error)

ParseRef validates the complete D5 grammar before any store access.

type ResolveRequest added in v1.4.14 

type ResolveRequest struct {
	ProjectRoot string
	Refs        []string
	AttemptID   string
}

ResolveRequest selects ordered references for an audited attempt in a project.

type RotationLog added in v1.0.12 

type RotationLog struct {
	Events    []RotationLogEntry `json:"events"`
	UpdatedAt string             `json:"updated_at"`
}

RotationLog represents all recorded rotation events.

func LoadRotationLog added in v1.0.12 

func LoadRotationLog(projectRoot string) (*RotationLog, error)

LoadRotationLog reads the rotation event log from disk.

type RotationLogEntry added in v1.0.12 

type RotationLogEntry struct {
	SecretName string `json:"secret_name"`
	RotatedAt  string `json:"rotated_at"`
	Status     string `json:"status"` // ok|failed|rolled_back
	Note       string `json:"note,omitempty"`
}

RotationLogEntry is a single event in the rotation event log.

type RotationSchedule 

type RotationSchedule struct {
	SecretName  string `json:"secret_name"`
	CadenceDays int    `json:"cadence_days"`
	WindowDays  int    `json:"window_days"` // dual-key overlap window
	LastRotated string `json:"last_rotated,omitempty"`
	NextDue     string `json:"next_due,omitempty"`
}

RotationSchedule defines when and how a secret should be rotated.

func DefaultSchedules 

func DefaultSchedules() []RotationSchedule

DefaultSchedules returns the minimum set of tracked secrets per the spec.

type RotationState 

type RotationState struct {
	Schedules []RotationSchedule `json:"schedules"`
	UpdatedAt string             `json:"updated_at"`
}

RotationState is the persisted state for all tracked secret schedules.

func LoadRotationState 

func LoadRotationState(projectRoot string) (*RotationState, error)

LoadRotationState reads the rotation schedule state from disk.

type ScheduleCheck 

type ScheduleCheck struct {
	SecretName  string        `json:"secret_name"`
	CadenceDays int           `json:"cadence_days"`
	WindowDays  int           `json:"window_days"`
	LastRotated string        `json:"last_rotated"`
	NextDue     string        `json:"next_due"`
	DueIn       time.Duration `json:"-"`
	DueInDays   int           `json:"due_in_days"`
	Status      string        `json:"status"` // ok, warning, overdue, missing
}

ScheduleCheck represents the result of checking one secret's rotation schedule.

func CheckSchedule 

func CheckSchedule(projectRoot string) ([]ScheduleCheck, error)

CheckSchedule validates all rotation schedules and returns findings.

type SecretEntry 

type SecretEntry struct {
	Value     string `json:"value"`
	CreatedAt string `json:"created_at"`
	UpdatedAt string `json:"updated_at"`
	RotatedAt string `json:"rotated_at,omitempty"`
}

SecretEntry represents a single secret with metadata.

type SecretStore 

type SecretStore struct {
	Secrets    map[string]SecretEntry `json:"secrets"`
	Recipients []string               `json:"recipients"`
	UpdatedAt  string                 `json:"updated_at"`
}

SecretStore is the full set of secrets for one environment.

type Value added in v1.4.14 

type Value struct {
	Ref       string  `json:"ref"`
	EnvName   string  `json:"env_name"`
	Value     string  `json:"value"`
	Source    string  `json:"source"`
	ExpiresAt *string `json:"expires_at"`
}

Value is a resolved secret with its environment variable name and source.

func Resolve added in v1.4.14 

func Resolve(ctx context.Context, req ResolveRequest, sink AuditFunc) (values []Value, err error)

Resolve audits exactly once, including validation failures and partial loads. Audit failure drops all values. All refs and collisions are checked first.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.