An org provider's key is the credential binding named after the provider in that org. Bindings are one instance-wide list that only the system org writes, so an org admin cannot add the key for their own provider. Done when an org admin can add, rotate and remove bindings for their own org only, with secret refs the org owns, and cannot see or change another org's bindings.
Acceptance criteria
Org admins can add, rotate, and remove their org-owned credential bindings without reading or changing another org bindings.
Imported from beads archie-core-kh3n7 · GitHub #1585 · type feature · priority P2 · created 2026-10-10
An org provider's key is the credential binding named after the provider in that org. Bindings are one instance-wide list that only the system org writes, so an org admin cannot add the key for their own provider. Done when an org admin can add, rotate and remove bindings for their own org only, with secret refs the org owns, and cannot see or change another org's bindings.
### Acceptance criteria
Org admins can add, rotate, and remove their org-owned credential bindings without reading or changing another org bindings.
---
_Imported from beads `archie-core-kh3n7` · GitHub #1585 · type feature · priority P2 · created 2026-10-10_
PRD — Orgs manage their own credential bindings (issue #1420 / #1585, beads archie-core-kh3n7)
Status: proposed, needs one maintainer decision (secret ownership, §7) before implementation Type: feature, P2 · Fits: yes — it finishes a half-built seam, and docs/prds/external-agent-harness.md:106 already decided the target state ("A Kit profile, its credential bindings and its OAuth tokens belong to one org. No record is shared between orgs.")
1. Problem
credential-bindings is already an org-keyed control-plane resource, and an org's document is already written and stored — but nothing ever reads it. The only bindings that take effect are the ones the instance admin writes into the system org's list with an explicit org: <id> column.
Verified in code (not by running the system):
Writes land in the caller's org.Server.Query/Command use requestOrg(ctx) = org.OrgFromContext (controlplanestore/controlplane.go:99,159,236), and the dashboard forwards the browser's principal and org after a membership check (rpcidentity/identity.go:66-89). So an org admin's save is stored under their org id.
Reads never look there.storeReader.Query pins storecontract.DefaultOrgID (controlplanestore/runtime_config.go:47) and layerCredentials writes that single document into cfg.Containers.Credentials (identity_grants.go:76-79). The daemon is a bare service caller, so Callers.resolve sets no scope and OrgFromContext returns org-sys (rpcidentity/identity.go:66-73). The org's document is silently ignored — a setting that parses with no consumer.
The org's write is not refused either.CredentialBindingsKind is in neither instanceOnlyKinds nor checkOrgWrite's switch (controlplanestore/org_models.go:166-190), so the store accepts it and reports success.
The dead end is user-visible.checkOrgProviders tells the org its provider key comes from "the org's credential binding named %q" (org_models.go:214-217); modelEgress.providerKey then fails at launch with provider %q has no credential binding named %q in org %s; daemon/kit_task.go:191 parks the task as BlockerModelCredential, and webui/task_recovery.go:44 sends the operator to /org/models — a page that cannot fix it (its link points back at /org/credential-bindings, ui/src/org/OrgModelsPage.vue:121). Same for the Model setup step (webui/api_setup.goproviderCredential) and the harness page (webui/harness.go:142), both of which read the caller's org document and therefore show nothing.
What "works" today is the instance admin's column.config.ContainerConfig.BoundCredentials filters on CredentialBinding.Org (config/config.go:745-764), so the only functioning configuration is an org: acme row written into the system document. The org's own list has no consumer at all.
The UI makes both meanings look the same.CredentialBindingsPage.vue:73-84 offers an Organisation picker on every row while the write goes into the acting org's document — so an instance admin and an org admin produce different results from the same form.
Silent failure is the reason this is worth doing now: the save succeeds, the page reports success, and the run parks later.
2. Proposed solution (recommended shape)
One document per org; resolution reads the run's org document, cached per org. This reuses two mechanisms already in the tree instead of adding new ones:
ModelsFor/deps.OrgModels (controlplanestore/org_models.go:83, staterpc/tasks.go:96, app/statestore/server.go:560-565) — the per-org document read that already backs org providers.
LivePlaybooks (controlplanestore/playbooks_client.go:65-107) — a read in the org's acting context, cached per org and compared by document version. The daemon already derives an org-acting principal (app/archied/issue_discovery.go:60-89) and already reads another org's document that way (alerts.goalertNotify).
2.1 Write side
checkOrgWrite gains a CredentialBindingsKind case (controlplanestore/org_models.go):
a non-system org's entries must not carry another org's id: org empty or equal to the writing org, else ErrValidation naming the field. This closes "two spellings of the same tenancy" inside the org document.
a binding must not be named after an instance provider — same rationale and error style as checkOrgProviders' name-collision refusal, so an org cannot silently substitute the key an instance provider runs on. (Pin this explicitly; it is the one collision that changes billing attribution.)
the secret-ownership rule (§7).
config.ContainerConfig.ValidateCredentialBindings (config/config.go:802) stays as is for the instance document; the per-org document is validated per-org (service non-empty, listed once).
Migration in ImportConfig (controlplanestore/registry.go:95-132, next to migrateTelegramConnection): move each org: <x> entry out of the system document into org <x>'s document when that org has no entry for the service. This carries the file document's [[containers.credentials]] org="acme" rows and any dashboard-written row into the new home, so existing multi-org Telegram channels keep running (archiemessaging/org_channels.go:140-165telegramBindings reads the system document for every org today and must switch to the org's own document).
2.2 Read side
New daemon component, e.g. internal/app/archied/org_credentials.go:
BindingsFor(ctx, orgID) []config.CredentialBinding // org-sys → the layered cfg.Containers.Credentials; else the org's document, cached by (org, version)
Read via the existing control-plane Query in a context acting for orgID — no proto change, no new RPC.
Cache invalidated by the document version the Query returns (the LivePlaybooks pattern), so rotate/remove take effect without a restart and without a per-request round trip on the egress hot path (egress/substitute.go:75, egress/credentials.go:100 call the resolver per proxied request).
Cache misses resolve as unbound (today's behaviour) and the task parks with the existing recovery link.
Needs a warm pass per org (the discovery loop already enumerates orgs and agents). Fallback if the maintainer does not want resolution to depend on an org having an agent principal: a daemon-only control-plane RPC returning a named org's credential-bindings document + version, modelled exactly on ChannelOrgs (controlplanestore/channel_orgs.go:19, caller restricted to the messaging service) — cost is proto + generated code, plus an asserted-org authorisation rule.
2.3 Consumers to switch onto BindingsFor
Consumer
Today
Change
archied/run_credential_resolver.goresolveBinding
cfg.Containers.BoundCredentials(org, …)
org's bindings; same intersection with grants; session path (sessions.GrantedFor) and task path both use the org
archied/model_egress.goOpen/providerKey
merged config
org's bindings (this is what unblocks org providers)
drop the picker; the page edits the acting org's list and says so
ui/src/stores/settings.tscredentialServices
services from the same draft
unchanged (it feeds identity grants' vocabulary)
instanceOnlyKinds stays as it is: credential-bindings remains a kind every org may see and write (its own copy), which is already how Catalog treats it.
3. Acceptance criteria
Add: an org admin (owner/admin role) saves a binding on /org/credential-bindings; it is stored in that org's credential-bindings document, and their org's next run resolves it — no restart, no instance-admin step.
Org provider runs: a task whose org has a provider plus a binding named after that provider launches instead of parking model_credential; modelEgress.providerKey finds the binding.
Rotate: replacing a binding's secret reference, or re-capturing the OAuth token set, changes what the next proxied request receives (the resolver reads the current document version, not a boot-time copy).
Remove: deleting a binding makes the next launch/session unbound — a parked task with BlockerModelCredential and the recovery link, never a stale credential.
No cross-org write: org A cannot create, change or remove a binding that resolves for org B. A non-system document carrying another org's id is refused at write with ErrValidation; the system document cannot be written by a non-system org.
No cross-org read:Query/History in org A return only A's document; no dashboard or RPC surface returns another org's bindings to a non-instance caller. Cross-org forbid is structural (access/roles.goCrossOrgForbidText); a test must assert the refusal, not assume it.
Org-owned secret refs: a non-system org's binding cannot name a secret the org does not own — refused at write with an error naming the rule (§7).
Instance admin: the system org's page manages the instance's own bindings only; no per-row Organisation picker remains anywhere.
Existing org channels keep running through the migration (org Telegram binding moved, not dropped).
Docs:docs/security/authorization.md inventory row updated with the allow/deny cases (docs/security/authorization.md:82, and the rule at :240-243); docs/prds/external-agent-harness.md "Credentials" section states that resolution is per-org.
Tests (AGENTS.md: this is a security-boundary seam, so tests are required): one table test in controlplanestore for the write rules and per-org read; extend archied/run_credential_resolver_test.go's TestEgressResolvesOnlyGrantedCredentials to source bindings from the org's document and keep its "another org's binding is unbound" rows; one test that a non-system document with a foreign org id is refused. Verification: go test -short ./internal/infrastructure/controlplanestore ./internal/app/archied ./internal/infrastructure/kitrun ./internal/config ./internal/webui, then task check.
4. Non-goals
No per-org secret store.internal/secret and infrastructure/secretengine resolve (engine, key) in an instance-wide namespace and are unchanged (secret/engine.go:39-48,124). Ownership is a write-time rule (§7), not a new engine, table or RPC.
No per-org OAuth work. Harness token sets are already keyed (org, service) in the State Store (postgres/queries/harness_secrets.sql) and already per-org; only the binding that names them moves.
No cross-org write API. The instance admin cannot provision a binding into another org's document in this change (that is why the org column is retired rather than kept as an admin override).
No change to identity grants, roles, or the org model policy shape.IdentityGrantsKind has the same silent-ignore pattern (org_models.go:166-190 has no case for it either) — separate issue, file it rather than fix it here.
No egress-proxy redesign, no Forge-connection or notify-secret rework, no change to the run-credential or grant model.
5. Files and components affected
Store/config: controlplanestore/credential_bindings.go (document rules), controlplanestore/org_models.go (checkOrgWrite case), controlplanestore/registry.go + a migrateOrgCredentialBindings beside telegram_connection.go, config/config.go (CredentialBinding/ValidateCredentialBindings docs and per-org validation).
Daemon: new archied/org_credentials.go, wiring in archied/control_plane.go/boot, archied/run_credential_resolver.go, archied/model_egress.go, archied/alerts.go, infrastructure/kitrun/launcher.go, daemon/daemon.go/kit_task.go (dependency interface only).
Other services: archiemessaging/org_channels.go.
UI: ui/src/settings/CredentialBindingsPage.vue, ui/src/org/OrgModelsPage.vue (copy only), possibly ui/src/stores/settings.ts.
Docs: docs/security/authorization.md, docs/prds/external-agent-harness.md.
Tests: controlplanestore/org_models_test.go, archied/run_credential_resolver_test.go, config/credential_org_test.go.
6. Estimated diff size
Hand-written ~500–700 lines across ~16 files, plus ~120–180 lines of tests. No proto or generated code on the recommended path; add ~250 generated lines if the fallback RPC is chosen instead. This is over AGENTS.md's ~100-line resting point, which is why it needs the maintainer's design call — but every piece is an existing mechanism, and the alternative (layer every org's document into the daemon's live config) is larger, because Watch is per-kind in the caller's org and would need per-org watches or a new cross-org read anyway.
7. Decision required: what "secret refs the org owns" means
This does not exist today and is the one genuine product/security decision. A SecretRef is (engine, key) in an instance-wide namespace; POST /api/secret-references/check is instance-only (webui/server.go:346). If org admins can write bindings unchanged, an org admin can bind env:OPENAI_API_KEY (or any instance key) to a service their Kit declares and have the instance's own credential injected for their runs.
Options, with my recommendation:
(A) Org-scoped key namespace, enforced at write (recommended). A non-system org's secret.key must carry the org id as a path segment (e.g. org/<org-id>/…), checked in checkOrgWrite with an error naming the rule. Cheap, no new mechanism, and it stops naming another org's or the instance's key. Caveat to state plainly: the built-in env engine's keys are env-var names, so org API keys in practice have to live in an extension engine (bws, sops) under that prefix, or the operator pre-provisions them. /api/secret-references/check either stays instance-only (org admins save untested refs) or gains an org-scoped variant limited to that prefix.
(B) OAuth-only org writes. Org-written bindings must carry an empty secret (OAuth); the org then owns the value through the setup terminal's per-org token set. Safest, smallest, but an org could never configure an API-key provider — which is most of the acceptance criterion's value.
(C) A real per-org secret store (State Store table, envelope encryption, (org, service) keys, resolver change). Correct long-term, but a new mechanism and out of proportion to this issue.
If the maintainer's answer is "org admins may reference any instance key", say so explicitly and record it in authorization.md — but I recommend (A) and would not green-light the change without an explicit answer here.
8. What I verified vs. did not
Verified by reading the tree (preflight toolchain: go1.27.3; the worktree is on branch feat/1420-orgs-manage-their-own-credential-bindings at 67fa570 with no implementation present): every read/write path, error string, recovery route, consumer list, the absence of an org concept in the secret engines, the per-org harness secret store, and the three precedents the design leans on (ModelsFor, LivePlaybooks, ChannelOrgs).
Not verified: I did not build, run tests, or reproduce the parked-task behaviour at runtime; the diff estimate and the migration's ability to keep a live Telegram channel running are reasoning from code, not measured. Two things to check first in implementation: whether every org that can open a harness setup session also has an agent principal (the cache warm path depends on it), and whether any deployment relies on an instance-admin-written org: binding that the migration cannot map.
Decide in chat or on the dashboard.
**archie's PRD is ready -- awaiting your go/no-go.**
# PRD — Orgs manage their own credential bindings (issue #1420 / #1585, beads `archie-core-kh3n7`)
**Status:** proposed, needs one maintainer decision (secret ownership, §7) before implementation
**Type:** feature, P2 · **Fits:** yes — it finishes a half-built seam, and `docs/prds/external-agent-harness.md:106` already decided the target state ("A Kit profile, its credential bindings and its OAuth tokens belong to one org. No record is shared between orgs.")
## 1. Problem
`credential-bindings` is already an org-keyed control-plane resource, and an org's document is already written and stored — but nothing ever reads it. The only bindings that take effect are the ones the **instance** admin writes into the system org's list with an explicit `org: <id>` column.
Verified in code (not by running the system):
- **Writes land in the caller's org.** `Server.Query`/`Command` use `requestOrg(ctx)` = `org.OrgFromContext` (`controlplanestore/controlplane.go:99,159,236`), and the dashboard forwards the browser's principal and org after a membership check (`rpcidentity/identity.go:66-89`). So an org admin's save is stored under their org id.
- **Reads never look there.** `storeReader.Query` pins `storecontract.DefaultOrgID` (`controlplanestore/runtime_config.go:47`) and `layerCredentials` writes that single document into `cfg.Containers.Credentials` (`identity_grants.go:76-79`). The daemon is a bare service caller, so `Callers.resolve` sets no scope and `OrgFromContext` returns `org-sys` (`rpcidentity/identity.go:66-73`). The org's document is silently ignored — a setting that parses with no consumer.
- **The org's write is not refused either.** `CredentialBindingsKind` is in neither `instanceOnlyKinds` nor `checkOrgWrite`'s switch (`controlplanestore/org_models.go:166-190`), so the store accepts it and reports success.
- **The dead end is user-visible.** `checkOrgProviders` tells the org its provider key comes from "the org's credential binding named %q" (`org_models.go:214-217`); `modelEgress.providerKey` then fails at launch with `provider %q has no credential binding named %q in org %s`; `daemon/kit_task.go:191` parks the task as `BlockerModelCredential`, and `webui/task_recovery.go:44` sends the operator to `/org/models` — a page that cannot fix it (its link points back at `/org/credential-bindings`, `ui/src/org/OrgModelsPage.vue:121`). Same for the Model setup step (`webui/api_setup.go` `providerCredential`) and the harness page (`webui/harness.go:142`), both of which read the caller's org document and therefore show nothing.
- **What "works" today is the instance admin's column.** `config.ContainerConfig.BoundCredentials` filters on `CredentialBinding.Org` (`config/config.go:745-764`), so the only functioning configuration is an `org: acme` row written into the system document. The org's own list has no consumer at all.
- **The UI makes both meanings look the same.** `CredentialBindingsPage.vue:73-84` offers an Organisation picker on every row while the write goes into the *acting* org's document — so an instance admin and an org admin produce different results from the same form.
Silent failure is the reason this is worth doing now: the save succeeds, the page reports success, and the run parks later.
## 2. Proposed solution (recommended shape)
**One document per org; resolution reads the run's org document, cached per org.** This reuses two mechanisms already in the tree instead of adding new ones:
- `ModelsFor`/`deps.OrgModels` (`controlplanestore/org_models.go:83`, `staterpc/tasks.go:96`, `app/statestore/server.go:560-565`) — the per-org document read that already backs org providers.
- `LivePlaybooks` (`controlplanestore/playbooks_client.go:65-107`) — a read in the org's acting context, cached per org and compared by document version. The daemon already derives an org-acting principal (`app/archied/issue_discovery.go:60-89`) and already reads another org's document that way (`alerts.go` `alertNotify`).
### 2.1 Write side
- **`checkOrgWrite` gains a `CredentialBindingsKind` case** (`controlplanestore/org_models.go`):
- a non-system org's entries must not carry another org's id: `org` empty or equal to the writing org, else `ErrValidation` naming the field. This closes "two spellings of the same tenancy" inside the org document.
- a binding must not be named after an **instance provider** — same rationale and error style as `checkOrgProviders`' name-collision refusal, so an org cannot silently substitute the key an instance provider runs on. (Pin this explicitly; it is the one collision that changes billing attribution.)
- the secret-ownership rule (§7).
- `config.ContainerConfig.ValidateCredentialBindings` (`config/config.go:802`) stays as is for the instance document; the per-org document is validated per-org (service non-empty, listed once).
- **Migration** in `ImportConfig` (`controlplanestore/registry.go:95-132`, next to `migrateTelegramConnection`): move each `org: <x>` entry out of the system document into org `<x>`'s document when that org has no entry for the service. This carries the file document's `[[containers.credentials]] org="acme"` rows and any dashboard-written row into the new home, so existing multi-org Telegram channels keep running (`archiemessaging/org_channels.go:140-165` `telegramBindings` reads the system document for every org today and must switch to the org's own document).
### 2.2 Read side
New daemon component, e.g. `internal/app/archied/org_credentials.go`:
```
BindingsFor(ctx, orgID) []config.CredentialBinding // org-sys → the layered cfg.Containers.Credentials; else the org's document, cached by (org, version)
```
- Read via the existing control-plane `Query` in a context acting for `orgID` — no proto change, no new RPC.
- Cache invalidated by the document version the `Query` returns (the `LivePlaybooks` pattern), so rotate/remove take effect without a restart and without a per-request round trip on the egress hot path (`egress/substitute.go:75`, `egress/credentials.go:100` call the resolver per proxied request).
- Cache misses resolve as unbound (today's behaviour) and the task parks with the existing recovery link.
- Needs a warm pass per org (the discovery loop already enumerates orgs and agents). **Fallback if the maintainer does not want resolution to depend on an org having an agent principal:** a daemon-only control-plane RPC returning a named org's `credential-bindings` document + version, modelled exactly on `ChannelOrgs` (`controlplanestore/channel_orgs.go:19`, caller restricted to the messaging service) — cost is proto + generated code, plus an asserted-org authorisation rule.
### 2.3 Consumers to switch onto `BindingsFor`
| Consumer | Today | Change |
| --- | --- | --- |
| `archied/run_credential_resolver.go` `resolveBinding` | `cfg.Containers.BoundCredentials(org, …)` | org's bindings; same intersection with grants; session path (`sessions.GrantedFor`) and task path both use the org |
| `archied/model_egress.go` `Open`/`providerKey` | merged config | org's bindings (this is what unblocks org providers) |
| `kitrun/launcher.go:170,228,331,341` | `l.Config.Get().Containers.Credentials` | a `Bindings(ctx, org)` dependency on `Request.Org` |
| `archied/alerts.go:203-227` `unboundAlerts`, `:396-404` `alertNotify` | merged config | per-org bindings; link becomes `/org/credential-bindings` |
| `archiemessaging/org_channels.go` `telegramBindings` | system document for all orgs | each org's own document (migration in §2.1 keeps current channels alive) |
| `webui/harness.go:142`, `webui/api_setup.go` `providerCredential` | caller's org document | already correct once the document is the live one |
| `ui/src/settings/CredentialBindingsPage.vue` | Organisation picker per row | drop the picker; the page edits the acting org's list and says so |
| `ui/src/stores/settings.ts` `credentialServices` | services from the same draft | unchanged (it feeds identity grants' vocabulary) |
`instanceOnlyKinds` stays as it is: `credential-bindings` remains a kind every org may see and write (its own copy), which is already how `Catalog` treats it.
## 3. Acceptance criteria
1. **Add:** an org admin (owner/admin role) saves a binding on `/org/credential-bindings`; it is stored in that org's `credential-bindings` document, and their org's next run resolves it — no restart, no instance-admin step.
2. **Org provider runs:** a task whose org has a provider plus a binding named after that provider launches instead of parking `model_credential`; `modelEgress.providerKey` finds the binding.
3. **Rotate:** replacing a binding's secret reference, or re-capturing the OAuth token set, changes what the next proxied request receives (the resolver reads the current document version, not a boot-time copy).
4. **Remove:** deleting a binding makes the next launch/session unbound — a parked task with `BlockerModelCredential` and the recovery link, never a stale credential.
5. **No cross-org write:** org A cannot create, change or remove a binding that resolves for org B. A non-system document carrying another org's id is refused at write with `ErrValidation`; the system document cannot be written by a non-system org.
6. **No cross-org read:** `Query`/`History` in org A return only A's document; no dashboard or RPC surface returns another org's bindings to a non-instance caller. Cross-org forbid is structural (`access/roles.go` `CrossOrgForbidText`); a test must assert the refusal, not assume it.
7. **Org-owned secret refs:** a non-system org's binding cannot name a secret the org does not own — refused at write with an error naming the rule (§7).
8. **Instance admin:** the system org's page manages the instance's own bindings only; no per-row Organisation picker remains anywhere.
9. **Existing org channels keep running** through the migration (org Telegram binding moved, not dropped).
10. **Docs:** `docs/security/authorization.md` inventory row updated with the allow/deny cases (`docs/security/authorization.md:82`, and the rule at `:240-243`); `docs/prds/external-agent-harness.md` "Credentials" section states that resolution is per-org.
Tests (AGENTS.md: this is a security-boundary seam, so tests are required): one table test in `controlplanestore` for the write rules and per-org read; extend `archied/run_credential_resolver_test.go`'s `TestEgressResolvesOnlyGrantedCredentials` to source bindings from the org's document and keep its "another org's binding is unbound" rows; one test that a non-system document with a foreign `org` id is refused. Verification: `go test -short ./internal/infrastructure/controlplanestore ./internal/app/archied ./internal/infrastructure/kitrun ./internal/config ./internal/webui`, then `task check`.
## 4. Non-goals
- **No per-org secret store.** `internal/secret` and `infrastructure/secretengine` resolve `(engine, key)` in an instance-wide namespace and are unchanged (`secret/engine.go:39-48,124`). Ownership is a write-time rule (§7), not a new engine, table or RPC.
- **No per-org OAuth work.** Harness token sets are already keyed `(org, service)` in the State Store (`postgres/queries/harness_secrets.sql`) and already per-org; only the binding that names them moves.
- **No cross-org write API.** The instance admin cannot provision a binding into another org's document in this change (that is why the `org` column is retired rather than kept as an admin override).
- **No change to identity grants, roles, or the org model policy shape.** `IdentityGrantsKind` has the same silent-ignore pattern (`org_models.go:166-190` has no case for it either) — separate issue, file it rather than fix it here.
- No egress-proxy redesign, no Forge-connection or notify-secret rework, no change to the run-credential or grant model.
## 5. Files and components affected
Store/config: `controlplanestore/credential_bindings.go` (document rules), `controlplanestore/org_models.go` (`checkOrgWrite` case), `controlplanestore/registry.go` + a `migrateOrgCredentialBindings` beside `telegram_connection.go`, `config/config.go` (`CredentialBinding`/`ValidateCredentialBindings` docs and per-org validation).
Daemon: new `archied/org_credentials.go`, wiring in `archied/control_plane.go`/boot, `archied/run_credential_resolver.go`, `archied/model_egress.go`, `archied/alerts.go`, `infrastructure/kitrun/launcher.go`, `daemon/daemon.go`/`kit_task.go` (dependency interface only).
Other services: `archiemessaging/org_channels.go`.
UI: `ui/src/settings/CredentialBindingsPage.vue`, `ui/src/org/OrgModelsPage.vue` (copy only), possibly `ui/src/stores/settings.ts`.
Docs: `docs/security/authorization.md`, `docs/prds/external-agent-harness.md`.
Tests: `controlplanestore/org_models_test.go`, `archied/run_credential_resolver_test.go`, `config/credential_org_test.go`.
## 6. Estimated diff size
Hand-written **~500–700 lines across ~16 files**, plus **~120–180 lines of tests**. No proto or generated code on the recommended path; add **~250 generated lines** if the fallback RPC is chosen instead. This is over AGENTS.md's ~100-line resting point, which is why it needs the maintainer's design call — but every piece is an existing mechanism, and the alternative (layer every org's document into the daemon's live config) is larger, because `Watch` is per-kind in the caller's org and would need per-org watches or a new cross-org read anyway.
## 7. Decision required: what "secret refs the org owns" means
This does not exist today and is the one genuine product/security decision. A `SecretRef` is `(engine, key)` in an instance-wide namespace; `POST /api/secret-references/check` is instance-only (`webui/server.go:346`). If org admins can write bindings unchanged, an org admin can bind `env:OPENAI_API_KEY` (or any instance key) to a service their Kit declares and have the instance's own credential injected for their runs.
Options, with my recommendation:
- **(A) Org-scoped key namespace, enforced at write (recommended).** A non-system org's `secret.key` must carry the org id as a path segment (e.g. `org/<org-id>/…`), checked in `checkOrgWrite` with an error naming the rule. Cheap, no new mechanism, and it stops naming another org's or the instance's key. Caveat to state plainly: the built-in `env` engine's keys are env-var names, so org API keys in practice have to live in an extension engine (`bws`, `sops`) under that prefix, or the operator pre-provisions them. `/api/secret-references/check` either stays instance-only (org admins save untested refs) or gains an org-scoped variant limited to that prefix.
- **(B) OAuth-only org writes.** Org-written bindings must carry an empty secret (OAuth); the org then owns the value through the setup terminal's per-org token set. Safest, smallest, but an org could never configure an API-key provider — which is most of the acceptance criterion's value.
- **(C) A real per-org secret store** (State Store table, envelope encryption, `(org, service)` keys, resolver change). Correct long-term, but a new mechanism and out of proportion to this issue.
If the maintainer's answer is "org admins may reference any instance key", say so explicitly and record it in `authorization.md` — but I recommend (A) and would not green-light the change without an explicit answer here.
## 8. What I verified vs. did not
Verified by reading the tree (preflight toolchain: go1.27.3; the worktree is on branch `feat/1420-orgs-manage-their-own-credential-bindings` at 67fa570 with no implementation present): every read/write path, error string, recovery route, consumer list, the absence of an org concept in the secret engines, the per-org harness secret store, and the three precedents the design leans on (`ModelsFor`, `LivePlaybooks`, `ChannelOrgs`).
Not verified: I did not build, run tests, or reproduce the parked-task behaviour at runtime; the diff estimate and the migration's ability to keep a live Telegram channel running are reasoning from code, not measured. Two things to check first in implementation: whether every org that can open a harness setup session also has an agent principal (the cache warm path depends on it), and whether any deployment relies on an instance-admin-written `org:` binding that the migration cannot map.
_Decide in chat or on the dashboard._
sam
added the deferred label 2026-11-15 17:26:17 +00:00
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
An org provider's key is the credential binding named after the provider in that org. Bindings are one instance-wide list that only the system org writes, so an org admin cannot add the key for their own provider. Done when an org admin can add, rotate and remove bindings for their own org only, with secret refs the org owns, and cannot see or change another org's bindings.
Acceptance criteria
Org admins can add, rotate, and remove their org-owned credential bindings without reading or changing another org bindings.
Imported from beads
archie-core-kh3n7· GitHub #1585 · type feature · priority P2 · created 2026-10-10archie's PRD is ready -- awaiting your go/no-go.
PRD — Orgs manage their own credential bindings (issue #1420 / #1585, beads
archie-core-kh3n7)Status: proposed, needs one maintainer decision (secret ownership, §7) before implementation
Type: feature, P2 · Fits: yes — it finishes a half-built seam, and
docs/prds/external-agent-harness.md:106already decided the target state ("A Kit profile, its credential bindings and its OAuth tokens belong to one org. No record is shared between orgs.")1. Problem
credential-bindingsis already an org-keyed control-plane resource, and an org's document is already written and stored — but nothing ever reads it. The only bindings that take effect are the ones the instance admin writes into the system org's list with an explicitorg: <id>column.Verified in code (not by running the system):
Server.Query/CommanduserequestOrg(ctx)=org.OrgFromContext(controlplanestore/controlplane.go:99,159,236), and the dashboard forwards the browser's principal and org after a membership check (rpcidentity/identity.go:66-89). So an org admin's save is stored under their org id.storeReader.Querypinsstorecontract.DefaultOrgID(controlplanestore/runtime_config.go:47) andlayerCredentialswrites that single document intocfg.Containers.Credentials(identity_grants.go:76-79). The daemon is a bare service caller, soCallers.resolvesets no scope andOrgFromContextreturnsorg-sys(rpcidentity/identity.go:66-73). The org's document is silently ignored — a setting that parses with no consumer.CredentialBindingsKindis in neitherinstanceOnlyKindsnorcheckOrgWrite's switch (controlplanestore/org_models.go:166-190), so the store accepts it and reports success.checkOrgProviderstells the org its provider key comes from "the org's credential binding named %q" (org_models.go:214-217);modelEgress.providerKeythen fails at launch withprovider %q has no credential binding named %q in org %s;daemon/kit_task.go:191parks the task asBlockerModelCredential, andwebui/task_recovery.go:44sends the operator to/org/models— a page that cannot fix it (its link points back at/org/credential-bindings,ui/src/org/OrgModelsPage.vue:121). Same for the Model setup step (webui/api_setup.goproviderCredential) and the harness page (webui/harness.go:142), both of which read the caller's org document and therefore show nothing.config.ContainerConfig.BoundCredentialsfilters onCredentialBinding.Org(config/config.go:745-764), so the only functioning configuration is anorg: acmerow written into the system document. The org's own list has no consumer at all.CredentialBindingsPage.vue:73-84offers an Organisation picker on every row while the write goes into the acting org's document — so an instance admin and an org admin produce different results from the same form.Silent failure is the reason this is worth doing now: the save succeeds, the page reports success, and the run parks later.
2. Proposed solution (recommended shape)
One document per org; resolution reads the run's org document, cached per org. This reuses two mechanisms already in the tree instead of adding new ones:
ModelsFor/deps.OrgModels(controlplanestore/org_models.go:83,staterpc/tasks.go:96,app/statestore/server.go:560-565) — the per-org document read that already backs org providers.LivePlaybooks(controlplanestore/playbooks_client.go:65-107) — a read in the org's acting context, cached per org and compared by document version. The daemon already derives an org-acting principal (app/archied/issue_discovery.go:60-89) and already reads another org's document that way (alerts.goalertNotify).2.1 Write side
checkOrgWritegains aCredentialBindingsKindcase (controlplanestore/org_models.go):orgempty or equal to the writing org, elseErrValidationnaming the field. This closes "two spellings of the same tenancy" inside the org document.checkOrgProviders' name-collision refusal, so an org cannot silently substitute the key an instance provider runs on. (Pin this explicitly; it is the one collision that changes billing attribution.)config.ContainerConfig.ValidateCredentialBindings(config/config.go:802) stays as is for the instance document; the per-org document is validated per-org (service non-empty, listed once).ImportConfig(controlplanestore/registry.go:95-132, next tomigrateTelegramConnection): move eachorg: <x>entry out of the system document into org<x>'s document when that org has no entry for the service. This carries the file document's[[containers.credentials]] org="acme"rows and any dashboard-written row into the new home, so existing multi-org Telegram channels keep running (archiemessaging/org_channels.go:140-165telegramBindingsreads the system document for every org today and must switch to the org's own document).2.2 Read side
New daemon component, e.g.
internal/app/archied/org_credentials.go:Queryin a context acting fororgID— no proto change, no new RPC.Queryreturns (theLivePlaybookspattern), so rotate/remove take effect without a restart and without a per-request round trip on the egress hot path (egress/substitute.go:75,egress/credentials.go:100call the resolver per proxied request).credential-bindingsdocument + version, modelled exactly onChannelOrgs(controlplanestore/channel_orgs.go:19, caller restricted to the messaging service) — cost is proto + generated code, plus an asserted-org authorisation rule.2.3 Consumers to switch onto
BindingsForarchied/run_credential_resolver.goresolveBindingcfg.Containers.BoundCredentials(org, …)sessions.GrantedFor) and task path both use the orgarchied/model_egress.goOpen/providerKeykitrun/launcher.go:170,228,331,341l.Config.Get().Containers.CredentialsBindings(ctx, org)dependency onRequest.Orgarchied/alerts.go:203-227unboundAlerts,:396-404alertNotify/org/credential-bindingsarchiemessaging/org_channels.gotelegramBindingswebui/harness.go:142,webui/api_setup.goproviderCredentialui/src/settings/CredentialBindingsPage.vueui/src/stores/settings.tscredentialServicesinstanceOnlyKindsstays as it is:credential-bindingsremains a kind every org may see and write (its own copy), which is already howCatalogtreats it.3. Acceptance criteria
/org/credential-bindings; it is stored in that org'scredential-bindingsdocument, and their org's next run resolves it — no restart, no instance-admin step.model_credential;modelEgress.providerKeyfinds the binding.BlockerModelCredentialand the recovery link, never a stale credential.ErrValidation; the system document cannot be written by a non-system org.Query/Historyin org A return only A's document; no dashboard or RPC surface returns another org's bindings to a non-instance caller. Cross-org forbid is structural (access/roles.goCrossOrgForbidText); a test must assert the refusal, not assume it.docs/security/authorization.mdinventory row updated with the allow/deny cases (docs/security/authorization.md:82, and the rule at:240-243);docs/prds/external-agent-harness.md"Credentials" section states that resolution is per-org.Tests (AGENTS.md: this is a security-boundary seam, so tests are required): one table test in
controlplanestorefor the write rules and per-org read; extendarchied/run_credential_resolver_test.go'sTestEgressResolvesOnlyGrantedCredentialsto source bindings from the org's document and keep its "another org's binding is unbound" rows; one test that a non-system document with a foreignorgid is refused. Verification:go test -short ./internal/infrastructure/controlplanestore ./internal/app/archied ./internal/infrastructure/kitrun ./internal/config ./internal/webui, thentask check.4. Non-goals
internal/secretandinfrastructure/secretengineresolve(engine, key)in an instance-wide namespace and are unchanged (secret/engine.go:39-48,124). Ownership is a write-time rule (§7), not a new engine, table or RPC.(org, service)in the State Store (postgres/queries/harness_secrets.sql) and already per-org; only the binding that names them moves.orgcolumn is retired rather than kept as an admin override).IdentityGrantsKindhas the same silent-ignore pattern (org_models.go:166-190has no case for it either) — separate issue, file it rather than fix it here.5. Files and components affected
Store/config:
controlplanestore/credential_bindings.go(document rules),controlplanestore/org_models.go(checkOrgWritecase),controlplanestore/registry.go+ amigrateOrgCredentialBindingsbesidetelegram_connection.go,config/config.go(CredentialBinding/ValidateCredentialBindingsdocs and per-org validation).Daemon: new
archied/org_credentials.go, wiring inarchied/control_plane.go/boot,archied/run_credential_resolver.go,archied/model_egress.go,archied/alerts.go,infrastructure/kitrun/launcher.go,daemon/daemon.go/kit_task.go(dependency interface only).Other services:
archiemessaging/org_channels.go.UI:
ui/src/settings/CredentialBindingsPage.vue,ui/src/org/OrgModelsPage.vue(copy only), possiblyui/src/stores/settings.ts.Docs:
docs/security/authorization.md,docs/prds/external-agent-harness.md.Tests:
controlplanestore/org_models_test.go,archied/run_credential_resolver_test.go,config/credential_org_test.go.6. Estimated diff size
Hand-written ~500–700 lines across ~16 files, plus ~120–180 lines of tests. No proto or generated code on the recommended path; add ~250 generated lines if the fallback RPC is chosen instead. This is over AGENTS.md's ~100-line resting point, which is why it needs the maintainer's design call — but every piece is an existing mechanism, and the alternative (layer every org's document into the daemon's live config) is larger, because
Watchis per-kind in the caller's org and would need per-org watches or a new cross-org read anyway.7. Decision required: what "secret refs the org owns" means
This does not exist today and is the one genuine product/security decision. A
SecretRefis(engine, key)in an instance-wide namespace;POST /api/secret-references/checkis instance-only (webui/server.go:346). If org admins can write bindings unchanged, an org admin can bindenv:OPENAI_API_KEY(or any instance key) to a service their Kit declares and have the instance's own credential injected for their runs.Options, with my recommendation:
secret.keymust carry the org id as a path segment (e.g.org/<org-id>/…), checked incheckOrgWritewith an error naming the rule. Cheap, no new mechanism, and it stops naming another org's or the instance's key. Caveat to state plainly: the built-inenvengine's keys are env-var names, so org API keys in practice have to live in an extension engine (bws,sops) under that prefix, or the operator pre-provisions them./api/secret-references/checkeither stays instance-only (org admins save untested refs) or gains an org-scoped variant limited to that prefix.(org, service)keys, resolver change). Correct long-term, but a new mechanism and out of proportion to this issue.If the maintainer's answer is "org admins may reference any instance key", say so explicitly and record it in
authorization.md— but I recommend (A) and would not green-light the change without an explicit answer here.8. What I verified vs. did not
Verified by reading the tree (preflight toolchain: go1.27.3; the worktree is on branch
feat/1420-orgs-manage-their-own-credential-bindingsat67fa570with no implementation present): every read/write path, error string, recovery route, consumer list, the absence of an org concept in the secret engines, the per-org harness secret store, and the three precedents the design leans on (ModelsFor,LivePlaybooks,ChannelOrgs).Not verified: I did not build, run tests, or reproduce the parked-task behaviour at runtime; the diff estimate and the migration's ability to keep a live Telegram channel running are reasoning from code, not measured. Two things to check first in implementation: whether every org that can open a harness setup session also has an agent principal (the cache warm path depends on it), and whether any deployment relies on an instance-admin-written
org:binding that the migration cannot map.Decide in chat or on the dashboard.