feat(rls): implement flexible RLS modes (public-read vs private)

README.md

@@ -92,14 +92,15 @@ Understanding which key to use—and when—prevents the most common integration
 
 ## 🛡️ Row-Level Security (RLS)
 
-RLS lets you safely allow frontend clients to write data without exposing your secret key. When enabled on a collection, `pk_live` writes are gated by user ownership.
+RLS lets you safely allow frontend clients to write data without exposing your secret key. When enabled on a collection, `pk_live` writes are gated by user ownership and reads can be scoped by mode.
 
 **How it works:**
 
-1. Enable RLS for a collection in the Dashboard (mode: `owner-write-only`).
-2. Choose the **owner field** — the document field that stores the authenticated user's ID (e.g., `userId`).
-3. The client must send a valid user JWT in the `Authorization: Bearer <token>` header.
-4. urBackend enforces that the JWT's `userId` matches the document's owner field.
+1. Enable RLS for a collection in the Dashboard and choose a mode.
+2. Use `public-read` for content anyone can view, or `private` for owner-only access. (`owner-write-only` is treated as `public-read` for legacy projects.)
+3. Choose the **owner field** — the document field that stores the authenticated user's ID (e.g., `userId`).
+4. The client must send a valid user JWT in the `Authorization: Bearer <token>` header for `pk_live` writes and for `private` reads.
+5. urBackend enforces that the JWT's `userId` matches the document's owner field.
 
 **Example — user creates a post:**
 

apps/dashboard-api/src/controllers/project.controller.js

@@ -120,7 +120,7 @@ const getDefaultRlsForCollection = (collectionName, schema = []) => {
 
   return {
     enabled: false,
-    mode: "owner-write-only",
+    mode: "public-read",
     ownerField,
     requireAuthForWrite: true,
   };
@@ -1305,9 +1305,10 @@ module.exports.updateCollectionRls = async (req, res) => {
         const collection = project.collections.find(c => c.name === collectionName);
         if (!collection) return res.status(404).json({ error: "Collection not found" });
 
-        const validMode = mode || collection?.rls?.mode || 'owner-write-only';
-        if (validMode !== 'owner-write-only') {
-            return res.status(400).json({ error: "Unsupported RLS mode. Only 'owner-write-only' is allowed in V1." });
+        const validMode = mode || collection?.rls?.mode || 'public-read';
+        const allowedModes = new Set(['public-read', 'private', 'owner-write-only']);
+        if (!allowedModes.has(validMode)) {
+            return res.status(400).json({ error: "Unsupported RLS mode. Allowed: public-read, private, owner-write-only (legacy)." });
         }
 
         const modelKeys = (collection.model || [])
@@ -1363,4 +1364,4 @@ module.exports.updateCollectionRls = async (req, res) => {
     } catch (err) {
         res.status(500).json({ error: err.message });
     }
-}
+}

apps/public-api/src/__tests__/authorizeReadOperation.test.js

@@ -0,0 +1,141 @@
+'use strict';
+
+const authorizeReadOperation = require('../middlewares/authorizeReadOperation');
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function makeProject(rlsOverrides = {}) {
+    return {
+        _id: 'proj_1',
+        collections: [
+            {
+                name: 'posts',
+                rls: {
+                    enabled: true,
+                    mode: 'public-read',
+                    ownerField: 'userId',
+                    requireAuthForWrite: true,
+                    ...rlsOverrides,
+                },
+            },
+        ],
+    };
+}
+
+function makeReq(overrides = {}) {
+    return {
+        keyRole: 'publishable',
+        params: { collectionName: 'posts' },
+        project: makeProject(),
+        authUser: null,
+        rlsFilter: undefined,
+        ...overrides,
+    };
+}
+
+function makeRes() {
+    const res = {
+        statusCode: null,
+        body: null,
+        status: jest.fn().mockReturnThis(),
+        json: jest.fn().mockReturnThis(),
+    };
+    res.status.mockImplementation((code) => {
+        res.statusCode = code;
+        return res;
+    });
+    res.json.mockImplementation((data) => {
+        res.body = data;
+        return res;
+    });
+    return res;
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('authorizeReadOperation middleware', () => {
+    let next;
+
+    beforeEach(() => {
+        next = jest.fn();
+    });
+
+    test('secret key bypass sets empty filter', async () => {
+        const req = makeReq({ keyRole: 'secret' });
+        const res = makeRes();
+
+        await authorizeReadOperation(req, res, next);
+
+        expect(next).toHaveBeenCalledTimes(1);
+        expect(req.rlsFilter).toEqual({});
+    });
+
+    test('returns 404 when collection is not found', async () => {
+        const req = makeReq({ params: { collectionName: 'unknown' } });
+        const res = makeRes();
+
+        await authorizeReadOperation(req, res, next);
+
+        expect(res.statusCode).toBe(404);
+        expect(res.body.error).toBe('Collection not found');
+        expect(next).not.toHaveBeenCalled();
+    });
+
+    test('rls disabled allows public read', async () => {
+        const req = makeReq({ project: makeProject({ enabled: false }) });
+        const res = makeRes();
+
+        await authorizeReadOperation(req, res, next);
+
+        expect(next).toHaveBeenCalledTimes(1);
+        expect(req.rlsFilter).toEqual({});
+    });
+
+    test('public-read allows read without auth', async () => {
+        const req = makeReq({ authUser: null });
+        const res = makeRes();
+
+        await authorizeReadOperation(req, res, next);
+
+        expect(next).toHaveBeenCalledTimes(1);
+        expect(req.rlsFilter).toEqual({});
+    });
+
+    test('owner-write-only is treated as public-read', async () => {
+        const req = makeReq({ project: makeProject({ mode: 'owner-write-only' }) });
+        const res = makeRes();
+
+        await authorizeReadOperation(req, res, next);
+
+        expect(next).toHaveBeenCalledTimes(1);
+        expect(req.rlsFilter).toEqual({});
+    });
+
+    test('private mode requires auth', async () => {
+        const req = makeReq({ project: makeProject({ mode: 'private' }) });
+        const res = makeRes();
+
+        await authorizeReadOperation(req, res, next);
+
+        expect(res.statusCode).toBe(401);
+        expect(res.body.error).toBe('Authentication required');
+        expect(next).not.toHaveBeenCalled();
+    });
+
+    test('private mode sets owner filter when authed', async () => {
+        const req = makeReq({
+            project: makeProject({ mode: 'private', ownerField: 'userId' }),
+            authUser: { userId: 'user_abc' },
+        });
+        const res = makeRes();
+
+        await authorizeReadOperation(req, res, next);
+
+        expect(next).toHaveBeenCalledTimes(1);
+        expect(req.rlsFilter).toEqual({ userId: 'user_abc' });
+    });
+});

apps/public-api/src/__tests__/data.controller.read.test.js

@@ -0,0 +1,104 @@
+'use strict';
+
+const mockFind = jest.fn();
+const mockAnd = jest.fn();
+const mockFindOne = jest.fn();
+const mockQueryLean = jest.fn().mockResolvedValue([]);
+
+// mockAnd returns an object with .lean() so features.query.lean() works after .and()
+mockAnd.mockReturnValue({ lean: mockQueryLean });
+
+const mockQueryEngine = jest.fn((query) => {
+    const engine = {
+        query,
+        filter() { return engine; },
+        sort() { return engine; },
+        paginate() { return engine; },
+    };
+    return engine;
+});
+
+jest.mock('@urbackend/common', () => ({
+    sanitize: (v) => v,
+    Project: {},
+    getConnection: jest.fn().mockResolvedValue({}),
+    getCompiledModel: jest.fn(() => ({
+        find: (...args) => {
+            mockFind(...args);
+            return { and: mockAnd, lean: mockQueryLean };
+        },
+        findOne: (...args) => {
+            mockFindOne(...args);
+            return { lean: jest.fn().mockResolvedValue({ _id: 'doc_1' }) };
+        },
+    })),
+    QueryEngine: mockQueryEngine,
+    validateData: jest.fn(),
+    validateUpdateData: jest.fn(),
+}));
+
+const { getAllData, getSingleDoc } = require('../controllers/data.controller');
+
+function makeReq(overrides = {}) {
+    return {
+        params: { collectionName: 'posts', id: '507f1f77bcf86cd799439011' },
+        project: {
+            _id: 'proj_1',
+            resources: { db: { isExternal: false } },
+            collections: [{ name: 'posts', model: [] }],
+        },
+        query: {},
+        rlsFilter: {},
+        ...overrides,
+    };
+}
+
+function makeRes() {
+    const res = {
+        statusCode: null,
+        body: null,
+        status: jest.fn().mockReturnThis(),
+        json: jest.fn().mockReturnThis(),
+    };
+    res.status.mockImplementation((code) => {
+        res.statusCode = code;
+        return res;
+    });
+    res.json.mockImplementation((data) => {
+        res.body = data;
+        return res;
+    });
+    return res;
+}
+
+describe('data.controller read RLS filters', () => {
+    beforeEach(() => {
+        jest.clearAllMocks();
+    });
+
+    test('getAllData applies rlsFilter to find()', async () => {
+        const req = makeReq({ rlsFilter: { userId: 'user_1' } });
+        const res = makeRes();
+
+        await getAllData(req, res);
+
+        expect(mockFind).toHaveBeenCalledWith();
+        expect(mockAnd).toHaveBeenCalledWith([{ userId: 'user_1' }]);
+        expect(res.json).toHaveBeenCalled();
+    });
+
+    test('getSingleDoc applies rlsFilter to findOne()', async () => {
+        const req = makeReq({ rlsFilter: { userId: 'user_1' } });
+        const res = makeRes();
+
+        await getSingleDoc(req, res);
+
+        expect(mockFindOne).toHaveBeenCalledWith({
+            $and: [
+                { _id: '507f1f77bcf86cd799439011' },
+                { userId: 'user_1' },
+            ],
+        });
+        expect(res.json).toHaveBeenCalled();
+    });
+});

apps/public-api/src/controllers/data.controller.js

@@ -102,8 +102,15 @@ module.exports.getAllData = async (req, res) => {
       project.resources.db.isExternal,
     );
 
+    const baseFilter = req.rlsFilter && typeof req.rlsFilter === 'object' ? req.rlsFilter : {};
     const features = new QueryEngine(Model.find(), req.query)
-      .filter()
+      .filter();
+
+    if (Object.keys(baseFilter).length > 0) {
+      features.query = features.query.and([baseFilter]);
+    }
+
+    features
       .sort()
       .paginate();
 
@@ -140,7 +147,8 @@ module.exports.getSingleDoc = async (req, res) => {
       project.resources.db.isExternal,
     );
 
-    const doc = await Model.findById(id).lean();
+    const baseFilter = req.rlsFilter && typeof req.rlsFilter === 'object' ? req.rlsFilter : {};
+    const doc = await Model.findOne({ $and: [{ _id: id }, baseFilter] }).lean();
     if (!doc) return res.status(404).json({ error: "Document not found." });
 
     res.json(doc);

apps/public-api/src/middlewares/authorizeReadOperation.js

@@ -0,0 +1,47 @@
+module.exports = async (req, res, next) => {
+    try {
+        if (req.keyRole === 'secret') {
+            req.rlsFilter = {};
+            return next();
+        }
+
+        const { collectionName } = req.params;
+        const project = req.project;
+        const collectionConfig = project.collections.find(c => c.name === collectionName);
+
+        if (!collectionConfig) {
+            return res.status(404).json({ error: 'Collection not found' });
+        }
+
+        const rls = collectionConfig.rls || {};
+        if (!rls.enabled) {
+            req.rlsFilter = {};
+            return next();
+        }
+
+        const modeRaw = rls.mode || 'public-read';
+        const mode = modeRaw === 'owner-write-only' ? 'public-read' : modeRaw;
+
+        if (mode === 'private') {
+            if (!req.authUser?.userId) {
+                return res.status(401).json({
+                    error: 'Authentication required',
+                    message: 'Provide a valid user Bearer token for private reads.'
+                });
+            }
+
+            const ownerField = rls.ownerField || 'userId';
+            req.rlsFilter = { [ownerField]: req.authUser.userId };
+            return next();
+        }
+
+        if (mode === 'public-read') {
+            req.rlsFilter = {};
+            return next();
+        }
+
+        return res.status(403).json({ error: 'Unsupported RLS mode' });
+    } catch (err) {
+        return res.status(500).json({ error: err.message });
+    }
+};

apps/public-api/src/middlewares/authorizeWriteOperation.js

@@ -31,7 +31,9 @@ module.exports = async (req, res, next) => {
             });
         }
 
-        if ((rls.mode || 'owner-write-only') !== 'owner-write-only') {
+        const modeRaw = rls.mode || 'public-read';
+        const allowedModes = new Set(['public-read', 'private', 'owner-write-only']);
+        if (!allowedModes.has(modeRaw)) {
             return res.status(403).json({ error: 'Unsupported RLS mode' });
         }