fix(security): honour Pods field restrictions (audit M4)

PodsFieldSource maps hidden, read_only, admin_only and
restrict_role/-capability like Pods' own view: hidden -> new status
HIDDEN, read_only -> READONLY, restricted and not permitted -> READONLY
with read_only_restricted, else HIDDEN. HIDDEN fields are not described,
read out, queried or written (they look unknown) but stay in the schema
for the media usage search; write() re-checks before Pods' save().
Required-but-restricted fields no longer block a create. Pods is not
active on DDEV: covered by unit tests with a field-option fixture.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01At3V6SjwbMe6eMzVGW3Hs7

src/Integrations/Pods/PodsFieldSource.php

@@ -13,6 +13,12 @@ use Throwable;
  * Pods field adapter (spec §6.1/§6.2): definitions from pods_api()->load_pod(),
  * values read and written through the Pods API so relationships and caches stay
  * consistent. Works with Pods 3.x (Pods\Whatsit\Pod / Pods\Whatsit\Field).
+ *
+ * Field restrictions (security audit M4): Pods enforces admin_only, restrict_role/-capability,
+ * read_only and hidden only in its forms – its PHP API (save() with from = 'save') skips them.
+ * They are mapped like Pods' own view does: hidden → HIDDEN; read_only → READONLY; restricted
+ * and not permitted for the current user → READONLY with read_only_restricted, else HIDDEN.
+ * write() refuses every field that is not writable before anything reaches Pods.
  */
 final class PodsFieldSource implements FieldSource
 {
@@ -34,10 +40,20 @@ final class PodsFieldSource implements FieldSource
     /** @var callable(string, int): mixed */
     private $podFor;
 
-    public function __construct(?callable $loadPod = null, ?callable $podFor = null)
+    /** @var callable(object): ?bool Pods field => null (unrestricted) or whether the current user may use it. */
+    private $permitted;
+
+    public function __construct(?callable $loadPod = null, ?callable $podFor = null, ?callable $permitted = null)
     {
         $this->loadPod = $loadPod ?? static fn (string $name): mixed => pods_api()->load_pod(['name' => $name]);
         $this->podFor = $podFor ?? static fn (string $name, int $id): mixed => pods($name, $id);
+        $this->permitted = $permitted ?? static function (object $field): ?bool {
+            if (! function_exists('pods_has_permissions') || ! pods_has_permissions($field)) {
+                return null;
+            }
+
+            return function_exists('pods_permission') && (bool) pods_permission($field);
+        };
     }
 
     public static function isAvailable(): bool
@@ -93,6 +109,11 @@ final class PodsFieldSource implements FieldSource
     {
         $data = [];
         foreach ($values as $key => $value) {
+            $status = isset($definitions[$key]) ? $definitions[$key]->status : null;
+            if ($status === FieldDefinition::READONLY || $status === FieldDefinition::HIDDEN) {
+                throw new RuntimeException(sprintf('Pods field %s is restricted for the current user.', $key));
+            }
+
             $multiple = isset($definitions[$key]) && $definitions[$key]->multiple;
             $data[$key] = $value ?? ($multiple ? [] : '');
         }
@@ -140,7 +161,7 @@ final class PodsFieldSource implements FieldSource
             (string) $field->get_label(),
             $normalized,
             'pods',
-            $normalized === 'unknown' ? FieldDefinition::UNKNOWN : FieldDefinition::WRITABLE,
+            $this->status($field, $normalized === 'unknown' ? FieldDefinition::UNKNOWN : FieldDefinition::WRITABLE),
             (bool) $field->is_required(),
             (bool) $field->is_multi_value(),
             $choices,
@@ -149,6 +170,28 @@ final class PodsFieldSource implements FieldSource
         );
     }
 
+    /** $open: the status without restrictions (writable or unknown). */
+    private function status(object $field, string $open): string
+    {
+        if (self::flag($field, 'hidden')) {
+            return FieldDefinition::HIDDEN;
+        }
+
+        if (($this->permitted)($field) === false) {
+            return self::flag($field, 'read_only_restricted') ? FieldDefinition::READONLY : FieldDefinition::HIDDEN;
+        }
+
+        return self::flag($field, 'read_only') ? FieldDefinition::READONLY : $open;
+    }
+
+    /** A Pods boolean option (stored as 1/'1'/true, like pods_v_bool()). */
+    private static function flag(object $field, string $name): bool
+    {
+        $value = $field->get_arg($name, false);
+
+        return $value === true || in_array(strtolower(trim((string) $value)), ['1', 'true', 'yes', 'on'], true);
+    }
+
     /** @return list<array{value: string, label: string}> */
     private function choices(string $raw): array
     {