refactor: improve SignedPayload structure and harden edge cases

- Extract duplicated payload/HMAC logic into private instance methods
  (payloadData(), sign()) to reduce code noise (DRY)
- Reorder methods: public static -> public instance -> private static
  -> private instance (standard PHP convention)
- Make handleSignedCall() and methodIsSigned() private (minimal surface)
- Combine chained filter() calls into single filter in methodIsSigned()
  and Signed::resolveMethodTtl()
- Use nullsafe operator in resolveMethodTtl() ($signed?->ttl)
- Replace implicit TTL falsy coercion ($ttl ?) with explicit $ttl > 0
- Add test for __callSigned called with no params
- Add documentation comments for design tradeoffs (public constructor,
  replay behavior, TTL 0->null normalization, $__livewire dependency)
- Update docs to reflect current architecture

Author: glasssshouse

docs/signed-actions.md

@@ -78,7 +78,7 @@ Replace inline method calls with the `@livewireAction` directive:
 
 1. **At render time**, `@livewireAction` generates an HMAC-SHA256 signature over the method name, parameters, and component ID using a purpose-specific key derived from your `APP_KEY` (domain-separated so that other subsystems sharing the same key cannot produce cross-valid signatures)
 2. The signed payload is encoded as a base64 string and rendered as `__callSigned('eyJ...')`
-3. **When clicked**, the `SupportSignedActions` hook intercepts the call, verifies the HMAC, checks the component ID matches, and only then executes the method
+3. **When clicked**, the `SupportSignedActions` hook intercepts the call and verifies in sequence: payload structure → field types → HMAC signature → expiry (if TTL is set) → component ID match. Only then is the method executed
 4. Direct calls to `#[Signed]` methods (e.g., `$wire.call('delete', 5)`) are **blocked**
 
 ### What's protected
@@ -87,6 +87,7 @@ Replace inline method calls with the `@livewireAction` directive:
 |--------|--------|
 | Change parameters in DOM | ❌ HMAC verification fails |
 | Call signed method directly via JS | ❌ Blocked - must use signed payload |
+| Call `__callSigned` with no payload | ❌ Blocked - payload parameter required |
 | Replay payload on different component | ❌ Component ID mismatch |
 | Tamper with expiration timestamp | ❌ HMAC verification fails |
 | Use expired payload | ❌ `ExpiredSignedActionException` thrown |

src/Attributes/Signed.php

@@ -39,11 +39,10 @@ public static function resolveMethodTtl(object $component, string $method, ?int
     {
         $signed = $component->getAttributes()
             ->whereInstanceOf(self::class)
-            ->filter(fn (self $attribute) => $attribute->getLevel() === AttributeLevel::METHOD)
-            ->filter(fn (self $attribute) => $attribute->getName() === $method)
+            ->filter(fn (self $attribute) => $attribute->getLevel() === AttributeLevel::METHOD && $attribute->getName() === $method)
             ->first();
 
-        if ($signed && $signed->ttl !== null) {
+        if ($signed?->ttl !== null) {
             return $signed->ttl;
         }
 

src/Features/SupportSignedActions/SignedPayload.php

@@ -11,31 +11,22 @@ class SignedPayload
 {
     private const JSON_FLAGS = JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE;
 
+    /**
+     * Constructor is public to allow tests to forge payloads for security assertions.
+     * Arbitrary instances cannot produce valid signatures without the APP_KEY.
+     */
     public function __construct(
         public readonly string $componentId,
         public readonly string $method,
         public readonly array $params = [],
         public readonly ?int $expiry = null,
     ) {}
 
-    /**
-     * Get the application signing key, ensuring it is set.
-     *
-     * Derives a purpose-specific key via HMAC to provide domain separation.
-     * This prevents cross-system signature confusion if other subsystems
-     * also use the raw APP_KEY with hash_hmac('sha256', ...).
-     *
-     * @throws \RuntimeException
-     */
-    private static function signingKey(): string
-    {
-        throw_unless(config('app.key'), \RuntimeException::class, 'No application key set. Signed actions require an APP_KEY to be configured.');
-
-        return hash_hmac('sha256', 'livewire-strict:signed-actions', config('app.key'));
-    }
-
     /**
      * Create a signed payload for a component, resolving per-method TTL overrides.
+     *
+     * Note: Signed::resolveMethodTtl() may return 0 (meaning "never expire").
+     * The `$ttl > 0` check normalizes 0 to null so the payload has no expiry.
      */
     public static function forComponent(object $component, string $method, mixed ...$params): self
     {
@@ -45,13 +36,21 @@ public static function forComponent(object $component, string $method, mixed ...
             componentId: $component->getId(),
             method: $method,
             params: $params,
-            expiry: $ttl ? Carbon::now()->timestamp + $ttl : null,
+            expiry: $ttl > 0 ? Carbon::now()->timestamp + $ttl : null,
         );
     }
 
     /**
      * Verify an encoded payload against a component and return a SignedPayload instance.
      *
+     * Verification order: structure → types → HMAC → expiry → component ID.
+     * This order avoids timing oracles (HMAC checked before component ID)
+     * and skips unnecessary work on structurally invalid payloads.
+     *
+     * Note: valid payloads can be replayed on the same component instance.
+     * This is by design - Blade buttons render a fixed payload that must
+     * remain usable across multiple clicks. Use TTL to limit the replay window.
+     *
      * @throws InvalidSignedActionException
      * @throws ExpiredSignedActionException
      */
@@ -65,71 +64,87 @@ public static function verify(string $encodedPayload, object $component): self
         );
 
         // Validate types of the decoded payload to avoid TypeError and ensure predictable failures.
-        $hasInvalidTypes = !is_scalar($decoded['id'])
-            || !is_scalar($decoded['method'])
-            || !is_scalar($decoded['sig'])
-            || !is_array($decoded['params'])
-            || (array_key_exists('exp', $decoded) && !is_int($decoded['exp']));
-
-        if ($hasInvalidTypes) {
-            throw new InvalidSignedActionException('');
-        }
-
-        $id = (string) $decoded['id'];
-        $method = (string) $decoded['method'];
+        throw_if(
+            !is_scalar($decoded['id'])
+                || !is_scalar($decoded['method'])
+                || !is_scalar($decoded['sig'])
+                || !is_array($decoded['params'])
+                || (array_key_exists('exp', $decoded) && !is_int($decoded['exp'])),
+            InvalidSignedActionException::class,
+        );
+
         $sig = (string) $decoded['sig'];
-        $params = $decoded['params'];
-        $exp = $decoded['exp'] ?? null;
-
-        $payloadData = array_filter([
-            'id' => $id,
-            'method' => $method,
-            'params' => $params,
-            'exp' => $exp,
-        ], fn ($value) => $value !== null);
 
-        $expectedSig = hash_hmac('sha256', json_encode($payloadData, self::JSON_FLAGS), self::signingKey());
+        $instance = new self(
+            componentId: (string) $decoded['id'],
+            method: (string) $decoded['method'],
+            params: $decoded['params'],
+            expiry: $decoded['exp'] ?? null,
+        );
 
-        throw_unless(hash_equals($expectedSig, $sig), InvalidSignedActionException::class, $method);
+        throw_unless(hash_equals($instance->sign(), $sig), InvalidSignedActionException::class, $instance->method);
 
         throw_if(
-            isset($exp) && Carbon::now()->timestamp > $exp,
+            isset($instance->expiry) && Carbon::now()->timestamp > $instance->expiry,
             ExpiredSignedActionException::class,
-            $method,
+            $instance->method,
         );
 
-        throw_unless($id === $component->getId(), InvalidSignedActionException::class, $method);
+        throw_unless($instance->componentId === $component->getId(), InvalidSignedActionException::class, $instance->method);
 
-        return new self(
-            componentId: $id,
-            method: $method,
-            params: $params,
-            expiry: $exp,
-        );
+        return $instance;
     }
 
     /**
      * Encode the payload into a signed, base64-encoded string.
      */
     public function encode(): string
     {
-        $payloadData = array_filter([
+        return base64_encode(json_encode(array_merge($this->payloadData(), ['sig' => $this->sign()])));
+    }
+
+    /**
+     * Get the wire action string for use in Blade templates.
+     */
+    public function toAction(): string
+    {
+        return "__callSigned('{$this->encode()}')";
+    }
+
+    /**
+     * Get the application signing key, ensuring it is set.
+     *
+     * Derives a purpose-specific key via HMAC to provide domain separation.
+     * This prevents cross-system signature confusion if other subsystems
+     * also use the raw APP_KEY with hash_hmac('sha256', ...).
+     *
+     * @throws \RuntimeException
+     */
+    private static function signingKey(): string
+    {
+        throw_unless(config('app.key'), \RuntimeException::class, 'No application key set. Signed actions require an APP_KEY to be configured.');
+
+        return hash_hmac('sha256', 'livewire-strict:signed-actions', config('app.key'));
+    }
+
+    /**
+     * Build the canonical payload data array used for signing.
+     */
+    private function payloadData(): array
+    {
+        return array_filter([
             'id' => $this->componentId,
             'method' => $this->method,
             'params' => $this->params,
             'exp' => $this->expiry,
         ], fn ($value) => $value !== null);
-
-        $signature = hash_hmac('sha256', json_encode($payloadData, self::JSON_FLAGS), self::signingKey());
-
-        return base64_encode(json_encode(array_merge($payloadData, ['sig' => $signature])));
     }
 
     /**
-     * Get the wire action string for use in Blade templates.
+     * Compute the HMAC-SHA256 signature for this payload.
      */
-    public function toAction(): string
+    private function sign(): string
     {
-        return "__callSigned('{$this->encode()}')";
+        return hash_hmac('sha256', json_encode($this->payloadData(), self::JSON_FLAGS), self::signingKey());
     }
 }

src/Features/SupportSignedActions/SupportSignedActions.php

@@ -39,7 +39,7 @@ public function call($method, $params, $returnEarly, $metadata, $componentContex
         }
     }
 
-    protected function handleSignedCall(array $params, callable $returnEarly): void
+    private function handleSignedCall(array $params, callable $returnEarly): void
     {
         throw_if(
             method_exists($this->component, '__callSigned'),
@@ -66,13 +66,12 @@ protected function handleSignedCall(array $params, callable $returnEarly): void
         );
     }
 
-    protected function methodIsSigned(string $method): bool
+    private function methodIsSigned(string $method): bool
     {
         return $this->component
             ->getAttributes()
             ->whereInstanceOf(Signed::class)
-            ->filter(fn (Signed $attribute) => $attribute->getLevel() === AttributeLevel::METHOD)
-            ->filter(fn (Signed $attribute) => $attribute->getName() === $method)
+            ->filter(fn (Signed $attribute) => $attribute->getLevel() === AttributeLevel::METHOD && $attribute->getName() === $method)
             ->isNotEmpty();
     }
 }

src/Features/SupportSignedActions/UnitTest.php

@@ -520,6 +520,22 @@ public function delete(int $id)
         })->call('__callSigned', 12345);
     }
 
+    public function test_rejects_callSigned_with_no_params()
+    {
+        $this->expectException(InvalidSignedActionException::class);
+
+        LivewireStrict::signedActions(components: 'WireElements\*');
+
+        Livewire::test(new class extends TestSignedComponent
+        {
+            #[Signed]
+            public function delete(int $id)
+            {
+                $this->result = $id;
+            }
+        })->call('__callSigned');
+    }
+
     public function test_valid_payload_can_be_replayed()
     {
         LivewireStrict::signedActions(components: 'WireElements\*');
@@ -924,7 +940,7 @@ public function delete(int $id)
             // expected
         }
 
-        // Disabling at runtime bypasses all protection — flag for audit
+        // Disabling at runtime bypasses all protection - flag for audit
         SupportSignedActions::$enabled = false;
 
         $component

src/LivewireStrict.php

@@ -29,7 +29,7 @@ public static function signedActions($shouldSignActions = true, $components = ['
     {
         Signed::validateTtl($ttl);
 
-        SupportSignedActions::$ttl = $ttl ?: null;
+        SupportSignedActions::$ttl = $ttl > 0 ? $ttl : null;
         SupportSignedActions::$enabled = $shouldSignActions;
         SupportSignedActions::$components = Arr::wrap($components);
     }

src/LivewireStrictServiceProvider.php

@@ -21,6 +21,7 @@ public function register(): void
      */
     public function boot(): void
     {
+        // $__livewire is the component instance injected by Livewire's Blade rendering.
         Blade::directive('livewireAction', function ($expression) {
             return "<?php echo \\WireElements\\LivewireStrict\\Features\\SupportSignedActions\\SignedPayload::forComponent(\$__livewire, $expression)->toAction(); ?>";
         });