Collection level column permissions

src/Database/Collection.php

@@ -2,6 +2,7 @@
 
 namespace Utopia\Database;
 
+use Utopia\Database\Exception as DatabaseException;
 use Utopia\Database\Exception\Index as IndexException;
 use Utopia\Database\Exception\Relationship as RelationshipException;
 use Utopia\Database\Exception\Structure as StructureException;
@@ -16,7 +17,22 @@ class Collection extends Document
 
     public const string DOCUMENT_SECURITY = 'documentSecurity';
 
-    private const array CORE_KEYS = [self::ATTRIBUTES, self::INDEXES, self::DOCUMENT_SECURITY];
+    /**
+     * The collection's permissions as they were written, kept only when one of them names a column.
+     *
+     * $permissions holds the same set with every column dropped, because that is the form every
+     * read gate matches against -- the `_perms` side table, Postgres' JSONB containment, Mongo's
+     * `$in`. Keeping the column there would make a collection granted `read("any", "name")`
+     * invisible to `any`, since no gate would find the `read("any")` it looks for.
+     *
+     * So this field is the collection's permissions and $permissions is a derived index of them.
+     * Read them through getPermissions(); nothing outside a gate should read $permissions directly.
+     * Empty whenever no permission names a column, which is almost every collection, and then
+     * $permissions is already the verbatim set.
+     */
+    public const string COLUMN_PERMISSIONS = 'columnPermissions';
+
+    private const array CORE_KEYS = [self::ATTRIBUTES, self::INDEXES, self::DOCUMENT_SECURITY, self::COLUMN_PERMISSIONS];
 
     /** @var list<Attribute>|null */
     private ?array $attributeModels = null;
@@ -80,7 +96,7 @@ public static function create(
         ];
 
         if ($permissions !== null) {
-            $data[self::PERMISSIONS] = $permissions;
+            $data = \array_merge($data, self::splitPermissions($permissions));
         }
 
         return new self(\array_merge($data, $metadata));
@@ -124,6 +140,44 @@ public static function fromDocument(Document $document): self
         return $document instanceof self ? $document : self::fromArray($document->getArrayCopy());
     }
 
+    /**
+     * Replace the permission set, writing the gate and the verbatim list together.
+     *
+     * The only place the two fields are set, so they cannot drift: a caller that writes
+     * $permissions alone would leave a stale verbatim list behind it, and getPermissions()
+     * would keep answering with the permissions the collection used to have.
+     *
+     * @param  list<string>  $permissions
+     *
+     * @throws DatabaseException
+     */
+    public function setPermissions(array $permissions): self
+    {
+        foreach (self::splitPermissions($permissions) as $key => $value) {
+            $this->setAttribute($key, $value);
+        }
+
+        return $this;
+    }
+
+    /**
+     * @param  list<string>  $permissions
+     * @return array<string, list<string>>
+     *
+     * @throws DatabaseException
+     */
+    private static function splitPermissions(array $permissions): array
+    {
+        $scoped = Permission::hasColumns($permissions);
+
+        return [
+            self::PERMISSIONS => $scoped ? Permission::withoutColumns($permissions) : $permissions,
+            // Cleared rather than left alone, so dropping the last column-scoped grant from a
+            // collection also drops the list that used to describe it.
+            self::COLUMN_PERMISSIONS => $scoped ? $permissions : [],
+        ];
+    }
+
     public function toDocument(): Document
     {
         $document = new Document();
@@ -265,11 +319,52 @@ public function documentSecurity(): bool
     }
 
     /**
-     * @return list<string>|null
+     * The collection's permissions as they were written, columns included.
+     *
+     * getPermissions() answers with what is stored, which is the role-only projection of these:
+     * every read gate matches that form, so a column stored there would hide the collection from
+     * the role it was granted to. Ask here for the grants themselves -- validation, enforcement
+     * and anything reporting them to a caller -- and ask getPermissions() for what the gate sees.
+     *
+     * @return list<string>|null null when the collection declares no permissions
+     *
+     * @throws StructureException when the stored grants are not a list of permission strings
      */
     public function declaredPermissions(): ?array
     {
-        return $this->offsetExists(self::PERMISSIONS) ? $this->getPermissions() : null;
+        if (! $this->offsetExists(self::PERMISSIONS) && ! $this->offsetExists(self::COLUMN_PERMISSIONS)) {
+            return null;
+        }
+
+        $verbatim = $this->getAttribute(self::COLUMN_PERMISSIONS, []);
+
+        // A definition read straight from storage reaches here before the json filter has run.
+        if (\is_string($verbatim) && $verbatim !== '') {
+            $verbatim = \json_decode($verbatim, true);
+        }
+
+        if ($verbatim === null || $verbatim === '' || $verbatim === []) {
+            return $this->getPermissions();
+        }
+
+        // Never fall back on a value that is present but unreadable. $permissions holds the same
+        // grants widened to the whole row, so answering with it would quietly report more access
+        // than the collection was given.
+        if (! \is_array($verbatim)) {
+            throw new StructureException('Collection '.self::COLUMN_PERMISSIONS.' must be a list of permission strings');
+        }
+
+        $grants = [];
+
+        foreach ($verbatim as $permission) {
+            if (! \is_string($permission)) {
+                throw new StructureException('Collection '.self::COLUMN_PERMISSIONS.' must be a list of permission strings');
+            }
+
+            $grants[] = $permission;
+        }
+
+        return $grants;
     }
 
     #[\Override]

src/Database/Database.php

@@ -183,6 +183,8 @@ class Database
 
     private const string COLLECTION_DOCUMENT_SECURITY = Collection::DOCUMENT_SECURITY;
 
+    private const string COLLECTION_COLUMN_PERMISSIONS = Collection::COLUMN_PERMISSIONS;
+
     private const string INDEX_ATTRIBUTES = 'attributes';
 
     /**
@@ -200,6 +202,7 @@ class Database
         self::COLLECTION_ATTRIBUTES => true,
         self::COLLECTION_INDEXES => true,
         self::COLLECTION_DOCUMENT_SECURITY => true,
+        self::COLLECTION_COLUMN_PERMISSIONS => true,
     ];
 
     protected Adapter $adapter;
@@ -268,6 +271,9 @@ class Database
     /** @var Value<bool>|null */
     private ?Value $validation = null;
 
+    /** @var Value<bool>|null */
+    private ?Value $columnPermissions = null;
+
     /** @var Value<bool>|null */
     private ?Value $datePreservation = null;
 
@@ -1350,6 +1356,29 @@ public function withValidation(bool $validation, callable $callback): mixed
         return $this->validation()->with($validation, $callback);
     }
 
+    /**
+     * Run the callback accepting collection permissions that name a column.
+     *
+     * Off by default, and deliberately so until the column is enforced. A grant naming a column
+     * is recorded, and the role it names is admitted to the row -- which is what every gate
+     * matches -- but nothing yet limits that role to the column. So a grant written to narrow
+     * access currently widens it, and the only safe thing to do with a feature in that state is
+     * to make it unreachable by accident.
+     *
+     * Scoped to the callback rather than stored, because this gates writing such a grant, not
+     * holding one: a collection created through here keeps its grant, and keeps widening, until
+     * masking and query refusal land and the gate comes off.
+     *
+     * @template T
+     *
+     * @param  callable(): T  $callback
+     * @return T
+     */
+    public function withColumnPermissions(callable $callback): mixed
+    {
+        return $this->columnPermissions()->with(true, $callback);
+    }
+
     /**
      * Run the callback without validation for the calling coroutine and the coroutines it starts.
      *
@@ -1635,6 +1664,7 @@ public function snapshot(): Snapshot
             preserveDates: $this->datePreservation()->get(),
             preserveSequence: $this->sequencePreservation()->get(),
             ignoreDuplicates: $this->ignoringDuplicates()->get(),
+            columnPermissions: $this->columnPermissions()->get(),
             requestTimestamp: $this->requestTimestamp()->get(),
             checkGrants: $this->grantChecking()->get(),
             rewriting: $this->rewriting()->get(),
@@ -1681,7 +1711,8 @@ private function withToggles(Snapshot $snapshot, callable $callback): mixed
         $rewritten = fn (): mixed => $this->rewriting()->with($snapshot->rewriting, $callback);
         $checked = fn (): mixed => $this->grantChecking()->with($snapshot->checkGrants, $rewritten);
         $timestamped = fn (): mixed => $this->requestTimestamp()->with($snapshot->requestTimestamp, $checked);
-        $deduplicated = fn (): mixed => $this->ignoringDuplicates()->with($snapshot->ignoreDuplicates, $timestamped);
+        $scoped = fn (): mixed => $this->columnPermissions()->with($snapshot->columnPermissions, $timestamped);
+        $deduplicated = fn (): mixed => $this->ignoringDuplicates()->with($snapshot->ignoreDuplicates, $scoped);
         $sequenced = fn (): mixed => $this->sequencePreservation()->with($snapshot->preserveSequence, $deduplicated);
         $dated = fn (): mixed => $this->datePreservation()->with($snapshot->preserveDates, $sequenced);
         $validated = fn (): mixed => $this->validation()->with($snapshot->validation, $dated);
@@ -1735,6 +1766,22 @@ private function validation(): Value
         return $this->validation ??= new Value(true);
     }
 
+    /**
+     * @return Value<bool>
+     */
+    private function columnPermissions(): Value
+    {
+        return $this->columnPermissions ??= new Value(false);
+    }
+
+    /**
+     * Whether a collection's permissions may name one of its columns.
+     */
+    public function hasColumnPermissions(): bool
+    {
+        return $this->columnPermissions()->get();
+    }
+
     /**
      * @return Value<bool>
      */
@@ -2657,6 +2704,7 @@ private static function sharedDefinition(): Collection
                 Attribute::string(self::COLLECTION_ATTRIBUTES, 1_000_000, filters: [Filter::Json]),
                 Attribute::string(self::COLLECTION_INDEXES, 1_000_000, filters: [Filter::Json]),
                 Attribute::boolean(self::COLLECTION_DOCUMENT_SECURITY, required: true),
+                Attribute::string(self::COLLECTION_COLUMN_PERMISSIONS, 1_000_000, default: [], filters: [Filter::Json]),
             ],
             documentSecurity: false,
             metadata: [Document::COLLECTION => self::METADATA],

src/Database/Document.php

@@ -299,7 +299,18 @@ private function parsePermissions(): array
                 continue;
             }
             $type = \trim(\substr($permission, 0, $open));
-            $roles[$type][] = \str_replace([')', '"', ' '], '', \substr($permission, $open + 1));
+            $role = \substr($permission, $open + 1);
+
+            // A column-scoped permission is read("role", "column"). Only the role belongs here:
+            // this list answers who holds a permission, and the column narrows what that
+            // permission reaches, not who holds it. Leaving the column in would produce a role
+            // of "any,name" that matches nobody.
+            $separator = \strpos($role, '", "');
+            if ($separator !== false) {
+                $role = \substr($role, 0, $separator + 1);
+            }
+
+            $roles[$type][] = \str_replace([')', '"', ' '], '', $role);
         }
 
         return $this->parsedPermissions = [

src/Database/Mirror.php

@@ -516,6 +516,20 @@ public function withValidation(bool $validation, callable $callback): mixed
         return parent::withValidation($validation, fn (): mixed => $this->source->withValidation($validation, $scoped));
     }
 
+    /**
+     * Opened on the mirror, its source and its destination alike: a collection the mirror
+     * replicates is written to both, and the second write would be refused if only the first
+     * had asked for column-scoped permissions.
+     */
+    #[\Override]
+    public function withColumnPermissions(callable $callback): mixed
+    {
+        $destination = $this->destination;
+        $scoped = $destination === null ? $callback : fn (): mixed => $destination->withColumnPermissions($callback);
+
+        return parent::withColumnPermissions(fn (): mixed => $this->source->withColumnPermissions($scoped));
+    }
+
     /**
      * Opens the scope on the mirror, its source and its destination, so the writes the mirror replicates before
      * returning use the tenant too; the replications it queues carry it (see replicate()).