From 30b650fe37682eb3892fd84cbe7c5b0077f2a209 Mon Sep 17 00:00:00 2001 From: UEddy Date: Sat, 7 Nov 2026 17:39:47 +0000 Subject: [PATCH 1/4] README: add Going live section Explains how to turn on live mode, recommends a restricted rk_live_ key with only the permissions Obol uses, notes Stripe account activation, warns that live sends email real clients, and asks for one small real invoice before relying on it. --- README.md | 42 +++++++++++++++++++++++++++++++++++++++++- 1 file changed, 41 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index aa27d4b..11a80f1 100644 --- a/README.md +++ b/README.md @@ -108,6 +108,46 @@ checks your bank details. Requires Hermes Agent 0.22+. No extra Python dependencies. +## Going live + +Out of the box Obol refuses live Stripe keys (`sk_live_…`, `rk_live_…`), both in the provider client and again in +the approval hook. Once you turn live mode on, it runs exactly the same code as test mode: the same Stripe calls, +the same approval prompts, the same scam checks. Bank-transfer mode needs no Stripe key, so none of this applies +to it. + +1. **Activate your Stripe account.** Stripe won't accept live invoices until the account is activated (business + details and a payout bank account). That happens on Stripe's side, not in Obol. +2. **Use a restricted key.** A restricted key (`rk_live_…`) is safer than a full secret key. Create one in the + Stripe dashboard with only what Obol uses: + + | Resource | Access | + |---|---| + | Customers | Write | + | Invoices (includes invoice items) | Write | + | Charges | Read (fraud-risk level on paid invoices) | + | Disputes | Read | + | Events | Read (recent contact or payment-detail changes) | + +3. **Set the key and allow live mode:** + + ```bash + hermes config set STRIPE_API_KEY rk_live_… + hermes config set plugins.entries.obol.settings.allow_live true + hermes obol doctor # should report live mode and Stripe reachable + ``` + +4. **Do one small real run before you rely on it.** Send yourself a small real invoice (for example $1 to your + own email), pay it, then void it or refund it in the Stripe dashboard. Obol's live path is the same code as + test mode, but the automated suite (`tests/test_stripe_live.py`) only runs against test keys, so this is the + check that confirms your account and key work end to end. + +> **In live mode, Stripe emails your client for real.** In test mode, sending only produces a payment link. With +> a live key, approving a send or a reminder makes Stripe email the actual customer, so one approval puts a real +> email in front of a real person. Read the recipient in the approval prompt before you approve. + +Two things stay test-only on purpose: `hermes obol demo` refuses anything but a test key, and syncing invoices from +Stripe test clocks only exists in test mode. + ## For judges | Check | How | @@ -173,7 +213,7 @@ Settings live under `plugins.entries.obol.settings` (Hermes Desktop shows them a | Setting | Default | Meaning | |---|---|---| -| `allow_live` | `false` | Must be `true` before a live key is accepted | +| `allow_live` | `false` | Must be `true` before a live key is accepted (see [Going live](#going-live)) | | `default_currency` | `usd` | Currency when a request doesn't name one | | `default_days_until_due` | `14` | Payment terms for new invoices | | `risk_duplicate_window_days` | `30` | Same customer and amount within this many days (`0` = off) | From ad835931bd47f807be7b09cec4d7667dff69727c Mon Sep 17 00:00:00 2001 From: UEddy Date: Sat, 7 Nov 2026 17:44:19 +0000 Subject: [PATCH 2/4] Warn in the approval prompt when a live send emails a real client In live mode, create-and-send, send and remind make Stripe email the actual customer. The approval prompt now says so; void, mark paid and drafts don't email anyone and get no warning. --- README.md | 4 ++-- src/obol_lib/gate.py | 11 +++++++++++ tests/test_gate.py | 10 ++++++++++ 3 files changed, 23 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 11a80f1..c7a03da 100644 --- a/README.md +++ b/README.md @@ -143,7 +143,7 @@ to it. > **In live mode, Stripe emails your client for real.** In test mode, sending only produces a payment link. With > a live key, approving a send or a reminder makes Stripe email the actual customer, so one approval puts a real -> email in front of a real person. Read the recipient in the approval prompt before you approve. +> email in front of a real person. The approval prompt says so too; read the recipient before you approve. Two things stay test-only on purpose: `hermes obol demo` refuses anything but a test key, and syncing invoices from Stripe test clocks only exists in test mode. @@ -154,7 +154,7 @@ Stripe test clocks only exists in test mode. |---|---| | Try it in two minutes | `hermes obol demo` with a Stripe test key: sample clients, then four prompts to try | | Installs cleanly | `hermes plugins validate . --install-deps && hermes plugins doctor . --ci` → 8 tools, 1 hook, install scan **safe** | -| Tests | `python -m pytest`: 234 tests, no keys needed (unit, adversarial, recorded real responses, gateway, Hermes integration) | +| Tests | `python -m pytest`: 235 tests, no keys needed (unit, adversarial, recorded real responses, gateway, Hermes integration) | | Claims are proven | `tests/test_readme_claims.py` fails if any test named in this README doesn't exist | | Real, not mocked | live test-mode suite (`tests/test_stripe_live.py`), real-model intake suite (`tests/test_intake_live.py`), recorded real responses, live Telegram run | | More than a skill | tools, an approval hook, structured extraction via `ctx.llm`, dashboard tab + API, slash command, CLI, automation blueprint, skill | diff --git a/src/obol_lib/gate.py b/src/obol_lib/gate.py index 312cc4d..87c8b1e 100644 --- a/src/obol_lib/gate.py +++ b/src/obol_lib/gate.py @@ -22,6 +22,15 @@ _VERBS = {"obol_send_invoice": "finalize and email", "obol_send_reminder": "re-send the payment email for", "obol_void_invoice": "VOID (cannot be undone)", "obol_mark_paid": "mark as PAID (money received outside the payment page)"} +LIVE_EMAIL_WARNING = "LIVE: approving makes Stripe email this real client now. Check the address." + + +def _emails_client(tool_name: str, args: dict) -> bool: + """True for the writes that make Stripe email the customer.""" + if tool_name == "obol_create_invoice": + return bool(args.get("send")) + return tool_name in ("obol_send_invoice", "obol_send_reminder") + def describe_create(args: dict, default_currency: str, bank: bool = False) -> str: cur = str(args.get("currency") or default_currency).lower() @@ -84,4 +93,6 @@ def decide(tool_name: str, args: dict, *, mode: str, allow_live: bool, unattende "message": f"Risk checks could not run ({exc.__class__.__name__}); review carefully."}] tag = {"live": "LIVE MONEY", "bank": "BANK TRANSFER"}.get(mode, "TEST mode") message = f"Obol ({tag}): {summary()}.\n{format_flags(flags)}" + if mode == "live" and _emails_client(tool_name, args): + message += f"\n{LIVE_EMAIL_WARNING}" return {"action": "approve", "message": message, "rule_key": f"obol:{tool_name}:{uuid.uuid4().hex}"} diff --git a/tests/test_gate.py b/tests/test_gate.py index 59a7241..fa0b60f 100644 --- a/tests/test_gate.py +++ b/tests/test_gate.py @@ -38,6 +38,16 @@ def test_live_key_blocked_unless_allowed(): assert allowed["action"] == "approve" and "LIVE MONEY" in allowed["message"] +def test_live_sends_warn_that_a_real_client_is_emailed(): + for tool in ("obol_create_invoice", "obol_send_invoice", "obol_send_reminder"): + assert gate.LIVE_EMAIL_WARNING in _decide(tool=tool, mode="live", allow_live=True)["message"], tool + for tool in ("obol_void_invoice", "obol_mark_paid"): + assert gate.LIVE_EMAIL_WARNING not in _decide(tool=tool, mode="live", allow_live=True)["message"], tool + assert gate.LIVE_EMAIL_WARNING not in _decide(args={**CREATE, "send": False}, mode="live", + allow_live=True)["message"] + assert gate.LIVE_EMAIL_WARNING not in _decide()["message"] + + def test_unattended_runs_are_blocked_cleanly(): d = _decide(unattended=True) assert d["action"] == "block" and "unattended" in d["message"] and "Nothing was sent" in d["message"] From bbc1da6e4d50abdee5aa6c2b04a6da0b4390ca26 Mon Sep 17 00:00:00 2001 From: UEddy Date: Sun, 8 Nov 2026 06:10:30 +0000 Subject: [PATCH 3/4] README: link the demo and catalog listing, document where bank details live --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index c7a03da..c007494 100644 --- a/README.md +++ b/README.md @@ -23,7 +23,7 @@ You: Have they paid? Hermes: Yes, paid in full today. ``` -**Demo (70 s):** link in the catalog PR · **Install:** `hermes plugins install ueddy/obol` +**Demo (70 s):** [watch on X](https://x.com/DeFiRanch/status/2118752233315791051) · **Install:** `hermes plugins install ueddy/obol` · Listed in the [official plugin catalog](https://github.com/NousResearch/hermes-agent/pull/149915) --- @@ -235,7 +235,7 @@ Injection detection is always on. - **Your model:** `obol_draft_from_message` sends the forwarded message to the model Hermes is configured to use, through `ctx.llm`. - **Emails:** sending and reminding make the payment provider email your client. In bank-transfer mode nobody is emailed; PDFs are written to `/plugin-data/obol/invoices/`. - **Credentials:** `STRIPE_API_KEY` (optional, Stripe mode only; install doesn't ask for it), read only through Hermes's secret route; never logged or stored. Without it, Stripe-mode tools answer "Stripe key not set" and do nothing. -- **Local data:** `/plugin-data/obol/data.db`: cached invoice metadata, risk findings, and hash-chained activity and security logs (forwarded message text is not stored). Delete the file to clear it. +- **Local data:** `/plugin-data/obol/data.db`: cached invoice metadata, risk findings, and hash-chained activity and security logs (forwarded message text is not stored). Delete the file to clear it. Bank-transfer details (account name, number, bank, routing) are plugin settings, stored in plain text in Hermes's `config.yaml`. The full number appears only there and on the PDFs: Obol's logs and database hold a fingerprint of the details and the account's last four digits, never the number itself. - **No telemetry, shell commands, background processes or self-updating code.** ## Development From 40b5e2968227a809f0091d8593ba7af28316bf73 Mon Sep 17 00:00:00 2001 From: UEddy Date: Sun, 8 Nov 2026 06:11:10 +0000 Subject: [PATCH 4/4] README: correct the test count to 231 (CI, inside Hermes, no keys) --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index c007494..7df05a1 100644 --- a/README.md +++ b/README.md @@ -154,7 +154,7 @@ Stripe test clocks only exists in test mode. |---|---| | Try it in two minutes | `hermes obol demo` with a Stripe test key: sample clients, then four prompts to try | | Installs cleanly | `hermes plugins validate . --install-deps && hermes plugins doctor . --ci` → 8 tools, 1 hook, install scan **safe** | -| Tests | `python -m pytest`: 235 tests, no keys needed (unit, adversarial, recorded real responses, gateway, Hermes integration) | +| Tests | `python -m pytest`: 231 tests, no keys needed (unit, adversarial, recorded real responses, gateway, Hermes integration) | | Claims are proven | `tests/test_readme_claims.py` fails if any test named in this README doesn't exist | | Real, not mocked | live test-mode suite (`tests/test_stripe_live.py`), real-model intake suite (`tests/test_intake_live.py`), recorded real responses, live Telegram run | | More than a skill | tools, an approval hook, structured extraction via `ctx.llm`, dashboard tab + API, slash command, CLI, automation blueprint, skill |