Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
53 changes: 53 additions & 0 deletions .github/workflows/sudo-release.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
name: sudo-secretspec downstream release checks

on:
pull_request:
paths:
- "packaging/**"
- "sudo-secretspec/**"
- "skills/sudo-secretspec/**"
- "tests/sudo_packaging/**"
- "tests/sudo_secretspec/**"
- "Cargo.toml"
- "Cargo.lock"
- ".github/workflows/sudo-release.yml"
- "CHANGELOG.md"
push:
tags:
- "v0.19.1-djbclark.1"
workflow_dispatch:

permissions:
contents: read

jobs:
packaging:
runs-on: macos-15
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
fetch-depth: 0
- uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v6.0.0
with:
python-version: "3.13"
- name: Install focused test dependencies
run: |
python -m pip install pytest ruff
brew install shellcheck shfmt
- name: Test downstream companion and release helper
run: |
python -m ruff check sudo-secretspec packaging tests/sudo_secretspec tests/sudo_packaging
python -m ruff format --check sudo-secretspec packaging tests/sudo_secretspec tests/sudo_packaging
python -m pytest tests/sudo_secretspec tests/sudo_packaging -q
shfmt -d -i 2 -ci sudo-secretspec/bin/install-sudo-secretspec sudo-secretspec/libexec/sudo-secretspec-broker
shellcheck -S warning sudo-secretspec/bin/install-sudo-secretspec sudo-secretspec/libexec/sudo-secretspec-broker
- name: Check formula style and syntax
run: |
ruby -c packaging/homebrew/sudo-secretspec.rb
brew style packaging/homebrew/sudo-secretspec.rb
- name: Verify pinned tag identity
if: github.ref_type == 'tag'
env:
EXPECTED_TAG: v0.19.1-djbclark.1
run: test "$GITHUB_REF_NAME" = "$EXPECTED_TAG"
3 changes: 3 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -17,3 +17,6 @@ target
/secretspec-swift/Artifacts/

.idea/

__pycache__/
*.pyc
12 changes: 12 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,18 @@ All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

### Added

- Downstream `sudo-secretspec` privilege-boundary companion: a single Rust
binary with mediated credential operations, fail-closed SQLite audit,
metadata-only doctor/drift checks, explicit install/adopt/rollback, and
Homebrew packaging that never performs privileged installation side effects.
- Short install UX: `sudo-secretspec install` / `install --adopt-existing`
with declaration auto-detection and TTY prompts; long flags are overrides.
- Fork docs: `sudo-secretspec/README.md`, `README.downstream.md`, `FORK-AI.md`.

## [0.19.1] - 2026-08-11

Republishes 0.19.0's command-line artifacts. The library and CLI behave exactly
Expand Down
17 changes: 15 additions & 2 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,9 +15,22 @@ For an upcoming provider or feature:
pages, README files, and generated documentation summaries with the minimum
version, for example `(0.15+)`.

## Project Overview
## Downstream fork notes (`djbclark/sudo-secretspec`)

SecretSpec is a declarative secrets manager for development workflows written in Rust. It provides a CLI tool and Rust library for managing environment variables and secrets across different environments using multiple storage backends (keyring, dotenv, environment variables, OnePassword, LastPass).
This repository is a fork. In addition to upstream SecretSpec:

- Companion crate: `sudo-secretspec-cli` (binary `sudo-secretspec`)
- Downstream docs: `sudo-secretspec/README.md`, `README.downstream.md`
- AI automation contract: `sudo-secretspec/AI-GUIDANCE.md`
- Fork-only agent notes/tricks: `FORK-AI.md` (do not upstream)
- Branches: `main` mirrors upstream; `sudo-main` is the downstream release line
- Version scheme: `0.19.1-djbclark.1`

When changing the companion, update `CHANGELOG.md` Unreleased with a user-facing
entry and keep privileged install explicit (Homebrew must not silently edit
sudoers/users/vaults).

Prefer system SQLite (not `rusqlite` bundled) on macOS; see `FORK-AI.md`.

## Build and Development Commands

Expand Down
85 changes: 78 additions & 7 deletions Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

10 changes: 7 additions & 3 deletions Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -6,11 +6,12 @@ members = [
"secretspec-node",
"secretspec-php",
"secretspec-py",
"sudo-secretspec-cli",
]
resolver = "2"

[workspace.package]
version = "0.19.1"
version = "0.19.1-djbclark.1"
edition = "2024"

[workspace.dependencies]
Expand All @@ -28,6 +29,9 @@ dotenvy = "0.15"
inquire = { version = "0.9.4", features = ["experimental-multiline-input"] }
miette = { version = "7.6", features = ["fancy"] }
serde_json = "1.0"
rusqlite = { version = "0.40.0", features = ["bundled"] }
sha2 = "0.10"
libc = "0.2"
proptest = "1"
tempfile = "3.0"
same-file = "1.0"
Expand All @@ -53,8 +57,8 @@ azure_identity = "1.0.0"
azure_security_keyvault_secrets = "1.0.0"
reqwest = { version = "0.12", default-features = false, features = ["json", "rustls-tls-native-roots"] }
tokio = { version = "1", features = ["rt", "rt-multi-thread"] }
secretspec-derive = { version = "0.19.1", path = "./secretspec-derive" }
secretspec = { version = "0.19.1", path = "./secretspec" }
secretspec-derive = { version = "0.19.1-djbclark.1", path = "./secretspec-derive" }
secretspec = { version = "0.19.1-djbclark.1", path = "./secretspec" }
rand = "0.9"
rsa = { version = "0.9", features = ["pem"] }
uuid = { version = "1", features = ["serde", "v4"] }
Expand Down
82 changes: 82 additions & 0 deletions FORK-AI.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,82 @@
# Fork-only notes for AI agents (`djbclark/sudo-secretspec`)

This file is **downstream-only**. Do not port it upstream to `cachix/secretspec`.

## Layout that matters

| Path | Purpose |
|---|---|
| `sudo-secretspec-cli/` | Rust companion binary/library (the product) |
| `sudo-secretspec/` | Guidance, config example, companion README |
| `packaging/` | Release script + Homebrew formula |
| `skills/sudo-secretspec/` | Distributable AI skill |
| `main` | upstream mirror |
| `sudo-main` | downstream default/release branch |

## High-value lessons (save time)

1. **Do not write complex shell for the boundary.** Runtime policy is Rust.
2. **Avoid `rusqlite` `bundled` on this Mac.** It can hang in `libsqlite3-sys`
build scripts. Prefer system SQLite:
```bash
export PKG_CONFIG_PATH="/opt/homebrew/opt/sqlite/lib/pkgconfig:$PKG_CONFIG_PATH"
export LIBRARY_PATH="/opt/homebrew/opt/sqlite/lib:$LIBRARY_PATH"
export CPATH="/opt/homebrew/opt/sqlite/include:$CPATH"
```
and `rusqlite = { version = "0.31" }` (no `bundled`).
3. **Cargo registry extract cache can be incomplete** after interrupted builds.
Incomplete dirs under `~/.cargo/registry/src/index.crates.io-*` missing
`Cargo.toml` can be deleted when the matching `.crate` archive exists.
4. **Toolchain is pinned** by `rust-toolchain.toml` (currently `1.92.0`). Ensure
`PATH` includes `~/.cargo/bin`.
5. **macOS path aliases:** `/var` → `/private/var`, `/etc` → `/private/etc`.
Validate resolved protected chains; accept public spellings.
6. **Dotenv provider must be pinned** to the vault file:
`dotenv:///var/db/.../.env` — never bare `dotenv` (cwd-relative).
7. **Audit must fail closed.** Do not ignore `append_event` errors.
8. **Public client elevates with:**
- lifecycle: `sudo -n /usr/local/libexec/sudo-secretspec __broker ...`
- install/rollback: interactive `sudo` (Touch ID)
- doctor: prefer `sudo -n` libexec elevation
9. **Adopt-existing must not chown/chmod the vault.** Only verify metadata.
10. **Install UX goal:** short forms (`install`, `install --adopt-existing`) with
auto-detection/prompts; long flags are overrides only.

## Useful commands

```bash
# focused tests
cargo test -p sudo-secretspec-cli

# release binary
cargo build -p sudo-secretspec-cli --release
cp target/release/sudo-secretspec ~/bin/sudo-secretspec

# live smoke after install
sudo -n /usr/local/libexec/sudo-secretspec doctor
sudo-secretspec check --reason "smoke"
```

## Delivery conventions

- PRs target `sudo-main` on `djbclark/sudo-secretspec` (not upstream).
- Never open upstream issues/PRs without explicit permission.
- Keep `CHANGELOG.md` Unreleased entries user-facing.
- After privileged install, verify paths under `/usr/local` and vault ownership
without reading secret values.

## Known residual findings on this host

After adopt-existing install of the stayturgid vault, doctor may report:

- `LEGACY_VAULT_CLUTTER` / previously `UNEXPECTED_RUNTIME_ENTRY` for `.local` /
`.ansible` under the vault (non-secret tool state; safe to clean later)
- audit ledger ownership should be `_secretspec:staff` (fixed in current tree by
chown-after-open when broker is root)

## Related human/AI guidance

- `sudo-secretspec/AI-GUIDANCE.md`
- `skills/sudo-secretspec/SKILL.md`
- `packaging/README.md`
- Local reusable Rust agent notes: `~/src/agent-guidance/rust/AGENTS.md`
Loading
Loading