tegwick
f87f4e5e4d
Gitea's "project/package/release" terms are overloaded, so the catalog now uses the most explicit words: - org = coulomb (the Gitea organisation) - repo = whynot-design (the Gitea repository/product) — not an org, not a scope - npm scope @whynot and package @whynot/design are distinct from both Changes: - catalog schema: replace conflated `owner` with required `org` + `repo`; `owner` is now a derived `org/repo` slug property - npm-config delivery is data-driven: registry + scope live in delivery_config.npm and are validated; engine no longer hardcodes a registry - exec delivery writes `<scope>:registry=<url>` + scoped `:_authToken` for the configured Gitea registry (token still env-expanded, never written to disk) - pilot lane points at https://gitea.coulomb.social/api/packages/coulomb/npm/, scope @whynot, KV path coulomb/whynot-design/npm/publish - npm-publish-demo uses @whynot scope so dry-run resolves the Gitea registry - docs: terminology table; routing owner shown as coulomb/whynot-design - tests: org/repo required, npm-config validation, registry authkey mapping Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
106 lines
4.2 KiB
Markdown
106 lines
4.2 KiB
Markdown
# secrets-engine CLI
|
|
|
|
## Terminology (Gitea is overloaded — be explicit)
|
|
|
|
| Term we use | Means | Example | Not to be confused with |
|
|
| --- | --- | --- | --- |
|
|
| **org** | the Gitea organisation | `coulomb` | the npm scope |
|
|
| **repo** | the Gitea repository / product | `whynot-design` | an org; a Gitea "project" board |
|
|
| **npm scope** | the `@`-prefix npm name | `@whynot` | the org or the repo |
|
|
| **npm package** | the published artifact | `@whynot/design` | the repo it's built from |
|
|
| **lane / catalog id** | a secrets-engine secret lane | `whynot-design-npm-publish` | — |
|
|
|
|
A catalog entry carries `org` + `repo` explicitly (never a bare "owner"), and the
|
|
npm registry/scope live in `delivery_config.npm` as data — the engine never
|
|
hardcodes a registry. The pilot publishes `@whynot/design` from the
|
|
`coulomb/whynot-design` repo to `https://gitea.coulomb.social/api/packages/coulomb/npm/`.
|
|
|
|
## Install
|
|
|
|
```bash
|
|
uv venv && uv pip install -e ".[dev]"
|
|
source .venv/bin/activate
|
|
secrets-engine --version
|
|
```
|
|
|
|
## Environment
|
|
|
|
| Var | Default | Purpose |
|
|
| --- | --- | --- |
|
|
| `BAO_ADDR` | `http://127.0.0.1:8200` | OpenBao address |
|
|
| `BAO_TOKEN` | _(unset)_ | OpenBao token (or use `--bootstrap-token-file`) |
|
|
| `SECRETS_ENGINE_HUB_URL` | `http://127.0.0.1:8000` | State Hub for decisions + evidence (empty to disable) |
|
|
| `SECRETS_ENGINE_CATALOG` | `./catalog` | catalog directory |
|
|
| `SECRETS_ENGINE_EVIDENCE` | `./.evidence` | local non-secret evidence log |
|
|
|
|
## Commands
|
|
|
|
```text
|
|
secrets-engine catalog list
|
|
secrets-engine catalog show <catalog-id>
|
|
secrets-engine decision inspect <decision-or-ccr-id>
|
|
secrets-engine plan <ref> --stage <build|test|prod>
|
|
secrets-engine apply <ref> --stage <stage> [--dry-run] [--bootstrap-token-file F]
|
|
secrets-engine provision <catalog-id> --stage <stage> --field NAME (--from-file F | --generate)
|
|
secrets-engine verify <catalog-id> --field NAME [--positive] [--negative]
|
|
secrets-engine exec --catalog <catalog-id> [--field NAME] [--mode auto|npm-config|exec-env] -- CMD...
|
|
secrets-engine route <catalog-id> [--json]
|
|
secrets-engine revoke <catalog-id> [--dry-run]
|
|
```
|
|
|
|
`<ref>` is a catalog id or a decision/CCR ref (matched against
|
|
`approval.decision_ref`). `plan` and `apply --dry-run` never mutate OpenBao.
|
|
|
|
## Exit codes
|
|
|
|
| Code | Meaning |
|
|
| --- | --- |
|
|
| 0 | success |
|
|
| 2 | catalog error (missing/invalid lane) |
|
|
| 3 | decision error (unapproved / superseded / missing) |
|
|
| 4 | policy guard error (out-of-stage / wildcard / broad admin) |
|
|
| 5 | backend error (OpenBao unreachable / failed) |
|
|
| 6 | provisioning error (bad file mode / inside repo / missing field) |
|
|
| 7 | verification failed |
|
|
| 8 | delivery error |
|
|
|
|
## End-to-end demo
|
|
|
|
```bash
|
|
SECRETS_ENGINE_HUB_URL="" bash scripts/demo-e2e.sh
|
|
```
|
|
|
|
Boots a throwaway in-memory OpenBao dev server and runs the whole pilot chain:
|
|
plan → apply → provision → verify(+/-) → exec (npm-config injection) → route →
|
|
revoke. Nothing is persisted; the token is a throwaway local string.
|
|
|
|
## npm publish wiring (dry-run)
|
|
|
|
```bash
|
|
bash scripts/npm-publish-demo.sh
|
|
```
|
|
|
|
Boots a throwaway OpenBao, applies + provisions the lane with a *fake* token, and
|
|
runs a **real `npm publish --dry-run`** through `secrets-engine exec` against a
|
|
scratch package. Proves npm in the child resolves its auth token from the temp
|
|
`.npmrc` secrets-engine injected, builds the tarball, and reaches the publish
|
|
step — while the parent shell never holds the token. For a real publish,
|
|
provision a real npm automation token the same way and drop `--dry-run`.
|
|
|
|
## Pilot: whynot-design npm publish
|
|
|
|
```bash
|
|
# 1. inspect the approved decision
|
|
secrets-engine decision inspect whynot-design-npm-publish
|
|
# 2. preview the OpenBao changes (no mutation)
|
|
secrets-engine plan whynot-design-npm-publish --stage prod
|
|
# 3. apply policy + approle
|
|
secrets-engine apply whynot-design-npm-publish --stage prod
|
|
# 4. provision the token from a mode-0600 file OUTSIDE the repo
|
|
secrets-engine provision whynot-design-npm-publish --stage prod \
|
|
--field npm_token --from-file ~/.secrets-engine/whynot.token
|
|
# 5. prove access without printing the value
|
|
secrets-engine verify whynot-design-npm-publish --field npm_token --positive --negative
|
|
# 6. publish with the token injected into the child only
|
|
secrets-engine exec --catalog whynot-design-npm-publish -- npm publish
|
|
```
|