inertia start

v1.1.0

v1.1.0

This release opens visitor contexts to your other first-party websites. A new public endpoint lets your other sites resolve the same anonymous context as the application.

Highlights

  • New public POST /api/context endpoint returning the visitor's context ID.
  • New I_S_CONTEXT_ALLOWED_ORIGINS environment variable listing the other first-party origins allowed to use it.
  • Browser requests coming from an origin that is not allowed are rejected.

Added

  • Added App\Http\Controllers\Api\ContextController, registered as POST /api/context. It runs the API SetContext middleware, is rate-limited to 60 requests per minute, and returns the resolved context as {"contextId": ...} with a no-store Cache-Control header. A request that resolves no context returns a 422.
  • Added the context_allowed_origins option to config/inertia-start.php, built from the new I_S_CONTEXT_ALLOWED_ORIGINS environment variable. The value is a comma-separated list of origins; entries are trimmed, empty ones are dropped, and duplicates are removed. The application's own origin is always accepted and does not need to be listed.
  • Added I_S_CONTEXT_ALLOWED_ORIGINS to .env.example.
  • Added feature coverage for the new endpoint in tests/Feature/GuestContextTest.php: resolving a context from an allowed origin, the browser preflight request, the missing fingerprint and unknown origin rejections, and an existing fingerprint being reused instead of creating a second context.

Changed

  • App\Http\Middleware\Api\SetContext now checks the Origin header of requests carrying an X-Guest fingerprint. A request whose origin is neither the application's own origin nor one of context_allowed_origins is rejected with a 403. Requests sent without an Origin header, such as server-to-server calls, are unaffected.
  • The middleware now ignores an empty X-Guest header. Previously the header only had to be present, so an empty value produced a context keyed on the client IP address alone.

Upgrade Guide

  1. No migration and no configuration change are required. Without I_S_CONTEXT_ALLOWED_ORIGINS, the new endpoint only answers browser requests coming from the application's own origin.

  2. To share contexts with another first-party website, add its origin to I_S_CONTEXT_ALLOWED_ORIGINS in your .env file:

    I_S_CONTEXT_ALLOWED_ORIGINS=https://www.example.com,https://docs.example.com

    Origins are matched exactly: scheme and host, plus the port when one is used, with no path and no trailing slash.

  3. That website then sends its Thumbmark fingerprint to POST /api/context in the X-Guest header and reuses the returned context ID, for instance to identify its Umami session with context:{contextId}. Keep @thumbmarkjs/thumbmarkjs at the same version on both sides, since two versions can produce two different fingerprints for the same browser.

  4. If you do not want to expose the endpoint at all, remove the context route from routes/api.php.