From fe717fa879c3e74fb658b17a3e40b4972fd4ea6e Mon Sep 17 00:00:00 2001 From: rkoster Date: Thu, 17 Sep 2026 12:18:53 +0200 Subject: [PATCH 1/3] docs: define SpiceDB research note --- ...2026-09-17-spicedb-research-note-design.md | 45 +++++++++++++++++++ 1 file changed, 45 insertions(+) create mode 100644 docs/superpowers/specs/2026-09-17-spicedb-research-note-design.md diff --git a/docs/superpowers/specs/2026-09-17-spicedb-research-note-design.md b/docs/superpowers/specs/2026-09-17-spicedb-research-note-design.md new file mode 100644 index 0000000..120d8df --- /dev/null +++ b/docs/superpowers/specs/2026-09-17-spicedb-research-note-design.md @@ -0,0 +1,45 @@ +# SpiceDB Research Note Design + +## Goal + +Add a sourced research note on SpiceDB as a fine-grained authorization substrate for agents, +tools, and Cloud Foundry resources. + +## Scope + +The note will cover SpiceDB's Zanzibar-inspired architecture: schema-defined relationships, +permissions, consistency, caveated relationships, reverse lookups, datastore/API boundaries, +and the separation of authentication from authorization. It will then assess a possible CF +integration in which instance identity certificates are verified outside SpiceDB and mapped to +stable authorization subjects. + +The CF analysis will use examples involving agents accessing spaces, applications, routes, +service bindings, tools, and other resources. It will discuss a shared SpiceDB service, +relationship synchronization from CAPI/Diego events, certificate rotation and revocation, +tenant isolation, latency/availability, and audit implications. It will not claim that SpiceDB +validates CF instance identity certificates natively. + +## Structure + +Create `research/spicedb.md` using the repository template and required sections: + +1. Summary +2. Key findings +3. CF relevance +4. Open questions + +Use provisional ratings and clearly label Cloud Foundry integration ideas as analysis or open +questions rather than existing SpiceDB features. + +## Sources and evidence + +Use the SpiceDB GitHub repository and README, official concepts/modeling/consistency/API +documentation where available, and the Zanzibar paper link referenced by the project. Claims +about CF instance identity certificates, CAPI/Diego synchronization, and agent authorization +will be framed as proposed integration boundaries. + +## Validation + +Run the repository's configured Devbox validation and test scripts, inspect whitespace and the +staged diff, then commit the note, plan, and this design spec on `research/spicedb`. Push the +branch and open a new PR targeting `main` without staging unrelated environment artifacts. From 1f256c3fa6f53a7344cde86e11bee8c61dcf434e Mon Sep 17 00:00:00 2001 From: rkoster Date: Thu, 17 Sep 2026 12:20:21 +0200 Subject: [PATCH 2/3] docs: add SpiceDB research note --- .../plans/2026-09-17-spicedb-research-note.md | 46 +++++++ research/spicedb.md | 128 ++++++++++++++++++ 2 files changed, 174 insertions(+) create mode 100644 docs/superpowers/plans/2026-09-17-spicedb-research-note.md create mode 100644 research/spicedb.md diff --git a/docs/superpowers/plans/2026-09-17-spicedb-research-note.md b/docs/superpowers/plans/2026-09-17-spicedb-research-note.md new file mode 100644 index 0000000..e2ff61b --- /dev/null +++ b/docs/superpowers/plans/2026-09-17-spicedb-research-note.md @@ -0,0 +1,46 @@ +# SpiceDB Research Note Implementation Plan + +> **For agentic workers:** Execute this plan inline with validation checkpoints. + +**Goal:** Add and publish a sourced research note on SpiceDB as a fine-grained authorization substrate for agents and Cloud Foundry resources. + +**Architecture:** Describe SpiceDB's schema, relationship, permission-check, consistency, and datastore/API model. Then analyze a CF integration boundary where an external certificate-verifying component maps instance identities to stable SpiceDB subjects and applications ask SpiceDB for authorization decisions. + +**Tech Stack:** Markdown, YAML frontmatter, Devbox, Git, GitHub CLI. + +--- + +### Task 1: Write the SpiceDB research note + +**Files:** +- Create: `research/spicedb.md` + +- [ ] Add frontmatter with title `SpiceDB: Fine-Grained Authorization for Agents and Cloud Foundry`, author `Ruben Koster (@rkoster)`, date `2026-09-17`, tags `[authorization, identity, agent-runtime, ecosystem-survey]`, `cf_areas: [uaa, capi, diego]`, `status: draft`, provisional ratings, and links to SpiceDB's repository, README, concepts, modeling, consistency, API, and Zanzibar sources. +- [ ] Explain SpiceDB as a Zanzibar-inspired authorization database where schemas define relations and permissions, relationship tuples store facts, and clients issue checks or reverse lookups. +- [ ] Cover consistency choices, caveated relationships, schema validation/tooling, supported datastores, gRPC/HTTP APIs, and the separation between authentication and authorization. +- [ ] Explain agent/tool examples: an agent instance requesting access to a CF space, app, route, service binding, or tool, with relations representing ownership, delegation, membership, and environment boundaries. +- [ ] Describe a proposed CF boundary where a gateway or policy service verifies an instance identity certificate, maps its verified identity to a stable subject, and queries SpiceDB; do not claim native certificate validation in SpiceDB. +- [ ] Assess relationship synchronization from CAPI/Diego events, certificate rotation and revocation, latency/availability, tenant isolation, fail-open/fail-closed behavior, and auditability. +- [ ] Add open questions around canonical subject IDs, delegated agent authority, stale tuples, revocation timing, policy ownership, and operational placement. + +### Task 2: Validate and inspect + +**Files:** +- Test: `.github/scripts/validate_notes.py` + +- [ ] Run `devbox run validate` and expect all research notes and ideas to be valid. +- [ ] Run `devbox run test` and expect success. +- [ ] Run `git diff --check` and inspect `git status --short`; leave unrelated environment artifacts unstaged. + +### Task 3: Commit and publish + +**Files:** +- Include: `research/spicedb.md` +- Include: `docs/superpowers/specs/2026-09-17-spicedb-research-note-design.md` +- Include: `docs/superpowers/plans/2026-09-17-spicedb-research-note.md` + +- [ ] Stage only the three intended files, using `git add -f` for ignored planning artifacts. +- [ ] Commit with `docs: add SpiceDB research note`. +- [ ] Push `research/spicedb` to origin. +- [ ] Open a PR titled `docs: add SpiceDB research note` targeting `main`, with the repository checklist completed. +- [ ] Verify the PR URL, branch, state, and CI status with `gh pr view`. diff --git a/research/spicedb.md b/research/spicedb.md new file mode 100644 index 0000000..3640354 --- /dev/null +++ b/research/spicedb.md @@ -0,0 +1,128 @@ +--- +title: "SpiceDB: Fine-Grained Authorization for Agents and Cloud Foundry" +author: Ruben Koster (@rkoster) +date: 2026-09-17 +tags: [authorization, identity, agent-runtime, ecosystem-survey] +cf_areas: [uaa, capi, diego] +status: draft +ratings: + platform-impact: + value: 84 + note: "Centralized relationship-based authorization could give agents and tools consistent access decisions across CF spaces, apps, and services." + maturity: + value: 82 + note: "SpiceDB is a mature, actively maintained Zanzibar-inspired authorization system with production use claims, multiple datastores, and client APIs." + novelty: + value: 62 + note: "The core model follows Zanzibar, while caveats and reverse lookups make it a practical foundation for complex agent and platform authorization." + actionability: + value: 80 + note: "The schema and tuple model provides a concrete way to prototype agent identity and delegated access policies, subject to CF identity integration work." +sources: + - https://github.com/authzed/spicedb + - https://raw.githubusercontent.com/authzed/spicedb/main/README.md + - https://authzed.com/docs/spicedb/concepts/schema + - https://authzed.com/docs/spicedb/concepts/consistency + - https://authzed.com/docs/spicedb/modeling/relationship-based-access-control + - https://authzed.com/docs/spicedb/modeling/caveats + - https://authzed.com/docs/spicedb/api/grpc + - https://research.google/pubs/zanzibar-googles-consistent-global-authorization-system/ +--- + +## Summary + +SpiceDB is an open-source, Zanzibar-inspired database for storing and querying fine-grained +authorization relationships. Applications define a schema, write relationship tuples, and +ask SpiceDB whether a subject has a permission on a resource; reverse lookups answer questions +such as who can access a resource or what a subject can do. For Cloud Foundry agent workloads, +SpiceDB is a candidate authorization substrate for agent-to-tool and agent-to-platform access, +but an external component would still need to authenticate instance identity certificates and +map them to stable authorization subjects. + +## Key findings + +- **SpiceDB separates authorization from authentication.** Its focus is evaluating whether a + subject may perform an action. The project is intentionally agnostic to authentication + systems and identity providers, which leaves certificate verification and identity lifecycle + to a gateway, application, or platform identity service. +- **Schemas describe the authorization graph.** Developers define resource types, relations, + and permissions. Relationship data then connects subjects to resources, while permissions + compute allowed actions through direct relations, unions, intersections, exclusions, and + traversals through related resources. +- **The data model fits platform hierarchies.** A schema can represent subjects such as users, + service accounts, agent instances, groups, spaces, applications, routes, tools, and service + bindings. A permission can inherit through relationships, for example an agent authorized + for a space receiving a narrower or broader permission on applications within that space. +- **Checks are designed for distributed authorization.** Clients can issue permission checks + and other queries through gRPC, HTTP, or client libraries. SpiceDB exposes consistency choices + so callers can trade freshness and latency according to the risk of using a recently changed + relationship. +- **Caveated relationships add contextual conditions.** Caveats can attach additional + expression-based conditions to relationships, combining relationship-based access control + with request context. This is potentially useful for agent policies that depend on a + deployment, environment, time window, or other request attributes, but the platform must + define which context is trusted and how it is supplied. +- **Reverse lookups are useful for control and audit workflows.** In addition to asking whether + an agent can access a resource, callers can query which subjects have a permission or what + resources a subject can access. These queries can support authorization review, tool catalog + filtering, and incident investigation, subject to query cost and privacy controls. +- **SpiceDB supports external durable datastores.** The project documents support for systems + including PostgreSQL, CockroachDB, MySQL, and Google Cloud Spanner. This lets operators choose + a persistence and availability architecture separately from the authorization API, but makes + datastore migration, consistency, backups, and schema/tuple rollout operational concerns. +- **An agent identity boundary is required for CF.** A possible CF design would have a gateway + or policy service validate an instance identity certificate, establish the workload's trusted + identity, and map it to a stable SpiceDB subject such as `agent_instance:`. SpiceDB + would then evaluate the subject's relationships. This is a proposed integration boundary; + SpiceDB itself should not be assumed to validate CF instance identity certificates. +- **Relationship data would need lifecycle synchronization.** CAPI, Diego, UAA, service + brokers, or another platform source could publish changes such as space membership, app + ownership, binding creation, instance replacement, and revocation. Tuple freshness becomes a + security property: stale grants can outlive a certificate or application lifecycle event. +- **SpiceDB is an authorization service, not an agent runtime.** It does not execute agents, + issue identity certificates, manage CF application lifecycle, or replace network policy. It + can provide a decision point that agent runtimes, tool gateways, and platform APIs call. + +## CF relevance + +Cloud Foundry could use SpiceDB as a shared fine-grained authorization service for agentic +workloads. An agent instance might present its CF instance identity certificate to a gateway; +the gateway would validate the certificate and bind the request to a stable workload identity. +The gateway or application would then ask SpiceDB whether that identity may invoke a tool, +read a service binding, access an application, or operate on a resource in a particular space. +This separates proof of identity from policy evaluation and avoids distributing a large, +platform-wide authorization graph into every agent process. + +The same model could express delegation: a platform-managed agent controller may be allowed to +create or operate on agents in a space, while an individual agent receives only the permissions +needed for its task. Relations could connect an agent instance to a deployment, app, space, +organization, tool, or service binding, with caveats supplying bounded context such as an +environment or expiration condition. The exact schema would be a CF design decision, not an +existing SpiceDB integration. + +Operating this as a platform capability would require a reliable relationship ingestion path. +CAPI and Diego events could update tuples as applications, instances, spaces, bindings, and +routes change. Certificate rotation and instance replacement would need stable subject and +revocation semantics so that a new instance does not accidentally inherit an old instance's +authority. Operators would also need to choose fail-closed behavior for security-sensitive +actions, bounded caching for availability, and audit correlation between the certificate, +SpiceDB subject, authorization decision, and resulting platform operation. + +## Open questions + +- What is the canonical SpiceDB subject for a CF agent: application, process instance, + instance identity certificate, service account, or a composite of these? +- Which component should verify CF instance identity certificates and perform the mapping to + SpiceDB subjects, and how should certificate rotation and revocation invalidate authority? +- Which CAPI, Diego, UAA, broker, and routing events must update relationships, and what tuple + staleness is acceptable for each permission class? +- How should delegated agent authority be represented without allowing an agent to mint or + transfer permissions beyond its own grant? +- Which agent-to-tool and agent-to-resource checks need caveats, and which request context can + be trusted by the authorization service? +- What should happen when SpiceDB is unavailable or a consistency requirement cannot be met: + fail closed, use a bounded cached decision, or permit only a restricted operation set? +- How should authorization decisions, relationship writes, certificate identities, and CF + audit events be correlated without exposing sensitive policy data? +- Should each CF foundation run a shared SpiceDB service, or should authorization be isolated + per foundation, org, space, or agent platform? From 8aa383dfd0f56f34e0bf4cec0f8d89d81ca3696e Mon Sep 17 00:00:00 2001 From: rkoster Date: Sat, 19 Sep 2026 16:29:01 +0200 Subject: [PATCH 3/3] docs: update generated research map --- generated/research-map.html | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/generated/research-map.html b/generated/research-map.html index bbe5f21..dd72027 100644 --- a/generated/research-map.html +++ b/generated/research-map.html @@ -23,9 +23,9 @@

Focus use cases

Attested Workload Authority and Mediated Tool AccessExchange platform-attested workload identity for scoped authority while credentials and outbound tool access remain mediated by the platform.Strategic decision: Decide whether CF should become the portable trust and policy layer between agent workloads and the tools they invoke.
Gap, experiments, and evidence
Current CF gap
CF issues workload identity certificates but does not exchange them for scoped tool authority, keep third-party credentials out of workloads, mediate off-platform access, or record delegation-aware audit events.
Candidate POC
Exchange a Diego instance identity certificate for a short-lived scoped token, invoke one allowed tool through a credential proxy and egress mediator, deny another, and emit attributable audit events.
Candidate RFC scope
Define workload token exchange, authority and delegation claims, credential brokering, outbound mediation and policy enforcement, audit events, revocation, and integration boundaries for UAA, routing, and service brokers.

Core

Supporting

-
Gap, experiments, and evidence
Current CF gap
CF can stage apps and run ephemeral tasks but cannot cheaply compose a reusable environment with per-session workspace state, select stronger isolation, constrain session networking, or resume the session lifecycle.
Candidate POC
Start two isolated sessions from one content-addressed staged environment, attach separate mutable workspaces, apply per-session egress policy, stop one session, and resume it on fresh compute.
Candidate RFC scope
Define environment and workspace references, session identity and lifecycle, isolation classes, network policy, workspace persistence and cleanup, scheduling, quotas, and compatibility with existing CF staging and task APIs.

Core

Supporting

ResearchIdea

Platform Impact x Maturity

Emerging < Maturity > EstablishedLocal concern < Platform Impact > Platform-wide concern
Unplaced notes (0)
  • All notes are placed.
+
Gap, experiments, and evidence
Current CF gap
CF can stage apps and run ephemeral tasks but cannot cheaply compose a reusable environment with per-session workspace state, select stronger isolation, constrain session networking, or resume the session lifecycle.
Candidate POC
Start two isolated sessions from one content-addressed staged environment, attach separate mutable workspaces, apply per-session egress policy, stop one session, and resume it on fresh compute.
Candidate RFC scope
Define environment and workspace references, session identity and lifecycle, isolation classes, network policy, workspace persistence and cleanup, scheduling, quotas, and compatibility with existing CF staging and task APIs.

Core

Supporting

ResearchIdea

Platform Impact x Maturity

Emerging < Maturity > EstablishedLocal concern < Platform Impact > Platform-wide concern
Unplaced notes (0)
  • All notes are placed.
 -