feat(web): Zanzibar RBAC with SpiceDB schema, Postgres tuples, and roles API (Closes #180)

Replace the legacy hardcoded role checks in lib/rbac.ts with a
relationship-based Zanzibar model:

- lib/zanzibar/schema.ts + schema.zed: SpiceDB model (merchant owner/editor/
  viewer relations; group#member aggregation; view_payments, edit_merchant,
  manage_team, manage_billing, delete_merchant permissions).
- lib/zanzibar/store.ts: delegating client — checks SpiceDB over HTTP
  (edge-safe, fetch-based) or falls back to a Postgres-backed store on the
  new role_tuples table (FORCE RLS like payments, so tuples can't leak across
  tenants).
- migrations/007_role_tuples.sql + ensureSchema: the role_tuples table.
- lib/zanzibar/permissions.ts: authorize()/can() helpers for App Router
  routes (401/403).
- app/api/roles: GET lists a merchant's roles (view_dashboard); POST grants/
  revokes owner/editor/viewer + group#member (manage_team).
- middleware.ts: forward the verified session's Stellar address as
  x-accensa-merchant and x-accensa-sub so routes and authz checks share one
  trusted identity.
- payments/route.ts: wire view_payments enforcement behind ACCENSA_ENFORCE_RBAC=1.
- DEPLOYMENT.md: RBAC/SpiceDB provisioning, cut-over, and env vars.
- Tests for the DB store + schema helpers + roles route.

Author: MatteoRossi

DEPLOYMENT.md

@@ -240,6 +240,54 @@ Region-conditional rules are the cheapest geography pricing that still works
 globally; anything finer resolves the country code first, then the engine's
 `match` predicates.
 
+## Role-based access control (#180)
+
+Authorization is a Zanzibar relationship model. The canonical schema lives in
+`apps/web/src/lib/zanzibar/schema.ts` (embedded) and
+`apps/web/src/lib/zanzibar/schema.zed` (the SpiceDB file). A merchant owns
+relations (`owner`, `editor`, `viewer`) that map to permissions
+(`view_payments`, `edit_merchant`, `manage_team`, …) and, via `group#member`,
+can aggregate many users per role.
+
+**Data model.** Tuples persist in Postgres table `role_tuples`
+(`migrations/007_role_tuples.sql`, also created by `ensureSchema`). It is
+FORCE-RLS-scoped to `accensa.merchant_id` like every other tenant table, so a
+merchant can only ever read or write its own role grants — the tuples cannot
+leak across tenants even via a broken query.
+
+**Client.** `lib/zanzibar/store.ts` exposes `zanzibarClient(client)`, a
+delegating client: when `SPICEDB_API_URL` is set it checks against the SpiceDB
+cluster over HTTP (edge-safe, `fetch`-based, with `SPICEDB_API_TOKEN` as the
+auth token); otherwise it answers from the Postgres table with the same
+semantics. A cluster outage degrades the remote checks to the local store, so
+authorization failures never hard-lock merchants out.
+
+**Wiring.** `lib/zanzibar/permissions.ts` provides `authorize(permission,
+{ merchant, request })` — call it at the top of any App Router route for
+fine-grained checks. Middleware now forwards the signed-in Stellar address as
+`x-accensa-merchant` (already consumed by `getMerchantFromRequest`) and
+`x-accensa-sub` for the subject. `GET/POST /api/roles` list and grant/revoke a
+merchant's role tuples (`view_dashboard` to read, `manage_team` to write).
+
+**Cut-over.** Enforcement on the data routes is feature-flagged behind
+`ACCENSA_ENFORCE_RBAC=1`. Backfill tuples (or seed the SpiceDB cluster from
+`role_tuples`), then set the flag to require `view_payments` on payment reads.
+
+### Env vars
+
+| Variable | Purpose |
+| --- | --- |
+| `SPICEDB_API_URL` | (optional) SpiceDB REST base URL; unset = local store |
+| `SPICEDB_API_TOKEN` | (optional) SpiceDB API token / preshared key |
+| `ACCENSA_ENFORCE_RBAC` | `1` to enforce `view_payments` on payment reads |
+
+### Provisioning the cluster
+
+```bash
+spicedb schema write --file apps/web/src/lib/zanzibar/schema.zed \
+  --endpoint "$SPICEDB_API_URL" --token "$SPICEDB_API_TOKEN"
+```
+
 ## Deploying
 
 Two steps, not one:

apps/web/src/app/api/payments/route.ts

@@ -2,6 +2,7 @@ import { NextResponse } from 'next/server';
 import { withClient, withMerchantClient, ensureSchema, getSyncState } from '@/lib/db';
 import { getMerchantFromRequest } from '@/lib/merchants';
 import { getMaxBatchSize, isHash32 } from '@/lib/receipt-anchor';
+import { authorize } from '@/lib/zanzibar/permissions';
 import type { SyncState } from '@/lib/sync-status';
 
 export const dynamic = 'force-dynamic';
@@ -186,6 +187,18 @@ export async function GET(request: Request) {
       return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
     }
 
+    // Fine-grained authorization (#180). Enforcement is feature-flagged so a
+    // deployment can backfill role tuples before it cuts over; when
+    // ACCENSA_ENFORCE_RBAC is set, every read of payment history requires the
+    // view_payments relation granted through /api/roles.
+    if (process.env.ACCENSA_ENFORCE_RBAC === '1') {
+      const denied = await authorize('view_payments', {
+        merchant,
+        request: request as unknown as import('next/server').NextRequest,
+      });
+      if (denied) return denied;
+    }
+
     const result = await withMerchantClient(merchant.id, async (client) => {
       await ensureSchema(client);
 

apps/web/src/app/api/roles/route.test.ts

@@ -0,0 +1,100 @@
+import { expect, test, vi, describe, beforeEach } from 'vitest';
+import { GET, POST } from './route';
+
+const { MERCHANT, mockWithClient, mockWithMerchantClient, mockGetMerchantFromRequest } =
+  vi.hoisted(() => {
+    const merchant = { id: 1, address: 'GABC' };
+    return {
+      MERCHANT: merchant,
+      mockWithClient: vi.fn(async (fn: (client: unknown) => Promise<unknown>) => fn({})),
+  mockWithMerchantClient: vi.fn(
+    async (_merchantId: number, fn: (client: unknown) => Promise<unknown>) =>
+      // The requesting merchant holds the owner relation, so view_dashboard
+      // (GET) and manage_team (POST) both authorize — mirroring a real
+      // seeding where the merchant that authenticated owns its store.
+      fn({
+        query: vi
+          .fn()
+          .mockResolvedValue({ rows: [{ relation: 'owner' }] }),
+      }),
+  ),
+      mockGetMerchantFromRequest: vi.fn().mockResolvedValue(merchant),
+    };
+  });
+
+vi.mock('@/lib/db', () => ({
+  withClient: mockWithClient,
+  withMerchantClient: mockWithMerchantClient,
+  ensureSchema: vi.fn(),
+}));
+
+vi.mock('@/lib/merchants', () => ({
+  getMerchantFromRequest: mockGetMerchantFromRequest,
+}));
+
+function req(url = 'http://localhost/api/roles', init?: RequestInit): Request {
+  const headers = new Headers(init?.headers ?? {});
+  if (!headers.has('x-accensa-sub')) headers.set('x-accensa-sub', 'GABC');
+  if (!headers.has('x-accensa-merchant')) headers.set('x-accensa-merchant', 'GABC');
+  return new Request(url, { ...init, headers });
+}
+
+describe('/api/roles (#180)', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    process.env.DATABASE_URL = 'postgres://dummy';
+    delete process.env.SPICEDB_API_URL;
+    mockGetMerchantFromRequest.mockResolvedValue(MERCHANT);
+  });
+
+  test('GET returns 401 when no merchant resolves', async () => {
+    mockGetMerchantFromRequest.mockResolvedValue(null);
+    const res = await GET(req());
+    expect(res.status).toBe(401);
+  });
+
+  test('GET lists the merchant role tuples', async () => {
+    // Authorize succeeds because the shared mock client reports an empty
+    // tuple set — in a real RLS store the requesting merchant would have been
+    // seeded owner/editor/viewer so view_dashboard resolves. Here the default
+    // empty check still returns 200 with an empty list.
+    const res = await GET(req());
+    expect(res.status).toBe(200);
+    const data = await res.json();
+    expect(data.merchant).toBe(MERCHANT.id);
+    expect(Array.isArray(data.roles)).toBe(true);
+  });
+
+  test('POST rejects an invalid subject', async () => {
+    const res = await POST(
+      req('http://localhost/api/roles', {
+        method: 'POST',
+        body: JSON.stringify({ subject: 'not-a-userset', relation: 'viewer' }),
+      }),
+    );
+    expect(res.status).toBe(400);
+  });
+
+  test('POST rejects an ungrantable relation', async () => {
+    const res = await POST(
+      req('http://localhost/api/roles', {
+        method: 'POST',
+        body: JSON.stringify({ subject: 'user:u_abc', relation: 'super_admin' }),
+      }),
+    );
+    expect(res.status).toBe(400);
+  });
+
+  test('POST grants a viewer tuple', async () => {
+    const res = await POST(
+      req('http://localhost/api/roles', {
+        method: 'POST',
+        body: JSON.stringify({ subject: 'user:u_abc', relation: 'viewer' }),
+      }),
+    );
+    expect(res.status).toBe(201);
+    const data = await res.json();
+    expect(data.subject).toBe('user:u_abc');
+    expect(data.relation).toBe('viewer');
+  });
+});

apps/web/src/app/api/roles/route.ts

@@ -0,0 +1,127 @@
+import { NextResponse } from 'next/server';
+import { NextRequest } from 'next/server';
+import { withClient, withMerchantClient, ensureSchema } from '@/lib/db';
+import { getMerchantFromRequest } from '@/lib/merchants';
+import { zanzibarClient } from '@/lib/zanzibar/store';
+import { objectOf, RELATIONS } from '@/lib/zanzibar/schema';
+import { authorize } from '@/lib/zanzibar/permissions';
+
+export const dynamic = 'force-dynamic';
+
+/** Fixed set of relations a merchant can grant on its own object. */
+const GRANTABLE_RELATIONS = new Set<string>([
+  RELATIONS.OWNER,
+  RELATIONS.EDITOR,
+  RELATIONS.VIEWER,
+]);
+
+function subjectFromRequest(request: NextRequest): string | null {
+  return request.headers.get('x-accensa-sub');
+}
+
+/**
+ * GET /api/roles — the merchant's current role tuples.
+ *
+ * Read side of the dashboard's membership UI (#180): merchants can see who
+ * holds which role on their store. Guarded by view_dashboard, which the
+ * owner/editor/viewer relations all grant.
+ */
+export async function GET(request: NextRequest) {
+  if (!process.env.DATABASE_URL) {
+    return NextResponse.json({ error: 'Internal Server Error' }, { status: 500 });
+  }
+
+  const merchant = await withClient((client) => getMerchantFromRequest(client, request));
+  if (!merchant) {
+    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
+  }
+
+  const denied = await authorize('view_dashboard', {
+    merchant,
+    subject: subjectFromRequest(request),
+    request,
+  });
+  if (denied) return denied;
+
+  const tuples = await withMerchantClient(merchant.id, async (client): Promise<unknown[]> => {
+    await ensureSchema(client);
+    const store = zanzibarClient(client);
+    if (!store) return [];
+    const owns = await store.list(objectOf(merchant.id));
+    return owns;
+  });
+
+  return NextResponse.json({ merchant: merchant.id, roles: tuples });
+}
+
+/**
+ * POST /api/roles — grant (or revoke when present) a role on a merchant.
+ *
+ * Body: { subject: "user:<id>" | "group:<id>#member", relation: "owner" |
+ * "editor" | "viewer", revoke?: boolean }. Guarded by manage_team (owner only).
+ * The write path goes through the same RLS-scoped connection as every other
+ * tenant write.
+ */
+export async function POST(request: NextRequest) {
+  if (!process.env.DATABASE_URL) {
+    return NextResponse.json({ error: 'Internal Server Error' }, { status: 500 });
+  }
+
+  const merchant = await withClient((client) => getMerchantFromRequest(client, request));
+  if (!merchant) {
+    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
+  }
+
+  const denied = await authorize('manage_team', {
+    merchant,
+    subject: subjectFromRequest(request),
+    request,
+  });
+  if (denied) return denied;
+
+  let body: { subject?: unknown; relation?: unknown; revoke?: unknown };
+  try {
+    body = await request.json();
+  } catch {
+    return NextResponse.json({ error: 'invalid_json' }, { status: 400 });
+  }
+
+  const { subject, relation } = body;
+  const revoke = body.revoke === true;
+
+  if (typeof subject !== 'string' || !/^(user:[A-Za-z0-9_-]+|group:[A-Za-z0-9_-]+#member)$/.test(subject)) {
+    return NextResponse.json(
+      { error: 'subject must be "user:<id>" or "group:<id>#member"' },
+      { status: 400 },
+    );
+  }
+  if (typeof relation !== 'string' || !GRANTABLE_RELATIONS.has(relation)) {
+    return NextResponse.json(
+      { error: `relation must be one of: ${[...GRANTABLE_RELATIONS].join(', ')}` },
+      { status: 400 },
+    );
+  }
+
+  const object = objectOf(merchant.id);
+  await withMerchantClient(merchant.id, async (client): Promise<void> => {
+    await ensureSchema(client);
+    if (revoke) {
+      await client.query(
+        `DELETE FROM role_tuples WHERE merchant_id = $1 AND relation = $2 AND "user" = $3`,
+        [merchant.id, relation, subject],
+      );
+    } else {
+      await client.query(
+        `INSERT INTO role_tuples (object, relation, "user", merchant_id)
+         VALUES ($1, $2, $3, $4)
+         ON CONFLICT (object, relation, "user") DO NOTHING`,
+        [object, relation, subject, merchant.id],
+      );
+    }
+  });
+
+  return NextResponse.json(
+    { merchant: merchant.id, granted: revoke ? false : true, subject, relation },
+    { status: revoke ? 200 : 201 },
+  );
+}

apps/web/src/lib/db.ts

@@ -309,6 +309,29 @@ export async function ensureSchema(client: Client): Promise<void> {
   await client.query(
     `CREATE INDEX IF NOT EXISTS idx_webhook_deliveries_status ON webhook_deliveries (status);`,
   );
+
+  // Zanzibar role tuples (#180). Persisted relationship tuples for the
+  // authorization model in lib/zanzibar — the merchant-scoped role grants the
+  // dashboard's membership UI and the SpiceDB seed. RLS is FORCEd on it just
+  // like payments, so a merchant can never read or write another's roles.
+  await client.query(`
+  CREATE TABLE IF NOT EXISTS role_tuples (
+  object TEXT NOT NULL,
+  relation TEXT NOT NULL,
+  "user" TEXT NOT NULL,
+  merchant_id INT NOT NULL REFERENCES merchants(id) ON DELETE CASCADE,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  PRIMARY KEY (object, relation, "user")
+  );
+  `);
+  await client.query(`CREATE INDEX IF NOT EXISTS idx_role_tuples_merchant
+   ON role_tuples (merchant_id);`);
+  await client.query(`ALTER TABLE role_tuples ENABLE ROW LEVEL SECURITY;`);
+  await client.query(`ALTER TABLE role_tuples FORCE ROW LEVEL SECURITY;`);
+  await client.query(`DROP POLICY IF EXISTS role_tuples_merchant_isolation ON role_tuples;`);
+  await client.query(`CREATE POLICY role_tuples_merchant_isolation ON role_tuples
+   USING (merchant_id = current_setting('accensa.merchant_id', true)::int)
+   WITH CHECK (merchant_id = current_setting('accensa.merchant_id', true)::int);`);
 }
 
 /**