SpiceDB: Zanzibar open-source na prática

A implementação Zanzibar mais madura

SpiceDB é o produto da Authzed, fundada por engenheiros vindos do Red Hat/CoreOS. Open-source desde 2021, Apache 2.0. É hoje a implementação ReBAC mais alinhada ao paper Zanzibar — mantém zookies (rebatizados ZedTokens), userset rewrites, namespaces, APIs Check/Expand/Lookup, e ainda adicionou caveats (ABAC condicional).

LinguagemGo — single binary spicedb, fácil de containerizar

StoragePostgres, CockroachDB, Spanner, MySQL (em ordem de maturidade)

APIgRPC primário + HTTP/JSON gateway; SDKs em Go, Java, Node, Python, Ruby

Performancesub-ms checks em cache hot, p99 < 10ms em produção típica

CloudAuthzed Dedicated / Serverless — managed; SpiceDB self-host livre

Schema Language: declarando o domínio

A primeira coisa a desenhar é o schema. SpiceDB tem uma DSL própria, type-safe, com tooling (zed CLI, playground.authzed.com). Exemplo de schema Drive-like:

schema.zed

definition user {}

definition organization {
  relation admin: user
  relation member: user

  permission manage = admin
  permission view = admin + member
}

definition folder {
  relation parent: folder | organization
  relation owner: user
  relation editor: user
  relation viewer: user

  permission write = owner + editor + parent->write
  permission read  = viewer + write + parent->read
}

definition document {
  relation parent: folder
  relation owner: user
  relation editor: user
  relation viewer: user

  permission write = owner + editor + parent->write
  permission read  = viewer + write + parent->read
  permission share = owner + parent->write
}

definition X {}declara o tipo de objeto (user, folder, document)

relation r: Taceita tuplas vinculando este objeto a usuários do tipo T

+ / & / -union, intersection, exclusion na composição de permissions

parent->readtuple-to-userset: para cada tupla parent, avalia read no objeto pai

| (pipe)union de tipos aceitos: parent: folder | organization

💡

Essa DSL substitui o protobuf de namespace config do paper Zanzibar — mesma expressividade, leitura humana. aplica em prod; versionado em git.

Os 4 verbos da API

API	Quando usar	Latência alvo
WriteRelationships	Criar/deletar tuplas (compartilhar doc, adicionar membro)	~10-30ms (storage commit)
CheckPermission	Pode user X fazer ação Y no recurso Z? — path do request HTTP	<10ms p99 (cache hot)
LookupResources	"Quais docs Tom pode ler?" — UI de listagem do user	Stream; depende do fan-out
LookupSubjects	"Quem tem acesso ao doc X?" — UI de admin/share	Stream; depende do grafo
ExpandPermission	Debug: quem deriva essa perm e por quê	~50ms; uso esporádico
ReadRelationships	Listar tuplas brutas (compliance, audit)	Stream paginado

APIWriteRelationships

Quando usarCriar/deletar tuplas (compartilhar doc, adicionar membro)

Latência alvo~10-30ms (storage commit)

APICheckPermission

Quando usarPode user X fazer ação Y no recurso Z? — path do request HTTP

Latência alvo<10ms p99 (cache hot)

APILookupResources

Quando usar"Quais docs Tom pode ler?" — UI de listagem do user

Latência alvoStream; depende do fan-out

APILookupSubjects

Quando usar"Quem tem acesso ao doc X?" — UI de admin/share

Latência alvoStream; depende do grafo

APIExpandPermission

Quando usarDebug: quem deriva essa perm e por quê

Latência alvo~50ms; uso esporádico

APIReadRelationships

Quando usarListar tuplas brutas (compliance, audit)

Latência alvoStream paginado

Exemplo end-to-end: compartilhar e checar

app/share.ts

import { v1 } from '@authzed/authzed-node';

const client = v1.NewClient('YOUR_API_TOKEN', 'spicedb.example.com:50051');

// 1. Alice compartilha doc:report-q1 com Bob como editor
const writeResp = await client.promises.writeRelationships(
  v1.WriteRelationshipsRequest.create({
    updates: [
      v1.RelationshipUpdate.create({
        operation: v1.RelationshipUpdate_Operation.CREATE,
        relationship: v1.Relationship.create({
          resource: { objectType: 'document', objectId: 'report-q1' },
          relation: 'editor',
          subject: { object: { objectType: 'user', objectId: 'bob' } },
        }),
      }),
    ],
  }),
);

// IMPORTANTE: guardar o zedToken retornado
const zedToken = writeResp.writtenAt;  // ex: 'GhUKEzE2Nz...'
await db.documents.update({
  where: { id: 'report-q1' },
  data: { authzZedToken: zedToken.token },
});

// 2. Bob faz GET /docs/report-q1 — middleware checa
const check = await client.promises.checkPermission(
  v1.CheckPermissionRequest.create({
    resource: { objectType: 'document', objectId: 'report-q1' },
    permission: 'read',
    subject: { object: { objectType: 'user', objectId: 'bob' } },
    consistency: v1.Consistency.create({
      requirement: { oneofKind: 'atLeastAsFresh',
        atLeastAsFresh: { text: doc.authzZedToken },
      },
    }),
  }),
);

if (check.permissionship !== v1.CheckPermissionResponse_Permissionship.HAS_PERMISSION) {
  throw new ForbiddenError();
}

⚠️

O persistido junto ao recurso é o que garante consistência. Sem ele, você pode ler dados com permissões obsoletas — exatamente o new enemy problem.

Caveats: ABAC dentro de ReBAC

A maior limitação histórica do ReBAC puro: como expressar "Bob pode ler MAS apenas do escritório (IP no CIDR corporativo)"? Em SpiceDB pós-2023, caveats resolvem isso via expressões CEL avaliadas em runtime.

schema.zed

caveat ip_allowlist(user_ip string, allowed_cidrs list<string>) {
  user_ip.isIpAddress() && user_ip.ipInCidrList(allowed_cidrs)
}

definition document {
  relation viewer: user with ip_allowlist
  permission read = viewer
}

// Write da tupla COM contexto fixo
await client.promises.writeRelationships({
  updates: [{
    operation: 'CREATE',
    relationship: {
      resource: { objectType: 'document', objectId: 'sensitive' },
      relation: 'viewer',
      subject: { object: { objectType: 'user', objectId: 'bob' } },
      optionalCaveat: {
        caveatName: 'ip_allowlist',
        context: { allowed_cidrs: ['10.0.0.0/8', '192.168.0.0/16'] },
      },
    },
  }],
});

// Check passando contexto runtime
await client.promises.checkPermission({
  resource: { objectType: 'document', objectId: 'sensitive' },
  permission: 'read',
  subject: { object: { objectType: 'user', objectId: 'bob' } },
  context: { user_ip: req.ip },  // contexto dinâmico do request
});

Arquitetura de deployment

🗺️ SpiceDB em produção (multi-region)

API service

GraphQL gateway

spicedb (stateless)

Dispatcher (consistent hashing)

Cache (Ristretto)

Postgres / CRDB

Watch API

Dispatcherroteia subqueries de uma expansão para o mesmo nó via consistent hashing — maximiza cache locality

Cache Ristrettocaches in-memory (Go); decisões + intermediate usersets — TTL invalidado por Watch

Logical replicationPostgres `wal_level=logical` + slot dedicado; cuidado com lag

Read replicasPostgres replicas para Lookup* APIs (caras) — main pra Check

Performance: como tirar sub-ms

🗺️ Fluxo do check no SpiceDB (path otimista)

Receive CheckgRPC handler, parse request

Cache lookupRistretto: hit → retorna em ~100µs

Dispatchmiss → consistent-hash para nó dono do (resource, perm)

Expand usersetrecursivo: avalia rewrite, busca tuplas, fan-out

Storage readPostgres: at_exact_snapshot via xmin (TID-based)

Cache storesubtree cacheada para próximas queries

💡

Tuning crítico: e . Sem isso, você não chega aos números do paper. Em single-node dev é fine, mas em produção dispatch cluster é obrigatório.

Modelagem real: multi-tenant SaaS

schema-saas.zed

definition user {}

definition organization {
  relation admin: user
  relation billing_admin: user
  relation member: user

  permission manage = admin
  permission view_billing = admin + billing_admin
  permission view = admin + billing_admin + member
}

definition project {
  relation org: organization
  relation owner: user
  relation contributor: user

  permission manage = owner + org->admin
  permission write = manage + contributor
  permission read  = write + org->member
}

definition issue {
  relation project: project
  relation assignee: user
  relation reporter: user

  permission manage = reporter + project->manage
  permission write  = manage + assignee + project->write
  permission read   = project->read
}

Note como herança org → project → issue é declarativa. Adicionar "guest" ao projeto não exige role nova nem mudança de schema — basta tupla project:web#contributor@user:guest. Esse é o ganho fundamental sobre RBAC.

Operando: zed CLI, dev container, testing

🗺️ Workflow de desenvolvimento SpiceDB

▼

validation.yaml

schema: |
  definition user {}
  definition doc {
    relation viewer: user
    relation editor: user
    permission read = viewer + editor
  }

relationships: |
  doc:report#editor@user:alice
  doc:report#viewer@user:bob

assertions:
  assertTrue:
    - doc:report#read@user:alice  # editor pode ler
    - doc:report#read@user:bob    # viewer pode ler
  assertFalse:
    - doc:report#read@user:charlie  # nem editor nem viewer

Quando NÃO usar SpiceDB

App pequeno com RBAC puro: 5 roles fixas, sem sharing → SQL bem modelado é mais simples e tem 1 dependência a menos.
Decisões puramente sobre código/infra: K8s admission, terraform — use OPA, é o nicho dele.
Sem orçamento de operação para storage stateful: SpiceDB precisa de Postgres com replication. Se você não tem time/orçamento, considere OpenFGA managed (Auth0 FGA) ou AVP.
Compliance que exige policy-as-code legível por auditor: Cedar e OPA escrevem regras em texto. SpiceDB é estrutural + dado — alguns auditores estranham.

Resumo executivo

SpiceDB (Authzed, Apache 2.0) é a implementação Zanzibar mais madura — fiel ao paper.
Schema language declarativa, type-safe, versionada em git. Substitui o protobuf do paper.
APIs Check/Expand/Lookup{Resources,Subjects}/Write — 4 verbos resolvem o caso de uso completo.
ZedTokens portam Zookies: persistir junto ao recurso, enviar em CheckPermission para consistência.
Caveats (2023) trazem ABAC condicional via CEL — preenchem o gap histórico do ReBAC puro.
Storage: Postgres ou CockroachDB. Dispatch cluster + cache Ristretto = sub-ms checks.
Use para: SaaS multi-tenant com sharing, Drive/Notion-like, IAM granular. Evite para: 5 roles fixas, infra-policy.

A implementação Zanzibar mais madura

LinguagemGo — single binary spicedb, fácil de containerizar

StoragePostgres, CockroachDB, Spanner, MySQL (em ordem de maturidade)

APIgRPC primário + HTTP/JSON gateway; SDKs em Go, Java, Node, Python, Ruby

Performancesub-ms checks em cache hot, p99 < 10ms em produção típica

CloudAuthzed Dedicated / Serverless — managed; SpiceDB self-host livre

Schema Language: declarando o domínio

A primeira coisa a desenhar é o schema. SpiceDB tem uma DSL própria, type-safe, com tooling (zed CLI, playground.authzed.com). Exemplo de schema Drive-like:

schema.zed

definition user {}

definition organization {
  relation admin: user
  relation member: user

  permission manage = admin
  permission view = admin + member
}

definition folder {
  relation parent: folder | organization
  relation owner: user
  relation editor: user
  relation viewer: user

  permission write = owner + editor + parent->write
  permission read  = viewer + write + parent->read
}

definition document {
  relation parent: folder
  relation owner: user
  relation editor: user
  relation viewer: user

  permission write = owner + editor + parent->write
  permission read  = viewer + write + parent->read
  permission share = owner + parent->write
}

definition X {}declara o tipo de objeto (user, folder, document)

relation r: Taceita tuplas vinculando este objeto a usuários do tipo T

+ / & / -union, intersection, exclusion na composição de permissions

parent->readtuple-to-userset: para cada tupla parent, avalia read no objeto pai

| (pipe)union de tipos aceitos: parent: folder | organization

💡

Essa DSL substitui o protobuf de namespace config do paper Zanzibar — mesma expressividade, leitura humana. aplica em prod; versionado em git.

Os 4 verbos da API

API	Quando usar	Latência alvo
WriteRelationships	Criar/deletar tuplas (compartilhar doc, adicionar membro)	~10-30ms (storage commit)
CheckPermission	Pode user X fazer ação Y no recurso Z? — path do request HTTP	<10ms p99 (cache hot)
LookupResources	"Quais docs Tom pode ler?" — UI de listagem do user	Stream; depende do fan-out
LookupSubjects	"Quem tem acesso ao doc X?" — UI de admin/share	Stream; depende do grafo
ExpandPermission	Debug: quem deriva essa perm e por quê	~50ms; uso esporádico
ReadRelationships	Listar tuplas brutas (compliance, audit)	Stream paginado

APIWriteRelationships

Quando usarCriar/deletar tuplas (compartilhar doc, adicionar membro)

Latência alvo~10-30ms (storage commit)

APICheckPermission

Quando usarPode user X fazer ação Y no recurso Z? — path do request HTTP

Latência alvo<10ms p99 (cache hot)

APILookupResources

Quando usar"Quais docs Tom pode ler?" — UI de listagem do user

Latência alvoStream; depende do fan-out

APILookupSubjects

Quando usar"Quem tem acesso ao doc X?" — UI de admin/share

Latência alvoStream; depende do grafo

APIExpandPermission

Quando usarDebug: quem deriva essa perm e por quê

Latência alvo~50ms; uso esporádico

APIReadRelationships

Quando usarListar tuplas brutas (compliance, audit)

Latência alvoStream paginado

Exemplo end-to-end: compartilhar e checar

app/share.ts

import { v1 } from '@authzed/authzed-node';

const client = v1.NewClient('YOUR_API_TOKEN', 'spicedb.example.com:50051');

// 1. Alice compartilha doc:report-q1 com Bob como editor
const writeResp = await client.promises.writeRelationships(
  v1.WriteRelationshipsRequest.create({
    updates: [
      v1.RelationshipUpdate.create({
        operation: v1.RelationshipUpdate_Operation.CREATE,
        relationship: v1.Relationship.create({
          resource: { objectType: 'document', objectId: 'report-q1' },
          relation: 'editor',
          subject: { object: { objectType: 'user', objectId: 'bob' } },
        }),
      }),
    ],
  }),
);

// IMPORTANTE: guardar o zedToken retornado
const zedToken = writeResp.writtenAt;  // ex: 'GhUKEzE2Nz...'
await db.documents.update({
  where: { id: 'report-q1' },
  data: { authzZedToken: zedToken.token },
});

// 2. Bob faz GET /docs/report-q1 — middleware checa
const check = await client.promises.checkPermission(
  v1.CheckPermissionRequest.create({
    resource: { objectType: 'document', objectId: 'report-q1' },
    permission: 'read',
    subject: { object: { objectType: 'user', objectId: 'bob' } },
    consistency: v1.Consistency.create({
      requirement: { oneofKind: 'atLeastAsFresh',
        atLeastAsFresh: { text: doc.authzZedToken },
      },
    }),
  }),
);

if (check.permissionship !== v1.CheckPermissionResponse_Permissionship.HAS_PERMISSION) {
  throw new ForbiddenError();
}

⚠️

O persistido junto ao recurso é o que garante consistência. Sem ele, você pode ler dados com permissões obsoletas — exatamente o new enemy problem.

Caveats: ABAC dentro de ReBAC

schema.zed

caveat ip_allowlist(user_ip string, allowed_cidrs list<string>) {
  user_ip.isIpAddress() && user_ip.ipInCidrList(allowed_cidrs)
}

definition document {
  relation viewer: user with ip_allowlist
  permission read = viewer
}

// Write da tupla COM contexto fixo
await client.promises.writeRelationships({
  updates: [{
    operation: 'CREATE',
    relationship: {
      resource: { objectType: 'document', objectId: 'sensitive' },
      relation: 'viewer',
      subject: { object: { objectType: 'user', objectId: 'bob' } },
      optionalCaveat: {
        caveatName: 'ip_allowlist',
        context: { allowed_cidrs: ['10.0.0.0/8', '192.168.0.0/16'] },
      },
    },
  }],
});

// Check passando contexto runtime
await client.promises.checkPermission({
  resource: { objectType: 'document', objectId: 'sensitive' },
  permission: 'read',
  subject: { object: { objectType: 'user', objectId: 'bob' } },
  context: { user_ip: req.ip },  // contexto dinâmico do request
});

Arquitetura de deployment

🗺️ SpiceDB em produção (multi-region)

API service

GraphQL gateway

spicedb (stateless)

Dispatcher (consistent hashing)

Cache (Ristretto)

Postgres / CRDB

Watch API

Dispatcherroteia subqueries de uma expansão para o mesmo nó via consistent hashing — maximiza cache locality

Cache Ristrettocaches in-memory (Go); decisões + intermediate usersets — TTL invalidado por Watch

Logical replicationPostgres `wal_level=logical` + slot dedicado; cuidado com lag

Read replicasPostgres replicas para Lookup* APIs (caras) — main pra Check

Performance: como tirar sub-ms

🗺️ Fluxo do check no SpiceDB (path otimista)

Receive CheckgRPC handler, parse request

Cache lookupRistretto: hit → retorna em ~100µs

Dispatchmiss → consistent-hash para nó dono do (resource, perm)

Expand usersetrecursivo: avalia rewrite, busca tuplas, fan-out

Storage readPostgres: at_exact_snapshot via xmin (TID-based)

Cache storesubtree cacheada para próximas queries

💡

Tuning crítico: e . Sem isso, você não chega aos números do paper. Em single-node dev é fine, mas em produção dispatch cluster é obrigatório.

Modelagem real: multi-tenant SaaS

schema-saas.zed

definition user {}

definition organization {
  relation admin: user
  relation billing_admin: user
  relation member: user

  permission manage = admin
  permission view_billing = admin + billing_admin
  permission view = admin + billing_admin + member
}

definition project {
  relation org: organization
  relation owner: user
  relation contributor: user

  permission manage = owner + org->admin
  permission write = manage + contributor
  permission read  = write + org->member
}

definition issue {
  relation project: project
  relation assignee: user
  relation reporter: user

  permission manage = reporter + project->manage
  permission write  = manage + assignee + project->write
  permission read   = project->read
}

Operando: zed CLI, dev container, testing

🗺️ Workflow de desenvolvimento SpiceDB

▼

validation.yaml

schema: |
  definition user {}
  definition doc {
    relation viewer: user
    relation editor: user
    permission read = viewer + editor
  }

relationships: |
  doc:report#editor@user:alice
  doc:report#viewer@user:bob

assertions:
  assertTrue:
    - doc:report#read@user:alice  # editor pode ler
    - doc:report#read@user:bob    # viewer pode ler
  assertFalse:
    - doc:report#read@user:charlie  # nem editor nem viewer

Quando NÃO usar SpiceDB

App pequeno com RBAC puro: 5 roles fixas, sem sharing → SQL bem modelado é mais simples e tem 1 dependência a menos.
Decisões puramente sobre código/infra: K8s admission, terraform — use OPA, é o nicho dele.
Sem orçamento de operação para storage stateful: SpiceDB precisa de Postgres com replication. Se você não tem time/orçamento, considere OpenFGA managed (Auth0 FGA) ou AVP.
Compliance que exige policy-as-code legível por auditor: Cedar e OPA escrevem regras em texto. SpiceDB é estrutural + dado — alguns auditores estranham.

Resumo executivo

SpiceDB (Authzed, Apache 2.0) é a implementação Zanzibar mais madura — fiel ao paper.
Schema language declarativa, type-safe, versionada em git. Substitui o protobuf do paper.
APIs Check/Expand/Lookup{Resources,Subjects}/Write — 4 verbos resolvem o caso de uso completo.
ZedTokens portam Zookies: persistir junto ao recurso, enviar em CheckPermission para consistência.
Caveats (2023) trazem ABAC condicional via CEL — preenchem o gap histórico do ReBAC puro.
Storage: Postgres ou CockroachDB. Dispatch cluster + cache Ristretto = sub-ms checks.
Use para: SaaS multi-tenant com sharing, Drive/Notion-like, IAM granular. Evite para: 5 roles fixas, infra-policy.

A implementação Zanzibar mais madura

Schema Language: declarando o domínio

Os 4 verbos da API

Exemplo end-to-end: compartilhar e checar

Caveats: ABAC dentro de ReBAC

Arquitetura de deployment

Performance: como tirar sub-ms

Modelagem real: multi-tenant SaaS

Operando: zed CLI, dev container, testing

Quando NÃO usar SpiceDB

Resumo executivo

Próximos passos sugeridos

Discussão

SpiceDB: Zanzibar open-source na prática

A implementação Zanzibar mais madura

Schema Language: declarando o domínio

Os 4 verbos da API

Exemplo end-to-end: compartilhar e checar

Caveats: ABAC dentro de ReBAC

Arquitetura de deployment

Performance: como tirar sub-ms

Modelagem real: multi-tenant SaaS

Operando: zed CLI, dev container, testing

Quando NÃO usar SpiceDB

Resumo executivo

Próximos passos sugeridos

Discussão