@moon-wave/rebac 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 linhhang1412
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,94 @@
+type ObjectType = 'user' | 'organization' | 'agent' | 'session';
+type RelationType = 'owner' | 'editor' | 'viewer' | 'member' | 'admin';
+interface ReBACTuple {
+    objectType: ObjectType;
+    objectId: string;
+    relation: RelationType;
+    subjectType: ObjectType;
+    subjectId: string;
+    /** For group references, e.g. "member" means subject is "organization:id#member" */
+    subjectRelation?: RelationType;
+}
+interface ReBACTupleRecord extends ReBACTuple {
+    id: number;
+    createdAt: string;
+}
+interface ReBACUser {
+    id: string;
+    name: string;
+    email: string;
+    createdAt: string;
+    /** Present only when freshly generated — never returned by listUsers() */
+    apiKey?: string;
+}
+interface CheckResult {
+    allowed: boolean;
+}
+/** Minimal D1 binding interface (compatible with Cloudflare Workers D1) */
+interface D1DatabaseBinding {
+    prepare(query: string): {
+        bind(...values: unknown[]): {
+            all<T = Record<string, unknown>>(): Promise<{
+                results: T[];
+            }>;
+            first<T = Record<string, unknown>>(): Promise<T | null>;
+            run(): Promise<void>;
+        };
+    };
+    exec(query: string): Promise<void>;
+}
+
+declare const REBAC_MIGRATION: string;
+/** Run after REBAC_MIGRATION to add api_key to existing installations. */
+declare const REBAC_MIGRATION_V2 = "ALTER TABLE rebac_users ADD COLUMN api_key TEXT UNIQUE";
+
+declare class D1ReBAC {
+    private db;
+    constructor(db: D1DatabaseBinding);
+    migrate(): Promise<void>;
+    writeTuple(tuple: ReBACTuple): Promise<void>;
+    deleteTuple(tuple: ReBACTuple): Promise<void>;
+    listTuples(filter?: {
+        objectType?: ObjectType;
+        objectId?: string;
+    }): Promise<ReBACTupleRecord[]>;
+    /**
+     * Check if subject has `relation` on object.
+     * Supports 1-level group expansion:
+     *   If a tuple says (object, relation) → (org, orgId, #member),
+     *   we check if (org, member) → (subject) also exists.
+     */
+    check(subjectType: ObjectType, subjectId: string, relation: RelationType, objectType: ObjectType, objectId: string): Promise<boolean>;
+    /**
+     * Convenience: returns true if user has owner OR editor relation on agent.
+     * Use before allowing an agent run.
+     */
+    canRunAgent(userId: string, agentName: string): Promise<boolean>;
+    /**
+     * Convenience: returns true if user has any relation (owner/editor/viewer) on agent.
+     */
+    canViewAgent(userId: string, agentName: string): Promise<boolean>;
+    listSubjectsForObject(objectType: ObjectType, objectId: string, relation: RelationType): Promise<Array<{
+        subjectType: string;
+        subjectId: string;
+        subjectRelation?: string;
+    }>>;
+    listObjectsForSubject(subjectType: ObjectType, subjectId: string, relation: RelationType, targetObjectType: ObjectType): Promise<string[]>;
+    createUser(id: string, name: string, email: string): Promise<void>;
+    listUsers(): Promise<ReBACUser[]>;
+    getUser(id: string): Promise<ReBACUser | null>;
+    /**
+     * Look up a user by their API key.
+     * Returns null if the key is invalid or not found.
+     */
+    getUserByApiKey(apiKey: string): Promise<ReBACUser | null>;
+    /**
+     * Generate a new random API key for a user.
+     * Returns the new key (only shown once — not retrievable later).
+     */
+    generateApiKey(userId: string): Promise<string>;
+    /** Revoke the API key for a user. */
+    revokeApiKey(userId: string): Promise<void>;
+}
+
+export { type CheckResult, type D1DatabaseBinding, D1ReBAC, type ObjectType, REBAC_MIGRATION, REBAC_MIGRATION_V2, type ReBACTuple, type ReBACTupleRecord, type ReBACUser, type RelationType };

package/dist/index.js

@@ -0,0 +1,205 @@
+// src/schema.ts
+var REBAC_MIGRATION = `
+CREATE TABLE IF NOT EXISTS rebac_users (
+  id         TEXT PRIMARY KEY,
+  name       TEXT NOT NULL,
+  email      TEXT UNIQUE NOT NULL,
+  api_key    TEXT UNIQUE,
+  created_at DATETIME DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE TABLE IF NOT EXISTS rebac_tuples (
+  id               INTEGER PRIMARY KEY AUTOINCREMENT,
+  object_type      TEXT NOT NULL,
+  object_id        TEXT NOT NULL,
+  relation         TEXT NOT NULL,
+  subject_type     TEXT NOT NULL,
+  subject_id       TEXT NOT NULL,
+  subject_relation TEXT,
+  created_at       DATETIME DEFAULT CURRENT_TIMESTAMP,
+  UNIQUE(object_type, object_id, relation, subject_type, subject_id, COALESCE(subject_relation, ''))
+);
+
+CREATE INDEX IF NOT EXISTS idx_rebac_object  ON rebac_tuples(object_type, object_id, relation);
+CREATE INDEX IF NOT EXISTS idx_rebac_subject ON rebac_tuples(subject_type, subject_id);
+CREATE INDEX IF NOT EXISTS idx_rebac_apikey  ON rebac_users(api_key);
+`.trim();
+var REBAC_MIGRATION_V2 = `ALTER TABLE rebac_users ADD COLUMN api_key TEXT UNIQUE`;
+
+// src/engine.ts
+var D1ReBAC = class {
+  constructor(db) {
+    this.db = db;
+  }
+  db;
+  async migrate() {
+    const statements = REBAC_MIGRATION.split(";\n").map((s) => s.trim()).filter(Boolean);
+    for (const sql of statements) {
+      await this.db.prepare(sql + ";").bind().run();
+    }
+    try {
+      await this.db.prepare(REBAC_MIGRATION_V2).bind().run();
+    } catch {
+    }
+  }
+  async writeTuple(tuple) {
+    await this.db.prepare(
+      `INSERT OR IGNORE INTO rebac_tuples
+           (object_type, object_id, relation, subject_type, subject_id, subject_relation)
+         VALUES (?, ?, ?, ?, ?, ?)`
+    ).bind(tuple.objectType, tuple.objectId, tuple.relation, tuple.subjectType, tuple.subjectId, tuple.subjectRelation ?? null).run();
+  }
+  async deleteTuple(tuple) {
+    await this.db.prepare(
+      `DELETE FROM rebac_tuples
+         WHERE object_type = ? AND object_id = ? AND relation = ?
+           AND subject_type = ? AND subject_id = ?
+           AND COALESCE(subject_relation, '') = COALESCE(?, '')`
+    ).bind(tuple.objectType, tuple.objectId, tuple.relation, tuple.subjectType, tuple.subjectId, tuple.subjectRelation ?? null).run();
+  }
+  async listTuples(filter) {
+    let sql = "SELECT * FROM rebac_tuples";
+    const bindings = [];
+    if (filter?.objectType && filter?.objectId) {
+      sql += " WHERE object_type = ? AND object_id = ?";
+      bindings.push(filter.objectType, filter.objectId);
+    } else if (filter?.objectType) {
+      sql += " WHERE object_type = ?";
+      bindings.push(filter.objectType);
+    }
+    sql += " ORDER BY created_at DESC";
+    const { results } = await this.db.prepare(sql).bind(...bindings).all();
+    return results.map(rowToTuple);
+  }
+  /**
+   * Check if subject has `relation` on object.
+   * Supports 1-level group expansion:
+   *   If a tuple says (object, relation) → (org, orgId, #member),
+   *   we check if (org, member) → (subject) also exists.
+   */
+  async check(subjectType, subjectId, relation, objectType, objectId) {
+    const direct = await this.db.prepare(
+      `SELECT 1 FROM rebac_tuples
+         WHERE object_type = ? AND object_id = ? AND relation = ?
+           AND subject_type = ? AND subject_id = ? AND subject_relation IS NULL
+         LIMIT 1`
+    ).bind(objectType, objectId, relation, subjectType, subjectId).first();
+    if (direct) return true;
+    const groupTuples = await this.db.prepare(
+      `SELECT subject_type, subject_id, subject_relation
+         FROM rebac_tuples
+         WHERE object_type = ? AND object_id = ? AND relation = ?
+           AND subject_relation IS NOT NULL`
+    ).bind(objectType, objectId, relation).all();
+    for (const group of groupTuples.results) {
+      const memberCheck = await this.db.prepare(
+        `SELECT 1 FROM rebac_tuples
+           WHERE object_type = ? AND object_id = ? AND relation = ?
+             AND subject_type = ? AND subject_id = ? AND subject_relation IS NULL
+           LIMIT 1`
+      ).bind(group.subject_type, group.subject_id, group.subject_relation, subjectType, subjectId).first();
+      if (memberCheck) return true;
+    }
+    return false;
+  }
+  /**
+   * Convenience: returns true if user has owner OR editor relation on agent.
+   * Use before allowing an agent run.
+   */
+  async canRunAgent(userId, agentName) {
+    const [isOwner, isEditor] = await Promise.all([
+      this.check("user", userId, "owner", "agent", agentName),
+      this.check("user", userId, "editor", "agent", agentName)
+    ]);
+    return isOwner || isEditor;
+  }
+  /**
+   * Convenience: returns true if user has any relation (owner/editor/viewer) on agent.
+   */
+  async canViewAgent(userId, agentName) {
+    const [isOwner, isEditor, isViewer] = await Promise.all([
+      this.check("user", userId, "owner", "agent", agentName),
+      this.check("user", userId, "editor", "agent", agentName),
+      this.check("user", userId, "viewer", "agent", agentName)
+    ]);
+    return isOwner || isEditor || isViewer;
+  }
+  async listSubjectsForObject(objectType, objectId, relation) {
+    const { results } = await this.db.prepare(
+      `SELECT subject_type, subject_id, subject_relation
+         FROM rebac_tuples
+         WHERE object_type = ? AND object_id = ? AND relation = ?
+         ORDER BY created_at DESC`
+    ).bind(objectType, objectId, relation).all();
+    return results.map((r) => ({
+      subjectType: r.subject_type,
+      subjectId: r.subject_id,
+      ...r.subject_relation ? { subjectRelation: r.subject_relation } : {}
+    }));
+  }
+  async listObjectsForSubject(subjectType, subjectId, relation, targetObjectType) {
+    const { results } = await this.db.prepare(
+      `SELECT object_id FROM rebac_tuples
+         WHERE subject_type = ? AND subject_id = ? AND relation = ? AND object_type = ?
+         ORDER BY created_at DESC`
+    ).bind(subjectType, subjectId, relation, targetObjectType).all();
+    return results.map((r) => r.object_id);
+  }
+  async createUser(id, name, email) {
+    await this.db.prepare(`INSERT INTO rebac_users (id, name, email) VALUES (?, ?, ?)`).bind(id, name, email).run();
+  }
+  async listUsers() {
+    const { results } = await this.db.prepare("SELECT id, name, email, created_at FROM rebac_users ORDER BY created_at DESC").bind().all();
+    return results.map(rowToUser);
+  }
+  async getUser(id) {
+    const row = await this.db.prepare("SELECT id, name, email, created_at FROM rebac_users WHERE id = ?").bind(id).first();
+    return row ? rowToUser(row) : null;
+  }
+  /**
+   * Look up a user by their API key.
+   * Returns null if the key is invalid or not found.
+   */
+  async getUserByApiKey(apiKey) {
+    const row = await this.db.prepare("SELECT id, name, email, created_at FROM rebac_users WHERE api_key = ? LIMIT 1").bind(apiKey).first();
+    return row ? rowToUser(row) : null;
+  }
+  /**
+   * Generate a new random API key for a user.
+   * Returns the new key (only shown once — not retrievable later).
+   */
+  async generateApiKey(userId) {
+    const key = generateRandomKey();
+    await this.db.prepare("UPDATE rebac_users SET api_key = ? WHERE id = ?").bind(key, userId).run();
+    return key;
+  }
+  /** Revoke the API key for a user. */
+  async revokeApiKey(userId) {
+    await this.db.prepare("UPDATE rebac_users SET api_key = NULL WHERE id = ?").bind(userId).run();
+  }
+};
+function rowToTuple(row) {
+  return {
+    id: row.id,
+    objectType: row.object_type,
+    objectId: row.object_id,
+    relation: row.relation,
+    subjectType: row.subject_type,
+    subjectId: row.subject_id,
+    ...row.subject_relation ? { subjectRelation: row.subject_relation } : {},
+    createdAt: row.created_at
+  };
+}
+function rowToUser(row) {
+  return { id: row.id, name: row.name, email: row.email, createdAt: row.created_at };
+}
+function generateRandomKey() {
+  const bytes = new Uint8Array(32);
+  crypto.getRandomValues(bytes);
+  return "mwk_" + Array.from(bytes).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+export {
+  D1ReBAC,
+  REBAC_MIGRATION,
+  REBAC_MIGRATION_V2
+};

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@moon-wave/rebac",
+  "version": "0.1.0",
+  "description": "Relationship-Based Access Control (ReBAC) engine for moon-wave — Zanzibar-style tuple model backed by Cloudflare D1",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0"
+  },
+  "author": "linhhang1412",
+  "license": "MIT",
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "dev": "tsup src/index.ts --format esm --dts --watch"
+  }
+}

package/src/__tests__/engine.test.ts

@@ -0,0 +1,128 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { D1ReBAC } from '../engine';
+import type { D1DatabaseBinding } from '../types';
+
+// In-memory mock for D1
+function createMockD1(): D1DatabaseBinding {
+  const tables: Record<string, Record<string, unknown>[]> = {
+    rebac_users: [],
+    rebac_tuples: [],
+  };
+  let autoId = 1;
+
+  function matchRow(row: Record<string, unknown>, where: Record<string, unknown>): boolean {
+    return Object.entries(where).every(([k, v]) => {
+      if (v === null) return row[k] === null || row[k] === undefined;
+      return row[k] === v;
+    });
+  }
+
+  return {
+    prepare(sql: string) {
+      return {
+        bind(...values: unknown[]) {
+          return {
+            async all<T>() {
+              if (sql.includes('FROM rebac_tuples') && !sql.includes('INSERT') && !sql.includes('DELETE')) {
+                const whereMatch = sql.match(/WHERE (.+?)(?:\s+ORDER|\s+LIMIT|$)/s);
+                if (!whereMatch) return { results: tables.rebac_tuples as T[] };
+
+                const conditions = whereMatch[1];
+                let results = tables.rebac_tuples.filter(row => {
+                  const parts = conditions.split(' AND ').map(s => s.trim());
+                  return parts.every((part, idx) => {
+                    if (part.includes('subject_relation IS NOT NULL')) return row.subject_relation != null;
+                    if (part.includes('subject_relation IS NULL')) return row.subject_relation == null;
+                    if (part.includes('= ?')) return row[part.split(' = ?')[0].trim().replace(/^.+\./, '')] === values[idx];
+                    return true;
+                  });
+                });
+                return { results: results as T[] };
+              }
+              if (sql.includes('FROM rebac_users')) {
+                return { results: tables.rebac_users as T[] };
+              }
+              return { results: [] as T[] };
+            },
+            async first<T>() {
+              if (sql.includes('SELECT 1 FROM rebac_tuples')) {
+                const [ot, oi, rel, st, si] = values as string[];
+                const found = tables.rebac_tuples.find(r =>
+                  r.object_type === ot && r.object_id === oi && r.relation === rel &&
+                  r.subject_type === st && r.subject_id === si && r.subject_relation == null
+                );
+                return (found ? { 1: 1 } : null) as T;
+              }
+              if (sql.includes('FROM rebac_users WHERE id')) {
+                const found = tables.rebac_users.find(r => r.id === values[0]);
+                return (found ?? null) as T;
+              }
+              return null as T;
+            },
+            async run() {
+              if (sql.startsWith('INSERT OR IGNORE INTO rebac_tuples')) {
+                const [ot, oi, rel, st, si, sr] = values;
+                const existing = tables.rebac_tuples.find(r =>
+                  r.object_type === ot && r.object_id === oi && r.relation === rel &&
+                  r.subject_type === st && r.subject_id === si &&
+                  (r.subject_relation ?? null) === (sr ?? null)
+                );
+                if (!existing) {
+                  tables.rebac_tuples.push({ id: autoId++, object_type: ot, object_id: oi, relation: rel, subject_type: st, subject_id: si, subject_relation: sr ?? null, created_at: new Date().toISOString() });
+                }
+              } else if (sql.startsWith('DELETE FROM rebac_tuples')) {
+                const [ot, oi, rel, st, si] = values;
+                tables.rebac_tuples = tables.rebac_tuples.filter(r =>
+                  !(r.object_type === ot && r.object_id === oi && r.relation === rel && r.subject_type === st && r.subject_id === si)
+                );
+              } else if (sql.startsWith('INSERT INTO rebac_users')) {
+                const [id, name, email] = values;
+                tables.rebac_users.push({ id, name, email, created_at: new Date().toISOString() });
+              } else if (sql.trim().endsWith(';') || sql.includes('CREATE TABLE') || sql.includes('CREATE INDEX')) {
+                // DDL — no-op in mock
+              }
+            },
+          };
+        },
+      };
+    },
+    async exec() {},
+  };
+}
+
+describe('D1ReBAC', () => {
+  let rebac: D1ReBAC;
+
+  beforeEach(() => {
+    rebac = new D1ReBAC(createMockD1());
+  });
+
+  it('returns false when no tuples exist', async () => {
+    const allowed = await rebac.check('user', 'alice', 'owner', 'agent', 'summarizer');
+    expect(allowed).toBe(false);
+  });
+
+  it('grants direct ownership', async () => {
+    await rebac.writeTuple({ objectType: 'agent', objectId: 'summarizer', relation: 'owner', subjectType: 'user', subjectId: 'alice' });
+    expect(await rebac.check('user', 'alice', 'owner', 'agent', 'summarizer')).toBe(true);
+  });
+
+  it('denies mismatched relation', async () => {
+    await rebac.writeTuple({ objectType: 'agent', objectId: 'summarizer', relation: 'viewer', subjectType: 'user', subjectId: 'alice' });
+    expect(await rebac.check('user', 'alice', 'owner', 'agent', 'summarizer')).toBe(false);
+  });
+
+  it('denies after tuple deletion', async () => {
+    const tuple = { objectType: 'agent' as const, objectId: 'summarizer', relation: 'owner' as const, subjectType: 'user' as const, subjectId: 'alice' };
+    await rebac.writeTuple(tuple);
+    await rebac.deleteTuple(tuple);
+    expect(await rebac.check('user', 'alice', 'owner', 'agent', 'summarizer')).toBe(false);
+  });
+
+  it('creates and lists users', async () => {
+    await rebac.createUser('u1', 'Alice', 'alice@example.com');
+    const users = await rebac.listUsers();
+    expect(users).toHaveLength(1);
+    expect(users[0].name).toBe('Alice');
+  });
+});

package/src/engine.ts

@@ -0,0 +1,278 @@
+import type { D1DatabaseBinding, ObjectType, ReBACTuple, ReBACTupleRecord, ReBACUser, RelationType } from './types';
+import { REBAC_MIGRATION, REBAC_MIGRATION_V2 } from './schema';
+
+interface TupleRow {
+  id: number;
+  object_type: string;
+  object_id: string;
+  relation: string;
+  subject_type: string;
+  subject_id: string;
+  subject_relation: string | null;
+  created_at: string;
+}
+
+interface UserRow {
+  id: string;
+  name: string;
+  email: string;
+  api_key: string | null;
+  created_at: string;
+}
+
+export class D1ReBAC {
+  constructor(private db: D1DatabaseBinding) {}
+
+  async migrate(): Promise<void> {
+    const statements = REBAC_MIGRATION.split(';\n').map(s => s.trim()).filter(Boolean);
+    for (const sql of statements) {
+      await this.db.prepare(sql + ';').bind().run();
+    }
+    // Add api_key column to existing installations — ignore error if already exists
+    try {
+      await this.db.prepare(REBAC_MIGRATION_V2).bind().run();
+    } catch {
+      // Column already exists — safe to ignore
+    }
+  }
+
+  async writeTuple(tuple: ReBACTuple): Promise<void> {
+    await this.db
+      .prepare(
+        `INSERT OR IGNORE INTO rebac_tuples
+           (object_type, object_id, relation, subject_type, subject_id, subject_relation)
+         VALUES (?, ?, ?, ?, ?, ?)`,
+      )
+      .bind(tuple.objectType, tuple.objectId, tuple.relation, tuple.subjectType, tuple.subjectId, tuple.subjectRelation ?? null)
+      .run();
+  }
+
+  async deleteTuple(tuple: ReBACTuple): Promise<void> {
+    await this.db
+      .prepare(
+        `DELETE FROM rebac_tuples
+         WHERE object_type = ? AND object_id = ? AND relation = ?
+           AND subject_type = ? AND subject_id = ?
+           AND COALESCE(subject_relation, '') = COALESCE(?, '')`,
+      )
+      .bind(tuple.objectType, tuple.objectId, tuple.relation, tuple.subjectType, tuple.subjectId, tuple.subjectRelation ?? null)
+      .run();
+  }
+
+  async listTuples(filter?: { objectType?: ObjectType; objectId?: string }): Promise<ReBACTupleRecord[]> {
+    let sql = 'SELECT * FROM rebac_tuples';
+    const bindings: unknown[] = [];
+
+    if (filter?.objectType && filter?.objectId) {
+      sql += ' WHERE object_type = ? AND object_id = ?';
+      bindings.push(filter.objectType, filter.objectId);
+    } else if (filter?.objectType) {
+      sql += ' WHERE object_type = ?';
+      bindings.push(filter.objectType);
+    }
+
+    sql += ' ORDER BY created_at DESC';
+
+    const { results } = await this.db.prepare(sql).bind(...bindings).all<TupleRow>();
+    return results.map(rowToTuple);
+  }
+
+  /**
+   * Check if subject has `relation` on object.
+   * Supports 1-level group expansion:
+   *   If a tuple says (object, relation) → (org, orgId, #member),
+   *   we check if (org, member) → (subject) also exists.
+   */
+  async check(
+    subjectType: ObjectType,
+    subjectId: string,
+    relation: RelationType,
+    objectType: ObjectType,
+    objectId: string,
+  ): Promise<boolean> {
+    // Direct match
+    const direct = await this.db
+      .prepare(
+        `SELECT 1 FROM rebac_tuples
+         WHERE object_type = ? AND object_id = ? AND relation = ?
+           AND subject_type = ? AND subject_id = ? AND subject_relation IS NULL
+         LIMIT 1`,
+      )
+      .bind(objectType, objectId, relation, subjectType, subjectId)
+      .first<{ 1: number }>();
+
+    if (direct) return true;
+
+    // Group expansion: find tuples where subject is a group reference
+    // e.g., (agent:X, editor) → (organization:acme, #member)
+    // then check if (organization:acme, member) → (user:alice)
+    const groupTuples = await this.db
+      .prepare(
+        `SELECT subject_type, subject_id, subject_relation
+         FROM rebac_tuples
+         WHERE object_type = ? AND object_id = ? AND relation = ?
+           AND subject_relation IS NOT NULL`,
+      )
+      .bind(objectType, objectId, relation)
+      .all<{ subject_type: string; subject_id: string; subject_relation: string }>();
+
+    for (const group of groupTuples.results) {
+      const memberCheck = await this.db
+        .prepare(
+          `SELECT 1 FROM rebac_tuples
+           WHERE object_type = ? AND object_id = ? AND relation = ?
+             AND subject_type = ? AND subject_id = ? AND subject_relation IS NULL
+           LIMIT 1`,
+        )
+        .bind(group.subject_type, group.subject_id, group.subject_relation, subjectType, subjectId)
+        .first<{ 1: number }>();
+
+      if (memberCheck) return true;
+    }
+
+    return false;
+  }
+
+  /**
+   * Convenience: returns true if user has owner OR editor relation on agent.
+   * Use before allowing an agent run.
+   */
+  async canRunAgent(userId: string, agentName: string): Promise<boolean> {
+    const [isOwner, isEditor] = await Promise.all([
+      this.check('user', userId, 'owner', 'agent', agentName),
+      this.check('user', userId, 'editor', 'agent', agentName),
+    ]);
+    return isOwner || isEditor;
+  }
+
+  /**
+   * Convenience: returns true if user has any relation (owner/editor/viewer) on agent.
+   */
+  async canViewAgent(userId: string, agentName: string): Promise<boolean> {
+    const [isOwner, isEditor, isViewer] = await Promise.all([
+      this.check('user', userId, 'owner', 'agent', agentName),
+      this.check('user', userId, 'editor', 'agent', agentName),
+      this.check('user', userId, 'viewer', 'agent', agentName),
+    ]);
+    return isOwner || isEditor || isViewer;
+  }
+
+  async listSubjectsForObject(
+    objectType: ObjectType,
+    objectId: string,
+    relation: RelationType,
+  ): Promise<Array<{ subjectType: string; subjectId: string; subjectRelation?: string }>> {
+    const { results } = await this.db
+      .prepare(
+        `SELECT subject_type, subject_id, subject_relation
+         FROM rebac_tuples
+         WHERE object_type = ? AND object_id = ? AND relation = ?
+         ORDER BY created_at DESC`,
+      )
+      .bind(objectType, objectId, relation)
+      .all<{ subject_type: string; subject_id: string; subject_relation: string | null }>();
+
+    return results.map(r => ({
+      subjectType: r.subject_type,
+      subjectId: r.subject_id,
+      ...(r.subject_relation ? { subjectRelation: r.subject_relation } : {}),
+    }));
+  }
+
+  async listObjectsForSubject(
+    subjectType: ObjectType,
+    subjectId: string,
+    relation: RelationType,
+    targetObjectType: ObjectType,
+  ): Promise<string[]> {
+    const { results } = await this.db
+      .prepare(
+        `SELECT object_id FROM rebac_tuples
+         WHERE subject_type = ? AND subject_id = ? AND relation = ? AND object_type = ?
+         ORDER BY created_at DESC`,
+      )
+      .bind(subjectType, subjectId, relation, targetObjectType)
+      .all<{ object_id: string }>();
+
+    return results.map(r => r.object_id);
+  }
+
+  async createUser(id: string, name: string, email: string): Promise<void> {
+    await this.db
+      .prepare(`INSERT INTO rebac_users (id, name, email) VALUES (?, ?, ?)`)
+      .bind(id, name, email)
+      .run();
+  }
+
+  async listUsers(): Promise<ReBACUser[]> {
+    const { results } = await this.db
+      .prepare('SELECT id, name, email, created_at FROM rebac_users ORDER BY created_at DESC')
+      .bind()
+      .all<UserRow>();
+    return results.map(rowToUser);
+  }
+
+  async getUser(id: string): Promise<ReBACUser | null> {
+    const row = await this.db
+      .prepare('SELECT id, name, email, created_at FROM rebac_users WHERE id = ?')
+      .bind(id)
+      .first<UserRow>();
+    return row ? rowToUser(row) : null;
+  }
+
+  /**
+   * Look up a user by their API key.
+   * Returns null if the key is invalid or not found.
+   */
+  async getUserByApiKey(apiKey: string): Promise<ReBACUser | null> {
+    const row = await this.db
+      .prepare('SELECT id, name, email, created_at FROM rebac_users WHERE api_key = ? LIMIT 1')
+      .bind(apiKey)
+      .first<UserRow>();
+    return row ? rowToUser(row) : null;
+  }
+
+  /**
+   * Generate a new random API key for a user.
+   * Returns the new key (only shown once — not retrievable later).
+   */
+  async generateApiKey(userId: string): Promise<string> {
+    const key = generateRandomKey();
+    await this.db
+      .prepare('UPDATE rebac_users SET api_key = ? WHERE id = ?')
+      .bind(key, userId)
+      .run();
+    return key;
+  }
+
+  /** Revoke the API key for a user. */
+  async revokeApiKey(userId: string): Promise<void> {
+    await this.db
+      .prepare('UPDATE rebac_users SET api_key = NULL WHERE id = ?')
+      .bind(userId)
+      .run();
+  }
+}
+
+function rowToTuple(row: TupleRow): ReBACTupleRecord {
+  return {
+    id: row.id,
+    objectType: row.object_type as ObjectType,
+    objectId: row.object_id,
+    relation: row.relation as RelationType,
+    subjectType: row.subject_type as ObjectType,
+    subjectId: row.subject_id,
+    ...(row.subject_relation ? { subjectRelation: row.subject_relation as RelationType } : {}),
+    createdAt: row.created_at,
+  };
+}
+
+function rowToUser(row: UserRow): ReBACUser {
+  return { id: row.id, name: row.name, email: row.email, createdAt: row.created_at };
+}
+
+function generateRandomKey(): string {
+  const bytes = new Uint8Array(32);
+  crypto.getRandomValues(bytes);
+  return 'mwk_' + Array.from(bytes).map(b => b.toString(16).padStart(2, '0')).join('');
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export type { ObjectType, RelationType, ReBACTuple, ReBACTupleRecord, ReBACUser, CheckResult, D1DatabaseBinding } from './types';
+export { REBAC_MIGRATION, REBAC_MIGRATION_V2 } from './schema';
+export { D1ReBAC } from './engine';

package/src/schema.ts

@@ -0,0 +1,28 @@
+export const REBAC_MIGRATION = `
+CREATE TABLE IF NOT EXISTS rebac_users (
+  id         TEXT PRIMARY KEY,
+  name       TEXT NOT NULL,
+  email      TEXT UNIQUE NOT NULL,
+  api_key    TEXT UNIQUE,
+  created_at DATETIME DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE TABLE IF NOT EXISTS rebac_tuples (
+  id               INTEGER PRIMARY KEY AUTOINCREMENT,
+  object_type      TEXT NOT NULL,
+  object_id        TEXT NOT NULL,
+  relation         TEXT NOT NULL,
+  subject_type     TEXT NOT NULL,
+  subject_id       TEXT NOT NULL,
+  subject_relation TEXT,
+  created_at       DATETIME DEFAULT CURRENT_TIMESTAMP,
+  UNIQUE(object_type, object_id, relation, subject_type, subject_id, COALESCE(subject_relation, ''))
+);
+
+CREATE INDEX IF NOT EXISTS idx_rebac_object  ON rebac_tuples(object_type, object_id, relation);
+CREATE INDEX IF NOT EXISTS idx_rebac_subject ON rebac_tuples(subject_type, subject_id);
+CREATE INDEX IF NOT EXISTS idx_rebac_apikey  ON rebac_users(api_key);
+`.trim();
+
+/** Run after REBAC_MIGRATION to add api_key to existing installations. */
+export const REBAC_MIGRATION_V2 = `ALTER TABLE rebac_users ADD COLUMN api_key TEXT UNIQUE`;

package/src/types.ts

@@ -0,0 +1,43 @@
+export type ObjectType = 'user' | 'organization' | 'agent' | 'session';
+
+export type RelationType = 'owner' | 'editor' | 'viewer' | 'member' | 'admin';
+
+export interface ReBACTuple {
+  objectType: ObjectType;
+  objectId: string;
+  relation: RelationType;
+  subjectType: ObjectType;
+  subjectId: string;
+  /** For group references, e.g. "member" means subject is "organization:id#member" */
+  subjectRelation?: RelationType;
+}
+
+export interface ReBACTupleRecord extends ReBACTuple {
+  id: number;
+  createdAt: string;
+}
+
+export interface ReBACUser {
+  id: string;
+  name: string;
+  email: string;
+  createdAt: string;
+  /** Present only when freshly generated — never returned by listUsers() */
+  apiKey?: string;
+}
+
+export interface CheckResult {
+  allowed: boolean;
+}
+
+/** Minimal D1 binding interface (compatible with Cloudflare Workers D1) */
+export interface D1DatabaseBinding {
+  prepare(query: string): {
+    bind(...values: unknown[]): {
+      all<T = Record<string, unknown>>(): Promise<{ results: T[] }>;
+      first<T = Record<string, unknown>>(): Promise<T | null>;
+      run(): Promise<void>;
+    };
+  };
+  exec(query: string): Promise<void>;
+}

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ES2022"],
+    "strict": true,
+    "declaration": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "skipLibCheck": true
+  },
+  "include": ["src"]
+}