Merge pull request #13 from anikeen-com/fix/guard-registration

Fix the anikeen API guard and register its user provider

README.md

@@ -157,6 +157,63 @@ Each order has `status` (`processing` = current month, still collecting; `pendin
 paid; `completed`; `cancelled`), the totals, `payment_attempts`, `next_payment_attempt_at` (null =
 no more automatic retries) and `last_payment_error`.
 
+### Checkout sessions (the user confirms several subscriptions at once)
+
+Instead of checking subscriptions out itself, an app can let the user confirm them on Anikeen ID,
+all of them in one step: a checkout session bundles new subscriptions (or existing drafts of the
+app, `['id' => …]`) of one user. The user sees every item with its price and the total of the first
+period, confirms (all subscriptions start, or none) or cancels, and returns to `return_url`.
+Open sessions expire after 24 hours with their drafts. Trusted apps can still check out directly;
+sessions are opt-in.
+
+Example: the Console's builder ("Jetzt kaufen") with several products and coupon prices:
+
+```php
+use Anikeen\Id\Exceptions\ApiException;
+
+$session = $request->user()->appCheckoutSessions()->create([   // app token; or ->checkoutSessions() with the user's token
+    'return_url' => route('builder.done'),                      // same origin as one of your redirect URIs
+    'metadata' => ['cart' => $cart->id],                        // returned as is
+    'idempotency_key' => "cart:{$cart->id}",                    // retries return the same session
+    'subscriptions' => $cart->items->map(fn ($item) => [
+        'group' => $team->id,
+        'name' => $item->product->name,
+        'description' => $item->label,
+        'unit' => $item->unit,                                  // hour, day, week, month, year
+        'price' => $item->priceAfterCoupon(),                   // net, per unit
+        'payload' => ['cart_item' => $item->id],
+    ])->all(),
+]);
+
+$cart->update(['checkout_session_id' => $session->id, 'subscription_ids' => $session->subscriptionIds()]);
+
+return redirect($session->confirmationUrl());
+// later: https://console.test/builder/done?status=completed&checkout_session=01K…
+```
+
+Provision when the webhook arrives (or after checking the session through the API; never trust the
+query string):
+
+```php
+use Anikeen\Id\Webhooks\EventType;
+
+match ($event['type']) {
+    EventType::CHECKOUT_COMPLETED => Provisioner::provision($event['data']['object']['subscriptions']), // all running
+    EventType::CHECKOUT_CANCELLED, EventType::CHECKOUT_EXPIRED => Cart::release($event['data']['object']['metadata']['cart'] ?? null),
+    default => null,
+};
+
+app(AnikeenId::class)->appCheckoutSessions()->find($id)?->isCompleted(); // any user's session
+$session->refresh()->subscriptions();  // AppSubscription objects
+$session->cancel();                    // withdraw an open session and its drafts (e.g. the cart changed)
+```
+
+While a session is open, its subscriptions can't be checked out or repriced by the app (409
+`in_checkout_session` / `not_changeable`). The session's `status` is `open`, `completed`,
+`cancelled` or `expired` (`isOpen()`, `isCompleted()`, `isCancelled()` for cancelled or expired).
+`subscription.activated` / `subscription.cancelled` are still sent per subscription, before the
+`checkout.*` event of the session.
+
 ### Selling as a third-party app (user confirms on Anikeen ID)
 
 Apps that are not trusted can create orders and subscriptions for the signed-in user (user token),
@@ -197,7 +254,8 @@ $order = $user->orders()->create([
 ```
 
 Once a paid order is sent, create a shipment. Anikeen ID adds its delivery note to the user's
-order documents (with the tracking link) and sends `order.shipped` to your webhook endpoints.
+order documents (with the tracking link), mails it to the user (`'notify_customer' => false` if
+your shop sends its own mail) and sends `order.shipped` to your webhook endpoints.
 Without `items`, everything physical that is left is shipped; partial deliveries name the items:
 
 ```php
@@ -221,12 +279,13 @@ points to the same page. Trusted apps keep checking out directly.
 
 ### Webhooks
 
-Anikeen ID sends `order.*` and `subscription.*` events to the webhook endpoints of your app (set up
+Anikeen ID sends `order.*`, `subscription.*` and `checkout.*` events to the webhook endpoints of your app (set up
 in the Anikeen ID admin panel, which also shows the signing secret `whsec_…`). Verify each request
 with the raw body and answer 2xx within 10 seconds; failed deliveries are retried for about three days.
 
 ```php
 use Anikeen\Id\Exceptions\SignatureVerificationException;
+use Anikeen\Id\Webhooks\EventType;
 use Anikeen\Id\Webhooks\Webhook;
 
 Route::post('webhooks/anikeen', function (Request $request) {
@@ -237,8 +296,9 @@ Route::post('webhooks/anikeen', function (Request $request) {
     }
 
     match ($event['type']) {
-        'order.completed' => Shop::fulfil($event['data']['object']['id']),
+        EventType::ORDER_COMPLETED => Shop::fulfil($event['data']['object']['id']),
-        'subscription.cancelled' => Panel::suspend($event['data']['object']['id']),
+        EventType::SUBSCRIPTION_CANCELLED => Panel::suspend($event['data']['object']['id']),
+        EventType::CHECKOUT_COMPLETED => Panel::provision($event['data']['object']['subscription_ids']),
         default => null,
     };
 
@@ -263,30 +323,10 @@ public function boot(): void
 }
 ```
 
-### Implementing Auth
+### Implementing Auth (API tokens)
 
-This method should typically be called in the `boot` method of your `AppServiceProvider` class:
+The package registers an `anikeen` guard driver and an `anikeen` user provider. Reference them
-
+in `config/auth.php`:
-```php
-use Anikeen\Id\AnikeenId;
-use Anikeen\Id\Providers\AnikeenIdUserProvider;
-use Illuminate\Http\Request;
-use Illuminate\Support\Facades\Auth;
-
-public function boot(): void
-{
-    Auth::provider('anikeen', function ($app, array $config) {
-        return new AnikeenIdUserProvider(
-            $app->make(AnikeenId::class),
-            $app->make(Request::class),
-            $config['model'],
-            $config['fields'] ?? [],
-        );
-    });
-}
-```
-
-reference the guard in the `guards` configuration of your `auth.php` configuration file:
 
 ```php
 'guards' => [
@@ -300,11 +340,7 @@ reference the guard in the `guards` configuration of your `auth.php` configurati
         'provider' => 'anikeen',
     ],
 ],
-```
 
-reference the provider in the `providers` configuration of your `auth.php` configuration file:
-
-```php
 'providers' => [
     'users' => [
         'driver' => 'eloquent',
@@ -314,11 +350,48 @@ reference the provider in the `providers` configuration of your `auth.php` confi
     'anikeen' => [
         'driver' => 'anikeen',
         'model' => App\Models\User::class,
-        'fields' => ['first_name', 'last_name', 'email'],
+        'column' => 'anikeen_id', // optional, see below
     ],
 ],
 ```
 
+The guard accepts `Authorization: Bearer <access token>` with an access token issued by Anikeen ID
+(personal access token or OAuth token, a JWT). It verifies the RS256 signature with Anikeen ID's
+public key and the time claims (`exp`, `nbf`, `iat`, 60 seconds leeway). The token's `sub` (the
+user's Anikeen ID) is looked up in the column `anikeen_id` of the user model: the provider's
+`column`, else `services.anikeen.user_id_column`, else `AnikeenId::useUserIdField()`. Tokens of
+unknown users, client credentials tokens (no `sub`), expired or forged tokens leave the request
+unauthenticated, so `auth:api` answers `401 {"message": "Unauthenticated."}` to JSON requests.
+
+The user model uses `Anikeen\Id\HasAnikeenTokens`; the token's scopes are then available:
+
+```php
+$request->user()->anikeenTokenCan('user');               // has the scope (or `*`)
+$request->user()->anikeenTokenCanAny(['user', 'user:read']);
+```
+
+or as middleware (`403` without the scope):
+
+```php
+use Anikeen\Id\Http\Middleware\CheckForAnyScope;
+use Anikeen\Id\Http\Middleware\CheckScopes;
+
+Route::middleware(['auth:api', CheckScopes::using('user')])->post(...);                    // all scopes
+Route::middleware(['auth:api', CheckForAnyScope::using('user', 'user:read')])->get(...);  // any scope
+```
+
+Options in `config/services.php` (`anikeen`):
+
+| Key | Default | |
+|-----|---------|-|
+| `public_key` | – | Anikeen ID's public key (PEM; `\n` escapes allowed) |
+| `public_key_path` | – | path to that key; without both the key shipped for the `mode` is used |
+| `user_id_column` | `anikeen_id` | column holding the user's Anikeen ID |
+| `verify_revocation` | `false` | also ask Anikeen ID (`GET v1/user`) whether the token is still valid, so revoked tokens stop working before they expire; fails closed when Anikeen ID is unreachable |
+| `revocation_cache_ttl` | `300` | seconds that answer is cached per token |
+
+The key is read once per process. In tests `AnikeenId::actingAs($user, ['user'])` signs in without a token.
+
 ## General
 
 #### Setters and Getters
@@ -470,6 +543,7 @@ public function shippingPriceList(): Result
 
 ```php
 public function appOrders(): AppOrders
+public function appCheckoutSessions(): AppCheckoutSessions
 public function createOrderForUser(string $userId, array $attributes): Result
 public function createTransactionForUser(string $userId, array $attributes): Result
 ```
@@ -572,6 +646,8 @@ public function getBillable(): Billable
 ```php
 public function subscriptions(): Subscriptions
 public function appSubscriptions(): AppSubscriptions
+public function appCheckoutSessions(): AppCheckoutSessions
+public function checkoutSessions(): CheckoutSessions
 public function appOrders(): AppOrders
 public function setBillable(Billable|Model $billable): self
 public function getBillable(): Billable

README.stub

@@ -157,6 +157,63 @@ Each order has `status` (`processing` = current month, still collecting; `pendin
 paid; `completed`; `cancelled`), the totals, `payment_attempts`, `next_payment_attempt_at` (null =
 no more automatic retries) and `last_payment_error`.
 
+### Checkout sessions (the user confirms several subscriptions at once)
+
+Instead of checking subscriptions out itself, an app can let the user confirm them on Anikeen ID,
+all of them in one step: a checkout session bundles new subscriptions (or existing drafts of the
+app, `['id' => …]`) of one user. The user sees every item with its price and the total of the first
+period, confirms (all subscriptions start, or none) or cancels, and returns to `return_url`.
+Open sessions expire after 24 hours with their drafts. Trusted apps can still check out directly;
+sessions are opt-in.
+
+Example: the Console's builder ("Jetzt kaufen") with several products and coupon prices:
+
+```php
+use Anikeen\Id\Exceptions\ApiException;
+
+$session = $request->user()->appCheckoutSessions()->create([   // app token; or ->checkoutSessions() with the user's token
+    'return_url' => route('builder.done'),                      // same origin as one of your redirect URIs
+    'metadata' => ['cart' => $cart->id],                        // returned as is
+    'idempotency_key' => "cart:{$cart->id}",                    // retries return the same session
+    'subscriptions' => $cart->items->map(fn ($item) => [
+        'group' => $team->id,
+        'name' => $item->product->name,
+        'description' => $item->label,
+        'unit' => $item->unit,                                  // hour, day, week, month, year
+        'price' => $item->priceAfterCoupon(),                   // net, per unit
+        'payload' => ['cart_item' => $item->id],
+    ])->all(),
+]);
+
+$cart->update(['checkout_session_id' => $session->id, 'subscription_ids' => $session->subscriptionIds()]);
+
+return redirect($session->confirmationUrl());
+// later: https://console.test/builder/done?status=completed&checkout_session=01K…
+```
+
+Provision when the webhook arrives (or after checking the session through the API; never trust the
+query string):
+
+```php
+use Anikeen\Id\Webhooks\EventType;
+
+match ($event['type']) {
+    EventType::CHECKOUT_COMPLETED => Provisioner::provision($event['data']['object']['subscriptions']), // all running
+    EventType::CHECKOUT_CANCELLED, EventType::CHECKOUT_EXPIRED => Cart::release($event['data']['object']['metadata']['cart'] ?? null),
+    default => null,
+};
+
+app(AnikeenId::class)->appCheckoutSessions()->find($id)?->isCompleted(); // any user's session
+$session->refresh()->subscriptions();  // AppSubscription objects
+$session->cancel();                    // withdraw an open session and its drafts (e.g. the cart changed)
+```
+
+While a session is open, its subscriptions can't be checked out or repriced by the app (409
+`in_checkout_session` / `not_changeable`). The session's `status` is `open`, `completed`,
+`cancelled` or `expired` (`isOpen()`, `isCompleted()`, `isCancelled()` for cancelled or expired).
+`subscription.activated` / `subscription.cancelled` are still sent per subscription, before the
+`checkout.*` event of the session.
+
 ### Selling as a third-party app (user confirms on Anikeen ID)
 
 Apps that are not trusted can create orders and subscriptions for the signed-in user (user token),
@@ -185,12 +242,13 @@ points to the same page. Trusted apps keep checking out directly.
 
 ### Webhooks
 
-Anikeen ID sends `order.*` and `subscription.*` events to the webhook endpoints of your app (set up
+Anikeen ID sends `order.*`, `subscription.*` and `checkout.*` events to the webhook endpoints of your app (set up
 in the Anikeen ID admin panel, which also shows the signing secret `whsec_…`). Verify each request
 with the raw body and answer 2xx within 10 seconds; failed deliveries are retried for about three days.
 
 ```php
 use Anikeen\Id\Exceptions\SignatureVerificationException;
+use Anikeen\Id\Webhooks\EventType;
 use Anikeen\Id\Webhooks\Webhook;
 
 Route::post('webhooks/anikeen', function (Request $request) {
@@ -201,8 +259,9 @@ Route::post('webhooks/anikeen', function (Request $request) {
     }
 
     match ($event['type']) {
-        'order.completed' => Shop::fulfil($event['data']['object']['id']),
+        EventType::ORDER_COMPLETED => Shop::fulfil($event['data']['object']['id']),
-        'subscription.cancelled' => Panel::suspend($event['data']['object']['id']),
+        EventType::SUBSCRIPTION_CANCELLED => Panel::suspend($event['data']['object']['id']),
+        EventType::CHECKOUT_COMPLETED => Panel::provision($event['data']['object']['subscription_ids']),
         default => null,
     };
 
@@ -227,30 +286,10 @@ public function boot(): void
 }
 ```
 
-### Implementing Auth
+### Implementing Auth (API tokens)
 
-This method should typically be called in the `boot` method of your `AppServiceProvider` class:
+The package registers an `anikeen` guard driver and an `anikeen` user provider. Reference them
-
+in `config/auth.php`:
-```php
-use Anikeen\Id\AnikeenId;
-use Anikeen\Id\Providers\AnikeenIdUserProvider;
-use Illuminate\Http\Request;
-use Illuminate\Support\Facades\Auth;
-
-public function boot(): void
-{
-    Auth::provider('anikeen', function ($app, array $config) {
-        return new AnikeenIdUserProvider(
-            $app->make(AnikeenId::class),
-            $app->make(Request::class),
-            $config['model'],
-            $config['fields'] ?? [],
-        );
-    });
-}
-```
-
-reference the guard in the `guards` configuration of your `auth.php` configuration file:
 
 ```php
 'guards' => [
@@ -264,11 +303,7 @@ reference the guard in the `guards` configuration of your `auth.php` configurati
         'provider' => 'anikeen',
     ],
 ],
-```
 
-reference the provider in the `providers` configuration of your `auth.php` configuration file:
-
-```php
 'providers' => [
     'users' => [
         'driver' => 'eloquent',
@@ -278,11 +313,48 @@ reference the provider in the `providers` configuration of your `auth.php` confi
     'anikeen' => [
         'driver' => 'anikeen',
         'model' => App\Models\User::class,
-        'fields' => ['first_name', 'last_name', 'email'],
+        'column' => 'anikeen_id', // optional, see below
     ],
 ],
 ```
 
+The guard accepts `Authorization: Bearer <access token>` with an access token issued by Anikeen ID
+(personal access token or OAuth token, a JWT). It verifies the RS256 signature with Anikeen ID's
+public key and the time claims (`exp`, `nbf`, `iat`, 60 seconds leeway). The token's `sub` (the
+user's Anikeen ID) is looked up in the column `anikeen_id` of the user model: the provider's
+`column`, else `services.anikeen.user_id_column`, else `AnikeenId::useUserIdField()`. Tokens of
+unknown users, client credentials tokens (no `sub`), expired or forged tokens leave the request
+unauthenticated, so `auth:api` answers `401 {"message": "Unauthenticated."}` to JSON requests.
+
+The user model uses `Anikeen\Id\HasAnikeenTokens`; the token's scopes are then available:
+
+```php
+$request->user()->anikeenTokenCan('user');               // has the scope (or `*`)
+$request->user()->anikeenTokenCanAny(['user', 'user:read']);
+```
+
+or as middleware (`403` without the scope):
+
+```php
+use Anikeen\Id\Http\Middleware\CheckForAnyScope;
+use Anikeen\Id\Http\Middleware\CheckScopes;
+
+Route::middleware(['auth:api', CheckScopes::using('user')])->post(...);                    // all scopes
+Route::middleware(['auth:api', CheckForAnyScope::using('user', 'user:read')])->get(...);  // any scope
+```
+
+Options in `config/services.php` (`anikeen`):
+
+| Key | Default | |
+|-----|---------|-|
+| `public_key` | – | Anikeen ID's public key (PEM; `\n` escapes allowed) |
+| `public_key_path` | – | path to that key; without both the key shipped for the `mode` is used |
+| `user_id_column` | `anikeen_id` | column holding the user's Anikeen ID |
+| `verify_revocation` | `false` | also ask Anikeen ID (`GET v1/user`) whether the token is still valid, so revoked tokens stop working before they expire; fails closed when Anikeen ID is unreachable |
+| `revocation_cache_ttl` | `300` | seconds that answer is cached per token |
+
+The key is read once per process. In tests `AnikeenId::actingAs($user, ['user'])` signs in without a token.
+
 ## General
 
 #### Setters and Getters

oauth-public.staging.key

@@ -1,14 +1,14 @@
 -----BEGIN PUBLIC KEY-----
-MIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEAi4Ta8r01zKaGSnGi1EiD
+MIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEArGn4rtfKjlLtJsh61eW/
-uMFWRXBlK4y/ZIfWBpElmS2ygv4mGeP3hT4Flm696Z2UMy56KC+c7CC/PQCiutLk
+cZdLC6ECbSUKVTZlLLvRoYr7Li6RKRDiIj7KEy+lRL4miiMtadXNx6d89KZwr8SL
-5NUphyX/t+0QS5Dqpw6FB33fLTNNY7GqSmGIUE4os8XYZRSyDQRgtOgq3R3vJkoV
+DQXDbP//F3HEXVJBtr6j8p8HbJh1pinLJeKtcmeJfOIwVLyQ3sPdewkQoFtwkQyF
-7zoavTJmSCQlG5Qf0T//iMmzQ+b+6VZm1CJSz5nGx94u1DuXNyP5Epkk0wuHrtwy
+uZWLeh6TCfAtcQs49I6C0rYgLDQrfTzvQ195mX1HkgArndNDXBiECMYCCulmPpzv
-kADR2lmydNodJzqpSD+8yQqnAhOZNtNF4qwQ3g13fRvHycBp3G2nlCfOn2g5PmYD
+yq5MWS5+/uQjKmPToo5lPfKxbWD6lyLII9ZkGp7wFilSonpUN1LmwRJlgQqh+1Hb
-KYBKqvTq4PQH4E+K3pbbMz6zf/T6Dw7zTfksqHR4hqMgN6byRRxmwuBczIumcu9b
+celGHTIXiP3lDNIG3sR/H5v6vwGeqfu9MBQ2Ksrz259O1aojqRQ+d9k1dj8pcbuC
-y7xbgoIGIVZXgJliALPFi+zTPTN7c8MedFs/xCBHCmzWYTCZfHgr8RPRewD19tCG
+ZurlI4++JOsmecc4B3g8tvlsevlb0UbtW/JHKckgK/JL9PO+04WJD+hSJrEhokLq
-NSny5R0vlArpuZCTTgedPESDeGU4eNEddg4yXFzKlpE2nNuvzZ1Ohruc5ETOSU19
+aB5Ceg6FKwqoM0l7dtoHRka8vh/q/UU3oawUESoZ5l3TjWI4b0jZzsJqE4cyKgK3
-RTCBUBkjeL6ESZRd/yKGjbVx4dEYxZdIz4yBl+hZ2ZOIyG7L3zPrccAWrPpG56xr
+S3tBooj4rM4dOh4y7crD1PcsJG/IF2bg4YEAO8q8Fz6TmOzCM20oBhaLrFJOnYph
-E5IDBXxLFhaJ5LlyEAGQehB0ShEuCdkr88Xz7ba9PHpGqY83l4//ULrqPIZPAa4Z
+Xhhl7ZPHqCCIt6HSDbwlFJw1Iw/2nygnkAZ0iJV/EQl0M+zlDGEv41SWHQfsLTK6
-E3AWHT1ZtXNPeA4SzZ9Y9Oij4M3chyHxqM0lL3kYP+dstZehTujStfElDIx2Ni10
+HBSM1QSEbuMz0sF/TpolYEvYso+nCDjDzQ4MFdhGxH6OVyuSySm6nG0fK/Bio5Ow
-73tILu4edYS0FxsL19m8gbsCAwEAAQ==
+6SNz0wIg3RagjzTbljHsT4cCAwEAAQ==
 -----END PUBLIC KEY-----

src/Id/Auth/TokenGuard.php

@@ -9,38 +9,39 @@ use Exception;
 use Firebase\JWT\JWT;
 use Firebase\JWT\Key;
 use Illuminate\Auth\AuthenticationException;
-use Illuminate\Auth\GuardHelpers;
+use Illuminate\Contracts\Auth\Authenticatable;
-use Illuminate\Container\Container;
-use Illuminate\Contracts\Container\BindingResolutionException;
-use Illuminate\Contracts\Debug\ExceptionHandler;
 use Illuminate\Contracts\Encryption\Encrypter;
 use Illuminate\Cookie\CookieValuePrefix;
 use Illuminate\Cookie\Middleware\EncryptCookies;
-use Illuminate\Foundation\Auth\User as Authenticatable;
 use Illuminate\Http\Request;
+use Illuminate\Support\Facades\Cache;
 use stdClass;
 use Throwable;
 
+/**
+ * Resolves the user of a request from an Anikeen ID access token (JWT, "Authorization: Bearer …")
+ * or from the encrypted token cookie of CreateFreshApiToken.
+ *
+ * A bearer token is verified with the JwtParser (signature, expiry). Its `sub` is the user's
+ * Anikeen ID, looked up by the provider (AnikeenIdUserProvider::retrieveByAnikeenId(), column
+ * `anikeen_id` by default). The token is attached to the user: `$user->anikeenTokenCan('scope')`.
+ *
+ * With `services.anikeen.verify_revocation` the token is also checked against Anikeen ID
+ * (GET v1/user, cached per token for `services.anikeen.revocation_cache_ttl` seconds), so
+ * revoked tokens stop working before they expire.
+ */
 class TokenGuard
 {
-    use GuardHelpers;
+    public function __construct(
-
+        protected UserProvider $provider,
-    private Encrypter $encrypter;
+        private Encrypter $encrypter,
-
+        private JwtParser $jwtParser
-    private JwtParser $jwtParser;
+    ) {
-
+        //
-    public function __construct(UserProvider $provider, Encrypter $encrypter, JwtParser $jwtParser)
-    {
-        $this->provider = $provider;
-        $this->encrypter = $encrypter;
-        $this->jwtParser = $jwtParser;
     }
 
     /**
      * Get the user for the incoming request.
-     *
-     * @throws BindingResolutionException
-     * @throws Throwable
      */
     public function user(Request $request): ?Authenticatable
     {
@@ -55,9 +56,6 @@ class TokenGuard
 
     /**
      * Authenticate the incoming request via the Bearer token.
-     *
-     * @throws BindingResolutionException
-     * @throws Throwable
      */
     protected function authenticateViaBearerToken(Request $request): ?Authenticatable
     {
@@ -65,51 +63,97 @@ class TokenGuard
             return null;
         }
 
-        // If the access token is valid we will retrieve the user according to the user ID
+        // client credentials tokens have no user
-        // associated with the token. We will use the provider implementation which may
+        if (!is_scalar($token->sub ?? null) || (string) $token->sub === '') {
-        // be used to retrieve users from Eloquent. Next, we'll be ready to continue.
+            return null;
-        /** @var Authenticatable|HasAnikeenTokens $user */
+        }
-        $user = $this->provider->retrieveById(
-            $request->attributes->get('oauth_user_id') ?: null
-        );
 
-        return $user?->withAnikeenAccessToken($token);
+        if (!$this->tokenIsActive($token, (string) $request->bearerToken())) {
+            return null;
+        }
 
+        /** @var Authenticatable|HasAnikeenTokens|null $user */
+        $user = $this->retrieveUser((string) $token->sub);
+
+        return $user && method_exists($user, 'withAnikeenAccessToken')
+            ? $user->withAnikeenAccessToken($token)
+            : $user;
     }
 
     /**
-     * Authenticate and get the incoming request via the Bearer token.
+     * Verify the Bearer token and expose its claims as request attributes.
-     *
-     * @throws BindingResolutionException
-     * @throws Throwable
      */
     protected function validateRequestViaBearerToken(Request $request): ?stdClass
     {
         try {
             $decoded = $this->jwtParser->decode($request);
+        } catch (AuthenticationException) {
+            return null;
+        }
 
-            $request->attributes->set('oauth_access_token_id', $decoded->jti);
+        $decoded->scopes = array_values(array_filter((array) ($decoded->scopes ?? []), 'is_string'));
-            $request->attributes->set('oauth_client_id', $decoded->aud);
+
-            $request->attributes->set('oauth_client_trusted', $decoded->client->trusted);
+        $request->attributes->set('oauth_access_token_id', $decoded->jti ?? null);
-            $request->attributes->set('oauth_user_id', $decoded->sub);
+        $request->attributes->set('oauth_client_id', $decoded->aud ?? null);
+        $request->attributes->set('oauth_client_trusted', $decoded->client->trusted ?? null);
+        $request->attributes->set('oauth_user_id', $decoded->sub ?? null);
         $request->attributes->set('oauth_scopes', $decoded->scopes);
 
         return $decoded;
-        } catch (AuthenticationException $e) {
-            $request->headers->set('Authorization', '', true);
-
-            Container::getInstance()->make(
-                ExceptionHandler::class
-            )->report($e);
-
-            return null;
     }
+
+    /**
+     * Whether Anikeen ID still accepts the token (only with services.anikeen.verify_revocation).
+     */
+    protected function tokenIsActive(stdClass $token, string $jwt): bool
+    {
+        if (!config('services.anikeen.verify_revocation')) {
+            return true;
+        }
+
+        $key = 'anikeen-id:token-active:' . hash('sha256', $jwt);
+
+        if (($cached = Cache::get($key)) !== null) {
+            return (bool) $cached;
+        }
+
+        try {
+            $result = (clone app(AnikeenId::class))->withToken($jwt)->getAuthedUser();
+        } catch (Throwable) {
+            return false; // Anikeen ID unreachable: fail closed, ask again next time
+        }
+
+        $status = $result->response?->getStatusCode();
+
+        if ($result->success()) {
+            $active = true;
+        } elseif (in_array($status, [401, 403], true)) {
+            $active = false;
+        } else {
+            return false; // server error: fail closed without caching
+        }
+
+        $ttl = (int) config('services.anikeen.revocation_cache_ttl', 300);
+        if (isset($token->exp)) {
+            $ttl = max(1, min($ttl, (int) $token->exp - time()));
+        }
+        Cache::put($key, $active, $ttl);
+
+        return $active;
+    }
+
+    /**
+     * Find the local user of an Anikeen ID.
+     */
+    protected function retrieveUser(string $anikeenId): ?Authenticatable
+    {
+        return $this->provider->retrieveByAnikeenId($anikeenId);
     }
 
     /**
      * Authenticate the incoming request via the token cookie.
      */
-    protected function authenticateViaCookie(Request $request): mixed
+    protected function authenticateViaCookie(Request $request): ?Authenticatable
     {
         if (!$token = $this->getTokenViaCookie($request)) {
             return null;
@@ -118,9 +162,11 @@ class TokenGuard
         // If this user exists, we will return this user and attach a "transient" token to
         // the user model. The transient token assumes it has all scopes since the user
         // is physically logged into the application via the application's interface.
-        /** @var Authenticatable|HasAnikeenTokens $user */
+        /** @var Authenticatable|HasAnikeenTokens|null $user */
-        if ($user = $this->provider->retrieveById($token['sub'])) {
+        if ($user = $this->retrieveUser((string) $token['sub'])) {
-            return $user->withAnikeenAccessToken((object)['scopes' => ['*']]);
+            return method_exists($user, 'withAnikeenAccessToken')
+                ? $user->withAnikeenAccessToken((object) ['scopes' => ['*']])
+                : $user;
         }
 
         return null;
@@ -136,15 +182,18 @@ class TokenGuard
         // database. If we can't decrypt the value we'll bail out with a null return.
         try {
             $token = $this->decodeJwtTokenCookie($request);
-        } catch (Exception $e) {
+        } catch (Exception) {
+            return null;
+        }
+
+        if (!isset($token['sub'], $token['expiry'])) {
             return null;
         }
 
         // We will compare the CSRF token in the decoded API token against the CSRF header
         // sent with the request. If they don't match then this request isn't sent from
         // a valid source and we won't authenticate the request for further handling.
-        if (!AnikeenId::$ignoreCsrfToken && (!$this->validCsrf($token, $request) ||
+        if (time() >= $token['expiry'] || (!AnikeenId::$ignoreCsrfToken && !$this->validCsrf($token, $request))) {
-                time() >= $token['expiry'])) {
             return null;
         }
 
@@ -156,7 +205,7 @@ class TokenGuard
      */
     protected function decodeJwtTokenCookie(Request $request): array
     {
-        return (array)JWT::decode(
+        return (array) JWT::decode(
             CookieValuePrefix::remove($this->encrypter->decrypt($request->cookie(AnikeenId::cookie()), AnikeenId::$unserializesCookies)),
             new Key(
                 $this->encrypter->getKey(),
@@ -186,7 +235,7 @@ class TokenGuard
             $token = CookieValuePrefix::remove($this->encrypter->decrypt($header, static::serialized()));
         }
 
-        return $token;
+        return (string) $token;
     }
 
     /**

src/Id/Auth/UserProvider.php

@@ -2,6 +2,7 @@
 
 namespace Anikeen\Id\Auth;
 
+use Anikeen\Id\AnikeenId;
 use Illuminate\Contracts\Auth\Authenticatable;
 use Illuminate\Contracts\Auth\UserProvider as Base;
 
@@ -10,11 +11,33 @@ class UserProvider implements Base
     /**
      * Create a new AnikeenId user provider.
      */
-    public function __construct(protected Base $provider, protected string $providerName)
+    public function __construct(protected Base $provider, protected string $providerName, protected ?string $column = null)
     {
         //
     }
 
+    /**
+     * The column that holds a user's Anikeen ID: the provider's `column`, else
+     * `services.anikeen.user_id_column`, else AnikeenId::getUserIdField() (`anikeen_id`).
+     */
+    public function column(): string
+    {
+        return $this->column ?: (config('services.anikeen.user_id_column') ?: AnikeenId::getUserIdField());
+    }
+
+    /**
+     * Find the user of an Anikeen ID (the `sub` of an access token).
+     */
+    public function retrieveByAnikeenId(string $anikeenId): ?Authenticatable
+    {
+        if (method_exists($this->provider, 'retrieveByAnikeenId')) {
+            return $this->provider->retrieveByAnikeenId($anikeenId);
+        }
+
+        // eloquent / database providers: a plain where on the column
+        return $this->provider->retrieveByCredentials([$this->column() => $anikeenId]);
+    }
+
     /**
      * {@inheritdoc}
      */
@@ -65,6 +88,6 @@ class UserProvider implements Base
 
     public function rehashPasswordIfRequired(Authenticatable $user, #[\SensitiveParameter] array $credentials, bool $force = false)
     {
-        // TODO: Implement rehashPasswordIfRequired() method.
+        $this->provider->rehashPasswordIfRequired($user, $credentials, $force);
     }
 }

src/Id/Concerns/IsCheckoutSession.php

@@ -0,0 +1,50 @@
+<?php
+
+namespace Anikeen\Id\Concerns;
+
+/**
+ * Reading a checkout session (see AppCheckoutSession and CheckoutSession).
+ */
+trait IsCheckoutSession
+{
+    /**
+     * Where the user confirms (or cancels) all of the session's subscriptions, or null once the
+     * session is no longer open. The user then returns to the session's `return_url` with
+     * `status` (completed or cancelled when confirming or cancelling; expired only from the
+     * "back to app" link of a session that had expired) and `checkout_session` (the id). Check the
+     * status through the API or the checkout.* webhooks; don't trust the query string.
+     */
+    public function confirmationUrl(): ?string
+    {
+        return $this->confirmation_url ?: null;
+    }
+
+    public function isOpen(): bool
+    {
+        return $this->status === self::STATUS_OPEN;
+    }
+
+    /**
+     * Confirmed: all of its subscriptions are running.
+     */
+    public function isCompleted(): bool
+    {
+        return $this->status === self::STATUS_COMPLETED;
+    }
+
+    /**
+     * Cancelled or expired: all of its drafts were cancelled.
+     */
+    public function isCancelled(): bool
+    {
+        return in_array($this->status, [self::STATUS_CANCELLED, self::STATUS_EXPIRED], true);
+    }
+
+    /**
+     * @return list<string>
+     */
+    public function subscriptionIds(): array
+    {
+        return array_values((array) ($this->subscription_ids ?? []));
+    }
+}

src/Id/Concerns/ManagesSubscriptions.php

@@ -2,8 +2,10 @@
 
 namespace Anikeen\Id\Concerns;
 
+use Anikeen\Id\Resources\AppCheckoutSessions;
 use Anikeen\Id\Resources\AppOrders;
 use Anikeen\Id\Resources\AppSubscriptions;
+use Anikeen\Id\Resources\CheckoutSessions;
 use Anikeen\Id\Resources\Subscriptions;
 use Throwable;
 
@@ -37,6 +39,24 @@ trait ManagesSubscriptions
         return new AppSubscriptions($this);
     }
 
+    /**
+     * Checkout sessions for the user, created with the app's own token (trusted apps only, scope
+     * subscriptions:client): the user confirms several subscriptions at once on Anikeen ID.
+     */
+    public function appCheckoutSessions(): AppCheckoutSessions
+    {
+        return new AppCheckoutSessions($this);
+    }
+
+    /**
+     * Checkout sessions with the user's own access token (any app): the user confirms several
+     * subscriptions at once on Anikeen ID.
+     */
+    public function checkoutSessions(): CheckoutSessions
+    {
+        return new CheckoutSessions($this);
+    }
+
     /**
      * The user's orders that bill the app's subscriptions, read with the app's own token
      * (trusted apps only, scope orders:client), e.g. ->pending() for unpaid ones.

src/Id/Concerns/ManagesUserBilling.php

@@ -2,6 +2,7 @@
 
 namespace Anikeen\Id\Concerns;
 
+use Anikeen\Id\Resources\AppCheckoutSessions;
 use Anikeen\Id\Resources\AppOrders;
 use Anikeen\Id\Result;
 use Throwable;
@@ -19,6 +20,15 @@ trait ManagesUserBilling
         return new AppOrders();
     }
 
+    /**
+     * Checkout sessions of the app for any user, e.g. to look one up from a checkout.* webhook
+     * (create() then needs a user_id).
+     */
+    public function appCheckoutSessions(): AppCheckoutSessions
+    {
+        return new AppCheckoutSessions();
+    }
+
     /**
      * Create an order for a user (VAT from the billing address). With `checkout`, it is paid right
      * away: with the given `transaction` (a payment captured elsewhere) or by charging the user's

src/Id/HasAnikeenTokens.php

@@ -26,9 +26,23 @@ trait HasAnikeenTokens
      */
     public function anikeenTokenCan(string $scope): bool
     {
-        $scopes = $this->accessToken ? $this->accessToken->scopes : [];
+        $scopes = (array) ($this->accessToken->scopes ?? []);
 
-        return in_array('*', $scopes) || in_array($scope, $this->accessToken->scopes);
+        return in_array('*', $scopes, true) || in_array($scope, $scopes, true);
+    }
+
+    /**
+     * Determine if the current API token has any of the given scopes.
+     */
+    public function anikeenTokenCanAny(array $scopes): bool
+    {
+        foreach ($scopes as $scope) {
+            if ($this->anikeenTokenCan($scope)) {
+                return true;
+            }
+        }
+
+        return false;
     }
 
     /**

src/Id/Helpers/JwtParser.php

@@ -7,32 +7,74 @@ use Firebase\JWT\JWT;
 use Firebase\JWT\Key;
 use Illuminate\Auth\AuthenticationException;
 use Illuminate\Http\Request;
+use RuntimeException;
 use stdClass;
 use Throwable;
 
+/**
+ * Verifies access tokens issued by Anikeen ID (Passport, RS256): signature against
+ * Anikeen ID's public key plus the time claims (exp, nbf, iat; 60 seconds leeway).
+ *
+ * The key is `services.anikeen.public_key` (PEM, "\n" escapes allowed) or the file at
+ * `services.anikeen.public_key_path`, else the key shipped with this package for the
+ * configured mode (production / staging). It is read once per process.
+ */
 class JwtParser
 {
+    /**
+     * Public keys already read, by source.
+     *
+     * @var array<string, string>
+     */
+    private static array $keys = [];
+
     /**
      * @throws AuthenticationException
      */
     public function decode(Request $request): stdClass
     {
+        return $this->decodeToken((string) $request->bearerToken());
+    }
+
+    /**
+     * @throws AuthenticationException
+     */
+    public function decodeToken(string $token): stdClass
+    {
+        if ($token === '') {
+            throw new AuthenticationException('No access token given.');
+        }
+
         JWT::$leeway = 60;
 
+        // outside the try: a missing key is a configuration error, not an invalid token
+        $key = new Key($this->getOauthPublicKey(), 'RS256');
+
         try {
-            return JWT::decode(
+            return JWT::decode($token, $key);
-                $request->bearerToken(),
+        } catch (Throwable) {
-                new Key($this->getOauthPublicKey(), 'RS256')
+            throw new AuthenticationException('The access token is invalid or expired.');
-            );
-        } catch (Throwable $exception) {
-            throw (new AuthenticationException());
         }
     }
 
-    private function getOauthPublicKey(): bool|string
+    /**
+     * Forget the keys read so far (e.g. after changing the configuration in tests).
+     */
+    public static function flushKeys(): void
     {
-        return AnikeenId::getMode() === 'staging'
+        self::$keys = [];
-            ? file_get_contents(dirname(__DIR__, 3) . '/oauth-public.staging.key')
+    }
-            : file_get_contents(dirname(__DIR__, 3) . '/oauth-public.key');
+
+    protected function getOauthPublicKey(): string
+    {
+        if ($key = config('services.anikeen.public_key')) {
+            return self::$keys['config:' . md5($key)] ??= str_replace('\\n', "\n", $key);
+        }
+
+        $path = config('services.anikeen.public_key_path') ?: (AnikeenId::getMode() === 'staging'
+            ? dirname(__DIR__, 3) . '/oauth-public.staging.key'
+            : dirname(__DIR__, 3) . '/oauth-public.key');
+
+        return self::$keys['file:' . $path] ??= (is_readable($path) ? (string) file_get_contents($path) : throw new RuntimeException("Anikeen ID public key [$path] is not readable."));
     }
 }

src/Id/Http/Middleware/CheckForAnyScope.php

@@ -6,7 +6,7 @@ use Anikeen\Id\Exceptions\MissingScopeException;
 use Closure;
 use Illuminate\Auth\AuthenticationException;
 use Illuminate\Http\Request;
-use Illuminate\Http\Response;
+use Symfony\Component\HttpFoundation\Response;
 
 class CheckForAnyScope extends UseParameters
 {
@@ -17,7 +17,7 @@ class CheckForAnyScope extends UseParameters
      */
     public function handle(Request $request, Closure $next, ...$scopes): Response
     {
-        if (!$request->user() || !$request->user()->anikeenToken()) {
+        if (!$request->user() || !method_exists($request->user(), 'anikeenToken') || !$request->user()->anikeenToken()) {
             throw new AuthenticationException;
         }
 

src/Id/Http/Middleware/CheckScopes.php

@@ -6,7 +6,7 @@ use Anikeen\Id\Exceptions\MissingScopeException;
 use Closure;
 use Illuminate\Auth\AuthenticationException;
 use Illuminate\Http\Request;
-use Illuminate\Http\Response;
+use Symfony\Component\HttpFoundation\Response;
 
 class CheckScopes extends UseParameters
 {
@@ -17,7 +17,7 @@ class CheckScopes extends UseParameters
      */
     public function handle(Request $request, Closure $next, ...$scopes): Response
     {
-        if (!$request->user() || !$request->user()->anikeenToken()) {
+        if (!$request->user() || !method_exists($request->user(), 'anikeenToken') || !$request->user()->anikeenToken()) {
             throw new AuthenticationException;
         }
 

src/Id/Providers/AnikeenIdServiceProvider.php

@@ -8,8 +8,11 @@ use Anikeen\Id\Auth\UserProvider;
 use Anikeen\Id\Contracts;
 use Anikeen\Id\Helpers\JwtParser;
 use Anikeen\Id\Repository;
+use Illuminate\Auth\AuthManager;
 use Illuminate\Auth\RequestGuard;
-use Illuminate\Support\Facades\Auth;
+use Illuminate\Contracts\Foundation\Application;
+use Illuminate\Http\Request;
+use InvalidArgumentException;
 use Illuminate\Support\ServiceProvider;
 
 class AnikeenIdServiceProvider extends ServiceProvider
@@ -38,15 +41,28 @@ class AnikeenIdServiceProvider extends ServiceProvider
     }
 
     /**
-     * Register the token guard.
+     * Register the `anikeen` guard driver and user provider.
+     *
+     * Laravel binds non-static extend() closures to the AuthManager, so these closures are
+     * static and use nothing but their arguments.
      */
     protected function registerGuard(): void
     {
-        Auth::resolved(function ($auth) {
+        $this->callAfterResolving('auth', static function (AuthManager $auth): void {
-            $auth->extend('anikeen', function ($app, $name, array $config) {
+            $auth->provider('anikeen', static fn (Application $app, array $config) => new AnikeenIdUserProvider(
-                return tap($this->makeGuard($config), function ($guard) {
+                $app->make(AnikeenId::class),
-                    $this->app->refresh('request', $guard, 'setRequest');
+                $app->make('request'),
-                });
+                $config['model'] ?? $app['config']->get('auth.providers.users.model'),
+                $config['fields'] ?? [],
+                $config['column'] ?? null,
+            ));
+
+            $auth->extend('anikeen', static function (Application $app, string $name, array $config): RequestGuard {
+                $guard = AnikeenIdServiceProvider::makeGuard($app, $config);
+
+                $app->refresh('request', $guard, 'setRequest');
+
+                return $guard;
             });
         });
     }
@@ -54,15 +70,20 @@ class AnikeenIdServiceProvider extends ServiceProvider
     /**
      * Make an instance of the token guard.
      */
-    protected function makeGuard(array $config): RequestGuard
+    public static function makeGuard(Application $app, array $config): RequestGuard
     {
-        return new RequestGuard(function ($request) use ($config) {
+        $providerName = $config['provider'] ?? $app['config']->get('auth.defaults.provider', 'users');
+        $provider = $app['auth']->createUserProvider($providerName)
+            ?? throw new InvalidArgumentException("Authentication user provider [$providerName] is not configured.");
+        $providerConfig = $app['config']->get("auth.providers.$providerName", []);
+
+        return new RequestGuard(static function (Request $request) use ($app, $provider, $providerName, $providerConfig, $config) {
             return (new TokenGuard(
-                new UserProvider(Auth::createUserProvider($config['provider']), $config['provider']),
+                new UserProvider($provider, $providerName, $config['column'] ?? $providerConfig['column'] ?? null),
-                $this->app->make('encrypter'),
+                $app->make('encrypter'),
-                $this->app->make(JwtParser::class)
+                $app->make(JwtParser::class)
             ))->user($request);
-        }, $this->app['request']);
+        }, $app['request'], $provider);
     }
 
     /**

src/Id/Providers/AnikeenIdUserProvider.php

@@ -18,7 +18,8 @@ class AnikeenIdUserProvider implements UserProvider
         private AnikeenId $anikeenId,
         private Request   $request,
         private string    $model,
-        private array     $fields = []
+        private array     $fields = [],
+        private ?string   $column = null,
     ) {
         $this->accessTokenField = AnikeenId::getAccessTokenField();
     }
@@ -97,6 +98,17 @@ class AnikeenIdUserProvider implements UserProvider
             ->first();
     }
 
+    /**
+     * Find the user of an Anikeen ID (the `sub` of an access token) by the provider's `column`,
+     * else `services.anikeen.user_id_column`, else AnikeenId::getUserIdField() (`anikeen_id`).
+     */
+    public function retrieveByAnikeenId(string $anikeenId): ?Authenticatable
+    {
+        $column = $this->column ?: (config('services.anikeen.user_id_column') ?: AnikeenId::getUserIdField());
+
+        return $this->newModelQuery()->where($column, $anikeenId)->first();
+    }
+
     /**
      * {@inheritDoc}
      */

src/Id/Resources/AppCheckoutSession.php

@@ -0,0 +1,97 @@
+<?php
+
+namespace Anikeen\Id\Resources;
+
+use Anikeen\Id\Concerns\IsCheckoutSession;
+use Anikeen\Id\Exceptions\ApiException;
+use Anikeen\Id\Support\AppRequest;
+use JsonSerializable;
+
+/**
+ * A checkout session created with the app's own token, see AppCheckoutSessions.
+ *
+ * @property string $id
+ * @property string $user_id
+ * @property ?string $oauth_client_id
+ * @property string $status open, completed, cancelled or expired
+ * @property ?string $return_url
+ * @property ?object $metadata
+ * @property ?string $confirmation_url
+ * @property list<string> $subscription_ids
+ * @property list<object> $subscriptions
+ * @property ?string $expires_at
+ * @property ?string $completed_at
+ * @property ?string $cancelled_at
+ * @property ?string $created_at
+ */
+class AppCheckoutSession implements JsonSerializable
+{
+    use IsCheckoutSession;
+
+    public const STATUS_OPEN = 'open';
+    public const STATUS_COMPLETED = 'completed';
+    public const STATUS_CANCELLED = 'cancelled';
+    public const STATUS_EXPIRED = 'expired';
+
+    public function __construct(protected object $data)
+    {
+    }
+
+    public function __get(string $name): mixed
+    {
+        return $this->data->{$name} ?? null;
+    }
+
+    public function __isset(string $name): bool
+    {
+        return isset($this->data->{$name});
+    }
+
+    /**
+     * The session's subscriptions (drafts until the user confirms).
+     *
+     * @return list<AppSubscription>
+     */
+    public function subscriptions(): array
+    {
+        return array_map(fn (object $subscription) => new AppSubscription($subscription), array_values((array) ($this->data->subscriptions ?? [])));
+    }
+
+    /**
+     * Withdraw an open session (e.g. the cart changed): it and its drafts are cancelled.
+     *
+     * @throws ApiException 409 "checkout_session_completed", "checkout_session_cancelled", "checkout_session_expired"
+     */
+    public function cancel(): self
+    {
+        return $this->send('POST', '/cancel');
+    }
+
+    /**
+     * @throws ApiException
+     */
+    public function refresh(): self
+    {
+        return $this->send('GET', '');
+    }
+
+    public function toArray(): array
+    {
+        return (array) $this->data;
+    }
+
+    public function jsonSerialize(): array
+    {
+        return $this->toArray();
+    }
+
+    /**
+     * @throws ApiException
+     */
+    private function send(string $method, string $action): self
+    {
+        $this->data = AppRequest::send($method, sprintf('v1/client/checkout-sessions/%s%s', $this->id, $action))->data;
+
+        return $this;
+    }
+}

src/Id/Resources/AppCheckoutSessions.php

@@ -0,0 +1,81 @@
+<?php
+
+namespace Anikeen\Id\Resources;
+
+use Anikeen\Id\Contracts\Billable;
+use Anikeen\Id\Exceptions\ApiException;
+use Anikeen\Id\Support\AppRequest;
+use Illuminate\Database\Eloquent\Model;
+use InvalidArgumentException;
+
+/**
+ * Checkout sessions created with the app's own token (trusted apps, scope `subscriptions:client`):
+ * several subscriptions of one user that the user confirms together on Anikeen ID, instead of the
+ * app checking them out itself. For one user ($user->appCheckoutSessions()) or, to look sessions
+ * up e.g. from a webhook, for all users (app(AnikeenId::class)->appCheckoutSessions()).
+ * Nothing is requested until a method is called.
+ */
+class AppCheckoutSessions
+{
+    public function __construct(protected Billable|Model|null $billable = null)
+    {
+    }
+
+    /**
+     * Open a checkout session with new subscriptions (their attributes, like
+     * AppSubscriptions::create()) and/or existing drafts of the app (`['id' => …]`).
+     *
+     * @param array{
+     *     subscriptions: list<array{id: string}|array{
+     *         group?: null|string,
+     *         name: string,
+     *         description?: null|string,
+     *         unit: string,
+     *         price: float|string,
+     *         monthly_cap?: null|float|string,
+     *         predecessor_id?: null|string,
+     *         vat_rate?: float,
+     *         payload?: null|array,
+     *         ends_at?: null|string
+     *     }>,
+     *     return_url?: null|string,
+     *     metadata?: null|array,
+     *     idempotency_key?: null|string,
+     *     user_id?: string
+     * } $attributes return_url must share scheme, host and port with one of the app's redirect
+     *               URIs; the user comes back to it with `status` and `checkout_session`. A
+     *               repeated idempotency_key returns the first session instead of a new one.
+     *
+     * @throws ApiException 422 validation (e.g. return_url), 409 "idempotency_key_conflict"
+     */
+    public function create(array $attributes): AppCheckoutSession
+    {
+        if ($this->billable) {
+            $attributes['user_id'] = (new AppSubscriptions($this->billable))->userId();
+        } elseif (empty($attributes['user_id'])) {
+            throw new InvalidArgumentException('A checkout session needs a user: use $user->appCheckoutSessions() or pass user_id.');
+        }
+
+        return new AppCheckoutSession(AppRequest::send('POST', 'v1/client/checkout-sessions', $attributes)->data);
+    }
+
+    /**
+     * A session of the app; null when it doesn't exist (or belongs to another user).
+     *
+     * @throws ApiException
+     */
+    public function find(string $id): ?AppCheckoutSession
+    {
+        try {
+            $session = new AppCheckoutSession(AppRequest::send('GET', sprintf('v1/client/checkout-sessions/%s', $id))->data);
+        } catch (ApiException $e) {
+            if ($e->isNotFound()) {
+                return null;
+            }
+
+            throw $e;
+        }
+
+        return !$this->billable || $session->user_id === (new AppSubscriptions($this->billable))->userId() ? $session : null;
+    }
+}

src/Id/Resources/AppSubscription.php

@@ -17,6 +17,9 @@ use JsonSerializable;
  * @property ?string $description
  * @property string $unit
  * @property float $price
+ * @property ?float $monthly_cap net, at most this per calendar month (hour and day units)
+ * @property ?float $expected_monthly_price gross estimate for a month (720 hours, at most the monthly cap)
+ * @property ?string $predecessor_id the subscription this one replaced (a resize); they share the monthly cap
  * @property ?float $vat_rate
  * @property bool $active
  * @property bool $autorenew
@@ -29,6 +32,7 @@ use JsonSerializable;
  * @property int $failed_renewal_retries
  * @property ?array $payload
  * @property ?string $idempotency_key
+ * @property ?string $checkout_session_id the checkout session the user confirms it in, if any
  */
 class AppSubscription implements JsonSerializable
 {

src/Id/Resources/AppSubscriptions.php

@@ -44,12 +44,18 @@ class AppSubscriptions
      *     description?: null|string,
      *     unit: string,
      *     price: float|string,
+     *     monthly_cap?: null|float|string,
+     *     predecessor_id?: null|string,
      *     vat_rate?: float,
      *     payload?: null|array,
      *     ends_at?: null|string,
      *     idempotency_key?: null|string
      * } $attributes With an idempotency_key (max. 191 characters), a retried call returns the
      *               subscription created by the first one instead of a duplicate.
+     *               monthly_cap: net, at most this per calendar month (hour and day units only,
+     *               at most 2 decimals, not below price; null = no cap).
+     *               predecessor_id: the subscription this one replaces (a resize; same user and
+     *               app, checked out, not cancelled): both share the monthly cap within a month.
      *
      * @throws ApiException
      */

src/Id/Resources/CheckoutSession.php

@@ -0,0 +1,57 @@
+<?php
+
+namespace Anikeen\Id\Resources;
+
+use Anikeen\Id\Concerns\HasBillable;
+use Anikeen\Id\Concerns\IsCheckoutSession;
+use Throwable;
+
+/**
+ * A checkout session created with the user's access token, see CheckoutSessions.
+ *
+ * @property string $id
+ * @property string $user_id
+ * @property ?string $oauth_client_id
+ * @property string $status open, completed, cancelled or expired
+ * @property ?string $return_url
+ * @property ?object $metadata
+ * @property ?string $confirmation_url
+ * @property list<string> $subscription_ids
+ * @property list<object> $subscriptions
+ * @property ?string $expires_at
+ * @property ?string $completed_at
+ * @property ?string $cancelled_at
+ * @property ?string $created_at
+ */
+class CheckoutSession extends BaseResource
+{
+    use HasBillable;
+    use IsCheckoutSession;
+
+    public const STATUS_OPEN = 'open';
+    public const STATUS_COMPLETED = 'completed';
+    public const STATUS_CANCELLED = 'cancelled';
+    public const STATUS_EXPIRED = 'expired';
+
+    /**
+     * Withdraw an open session: it and its drafts are cancelled.
+     *
+     * @throws Throwable
+     */
+    public function cancel(): self
+    {
+        return (new self(fn () => $this->billable->anikeenId()
+            ->request('POST', sprintf('v1/checkout-sessions/%s/cancel', $this->id))))
+            ->setBillable($this->billable);
+    }
+
+    /**
+     * @throws Throwable
+     */
+    public function refresh(): self
+    {
+        return (new self(fn () => $this->billable->anikeenId()
+            ->request('GET', sprintf('v1/checkout-sessions/%s', $this->id))))
+            ->setBillable($this->billable);
+    }
+}

src/Id/Resources/CheckoutSessions.php

@@ -0,0 +1,58 @@
+<?php
+
+namespace Anikeen\Id\Resources;
+
+use Anikeen\Id\Concerns\HasBillable;
+use Anikeen\Id\Contracts\Billable;
+use Anikeen\Id\Exceptions\ResourceException;
+use Illuminate\Database\Eloquent\Model;
+use Throwable;
+
+/**
+ * Checkout sessions of the signed-in user, with the user's access token (any app): several
+ * subscriptions the user confirms together on Anikeen ID. Nothing is requested until a method is
+ * called.
+ */
+class CheckoutSessions
+{
+    use HasBillable;
+
+    public function __construct(Billable|Model $billable)
+    {
+        $this->billable = $billable;
+    }
+
+    /**
+     * Open a checkout session with new subscriptions and/or existing drafts of the app
+     * (`['id' => …]`); see AppCheckoutSessions::create() for the attributes (no user_id here,
+     * vat_rate only for trusted apps).
+     *
+     * @throws Throwable
+     */
+    public function create(array $attributes): CheckoutSession
+    {
+        return (new CheckoutSession(fn () => $this->billable->anikeenId()
+            ->request('POST', 'v1/checkout-sessions', $attributes)))
+            ->setBillable($this->billable);
+    }
+
+    /**
+     * A session the app created for the user; null when it doesn't exist.
+     *
+     * @throws Throwable
+     */
+    public function find(string $id): ?CheckoutSession
+    {
+        try {
+            return (new CheckoutSession(fn () => $this->billable->anikeenId()
+                ->request('GET', sprintf('v1/checkout-sessions/%s', $id))))
+                ->setBillable($this->billable);
+        } catch (ResourceException $e) {
+            if ($e->getCode() === 404) {
+                return null;
+            }
+
+            throw $e;
+        }
+    }
+}

src/Id/Resources/Shipments.php

@@ -27,11 +27,14 @@ class Shipments extends BaseCollection
      *     tracking_url?: string,
      *     note?: string,
      *     shipped_at?: string,
+     *     notify_customer?: bool,
      *     items?: array<array{order_item_id: string, units?: float|int|string}>
      * } $attributes
      *   - carrier:         e.g. "DHL"
      *   - tracking_url:    http(s) link to track the parcel, shown to the user
      *   - shipped_at:      when it was sent (default: now, not in the future)
+     *   - notify_customer: Anikeen ID mails the user with the delivery note (default true);
+     *                      false if your shop sends its own mail
      *   - items:           physical items of the order and how many of them (default: all left)
      *
      * Errors (ResourceException with the HTTP status): 409 when the order isn't paid or nothing

src/Id/Resources/Subscription.php

@@ -13,6 +13,9 @@ use Throwable;
  * @property string $description
  * @property string $unit
  * @property float $price
+ * @property ?float $monthly_cap net, at most this per calendar month (hour and day units)
+ * @property ?float $expected_monthly_price gross estimate for a month (720 hours, at most the monthly cap)
+ * @property ?string $predecessor_id the subscription this one replaced (a resize); they share the monthly cap
  * @property float $vat_rate
  * @property array $payload
  * @property string $ends_at
@@ -32,6 +35,7 @@ class Subscription extends BaseResource
      *      description: null|string,
      *      unit: string,
      *      price: float,
+     *      monthly_cap?: null|float,
      *      vat_rate: float,
      *      payload: null|array,
      *      ends_at: null|string
@@ -41,6 +45,7 @@ class Subscription extends BaseResource
      *    - description:    The description (optional)
      *    - unit:           The unit (required when set, e.g. "hour", "day", "week", "month", "year")
      *    - price:          The price per unit (required when set)
+     *    - monthly_cap:    Net, at most this per calendar month (hour and day units; optional)
      *    - vat_rate:       The VAT rate (required when set)
      *    - payload:        The payload (optional)
      *    - ends_at:        The end date (optional)

src/Id/Resources/Subscriptions.php

@@ -20,6 +20,8 @@ class Subscriptions extends BaseCollection
      *      description: null|string,
      *      unit: string,
      *      price: float,
+     *      monthly_cap?: null|float,
+     *      predecessor_id?: null|string,
      *      vat_rate: float,
      *      payload: null|array,
      *      ends_at: null|string
@@ -29,6 +31,8 @@ class Subscriptions extends BaseCollection
      *    - description:    The description (optional)
      *    - unit:           The unit (e.g. "hour", "day", "week", "month", "year")
      *    - price:          The price per unit
+     *    - monthly_cap:    Net, at most this per calendar month (hour and day units, max. 2 decimals; optional)
+     *    - predecessor_id: The subscription this one replaces (a resize); both share the monthly cap (optional)
      *    - vat_rate:       The VAT rate (required when set)
      *    - payload:        The payload (optional)
      *    - ends_at:        The end date (optional)

src/Id/Webhooks/EventType.php

@@ -0,0 +1,46 @@
+<?php
+
+namespace Anikeen\Id\Webhooks;
+
+/**
+ * The `type` of webhook events Anikeen ID sends, e.g.
+ * `match ($event['type']) { EventType::CHECKOUT_COMPLETED => …, … }`.
+ */
+final class EventType
+{
+    public const ORDER_CREATED = 'order.created';
+    public const ORDER_COMPLETED = 'order.completed';
+    public const ORDER_PAYMENT_FAILED = 'order.payment_failed';
+    public const ORDER_CANCELLED = 'order.cancelled';
+    public const ORDER_SHIPPED = 'order.shipped';
+
+    public const SUBSCRIPTION_CREATED = 'subscription.created';
+    public const SUBSCRIPTION_ACTIVATED = 'subscription.activated';
+    public const SUBSCRIPTION_PAUSED = 'subscription.paused';
+    public const SUBSCRIPTION_RESUMED = 'subscription.resumed';
+    public const SUBSCRIPTION_CANCELLED = 'subscription.cancelled';
+    public const SUBSCRIPTION_EXPIRED = 'subscription.expired';
+
+    /** The user confirmed a checkout session: all of its subscriptions are running (sent after their subscription.activated). */
+    public const CHECKOUT_COMPLETED = 'checkout.completed';
+
+    /** The user or the app cancelled a checkout session; its drafts were cancelled. */
+    public const CHECKOUT_CANCELLED = 'checkout.cancelled';
+
+    /** A checkout session was not confirmed within 24 hours; its drafts were cancelled. */
+    public const CHECKOUT_EXPIRED = 'checkout.expired';
+
+    public const TEST = 'webhook.test';
+
+    /**
+     * @return list<string>
+     */
+    public static function all(): array
+    {
+        return array_values((new \ReflectionClass(self::class))->getConstants());
+    }
+
+    private function __construct()
+    {
+    }
+}

tests/Id/CheckoutSessionsTest.php

@@ -0,0 +1,163 @@
+<?php
+
+namespace Anikeen\Id\Tests;
+
+use Anikeen\Id\AnikeenId;
+use Anikeen\Id\Billable;
+use Anikeen\Id\Exceptions\ApiException;
+use Anikeen\Id\Resources\AppCheckoutSession;
+use Anikeen\Id\Resources\AppSubscription;
+use Anikeen\Id\Resources\CheckoutSession;
+use Anikeen\Id\Webhooks\EventType;
+use Anikeen\Id\Webhooks\Webhook;
+use Illuminate\Database\Eloquent\Model;
+use InvalidArgumentException;
+
+class CheckoutSessionsTest extends TestCase
+{
+    private function owner(): Model
+    {
+        $owner = new class extends Model {
+            use Billable;
+
+            protected $guarded = [];
+        };
+        $owner->anikeen_id = '01JUSER';
+        $owner->anikeen_id_access_token = 'user-token';
+
+        return $owner;
+    }
+
+    private function sessionData(array $overrides = []): array
+    {
+        return ['data' => [
+            'object' => 'checkout_session',
+            'id' => '01JCS',
+            'user_id' => '01JUSER',
+            'status' => 'open',
+            'return_url' => 'https://console.test/builder/done',
+            'metadata' => ['cart' => '42'],
+            'confirmation_url' => 'https://id.anikeen.com/checkout/sessions/01JCS',
+            'subscription_ids' => ['01JS1', '01JS2'],
+            'subscriptions' => [
+                ['id' => '01JS1', 'user_id' => '01JUSER', 'name' => 'Cloud Server S', 'active' => false, 'payload' => ['product' => 'server-s']],
+                ['id' => '01JS2', 'user_id' => '01JUSER', 'name' => 'Backup', 'active' => false],
+            ],
+            ...$overrides,
+        ]];
+    }
+
+    private function request(int $index): string
+    {
+        $request = $this->sent[$index]['request'];
+
+        return $request->getMethod() . ' ' . $request->getUri()->getPath() . ' ' . $request->getHeaderLine('Authorization');
+    }
+
+    public function test_a_trusted_app_opens_a_session_with_its_own_token(): void
+    {
+        $this->respond(201, $this->sessionData());
+
+        $session = $this->owner()->appCheckoutSessions()->create([
+            'return_url' => 'https://console.test/builder/done',
+            'idempotency_key' => 'cart:42',
+            'subscriptions' => [
+                ['group' => 'team-1', 'name' => 'Cloud Server S', 'unit' => 'hour', 'price' => '0.0137', 'payload' => ['product' => 'server-s']],
+                ['id' => '01JS2'],
+            ],
+        ]);
+
+        $this->assertSame('POST /api/v1/client/checkout-sessions Bearer app-token', $this->request(0));
+        $this->assertSame('01JUSER', $this->sentJson(0)['user_id']);
+        $this->assertSame([['group' => 'team-1', 'name' => 'Cloud Server S', 'unit' => 'hour', 'price' => '0.0137', 'payload' => ['product' => 'server-s']], ['id' => '01JS2']], $this->sentJson(0)['subscriptions']);
+
+        $this->assertInstanceOf(AppCheckoutSession::class, $session);
+        $this->assertSame('https://id.anikeen.com/checkout/sessions/01JCS', $session->confirmationUrl());
+        $this->assertTrue($session->isOpen());
+        $this->assertSame(['01JS1', '01JS2'], $session->subscriptionIds());
+        $this->assertContainsOnlyInstancesOf(AppSubscription::class, $session->subscriptions());
+        $this->assertSame('server-s', $session->subscriptions()[0]->payload->product);
+        $this->assertSame('42', $session->metadata->cart);
+    }
+
+    public function test_the_app_finds_refreshes_and_cancels_sessions(): void
+    {
+        $this->respond(200, $this->sessionData(['status' => 'completed', 'confirmation_url' => null]));
+        $this->respond(200, $this->sessionData(['user_id' => 'someone-else']));
+        $this->respond(404, ['message' => 'Checkout session not found.', 'error' => 'checkout_session_not_found']);
+        $this->respond(200, $this->sessionData());
+        $this->respond(200, $this->sessionData(['status' => 'cancelled', 'confirmation_url' => null]));
+        $this->respond(409, ['message' => 'The checkout session is cancelled.', 'error' => 'checkout_session_cancelled']);
+
+        $sessions = $this->owner()->appCheckoutSessions();
+
+        $completed = $sessions->find('01JCS');
+        $this->assertTrue($completed->isCompleted());
+        $this->assertNull($completed->confirmationUrl());
+        $this->assertNull($sessions->find('01JCS'), 'another user\'s session');
+        $this->assertNull($sessions->find('unknown'));
+
+        $session = app(AnikeenId::class)->appCheckoutSessions()->find('01JCS'); // e.g. from a webhook
+        $session->cancel();
+        $this->assertTrue($session->isCancelled());
+        $this->assertSame('POST /api/v1/client/checkout-sessions/01JCS/cancel Bearer app-token', $this->request(4));
+
+        try {
+            $session->cancel();
+            $this->fail('Expected an ApiException.');
+        } catch (ApiException $e) {
+            $this->assertTrue($e->isConflict());
+            $this->assertSame('checkout_session_cancelled', $e->error);
+        }
+    }
+
+    public function test_without_a_billable_the_user_id_is_required(): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+
+        app(AnikeenId::class)->appCheckoutSessions()->create(['subscriptions' => [['id' => '01JS1']]]);
+    }
+
+    public function test_any_app_opens_a_session_with_the_users_token(): void
+    {
+        $this->respond(201, $this->sessionData());
+        $this->respond(200, $this->sessionData(['status' => 'expired', 'confirmation_url' => null]));
+        $this->respond(404, ['message' => 'Checkout session not found.', 'error' => 'checkout_session_not_found']);
+
+        $user = $this->owner();
+        $session = $user->checkoutSessions()->create(['subscriptions' => [['name' => 'Pro', 'unit' => 'month', 'price' => 4.99]]]);
+
+        $this->assertSame('POST /api/v1/checkout-sessions Bearer user-token', $this->request(0));
+        $this->assertArrayNotHasKey('user_id', $this->sentJson(0));
+        $this->assertInstanceOf(CheckoutSession::class, $session);
+        $this->assertSame('https://id.anikeen.com/checkout/sessions/01JCS', $session->confirmationUrl());
+        $this->assertSame(['01JS1', '01JS2'], $session->subscriptionIds());
+
+        $expired = $user->checkoutSessions()->find('01JCS');
+        $this->assertTrue($expired->isCancelled());
+        $this->assertSame(CheckoutSession::STATUS_EXPIRED, $expired->status);
+        $this->assertNull($user->checkoutSessions()->find('unknown'));
+    }
+
+    public function test_nothing_is_requested_until_a_method_is_called(): void
+    {
+        $this->owner()->checkoutSessions();
+        $this->owner()->appCheckoutSessions();
+
+        $this->assertCount(0, $this->sent);
+    }
+
+    public function test_checkout_webhooks_carry_the_session(): void
+    {
+        $payload = json_encode(['id' => '01JEV', 'type' => 'checkout.completed', 'created' => time(), 'data' => ['object' => $this->sessionData(['status' => 'completed'])['data']]]);
+        $timestamp = time();
+        $signature = 't=' . $timestamp . ',v1=' . hash_hmac('sha256', "{$timestamp}.{$payload}", 'whsec_test');
+
+        $event = Webhook::constructEvent($payload, $signature, 'whsec_test');
+
+        $this->assertSame(EventType::CHECKOUT_COMPLETED, $event['type']);
+        $this->assertSame(['01JS1', '01JS2'], $event['data']['object']['subscription_ids']);
+        $this->assertContains('checkout.expired', EventType::all());
+        $this->assertContains('subscription.activated', EventType::all());
+    }
+}

tests/Id/TokenGuardTest.php

@@ -0,0 +1,204 @@
+<?php
+
+namespace Anikeen\Id\Tests;
+
+use Anikeen\Id\HasAnikeenTokens;
+use Anikeen\Id\Helpers\JwtParser;
+use Anikeen\Id\Http\Middleware\CheckForAnyScope;
+use Anikeen\Id\Http\Middleware\CheckScopes;
+use Firebase\JWT\JWT;
+use Illuminate\Auth\RequestGuard;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Foundation\Auth\User as Authenticatable;
+use Illuminate\Support\Facades\Auth;
+use Illuminate\Support\Facades\Route;
+use Illuminate\Support\Facades\Schema;
+use Illuminate\Support\Str;
+
+class TokenGuardTest extends TestCase
+{
+    private static ?string $privateKey = null;
+
+    private static string $publicKey;
+
+    protected function setUp(): void
+    {
+        parent::setUp();
+
+        if (self::$privateKey === null) {
+            $key = openssl_pkey_new(['private_key_bits' => 2048, 'private_key_type' => OPENSSL_KEYTYPE_RSA]);
+            openssl_pkey_export($key, $private);
+            self::$privateKey = $private;
+            self::$publicKey = openssl_pkey_get_details($key)['key'];
+        }
+
+        JwtParser::flushKeys();
+        config([
+            'services.anikeen.public_key' => self::$publicKey,
+            'app.key' => 'base64:'.base64_encode(str_repeat('k', 32)),
+            'database.default' => 'testing',
+            'auth.guards.api' => ['driver' => 'anikeen', 'provider' => 'anikeen'],
+            'auth.providers.anikeen' => ['driver' => 'anikeen', 'model' => GuardUser::class],
+        ]);
+
+        Schema::create('users', function (Blueprint $table) {
+            $table->id();
+            $table->string('anikeen_id')->nullable();
+            $table->string('email');
+        });
+
+        GuardUser::query()->insert([
+            ['id' => 1, 'anikeen_id' => 'ulid-of-alice', 'email' => 'alice@example.com'],
+            ['id' => 2, 'anikeen_id' => '1', 'email' => 'bob@example.com'],
+        ]);
+
+        Route::middleware('auth:api')->get('/me', fn () => ['email' => auth()->user()->email, 'scopes' => auth()->user()->anikeenToken()->scopes]);
+        Route::middleware(['auth:api', CheckScopes::using('user')])->post('/write', fn () => ['ok' => true]);
+        Route::middleware(['auth:api', CheckForAnyScope::using('user', 'user:read')])->get('/read', fn () => ['ok' => true]);
+    }
+
+    /**
+     * Like a fresh request in production: the guard remembers its user per application.
+     */
+    public function call($method, $uri, $parameters = [], $cookies = [], $files = [], $server = [], $content = null)
+    {
+        Auth::forgetGuards();
+
+        return parent::call($method, $uri, $parameters, $cookies, $files, $server, $content);
+    }
+
+    private function token(array $claims = [], ?string $privateKey = null): string
+    {
+        $now = time();
+
+        return JWT::encode(array_merge([
+            'aud' => '019a0000-0000-7000-8000-000000000001',
+            'jti' => Str::random(40),
+            'iat' => $now,
+            'nbf' => $now,
+            'exp' => $now + 3600,
+            'sub' => 'ulid-of-alice',
+            'scopes' => ['user'],
+        ], $claims), $privateKey ?? self::$privateKey, 'RS256');
+    }
+
+    public function test_the_api_guard_resolves(): void
+    {
+        $this->assertInstanceOf(RequestGuard::class, Auth::guard('api'));
+        $this->assertNull(Auth::guard('api')->user());
+    }
+
+    public function test_a_valid_token_resolves_the_user_by_anikeen_id(): void
+    {
+        $this->getJson('/me', ['Authorization' => 'Bearer '.$this->token()])
+            ->assertOk()
+            ->assertExactJson(['email' => 'alice@example.com', 'scopes' => ['user']]);
+    }
+
+    public function test_the_user_is_not_looked_up_by_primary_key(): void
+    {
+        // sub "2" is bob's primary key, but nobody has the Anikeen ID "2"
+        $this->getJson('/me', ['Authorization' => 'Bearer '.$this->token(['sub' => '2'])])->assertUnauthorized();
+        // sub "1" is bob's Anikeen ID (alice's primary key)
+        $this->getJson('/me', ['Authorization' => 'Bearer '.$this->token(['sub' => '1'])])
+            ->assertOk()->assertJsonPath('email', 'bob@example.com');
+    }
+
+    public function test_the_lookup_column_is_configurable(): void
+    {
+        config(['auth.providers.anikeen.column' => 'email']);
+
+        $this->getJson('/me', ['Authorization' => 'Bearer '.$this->token(['sub' => 'bob@example.com'])])
+            ->assertOk()->assertJsonPath('email', 'bob@example.com');
+    }
+
+    public function test_the_eloquent_provider_works_too(): void
+    {
+        config([
+            'auth.guards.api.provider' => 'users',
+            'auth.providers.users' => ['driver' => 'eloquent', 'model' => GuardUser::class],
+        ]);
+
+        $this->getJson('/me', ['Authorization' => 'Bearer '.$this->token()])
+            ->assertOk()->assertJsonPath('email', 'alice@example.com');
+    }
+
+    public function test_invalid_tokens_answer_401_json(): void
+    {
+        $other = openssl_pkey_new(['private_key_bits' => 2048, 'private_key_type' => OPENSSL_KEYTYPE_RSA]);
+        openssl_pkey_export($other, $otherPrivate);
+
+        $cases = [
+            'no token' => [],
+            'garbage' => ['Authorization' => 'Bearer not-a-jwt'],
+            'expired' => ['Authorization' => 'Bearer '.$this->token(['exp' => time() - 120])],
+            'not yet valid' => ['Authorization' => 'Bearer '.$this->token(['nbf' => time() + 600])],
+            'foreign key' => ['Authorization' => 'Bearer '.$this->token([], $otherPrivate)],
+            'unknown user' => ['Authorization' => 'Bearer '.$this->token(['sub' => 'nobody'])],
+            'client credentials' => ['Authorization' => 'Bearer '.$this->token(['sub' => ''])],
+        ];
+
+        foreach ($cases as $case => $headers) {
+            $this->getJson('/me', $headers)->assertUnauthorized()->assertJson(['message' => 'Unauthenticated.'], $case);
+        }
+    }
+
+    public function test_scopes_are_enforced(): void
+    {
+        $read = $this->token(['scopes' => ['user:read']]);
+        $billing = $this->token(['scopes' => ['billing']]);
+        $all = $this->token(['scopes' => ['*']]);
+
+        $this->getJson('/read', ['Authorization' => "Bearer $read"])->assertOk();
+        $this->postJson('/write', [], ['Authorization' => "Bearer $read"])->assertForbidden();
+        $this->getJson('/read', ['Authorization' => "Bearer $billing"])->assertForbidden();
+        $this->postJson('/write', [], ['Authorization' => "Bearer $all"])->assertOk();
+        $this->postJson('/write', [], ['Authorization' => 'Bearer '.$this->token()])->assertOk();
+    }
+
+    public function test_token_can(): void
+    {
+        $user = GuardUser::query()->find(1)->withAnikeenAccessToken((object) ['scopes' => ['user:read']]);
+
+        $this->assertTrue($user->anikeenTokenCan('user:read'));
+        $this->assertFalse($user->anikeenTokenCan('user'));
+        $this->assertTrue($user->anikeenTokenCanAny(['user', 'user:read']));
+        $this->assertFalse((new GuardUser())->anikeenTokenCan('user'));
+    }
+
+    public function test_revoked_tokens_are_rejected_when_revocation_is_verified(): void
+    {
+        config(['services.anikeen.verify_revocation' => true]);
+        $active = $this->token();
+        $revoked = $this->token();
+
+        $this->respond(200, ['data' => ['id' => 'ulid-of-alice']]);
+        $this->getJson('/me', ['Authorization' => "Bearer $active"])->assertOk();
+        // cached: no second request to Anikeen ID
+        $this->getJson('/me', ['Authorization' => "Bearer $active"])->assertOk();
+        $this->assertCount(1, $this->sent);
+        $this->assertSame("Bearer $active", $this->sent[0]['request']->getHeaderLine('Authorization'));
+        $this->assertStringEndsWith('v1/user', (string) $this->sent[0]['request']->getUri());
+
+        $this->respond(401, ['message' => 'Unauthenticated.']);
+        $this->getJson('/me', ['Authorization' => "Bearer $revoked"])->assertUnauthorized();
+
+        // Anikeen ID down: fail closed, not cached
+        $other = $this->token();
+        $this->respond(503);
+        $this->getJson('/me', ['Authorization' => "Bearer $other"])->assertUnauthorized();
+        $this->respond(200, ['data' => ['id' => 'ulid-of-alice']]);
+        $this->getJson('/me', ['Authorization' => "Bearer $other"])->assertOk();
+    }
+}
+
+class GuardUser extends Authenticatable
+{
+    use HasAnikeenTokens;
+
+    protected $table = 'users';
+
+    public $timestamps = false;
+
+    protected $guarded = [];
+}