Minting
A taken-over session could otherwise issue itself a dozen long-lived tokens in seconds, and they
would outlive the password change that ends the session. PersonalTokens mints for the signed-in
user of a request, under these rules:
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Route;
use Pushery\SanctumHardening\Tokens\PersonalTokens;
Route::post('/settings/tokens', function (Request $request, PersonalTokens $tokens) {
$minted = $tokens->mint($request, $request->string('name')->toString(), ['orders:read'], 90);
// The plain text exists once, in this answer.
return response()->json(['token' => $minted->plainTextToken], 201);
})->middleware(['auth', 'password.confirm']);
The rules of a mint
| Rule | Setting | Refusal |
|---|---|---|
| a model that holds tokens | not_ | |
| for another tokenable, a Gate ability that lets the signed-in user manage its tokens | tokenable_ | not_ |
| a password confirmed within the timeout | minting.password_timeout, or auth.password_timeout | password_ |
| at most this many tokens that have not expired | minting. | limit_ |
| at most this many mints a minute | minting. | too_ |
| one mint at a time for a user | too_ | |
| a lifetime from the list, never longer than the longest | minting.lifetimes, minting.max_lifetime | lifetime |
| no token without an expiry unless allowed | minting. | lifetime |
a name of 1 to 255 characters, here and in mintForSystem() | name |
Each refusal is a MintRefused exception with its reason, and retryAfter or limit where they
apply. A mint that is refused costs the minute nothing. The lifetime is given in days: one of the
configured ones, 0 for a token without an expiry where that is allowed, and null for the
default: minting.default_lifetime where a token may be given it, otherwise the longest allowed
lifetime below it, otherwise the shortest allowed one. PersonalTokens::lifetimes() and
PersonalTokens::defaultLifetime() answer both for a screen of your own.
The password is read the way Laravel's password.confirm middleware records it, so the route that
mints sits behind that middleware.
A limit of the application's own
Where a plan decides how many tokens a user may hold, bind a resolver. The lower of its answer and
minting.max_tokens_per_user counts. It is asked about the tokenable a token is minted for, the
user or a workspace:
use Illuminate\Database\Eloquent\Model;
use Pushery\SanctumHardening\Tokens\ResolvesTokenLimit;
final class PlanTokenLimit implements ResolvesTokenLimit
{
public function limitFor(Model $tokenable): ?int
{
return $tokenable->getAttribute('plan') === 'free' ? 2 : null;
}
}
use App\Tokens\PlanTokenLimit;
use Pushery\SanctumHardening\Tokens\ResolvesTokenLimit;
$this->app->bind(ResolvesTokenLimit::class, PlanTokenLimit::class);
Tokens of a workspace
A token can belong to another model than the signed-in user, a workspace for instance, so that it
outlives the person who minted it. mintFor() mints one under the rules above, counted for that
tokenable: its own limit, its own minute and its own lock. The password is the signed-in user's:
use App\Models\Workspace;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Route;
use Pushery\SanctumHardening\Tokens\PersonalTokens;
Route::post('/workspaces/{workspace}/tokens', function (Request $request, Workspace $workspace, PersonalTokens $tokens) {
$minted = $tokens->mintFor($request, $workspace, $request->string('name')->toString(), ['orders:read'], 90);
return response()->json(['token' => $minted->plainTextToken], 201);
})->middleware(['auth', 'password.confirm']);
Who may do so is the application's call. The package asks the Gate for the ability
manage-tokens with the workspace as its argument, and refuses with not_allowed where the
application defines none. A policy of the model answers it in manageTokens(), or a definition of
its own does:
use App\Models\User;
use App\Models\Workspace;
use Illuminate\Support\Facades\Gate;
Gate::define('manage-tokens', fn (User $user, Workspace $workspace): bool => $workspace->owner_id === $user->id);
Where manage-tokens already means something else in the application, tokenable_ability names
another ability. mint($request, …) is mintFor() for the signed-in user, whose own tokens never
need the Gate.
Tokens of the application's own code
mintForSystem() mints without a password and outside the limits of a person, and it may carry a
reserved ability:
use Pushery\SanctumHardening\Tokens\PersonalTokens;
$device = app(PersonalTokens::class)->mintForSystem($user, 'Phone', ['device:sync'], now()->addYear());
Limiting a token to networks
Every mint takes the addresses and networks a token may be used from as its last argument: IPv4 and IPv6 addresses, and networks in CIDR notation. A request from anywhere else is refused the way a token that does not exist is refused, so the answer does not tell the caller that the token is valid.
use Pushery\SanctumHardening\Tokens\PersonalTokens;
$minted = app(PersonalTokens::class)->mintForSystem($server, 'Backup', ['device:sync'], now()->addYear(), ['203.0.113.0/24', '2001:db8::/32']);
TokenNetworks::restrict($token, $networks) changes the networks of a token minted before, and an
empty list lifts the limit. TokenNetworks::of($token) reads them. An entry that is no address and
no network is refused with a MintRefused whose reason is network.
The address is the request's as Laravel reads it, through the proxies the application trusts. A
header such as X-Forwarded-For counts only where it comes from a trusted proxy, so a client cannot
claim an address it does not send from. The check runs inside Sanctum's authentication callback. A
callback the application sets with Sanctum::authenticateAccessTokensUsing() in a service
provider's boot() keeps answering, and a token passes only where both let it. One set after the
application has booted replaces the check, and sanctum-hardening:doctor then names every limited
token and ends with exit code 1. It sees a callback replaced while the application boots, not one
replaced inside a request.
Listing and revoking
listFor($request) returns the signed-in user's tokens, the newest first, without a token that
carries a reserved ability or was revoked. revoke($request, $tokenId) revokes one of them and
answers whether it did. Both take a workspace as their last argument, listFor($request, $workspace)
and revoke($request, $tokenId, $workspace), and ask the Gate the way mintFor() does: a user it
does not allow sees no token and revokes none. To tell the tokens apart, TokenPrefixes::of($tokens)
gives the first twelve characters of each token's secret, as they stand at the start of the value
that was handed out. A token minted outside the package has none.
Revoked, not deleted
A revoked token keeps its row. Its expiry moves to the moment it was revoked, so Sanctum refuses
every request with it from then on, and a record names the token, its holder, the signed-in user who
revoked it and the time. The application's own code revokes the same way, with the user it acts for
or null:
use Pushery\SanctumHardening\Tokens\TokenRevocations;
$revocations = app(TokenRevocations::class);
$revocations->revoke($token, $admin);
foreach ($revocations->of($user) as $revocation) {
// $revocation->tokenName, ->revokedByType, ->revokedById, ->revokedAt
}
sanctum-hardening:prune-revocations deletes the record of a revocation once revocations.keep_days
days have passed, 90 by default, and the revoked token with it where its row is still there. A
revoked token is expired from the moment it is revoked, so sanctum:prune-expired deletes its row
once the hours it runs with have passed, a day in the schedule under
pruning.