chore(release): v0.4.19

[roncodes]

Release scope

This is the Storefront v0.4.19 release branch. It includes the patch version bump, contract-workflow updates, API reliability fixes already accumulated on dev-v0.4.19, and the restored marketplace backend required by the refactored Storefront App.

Marketplace API

• return paginated network member stores with search, category/tag, online, rating, trending, age, popularity, nearest, and maximum-distance filters
• expose marketplace member locations, categories, products, merchant metadata, reviews, and payment gateways while preserving store-key location and tag contracts
• tenant-scope carts and validate every line's merchant and store location
• enrich cart lines with merchant data without per-line queries
• enforce online membership, product publication/availability, store-location ownership, multi-store policy, and one currency before checkout
• treat authenticated Customer-Token identity as authoritative and reject mismatched customer IDs with 403
• resolve multi-origin service quotes in bulk and preserve one delivery origin per merchant
• constrain store- and product-subject review lookup, creation, and deletion to the authenticated storefront context and owning customer

Security and compatibility

The implementation fails closed across network membership and tenant boundaries. Foreign store, category, product, review, and location IDs are not exposed. Existing single-store API behavior remains supported while network keys gain explicit marketplace behavior. Store keys retain access to their own newly created products for retrieval and cart workflows; marketplace keys only expose published, available products from current member stores.

Validation

• full backend suite: 424 tests, 2675 assertions
• Clover line coverage: 100.00% (7127/7127)
• Clover method coverage: 100.00% (675/675)
• Clover class coverage: 100.00% (134/134)
• PHP CS Fixer dry run across the full changed PHP set: clean
• Postman Native Git collection lint: 288 requests, 0 errors, 0 warnings
• live Postman regression comparison: all 16 marketplace-induced assertions restored to passing; 38 pre-existing fixture/integration assertions remain unchanged from the preceding branch run
• git diff --check: clean

The repository PHPStan configuration currently points at a missing src directory. An explicit changed-path run reaches the existing framework/model-magic baseline rather than producing a usable package gate; this PR does not weaken static-analysis configuration.

Related PRs and rollout

1. Backend API: this PR
2. SDK: feat: add marketplace SDK helpers storefront-js#11
3. App: feat: restore marketplace edition storefront-app#54
4. API specification: docs: document marketplace API contracts postman#34
5. Documentation: docs: add marketplace edition guide fleetbase.io#90

Accept the API and SDK contracts before releasing the app. Documentation and API examples should land with the corresponding backend release.

Review focus

Human review is requested for public API compatibility, network isolation, authenticated customer identity, multi-merchant payment behavior, delivery quote origins, review-subject scoping, and release sequencing.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (1c7534e) to head (25a1de1).

Additional details and impacted files

@@             Coverage Diff              @@
##                main       #88    +/-   ##
============================================
  Coverage     100.00%   100.00%            
- Complexity      1640      1742   +102     
============================================
  Files            135       135            
  Lines           7366      7699   +333     
============================================
+ Hits            7366      7699   +333     

Flag	Coverage Δ
backend	100.00% <100.00%> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[roncodes]

Authorization gap in checkout — not addressed by this branch

Flagging for follow-up. Found while scoping the verification-bypass fix; it is a separate and larger change, so it is deliberately not in this release branch.

CheckoutController takes the customer as a request body parameter and never checks it against the authenticated caller:

// CheckoutController.php:169
$customerId = $request->input('customer');
...
// CheckoutController.php:188
$customer = Customer::findFromCustomerId($customerId);

Storefront requests carry two independent credentials — a store_/network_ key as the bearer, and a Customer-Token header identifying the customer (Support/Storefront.php:109, getCustomerFromToken()). Checkout consults neither when resolving the customer; it trusts the id in the payload.

Impact: anyone holding a storefront key — which is client-side by nature, it ships in the storefront app — can check out as an arbitrary customer by passing their customer_xxxxx public id. Customer public ids are exposed in ordinary API responses, so they are not a secret.

Suggested fix: resolve the customer from Storefront::getCustomerFromToken() and treat the body parameter as, at most, an assertion that must match:

$authenticated = Storefront::getCustomerFromToken();
if ($authenticated && $customerId && $authenticated->public_id !== $customerId) {
    return response()->apiError('Customer does not match the authenticated session.', 403);
}
$customer = $authenticated ?: Customer::findFromCustomerId($customerId);

Guest checkout appears to be a legitimate flow here, which is why this needs a decision rather than a blind patch: if a caller may check out with no Customer-Token at all, the body parameter has to stay supported for that path, and the check can only apply when a token is present. Worth confirming whether guest checkout is intended before changing it.

Related hardening in this branch: the verification bypass is now restricted to designated review accounts, so a leaked code no longer authenticates arbitrary customers.

[roncodes]

Implemented on this branch in c7c2ba2.

A Customer-Token now takes precedence at all three checkout sites (beforeCheckout, createStripeSetupIntentForCustomer, updateStripePaymentIntent), and a body parameter naming a different customer is refused with 403. Guest checkout is preserved — with no token the body parameter is still used.

One subtlety worth noting for review: the comparison normalises the prefix before matching. A storefront customer is stored as a Contact, and findFromCustomerId() rewrites customer_ to contact_ before lookup — so comparing the raw values would never match a caller's own record and would have 403'd every authenticated checkout. Verified that a caller's own customer_ id resolves against their contact_ record, while someone else's is refused.

[roncodes]

API contract findings — two fixes on this branch

Both of these came out of the Storefront API contract run and are pushed here. Flagging them for your review because the second one changes session behaviour.

1. service_quote was rejected by validation even though the controller supports it

CheckoutController reads the quote with or(['serviceQuote', 'service_quote']), so both spellings work downstream — but InitializeCheckoutRequest validated only the camelCase one. A delivery checkout sending the snake_case spelling was rejected with "The service quote field is required." before the controller ever ran, with a perfectly valid quote id in the query string.

That is the spelling our own API reference documents, so /checkouts/before was unreachable via the documented payload for delivery checkouts.

Either spelling now satisfies the requirement. Sending neither on a delivery checkout still fails; pickup still requires neither.

2. The storefront session kept both scopes when the key type changed

SetStorefrontSession::setKey() only ever added keys. Storefront sessions are cookie-backed, so a client that calls a network endpoint and then a store endpoint reuses the same session and ends up with both storefront_store and storefront_network set.

Every query branching on those applies them additively:

->when(session('storefront_store'), fn ($q) => $q->where('store_uuid', session('storefront_store')))
->when(session('storefront_network'), function ($q) {
    $q->whereHas('store.networks', ...);
    $q->where('is_available', 1);
    $q->where('status', 'published');
})

So a store-scoped request silently picked up the stricter network filter too. Cart::findProduct() returned null for a product that plainly belongs to the store, and the cart answered "Invalid product provided to cart!" — with both ids resolving in the URL, which is what made this look like a fixture problem rather than a scoping one.

That is exactly the contract run's shape: List Network Stores (network key) runs before the Cart folder (store key), and products created through the API have status NULL, so the leaked network branch excluded them. ProductController::find and query carry the same both-branches shape and were mis-scoped identically.

setKey() is the only writer of these session keys and each request re-runs the middleware with its own key, so clearing the opposing scope is safe.

Worth your judgement: if any client depends on a network key and a store key being layered on the same session on purpose, this changes that behaviour. I found no code path that reads one while the other is authoritative, but you would know better whether storefront-app or the console relies on it.

[roncodes]

Unfixed, needs a decision: a product created via the public API can never be published

Not touched on this branch — the fix depends on which side you consider correct.

CreateProductRequest allows three statuses:

'status' => 'nullable|string|in:draft,active,archived',

But published is the status the rest of the codebase filters on:

• Models/Product.php:25 — public const PUBLISHED = 'published'
• Models/Product.php:457, Http/Controllers/v1/ProductController.php:351,385, CategoryController.php:53,101, StoreController.php:230 — where('status', 'published')
• Models/Cart.php:709 — the network branch of findProduct()
• Http/Controllers/v1/CheckoutController.php:166 — cart validation at checkout
• Http/Controllers/ProductController.php:110 (internal/console) — writes 'status' => 'published'

So the console creates published products and the public API cannot. status is also nullable with no default, so an API-created product starts as NULL.

Consequences:

1. Network-scoped storefronts never see API-created products — ProductController::query/find require status = 'published' under a network key.
2. Checkout rejects them — CheckoutController:166 looks up cart items with ->where('is_available', 1)->where('status', 'published'), so an API-created product in a cart is not found at capture time. This one bites store-scoped merchants too, not just networks.

Three ways I can see to close it, and I'd rather you pick:

• Add published to the allowed list and default status to published on create — matches what the console already does, and makes the public API a first-class path.
• Change the filters to active — if draft,active,archived is the intended vocabulary and published is legacy, the read side is what's stale.
• Map on write — accept the documented vocabulary and translate active → published internally. Keeps the public contract as-is but leaves two vocabularies in the schema.

Whichever we choose, the contract collection currently sends no status on Create Product, so it exercises the NULL path.

[roncodes]

Unfixed, minor: CartController::retrieveCart() passes its flag into a differently-meaning parameter

Spotted while tracing the cart failure. Not changed here — it alters mutation behaviour and deserves a deliberate call.

// CartController.php:12
protected function retrieveCart(?string $uniqueId, bool $create = false): Cart
{
    return Cart::retrieve($uniqueId, $create);
}

// Cart.php:647
public static function retrieve(?string $id, bool $excludeCheckedout = true): Cart

The flag is named $create at the call site but lands in $excludeCheckedout. Effect:

• retrieve() (the GET action, line 36) passes true → excludes checked-out carts. Correct, by coincidence of the name.
• add, update, remove, empty, delete (lines 53, 77, 97, 115, 129) all take the default false → they will happily mutate a cart that has already been checked out.

So after a checkout captures an order, the same cart_* id still accepts item additions and removals. I don't know whether storefront-app relies on that (e.g. re-ordering from a past cart), which is why I've left it alone.

If checked-out carts should be immutable, the fix is to drop the passthrough flag and let Cart::retrieve() keep its true default. If the current behaviour is intentional, the parameter should at least be renamed so it stops reading as "create".