diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index eb284e4..d0f17ff 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -47,10 +47,15 @@ jobs: run: | version="${GITHUB_REF_NAME#v}" notes=$(awk -v v="$version" ' - $0 ~ "^## \\[" v "\\]" { f=1; next } + index($0, "## [" v "]") == 1 { f=1; next } f && /^## \[/ { exit } f { print } ' CHANGELOG.md) + # A final release must describe itself; only a pre-release (vX.Y.Z-rc.N) may fall back. + if [ -z "$(printf '%s' "$notes" | tr -d '[:space:]')" ] && [[ "$GITHUB_REF_NAME" != *-* ]]; then + echo "::error::CHANGELOG.md has no '## [$version]' section with content; add it before tagging." + exit 1 + fi { echo "body<<__CHANGELOG_EOF__" if [ -n "$notes" ]; then printf '%s\n' "$notes"; else @@ -62,8 +67,9 @@ jobs: } >> "$GITHUB_OUTPUT" - name: Create GitHub release - uses: softprops/action-gh-release@efb35369e0ad2afab669f228072c1b0d510eae64 # v3.0.3 + uses: softprops/action-gh-release@8a0cd651e5b2365bd640854a3fa5dfc70e4875f3 # v3.0.4 with: generate_release_notes: true + prerelease: ${{ contains(github.ref_name, '-') }} body: ${{ steps.changelog.outputs.body }} files: settings.cdx.json diff --git a/CHANGELOG.md b/CHANGELOG.md index d07fc95..fa4cd17 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,526 +7,153 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] -### Added - -- Automatic promotion. A store set to `promote: auto` (or every store, with - `LARANAIL_SETTINGS_PROMOTE=auto`) copies its runtime file into its database layer once, the - first time the connection answers and its table exists: straight after `migrate`, or after the - first request or queued job that finds the database ready, once the response is sent. It runs as - the system under the promotion lock, skips keys that already have a row, and archives the file. - A failure is logged and retried on the next run, and reads keep coming from the file until then. - `manual`, the default, keeps today's behaviour. The runtime configuration's - `promote($store, $mode)` sets it per request, and `Settings::promoteWhenReady()` promotes now - when it can and otherwise sets the store to `auto` for the rest of the request, job or command. - `doctor` warns about an `auto` store whose file is still there while its database is ready. -- Selective promotion. `promote` also takes a long form, `['mode' => 'auto', 'include' => - ['settings', 'owners'], 'owners' => ['user', 'team']]`: `settings` are the application-wide - values, `owners` the per-owner values, optionally limited to some morph aliases (`['*']`, the - default, is everything; the runtime file holds setting values only, so these are the only - kinds). The archive keeps the whole original file, and the values left out are written back to - the runtime file in one rename, so they keep answering reads from there. `laranail::settings.promote` - takes `--only=settings,owners` and `--owner=user,team`, `promoteWhenReady()` and the runtime - configuration's `promote()` take a `PromotionSelection`, and `PromotionReport` lists what was - `kept`. -- Fluent promotion setters: `Settings::store('settings')->promotion()->auto()->only('owners') - ->forOwners('user')` (also `manual()`, `everything()`, `forAllOwners()`), for the current - request or job. Each option is resolved in one place, highest first: the fluent setters, the - runtime configuration, persisted configuration, then the configuration file. Automatic promotion, - `promoteWhenReady()`, `doctor` and the command's defaults all read that result, and `SettingsFake` - supports the chain. -- `laranail::settings.show` reads a cached answer's row past the cache and prints its `Stored` - version and whether the `Cache` is stale. -- `doctor` warns when a dedicated store's `owner_id` column does not have the type of the owner - table's key (`: owner key`). - -- `laranail::settings.show {key} [--store=] [--owner=] [--locale=] [--reveal]`: prints how one - setting resolves (value, layer, scope, type, version, locked, encrypted and sensitive flags, and - the latest audit entry), through the same `ExplainSetting` action as `explain()`. Sensitive and - encrypted values print as `[protected]` unless `--reveal` is given. -- `doctor` warns, without failing, about a stored value or a code or config definition whose key's - first segment is not its category's slug (`: category keys`, `definitions: category keys`). -- `Logging\LogContext`: every operational log entry's context now starts with `store`, `key`, - `scope`, `actor` and `channel`, in that order and `null` where the entry has none. Refusals, - write retries, cache failures, alert failures, skipped persisted entries, runtime configuration - changes and log-sink audit entries all use it, so one log query finds every entry about a setting. +The first public release. `Added` describes the package; `Changed`, `Removed`, `Fixed` and +`Security` matter only to a checkout taken before the first tag, and [Upgrading](docs/upgrading.md) +has the steps for one. -- Consumer conveniences on the `Settings` contract, each a thin delegation onto the existing read - and write paths: `missing()`, `many()` (keys or `key => default` pairs), `setMany()` and - `forgetMany()` (one write each, not atomic), `remember()` (read-through: writes a computed value - once through `set()`), `all(?string $prefix)` (every visible value of the handle's scope, the PHP - form of the REST listing) and `definitions()` (the store's definitions, the PHP form of - `GET stores/{store}/definitions`). `SettingsFake` implements all of them and records the writes. - The facade's docblock now lists every contract method. -- A namespaced `Simtabi\Laranail\Settings\settings()` helper (`use function …\settings;`): the - handle with no argument, else `get($key, $default)`. Deliberately not a global function. -- `Services\Resolution\ScopeKeys`: the key walk a listing uses, shared by `all()` and the REST - listing (moved verbatim out of `Actions\Reads\ReadSettings`). -- Documentation: a complete PHP API reference (every contract method with signature, example, - exceptions and events, plus the facade, the helper, `HasSettings` and typed settings), a per-route - REST API reference with every problem type, an exceptions reference, the six approval events and - a call-to-event table in the events reference, and recipes for an admin UI on the REST API, SPA and - mobile clients, a per-user preferences screen, multi-tenancy, auditing a change, moving settings - between environments and typed settings. Tests fail when a contract method, route, event, - exception, command or config key (and its default) goes undocumented. - -- Approvals (design §16.7, Phase 4b): a write (`set`, `forget`, `lock`, `unlock`) to a setting - whose definition is `requiresApproval()`, or whose key matches the store's new - `approvals.keys` globs, opens a change request instead of writing. A - `settings_change_requests` table (one per connection, ULID keys, tenant column in column-mode - tenancy) is created by the one migration when the new schema switch `approvals.table` is on (the - default). The proposed value is validated and stored as the values table would store it, so an - encrypted definition's value is encrypted at rest. `$settings->propose()` and - `$settings->approvals()` (`Approvals\Approvals`: `pending()`, `status()`, `key()`, `for()`, - `get()`, `find()`, `approve()`, `reject()`, `cancel()`). Approving needs `approve`; the - requester cannot approve their own request unless `approvals.allow_self`; `approvals.min_approvals` - approvals apply the change through the write pipeline against the base version, so a setting - that changed meanwhile makes the request `stale`; requests expire after `approvals.expire_after` - days. Events `ChangeRequested`, `ChangeApproved`, `ChangeApplied`, `ChangeRejected`, - `ChangeCancelled`, `ChangeStale` (the alert listener knows the first four of interest); audit - actions `propose`, `reject`, `cancel` with the change request's id in the `change_request` - column; `laranail::settings.prune-changes`. Enums `ChangeStatus`, `ChangeOperation`; exceptions - `UnknownChangeRequest`, `ChangeRequestClosed`. -- Export, import and store diff (G-10, G-42): `$settings->export(ExportMode)`, `import()`, - `previewImport()`, `compare()`; `laranail::settings.export` (`--with-secrets`, `--decrypt` with - the store name typed), `.import` (dry run unless `--apply`; `--trusted` for locks and system - categories) and `.diff`. Documents name categories by slug and settings by scope, key and locale, - never a numeric id. Imports create categories first and write each setting through the write - pipeline, in one transaction. Gated by `export` / `import`, audited. -- Importers (G-43) behind `Contracts\Importer`: `spatie` (spatie/laravel-settings' table), - `toolkit` (laranail/toolkit's JSON store) and `akaunting` (akaunting/laravel-setting's table), - configured in `importers`, used with `import --from=`. No dependency on any of them. -- `laranail::settings.reencrypt` (`Actions\ReencryptSettings`): encrypts live values, history and - change requests again under the current key, leaving unreadable payloads untouched and - reporting them. `laranail::settings.rescope {from} {to}` (`Actions\RescopeOwners`, G-30) renames - an owner alias in values (with `settable_type` and per-row slugs), history and change requests. -- `doctor` also reports encrypted values no key can read, open change requests past their expiry, - schema drift on the history, change requests and persisted configuration tables, and persisted - entries skipped as invalid. -- Persisted configuration (§16.11): with the new schema switch `configuration.persisted`, a - `settings_stores` table holds stores and layers saved through - `$settings->persistedConfiguration()` (and the REST API), and definitions are saved to the - definitions table. Validated like configuration, gated (`manage_stores`, `manage_definitions`), - audited, read on first use and merged in `configuration.sources` order; an invalid entry is - logged and skipped. -- The REST API (§16.10, Phase 4c), off unless `http.enabled`: 39 routes under `http.prefix`/v1 - named `laranail-settings.api.*`, through `http.middleware`, the `laranail-settings` rate limiter - and an `Idempotency-Key` cache for writes. Route → FormRequest → controller → the same actions - the PHP API runs (`Enums\Capability`), API resources, ETags with `If-Match` (412), `202` with a - change request for approvals, cursor-paginated lists, values the actor may not view left out, - RFC 9457 problem details, `Contracts\OwnerResolver` (morph map by default; unknown alias 404). - New read actions `Actions\Reads\{ReadSetting, ReadSettings, ExplainSetting, ReadHistory, - ListStores, ListDefinitions}` and `Actions\Categories\ListCategories`. - `laranail::settings.openapi` writes an OpenAPI 3.1 document; the tests validate responses - against it. -- Typed settings classes (Phase 5): `Typed\TypedSettings` with `load()`, `save()`, - `register()` and the attributes `#[Store]`, `#[Group]`, `#[Key]`, `#[Encrypted]`, `#[Type]`; - typed classes resolve from the container loaded, and `typed.classes` registers their - definitions. Settings migrations (G-17): `Typed\SettingsMigration` with `rename()`, `move()`, - `add()` and `delete()` (`Actions\MigrateSettings`, audited as `migrate`). -- Value history (design §4.3, Phase 4): a `settings_history` table, one per connection like the - audit table, created by the one migration when the new schema switch `history.enabled` is on - (the default; recorded in the schema file as `history_table`, and read as off from a file - recorded before it existed). Every set, forget, lock, unlock and rollback on a database layer - appends the payload before and after exactly as stored (encrypted values stay encrypted), the - operation, the version, the causer (the actor; `system` without one), the reason and the row's - `uid` (or id) as `setting_ref`, in the same transaction as the change, so a failed history - insert rolls the change back. A forget writes a tombstone, and a key set again continues its - version from the history. Column-mode tenancy adds a `tenant` column. New config - `tables.history`, `history.enabled`, `history.keep_days` (365) and `history.keep_versions` - (null). -- `$settings->history()` (`History\HistoryQuery`: `key()`, `for()`, `global()`, `store()`, - `locale()`, `since()`, `until()`, `versions()`, then `get()`, `cursor()` or `paginate()`), - gated by `view_history`; payloads of encrypted or sensitive settings are removed for an actor - without `view_sensitive`. `$settings->rollback($key, $toVersion)` writes an earlier value as a - new version through the normal write pipeline (gated by `rollback`, step-up verification per - `verification.abilities`, audited as `rollback`) and returns the new version. - `$settings->historyDiff($key, $from, $to)` returns a `Data\HistoryDiff`, decrypting only for an - actor holding `view_sensitive` (or a trusted call). Actions `QueryHistory`, `RollbackSetting`, - `DiffHistory`, `PruneHistory` and the bundle `HistoryActions`; `Services\Database\HistoryRepository`; - `Data\HistoryEntry`, `HistoryFilter`, `HistoryPage`, `HistoryDiff`; `Enums\HistoryOperation`; - `Exceptions\HistoryUnavailable`; `DatabaseDriver::reference()`; `SettingWriter::causedBy()` and - `rollback()`. -- `laranail::settings.history {key}` (`--store`, `--owner=alias:id`, `--locale`, - `--diff=FROM..TO`, `--rollback=`, `--reveal`, `--limit`) and `laranail::settings.prune-history` - (`--days`, `--versions`; gated by `prune`, audited). -- Events: `SettingLocked`, `SettingUnlocked`, `SettingRolledBack`, `CategoryMoved`, - `CategoryRenamed`, `DefinitionsSynced`, `AuditPruned`, `HistoryPruned`, `OrphansPruned` (all - after commit), and `AccessWasDenied` and `VerificationWasRequired`, dispatched at once by the - access guard when it refuses (the refusal throws, so its transaction rolls back). None carries - a value. -- Built-in listeners, switchable under `listeners.*`: `Listeners\SendSettingsAlert` (on, but - needs `alerts.enabled`) and `Listeners\LogSettingsEvent` (off; every event to the operational - log, refusals at `warning`). -- Alerts (`alerts.enabled`, default `false`): Laravel notifications (`Notifications\SettingsAlert`) - sent when an event matches a rule in `alerts.rules` (events, key globs, stores, - `sensitive_only`, outcomes; `notify.mail`, `notify.slack` when - laravel/slack-notification-channel is installed, `notify.database`; `queue`), throttled per - rule and key for `alerts.throttle` seconds in `alerts.cache`. An alert carries identifiers only - (`Data\AlertContext`), never a value; a test renders every channel of alerts about a seeded - secret and fails if it appears. An alert that cannot be sent is logged, never thrown. - `Data\AlertRule`, `Support\EventSummary`. -- `CategoryGuard::run()` takes an optional list of further events to dispatch after commit. -- The settings cache (design phase 3, §7.5): `Drivers\CachingDriver` puts each database layer - behind `Caching\SettingsCache`, which caches every scope's raw rows (a "bag", every locale, - misses as empty bags) keyed by a hashed, length-prefixed tuple of connection, database, tenant, - store, table and scope. Invalidation replaces ULID generation tokens (per scope, per store, and - a global epoch) on every write path: set, forget, lock, unlock, flush, owner deletion and - promotion, after the write's transaction commits. Past `cache.ttl` a bag is still answered for - `cache.stale` seconds through `Cache::flexible()` while it is refreshed; a refresh can never - restore an invalidated value. Reads inside an open transaction and while bootstrap mode skips - the layer go straight to the database. A failing cache store falls back to the database and is - logged. New keys `cache.enabled` (default `true`), `cache.store`, `cache.prefix`, `cache.ttl` - and `cache.stale`. -- `laranail::settings.warm` and `laranail::settings.clear-cache` (`--store=*`), and - `clearCache()` / `warmCache()` on a settings handle, through the new `Actions\WarmCache` and - `Actions\ClearCache`: gated by `manage_stores` when an actor is present and audited as a - `manage_stores` entry (`meta.operation` `cache.warm` / `cache.clear`). -- `Store::isCached()`, `forgetCached()`, `forgetCachedStore()` and `warmCache()`; - `Data\CacheTarget`; `Support\BagCodec`. -- A phpbench benchmark of one request's reads with and without the cache (`benchmarks/`, - `phpbench.json`, `composer bench`). phpbench installs into `tools/phpbench/`, outside the - package's dependencies. +### Added -- Tenancy (`tenancy.mode`: `none`, `column`, `database`; recorded in the schema file). Column - mode adds a `tenant` column to the values, categories and audit tables, leading their unique - keys; every row is stamped with the current tenant and every query, the audit trail and the - models included, is limited to it. A `TenantDiscriminator` contract (`NullTenantDiscriminator`, - `ClosureTenantDiscriminator`) picked by `tenancy.discriminator` (`auto` detects stancl/tenancy, - then spatie/laravel-multitenancy; both only suggested). Preloaded records are kept per tenant - in every mode. New enum `TenancyMode`. -- Default categories: `DefaultCategoriesSeeder` (in `database/seeders`, registered with the - application's `db:seed`) creates `seed.categories` (general, appearance, localisation, mail, - notifications, security) as system categories in `seed.stores`, through the settings API as - the system actor; idempotent; `seed.enabled` switches it off. `NewCategory` takes `system`. -- Eloquent models (`Models\Setting`, `SettingCategory`, `SettingDefinition`, - `SettingAuditEntry`) and their factories in `database/factories`, for tests, seeding and admin - screens; they follow the recorded shape and tenancy. The engine itself stays on the query - builder. -- Schema switches (design phase 2b, §4.0): `identity.mode` (`slug_uid`, `slug_per_row`, - `uid_only`), `ids.type` (`bigint`, `uuid`, `ulid`; follows `laranail.db-tools.id_type` unless - set) with matching category keys, `ids.owner_key` (`string`, `typed`), `stores..mode` - (`polymorphic`, `dedicated` with an `owner_id` foreign key, `owner.*` and a polymorphic - `fallback` store for global values), `stores..soft_deletes` (forget trashes; the next - write restores through the version check, never as a conflict) and `categories.soft_deletes`, - `translations.mode` (`lang`, `json`; `NewCategory` `translations`, `Category::$titles` and - `titleIn()`), and `tables.definitions`. New enums `IdentityMode`, `IdType`, `OwnerKeyType`, - `StoreMode`, `TranslationsMode`. -- The schema-shape file (`database/settings-schema.php`, `schema.path`): `install` records the - shape its migrations produce and `make-store` adds its store; the migrations and the runtime - read the record, not live configuration (`SchemaShape`, `StoreSchema`, - `SchemaShapeRepository`). -- `doctor` drift detection: configuration against the schema file, the file's shape version - against this release, unrecorded database stores, and the live tables against the recorded - shape (missing or unexpected columns, wrong `id` type). `doctor --fix` syncs definitions. -- The optional `settings_definitions` table (D-6, `definitions.table`) with its migration, - `laranail::settings.sync-definitions` (code and config definitions as `is_system` rows; stale - ones removed; runtime rows never touched; gated by `manage_definitions`, audited), and the - `database` definition source for keys no code covers, with rules filtered through - `definitions.allowed_rules`. `definitions.sources` selects `code`, `config` and `database`. -- `$settings->audit()`: an immutable audit query (`for()`, `global()`, `store()`, `key()`, - `action()`, `outcome()`, `since()`, `until()`, then `get()`, `cursor()` or `paginate()` returning - an `AuditPage`), gated by `view_audit`; `Actions\QueryAudit`, `Data\AuditFilter`. -- A plain `set()` retries once after a concurrent change, re-reading the row under a row lock - (`writes.retry_on_conflict`, default on; logged). `SettingWrite::$expectedVersion` makes a - write conditional on a version and is never retried (`SettingWriter::setExpecting()`). -- The `prune` ability (and audit action): `Actions\PruneOrphans` and `Actions\PruneAudit` need it - when called with an actor, and both prunes are audited. -- `readiness.flush_on`: schema readiness is forgotten on tenancy events (stancl/tenancy and - spatie/laravel-multitenancy by default), since db-tools has no tenant hook of its own. -- The §13 switch matrix: a pairwise set of 10 shapes covering all 141 value pairs (both - asserted) on SQLite, MySQL and PostgreSQL, and the full 576-shape product weekly - (`LARANAIL_SETTINGS_MATRIX=full`, CI job `matrix-full`). +- **Settings engine.** The `Settings` contract, facade and namespaced `settings()` helper, for any + owner: the application, or a model by morph alias and id (`OwnerRef`, `Settable`, and + `HasSettings` with `withSettings()` eager loading and deletion with the owner). Immutable + `store()`, `for()`, `locale()`, `as()`, `asSystem()`, `asCurrentActor()` and `because()` + handles; `get`, `lookup`, `has`, `missing`, `many`, `all`, typed getters, `explain`, `set`, + `setMany`, `forget`, `forgetMany`, `remember`, `lock`, `unlock`, `flush` and `preload`. A stored + `null` is an answer, distinct from absence. Owners can inherit through their parents, then the + global value. +- **Layered stores** that work before the database exists and after it does: the `database`, + `json`, `php`, `config` and `array` drivers (`DriverType`), custom drivers through + `DriverFactory::extend()`, and `make-store` for further stores. The database layer + version-checks every write (`ConcurrentModification`; a plain `set()` retries once under a row + lock), and reports an outage as `DriverUnavailable` or `DriverFailure`, never as a PDO error. +- **Bootstrap and promotion.** Bootstrap mode skips the database layer only on positive evidence of + an install in progress (`bootstrap`, `stores..bootstrap`, or laranail/installer-headless). + `promote()` and `laranail::settings.promote` copy runtime-written values (never shipped defaults) + into the database under a lock and archive the file. `promote: auto` does it once, as soon as the + database is ready; `include`/`owners` (and `--only`/`--owner`) promote part of the file; + `promoteWhenReady()` and the fluent `promotion()` setters choose it per request. +- **Definitions** in code, config, typed classes or the definitions table (`definitions.sources`): + type (caster aliases and registered enums), default, validation rules, encryption, sensitivity, + locks, localisation, owner restrictions, categories, step-up verification and approval. + `laranail::settings.sync-definitions`. +- **Typed settings** (`Typed\TypedSettings` with `#[Store]`, `#[Group]`, `#[Key]`, `#[Encrypted]`, + `#[Type]`; `typed.classes`) and settings migrations (`Typed\SettingsMigration`: `rename`, + `move`, `add`, `delete`). +- **Categories**: create, rename, move, delete, get and list, per store, with system categories + and `DefaultCategoriesSeeder`. +- **Access control.** `Actor` (users, tokens, services and the system), actor resolvers (`guard`, + `sanctum` with token abilities as a ceiling), authorizers (`gate` on + `laranail-settings.`, `permissions`, closures, chains) over 18 abilities (`Ability`), + deny-by-default for undefined abilities, `authorization.require_actor`, guarded locks with + `override_lock`, `view_sensitive` redaction, and step-up verification (`password_confirmation`, + `actor`, `none`, custom). +- **Audit trail** of every write, refusal and configuration change, never holding a value, through + the `auto`, `database`, `log` and `null` sinks; `$settings->audit()` queries it, and + `prune-audit` trims it. +- **History** of every value change on a database layer, written in the change's transaction: + `$settings->history()`, `rollback()`, `historyDiff()`, `laranail::settings.history` and + `prune-history`. Encrypted payloads stay encrypted, and payloads are removed for an actor without + `view_sensitive`. +- **Approvals.** A write to a setting that needs approval opens a change request instead: + `propose()`, `approvals()` (`approve`, `reject`, `cancel`, `find`, listings), minimum approvals, + no self-approval by default, expiry, and `stale` when the setting changed meanwhile; + `prune-changes`. The proposed value is stored as the values table would store it. +- **Encryption** at rest for encrypted definitions, in values, history and change requests; + `laranail::settings.reencrypt` after a key change. +- **Caching** of each scope's rows in front of every database layer, invalidated by generation + tokens after commit, with stale-while-revalidate (`cache.*`), `warm` and `clear-cache`. +- **Tenancy** (`tenancy.mode`: `none`, `column`, `database`) with a `TenantDiscriminator` that + detects stancl/tenancy and spatie/laravel-multitenancy; in `column` mode every tenant-owned row + and query carries the tenant. +- **Export, import and diff** of a store (`export`, `import`, `previewImport`, `compare`, and the + `export`, `import`, `diff` commands), with encrypted values redacted unless asked for, and + importers for spatie/laravel-settings, laranail/toolkit and akaunting/laravel-setting. +- **Persisted configuration** of stores, layers and definitions in the database + (`configuration.persisted`), validated like configuration, gated and audited. +- **REST API**, off unless `http.enabled`: 39 routes under `http.prefix`/v1, named + `laranail-settings.api.*`, running the same actions as the PHP API, with ETags and `If-Match`, + `202` for approvals, cursor pages, `Idempotency-Key` replays, a rate limiter and RFC 9457 + problem details. +- **Events** for every change, refusal, approval, category, promotion and prune, carrying + identifiers only; built-in listeners for alerts (mail, Slack, database notifications, throttled) + and logging. +- **Commands** under `laranail::settings.*`: `install`, `doctor` (readiness, missing columns, + configuration problems; `--fix`), `show`, `history`, `promote`, `make-store`, `sync-definitions`, + `export`, `import`, `diff`, `reencrypt`, `rescope`, `warm`, `clear-cache`, `prune-audit`, + `prune-history`, `prune-changes` and `prune-orphans`. +- **Testing**: `Settings::fake()` with assertions for writes, forgets and audit entries; Eloquent + models and factories for every table. +- One migration for every table, tested on SQLite, MySQL 8.4 and PostgreSQL 17 in CI. +- `values.max_bytes` (`LARANAIL_SETTINGS_MAX_VALUE_BYTES`, default 1 MiB, `null` for no limit): + every write path (the PHP API, REST, import, promotion, approvals) refuses a value whose encoded + payload is larger, with `InvalidSettingValue` (REST `422 invalid-value`). ### Changed -- REST listings read `http.page_size` (default 50, clamped to 1 to 200) for a request without - `?limit=`; the key was documented as reserved and every listing used 50. - Sanctum token abilities are vendor-scoped: `laranail-settings:` and - `laranail-settings:*`, in place of `settings:` and `settings:*`. Issue tokens with the - new names; a token holding only the old names is refused. -- Problem `type` URIs point at sections of the exceptions reference, - `https://opensource.simtabi.com/documentation/laranail/settings/tools/exceptions#` - (`#http-status` for every `http-` type), instead of `…/settings/problems/`, - which had no page. Each type has an anchor there, and a test holds the two together. -- `composer test-coverage` reports coverage without a fixed `--min` floor; coverage ratchets - instead (see CONTRIBUTING). -- With the REST API on, an `authorization.driver` that cannot be built fails closed (every actor - denied, API requests answer `401 actor-required`, one warning logged) instead of raising - `InvalidConfiguration` on every call. Without the API it still raises. -- The table shape is fixed, with `tenancy.mode` as the one switch: every table is keyed by a ULID, - each values row has a unique `uid` (the history's `setting_ref`) and no `slug`, `settable_id` is - `string(36)`, and titles, labels and descriptions are JSON maps of locale to text. The migration - always creates the definitions, history, change requests and persisted configuration tables, and - every values table has `deleted_at`. In `column` mode each tenant-owned table gets `tenant` in its - unique and lookup keys. Dedicated stores keep their `owner_id` foreign key. -- History is always recorded for a store with a database layer, and change requests always have - their table. A store on file layers only still raises `HistoryUnavailable` and - `ApprovalUnavailable`. -- `definitions.sources` defaults to `['code', 'config']`: add `database` to read definitions saved at - runtime, which costs one query per store per request. -- `configuration.persisted` now only turns the persisted configuration on and off; its table always - exists. -- Deleting a category deletes the row; creating the slug again makes a new category. -- The Eloquent models are the data layer for categories, definitions, audit, history and change - requests: `SettingsModel` holds the ULID keys, the connection and the tenant scope - (`Models\Scopes\TenantScope`, lifted with `allTenants()`), and the new `SettingHistory` and - `SettingChangeRequest` join `Setting`, `SettingCategory`, `SettingDefinition` and - `SettingAuditEntry`. The database driver still reads and writes values through the query builder - and takes the table name from `Setting::tableFor()`. `ModelContext` now holds the configuration - and the current tenant only. -- `doctor` checks that every column the package uses exists, instead of comparing a recorded shape - with configuration and the database. -- `QueryHistory::handle()` returns an Eloquent builder of `SettingHistory`. - -- Prepared for the public release. Source, config, migration, route, helper and test comments are - rewritten as short plain docblocks, with no references to internal planning documents; the - design rationale they carried is now in `docs/architecture.md`. Comment lines in `src/` went - from 3,784 to 2,743. No behaviour changed. -- The migration builds each table in one method with a flat column list; the values table's - indexes moved to `indexValues()`. Every column, type, index name and foreign key is unchanged, - verified by diffing the SQLite schema of the default and the full shape before and after. -- The service provider is split into one private method per concern (`registerDrivers()`, - `registerStores()`, `registerCache()`, `registerLogging()`, `registerAudit()`, - `registerAccess()`, `registerAlerts()`, `bootReadinessFlush()`, `bootListeners()`, …), so - `register()` and `boot()` read as a table of contents. No binding changed. -- README: the Tests, Static analysis and MIT badges, with a note that the package is not on - Packagist; `.gitattributes` also export-ignores `.claude`. -- The package is wired the way Laravel wires an application (conventions review, 2026-11-10). - `routes/api.php` declares every REST route by hand in named, nested groups, each `http.routes` - switch an `if` around its group; the service provider loads it once, under `http.prefix`/v1 and - the `laranail-settings.api.` name prefix. URIs, names, methods and middleware are unchanged (39 - routes). `routes/web.php` is no longer loaded while it holds no routes. -- `http.prefix` reads `LARANAIL_SETTINGS_HTTP_PREFIX` (default still `api/settings`); slashes are - trimmed and an empty prefix mounts the API at `/v1`. Change it when the application already has - routes under `/api/settings`: Laravel keeps the last route registered for a method and URI. -- Most classes are autowired, with their lifetime as `#[Scoped]` / `#[Singleton]` on the class and - their configuration as `#[Config]` on the parameter; the service provider binds only what - configuration chooses or validates (1,180 lines to about 700). Closure collaborators became - injected ones: one `Support\Clock` (Laravel's `Date` seam) for every timestamp, the operational - log for write retries and cache failures, the event dispatcher for skipped layers, and a - `Services\Definitions\Definitions` service for "which definition applies", which replaced a - provider closure and two copies of the same rule. -- `SettingsManager` takes every collaborator, required, and its fluent methods return a copy; the - "built without X" `LogicException`s are gone. `CategoryManager`, `Approvals` and - `PersistedConfigurationEditor` take their actions and are narrowed with `in($store, $actor)`. -- REST controllers take their actions per method, return JSON resources and resource collections - (bodies unchanged), and validate each write with its own form request. -- Each exception names its HTTP status and problem type (`STATUS`, `TYPE`); `Problems` renders them - and reads its titles through the translator. Messages are read through Laravel's translator - (`laranail/settings::settings.*`), `__()` and `trans_choice()` in the commands. -- Typed settings classes listed in `typed.classes` are bound when the application boots; the global - `beforeResolving` hook is gone, so a class not listed resolves unloaded (build it with - `::load()`). -- The REST rate limiter is registered through package-tools' `registerRateLimiter()` and reads - `http.rate_limit` per request. -- Configuration is read with the repository's typed getters, which throw on a value of the wrong - type where the old reader fell back to the default (a digit string for a number is now an error). - -- A write to a setting that needs approval opens a change request where the store can hold one; - `ApprovalUnavailable` is now raised only where it cannot (no active database layer, or no - change requests table). `SetSetting`, `ForgetSetting`, `LockSetting` and `UnlockSetting` return - the change request they opened (null when they wrote), and `WriteGuard::run()` takes an optional - proposal and returns it. -- The `Settings` contract gains `propose()`, `approvals()`, `export()`, `import()`, - `previewImport()`, `compare()` and `persistedConfiguration()` (pre-1.0; `SettingsManager` and - the fake implement them). -- The schema-switch matrix covers `approvals.table`: 11 pairwise shapes for 261 pairs per pull - request, 4,608 shapes in the weekly full product. -- The test suite runs with a 512 MB memory limit (`phpunit.xml`). -- Every service now lives under `Services\` (Phase 4 plan §1), moved verbatim: - `Services\Database\{AuditRepository, CategoryRepository, DefinitionsRepository, SchemaInspector, - SchemaShapeRepository}`, `Services\Stores\{SettingWriter, StoreRegistry}`, - `Services\Resolution\{Resolver, PreloadedRecords}`, `Services\Access\{AccessGuard, Auditor}`, - `Services\Configuration\RuntimeConfiguration`, - `Services\Definitions\{DefinitionRegistry, DatabaseDefinitions}`, - `Services\Tenancy\TenantDiscriminators`, `Services\Casting\CasterRegistry`, - `Services\Values\ValuePipeline`, `Services\Drivers\DriverFactory` and - `Services\Cache\SettingsCache`. The package's own code uses the new names. Architecture tests - keep contract implementations out of `Services\` and every `*Repository` / `*Registry` in it. -- The `Settings` contract gains `history()`, `rollback()` and `historyDiff()`. A third-party - implementation must add them (pre-1.0; `SettingsManager` and the fake implement them). -- With history on, a key set again after a forget continues its version (previously it started - again at 1), so "version N" names one value. -- The access guard dispatches `AccessWasDenied` / `VerificationWasRequired` when given a - dispatcher (the container's guard is); `PruneAudit`, `PruneOrphans` and `SyncDefinitions` - take an optional dispatcher for their new events. -- The schema-switch matrix covers `history.enabled`: 11 pairwise shapes for 217 pairs per pull - request, 2,304 shapes in the weekly full product. -- The code is layered entry points → actions → services → support, held by architecture - tests. Database work moved out of actions into `Database\AuditRepository` (the audit sink, - query and prune), `Database\DefinitionsRepository` (definitions sync and reads) and - `Database\SchemaInspector` (`doctor` and install's foreign-table check); the tenant adapters - into `Tenancy\TenantDiscriminators`; the transaction-and-audit sequence of every write, - category change and promotion into `Support\AuditedTransaction`; shared helpers into - `Support\Json`, `Support\Translations`, `Support\DatabaseValues` and - `Support\ConfigValues`, and `Scope::of()`, `Scope::fromString()`, `Scope::owner()`, - `Store::requireDatabase()`, `CategoryRepository::of()`. Behaviour, messages and audit entries - are unchanged. -- `FindOrphans` finds orphaned owners' settings; `PruneOrphans` removes them. -- With caching on (the default), a store's database layer is a `CachingDriver` in front of the - `DatabaseDriver`; `->database()` still returns the `DatabaseDriver`. Rows changed past the API - (raw queries, `Models\Setting` saves) are not seen until `clear-cache` runs or the bag expires. -- `Contracts\Settings` gains `clearCache()` and `warmCache()`; `Actions\StoreActions` gains the - optional `warmCache` and `clearCache` actions. + `laranail-settings:*`, in place of `settings:` and `settings:*`. +- The table shape is fixed, with `tenancy.mode` as the one switch: ULID keys, a unique `uid` per + values row, `string(36)` owner ids, JSON title maps, and the definitions, history, change + requests and persisted configuration tables always created. +- The default store's layers are `['database', 'runtime', 'shipped']`, and `audit.sinks` defaults to + `['auto']`. +- `definitions.sources` defaults to `['code', 'config']`; add `database` to read definitions saved + at runtime. +- REST listings read `http.page_size` (default 50, 1 to 200) when no `?limit=` is given. +- Problem `type` URIs point at sections of the exceptions reference. +- Configuration is read with typed getters: a value of the wrong type is an error, not the default. +- Typed settings classes listed in `typed.classes` are bound at boot; one not listed resolves + unloaded. ### Removed -- Removed with the owner's approval (2026-11-10), before the first tag, with the fixed schema: - the config keys `schema.path`, `identity.mode`, `ids.type`, `ids.owner_key`, - `translations.mode`, `categories.soft_deletes`, `definitions.table`, `history.enabled` and - `approvals.table`; `Database\SchemaShape`, `Database\StoreSchema`, - `Services\Database\SchemaShapeRepository` and the `database/settings-schema.php` file that - `install` and `make-store` recorded; the `Enums\IdentityMode`, `Enums\OwnerKeyType` and - `Enums\TranslationsMode` enums; `DatabaseDriver::newId()`, `shape()` and `schemaOf()`; the - `doctor` checks against a recorded shape; the pairwise schema matrix - (`tests/Feature/Database/SchemaMatrixTest.php`, `tests/Support/Pairwise.php`, test groups - `matrix`) and the weekly `matrix-full` CI job, replaced by a tenancy matrix (`none`, `column`) - in the `database` group; and `docs/tools/schema-switches.md`, whose surviving content is in - `docs/tools/database.md`. -- Removed with the same approval: `Services\Database\CategoryRepository`, - `DefinitionsRepository`, `AuditRepository`, `HistoryRepository` and `ChangeRequestRepository`, - whose queries live on the models and in the actions; and `Models\Concerns\UsesSettingsSchema`, - replaced by `Models\Concerns\BelongsToTenant` on `SettingsModel`. - -- Removed with the owner's approval (2026-11-10), before the first tag: `Http\ApiRoutes`, - `Enums\Capability`, `Http\OpenApi\OpenApiDocument` and the `laranail::settings.openapi` - command; `Http\Middleware\FreshControllers`; the seven action bundles (`SettingActions`, - `StoreActions`, `HistoryActions`, `ApprovalActions`, `TransferActions`, `ConfigurationActions`, - `CategoryActions`); `Http\Requests\BodyRequest`, `Data\Http\BodyInput` and - `Http\Support\ListResponse`; the static `fields()` of the five resources; `Support\Messages` - and `Support\ConfigValues`; and the single-implementation contracts `ReadinessProbe` (with - `Database\SchemaReadinessProbe`), `ValueValidator`, `ValueEncrypter`, `BootstrapEvidence` and - `OwnerResolver`. Inject the action, the concrete class or db-tools' `SchemaReadinessInterface` - instead. - -- The old names of the 19 classes moved into `Services\` (listed under Changed), the - `src/deprecated-aliases.php` file that aliased them, `PruneOrphans::find()` (use - `FindOrphans::handle()`) and `DatabaseDefinitions::localised()` (use - `Support\Translations::nullableText()`). None was ever in a tagged release. - -- The four migration stubs are replaced by one migration, - `database/migrations/create_laranail_settings_tables.php`, which creates categories, the - optional definitions table, every recorded database store's values table (on its own - connection, with that connection's categories and audit tables) and the audit table, in - that order, and drops them in reverse. `install` publishes it; migrations published from the - stubs keep working. `make-store` writes one migration per store, a copy of it pinned to the - store (and connection), instead of up to three stub copies. -- The schema-switch matrix covers `tenancy.mode`: 10 pairwise shapes for 177 pairs per pull - request, 1,152 shapes in the weekly full product. -- The migration stubs read the recorded schema shape (or configuration, when nothing is - recorded) instead of individual config keys, and run on the store's recorded connection. -- `laranail::settings.install` publishes a fourth migration (`create_settings_definitions_table`, - a no-op while the table is off), records the schema file and syncs definitions. -- `laranail::settings.prune-audit` now writes an audit entry for the prune itself. -- The `Settings` contract gains `audit()`. A third-party implementation of the contract must add - it (pre-1.0; `SettingsManager` and the fake implement it). - -- The database layer (design phase 2, default schema): the `database` driver - (`DriverType::Database`) over the query builder, with version-checked writes that raise - `ConcurrentModification`, inserts in a savepoint, and database errors surfaced as - `DriverUnavailable` (unreachable or table missing) or `DriverFailure`, never as PDO exceptions. -- Publishable migrations for `settings_categories`, `settings` (polymorphic, `slug_uid`, - bigint ids, string owner key, binary-collated identity) and `settings_audit`; - `tables.prefix`, `tables.categories`, `tables.audit` and `stores..table`. -- `laranail::settings.install` now also publishes the migrations, and refuses to run over a - table of the same name that is not the package's (D-4). -- Bootstrap mode (`stores..bootstrap`, `bootstrap` / `LARANAIL_SETTINGS_BOOTSTRAP`, or - laranail/installer-headless' `isInstalling()`): the database layer is skipped only on positive - evidence of an install in progress and while the database is not ready, with a `LayerSkipped` - event. Readiness comes from laranail/db-tools and is flushed after migrations and per job. -- Promotion: `$settings->promote()` and `laranail::settings.promote` copy runtime-written values - (never shipped defaults) into the database, skip existing rows unless forced, replay an - archive with `--from`, take a cache lock, and archive the runtime file. `StorePromoting` / - `StorePromoted` events; `PromotionLocked`. -- Categories: `$settings->categories()` with create, rename, move, delete, get and all, gated by - `manage_categories` and audited; `CategoryCycle`, `CategoryStoreMismatch`, `UnknownCategory`; - `CategorySaving`/`Saved`/`Deleting`/`Deleted` events. Definitions' categories are linked per - store (G-33). -- `HasSettings` for Eloquent owners: `settings()`, `withSettings()` eager loading, and deletion - of an owner's settings with the owner (on force delete for soft-deleting models). -- `$settings->preload()` (one read per store for a list of owners) and `$settings->flush()` (an - owner's values, gated by `forget`), with `ScopeFlushing` / `ScopeFlushed` events. -- The `database` and `auto` audit sinks; an allowed change and its audit row commit in one - transaction, so a failed audit insert rolls the change back. `audit.keep_days` and - `laranail::settings.prune-audit`. -- `laranail::settings.make-store`, `laranail::settings.doctor` (readiness, schema drift, - class-name and unlisted scopes, cross-store categories) and - `laranail::settings.prune-orphans`. -- CI runs the `database` test group on MySQL 8.4 and PostgreSQL 17. - -- Access control (design phase 1b): the `Actor` authentication object (`Actor::user()`, - `Actor::system()`, never serialising the model) and `as()`, `asSystem()`, `asCurrentActor()`, - `because()` and `actor()` on the `Settings` contract. A handle with an actor authorizes every - operation, reads included; a handle without one runs as trusted code, audited as `system`. - `authorization.require_actor` refuses actorless calls (`ActorRequired`). -- Actor resolvers behind `Contracts\ActorResolver`: `guard` (default), `sanctum` (token - abilities become a ceiling; `laravel/sanctum` suggested only) and custom classes. -- The enumerator-backed `Ability` enum (17 abilities), `Subject` and `Decision`, and - authorizers behind `Contracts\Authorizer`: `gate` (`laranail-settings.`, default), - `permissions` (`$user->can()`), closures and chains. Undefined abilities deny unless - `authorization.undefined` is `allow`. Denials raise `AccessDenied`, carrying no value. -- Guarded locks: `lock` and `unlock` abilities, and `override_lock` on stores with - `locks.overridable`. Sensitive definitions (`sensitive()`, implied by `encrypted()`) need - `view_sensitive`, and `explain()` redacts what the actor may not see. -- Step-up verification behind `Contracts\Verifier`: `password_confirmation` (default), - `actor`, `none` and custom classes; `requiresVerification()` definitions and - `verification.abilities`; `VerificationRequired`. -- `requiresApproval()` definitions, which raise `ApprovalUnavailable` until approvals ship - with the database layer. -- An audit trail of writes, forgets, locks, unlocks, refusals and configuration changes - (`AuditEntry`, `AuditAction`, `AuditOutcome`) that never records a value, through - `Contracts\AuditSink` sinks `log` (default), `null` and custom classes. -- An operational log on `logging.channel` (or off with `false`) at `logging.level`. -- `RuntimeConfiguration` through `configuration()` and `withConfiguration()`: stores, layers, - drivers, definitions, authorizer, verifier, resolver, audit sinks, log and the actor - requirement for one request, validated like config and bound `scoped`. -- The actions layer: `SetSetting`, `ForgetSetting`, `LockSetting` and `UnlockSetting`, each - taking a DTO (`SettingWrite`, `SettingTarget`) and the actor; the manager delegates to them. -- `Settings::fake()` records audit entries and gains `assertAudited()`, `assertDenied()` and - `auditEntries()`. -- Guards: the package is headless (no view, Blade, Livewire or Filament reference, no - `resources/views`), and write actions are final with a `handle()` method. - -### Changed - -- The default store's layers are now `['database', 'runtime', 'shipped']`: run the migrations - after install, or drop `database` from the layers to stay on files. -- `audit.sinks` defaults to `['auto']` (the database for a store with a database layer, the log - otherwise) instead of `['log']`. -- `Record` gains optional `group`, `category` and `public` fields; `SettingWriter::lock()` and - `unlock()` take an optional definition; `Store`, `StoreRegistry`, `DriverFactory` and - `SettingsManager` take further trailing optional constructor arguments. Existing calls are - unaffected. -- The `Settings` contract gains `flush()`, `preload()`, `categories()` and `promote()`. - -- `SettingWriter::set()`, `lock()` and `unlock()` return the stored `Record`, and `forget()` - the removed one (or null), instead of nothing. Callers that ignored the result are unaffected. -- `SettingsManager` takes its actions, access guard, runtime configuration, actor and reason - as trailing optional constructor arguments. A manager built without them behaves as before - for trusted calls and denies every actor. - -- The settings engine (design phase 1): the `Settings` contract and facade with immutable - `store()`, `for()` and `locale()` handles; `get`, `lookup`, `has`, typed getters, `explain`, - `set`, `forget`, `lock` and `unlock`. -- Layered stores with the `json`, `php`, `config` and `array` drivers, resolved through the - enumerator-backed `DriverType` enum; custom drivers through `DriverFactory::extend()` closures. -- Owners by morph alias and id (`OwnerRef`, `Settable`), store routing by alias, and opt-in - inheritance through parents in their own stores, then the global value. -- Definitions in code or config: types (caster aliases, including registered enums), defaults, - validation of the raw value, encryption, locks, localisation, owner restrictions and - precedence. -- Presence-aware reads: a stored `null` is an answer, distinct from absence. -- `SettingSaving`, `SettingSaved`, `SettingForgetting` and `SettingForgotten` events, dispatched - after commit and carrying identifiers only. -- `Settings::fake()` with `assertSaved`, `assertNotSaved` and `assertForgotten`. -- An exception hierarchy under `SettingsException`. -- Package skeleton on `laranail/package-tools`, with `laranail/console`, `laranail/db-tools` and - `laranail/enumerator` as dependencies. -- `SettingsServiceProvider`, the `laranail.settings` config key and the - `laranail::settings.install` command, which publishes the config under - `laranail::settings-config`. -- Guards: architecture rules, vendor-scoped names read from the live registries, config read - only at the registered key, provider layout, no literal test credentials, and the docs - standard. -- CI: tests, static analysis, Pest mutation testing (minimum score 70), security audit, - release hygiene and a tag-driven release. +Each was removed before the first tag; none was in a tagged release. + +- Config keys `schema.path`, `identity.mode`, `ids.type`, `ids.owner_key`, `translations.mode`, + `categories.soft_deletes`, `definitions.table`, `history.enabled` and `approvals.table`, with the + `database/settings-schema.php` file, `SchemaShape`, `StoreSchema`, `SchemaShapeRepository` and the + `IdentityMode`, `OwnerKeyType` and `TranslationsMode` enums: the shape is fixed. +- `Http\ApiRoutes`, `Enums\Capability`, the OpenAPI generator and `laranail::settings.openapi`: + routes are declared in `routes/api.php`. +- The seven action bundles (`SettingActions`, `StoreActions`, `HistoryActions`, `ApprovalActions`, + `TransferActions`, `ConfigurationActions`, `CategoryActions`): inject the action. +- The `CategoryRepository`, `DefinitionsRepository`, `AuditRepository`, `HistoryRepository` and + `ChangeRequestRepository` services: the queries live on the models and in the actions. +- `Http\Middleware\FreshControllers`, `Http\Requests\BodyRequest`, `Data\Http\BodyInput`, + `Http\Support\ListResponse`, `Support\Messages`, `Support\ConfigValues`, and the + single-implementation contracts `ReadinessProbe`, `ValueValidator`, `ValueEncrypter`, + `BootstrapEvidence` and `OwnerResolver`: inject the concrete class or db-tools' + `SchemaReadinessInterface`. +- The pre-`Services\` class names and their aliases, `PruneOrphans::find()` (use `FindOrphans`) and + `DatabaseDefinitions::localised()` (use `Support\Translations::nullableText()`). +- The four migration stubs, replaced by `create_laranail_settings_tables.php`. + +### Fixed + +- A malformed record in a `json` layer's file (bad key, locale, date or version) is reported as + `DriverFailure` naming the file, instead of an `InvalidKey`, `InvalidIdentifier` or Carbon + exception. +- `DELETE` with `If-Match` (and `ForgetSetting` with an expected version) forgets only at that + version, re-checked under a row lock, so a change made after the check answers `412` instead of + being deleted. +- Two approvals recorded at once both count: the request is re-read under a row lock before an + approval is added. +- A REST `cursor` the listing did not hand out answers `422` instead of the first page. + +### Security + +- A change request is found only in the store that holds it. Before, `approve`, `reject` and + `cancel` through another store's handle or route were authorized against that store and applied + the value to it. +- Persisted configuration refuses `php` and `config` layers, saved or read back. A `php` layer + requires the file it names, so an actor with `manage_stores` could run any PHP file on the server + through the REST API; a `config` layer exposes application configuration. +- REST idempotency replays are keyed by the resolved actor and host as well as the method, path and + key, so two actors the guard cannot tell apart never share a replay. A retry with a different + body is refused with `422` instead of being answered with the first response, and the stored + response is encrypted, since it can hold an encrypted setting's value. +- An audit query without a store filter returns entries of the stores the actor may audit only, + and is refused (`403`) when there is none. Before, it was authorized against the default store + and returned every store's entries. +- A persisted layer may not redefine a layer the configuration file defines, saved or read back; + it could otherwise move a configured store onto another connection, table or driver. diff --git a/README.md b/README.md index b063b63..a2bdef1 100644 --- a/README.md +++ b/README.md @@ -39,7 +39,9 @@ php artisan db:seed # general, appearance, localisation, mail, notifications ``` For multi-tenant applications set `tenancy.mode` before migrating (see -[Tenancy](docs/tools/tenancy.md)). +[Tenancy](docs/tools/tenancy.md)). To keep values per owner, list the owner's morph alias in a +store's `owners` (for example `'owners' => ['user']` under `stores.settings`); an alias no store +lists raises `OwnerNotAllowed`. An application without a database drops `database` from `stores.settings.layers` and keeps its values in `storage/app/private/laranail/settings/settings.json`. diff --git a/config/settings.php b/config/settings.php index 092d943..e795071 100644 --- a/config/settings.php +++ b/config/settings.php @@ -139,6 +139,14 @@ 'retry_on_conflict' => true, ], + /* + | max_bytes: the largest value a write accepts, measured as the encoded + | payload before encryption; null for no limit. + */ + 'values' => [ + 'max_bytes' => env('LARANAIL_SETTINGS_MAX_VALUE_BYTES', 1048576), + ], + /* | The cache in front of database layers. | diff --git a/docs/configuration.md b/docs/configuration.md index aed1397..34bf6df 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -62,6 +62,7 @@ Every key in `config/laranail/settings.php`, read at `config('laranail.settings. | Key | Default | Purpose | |---|---|---| | `writes.retry_on_conflict` | `true` | retry a plain `set()` once after a concurrent change | +| `values.max_bytes` | `1048576` (`LARANAIL_SETTINGS_MAX_VALUE_BYTES`) | the largest value a write accepts, as its encoded payload before encryption; `null` for no limit; a larger value raises `InvalidSettingValue` | | `seed.enabled` | `true` (`LARANAIL_SETTINGS_SEED`) | whether `db:seed` creates the default categories | | `seed.stores` | `[]` | the stores to seed; empty means the default store | | `seed.categories` | general, appearance, localisation, mail, notifications, security | `slug => title` or `slug => [title, description, icon, parent, sort_order, translations]` | diff --git a/docs/tools/audit-queries.md b/docs/tools/audit-queries.md index 9844701..93ce4db 100644 --- a/docs/tools/audit-queries.md +++ b/docs/tools/audit-queries.md @@ -37,7 +37,8 @@ at either end) and `hasMore()`. ## Access With an actor on the handle, every run needs `view_audit` (checked against the filtered store, -key and owner); a denial is itself audited. Without an actor the call is trusted, unless +key and owner); a denial is itself audited. Without `store()`, the query returns entries of the +stores the actor may audit only, and is refused when there is none. Without an actor the call is trusted, unless `authorization.require_actor` is on. Entries never carry a value, encrypted or not, so there is nothing to redact. diff --git a/docs/tools/exceptions.md b/docs/tools/exceptions.md index ea1e715..6f99192 100644 --- a/docs/tools/exceptions.md +++ b/docs/tools/exceptions.md @@ -45,7 +45,7 @@ Messages name the store, key, scope and ability involved, never a value, so they | `UnknownCategory` | `SettingsException` | no category with the slug exists in the store | `404 unknown-category` | | `CategoryCycle` | `SettingsException` | moving a category under itself or a descendant | `422 category-cycle` | | `CategoryStoreMismatch` | `SettingsException` | a category belongs to another store than what refers to it | `422 category-store-mismatch` | -| `InvalidSettingValue` | `SettingsException` | a value failed its definition's rules, cast or locale constraints | `422 invalid-value` | +| `InvalidSettingValue` | `SettingsException` | a value failed its definition's rules, cast or locale constraints, or its payload is larger than `values.max_bytes` | `422 invalid-value` | | `TypeMismatch` | `SettingsException` | a typed getter (`string()`, `integer()`, …) or a typed settings property found another type, or no value | `422 type-mismatch` | | `InvalidIdentifier` | `SettingsException` | a store name, locale, owner alias or filter failed validation | `422 invalid-identifier` | | `InvalidKey` | `InvalidIdentifier` | a key is not lower-case dot notation of `[a-z0-9_]` segments, at most 191 characters; or `many()` got a non-string list entry | `422 invalid-identifier` | diff --git a/docs/tools/persisted-configuration.md b/docs/tools/persisted-configuration.md index 818e58b..c391c24 100644 --- a/docs/tools/persisted-configuration.md +++ b/docs/tools/persisted-configuration.md @@ -29,13 +29,13 @@ $editor->saveDefinition('site.theme', ['type' => 'string', 'default' => 'light', $editor->deleteDefinition('site.theme'); ``` -Store and layer entries take the shape the configuration file gives `stores.` and `layers.`; definitions take the attributes of `definitions.`. Each change is validated exactly like configuration before it is stored, needs `manage_stores` (step-up verification by default) or `manage_definitions`, and is audited. A definition from code or configuration cannot be overridden or deleted here, and a persisted store may not change the layers the configuration file gives a store: moving data between drivers is [promote](commands.md)'s job. +Store and layer entries take the shape the configuration file gives `stores.` and `layers.`; definitions take the attributes of `definitions.`. Each change is validated exactly like configuration before it is stored, needs `manage_stores` (step-up verification by default) or `manage_definitions`, and is audited. A definition from code or configuration cannot be overridden or deleted here, and a persisted store may not change the layers the configuration file gives a store: moving data between drivers is [promote](commands.md)'s job. A persisted layer only adds to the file's: one named like a layer the configuration file defines is refused. It may not use the `php` or `config` driver: the first requires the file it names and the second reads application configuration, so both are defined in the configuration file only. ## Loading Persisted entries are read on first use, never at boot, once per request or job. An entry that fails validation (a layer that no longer exists, a driver that is not registered) is logged to the operational log and skipped, so a bad row never stops the application from booting; `doctor` lists what was skipped. -`configuration.sources` decides precedence: with `['config', 'database', 'runtime']` a persisted entry overrides the file, and a change made in code for one request ([runtime configuration](runtime-configuration.md)) overrides both. Put `database` first to let the file win. +`configuration.sources` decides precedence: with `['config', 'database', 'runtime']` a persisted store entry overrides the file's (layers never: see above), and a change made in code for one request ([runtime configuration](runtime-configuration.md)) overrides both. Put `database` first to let the file win. --- diff --git a/docs/tools/rest-api-reference.md b/docs/tools/rest-api-reference.md index 5aeadfd..502948a 100644 --- a/docs/tools/rest-api-reference.md +++ b/docs/tools/rest-api-reference.md @@ -13,9 +13,9 @@ Paths are under `/{http.prefix}/v1`, by default `/api/settings/v1`; set `http.pr | Owners | a settings route has a global form (`/stores/{store}/settings/…`) and an owner form (`/stores/{store}/owners/{alias}/{id}/settings/…`). `{alias}` is a morph alias from `http.owners` or the morph map, never a class name. | | Locales | `?locale=fr` on settings routes; the write routes also take it. | | Bodies | JSON. Every write may send `"reason"` (recorded in the audit trail and history). | -| ETags | setting responses carry `ETag`. Send it back as `If-Match` on `PUT` or `DELETE`: a mismatch is `412`; `*` matches any version. | -| Idempotency | every non-`GET` route accepts `Idempotency-Key`; a retry with the same key, user, method and path within `http.idempotency.ttl` (24 hours) is answered from cache with `Idempotent-Replayed: true`. | -| Pagination | lists answer `{"data": [...], "meta": {"next_cursor": "…" or null}}`; pass `?cursor=` and `?limit=` (1 to 200, default `http.page_size`). Cursors are opaque. | +| ETags | setting responses carry `ETag`. Send it back as `If-Match` on `PUT` or `DELETE`: a mismatch is `412`, and the write or delete applies only at that version, so a change made after the check is also `412`; `*` matches any version. | +| Idempotency | every non-`GET` route accepts `Idempotency-Key`; a retry with the same key, actor, host, method and path within `http.idempotency.ttl` (24 hours) is answered from cache with `Idempotent-Replayed: true`. The same key with a different body answers `422` (`http-422`) and applies nothing. | +| Pagination | lists answer `{"data": [...], "meta": {"next_cursor": "…" or null}}`; pass `?cursor=` and `?limit=` (1 to 200, default `http.page_size`). Cursors are opaque; one the listing did not hand out answers `422` (`validation`). | | Visibility | values the actor may not view are left out of lists; a single setting answers `"redacted": true` without `value`. | | Approvals | a write to a setting that needs approval answers `202` with the change request instead of the setting. | | Errors | RFC 9457 `application/problem+json`; see [Problem types](#problem-types). | @@ -179,7 +179,7 @@ Answers `200` with the setting as now read. Status: `200`, `401`, `403`, `404`, ### `GET /audit` -`audit.index`, ability `view_audit`. The audit trail, newest first. Entries never hold values. Filters: `store`, `scope` (`global` or `alias:id`), `key`, `action` (an `AuditAction` value such as `set`, `forget`, `rollback`), `outcome` (`allowed`, `denied`, `pending`, `failed`), `since`, `until` (dates); plus `limit`, `cursor`. +`audit.index`, ability `view_audit`. The audit trail, newest first; without `store`, of the stores the actor may audit only (`403` when none). Entries never hold values. Filters: `store`, `scope` (`global` or `alias:id`), `key`, `action` (an `AuditAction` value such as `set`, `forget`, `rollback`), `outcome` (`allowed`, `denied`, `pending`, `failed`), `since`, `until` (dates); plus `limit`, `cursor`. ```json {"data": [{"id": "01JC…", "occurred_at": "2026-11-10T09:12:00+00:00", "action": "set", "outcome": "allowed", diff --git a/docs/tools/rest-api.md b/docs/tools/rest-api.md index 856d4ec..c44a567 100644 --- a/docs/tools/rest-api.md +++ b/docs/tools/rest-api.md @@ -64,12 +64,12 @@ Idempotency-Key: 6c0d1e8e-… "layer": "database", "from": "global", "version": 2, "redacted": false, "value": "Acme Ltd"}} ``` -- **ETags.** Every setting response carries an `ETag` derived from store, scope, key, locale and version. Send it back as `If-Match` and the write is checked against that version; a mismatch answers `412`. +- **ETags.** Every setting response carries an `ETag` derived from store, scope, key, locale and version. Send it back as `If-Match` and the write or delete applies only at that version; a mismatch answers `412`. - **Approvals.** A write to a setting that needs approval answers `202 Accepted` with the change request. -- **Lists** are `{"data": [...], "meta": {"next_cursor": …}}`; pass `?cursor=` for the next page and `?limit=` (1-200). +- **Lists** are `{"data": [...], "meta": {"next_cursor": …}}`; pass `?cursor=` for the next page and `?limit=` (1-200). A cursor the list did not hand out answers `422`. - **Locales**: `?locale=fr`. - **Values the actor may not view** are left out, not masked: a list skips the key, a single setting answers `"redacted": true` without `value`. -- **Idempotency.** A write with an `Idempotency-Key` header is answered from cache when retried (same user, method, path and key) for `http.idempotency.ttl` seconds (24 hours), with `Idempotent-Replayed: true`. +- **Idempotency.** A write with an `Idempotency-Key` header is answered from cache when retried (same actor, host, method, path and key) for `http.idempotency.ttl` seconds (24 hours), with `Idempotent-Replayed: true`. A retry with the same key and a different body is refused with `422` and applies nothing. The stored response is encrypted with the application key, since it can hold an encrypted setting's value; without an application key, or without an actor, nothing is stored. ## Errors diff --git a/docs/upgrading.md b/docs/upgrading.md index a90ac36..df98540 100644 --- a/docs/upgrading.md +++ b/docs/upgrading.md @@ -17,9 +17,12 @@ its replacement. A checkout from before the single migration published four migrations (`create_settings_categories_table`, `create_settings_table`, `create_settings_audit_table`, -`create_settings_definitions_table`). They stay in your `database/migrations` and keep working; do -not publish the new one next to them, or the tables would be created twice. Store migrations -written by an older `make-store` keep working too. +`create_settings_definitions_table`). They no longer work: they import classes removed before the +tag (`SchemaShapeRepository`, `IdentityMode`, `OwnerKeyType`, `TranslationsMode`), so a fresh +`migrate` stops on them, and the tables they made have the old shape (integer keys, `slug`, no +`uid`), which 0.1.0 does not read. Delete them and the store migrations an older `make-store` +wrote, publish the one migration with `install`, and create the tables again; copy any values +you need across before dropping the old tables. 1. Compare your `config/laranail/settings.php` with the package's `config/settings.php`, and drop any key that [Configuration](configuration.md) does not list. diff --git a/src/Actions/Approvals/ApproveChange.php b/src/Actions/Approvals/ApproveChange.php index ce380ff..84cad01 100644 --- a/src/Actions/Approvals/ApproveChange.php +++ b/src/Actions/Approvals/ApproveChange.php @@ -75,11 +75,23 @@ public function handle(ChangeDecision $decision, ?Actor $actor = null): ChangeRe throw AccessDenied::for(Ability::Approve, $subject, 'the requester cannot approve their own change request'); } - $approvals = array_values(array_unique([...$request->approvals, ChangeRequest::actorKey($actor ?? Actor::system())])); - $remaining = max(0, $this->policy->minApprovals - count($approvals)); + // Counted under a row lock, so two approvals recorded at once both count. + [$approvals, $remaining] = $database->transaction(function () use ($database, $store, $request, $subject, $actor, $decision, $now): array { + $current = $database->attempt($store->name, static fn (): ChangeRequest => SettingChangeRequest::locked($database->connectionName(), $store->name, $request->id)); + $approvals = array_values(array_unique([...$current->approvals, ChangeRequest::actorKey($actor ?? Actor::system())])); + $remaining = max(0, $this->policy->minApprovals - count($approvals)); + + if ($remaining > 0) { + $this->record($database, $current, $subject, $actor, $decision->reason, $approvals, $remaining, $now); + } + + return [$approvals, $remaining]; + }, $store->name); if ($remaining > 0) { - return $this->record($database, $request, $subject, $actor, $decision->reason, $approvals, $remaining, $now); + $this->events->dispatch(new ChangeApproved($request->id, $request->store, $request->scope, $request->key, $request->locale, $request->operation->value, $remaining)); + + return $database->attempt($store->name, static fn (): ChangeRequest => SettingChangeRequest::get($database->connectionName(), $store->name, $request->id)); } try { @@ -113,16 +125,13 @@ public function handle(ChangeDecision $decision, ?Actor $actor = null): ChangeRe } /** @param list $approvals */ - private function record(DatabaseDriver $database, ChangeRequest $request, Subject $subject, ?Actor $actor, ?string $reason, array $approvals, int $remaining, CarbonImmutable $now): ChangeRequest + private function record(DatabaseDriver $database, ChangeRequest $request, Subject $subject, ?Actor $actor, ?string $reason, array $approvals, int $remaining, CarbonImmutable $now): void { if (! $database->attempt(new StoreName($request->store), static fn (): bool => SettingChangeRequest::transition($database->connectionName(), $request, [ChangeStatus::Pending, ChangeStatus::Approved], ChangeStatus::Approved, null, null, $now, $approvals))) { throw new ChangeRequestClosed(sprintf('Change request [%s] was decided by somebody else first.', $request->id)); } $this->access->auditor()->record(AuditAction::Approve, AuditOutcome::Pending, $subject, $actor, $reason, meta: ['change_request' => $request->id, 'remaining' => $remaining]); - $this->events->dispatch(new ChangeApproved($request->id, $request->store, $request->scope, $request->key, $request->locale, $request->operation->value, $remaining)); - - return $database->attempt($subject->store, static fn (): ChangeRequest => SettingChangeRequest::get($database->connectionName(), $subject->store, $request->id)); } private function assertOpen(DatabaseDriver $database, ChangeRequest $request, CarbonImmutable $now): void diff --git a/src/Actions/ForgetSetting.php b/src/Actions/ForgetSetting.php index 214ee48..539db69 100644 --- a/src/Actions/ForgetSetting.php +++ b/src/Actions/ForgetSetting.php @@ -20,13 +20,20 @@ public function __construct( private WriteGuard $guard, ) {} - /** @return ?ChangeRequest the change request opened instead, when the setting needs approval */ - public function handle(SettingTarget $target, ?Actor $actor = null): ?ChangeRequest + /** + * @param ?int $expectedVersion forget only while the row is at this version (0: no row) + * + * @return ?ChangeRequest the change request opened instead, when the setting needs approval + */ + public function handle(SettingTarget $target, ?Actor $actor = null, ?int $expectedVersion = null): ?ChangeRequest { - return $this->guard->run(Ability::Forget, $target, $actor, respectsLocks: true, write: function (bool $override) use ($target, $actor): array { - $removed = $override - ? $this->writer->causedBy($actor, $target->reason)->forgetOverridingLock($target->store, $target->key, $target->locale, $target->owner, $target->definition) - : $this->writer->causedBy($actor, $target->reason)->forget($target->store, $target->key, $target->locale, $target->owner, $target->definition); + return $this->guard->run(Ability::Forget, $target, $actor, respectsLocks: true, write: function (bool $override) use ($target, $actor, $expectedVersion): array { + $writer = $this->writer->causedBy($actor, $target->reason); + $removed = match (true) { + $expectedVersion !== null => $writer->forgetExpecting($target->store, $target->key, $target->locale, $target->owner, $target->definition, $expectedVersion, $override), + $override => $writer->forgetOverridingLock($target->store, $target->key, $target->locale, $target->owner, $target->definition), + default => $writer->forget($target->store, $target->key, $target->locale, $target->owner, $target->definition), + }; return [$removed?->version, null]; }, proposal: new ChangeProposal($target, ChangeOperation::Forget)); diff --git a/src/Actions/QueryAudit.php b/src/Actions/QueryAudit.php index d88c613..8243dad 100644 --- a/src/Actions/QueryAudit.php +++ b/src/Actions/QueryAudit.php @@ -4,6 +4,7 @@ namespace Simtabi\Laranail\Settings\Actions; +use Closure; use Illuminate\Pagination\Cursor; use Illuminate\Support\LazyCollection; use Illuminate\Database\Eloquent\Builder; @@ -62,16 +63,45 @@ public function paginate(AuditFilter $filter, ?Actor $actor = null, int $perPage private function query(AuditFilter $filter, ?Actor $actor): Builder { $store = $filter->store instanceof StoreName ? $this->stores->get($filter->store) : $this->stores->default(); + $subject = static fn (StoreName $name): Subject => new Subject($name, key: $filter->key, owner: $filter->scope?->owner()); + $readable = $filter->store instanceof StoreName ? null : $this->readableStores($actor, $subject); - $this->access->authorize($actor, Ability::ViewAudit, new Subject( - $store->name, - key: $filter->key, - owner: $filter->scope?->owner(), - )); + // No store filter: only the stores this actor may audit. None at all is refused, audited, + // the same as a query naming one store. + if ($readable === null || $readable === []) { + $this->access->authorize($actor, Ability::ViewAudit, $subject($store->name)); + } $database = $this->stores->auditDatabase($store->name) ?? throw new DriverUnavailable(sprintf('Store [%s] has no active database layer, so its audit trail went to the log and cannot be queried.', $store->name)); - return SettingAuditEntry::on($database->connectionName())->matching($filter); + $query = SettingAuditEntry::on($database->connectionName())->matching($filter); + + return $readable === null ? $query : $query->whereIn('store', $readable); + } + + /** + * The names of the stores an actor may audit; null for trusted code and the system, which + * read every store. + * + * @param Closure(StoreName): Subject $subject + * + * @return list|null + */ + private function readableStores(?Actor $actor, Closure $subject): ?array + { + if (! $actor instanceof Actor || $actor->isSystem()) { + return null; + } + + $readable = []; + + foreach ($this->stores->all() as $store) { + if ($this->access->allows($actor, Ability::ViewAudit, $subject($store->name))) { + $readable[] = $store->name->value; + } + } + + return $readable; } } diff --git a/src/Http/Controllers/SettingsController.php b/src/Http/Controllers/SettingsController.php index 4b651b2..0b19af8 100644 --- a/src/Http/Controllers/SettingsController.php +++ b/src/Http/Controllers/SettingsController.php @@ -71,8 +71,8 @@ public function destroy(WriteSettingRequest $request, ForgetSetting $forget, Add $input = $request->toData(); $actor = $actors->of($request, $input->reason); $address = $addresses->of($input->address); - $this->expectedVersion($targets, $address, $input->ifMatch); - $change = $forget->handle($targets->target($address, $input->reason), $actor); + $expected = $this->expectedVersion($targets, $address, $input->ifMatch); + $change = $forget->handle($targets->target($address, $input->reason), $actor, $expected); return $change instanceof ChangeRequest ? $this->accepted($change) : new Response(status: 204); } diff --git a/src/Http/Middleware/IdempotentWrites.php b/src/Http/Middleware/IdempotentWrites.php index ade42f3..d8cc1b0 100644 --- a/src/Http/Middleware/IdempotentWrites.php +++ b/src/Http/Middleware/IdempotentWrites.php @@ -5,19 +5,30 @@ namespace Simtabi\Laranail\Settings\Http\Middleware; use Closure; +use JsonException; use Illuminate\Http\Request; +use Simtabi\Laranail\Settings\Data\Actor; use Illuminate\Contracts\Cache\Repository; use Symfony\Component\HttpFoundation\Response; use Illuminate\Http\Response as IlluminateResponse; +use Simtabi\Laranail\Settings\Services\Access\AccessGuard; +use Simtabi\Laranail\Settings\Exceptions\SettingsException; +use Simtabi\Laranail\Settings\Support\LaravelValueEncrypter; +use Symfony\Component\HttpKernel\Exception\UnprocessableEntityHttpException; /** - * Replays the stored response to a REST write retried with the same `Idempotency-Key`, user, - * method and path. Server errors are not stored, so they can be retried. + * Replays the stored response to a REST write retried with the same `Idempotency-Key`, actor, + * host, method and path. A retry with a different body is refused with 422. Server errors are + * not stored, so they can be retried, and nothing is stored for a request with no actor. + * + * The stored response is encrypted, because it can hold the value of an encrypted setting. */ final readonly class IdempotentWrites { public function __construct( private Repository $cache, + private AccessGuard $access, + private LaravelValueEncrypter $encrypter, private int $ttl = 86400, private string $prefix = 'laranail-settings', ) {} @@ -25,36 +36,76 @@ public function __construct( public function handle(Request $request, Closure $next): Response { $key = $request->header('Idempotency-Key'); + $actor = is_string($key) && $key !== '' && strlen($key) <= 255 ? $this->access->resolveActor($request) : null; - if (! is_string($key) || $key === '' || strlen($key) > 255) { + if (! is_string($key) || ! $actor instanceof Actor) { /** @var Response */ return $next($request); } - $user = $request->user()?->getAuthIdentifier(); - $cacheKey = $this->prefix . ':idempotency:' . sha1(implode('|', [is_scalar($user) ? (string) $user : '', $request->method(), $request->path(), $key])); - $stored = $this->cache->get($cacheKey); + $cacheKey = $this->prefix . ':idempotency:' . hash('sha256', implode('|', [ + $actor->type->value, $actor->alias ?? '', $actor->id ?? '', $request->getHost(), $request->method(), $request->path(), $key, + ])); + $fingerprint = hash('sha256', $request->getQueryString() . '|' . $request->getContent()); + $stored = $this->read($this->cache->get($cacheKey)); - if (is_array($stored) && is_int($stored['status'] ?? null) && is_string($stored['body'] ?? null)) { - $headers = is_array($stored['headers'] ?? null) ? $stored['headers'] : []; + if ($stored !== null) { + if ($stored['fingerprint'] !== $fingerprint) { + throw new UnprocessableEntityHttpException('This Idempotency-Key was already used with a different request; send a new key.'); + } - return new IlluminateResponse($stored['body'], $stored['status'], $headers + ['Idempotent-Replayed' => 'true']); + return new IlluminateResponse($stored['body'], $stored['status'], $stored['headers'] + ['Idempotent-Replayed' => 'true']); } /** @var Response $response */ $response = $next($request); if ($response->getStatusCode() < 500) { - $this->cache->put($cacheKey, [ - 'status' => $response->getStatusCode(), - 'body' => (string) $response->getContent(), - 'headers' => array_filter([ - 'Content-Type' => $response->headers->get('Content-Type'), - 'ETag' => $response->headers->get('ETag'), - ], static fn (?string $value): bool => $value !== null), - ], $this->ttl); + $this->store($cacheKey, $fingerprint, $response); } return $response; } + + private function store(string $cacheKey, string $fingerprint, Response $response): void + { + $entry = json_encode([ + 'fingerprint' => $fingerprint, + 'status' => $response->getStatusCode(), + 'body' => (string) $response->getContent(), + 'headers' => array_filter([ + 'Content-Type' => $response->headers->get('Content-Type'), + 'ETag' => $response->headers->get('ETag'), + ], static fn (?string $value): bool => $value !== null), + ], JSON_THROW_ON_ERROR); + + try { + $this->cache->put($cacheKey, $this->encrypter->encrypt($entry), $this->ttl); + } catch (SettingsException) { + // No application key: the write is answered, but a retry runs it again. + } + } + + /** @return array{fingerprint: string, status: int, body: string, headers: array}|null */ + private function read(mixed $stored): ?array + { + if (! is_string($stored)) { + return null; + } + + try { + $entry = json_decode($this->encrypter->decrypt($stored), true, flags: JSON_THROW_ON_ERROR); + } catch (SettingsException|JsonException) { + return null; + } + + if (! is_array($entry) || ! is_string($entry['fingerprint'] ?? null) || ! is_int($entry['status'] ?? null) || ! is_string($entry['body'] ?? null)) { + return null; + } + + $headers = is_array($entry['headers'] ?? null) ? array_filter($entry['headers'], is_string(...)) : []; + + /** @var array $headers */ + return ['fingerprint' => $entry['fingerprint'], 'status' => $entry['status'], 'body' => $entry['body'], 'headers' => $headers]; + } } diff --git a/src/Http/Requests/PageRequest.php b/src/Http/Requests/PageRequest.php index cb40466..ccd6616 100644 --- a/src/Http/Requests/PageRequest.php +++ b/src/Http/Requests/PageRequest.php @@ -4,6 +4,8 @@ namespace Simtabi\Laranail\Settings\Http\Requests; +use Illuminate\Pagination\Cursor; +use Illuminate\Validation\Validator; use Illuminate\Contracts\Config\Repository; use Illuminate\Foundation\Http\FormRequest; use Simtabi\Laranail\Settings\Data\Http\PageInput; @@ -36,6 +38,36 @@ public function rules(): array ] + array_fill_keys(array_diff(self::FILTERS, ['since', 'until']), ['nullable', 'string', 'max:191']); } + /** + * A `cursor` must be one this listing hands out: a setting key, a change request id, or an + * encoded cursor. Anything else is refused rather than read as the first page. + * + * @return list + */ + public function after(): array + { + return [function (Validator $validator): void { + $cursor = $this->query('cursor'); + $route = $this->route(); + $name = is_object($route) && method_exists($route, 'getName') ? (string) $route->getName() : ''; + + if (! is_string($cursor) || $cursor === '') { + return; + } + + $valid = match (true) { + str_ends_with($name, '.settings.index') => preg_match('/^[a-z0-9_]+(\.[a-z0-9_]+)*$/', $cursor) === 1, + str_ends_with($name, '.changes.index') => preg_match('/^[0-9a-z]{26}$/i', $cursor) === 1, + str_ends_with($name, '.history'), str_ends_with($name, '.audit.index') => Cursor::fromEncoded($cursor) instanceof Cursor, + default => true, + }; + + if (! $valid) { + $validator->errors()->add('cursor', 'The cursor is not one this listing returned; start again without it.'); + } + }]; + } + /** @param ?int $defaultLimit the page size without `?limit=`; null reads `http.page_size` */ public function toData(?int $defaultLimit = null): PageInput { diff --git a/src/Models/SettingChangeRequest.php b/src/Models/SettingChangeRequest.php index b977e1c..fb799a4 100644 --- a/src/Models/SettingChangeRequest.php +++ b/src/Models/SettingChangeRequest.php @@ -57,10 +57,27 @@ public static function open(?string $connection, array $request, Actor $requeste ])->refresh()->toRequest(); } - /** @throws UnknownChangeRequest */ + /** + * The request with this id in this store; one opened in another store is unknown here, so a + * route naming one store can never decide another store's request. + * + * @throws UnknownChangeRequest + */ public static function get(?string $connection, StoreName $store, string $id): ChangeRequest { - return self::on($connection)->find($id)?->toRequest() + return self::on($connection)->where('store', $store->value)->find($id)?->toRequest() + ?? throw new UnknownChangeRequest(sprintf('Store [%s] has no change request [%s].', $store, $id)); + } + + /** + * {@see get()} under a row lock, inside the caller's transaction, so concurrent approvals + * read each other's. + * + * @throws UnknownChangeRequest + */ + public static function locked(?string $connection, StoreName $store, string $id): ChangeRequest + { + return self::on($connection)->where('store', $store->value)->whereKey($id)->lockForUpdate()->first()?->toRequest() ?? throw new UnknownChangeRequest(sprintf('Store [%s] has no change request [%s].', $store, $id)); } diff --git a/src/Providers/SettingsServiceProvider.php b/src/Providers/SettingsServiceProvider.php index 7897b31..0d3ac1c 100644 --- a/src/Providers/SettingsServiceProvider.php +++ b/src/Providers/SettingsServiceProvider.php @@ -624,6 +624,8 @@ private function registerHttp(): void { $this->app->bind(IdempotentWrites::class, static fn (Application $app): IdempotentWrites => new IdempotentWrites( self::cacheStore($app, $app->make(Repository::class)->get('laranail.settings.http.idempotency.cache'), 'laranail.settings.http.idempotency.cache'), + $app->make(AccessGuard::class), + $app->make(LaravelValueEncrypter::class), $app->make(Repository::class)->integer('laranail.settings.http.idempotency.ttl', 86400), $app->make(Repository::class)->string('laranail.settings.cache.prefix', 'laranail-settings'), )); diff --git a/src/Services/Configuration/PersistedConfiguration.php b/src/Services/Configuration/PersistedConfiguration.php index 0d1bf10..a59a1cd 100644 --- a/src/Services/Configuration/PersistedConfiguration.php +++ b/src/Services/Configuration/PersistedConfiguration.php @@ -13,6 +13,7 @@ use Illuminate\Container\Attributes\Scoped; use Simtabi\Laranail\Settings\Support\Json; use Simtabi\Laranail\Settings\Data\StoreName; +use Simtabi\Laranail\Settings\Enums\DriverType; use Simtabi\Laranail\Settings\Logging\LogContext; use Simtabi\Laranail\Settings\Database\SchemaNames; use Illuminate\Database\ConnectionResolverInterface; @@ -225,6 +226,19 @@ private function load(): array */ private function check(string $kind, string $name, array $config, array $stores, array $layers): void { + // A php layer requires the file it names and a config layer reads application + // configuration: from a row anyone with manage_stores can write, either would run code or + // disclose secrets. They belong in the configuration file. + if ($kind === 'layer' && in_array($config['driver'] ?? null, [DriverType::Php->value, DriverType::Config->value], true)) { + throw new InvalidConfiguration(sprintf('Persisted layer [%s]: the [%s] driver reads files or configuration on the server, so it can only be defined in the configuration file.', $name, is_string($config['driver']) ? $config['driver'] : '')); + } + + // Persisted layers only add to the file's: redefining one would move a store the file + // configures onto another connection, table or driver, which is promote's job. + if ($kind === 'layer' && array_key_exists($name, $this->configLayers)) { + throw new InvalidConfiguration(sprintf('Persisted layer [%s] would redefine a layer the configuration file defines; change it there, or persist a layer under a new name.', $name)); + } + $configured = $this->configStores[$name] ?? null; if ($kind === 'store' && is_array($configured) && ($configured['layers'] ?? null) !== ($config['layers'] ?? null)) { diff --git a/src/Services/Stores/SettingWriter.php b/src/Services/Stores/SettingWriter.php index 8a0fb14..2938aab 100644 --- a/src/Services/Stores/SettingWriter.php +++ b/src/Services/Stores/SettingWriter.php @@ -100,6 +100,16 @@ public function forget(Store $store, Key $key, Locale $locale, ?OwnerRef $owner, return $this->remove($store, $key, $locale, $owner, $definition, overrideLock: false); } + /** + * Remove this scope's own value only if it is still at `$expectedVersion` (0 for no row). + * + * @throws ConcurrentModification + */ + public function forgetExpecting(Store $store, Key $key, Locale $locale, ?OwnerRef $owner, ?Definition $definition, int $expectedVersion, bool $overrideLock = false): ?Record + { + return $this->remove($store, $key, $locale, $owner, $definition, $overrideLock, $expectedVersion); + } + /** {@see forget()} over a row lock; the same precondition as {@see setOverridingLock()}. */ public function forgetOverridingLock(Store $store, Key $key, Locale $locale, ?OwnerRef $owner, ?Definition $definition): ?Record { @@ -229,13 +239,14 @@ private function database(Layer $layer): ?DatabaseDriver return $layer->driver instanceof DatabaseBacked && $layer->driver->isActive() ? $layer->driver->database() : null; } - private function remove(Store $store, Key $key, Locale $locale, ?OwnerRef $owner, ?Definition $definition, bool $overrideLock): ?Record + private function remove(Store $store, Key $key, Locale $locale, ?OwnerRef $owner, ?Definition $definition, bool $overrideLock, ?int $expectedVersion = null): ?Record { $this->guard($store, $key, $locale, $owner, $definition, $overrideLock); $layer = $store->writableLayer(); $scope = $this->scope($owner); $existing = $layer->driver->load($store->name, [$scope])->find($scope, $key, $locale); + $this->assertVersion($store, $scope, $key, $existing, $expectedVersion); if (! $existing instanceof Record) { return null; @@ -246,7 +257,12 @@ private function remove(Store $store, Key $key, Locale $locale, ?OwnerRef $owner if ($database instanceof DatabaseDriver) { // A tombstone: the version that was removed, no new value. The next write continues after it. - $database->transaction(function () use ($store, $layer, $database, $scope, $key, $locale, $existing): void { + $database->transaction(function () use ($store, $layer, $database, $scope, $key, $locale, $existing, $expectedVersion): void { + // Under a row lock, so a write between the check above and this delete is caught. + if ($expectedVersion !== null) { + $this->assertVersion($store, $scope, $key, $database->lockedFind($store->name, $scope, $key, $locale), $expectedVersion); + } + $reference = $database->reference($store->name, $scope, $key, $locale); $layer->driver->forget($store->name, $scope, $key, $locale); $database->attempt($store->name, fn (): SettingHistory => SettingHistory::record($database->connectionName(), $store->name, HistoryOperation::Forget, $existing, null, $reference, $this->causer, $this->reason, $this->clock->now())); @@ -260,6 +276,14 @@ private function remove(Store $store, Key $key, Locale $locale, ?OwnerRef $owner return $existing; } + /** @throws ConcurrentModification when the row is not at the expected version (0: no row) */ + private function assertVersion(Store $store, Scope $scope, Key $key, ?Record $current, ?int $expectedVersion): void + { + if ($expectedVersion !== null && ($current->version ?? 0) !== $expectedVersion) { + throw new ConcurrentModification(sprintf('Setting [%s] in store [%s] for scope [%s] is at version %d, not the expected %d; re-read and retry.', $key, $store->name, $scope, $current->version ?? 0, $expectedVersion)); + } + } + private function storeLock(Store $store, Key $key, Locale $locale, ?OwnerRef $owner, bool $locked, ?Definition $definition): Record { $this->ownerAllowed($store, $owner, null); diff --git a/src/Services/Values/ValuePipeline.php b/src/Services/Values/ValuePipeline.php index 47d55b1..7721b15 100644 --- a/src/Services/Values/ValuePipeline.php +++ b/src/Services/Values/ValuePipeline.php @@ -6,11 +6,13 @@ use Simtabi\Laranail\Settings\Data\Key; use Simtabi\Laranail\Settings\Data\Record; +use Illuminate\Container\Attributes\Config; use Illuminate\Container\Attributes\Singleton; use Simtabi\Laranail\Settings\Data\Definition; use Simtabi\Laranail\Settings\Support\ValueEncoder; use Simtabi\Laranail\Settings\Support\LaravelValueEncrypter; use Simtabi\Laranail\Settings\Support\LaravelValueValidator; +use Simtabi\Laranail\Settings\Exceptions\InvalidSettingValue; use Simtabi\Laranail\Settings\Services\Casting\CasterRegistry; /** @@ -25,9 +27,11 @@ public function __construct( private LaravelValueValidator $validator, private LaravelValueEncrypter $encrypter, private ValueEncoder $encoder, + #[Config('laranail.settings.values.max_bytes', 1048576)] + private mixed $maxBytes = 1048576, ) {} - /** The encoded, and where defined encrypted, payload. */ + /** The encoded, and where defined encrypted, payload; refused when larger than `values.max_bytes`. */ public function toPayload(Key $key, mixed $value, ?Definition $definition): string { $this->validator->validate($key, $value, $definition->rules ?? []); @@ -35,6 +39,11 @@ public function toPayload(Key $key, mixed $value, ?Definition $definition): stri $type = $definition?->type; $stored = $type === null ? $value : $this->casters->get($type)->toStorage($key, $value); $payload = $this->encoder->encode($key, $stored); + $limit = is_numeric($this->maxBytes) ? (int) $this->maxBytes : null; + + if ($limit !== null && strlen($payload) > $limit) { + throw new InvalidSettingValue(sprintf('Setting [%s]: the value is %d bytes, over the %d-byte limit in laranail.settings.values.max_bytes.', $key, strlen($payload), $limit)); + } return $definition instanceof Definition && $definition->encrypted ? $this->encrypter->encrypt($payload) : $payload; } diff --git a/src/Support/RecordSerializer.php b/src/Support/RecordSerializer.php index a6464d2..705aff7 100644 --- a/src/Support/RecordSerializer.php +++ b/src/Support/RecordSerializer.php @@ -9,8 +9,10 @@ use Simtabi\Laranail\Settings\Data\Scope; use Simtabi\Laranail\Settings\Data\Locale; use Simtabi\Laranail\Settings\Data\Record; +use Carbon\Exceptions\InvalidFormatException; use Illuminate\Container\Attributes\Singleton; use Simtabi\Laranail\Settings\Exceptions\DriverFailure; +use Simtabi\Laranail\Settings\Exceptions\InvalidIdentifier; /** Converts records to and from the plain arrays file layers store. */ #[Singleton] @@ -44,21 +46,26 @@ public function fromArray(array $row, string $source): Record $writtenAt = $row['written_at'] ?? null; if (! is_string($scope) || ! is_string($key) || ! is_string($locale) || ($payload !== null && ! is_string($payload)) - || ($type !== null && ! is_string($type)) || ! is_int($version) || ($writtenAt !== null && ! is_string($writtenAt))) { + || ($type !== null && ! is_string($type)) || ! is_int($version) || $version < 1 || ($writtenAt !== null && ! is_string($writtenAt))) { throw new DriverFailure(sprintf('A record in [%s] is malformed.', $source)); } - return new Record( - scope: $this->scope($scope, $source), - key: new Key($key), - locale: new Locale($locale), - payload: $payload, - type: $type, - encrypted: ($row['encrypted'] ?? false) === true, - locked: ($row['locked'] ?? false) === true, - version: $version, - writtenAt: $writtenAt === null ? null : CarbonImmutable::parse($writtenAt), - ); + // A key, locale or date the file got wrong is the file's fault, reported like any other. + try { + return new Record( + scope: $this->scope($scope, $source), + key: new Key($key), + locale: new Locale($locale), + payload: $payload, + type: $type, + encrypted: ($row['encrypted'] ?? false) === true, + locked: ($row['locked'] ?? false) === true, + version: $version, + writtenAt: $writtenAt === null ? null : CarbonImmutable::parse($writtenAt), + ); + } catch (InvalidIdentifier|InvalidFormatException $exception) { + throw new DriverFailure(sprintf('A record in [%s] is malformed: %s', $source, $exception->getMessage()), 0, $exception); + } } private function scope(string $value, string $source): Scope diff --git a/tests/Feature/Database/ApprovalsTest.php b/tests/Feature/Database/ApprovalsTest.php index a21709b..d7942df 100644 --- a/tests/Feature/Database/ApprovalsTest.php +++ b/tests/Feature/Database/ApprovalsTest.php @@ -6,6 +6,8 @@ use Illuminate\Support\Facades\Gate; use Illuminate\Support\Facades\Event; use Illuminate\Support\Facades\Artisan; +use Simtabi\Laranail\Settings\Data\Actor; +use Simtabi\Laranail\Settings\Data\Subject; use Simtabi\Laranail\Settings\Data\OwnerRef; use Simtabi\Laranail\Settings\Enums\Ability; use Simtabi\Laranail\Settings\Enums\AuditAction; @@ -14,6 +16,7 @@ use Simtabi\Laranail\Settings\Enums\ChangeStatus; use Simtabi\Laranail\Settings\Events\ChangeStale; use Simtabi\Laranail\Settings\Events\ChangeApplied; +use Illuminate\Database\Events\TransactionBeginning; use Simtabi\Laranail\Settings\Enums\ChangeOperation; use Simtabi\Laranail\Settings\Events\ChangeApproved; use Simtabi\Laranail\Settings\Events\ChangeRejected; @@ -127,6 +130,29 @@ function needsApproval(string $key = 'mail.host'): void ->and(settings()->get('mail.host'))->toBe('smtp.acme.test'); }); +it('counts two approvals recorded at once, never losing one', function (): void { + config()->set('laranail.settings.approvals.min_approvals', 3); + app()->forgetScopedInstances(); + needsApproval(); + settings()->as(user(1))->set('mail.host', 'smtp.acme.test'); + $id = settings()->approvals()->get()[0]->id; + + // User 3's approval commits after user 2 read the request and before user 2 records theirs. + $raced = false; + Event::listen(TransactionBeginning::class, static function () use (&$raced, $id): void { + if (! $raced) { + $raced = true; + DB::table('settings_change_requests')->where('id', $id)->update(['status' => 'approved', 'approvals' => json_encode([ChangeRequest::actorKey(Actor::user(user(3)))])]); + } + }); + + $approved = settings()->as(user(2))->approvals()->approve($id); + + expect($raced)->toBeTrue() + ->and($approved->status)->toBe(ChangeStatus::Approved) + ->and($approved->approvals)->toHaveCount(2); +}); + it('marks a request stale when its setting changed after it was opened, and never overwrites', function (): void { Event::fake([ChangeStale::class]); useDatabase(['stores.settings.approvals' => ['keys' => ['mail.*']]]); @@ -166,6 +192,23 @@ function needsApproval(string $key = 'mail.host'): void Event::assertDispatched(ChangeCancelled::class); }); +it('never decides a change request through another store, where it would be authorized and applied', function (): void { + useDatabase(['stores.billing' => ['layers' => ['database'], 'approvals' => ['keys' => ['plan.*']]]], ['billing']); + allowGates(Ability::Update, Ability::Approve, Ability::View); + // An approver of the settings store only. + Gate::define(Ability::Approve->gateName(), static fn ($user, Subject $subject): bool => $subject->store->value === 'settings'); + $change = settings()->store('billing')->as(user(1))->propose('plan.tier', 'gold'); + + foreach (['approve', 'reject', 'cancel'] as $decision) { + expect(fn (): ChangeRequest => settings()->as(user(2))->approvals()->{$decision}($change->id))->toThrow(UnknownChangeRequest::class, 'Store [settings]'); + } + + expect(settings()->get('plan.tier'))->toBeNull() + ->and(settings()->store('billing')->get('plan.tier'))->toBeNull() + ->and(DB::table('settings_change_requests')->value('status'))->toBe('pending') + ->and(settings()->store('billing')->approvals()->find($change->id)->store)->toBe('billing'); +}); + it('proposes forget, lock and unlock as well as values', function (): void { settings()->for(new OwnerRef('user', 5))->set('mail.host', 'a.test'); needsApproval(); diff --git a/tests/Feature/Database/AuditQueryTest.php b/tests/Feature/Database/AuditQueryTest.php index 5be30de..5e75d7f 100644 --- a/tests/Feature/Database/AuditQueryTest.php +++ b/tests/Feature/Database/AuditQueryTest.php @@ -3,6 +3,8 @@ declare(strict_types=1); use Illuminate\Support\Facades\DB; +use Illuminate\Support\Facades\Gate; +use Simtabi\Laranail\Settings\Data\Subject; use Simtabi\Laranail\Settings\Data\OwnerRef; use Simtabi\Laranail\Settings\Enums\Ability; use Simtabi\Laranail\Settings\Data\AuditEntry; @@ -77,6 +79,21 @@ function auditKeys(array $entries): array expect(settings()->as(user())->audit()->outcome(AuditOutcome::Denied)->get()[0]->action)->toBe(AuditAction::ViewAudit); }); +it('answers an unfiltered query with the stores the actor may audit only', function (): void { + settings()->set('site.name', 'Acme'); + settings()->store('billing')->set('plan.tier', 'gold'); + // An auditor of the settings store only. + Gate::define(Ability::ViewAudit->gateName(), static fn ($user, Subject $subject): bool => $subject->store->value === 'settings'); + + expect(array_map(static fn (AuditEntry $entry): string => $entry->store, settings()->as(user())->audit()->action(AuditAction::Update)->get()))->toBe(['settings']) + ->and(fn (): array => settings()->as(user())->audit()->store('billing')->get())->toThrow(AccessDenied::class) + ->and(count(settings()->audit()->action(AuditAction::Update)->get()))->toBe(2); + + Gate::define(Ability::ViewAudit->gateName(), static fn (): bool => false); + + expect(fn (): array => settings()->as(user())->audit()->get())->toThrow(AccessDenied::class); +}); + it('cannot query a store whose trail is not in a database', function (): void { config()->set('laranail.settings.stores.settings.layers', ['runtime']); config()->set('laranail.settings.stores.billing.layers', ['runtime']); diff --git a/tests/Feature/Database/PersistedConfigurationTest.php b/tests/Feature/Database/PersistedConfigurationTest.php index 3f89d78..6a59584 100644 --- a/tests/Feature/Database/PersistedConfigurationTest.php +++ b/tests/Feature/Database/PersistedConfigurationTest.php @@ -62,6 +62,45 @@ ->and(DB::table('settings_stores')->count())->toBe(0); }); +it('never persists a php or config layer, which would run a file or read configuration on the server', function (): void { + $file = sys_get_temp_dir() . '/laranail-settings-persisted-' . bin2hex(random_bytes(6)); + $marker = $file . '.ran'; + file_put_contents($file . '.php', " 1];"); + $editor = settings()->persistedConfiguration(); + + expect(fn () => $editor->saveLayer('evil', ['driver' => 'php', 'path' => $file . '.php']))->toThrow(InvalidConfiguration::class, 'only be defined in the configuration file') + ->and(fn () => $editor->saveLayer('shipped', ['driver' => 'php', 'path' => $file . '.php']))->toThrow(InvalidConfiguration::class, 'only be defined in the configuration file') + ->and(fn () => $editor->saveLayer('secrets', ['driver' => 'config', 'prefix' => 'app']))->toThrow(InvalidConfiguration::class, 'only be defined in the configuration file') + ->and(DB::table('settings_stores')->count())->toBe(0); + + // A row written to the table directly is skipped the same way, and its file is never required. + DB::table('settings_stores')->insert([ + ['id' => '01J00000000000000000000001', 'kind' => 'layer', 'name' => 'evil', 'config' => json_encode(['driver' => 'php', 'path' => $file . '.php']), 'created_at' => now(), 'updated_at' => now()], + ['id' => '01J00000000000000000000002', 'kind' => 'store', 'name' => 'evil', 'config' => '{"layers":["evil"]}', 'created_at' => now(), 'updated_at' => now()], + ]); + app()->forgetScopedInstances(); + + expect(fn (): mixed => settings()->store('evil')->get('a'))->toThrow(UnknownStore::class) + ->and(is_file($marker))->toBeFalse(); +}); + +it('only adds layers: a persisted layer never redefines one the configuration file defines', function (): void { + expect(fn () => settings()->persistedConfiguration()->saveLayer('database', ['driver' => 'array']))->toThrow(InvalidConfiguration::class, 'would redefine a layer') + ->and(DB::table('settings_stores')->count())->toBe(0); + + settings()->set('site.name', 'Acme'); + // A row written to the table directly is skipped, and the store keeps the file's database layer. + DB::table('settings_stores')->insert(['id' => '01J00000000000000000000003', 'kind' => 'layer', 'name' => 'database', 'config' => '{"driver":"array"}', 'created_at' => now(), 'updated_at' => now()]); + app()->forgetScopedInstances(); + + expect(settings()->get('site.name'))->toBe('Acme') + ->and(settings()->persistedConfiguration()->entries())->toBe([]); + + Artisan::call('laranail::settings.doctor', ['--json' => true]); + + expect(Artisan::output())->toContain('layer [database]: Persisted layer [database] would redefine'); +}); + it('skips and reports an invalid row instead of failing', function (): void { DB::table('settings_stores')->insert([ ['id' => '01J00000000000000000000001', 'kind' => 'store', 'name' => 'broken', 'config' => '{"layers":["missing"]}', 'created_at' => now(), 'updated_at' => now()], diff --git a/tests/Feature/Database/RestApiTest.php b/tests/Feature/Database/RestApiTest.php index 7e420bc..712c613 100644 --- a/tests/Feature/Database/RestApiTest.php +++ b/tests/Feature/Database/RestApiTest.php @@ -6,12 +6,17 @@ use Illuminate\Support\Facades\DB; use Illuminate\Support\Facades\Gate; use Illuminate\Testing\TestResponse; +use Illuminate\Support\Facades\Event; use Illuminate\Support\Facades\Schema; +use Illuminate\Support\Facades\Storage; use Illuminate\Database\Schema\Blueprint; +use Simtabi\Laranail\Settings\Data\Actor; use Simtabi\Laranail\Settings\Data\OwnerRef; use Simtabi\Laranail\Settings\Enums\Ability; use Simtabi\Laranail\Settings\Data\NewCategory; +use Simtabi\Laranail\Settings\Data\PromotionReport; use Illuminate\Database\Eloquent\Relations\Relation; +use Illuminate\Database\Events\TransactionBeginning; use Simtabi\Laranail\Settings\Http\Support\Problems; use Simtabi\Laranail\Settings\Exceptions\AccessDenied; use Simtabi\Laranail\Settings\Tests\Fixtures\TestUser; @@ -19,6 +24,8 @@ use Simtabi\Laranail\Settings\Tests\Support\JsonSchema; use Simtabi\Laranail\Package\Tools\Testing\TestCredentials; use Simtabi\Laranail\Settings\Tests\Fixtures\SettingsOwner; +use Simtabi\Laranail\Settings\Services\Values\ValuePipeline; +use Simtabi\Laranail\Settings\Exceptions\InvalidSettingValue; use Simtabi\Laranail\Settings\Exceptions\InvalidConfiguration; use Simtabi\Laranail\Settings\Services\Definitions\DefinitionRegistry; @@ -78,6 +85,26 @@ function api(string $method, string $uri, array $data = [], array $headers = []) ->and(DB::table('settings_audit')->where('channel', 'rest')->where('action', 'update')->count())->toBe(2); }); +it('forgets on If-Match only at that version, even when the setting changes after the check', function (): void { + $etag = api('PUT', 'stores/settings/settings/site.name', ['value' => 'Acme'])->headers->get('ETag'); + + api('DELETE', 'stores/settings/settings/site.name', [], ['If-Match' => '"stale"'])->assertStatus(412); + + // Another writer lands between the If-Match check and the delete, as the write's transaction opens. + $moved = false; + Event::listen(TransactionBeginning::class, static function () use (&$moved): void { + if (! $moved) { + $moved = true; + DB::table('settings')->where('key', 'site.name')->update(['value' => json_encode('Moved on'), 'version' => 2]); + } + }); + + api('DELETE', 'stores/settings/settings/site.name', [], ['If-Match' => $etag])->assertStatus(412)->assertHeader('Content-Type', 'application/problem+json'); + + // The simulated write ran inside the refused transaction and rolled back with it; the row is not deleted. + expect(DB::table('settings')->where('key', 'site.name')->count())->toBe(1); +}); + it('lists, explains, locks, unlocks and forgets, for the global value and an owner', function (): void { settings()->set('site.name', 'Acme'); settings()->set('theme', 'light'); @@ -193,6 +220,102 @@ function api(string $method, string $uri, array $data = [], array $headers = []) ->and(settings()->get('site.name'))->toBe('Moved on'); }); +it('refuses an idempotency key reused with a different body, and applies nothing', function (): void { + api('PUT', 'stores/settings/settings/site.name', ['value' => 'Acme'], ['Idempotency-Key' => 'reused'])->assertOk(); + + test()->json('PUT', '/api/settings/v1/stores/settings/settings/site.name', ['value' => 'Other'], ['Idempotency-Key' => 'reused']) + ->assertUnprocessable() + ->assertHeader('Content-Type', 'application/problem+json') + ->assertHeaderMissing('Idempotent-Replayed'); + + expect(settings()->get('site.name'))->toBe('Acme'); +}); + +it('keys a replay by the resolved actor, not only by the session user', function (): void { + auth()->logout(); + $this->rebootWith(['laranail.settings.http.enabled' => true, 'laranail.settings.http.middleware' => ['api']]); + useDatabase(['verification.driver' => 'none']); + allowGates(...Ability::cases()); + // An application that finds its actor from a header rather than a Laravel guard. + settings()->configuration()->resolveActorsUsing(static fn ($request): ?Actor => is_numeric($request?->header('X-User')) + ? Actor::user(user((int) $request->header('X-User'))) + : null); + + test()->json('PUT', '/api/settings/v1/stores/settings/settings/site.name', ['value' => 'Acme'], ['Idempotency-Key' => 'shared', 'X-User' => '1'])->assertOk(); + settings()->set('site.name', 'Moved on'); + $other = test()->json('PUT', '/api/settings/v1/stores/settings/settings/site.name', ['value' => 'Acme'], ['Idempotency-Key' => 'shared', 'X-User' => '2'])->assertOk(); + + expect($other->headers->get('Idempotent-Replayed'))->toBeNull() + ->and($other->json('data.version'))->toBe(3); +}); + +it('keeps a stored idempotent response encrypted, since it can hold a secret', function (): void { + $directory = sys_get_temp_dir() . '/laranail-settings-idempotency-' . bin2hex(random_bytes(6)); + config()->set('cache.stores.idempotency', ['driver' => 'file', 'path' => $directory]); + config()->set('laranail.settings.http.idempotency.cache', 'idempotency'); + app(DefinitionRegistry::class)->define('mail.password')->encrypted()->register(); + $secret = TestCredentials::secret(); + + api('PUT', 'stores/settings/settings/mail.password', ['value' => $secret], ['Idempotency-Key' => 'secret'])->assertOk()->assertJsonPath('data.value', $secret); + $replay = api('PUT', 'stores/settings/settings/mail.password', ['value' => $secret], ['Idempotency-Key' => 'secret'])->assertOk(); + + $files = array_filter(iterator_to_array(new RecursiveIteratorIterator(new RecursiveDirectoryIterator($directory, FilesystemIterator::SKIP_DOTS))), static fn (SplFileInfo $file): bool => $file->isFile()); + + expect($replay->headers->get('Idempotent-Replayed'))->toBe('true') + ->and($replay->json('data.value'))->toBe($secret) + ->and($files)->toHaveCount(1) + ->and((string) file_get_contents((string) array_key_first($files)))->not->toContain($secret); +}); + +it('applies values.max_bytes to REST writes, imports and promotion alike', function (): void { + config()->set('laranail.settings.values.max_bytes', 64); + app()->forgetInstance(ValuePipeline::class); + app()->forgetScopedInstances(); + $big = str_repeat('x', 100); + + api('PUT', 'stores/settings/settings/site.name', ['value' => $big])->assertUnprocessable() + ->assertJsonPath('type', 'https://opensource.simtabi.com/documentation/laranail/settings/tools/exceptions#invalid-value'); + + $document = ['format' => 'laranail/settings', 'version' => 1, 'store' => 'settings', 'mode' => 'redacted', 'exported_at' => now()->toIso8601String(), 'categories' => [], + 'settings' => [['scope' => 'global', 'key' => 'site.name', 'locale' => '', 'value' => $big, 'encrypted' => false]]]; + api('POST', 'stores/settings/import', ['document' => $document, 'apply' => true])->assertUnprocessable()->assertJsonPath('detail', fn (string $detail): bool => str_contains($detail, 'over the 64-byte limit')); + + Storage::disk('local')->put('laranail/settings/settings.json', (string) json_encode(['records' => [ + ['scope' => 'global', 'key' => 'site.tagline', 'locale' => '', 'payload' => json_encode($big), 'version' => 1], + ]])); + + expect(fn (): PromotionReport => settings()->asSystem()->promote())->toThrow(InvalidSettingValue::class) + ->and(DB::table('settings')->count())->toBe(0); +}); + +it('refuses a malformed cursor instead of serving the first page', function (string $uri): void { + settings()->set('site.name', 'Acme'); + + api('GET', $uri . '?cursor=' . rawurlencode('not a cursor!'))->assertUnprocessable() + ->assertHeader('Content-Type', 'application/problem+json') + ->assertJsonStructure(['errors' => ['cursor']]); +})->with([ + 'settings' => ['stores/settings/settings'], + 'owner' => ['stores/settings/owners/user/1/settings'], + 'history' => ['stores/settings/settings/site.name/history'], + 'changes' => ['stores/settings/changes'], + 'audit' => ['audit'], +]); + +it('accepts the cursors its listings hand out', function (): void { + settings()->set('site.name', 'Acme'); + settings()->set('site.name', 'Acme Ltd'); + settings()->set('theme', 'dark'); + + $settings = api('GET', 'stores/settings/settings?limit=1')->json('meta.next_cursor'); + $history = api('GET', 'stores/settings/settings/site.name/history?limit=1')->json('meta.next_cursor'); + $audit = api('GET', 'audit?limit=1')->json('meta.next_cursor'); + + api('GET', 'stores/settings/settings?limit=1&cursor=' . rawurlencode((string) $settings))->assertOk()->assertJsonPath('data.0.key', 'theme'); + api('GET', 'stores/settings/settings/site.name/history?limit=1&cursor=' . rawurlencode((string) $history))->assertOk()->assertJsonCount(1, 'data'); + api('GET', 'audit?limit=1&cursor=' . rawurlencode((string) $audit))->assertOk()->assertJsonCount(1, 'data'); +}); + it('needs an authenticated user and switches route groups off', function (): void { auth()->logout(); test()->json('GET', '/api/settings/v1/stores')->assertUnauthorized()->assertJsonPath('status', 401); diff --git a/tests/Feature/SettingsApiTest.php b/tests/Feature/SettingsApiTest.php index 8c3284a..762d256 100644 --- a/tests/Feature/SettingsApiTest.php +++ b/tests/Feature/SettingsApiTest.php @@ -5,6 +5,8 @@ use Illuminate\Support\Facades\Storage; use Simtabi\Laranail\Settings\Data\OwnerRef; use Simtabi\Laranail\Settings\Exceptions\TypeMismatch; +use Simtabi\Laranail\Settings\Services\Values\ValuePipeline; +use Simtabi\Laranail\Settings\Exceptions\InvalidSettingValue; it('writes to the runtime file and reads the value back', function (): void { settings()->set('site.name', 'Acme'); @@ -89,3 +91,21 @@ ->and($base->get('ui.theme'))->toBeNull() ->and($scoped->get('ui.theme'))->toBe('dark'); }); + +it('refuses a value whose payload is larger than values.max_bytes, and takes null as no limit', function (): void { + config()->set('laranail.settings.values.max_bytes', 16); + app()->forgetInstance(ValuePipeline::class); + app()->forgetScopedInstances(); + + settings()->set('site.name', str_repeat('a', 14)); // "aaaaaaaaaaaaaa" is 16 bytes encoded + + expect(fn () => settings()->set('site.name', str_repeat('a', 15)))->toThrow(InvalidSettingValue::class, 'over the 16-byte limit') + ->and(settings()->get('site.name'))->toBe(str_repeat('a', 14)); + + config()->set('laranail.settings.values.max_bytes'); + app()->forgetInstance(ValuePipeline::class); + app()->forgetScopedInstances(); + settings()->set('site.name', str_repeat('a', 2048)); + + expect(settings()->get('site.name'))->toHaveLength(2048); +}); diff --git a/tests/Unit/SupportTest.php b/tests/Unit/SupportTest.php index a364562..98f12db 100644 --- a/tests/Unit/SupportTest.php +++ b/tests/Unit/SupportTest.php @@ -8,6 +8,7 @@ use Simtabi\Laranail\Settings\Support\Translations; use Simtabi\Laranail\Settings\Support\DatabaseValues; use Simtabi\Laranail\Settings\Exceptions\DriverFailure; +use Simtabi\Laranail\Settings\Support\RecordSerializer; use Simtabi\Laranail\Settings\Exceptions\InvalidIdentifier; it('builds and reads per-locale title maps', function (): void { @@ -48,3 +49,13 @@ ->and(Scope::global()->owner())->toBeNull() ->and(fn (): ?Scope => Scope::fromString('App\\Models\\User:1'))->toThrow(InvalidIdentifier::class); }); + +it('reports a file record with a bad key, locale, date or version as a malformed record', function (array $row): void { + expect(fn (): mixed => new RecordSerializer()->fromArray(['scope' => 'global', 'key' => 'site.name', ...$row], 'runtime.json')) + ->toThrow(DriverFailure::class, 'A record in [runtime.json] is malformed'); +})->with([ + 'key' => [['key' => 'Not A Key']], + 'locale' => [['locale' => 'zz-garbage-locale']], + 'date' => [['written_at' => 'not a date']], + 'version' => [['version' => 0]], +]);