feat: implement timestamps metadata to indicate when secrets were last created/updates.

Author: BinSquare

README.md

@@ -22,13 +22,22 @@
 
 # envmap
 
-`envmap` keeps secrets out of your Git history by sourcing them from a provider (local encrypted store, AWS SSM, Vault, etc.) and injecting them directly into the target process. No `.env` files, no accidental commits, no “who has the latest .env?” in Slack.
+`envmap` is a local env manager that keeps laptops, CI, and feature branches in sync with the remote secret stores you already trust. Instead of copying `.env` files or manually editing it, every repo declares a typed mapping of `env → provider path`, and you run `envmap run -- npm start` (or any command) to launch processes with fresh, provider-backed variables.
 
-## Why?
+For devs not using a remote secrets manager - it doubles as an env-set switcher: define dev/staging/prod mappings once and jump between them without ever touching a plaintext `.env`. No more editing files or committing accidental changes or need to have a plaintext file with all your secrets exposed.
 
-- `.env` files are easy to leak and hard to rotate across multiple engineers and machines.
-- Most teams already have a secrets backend (or should); local dev is the messy part.
-- `envmap` gives each repo a single, typed mapping from “env name → provider path” and a consistent `envmap run -- <cmd>` entrypoint.
+### Core benefits
+
+- **Faster onboarding** – a new engineer can clone the repo, run `envmap init`, and immediately inherit the exact env vars if the remote secret stores are configured.
+- **Parity across environments** – map each env to its provider path once and guarantee that laptops, CI, and staging all get the right variables.
+- **Safer secret handling** – secrets live in providers, not Slack or git; rotations propagate automatically, and values never persist past the process lifetime.
+
+### Why?
+
+- Individual developers juggling multiple `.env` variants locally (dev vs staging vs production) without rewriting files or commenting out envs.
+- `.env` files are easy to leak, tough to rotate, and drift across environments.
+- Most teams already run a real secrets backend; envmap simply brings those secrets to local dev in a reproducible way.
+- A single `envmap run -- <cmd>` entrypoint ensures your tooling, CI, and developers share one contract for acquiring secrets.
 
 ## Installation
 

env.go

@@ -27,6 +27,18 @@ func NewProvider(envName string, envCfg EnvConfig, globalCfg GlobalConfig) (prov
 }
 
 func CollectEnv(ctx context.Context, projectCfg ProjectConfig, globalCfg GlobalConfig, envName string) (map[string]string, error) {
+	records, err := CollectEnvWithMetadata(ctx, projectCfg, globalCfg, envName)
+	if err != nil {
+		return nil, err
+	}
+	out := make(map[string]string, len(records))
+	for k, rec := range records {
+		out[k] = rec.Value
+	}
+	return out, nil
+}
+
+func CollectEnvWithMetadata(ctx context.Context, projectCfg ProjectConfig, globalCfg GlobalConfig, envName string) (map[string]provider.SecretRecord, error) {
 	envCfg, ok := projectCfg.Envs[envName]
 	if !ok {
 		return nil, fmt.Errorf("env %q not found in project config", envName)
@@ -35,7 +47,7 @@ func CollectEnv(ctx context.Context, projectCfg ProjectConfig, globalCfg GlobalC
 	if err != nil {
 		return nil, err
 	}
-	return p.List(ctx, provider.ResolvedPrefix(envCfg.ToProviderConfig()))
+	return provider.ListOrDescribe(ctx, p, provider.ResolvedPrefix(envCfg.ToProviderConfig()))
 }
 
 func FetchSecret(ctx context.Context, projectCfg ProjectConfig, globalCfg GlobalConfig, envName, key string) (string, error) {

main.go

@@ -9,6 +9,7 @@ import (
 	"path/filepath"
 	"sort"
 	"strings"
+	"time"
 
 	"github.com/binsquare/envmap/provider"
 	"github.com/spf13/cobra"
@@ -132,26 +133,34 @@ func newEnvCmd() *cobra.Command {
 			if err != nil {
 				return err
 			}
-			secretEnv, err := CollectEnv(cmd.Context(), projectCfg, globalCfg, envToUse)
+			records, err := CollectEnvWithMetadata(cmd.Context(), projectCfg, globalCfg, envToUse)
 			if err != nil {
 				return err
 			}
 
 			// Sort keys for consistent output
-			keys := make([]string, 0, len(secretEnv))
-			for k := range secretEnv {
+			keys := make([]string, 0, len(records))
+			for k := range records {
 				keys = append(keys, k)
 			}
 			sort.Strings(keys)
 
 			fmt.Fprintf(os.Stderr, "# env: %s (%d secrets)\n", envToUse, len(keys))
 			for _, k := range keys {
-				v := secretEnv[k]
+				rec := records[k]
+				v := rec.Value
 				if raw {
-					fmt.Printf("%s=%s\n", k, v)
+					fmt.Printf("%s=%s", k, v)
 				} else {
-					fmt.Printf("%s=%s\n", k, MaskValue(v))
+					fmt.Printf("%s=%s", k, MaskValue(v))
+				}
+				if !rec.CreatedAt.IsZero() {
+					fmt.Printf("  # created %s", rec.CreatedAt.UTC().Format(time.RFC3339))
+					if age := humanizeAge(rec.CreatedAt); age != "" {
+						fmt.Printf(" (%s ago)", age)
+					}
 				}
+				fmt.Println()
 			}
 			return nil
 		},
@@ -244,6 +253,30 @@ func isSimpleValue(s string) bool {
 	return len(s) > 0
 }
 
+func humanizeAge(created time.Time) string {
+	if created.IsZero() {
+		return ""
+	}
+	d := time.Since(created)
+	if d < 0 {
+		d = 0
+	}
+	switch {
+	case d < time.Minute:
+		return fmt.Sprintf("%ds", int(d.Seconds()))
+	case d < time.Hour:
+		return fmt.Sprintf("%dm", int(d.Minutes()))
+	case d < 24*time.Hour:
+		return fmt.Sprintf("%dh", int(d.Hours()))
+	case d < 30*24*time.Hour:
+		return fmt.Sprintf("%dd", int(d.Hours()/24))
+	case d < 365*24*time.Hour:
+		return fmt.Sprintf("%dmo", int(d.Hours()/(24*30)))
+	default:
+		return fmt.Sprintf("%dyr", int(d.Hours()/(24*365)))
+	}
+}
+
 func newSetCmd() *cobra.Command {
 	var envName string
 	var fromFile string

provider/local.go

@@ -15,6 +15,7 @@ import (
 	"path/filepath"
 	"strings"
 	"sync"
+	"time"
 
 	"github.com/gofrs/flock"
 	"golang.org/x/crypto/hkdf"
@@ -47,6 +48,8 @@ type localFile struct {
 	mu          sync.Mutex
 }
 
+var _ MetadataLister = (*localFile)(nil)
+
 func newLocalFile(envCfg EnvConfig, providerCfg ProviderConfig) (Provider, error) {
 	if providerCfg.Path == "" {
 		return nil, fmt.Errorf("local-file provider missing path")
@@ -83,31 +86,21 @@ func (p *localFile) Get(_ context.Context, name string) (string, error) {
 		if !ok {
 			return fmt.Errorf("missing secret %s for env (expected from %s)", name, p.path)
 		}
-		value = val
+		value = val.Value
 		return nil
 	})
 	return value, err
 }
 
-func (p *localFile) List(_ context.Context, prefix string) (map[string]string, error) {
-	out := make(map[string]string)
-	err := p.withExclusiveLock(func() error {
-		entries, err := p.readAllUnlocked()
-		if err != nil {
-			return err
-		}
-		for name, val := range entries {
-			if prefix != "" && !strings.HasPrefix(name, ensurePrefixSlash(prefix)) {
-				continue
-			}
-			base := TrimPrefix(p.envCfg, name)
-			out[base] = val
-		}
-		return nil
-	})
+func (p *localFile) List(ctx context.Context, prefix string) (map[string]string, error) {
+	records, err := p.ListWithMetadata(ctx, prefix)
 	if err != nil {
 		return nil, err
 	}
+	out := make(map[string]string, len(records))
+	for k, rec := range records {
+		out[k] = rec.Value
+	}
 	return out, nil
 }
 
@@ -117,13 +110,18 @@ func (p *localFile) Set(_ context.Context, name, value string) error {
 		if err != nil {
 			return err
 		}
-		entries[name] = value
+		entry := entries[name]
+		if entry.CreatedAt.IsZero() {
+			entry.CreatedAt = time.Now().UTC()
+		}
+		entry.Value = value
+		entries[name] = entry
 		return p.writeAllUnlocked(entries)
 	})
 }
 
-func (p *localFile) readAllUnlocked() (map[string]string, error) {
-	entries := map[string]string{}
+func (p *localFile) readAllUnlocked() (map[string]SecretRecord, error) {
+	entries := map[string]SecretRecord{}
 	raw, err := os.ReadFile(p.path)
 	if err != nil {
 		if errors.Is(err, os.ErrNotExist) {
@@ -144,7 +142,7 @@ func (p *localFile) readAllUnlocked() (map[string]string, error) {
 	return entries, nil
 }
 
-func (p *localFile) writeAllUnlocked(entries map[string]string) error {
+func (p *localFile) writeAllUnlocked(entries map[string]SecretRecord) error {
 	encoded, err := json.MarshalIndent(entries, "", "  ")
 	if err != nil {
 		return fmt.Errorf("encode local store: %w", err)
@@ -199,6 +197,28 @@ func (p *localFile) writeAllUnlocked(entries map[string]string) error {
 	return nil
 }
 
+func (p *localFile) ListWithMetadata(_ context.Context, prefix string) (map[string]SecretRecord, error) {
+	out := make(map[string]SecretRecord)
+	err := p.withExclusiveLock(func() error {
+		entries, err := p.readAllUnlocked()
+		if err != nil {
+			return err
+		}
+		for name, val := range entries {
+			if prefix != "" && !strings.HasPrefix(name, ensurePrefixSlash(prefix)) {
+				continue
+			}
+			base := TrimPrefix(p.envCfg, name)
+			out[base] = val
+		}
+		return nil
+	})
+	if err != nil {
+		return nil, err
+	}
+	return out, nil
+}
+
 func (p *localFile) withExclusiveLock(fn func() error) error {
 	if err := p.lock.Lock(); err != nil {
 		return fmt.Errorf("acquire lock %s: %w", p.lock.Path(), err)

provider/local_test.go

@@ -0,0 +1,76 @@
+package provider
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+)
+
+func TestLocalFileStoresCreatedAt(t *testing.T) {
+	t.Parallel()
+
+	dir := t.TempDir()
+	keyPath := filepath.Join(dir, "key")
+	if err := os.WriteFile(keyPath, bytesOfLen(32), 0o600); err != nil {
+		t.Fatalf("write key: %v", err)
+	}
+	cfg := ProviderConfig{
+		Path: filepath.Join(dir, "secrets.db"),
+		Encryption: &EncryptionConfig{
+			KeyFile: keyPath,
+		},
+	}
+	envCfg := EnvConfig{PathPrefix: "/app/dev"}
+
+	p, err := newLocalFile(envCfg, cfg)
+	if err != nil {
+		t.Fatalf("newLocalFile: %v", err)
+	}
+	lf := p.(*localFile)
+
+	ctx := context.Background()
+	fullKey := ApplyPrefix(envCfg, "DB_URL")
+	if err := lf.Set(ctx, fullKey, "postgres://example"); err != nil {
+		t.Fatalf("Set: %v", err)
+	}
+
+	records, err := lf.ListWithMetadata(ctx, ResolvedPrefix(envCfg))
+	if err != nil {
+		t.Fatalf("ListWithMetadata: %v", err)
+	}
+	rec, ok := records["DB_URL"]
+	if !ok {
+		t.Fatalf("expected DB_URL to be returned, got keys %v", records)
+	}
+	if rec.Value != "postgres://example" {
+		t.Fatalf("value mismatch: got %q", rec.Value)
+	}
+	if rec.CreatedAt.IsZero() {
+		t.Fatalf("expected CreatedAt to be set")
+	}
+
+	// Reopen provider to ensure CreatedAt persisted to disk.
+	time.Sleep(10 * time.Millisecond) // allow measurable difference if overwritten
+	p2, err := newLocalFile(envCfg, cfg)
+	if err != nil {
+		t.Fatalf("re-open newLocalFile: %v", err)
+	}
+	records2, err := p2.(*localFile).ListWithMetadata(ctx, ResolvedPrefix(envCfg))
+	if err != nil {
+		t.Fatalf("ListWithMetadata second read: %v", err)
+	}
+	rec2 := records2["DB_URL"]
+	if !rec.CreatedAt.Equal(rec2.CreatedAt) {
+		t.Fatalf("created timestamps differ: first=%v second=%v", rec.CreatedAt, rec2.CreatedAt)
+	}
+}
+
+func bytesOfLen(n int) []byte {
+	buf := make([]byte, n)
+	for i := range buf {
+		buf[i] = byte(1 + (i % 250))
+	}
+	return buf
+}

provider/metadata.go

@@ -0,0 +1,35 @@
+package provider
+
+import (
+	"context"
+	"time"
+)
+
+// SecretRecord carries a secret's value plus optional metadata for presentation.
+type SecretRecord struct {
+	Value     string    `json:"value"`
+	CreatedAt time.Time `json:"created_at,omitempty"`
+}
+
+// MetadataLister can return values plus metadata in one call.
+type MetadataLister interface {
+	ListWithMetadata(ctx context.Context, prefix string) (map[string]SecretRecord, error)
+}
+
+// ListOrDescribe fetches secrets with metadata when the provider supports it.
+// For providers that do not expose metadata, the map still contains values,
+// but CreatedAt is left zero to signal "unknown".
+func ListOrDescribe(ctx context.Context, p Provider, prefix string) (map[string]SecretRecord, error) {
+	if lister, ok := p.(MetadataLister); ok {
+		return lister.ListWithMetadata(ctx, prefix)
+	}
+	values, err := p.List(ctx, prefix)
+	if err != nil {
+		return nil, err
+	}
+	records := make(map[string]SecretRecord, len(values))
+	for k, v := range values {
+		records[k] = SecretRecord{Value: v}
+	}
+	return records, nil
+}