Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 29 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -141,6 +141,22 @@ Each was removed before the first tag; none was in a tagged release.
- 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.
- An `Idempotency-Key` retry sent while the first request is still running answers `409` instead
of running the write a second time. (SP-04)
- An actor without `approve` saw an empty page of change requests when other people's newer
requests filled the page; their own are now filtered in the query. (SP-05)
- `sync-definitions` read each definition's row and category one query at a time; it now reads
them once per store. (SP-06)
- Every write (set, forget, lock, unlock, and so each row of an import) read all the rows of its
scope, twice, to check one; it now reads that row only. (SP-07)
- The JSON driver lost updates under concurrent writers. A write now holds an exclusive `flock`
on a sidecar `<file>.lock` (local disks) for its read-modify-write, and is version-checked like
the database layer, so a stale writer gets `ConcurrentModification`. (SP-09)
- `laranail::settings.export` and `POST /stores/{store}/export` stream the document, 500 rows per
query, instead of building the whole store in memory; the output bytes are unchanged.
The `StreamExport` action is new; `export()` still returns the `ExportDocument`. (SP-10)
- Two overlapping `sync-definitions` runs no longer fail on each other's rows: the second waits up
to five seconds for a cache lock, then reports `busy` and changes nothing. (SP-11)

### Security

Expand All @@ -159,3 +175,16 @@ Each was removed before the first tag; none was in a tagged release.
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.
- A value stored encrypted is sensitive whatever its definition now says. Redefining or deleting a
runtime definition (`manage_definitions`) used to make the stored secret readable in plaintext
by any actor with `view`, over REST and PHP. Reads now also check the stored row: without
`view_sensitive`, `get()` throws `AccessDenied`, `explain()` and REST redact, listings omit it.
`Lookup::isEncrypted()` is new. (SP-01)
- The REST API refuses a request whose actor resolver returns the system actor (`401`
`actor-required`), which used to skip every check. (SP-02)
- An API token counts as its user in approvals: it can no longer approve its user's own change
request, and a user and their token are one approval towards `min_approvals`. Approvals
recorded under `token:` before this release are read as their user's. (SP-03)
- Idempotent replays are keyed by tenant as well as actor: in `column` or `database` tenancy,
`user:1` of one tenant reusing a key used by `user:1` of another received that tenant's stored
response. (SP-08)
2 changes: 1 addition & 1 deletion docs/tools/access-control.md
Original file line number Diff line number Diff line change
Expand Up @@ -107,7 +107,7 @@ With `locks.overridable` on, an actor allowed `override_lock` may `set` or `forg

## Sensitive settings

Mark a definition `sensitive()` (or `'sensitive' => true` in config); `encrypted()` implies it. Reading one needs `view_sensitive` as well as `view`, and `explain()` redacts its value: `Explanation::isRedacted()` is true, `Lookup::value()` throws, and the layer and steps stay visible.
Mark a definition `sensitive()` (or `'sensitive' => true` in config); `encrypted()` implies it. Reading one needs `view_sensitive` as well as `view`, and `explain()` redacts its value: `Explanation::isRedacted()` is true, `Lookup::value()` throws, and the layer and steps stay visible. A value stored encrypted stays sensitive after its definition is changed or removed: the stored row decides as well as the definition (`Lookup::isEncrypted()`).

## Step-up verification

Expand Down
2 changes: 1 addition & 1 deletion docs/tools/approvals.md
Original file line number Diff line number Diff line change
Expand Up @@ -50,7 +50,7 @@ $settings->as($editor)->approvals()->cancel($id); // the requester only
| Days before an open request expires | 7 | `approvals.expire_after` (null: never) |
| Days a decided request is kept | 90 | `approvals.keep_days` (null: for ever) |

Approving and rejecting need `approve` on the setting. Listing needs `approve` to see everyone's requests; an actor without it sees only their own. Trusted code without an actor sees and decides everything.
An API token acts for its user: a user and their token are one person, so a token cannot approve its user's request, and the two count as one approval towards `min_approvals`. Approving and rejecting need `approve` on the setting. Listing needs `approve` to see everyone's requests; an actor without it sees only their own. Trusted code without an actor sees and decides everything.

## Applying

Expand Down
2 changes: 1 addition & 1 deletion docs/tools/database.md
Original file line number Diff line number Diff line change
Expand Up @@ -79,7 +79,7 @@ table has the `deleted_at` column, so the option can be turned on at any time.

`laranail::settings.sync-definitions` (also run by `install` once the table exists, and by
`doctor --fix`) copies code and config definitions in as read-only `is_system` rows, so UIs can
list them; system rows nothing defines any more are removed.
list them; system rows nothing defines any more are removed. One run at a time: a run that finds another holding the lock waits up to five seconds, then changes nothing and says so (the report's `busy`).

Other rows are definitions edited at runtime. With `database` in `definitions.sources` they answer
for keys no code or config definition covers, so a row can never loosen a coded setting, and a row
Expand Down
2 changes: 1 addition & 1 deletion docs/tools/drivers.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ Described in [Database](database.md): one table per store, version-checked write

## The JSON driver

One file per store. Writes go to a temporary file that is then moved over the real one, which is an atomic rename on local disks. There is no cross-process lock, so two processes writing at the same moment can lose one update; the runtime layer is meant for the install window, not for heavy concurrent writing. A public disk is refused.
One file per store. Writes go to a temporary file that is then moved over the real one, which is an atomic rename on local disks. On a local disk each write holds an exclusive `flock` on a sidecar `<file>.lock` for its read-modify-write, and is version-checked like the database layer: a writer whose base version is stale gets `ConcurrentModification` (a plain `set()` retries once), so no update is lost. Reads take no lock; the rename means a reader never sees half a file. A disk that is not local has no lock, so only the version check guards it; the runtime layer is still meant for the install window, not for heavy concurrent writing. A public disk is refused.

## The PHP driver

Expand Down
2 changes: 2 additions & 0 deletions docs/tools/import-export.md
Original file line number Diff line number Diff line change
Expand Up @@ -49,6 +49,8 @@ php artisan laranail::settings.import storage/settings.json --apply
php artisan laranail::settings.import storage/settings.json --apply --trusted
```

The console command and `POST /stores/{store}/export` stream the document, reading 500 rows at a time, so a large store is never held in memory; the bytes are the ones `export()->toJson()` gives. In PHP, the `StreamExport` action (`handle($request, $stream, $actor)`) writes to any stream; `export()` still returns the whole `ExportDocument`.

An import creates missing categories first, by slug, parents before children, then writes each setting through the normal write pipeline as the actor: validated and cast under the destination's definition, encrypted, with history and one audit entry per key. A setting that needs approval opens a change request instead (the report lists them). Everything runs in one transaction, so one failed write leaves the store as it was. Redacted values, owners the store does not accept and global values for a dedicated store are skipped, each with its reason in the report.

Locks and system categories in a document are applied only by a trusted import (`--trusted` on the console); the PHP `import()` and the REST API never apply them. `import` needs step-up verification by default (`verification.abilities`).
Expand Down
2 changes: 1 addition & 1 deletion docs/tools/rest-api-reference.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ Paths are under `/{http.prefix}/v1`, by default `/api/settings/v1`; set `http.pr
| 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`, 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. |
| Idempotency | every non-`GET` route accepts `Idempotency-Key`; a retry with the same key, tenant, 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; the same key while its first request still runs answers `409` (`http-409`). |
| Pagination | lists answer `{"data": [...], "meta": {"next_cursor": "…" or null}}`; pass `?cursor=<next_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. |
Expand Down
4 changes: 2 additions & 2 deletions docs/tools/rest-api.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ A JSON API over every capability of the PHP API, in this package and off by defa
],
```

No route is registered until `enabled` is true. The routes are declared in `routes/api.php`, and each controller method takes the action it runs as a parameter, so under Octane no request's actor, tenant or stores reach the next one. Routes are named `laranail-settings.api.<name>` (the owner form of a settings route adds `owners.`), run through `http.middleware` and the `laranail-settings` rate limiter, and every write runs through the idempotency middleware. The host's middleware authenticates; the configured actor resolver turns the request into an [actor](access-control.md) on the `rest` channel, so with the `sanctum` resolver a token's `laranail-settings:<ability>` abilities are a ceiling on what it may do. A request nobody is authenticated for is refused (`401`); the API never runs as trusted code.
No route is registered until `enabled` is true. The routes are declared in `routes/api.php`, and each controller method takes the action it runs as a parameter, so under Octane no request's actor, tenant or stores reach the next one. Routes are named `laranail-settings.api.<name>` (the owner form of a settings route adds `owners.`), run through `http.middleware` and the `laranail-settings` rate limiter, and every write runs through the idempotency middleware. The host's middleware authenticates; the configured actor resolver turns the request into an [actor](access-control.md) on the `rest` channel, so with the `sanctum` resolver a token's `laranail-settings:<ability>` abilities are a ceiling on what it may do. A request nobody is authenticated for is refused (`401`), and so is one the resolver maps to the system actor: the API never runs as trusted code.

## Endpoints

Expand Down Expand Up @@ -69,7 +69,7 @@ Idempotency-Key: 6c0d1e8e-…
- **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 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.
- **Idempotency.** A write with an `Idempotency-Key` header is answered from cache when retried (same tenant, 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; one sent while the first request with that key is still running is refused with `409`, so the write runs once (the idempotency cache store must support locks for this, as Laravel's `redis`, `database`, `file` and `array` stores do). 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

Expand Down
1 change: 1 addition & 0 deletions resources/lang/en/settings.php
Original file line number Diff line number Diff line change
Expand Up @@ -76,6 +76,7 @@
'cache_off' => 'Caching is off; nothing to reset.',
'definitions_synced' => 'Synced :synced definition(s); removed :removed stale system row(s).',
'definitions_skipped' => 'Store [:store] skipped: no active database layer, or the definitions table is off.',
'definitions_busy' => 'Another sync-definitions run holds the lock; this one changed nothing. Run it again once that one finishes.',
'definitions_conflict' => '[:key] is defined in code and edited in the table; code wins, the row was left alone.',
'diff_none' => 'No differences (:unchanged setting(s) equal).',
'diff_summary' => ':added to add, :removed only in the store, :changed changed, :unknown not comparable (redacted).',
Expand Down
2 changes: 1 addition & 1 deletion src/Actions/Approvals/ApproveChange.php
Original file line number Diff line number Diff line change
Expand Up @@ -78,7 +78,7 @@ public function handle(ChangeDecision $decision, ?Actor $actor = null): ChangeRe
// 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())]));
$approvals = array_values(array_unique([...array_map(ChangeRequest::normaliseKey(...), $current->approvals), ChangeRequest::actorKey($actor ?? Actor::system())]));
$remaining = max(0, $this->policy->minApprovals - count($approvals));

if ($remaining > 0) {
Expand Down
35 changes: 20 additions & 15 deletions src/Actions/Approvals/QueryChanges.php
Original file line number Diff line number Diff line change
Expand Up @@ -34,21 +34,26 @@ public function handle(ChangeFilter $filter, ?Actor $actor = null, int $limit =
$this->access->assertActorNotRequired(Ability::Approve, $subject);
}

// An actor who may not approve sees only their own requests: filtered in the query, so a
// page is never filled with other people's requests and then emptied.
$own = $actor instanceof Actor && ! $actor->isSystem() && ! $this->access->allows($actor, Ability::Approve, $subject) ? $actor : null;
$database = $store->changeRequestsDatabase();
$requests = $database->attempt($store->name, static fn (): array => SettingChangeRequest::on($database->connectionName())
->matching($filter)
->when($after !== null, static fn (Builder $query): Builder => $query->where('id', '<', $after))
->limit($limit)
->get()
->map(static fn (SettingChangeRequest $request): ChangeRequest => $request->toRequest())
->values()
->all());
$requests = array_values($requests);

if (! $actor instanceof Actor || $actor->isSystem() || $this->access->allows($actor, Ability::Approve, $subject)) {
return $requests;
}

return array_values(array_filter($requests, static fn (ChangeRequest $request): bool => $request->isRequestedBy($actor)));
$requests = $database->attempt($store->name, static function () use ($database, $filter, $own, $after, $limit): array {
$query = SettingChangeRequest::on($database->connectionName())->matching($filter);

if ($own instanceof Actor) {
SettingChangeRequest::requestedBy($query, $own);
}

return $query
->when($after !== null, static fn (Builder $query): Builder => $query->where('id', '<', $after))
->limit($limit)
->get()
->map(static fn (SettingChangeRequest $request): ChangeRequest => $request->toRequest())
->values()
->all();
});

return array_values(array_filter($requests, static fn (ChangeRequest $request): bool => ! $own instanceof Actor || $request->isRequestedBy($own)));
}
}
Loading
Loading