stablemate-saddlebag 2.0.0__tar.gz

stablemate_saddlebag-2.0.0/.gitignore

@@ -0,0 +1,264 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer,
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml
+
+.playwright-mcp
+
+.agents/*
+
+
+# A benchmark round's built repo, its run artifacts and its scorecard. Untracked for
+# three separate reasons, any one of which is sufficient — it is large (a whole app per
+# round), it is derived (re-runnable from the task module), and the built repo is its OWN
+# git repo, which is the whole point: nesting one working tree inside another is only safe
+# while the outer one cannot see it. Paddock's work and result roots live outside the tree
+# entirely (`~/.local/share/stablemate/paddock`) for the same reason; this entry stays as
+# the backstop for a round pointed at the repo by hand.
+/data/
+
+
+# Internal planning notes: maintainer paths, private-project references and
+# retired-engine prose live here by nature. The directory stays (kept by .gitkeep)
+# but its contents never ship.
+docs/plans/*
+!docs/plans/.gitkeep
+progress.md
+docs/specs
+.opencode/opencode-loop
+
+docs/backload.md
+
+# >>> farrier: QA evidence (generated) >>>
+**/qa/**/steps/
+**/qa/**/asserts/
+**/qa/**/traces/
+**/qa/**/videos/
+**/qa/**/screenshots/
+**/qa/qa-run.ndjson
+**/qa/run-manifest.json
+**/qa/qa-session.json
+# <<< farrier: QA evidence <<<
+
+.agents/runs/
+.agents/worktrees/
+.agents/workflows/
+.agents/operator/
+.agents/local.compose.yaml
+.agents/agents-context.json
+.agents/agents-context.*.json
+.agents/agents.mk

stablemate_saddlebag-2.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gabriel Côté
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

stablemate_saddlebag-2.0.0/PKG-INFO

@@ -0,0 +1,299 @@
+Metadata-Version: 2.5
+Name: stablemate-saddlebag
+Version: 2.0.0
+Summary: A Vault-backed daemon that fills secrets into browsers and commands without printing them.
+Project-URL: Homepage, https://github.com/GabrielCpp/stablemate/tree/main/saddlebag
+Project-URL: Repository, https://github.com/GabrielCpp/stablemate
+Project-URL: Issues, https://github.com/GabrielCpp/stablemate/issues
+Author: Gabriel Côté
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,credentials,secrets,testing,vault,workflow
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Testing
+Classifier: Topic :: Utilities
+Requires-Python: >=3.12
+Requires-Dist: hvac>=2.0
+Requires-Dist: keyring>=25
+Requires-Dist: platformdirs>=4.0
+Requires-Dist: websockets>=13.0
+Provides-Extra: test
+Requires-Dist: pytest>=8.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# saddlebag
+
+> Carry the right credentials for every ride.
+
+`saddlebag` holds the secrets a QA run needs and puts each one where it is consumed, so
+that an agent driving a `workhorse` workflow never holds a secret in its context. A
+secret leaves the store in exactly two ways. `fill` types it into a field of a browser
+over the Chrome DevTools Protocol. `exec` runs a command with it set in that command's
+process environment. Neither hands the value back to whoever ran them.
+
+One daemon holds the HashiCorp Vault token, and every other command is a thin client
+over a unix socket. That is what lets the same tool serve a run on the host and a run
+in a container: the container sees the socket and nothing else.
+
+---
+
+## Position in the ecosystem
+
+| Tool | Job |
+|---|---|
+| **ostler** | Tends the knowledge graph: epics, stories, seeds, specs |
+| **farrier** | Fits the shared prompt library onto each repo |
+| **workhorse** | Runs the workflow graph unattended |
+| **saddlebag** | Carries secrets and fills them where they are consumed |
+
+Ostler owns the spec of what a test needs and which environment it runs against.
+Saddlebag owns the secret material that satisfies it. Ostler's stack bring-up asks
+saddlebag for the variables a stack needs, as described under
+[The ostler stack](#the-ostler-stack).
+
+---
+
+## Install
+
+Saddlebag publishes to PyPI as `stablemate-saddlebag`, because the name `saddlebag` is
+unavailable. The command and the import package stay `saddlebag`.
+
+```bash
+uv tool install stablemate-saddlebag
+pipx install stablemate-saddlebag
+```
+
+The `stablemate` package installs it along with the other tools (`uv tool install stablemate`).
+From a checkout of the [stablemate](https://github.com/GabrielCpp/stablemate) workspace:
+
+```bash
+uv run --package stablemate-saddlebag saddlebag --help
+```
+
+Requires Python ≥ 3.12 and a reachable HashiCorp Vault with a KV v2 mount named
+`secret`. For a developer machine, `vault server -dev` is enough.
+
+---
+
+## Sixty seconds
+
+```bash
+# 1. Start the daemon. The token arrives on stdin and stays in the daemon's memory.
+export VAULT_ADDR=http://127.0.0.1:8200
+printf '%s' "$VAULT_TOKEN_FROM_YOUR_LOGIN" | saddlebag serve
+
+# 2. In another shell: describe a secret, then give it its value on stdin.
+saddlebag secret create normal_login \
+  --username gab \
+  --description "Log in as a normal user" \
+  --var LOGIN_PASSWORD \
+  --tag environment=local --tag role=user
+printf '%s' "$PASSWORD" | saddlebag secret set normal_login
+
+# 3. An agent finds it by tag and reads the description. No value is printed.
+saddlebag list --tag environment=local
+
+# 4. Deliver it. Into a browser field, or into a command's environment.
+saddlebag fill normal_login --field username --selector "#login_field" --url-contains example.com
+saddlebag fill normal_login --field password --selector "#password"    --url-contains example.com
+saddlebag exec --tag environment=local -- docker compose up
+```
+
+The browser the fourth step talks to is one you started with a debugger port:
+
+```bash
+chromium --remote-debugging-port=9222 --user-data-dir=/tmp/qa-profile
+```
+
+Saddlebag connects only to a DevTools endpoint on loopback and refuses any other
+host. That port is unauthenticated and grants total control of the browser.
+
+---
+
+## The daemon
+
+`saddlebag serve` is the one process that talks to Vault. It reads the token from
+stdin when piped, else from the OS keyring where `saddlebag serve --keep-token` stored
+it, else from `saddlebag/vault-token` under the stablemate state dir when that file is
+mode 0600. It refuses to start if `VAULT_TOKEN` is set in its environment, and listens
+on a unix socket created with owner-only permissions. Every other verb connects to
+that socket, sends one request and reads one reply.
+
+| | |
+|---|---|
+| Backend | `$SADDLEBAG_BACKEND` (`keyring` or `daemon`), else `backend` under `[saddlebag]` in the shared stablemate `config.toml`, else a daemon that answers on the socket, else the OS keyring |
+| Socket path | `$SADDLEBAG_SOCKET`, else `$XDG_RUNTIME_DIR/saddlebag.sock`, else the OS runtime dir |
+| Vault address | `$VAULT_ADDR` or `--vault-addr` |
+| Browser | `--cdp`, default `http://127.0.0.1:9222` |
+
+saddlebag never puts the token in an environment variable, because a process of the
+same user can read `/proc/<pid>/environ`. The kept token lives in the OS keyring. The
+filed token is the operator's choice, and `doctor` warns about it because any file the
+user owns is readable by their other processes. For the same reason the operator's own
+Vault login must not leave `~/.vault-token` behind, and `doctor` warns when that file
+exists.
+
+### A run in a container
+
+Mount the socket and name it. The client inside the container talks to the daemon
+on the host, which is also where the browser and its debug port live.
+
+```bash
+docker run \
+  -v "$SADDLEBAG_SOCKET:/run/saddlebag.sock" \
+  -e SADDLEBAG_SOCKET=/run/saddlebag.sock \
+  ...
+```
+
+---
+
+## Secrets and tags
+
+A **secret** has a name, an optional username, a description an agent reads to choose
+between candidates, an optional `var` naming the environment variable `exec` fills it
+into, and a set of `key=value` tags. It holds up to two values: a `password` and a
+`totp` enrolment seed. The username is metadata and may print. The two values never do.
+
+```jsonc
+{
+  "name":        "normal_login",
+  "username":    "gab",
+  "description": "Log in as a normal user",
+  "var":         "LOGIN_PASSWORD",
+  "tags":        [["environment", "local"], ["role", "user"]],
+  "fields":      ["password"]
+}
+```
+
+Tags are the whole query vocabulary. `list --tag environment=local --tag role=admin`
+returns the secrets carrying both pairs. `tags` lists the distinct pairs in use. The
+convention the ostler integration relies on is that a secret for a QA environment
+carries `environment=<ostler environment node id>`.
+
+---
+
+## Commands
+
+| | |
+|---|---|
+| `serve` | run the daemon; token from stdin, the OS keyring or a 0600 file; `--keep-token` stores one |
+| `list` `tags` | query by tag; neither can emit a value |
+| `secret create` `set` `unset` `remove` `tag` `untag` | manage a secret; `set` reads its value from stdin |
+| `fill` | type a secret's username, password or current TOTP code into a browser field |
+| `exec` | run a command with matching secrets in its environment |
+| `doctor` | backend and route in use, store reachable, secrets with no value, orphan keyring items, stray token file, and on the daemon route where its token came from |
+
+```bash
+saddlebag fill NAME --field username|password|totp --selector S [--url-contains X]
+saddlebag exec [--tag k=v]... [--env VAR=NAME[.field]]... -- cmd args...
+```
+
+`exec` fills each tag-matched secret's `var` with its password. An explicit
+`--env VAR=NAME.field` binding may name any field, including the username and the
+current TOTP code. A secret matched by tag that has no `var` is an error naming it,
+not a silent skip.
+
+**What each verb guarantees.** `fill` reports a character count, a selector and a URL.
+The value is typed through `Input.insertText` and never interpolated into an evaluated
+expression. A TOTP seed leaves the store only as a computed six-digit code, and only
+by being typed. `exec` is as private as the command it runs: a command that prints its
+own environment prints the secret. What `exec` guarantees is that the value is never
+in the agent's transcript by default and never on disk. The agent's permission layer
+decides which commands it may run under `exec`.
+
+---
+
+## The ostler stack
+
+A repository's `docs/services/ops/stack.yml` names one secret source for its compose
+stack. With saddlebag as that source, ostler asks `saddlebag list` for the variable
+names the matching secrets fill, checks them against the `${VAR}` references in the
+rendered compose file, and runs every `docker compose` command under `saddlebag exec`.
+No `stack.env` file is written.
+
+```yaml
+secrets:
+  saddlebag: environment=local
+```
+
+The value is one or more space-separated tag pairs. The ostler README documents the
+other two sources and the required-name check.
+
+---
+
+## Where secrets live
+
+A command picks its route in this order: `SADDLEBAG_BACKEND`, then the `backend` key
+of the `[saddlebag]` table in the shared stablemate `config.toml`, then a daemon that
+answers on the socket, else the OS keyring in this process. A set `SADDLEBAG_SOCKET`
+always means the daemon, and nothing listening there is an error, never a silent
+fall-back to the keyring.
+
+Without a daemon, values live in the OS keyring, one item per secret and field under
+the service `stablemate-saddlebag`, and their metadata in `saddlebag/catalogue.json`
+under the stablemate state dir, owner-only. Behind the daemon, values and metadata both
+live in Vault under `secret/saddlebag/<name>`: the values as the secret's data, the
+metadata as its custom metadata. Saddlebag implements no encryption and keeps no
+plaintext fallback. A locked or absent keyring stops the command with a line that says
+what to do, and if Vault is unreachable, the daemon does not start.
+
+Over SSH the keyring is usually locked. Feed your login password to
+`gnome-keyring-daemon --unlock` to open it, or set `SADDLEBAG_BACKEND=daemon`. On
+macOS the Keychain trusts the interpreter that stored an item, so a reinstalled
+interpreter prompts once per item; `doctor` prints the interpreter path, which
+`security add-generic-password -T <path>` takes to pre-authorise it. The full account,
+including what the socket and the keyring do and do not protect against, is in
+[docs/SECURITY.md](https://github.com/GabrielCpp/stablemate/blob/main/saddlebag/docs/SECURITY.md).
+Driving saddlebag from a workflow node is in
+[docs/INTEGRATION.md](https://github.com/GabrielCpp/stablemate/blob/main/saddlebag/docs/INTEGRATION.md).
+
+---
+
+## Upgrading from 1.x
+
+Version 2.0 removed the 1.x OS keyring backend, the SQLite pool, credential leases,
+AI selection, the `env` command family and the YAML manifest. Nothing is migrated.
+Credentials in a 1.x pool and 1.x keyring items under the service `saddlebag` are left
+in place and orphaned; the keyring store of 2.x reads only items under
+`stablemate-saddlebag`, which it wrote itself. Create each secret you still need with
+`secret create` and `secret set`.
+
+---
+
+## Package layout
+
+```
+saddlebag/
+├── __init__.py
+├── cli.py        # argparse front end: build a request, route it, print the reply; `exec`
+├── route.py      # how a command reaches the counter: the daemon's socket, or in-process over the keyring
+├── verbs.py      # the verb handlers over one store, used in-process or behind the daemon
+├── store.py      # the SecretStore contract every verb talks to, and StoreUnavailable
+├── custody.py    # the Vault token's three sources and the refusal
+├── daemon.py     # `serve`: the socket accept loop over the verbs
+├── protocol.py   # the socket path, newline-JSON framing and the client's send()
+├── vault.py      # Vault KV v2: values in the secret's data, metadata in its custom metadata
+├── keyring_store.py  # the OS keyring door and the shelf: values in the keyring, records in the catalogue
+├── catalogue.py  # the keyring shelf's records, in one owner-only JSON file
+├── models.py     # Secret and tag parsing; no field of it carries a value
+├── browser.py    # CDP target discovery and Input.insertText; only a length comes back
+└── totp.py       # RFC 6238, computed in-process so the seed never leaves
+```
+
+## Name
+
+A **saddlebag** is the kit a horse carries on a ride: the right tools, ready when
+needed, returned to the stable when the ride is done. It fits the stablemate
+vocabulary. Ostler tends the stable, farrier fits the gear, workhorse does the
+riding, and saddlebag carries what the journey needs.
+
+## Map
+
+- `saddlebag/`: the package behind the `saddlebag` command. [Package layout](#package-layout) says what each module owns.
+- `docs/`: the security model and the workflow integration.
+- `tests/`: the suite, run from the repo root with `uv run --package stablemate-saddlebag pytest saddlebag/tests`.