From cccb042ad32a14cb5541ce193d990828eec33163 Mon Sep 17 00:00:00 2001 From: Kevin J <6829515+kmjones1979@users.noreply.github.com> Date: Sun, 7 Jun 2026 20:35:27 -0400 Subject: [PATCH 1/3] docs: update 1claw skill for per-org Bankr BYOK Co-authored-by: Cursor --- 1claw/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/1claw/SKILL.md b/1claw/SKILL.md index 98c68f7569..03f0a6e708 100644 --- a/1claw/SKILL.md +++ b/1claw/SKILL.md @@ -55,7 +55,7 @@ metadata: - **Secret versioning and rotation** — every write creates a new version; server-generated rotation with configurable charset - **Webhooks** — subscribe to wallet, proposal, transaction, policy, and signing key events -**Pair with Bankr (recommended — Dynamic Key Vending):** Org admins configure `BANKR_PARTNER_KEY` on Vault. Agents lease short-lived, scoped `bk_usr_` keys via `lease_bankr_key` (MCP), `1claw agent bankr-key lease`, or the dashboard — no manual `put_secret` / rotation. Shroud auto-resolves leased keys for `X-Shroud-Provider: bankr`. See [Bankr Key Vending guide](https://docs.1claw.xyz/docs/guides/bankr-key-vending). +**Pair with Bankr (recommended — Dynamic Key Vending):** Org owners/admins add their `bk_ptr_` partner key under **Settings → Bankr** (`PUT /v1/org/bankr-config`). Agents lease short-lived, scoped `bk_usr_` keys via `lease_bankr_key` (MCP), `1claw agent bankr-key lease`, or the dashboard — no manual `put_secret` / rotation. Shroud auto-resolves leased keys for `X-Shroud-Provider: bankr`. See [Bankr Key Vending guide](https://docs.1claw.xyz/docs/guides/bankr-key-vending). **Legacy static path:** Store a long-lived Bankr key at `keys/bankr-api-key` or `providers/bankr/api-key` via `put_secret`, then `get_secret` when calling Bankr endpoints. Manual rotation when the key expires. Never paste `bk_...` or `ocv_...` keys into chat. From 20e4e841553082a6cbbb4422261098fd92a0b8fc Mon Sep 17 00:00:00 2001 From: Kevin J <6829515+kmjones1979@users.noreply.github.com> Date: Sun, 7 Jun 2026 21:29:28 -0400 Subject: [PATCH 2/3] docs: align Bankr key vending with per-org BYOK Replace stale BANKR_PARTNER_KEY-only wording with org settings and API config; note optional deployment fallback for self-hosted Vault. Co-authored-by: Cursor --- 1claw/SKILL.md | 2 +- 1claw/references/mcp-and-api.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/1claw/SKILL.md b/1claw/SKILL.md index 03f0a6e708..d46cf085d1 100644 --- a/1claw/SKILL.md +++ b/1claw/SKILL.md @@ -175,7 +175,7 @@ See `references/mcp-and-api.md` for the full tool list and REST auth flows. ### Bankr Dynamic Key Vending (preferred) -When the org has `BANKR_PARTNER_KEY` configured on Vault, lease scoped TTL-bound keys instead of storing long-lived `bk_` secrets. +When the org has configured Bankr BYOK (partner key + default wallet under **Settings → Bankr** or `PUT /v1/org/bankr-config`), lease scoped TTL-bound keys instead of storing long-lived `bk_` secrets. Self-hosted operators may use deployment-level `BANKR_PARTNER_KEY` as a fallback when org BYOK is unset. **Privileged — deny-by-default:** Agents need an explicit policy on the `__agent-keys` vault: diff --git a/1claw/references/mcp-and-api.md b/1claw/references/mcp-and-api.md index 3b1463d97d..724fbb32ba 100644 --- a/1claw/references/mcp-and-api.md +++ b/1claw/references/mcp-and-api.md @@ -108,7 +108,7 @@ Supported chains: `ethereum`, `bitcoin`, `solana`, `xrp`, `cardano`, `tron`. ## Bankr Dynamic Key Vending -Partner-key secret engine for short-lived Bankr wallet API keys. Requires `BANKR_PARTNER_KEY` on Vault (server-side; never stored in agent vault paths). +Partner-key secret engine for short-lived Bankr wallet API keys. Each org stores its own encrypted `bk_ptr_` via `PUT /v1/org/bankr-config` (Dashboard **Settings → Bankr**); optional deployment `BANKR_PARTNER_KEY` fallback for self-hosted Vault. Partner keys never enter agent vault paths. | Endpoint | Purpose | | --- | --- | From 4c480e9e88e16bb291857d03b3223bddc0f6c80b Mon Sep 17 00:00:00 2001 From: Kevin J <6829515+kmjones1979@users.noreply.github.com> Date: Mon, 8 Jun 2026 17:33:46 -0400 Subject: [PATCH 3/3] docs: document Bankr fallback tenant-isolation controls Address maintainer review on PR #458: multi-tenant should not use BANKR_PARTNER_KEY; org BYOK precedence, audit credential_source, and prod fallback alerting. Co-authored-by: Cursor --- 1claw/SKILL.md | 14 +++++++++++++- 1claw/references/mcp-and-api.md | 11 ++++++++++- 2 files changed, 23 insertions(+), 2 deletions(-) diff --git a/1claw/SKILL.md b/1claw/SKILL.md index d46cf085d1..0cd343f5b9 100644 --- a/1claw/SKILL.md +++ b/1claw/SKILL.md @@ -57,6 +57,18 @@ metadata: **Pair with Bankr (recommended — Dynamic Key Vending):** Org owners/admins add their `bk_ptr_` partner key under **Settings → Bankr** (`PUT /v1/org/bankr-config`). Agents lease short-lived, scoped `bk_usr_` keys via `lease_bankr_key` (MCP), `1claw agent bankr-key lease`, or the dashboard — no manual `put_secret` / rotation. Shroud auto-resolves leased keys for `X-Shroud-Provider: bankr`. See [Bankr Key Vending guide](https://docs.1claw.xyz/docs/guides/bankr-key-vending). +**Deployment fallback (operators only — tenant isolation):** + +| Environment | Guidance | +| --- | --- | +| **Multi-tenant SaaS** (`api.1claw.xyz`) | Do **not** set `BANKR_PARTNER_KEY`. Every org must configure BYOK. Fallback is off by default. | +| **Self-hosted** | `BANKR_PARTNER_KEY` is optional — only when all orgs intentionally share one Bankr partner account. | + +- **Precedence:** Org BYOK always wins when configured (`org_byok`); deployment key is used only when an org has no BYOK (`platform_fallback`). +- **Opt-in:** Treat deployment fallback as an explicit operator choice — not for shared multi-tenant deployments. +- **Audit:** Each `bankr_key.leased` event records `credential_source` (`org_byok` or `platform_fallback`). +- **Alerting:** Production Vault emits a warning log when `platform_fallback` is used — monitor for unexpected fallback in prod. + **Legacy static path:** Store a long-lived Bankr key at `keys/bankr-api-key` or `providers/bankr/api-key` via `put_secret`, then `get_secret` when calling Bankr endpoints. Manual rotation when the key expires. Never paste `bk_...` or `ocv_...` keys into chat. --- @@ -175,7 +187,7 @@ See `references/mcp-and-api.md` for the full tool list and REST auth flows. ### Bankr Dynamic Key Vending (preferred) -When the org has configured Bankr BYOK (partner key + default wallet under **Settings → Bankr** or `PUT /v1/org/bankr-config`), lease scoped TTL-bound keys instead of storing long-lived `bk_` secrets. Self-hosted operators may use deployment-level `BANKR_PARTNER_KEY` as a fallback when org BYOK is unset. +When the org has configured Bankr BYOK (partner key + default wallet under **Settings → Bankr** or `PUT /v1/org/bankr-config`), lease scoped TTL-bound keys instead of storing long-lived `bk_` secrets. Do not rely on deployment-level `BANKR_PARTNER_KEY` in multi-tenant environments — see **Deployment fallback** above. **Privileged — deny-by-default:** Agents need an explicit policy on the `__agent-keys` vault: diff --git a/1claw/references/mcp-and-api.md b/1claw/references/mcp-and-api.md index 724fbb32ba..564f12dcfd 100644 --- a/1claw/references/mcp-and-api.md +++ b/1claw/references/mcp-and-api.md @@ -108,7 +108,16 @@ Supported chains: `ethereum`, `bitcoin`, `solana`, `xrp`, `cardano`, `tron`. ## Bankr Dynamic Key Vending -Partner-key secret engine for short-lived Bankr wallet API keys. Each org stores its own encrypted `bk_ptr_` via `PUT /v1/org/bankr-config` (Dashboard **Settings → Bankr**); optional deployment `BANKR_PARTNER_KEY` fallback for self-hosted Vault. Partner keys never enter agent vault paths. +Partner-key secret engine for short-lived Bankr wallet API keys. Each org stores its own encrypted `bk_ptr_` via `PUT /v1/org/bankr-config` (Dashboard **Settings → Bankr**). Partner keys never enter agent vault paths. + +**Credential resolution (tenant isolation):** + +| Source | When used | `credential_source` in audit | +| --- | --- | --- | +| Org BYOK | Org has configured `PUT /v1/org/bankr-config` | `org_byok` (always takes precedence) | +| Platform fallback | Self-hosted only; org has no BYOK and `BANKR_PARTNER_KEY` is set | `platform_fallback` | + +Multi-tenant SaaS should leave `BANKR_PARTNER_KEY` unset. Production Vault warns when `platform_fallback` is used. | Endpoint | Purpose | | --- | --- |