Take Pireon's webhooks: a deactivation or a revocation counts at once

Until now, an account switched off or a token revoked at the identity
server kept working here: bearer tokens until the introspection cache
ran out, panel sessions until they ended, and machine tokens for good,
as they only look at the local account.

POST /api/v1/webhooks/pireon takes user.deactivated (the account goes
inactive, which stops its machine tokens and the panel; its sessions
end and its cached tokens are forgotten) and token.revoked (sessions
and cached tokens go). Pireon signs each delivery with the secret of
the client that registered the webhook, so either PIREON_WEBHOOK_SECRET
(password client) or PIREON_REDIRECT_WEBHOOK_SECRET («Entrar con
Pireon») verifies it; with neither, the endpoint refuses everything.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

app/Actions/Auth/HandlePireonWebhook.php

@@ -0,0 +1,79 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Actions\Auth;
+
+use App\Auth\PireonTokenGuard;
+use App\Models\User;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Log;
+
+/**
+ * What a Pireon webhook changes here.
+ *
+ * - `user.deactivated`: the account goes inactive (which also stops its
+ *   machine tokens and the panel), its panel sessions end and its cached
+ *   bearer tokens are forgotten. Signing in again once Pireon reactivates it
+ *   turns it back on, as every sign-in copies the upstream state.
+ * - `token.revoked`: only token hashes are cached, so every cached token and
+ *   panel session of that person goes; they sign in again.
+ *
+ * Anything else, or a person who never signed in here, is ignored. Repeating
+ * a delivery (one arrives per registered client) changes nothing.
+ */
+class HandlePireonWebhook
+{
+    public const EVENTS = ['user.deactivated', 'token.revoked'];
+
+    /**
+     * @param  array<string, mixed>  $data
+     */
+    public function handle(string $event, array $data): void
+    {
+        if (! in_array($event, self::EVENTS, true)) {
+            Log::debug('Unhandled Pireon webhook', ['event' => $event]);
+
+            return;
+        }
+
+        $oauthId = $data['user_id'] ?? $data['userId'] ?? ($data['user']['id'] ?? null);
+
+        if ($oauthId === null || $oauthId === '') {
+            Log::warning('Pireon webhook without a user id, ignored', ['event' => $event]);
+
+            return;
+        }
+
+        PireonTokenGuard::forgetUser((string) $oauthId);
+
+        $user = User::query()->where('oauth_id', $oauthId)->first();
+
+        if ($user === null) {
+            return;
+        }
+
+        if ($event === 'user.deactivated' && $user->is_active) {
+            $user->forceFill(['is_active' => false])->save();
+        }
+
+        $this->endSessions($user);
+    }
+
+    /**
+     * Sessions kept in the database can be ended one person at a time. With
+     * any other driver they cannot, but an inactive account is still turned
+     * away on its next request (canAccessPanel).
+     */
+    protected function endSessions(User $user): void
+    {
+        if (config('session.driver') !== 'database') {
+            return;
+        }
+
+        DB::connection(config('session.connection'))
+            ->table((string) config('session.table', 'sessions'))
+            ->where('user_id', $user->getKey())
+            ->delete();
+    }
+}

app/Auth/PireonTokenGuard.php

@@ -104,9 +104,33 @@ class PireonTokenGuard
 
         Cache::put($key, $identity->toArray(), $ttl);
 
+        // Which cached tokens are whose, so a webhook can drop a person's.
+        $index = self::indexKey($identity->id);
+        Cache::put($index, array_values(array_unique([...(array) Cache::get($index, []), $key])), $ttl);
+
         return $identity;
     }
 
+    /**
+     * Forget every token of that person checked lately: the next request with
+     * any of them asks the identity server again.
+     */
+    public static function forgetUser(int|string $oauthId): void
+    {
+        $index = self::indexKey($oauthId);
+
+        foreach ((array) Cache::get($index, []) as $key) {
+            Cache::forget((string) $key);
+        }
+
+        Cache::forget($index);
+    }
+
+    protected static function indexKey(int|string $oauthId): string
+    {
+        return 'pireon:introspect:user:'.$oauthId;
+    }
+
     /**
      * Mirror the identity locally so policies, ownership checks and foreign
      * keys have a real row to work with. Local roles are left untouched.

app/Http/Controllers/Api/V1/PireonWebhookController.php

@@ -0,0 +1,61 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Http\Controllers\Api\V1;
+
+use App\Actions\Auth\HandlePireonWebhook;
+use App\Http\Controllers\Controller;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+use Illuminate\Http\Response;
+
+/**
+ * Receives `user.deactivated` and `token.revoked` from the Pireon identity
+ * server, called by it and not by apps.
+ *
+ * `X-Webhook-Signature` is the HMAC-SHA256 (hex) of the raw body with the
+ * secret of the Pireon client that registered the webhook. This application
+ * has two clients (password and redirect), so a delivery is good if it
+ * verifies with either secret. With none configured the endpoint is off: an
+ * open one would let anyone switch accounts off.
+ */
+class PireonWebhookController extends Controller
+{
+    public function __invoke(Request $request, HandlePireonWebhook $handle): Response|JsonResponse
+    {
+        $secrets = (array) config('pireon.webhook_secrets', []);
+
+        if ($secrets === []) {
+            return $this->refuse('Pireon webhooks are disabled (PIREON_WEBHOOK_SECRET is not set).');
+        }
+
+        $signature = preg_replace('/^sha256=/', '', (string) $request->header('X-Webhook-Signature'));
+        $body = $request->getContent();
+
+        $valid = $signature !== '' && collect($secrets)->contains(
+            fn (string $secret): bool => hash_equals(hash_hmac('sha256', $body, $secret), $signature),
+        );
+
+        if (! $valid) {
+            return $this->refuse('Missing or invalid signature.');
+        }
+
+        $event = (string) ($request->input('event') ?? $request->input('type') ?? '');
+
+        if ($event === '') {
+            return response()->json(['message' => 'Missing event name.'], 400);
+        }
+
+        $data = (array) ($request->input('data') ?? $request->input('payload') ?? $request->all());
+
+        $handle->handle($event, $data);
+
+        return response()->noContent();
+    }
+
+    protected function refuse(string $message): JsonResponse
+    {
+        return response()->json(['message' => $message], 401);
+    }
+}