PRJ-2026-03-gopass-personal-docs: Secure Credential Generator

1. Project Summary

Field Value

PRJ ID

PRJ-2026-03-gopass-personal-docs

Owner

Evan Rosado

Priority

P1

Category

Security / Personal Tooling

Status

Active (v2.2.0)

Repository

dots-quantum/bin/.local/bin/gopass-personal-docs

Stow Package

bin (symlinked to ~/.local/bin/)

Language

Bash

Lines

~4,014 → modular (16 files)

Created

2026-03-18

2. Purpose

Interactive CLI tool for generating structured gopass entries across 15 life categories. Ensures consistent YAML schema, proper secret handling, and organized credential storage.

2.1. Problem Solved

Without this tool, creating a gopass entry requires:

  1. Remembering the correct path structure (v3/domains/d000/identity/ise/…​)

  2. Knowing which fields each entry type needs

  3. Manually formatting YAML key-value pairs

  4. Risking inconsistent schemas across entries

gopass-personal-docs solves all of this with guided prompts, domain-aware paths, and enforced schemas.

2.2. Learning Value

This project teaches:

  • Modular shell architecture — sourced library files, source guards, function namespacing

  • Security coding — umask, trap for secret cleanup, input validation, hidden prompts

  • CLI UX design — colored output, interactive menus, argument parsing, defaults

  • Refactoring discipline — monolith → modular → library (same pattern as AsciiDoc partials)

  • Credential management — gopass/gpg/age encryption workflow

3. Architecture

3.1. Modular Structure (v2.2.0)

gopass-personal-docs                  # Entry point (~155 lines)
lib/gopass/
├── common.sh                         # Colors, prompts, entry creation, security
├── accounts.sh                       # Browser, email, developer, shopping, social, cloud
├── automotive.sh                     # Vehicles
├── documents.sh                      # SSN, passport, DL, birth cert
├── emergency.sh                      # ICE contacts
├── finance.sh                        # Cards, banks, investments, loans, HSA/FSA
├── government.sh                     # DMV, IRS, SSA, TSA
├── health.sh                         # Insurance, providers, medications, immunizations
├── housing.sh                        # Property, utilities, storage
├── infrastructure.sh                 # Firewall, switch, ISE, server, hypervisor, certs, wifi
├── insurance.sh                      # Auto, home, life
├── legal.sh                          # Will, POA, trust
├── recovery.sh                       # 2FA codes, recovery keys, seed phrases
├── subscriptions.sh                  # Streaming, software, memberships
└── travel.sh                         # Flights, hotels, car rentals, loyalty

3.2. Gopass Path Structure

Base Path Content

v3/personal/

Personal documents (SSN, passport, health, finance, legal)

v3/domains/d000/

Home lab infrastructure (ISE, VyOS, servers, certs)

v3/domains/d001/

CHLA work infrastructure (ISE, switches, services)

3.3. Security Measures

  • umask 077 — prevents other users from reading temp files

  • trap on EXIT — clears password variables from memory

  • read -rs — hidden input for all secrets

  • gopass + gpg-agent validation before any operations

  • Source guards prevent double-loading of libraries

  • No secrets ever written to stdout or logs

3.4. Entry Format

Every gopass entry follows the same YAML schema:

<primary-password>
---
type: <category>
hostname: <value>
username: <value>
# ... category-specific fields
notes: <value>
created: YYYY-MM-DD

First line is always the primary secret. Everything after --- is structured YAML metadata queryable with gopass show <path> <field>.

3.5. Key Design: One Entry Per Device, Multiple Credentials as Fields

<primary-admin-password>
---
type: ise
hostname: ise-02
ip: 10.50.1.21

credentials:
  admin:
    username: admin
    password: <password>
  cli:
    username: admin
    password: <password>
  dataconnect:
    username: dataconnect
    password: <password>
    port: 2484

ports:
  ers: 9060
  openapi: 443
  mnt: 443
  pxgrid: 8910

role: secondary
persona: mnt
created: 2026-04-02

NOT this (old pattern — creates entry sprawl):

v3/domains/d000/identity/ise/ise-01/admin        # separate entry
v3/domains/d000/identity/ise/ise-01/cli          # separate entry
v3/domains/d000/identity/ise/ise-01/dataconnect  # separate entry

Instead, one entry with all credentials as YAML fields:

v3/domains/d000/identity/ise/ise-01              # single entry, all fields

Query individual fields using sed + yq (skip password line, parse YAML):

# Get nested credential
gopass show v3/domains/d000/identity/ise/ise-01 | sed '1,/^---$/d' | yq -r '.credentials.cli.password'

# Get IP
gopass show v3/domains/d000/identity/ise/ise-01 | sed '1,/^---$/d' | yq -r '.ip'

# Get port
gopass show v3/domains/d000/identity/ise/ise-01 | sed '1,/^---$/d' | yq -r '.ports.ers'

# Using gpf helper (if added to .zshrc — see examples/codex/gopass/jq-patterns.adoc)
gpf v3/domains/d000/identity/ise/ise-01 credentials.admin.password
gpf v3/domains/d000/identity/ise/ise-01 ip

See include::example$codex/gopass/jq-patterns.adoc[] for the full pattern library including helper functions, batch operations, and error handling.

4. Categories (15)

# Category Functions Path

1

Documents

SSN, passport, DL, birth cert

v3/personal/documents/

2

Government

DMV, IRS, SSA, TSA

v3/personal/government/

3

Health

Insurance, providers, medications, immunizations, allergies, conditions, blood type

v3/personal/health/

4

Finance

Credit cards, banks, investments, loans, retirement, HSA/FSA, credit monitoring

v3/personal/finance/

5

Insurance

Auto, home/renters, life

v3/personal/insurance/

6

Legal

Will, POA, trust

v3/personal/legal/

7

Emergency

ICE contacts

v3/personal/emergency/

8

Automotive

Vehicles

v3/personal/automotive/

9

Housing

Property, utilities, storage

v3/personal/housing/

10

Travel

Flights, hotels, car rentals, loyalty programs

v3/personal/travel/

11

Subscriptions

Streaming, software, memberships

v3/personal/subscriptions/

12

Recovery

2FA backup codes, recovery keys, seed phrases, security questions

v3/personal/recovery/

13

Infrastructure

Cisco ISE, firewall, switch, wireless, server, hypervisor, service, certs, WiFi

v3/domains/<domain>/

14

Accounts

Browser (Firefox/Chrome), email, developer (GitHub), shopping, social, cloud (AWS/GCP), generic

v3/personal/accounts/

15

List entries

Browse existing gopass entries

 — 

5. Decision Log

Date Decision Rationale Decided By

2026-03-18

Bash, not Python

Must run anywhere gopass runs. No dependencies beyond coreutils. Sourced libraries for modularity.

Evan Rosado

2026-03-18

YAML format inside entries

Queryable with gopass show path field. Consistent schema enforced by prompts.

Evan Rosado

2026-04-01

Domain-aware paths (d000/d001)

Infrastructure credentials need domain separation. Personal docs stay at v3/personal/.

Evan Rosado

2026-04-01

Dedicated ISE function

ISE needs admin, CLI, DataConnect, ERS, pxGrid — too many credentials for generic "service" template.

Evan Rosado

2026-04-01

Modular library split

3,946 lines unmanageable. Split into 14 sourced libs + entry point. Each category independently editable.

Evan Rosado

2026-04-01

Security hardening (umask, trap)

Tool handles secrets — must not leak via temp files or residual memory. Professional security hygiene.

Evan Rosado

2026-04-02

YAML key-value pairs per entry, not separate entries per credential type

ISE has admin, CLI, DataConnect — store as fields in ONE entry, not 3 separate gopass entries. Queryable via gopass show path field. Reduces entry sprawl.

Evan Rosado

2026-04-02

Clean menu labels — no implementation details in UI

Menu item should say "Cisco ISE" not "Cisco ISE (all credentials in one entry)". Implementation details belong in docs, not UX.

Evan Rosado

2026-04-03

New "Accounts" category (14) — separate from Subscriptions

Online accounts (Firefox, GitHub, Gmail, AWS) are identity credentials, not paid subscriptions. 7 sub-types: browser, email, developer, shopping, social, cloud, generic.

Evan Rosado

6. Metadata

Field Value

PRJ ID

PRJ-2026-03-gopass-personal-docs

Author

Evan Rosado

Created

2026-03-18

Last Updated

2026-04-03

Status

Active (v2.2.0)

Next Review

2026-04-15

7. Related