# UPGRADE — Lvntr Starter Kit
This file is the cross-major-version migration guide. Every release gets its own section, newest at the top. Small bug fixes live only in `CHANGELOG.md` — this document covers only changes that touch **published** files (i.e. files copied into your app by `sk:install`), because those changes cannot be delivered by `composer update` alone.
---
## v13.8.3 → v13.8.4
### Share link management needs a new migration
**Affects:** every app that uses the File Manager share links.
- The migration `create_file_manager_share_links_table` ships in the package's `database/migrations/`. Run `php artisan migrate` (`sk:update` already runs it). Until it has run, creating a share link fails.
- Links created before the upgrade are not listed in the new "Active Share Links" drawer, because their signatures were never stored. They still expire on schedule, 30 days later at most.
- If you copied `resources/js/composables/useFileShare.ts` or the Files page into your app, you keep the old UI until you re-sync those files (`php artisan sk:update --dry-run` shows the diff).
### `AuthenticateSession` is now in every `web` group — a password change ends other sessions
**Affects:** every app. Nobody is signed out by the upgrade itself.
- The package appends Laravel's `AuthenticateSession` to the `web` middleware group. Sessions that were already open are stamped on their next request; from then on a password change or reset signs the user out of their other sessions on their next request. This is what makes "Log out other browser sessions" work on the `file`, `redis`, `memcached` and `cookie` drivers. Do not remove the middleware from `web`: on a non-`database` driver the purge would report success without ending anything.
- The purge re-hashes the password without moving `password_changed_at`, and it cycles the remember token, so other devices' remember-me cookies stop working.
- If you ran `sk:eject Session`, you own `app/Domain/Session/Actions/PurgeOtherSessionsAction.php` and `sk:update` will not touch it. Port the new `execute()` body by hand: inside `Model::withoutEvents()`, set a new remember token on the guard's user and re-hash the password through the session guard's `logoutOtherDevices()`; then delete the other session rows on the `database` driver.
- If you ran `sk:eject User`, you own `app/Domain/User/Actions/UpdateUserAction.php`. Copy the `Auth::setUser($user)` block that follows the transaction in the package's `UpdateUserAction::execute()`. Without it, users who change their own password on the Users screen are signed out on their next request. Diff against the package copy in `vendor/lvntr/laravel-starter-kit/src/Domain/Session/Actions/PurgeOtherSessionsAction.php`.
### `useFileManager().sort` can be `null`
**Affects:** apps that read `sort` from `useFileManager()` in their own code.
- `sort` is now `SortKey | null`. `null` means "the view's default order" (Trash opens newest-deleted first). Handle `null` before using it as a key. The stock `FileManager.vue` already does; only code you wrote yourself needs a check.
- `GET /file-manager/favorites/contents` and `GET /file-manager/trash/contents` accept `sort` / `direction`; callers that send neither get the same order as before.
---
## v13.7.3 → v13.7.4
### The "Debug Mode" badge is now gated on `system_admin` instead of the environment
**Affects:** apps that edited `app/Http/Middleware/HandleInertiaRequests.php`. **Not affected:** apps that left the file untouched — `sk:update` tracks it by hash and delivers the new version for you.
`appDebug` used to be shared as `false` throughout production, so the header's "Debug Mode" badge — the only visible sign that `APP_DEBUG=true` was still on — went dark on the one server where leaving it on actually costs something. The flag is now gated on the viewer rather than the environment: a `system_admin` sees the badge in every environment, and nobody else ever receives the flag, which keeps the fingerprinting concern the environment check was written for intact.
If `sk:update` reports that your copy of the file diverged (it keeps your edits), apply the two-line change yourself:
```php
// before
'appDebug' => fn () => app()->environment('production') ? false : (bool) config('app.debug'),
// after
'appDebug' => fn () => (bool) config('app.debug')
&& ($request->user()?->hasRole('system_admin') ?? false),
```
`php artisan sk:update --dry-run` shows the diff before anything is written. `appEnv` is unchanged — its "Dev Mode" badge only ever renders on `local`. The check costs no extra query: the `roles` relation is already loaded for the `auth` share in the same method.
---
## v13.6.16 → v13.7.0
### FileManager file URLs on a local/public disk are no longer permanent public links
**Affects:** installs where the FileManager (or avatar) media disk is `local` or `public` — anything without temporary/signed-URL support. **Not affected:** S3 and any other disk that supports temporary URLs (unchanged).
`FileItemDTO::fromModel()` used to fall back to `Media::getUrl()` whenever the disk throws on `getTemporaryUrl()` — every local/public disk does. That URL is permanent, unauthenticated, and works forever: it bypasses `FileManagerAuthorizer` entirely, keeps serving the file after a permission revoke, and keeps serving it after the file is moved to trash. It now falls back to a new authorized `files.preview` route instead, gated by the same `authorizeRead()` check and context guard `files.download` already uses, and it requires an authenticated session (the browser sends the session cookie automatically for an `` on the same origin).
**What to check:** any URL your app stored, emailed, or otherwise handed out from a FileManager listing on a local/public disk (a saved link, a value cached client-side, a link sent in a notification) now points at the old bare `/storage/...` path and will keep working only as long as that file is still physically on disk at that path — it will NOT gain authorization retroactively, and it will NOT auto-update to the new preview URL. Any such link needs to be regenerated from a fresh FileManager listing (or download link) if it needs to keep working, or reissued as a `files.preview`/`files.download` link if it needs to be access-controlled. A consumer that reads `FileItemDTO->url` fresh on every request (the normal case — nothing in the shipped frontend persists it) needs no changes.
**Publishing an image is still possible — use `public_url`.** A FileManager listing entry now carries a second URL field: `public_url` is `Media::getUrl()` when the backing disk is declared `'visibility' => 'public'`, and `null` on any disk that is not publicly readable. `url` stays the session-gated preview link and is what the file browser uses everywhere. Anything that writes a file URL into content that outlives the admin session — the rich-text editor's embedded ``/`` can seek. Remote drivers (no real filesystem path) keep the streamed response and answer `200` with the full body, as before.
`Lvntr\StarterKit\Traits\HasMediaCollections::getMediaForForm()` (used for avatar and other form-attached media) still calls `Media::getUrl()` directly and is **deliberately unchanged in this wave** — it is a separate, narrower surface (a bound form field, not a public listing) and carries the same raw-URL pattern; not addressed here.
### The aura page header moved into the content card — `AdminLayout.vue` and `AdminHeader.vue` migrate together
**Affects:** installs on the aura theme that customised `stubs/resources/js/layouts/AdminLayout.vue`. **Not affected:** the main theme, or an app that left both layout files untouched.
Aura used to hand the page title, subtitle and back button to `AdminHeader` for display in the topbar; the header is now drawn inside the content card's own head, and the shipped `AdminLayout.vue` no longer binds `pageTitle`/`pageSubtitle`/`showBack` or listens for `back`. `sk:update` tracks each published file by its own hash, so an app that edited only the layout keeps its edited copy and still receives the new header — a pairing that would leave the old layout feeding a title and a back button nothing renders any more.
`AdminHeader.vue` therefore still accepts all three props, still emits `back`, and still renders the topbar title block and back button when they are set. Nothing binds them by default, so a fresh install is unaffected. (`showBack`/`back` never appeared in a tagged release — they existed only between two 13.7.0 development commits — so this half of the bridge matters only to an app installed from `main` rather than from a version tag.) If you customised the layout, either take the new page-header wiring from the shipped `AdminLayout.vue` (compare it with `php artisan sk:update --dry-run`) or keep binding the props — both render a page title, just in different places. The bridge is back-compat only and will be removed in a later major.
### Two `@tiptap/*` packages removed from `stubs/package.json`
`@tiptap/extension-task-item` and `@tiptap/extension-task-list` were removed from the stub's direct dependencies — neither is imported anywhere in the kit's own code (`EditorInput.vue` or elsewhere). If your own code imports either of these directly (a custom rich-text extension, a task-list feature built on top of the editor), add them back to your own app's `package.json`; `sk:update`/`composer update`/`npm install` no longer pull them in for you, even transitively.
### `npm install` may fail with `ERESOLVE` — delete `package-lock.json` and install again
**Affects:** any app upgrading to 13.7.x that keeps the `package-lock.json` it installed 13.6.x with. **Not affected:** a fresh `sk:install`, which regenerates the lockfile.
13.7.0 moved the whole frontend toolchain onto its current releases, `@tiptap/*` among them (`^3.27.1` → `^3.31.3`). `sk:update` merges the new constraints into your `package.json`, but your `package-lock.json` still pins the old graph — and every `@tiptap/extension-*` package declares an **exact** peer on `@tiptap/core` (`peer @tiptap/core@"3.27.1"`), so npm cannot lift half the family and leave the rest. It gives up:
```
npm error ERESOLVE could not resolve
npm error Found: @tiptap/core@3.27.1
npm error @tiptap/core@"^3.31.3" from the root project
npm error peer @tiptap/core@"3.27.1" from @tiptap/extension-blockquote@3.27.1
```
Drop the stale lockfile and the tree built from it, then install again:
```bash
rm -rf node_modules package-lock.json
npm install && npm run build
```
The lockfile is regenerated from the same `package.json` ranges your app already declares, so nothing moves outside a constraint you approved. Do **not** reach for `--force` or `--legacy-peer-deps`: both leave a `@tiptap/core` in `node_modules` that the extensions around it were never built against, and the editor breaks at runtime rather than at install time.
### `LogoutUserAction` now revokes the refresh token bound to the current credential too
`app/Http/Controllers/Admin/*`'s logout path is not affected, but the stub `app/Domain/Auth/Actions/LogoutUserAction.php` is: it used to call `$user->token()?->revoke()` and stop there, leaving a live OAuth refresh token bound to the just-revoked access token — a refresh token deliberately outlives its access token, so the caller could mint a brand-new access token immediately after "logging out." The action now uses a new `Lvntr\StarterKit\Domain\User\Concerns\RevokesOAuthCredentials` trait that revokes the refresh token first and the access token second.
**This is a published stub — `sk:update` will not silently overwrite a copy you modified.** If you have customised `LogoutUserAction` (added an audit log call, a `Fortify::logout()` hook, a custom response), the fix will not reach you automatically: your on-disk hash no longer matches the shipped one, so the three-way comparison treats the file as a consumer edit and skips it (see the "consumer-modified published file" note above). Port the change over by hand — add `use Lvntr\StarterKit\Domain\User\Concerns\RevokesOAuthCredentials;`, `use RevokesOAuthCredentials;` on the class, and replace the `$user->token()?->revoke()` line with `$this->revokeCurrentOAuthCredentials($user);`. Do **not** reach for `sk:update --force` here: the command takes no file argument, so `--force` drops the modification guard for *every* published file at once and overwrites all of your customisations, not just this one. An install that never customised the stub picks the fix up automatically on the next `sk:update`.
The same gap in `Lvntr\StarterKit\Domain\User\Actions\RevokeUserAccessAction` (used when an operator revokes a user's access, e.g. via the Users screen) is fixed in vendor code and needs only `composer update` — no stub to carry over.
### `encryption:key` gained `--allow-acl-loss` — now covers an inherited-ACL mismatch too, not only a loss
If your `.env` has a POSIX ACL grant on it (`setfacl -m u:www-data:r .env`, or the macOS `chmod +a` equivalent) rather than relying on group ownership alone, `encryption:key` now refuses to complete a rotation unless it can verify that ACL survived onto the replacement file — it previously carried over owner/group/mode but silently dropped the ACL, which `fileperms()` cannot see either before or after. Most installs have no file-specific ACL and see no change in behavior.
The flag also now covers the MIRROR direction: the temporary file is created inside `.env`'s own directory, so a directory-level ACL inheritance rule (`setfacl -d -m …`, or the macOS `chmod +a "… file_inherit"` equivalent) can put a grant on it that `.env` itself never had — invisible to the mode check the same way, and present before a single byte of the new key is written. The rotation now refuses to complete unless that inherited entry is normalised away too. Only relevant if `.env`'s directory carries an inheritance rule; most installs see no change.
If either refusal fires and you plan to reconcile the ACL by hand right after rotating, pass `--allow-acl-loss` to downgrade it to a warning (printed to the console and written to the log — the warning carries the file path and ACL text only, never key material) instead of aborting the rotation. Do not pass it as a default habit: the refusal exists because a `.env` the web server cannot read after rotation — or one that grants access to a principal it shouldn't — is a broken deploy, not a cosmetic warning.
### `release.sh` now requires `gh` and a green remote CI run on the tagged commit
This only affects whoever runs `./release.sh` for this package — it has no effect on any consumer app. The release flow is now: commit → `git push origin main` → wait for CI to go green → `./release.sh`. The script queries `gh run list --commit ` before running the local quality gate and stops if `gh` is missing, unauthenticated (`gh auth login`), the commit was never pushed, or any workflow's latest run for that commit is not `success`/`skipped`. `--skip-checks` bypasses this along with the rest of the local gate, same as before.
### `sk:install` now refuses to run on an app it did not install
`sk:install` used to trust its own hash registry (`storage/starter-kit/hashes.json`) as the only signal that a project was already installed — and that registry is git-ignored, so a stateless deploy or a cleared `storage/` directory made a live application look brand new. The command now runs a fail-closed detection pass ahead of the banner: it looks for the kit's schema tables and a handful of paths that only an install creates. If any of that evidence is present but the registry is missing, the command stops before writing anything and prints exactly what it found.
The stop names two ways out: `sk:update` for changing an installed app, and `php artisan sk:install --adopt` (add `--dry-run` to preview) to rebuild the registry from the files already on disk — it copies no file, runs no migration, and never touches `.env`. `--force` still proceeds past the stop for a genuine edge case, but read it as "overwrite the paths listed above," and note that a forced run is **not** treated as a first install (no default-domain eject, no first-install `.env` seeding).
### `.env` is never overwritten — a first install onto an app that already has one now merges
A first install used to copy `.env.example` over an existing `.env` outright — destroying `DB_PASSWORD`, `APP_KEY`, and everything else already configured whenever `sk:install` ran on the ordinary `composer create-project` shape (a Laravel app that already ships a `.env`). `.env` is no longer overwritten on either path. If the file already exists, the installer merges: every key present in `.env.example` but missing from `.env` is appended, and the first-install-only keys are seeded **only where absent**. No existing key's value is ever rewritten. `.env` is created from `.env.example` only when it does not exist at all. `APP_KEY` is still generated when the merged file leaves it blank, so the app can boot.
### A consumer-modified published file is skipped by default — `--force` is the opt-out
Both `sk:install` and `sk:update` now decide whether to overwrite a published path through the same three-way comparison (shipped stub hash vs. on-disk hash vs. the hash recorded in the registry at the last install/update). When the on-disk copy no longer matches what was recorded, the difference is treated as a consumer edit and the file is **skipped and reported**, instead of being silently overwritten — this now also covers `sk:install`'s re-publish path, not only `sk:update`'s. Pass `--force` to overwrite anyway; commit first so Git keeps the previous version reachable.
This closes the one remaining gap in that guard: on a re-install, a file the hash registry has **no record of at all** — because a newer package version started shipping into a path it never shipped into on this app before — used to be overwritten regardless of `--force`. It is now treated the same as a consumer edit: preserved and reported, not overwritten, unless `--force` is passed. The protection only applies once a registry exists to be authoritative; a genuine first install still publishes every path, tracked or not, because there is nothing yet to compare against.
### Inactive users are cut off mid-session
The login path already refused a non-active account, but it could not reach a session that was already open — an operator deactivating a user had to wait for that user's session cookie to expire on its own. A new `EnsureUserIsActive` middleware (wired automatically onto the `web` and `api` guards) now checks the authenticated user's `status` on every request and, if it matches the operator's deny-list, logs a web session out and redirects to login, or returns a 403 for an API request.
This is deliberately **fail-open** on every ambiguous case: a guard with no authenticated user, an unresolvable guard, a user model with no `status` attribute, a non-string `status`, or — critically — a value that is **not on the deny-list**, all pass through untouched. The middleware never infers "not active therefore blocked"; it only ever blocks a status that was explicitly listed. The default deny-list is `['inactive', 'banned']`, matching the shipped `userStatus` definition; an install using its own vocabulary adds its own values via `starter-kit.security.active_status_denied`. `starter-kit.security.enforce_active_status = false` is the kill switch — set it to disable the middleware outright without touching `bootstrap/app.php`. A consumer who published `config/starter-kit.php` before this `security` block existed is still covered: the middleware falls back to class constants matching the shipped defaults when the published config is missing the new keys.
### Installer commands now exit non-zero on a failed mandatory step
`sk:install`, `sk:update`, `sk:upgrade`, and the published `site:install` stub used to invoke `migrate`, `db:seed`, `vendor:publish`, `sk:seed-permissions`, `passport:keys`, `key:generate` and other sub-commands without reading their result, so a failed migration still printed `DONE`, recorded the step as complete in the resume checkpoint, and the command exited `0` — a CI job could go green over a half-installed application. Every sub-command result is now checked; a failed **mandatory** step (publish, migrations, seeders, permission seeding, Passport keys, encryption keys) now aborts the run with a non-zero exit code, leaves the checkpoint pending so `sk:install --resume` picks up where it stopped, and skips the stub-hash registry write.
If a CI pipeline currently passes despite a silently failing installer step, it will start failing after this upgrade — that is the intended signal, not a regression to work around. Frontend and tooling steps (`npm install`, Wayfinder generation, `npm run build`, `composer dump-autoload`, cache clears) deliberately stay non-fatal: they warn, print the command to run by hand, and are listed again in the closing summary, so a machine without Node or Composer still installs exactly as it does today. The `site:install` change ships through `stubs/`, so it reaches new installs and `sk:update`-refreshed apps only — an existing, untouched consumer copy of `site:install` is not changed.
An unreachable database at install time used to still print `Lvntr Starter Kit installed successfully!` and exit `0` — the database block (migrations, seeders, permission seeding) was skipped with only an on-screen warning. That run now ends the install as **incomplete**: no stub-hash registry is written, the resume checkpoint from the filesystem steps that did finish is kept, and the command exits non-zero. Fix the database connection and run `php artisan sk:install --resume` to pick up exactly where it stopped, rather than starting over.
### `migrate:fresh` now demands a typed confirmation
When `sk:install` finds an existing database with tables already in it, it offers a `select()` menu that included a "Drop all tables and run fresh migrations" option, confirmed by the ordinary yes/no `select()` answer — one accidental keystroke away from an irreversible `migrate:fresh`. That option is now gated behind a **typed** confirmation: the operator must type the database name (or the literal word `fresh`) at a `text()` prompt before the drop runs; anything else, including an empty answer or a reflexive `y`, falls back to the additive `migrate` path with nothing dropped. The destructive option is also withheld outright — the prompt explains why — when `APP_ENV` looks production-like, `APP_DEBUG` is off, the session cannot prompt at all (`--no-interaction`, CI, no TTY), or any existing table already holds rows (a table that cannot be read counts as holding data). There is no escape hatch around the typed confirmation itself; the only way to skip it is to run against an empty database or use `migrate` instead.
### `sk:install` is no longer documented as a recovery path
`docs/install.md` and `docs/update.md` previously described re-running `php artisan sk:install` on an existing project as an idempotent whole-project recovery step. It is not, and that advice is withdrawn — treat `storage/starter-kit/` as persistent operational state in your deploy strategy — it must survive a release the same way `storage/app/` does.
Two of the risks that originally motivated withdrawing that advice are now addressed above rather than open: a missing registry no longer makes `sk:install` silently treat an installed app as a first install (see "`sk:install` now refuses to run on an app it did not install" above), and a first install onto an app that already has `.env` no longer overwrites it (see "`.env` is never overwritten" above). What still makes `sk:install` the wrong tool for touching an already-installed app is the consumer-edit handling described in "A consumer-modified published file is skipped by default" above: without `--force` an edited file is skipped and reported rather than refreshed, and with `--force` it is overwritten outright, so neither mode gives you the selective, edit-preserving refresh `sk:update` or a scoped `sk:publish --tag=.` route name whose action segment is in the middleware's ability map, so a permission resolves automatically.
- Gate it with an explicit permission argument, e.g. `check.permission:reports.read`.
- If the route is deliberately permission-free (a public webhook, a health check, …), declare it under `starter-kit.permissions.unrestricted_routes` (tight `Str::is` patterns — prefer listing endpoints over whole trees, since a broad pattern silently exempts routes added later too).
3. With steps 1–2 done, set `STARTER_KIT_ALLOW_UNRESOLVED_ROUTES=false` (or `starter-kit.permissions.allow_unresolved` = `false`) in a staging environment and confirm nothing you rely on gets denied. Once staging is clean, set the same value in production. That line is the whole opt-in — nothing else has to change, and nothing will do it for you.
**If you published the kit's config** (`php artisan sk:publish --tag=config`), your `config/starter-kit.php` predates both new keys, and `mergeConfigFrom` merges only the top level — the package's `permissions` array does not fill gaps inside yours. Nothing breaks: `allow_unresolved` falls back to the package default in code, and an absent `unrestricted_routes` reads as an empty list. But step 2's third option does nothing until you add `'unrestricted_routes' => [...]` to your published `permissions` array yourself. Diff your copy against `vendor/lvntr/laravel-starter-kit/config/starter-kit.php` to pick up both keys.
**No release will flip this for you.** `STARTER_KIT_ALLOW_UNRESOLVED_ROUTES` (config `starter-kit.permissions.allow_unresolved`) defaults to `true` for an app that does not set it, and that default does not change anywhere in 13.x. There is no scheduled release in which your app starts denying on its own; step 3 is the only thing that turns it on, and you choose when.
The reason it is not simply switched is how far the switch would reach. An installation that never published the config, and one whose published copy predates the key, both fall through to the package's own constant — so changing that constant would alter authorization on a plain `composer update`, for every app, without anyone editing a file. A default with that reach is not a default anyone can change safely inside a release line; if it is ever revisited, it belongs in a major, with its own upgrade note.
**A brand-new project is different, and already strict.** `sk:install` writes `STARTER_KIT_ALLOW_UNRESOLVED_ROUTES=false` into the `.env` it creates: a fresh app has no legacy route to grandfather in, so it starts fail-closed and its first ungated route is caught during development instead of in production. This applies to first installs only — re-running `sk:install` on an existing app will not add the key, and neither will `sk:update` or `sk:upgrade`.
Whichever way you set it, the env var stays a valid production escape hatch: set it back to `true` if you need more time to finish remediation, keeping in mind that every route left unresolved is, by definition, ungated for as long as it stays that way.
### Cross-page bulk selection now fail-closes on unsupported filters
If a page adds its own filter on top of the kit's Users or Roles table — a custom `filter[...]` key the datatable doesn't declare — clicking "select all filtered" for a bulk action now returns a **422** (`sk-bulk.unknown_filters`) instead of silently running the bulk action against a set that ignores that filter. Before this release, an unsupported active filter was dropped from the snapshot and the resolved set was **wider** than what the table showed — deleting or acting on rows the filter was meant to hide.
A blank value is active too. `filter[status]=` (an empty or whitespace-only string) is applied by the table as `WHERE status = ''` — an empty set — so the bulk side now passes it through verbatim instead of treating it as "no filter": on a supported key it resolves the same (empty) set the table showed, on an unsupported key it is rejected with the same 422. Only a `null` value or an empty array is ignored, matching what Spatie's `AllowedFilter` skips. The shipped `SkDatatable` never writes a blank filter into the URL, so the stock Users/Roles pages are unaffected; a page that builds its own `filter_snapshot` should drop blank keys rather than send them.
**Do not "fix" the 422 by stripping the unsupported filter out of the snapshot before it reaches the backend** — that re-widens the set back to the old, unsafe behavior. Instead, extend the allow-list the query class actually applies (`UserBulkSelectionQuery::ALLOWED_FILTERS` / the Roles equivalent) so the new filter is honoured with the same semantics the table uses, or leave cross-page selection disabled while that filter is active and fall back to per-row selection.
This fix lives in the vendor query classes (`Lvntr\StarterKit\Domain\User\Queries\UserBulkSelectionQuery`, `Lvntr\StarterKit\Domain\Role\Queries\RoleBulkSelectionQuery`). **An ejected copy of either query — via `make:sk-domain` or any manual copy out of the vendor namespace — does not receive this fix on `composer update`**; re-diff your copy against the vendor source to pick it up. Likewise, a copy of `useDatatableSelection.ts` published with `php artisan sk:publish --tag=composables` keeps sending whatever id shape it sent before until you re-publish or manually port the change described below.
### `BulkActionRequest` no longer requires `ids` in cross-page mode
`app/Http/Requests/Admin/BulkActionRequest.php` required `ids` (`min:1`) even when `select_all_filtered` was `true`, contradicting the documented payload (`ids` is empty then) — a host calling `useDatatableSelection().executeBulkAction()` directly with nothing selected on the current page got a 422 (`sk-bulk.ids_required`). The rule is now `Rule::requiredIf(! select_all_filtered)`; any ids that are sent are still validated (`array`, `max:500`, opaque strings), and the cross-page set stays bounded by the selection query's `MAX_ITEMS` cap. This is a published stub: an unmodified copy is refreshed by `php artisan sk:update`; a copy you edited keeps the old rule until you port the change.
### Bulk selection ids are sent as opaque strings, no numeric coercion
`useDatatableSelection()`'s `executeBulkAction()` no longer coerces selected row ids before posting them. Backend `ids.*` validation already accepts `string|min:1|max:64`, so UUID/ULID primary keys were already valid — but a numeric-looking id could previously round-trip through a coercion step. If your own bulk endpoint parses `ids` with a strict integer cast, confirm it still accepts the exact string PrimeVue key type your `idKey` column uses.
### `DatatableQueryBuilder::columns()` payload shaping is fail-closed
A backend that declares `columns()` and receives a `?columns=` request parameter with **no key matching a declared column** now reduces every row to the `alwaysInclude()` keys only — it no longer falls back to returning the full row. An absent `columns` parameter is unaffected and still returns the full row. If a frontend column key and the corresponding backend `columns()` key have ever drifted apart (a rename on one side only), affected cells now render empty instead of masking the mismatch with the full payload; audit both sides if you see missing cell data after upgrading.
### `definitions.lang` is narrowed — the migration can refuse
`create_definitions_table` declared `unique(['key', 'value', 'lang'])` over three default `string()` (255-character, utf8mb4) columns — 3060 of MySQL/MariaDB's 3072-byte InnoDB key limit, one column-width away from breaking outright. A new migration narrows **`lang` only**, to 35 characters — the widest locale value the kit already accepts anywhere, taken from `content_languages.code`, so any tag you could have stored through the kit's own screens still fits and the refusal below stays unreachable for it. `key` and `value` keep their published 255: `lang` alone brings the index down to 2180 bytes, ~892 under the ceiling, so narrowing them would only have blocked data the current schema accepts.
**Before touching the schema, the migration measures every existing row** (`lang` character length, soft-deleted rows included — they still occupy the unique index) and refuses, unchanged, if any row would lose characters at the new limit. If it refuses on your data:
1. Read the error — it names the column, the row count over the limit, and the longest value found.
2. Shorten or delete the offending `definitions` rows (including soft-deleted ones — `deleted_at` does not exempt a row from the unique index).
3. Re-run `php artisan migrate`.
The migration is a straight rollback (`down()` widens `lang` back to 255 — a widening never truncates, so it needs no probe). Either direction ends by asserting the unique index is present, so a table that reached it with the index already missing (a half-finished earlier run) gets it rebuilt rather than recorded as migrated without its guarantee. On a table grown well beyond the kit's own ~34 seeded rows, the `ALTER TABLE` + index rebuild holds a metadata lock for its duration; schedule it with the same care as any other ALTER on a large table.
### `media` table migration now has a rollback path — one that refuses rather than destroys
`create_media_table` had no `down()`. Laravel's migrator guards that call with `method_exists`, so `php artisan migrate:rollback` did not error — it silently skipped the table and deleted the migration's ledger row anyway, leaving a `media` table that the app no longer had a record of and a re-`migrate` that failed on it. It now declares a `down()`: the table is dropped when it is empty, and a rollback attempted while rows remain stops with an error naming the table. The two later migrations in the same chain (`add_folder_id_to_media_table`, `add_soft_deletes_to_media_table`) carry the identical refusal, because a batch rolls back newest-first: without it they would have dropped `folder_id` and `deleted_at` off a populated table before the create migration's guard was ever reached.
**This is a behaviour change for existing consumers**: a `migrate:rollback` covering the batch this migration belongs to used to walk past `media` in silence; on an install that has media rows it now **fails**. That failure is the feature. Dropping a populated `media` would remove the **rows**, not the **files**: every row points at a blob on a configured disk, and Spatie deletes that blob only through the model's deleting event — a schema rollback bypasses Eloquent entirely, so the storage directories would survive intact while the only index of them was destroyed, leaving orphaned files nothing in the app can enumerate afterwards.
To roll the migration back deliberately, delete the media **through the application** first, so the blobs go with the rows, then run the rollback again. Do not empty the table with raw SQL to get past the guard — that reproduces exactly the orphaning the guard exists to prevent.
### File uploads now enforce a client-extension allowlist
FileManager and avatar uploads no longer pass purely on a sniffed content-type match — the client file name's extension is checked too, and `media-library.disallowed_extensions` now blocks `html`, `htm`, `xhtml`, `xht`, `svg`, `svgz`, `xml`, `xsl`, `xslt`, `js`, `mjs`, and `hta` in every dot segment of the name, not only the last one (so `name.html.pdf` is refused even though `.pdf` is the final extension). See `CHANGELOG.md` for why. Nothing here touches the database or `.env`; two things need an operator's attention.
**The avatar request stub is consumer-owned.** `stubs/app/Http/Requests/UploadAvatarRequest.php` was copied into your app by `sk:install`, and the kit cannot reach back into a file it already handed you. An existing installation keeps its old rules — `image`, `mimes:jpg,jpeg,png,webp`, no extension check — until you either run `php artisan sk:update` to pull the refreshed stub, or add `'extensions:jpg,jpeg,png,webp'` to your own copy's `rules()` array by hand, right after the existing `'mimes:jpg,jpeg,png,webp'` entry.
**The `media-library.disallowed_extensions` hardening applies unconditionally — there is no flag to opt out.** Unlike the kit's `media-library.php`/`activitylog.php` overrides, which back off the moment you publish your own copy of that config, this merge runs on every boot regardless. If your application genuinely needs to accept one of the newly blocked extensions, override `mimeExtensionMap()` in a subclassed request to declare the MIME/extension pair you accept, and remove that extension from `media-library.disallowed_extensions` yourself in your own service provider (registered after the kit's) — understanding that doing so reopens the active-content risk this hardening closes.
**Renames keep their extension, and the size ceiling is aligned.** `PATCH files/{media}` now rejects (422) a new name whose extension differs from the stored file's or that contains a blocked segment (`report.php.pdf`). Accepted MIME types outside the kit's `mimeExtensionMap()` (PPTX, RAR, Markdown, …) resolve their extensions from Symfony's MIME database, so the subclass override above is only needed for a MIME neither knows. The media library's own `media-library.max_file_size` (10 MB by default) is independent of the FileManager `max_size_mb` setting: an upload above it now fails with a 422 ("The uploaded file is too large.") instead of a 500, and the refreshed `app/Providers/SettingsServiceProvider.php` stub sets `max_file_size` from `max_size_mb` — pull it with `php artisan sk:update`, or add `config(['media-library.max_file_size' => $maxSizeMb * 1024 * 1024])` next to the existing `file-manager.settings.max_size_mb` write in your copy.
Per-segment blocking (the `name.html.pdf` case above) ships in `spatie/laravel-medialibrary` **11.23.0** (2026-05-28), and the kit's `composer.json` now requires `^11.23`, so the `composer update` that brings in this release pulls a build that enforces the list; the kit's own request-level segment check covers any interval in which an older build is still installed. Check with `composer show spatie/laravel-medialibrary` if in doubt.
### The settings cache key changed — no action required unless you subclassed `SettingService`
`SettingService` now caches raw (ciphertext) rows under `settings:v2` instead of caching decrypted values under `settings`; see `CHANGELOG.md` for why. No deploy step is required: the old `settings` key is dropped automatically the first time the new snapshot is built. Running `php artisan cache:forget settings` by hand is harmless if you'd rather drop a lingering plaintext snapshot immediately instead of waiting for it to be replaced.
**If you extended `SettingService` to work around the old cache behaviour, remove that subclass.** Before this release the write paths did not drop the cached snapshot, and some installations patched around it with a child class of their own that re-declared the cache key — typically `private const CACHE_KEY = 'settings';`. `SettingService::CACHE_KEY` is now a **public** constant, and PHP does not allow a subclass to reduce a constant's visibility, so such a class fatals at autoload time on `composer update`:
```
Access level to App\...\YourSettingService::CACHE_KEY must be public
(as in class Lvntr\StarterKit\Domain\Setting\SettingService)
```
The subclass is also obsolete: every write path now calls `Cache::forget()` through `DB::afterCommit()`, so the snapshot is dropped on the outermost commit. Delete the child class, point your container binding (and any `class_alias`) back at `Lvntr\StarterKit\Domain\Setting\SettingService`, then run `composer dump-autoload && php artisan optimize:clear`. Keeping the subclass is not an option even with the visibility corrected — its `'settings'` key would put the plaintext-caching v1 behaviour back. A consumer that never subclassed `SettingService` is unaffected; the kit ships no such subclass in `stubs/`.
### `POST /api/v1/auth/login` now has its own per-account rate limiter
`stubs/routes/api/public-api.php`'s `login` route moves from `throttle:5,1` to a new named limiter, `api-login` (registered by the package itself, in `Lvntr\StarterKit\StarterKitServiceProvider`): `Limit::perMinute(5)->by('ip:...')` **plus** `Limit::perMinute(3)->by('email:...')`. Before this release the endpoint had no per-account cap at all — an attacker spreading login attempts for one account across many IPs never tripped anything. `register` and `two-factor-challenge` are unchanged, still `throttle:5,1`: `register` has no account identity to key on before the account exists, and the 2FA challenge is single-use and keyed to a short-lived server-issued challenge id, so an IP cap is the only axis an attacker can move on either route.
**One axis got looser, deliberately.** An unnamed `throttle:5,1` keys on the domain and IP only — no route component — so `login`, `register` and `two-factor-challenge` previously shared a **single** 5/min bucket per IP. `login` now has its own namespaced bucket, so the three endpoints together allow 10 requests a minute per IP instead of 5. The login route itself is unchanged at 5/min per IP (and now additionally capped at 3/min per email); the whole `/api/v1` group is still bounded by its own `throttle:api` 60/min.
`api-login` is a **separate** limiter from the web `login` one on purpose, not a reuse: the `auth.login_throttle` setting rewrites only the config value Fortify's own route registration reads, so no admin toggle can relax the API's ceiling, and the API does not inherit the web limiter's looser 10/min-per-IP allowance.
**The limiter itself needs no hand-porting.** It is registered by the package, in `Lvntr\StarterKit\StarterKitServiceProvider::configureRateLimiting()`, and not in the published `FortifyServiceProvider` — deliberately. `sk:update` refreshes published files *independently of one another*, so a consumer with a customised provider (preserved on a hash mismatch) and an untouched route file (refreshed) would otherwise be left with a route naming a limiter nobody declared; Laravel answers that with `MissingRateLimiterException`, i.e. a 500 on every API login. Shipping it from vendor removes that failure mode. If you had already added an `api-login` limiter of your own, it still wins: your provider boots after the package's.
**One thing may still need hand-porting.** `routes/api/public-api.php` is a published stub, and an on-disk copy that no longer matches the shipped hash is skipped, not overwritten, by `sk:update`. If you customised it, change the `login` route's middleware from `throttle:5,1` to `throttle:api-login` yourself. Until you do, the endpoint keeps its old IP-only ceiling and gains no per-account cap — it will not error, it simply stays as it was.
### New `starter-kit.security.csp_nonce` flag — opt-in, breaks an unpublished-Blade upgrade if turned on blind
A new config key, `starter-kit.security.csp_nonce` (env `STARTER_KIT_CSP_NONCE`), switches the `SecurityHeaders` middleware's `script-src` directive from `'unsafe-inline'` to a per-request `'nonce-'`, generated through `Vite::useCspNonce()` before the response renders. With a nonce present, a browser **stops honouring `'unsafe-inline'` entirely** — this is what makes the flag close a real gap (an injected inline `