Auth & Sessions

There are three distinct auth contexts: Shopify OAuth (install), embedded merchant sessions, and the admin/operator PIN.

Shopify OAuth (install)

• Install — GET /api/auth/install?shop=… builds the Shopify install URL with a signed state, sets shopify_oauth_state + return-host cookies, redirects to Shopify.
• Callback — /api/auth/callback (and /auth/callback) validates HMAC + state, exchanges the code for an access token, and stores it encrypted in platform_connections (TOKEN_ENCRYPTION_KEY). upsertStore creates/updates the stores row and sets trial dates on first install.

Embedded merchant access

• Embedded pages render inside Shopify admin via App Bridge. The shell is detected with the x-tryvio-shell: embedded header (set when host is present); layout.tsx injects the App Bridge script and shopify-api-key meta only then.
• Server pages use requireInstalledMerchantPageAccess() to resolve the authorized shopDomain from the embedded session/cookies.
• Shopify-API-backed route handlers use resolveAuthorizedShopForShopifyRequest(request).

Storefront (public) requests

• Widget endpoints under /api/storefront/* are public (CORS-enabled) and are scoped by shopDomain + a server-created tryon_sessions row. Abuse is bounded by enforceAuditWindowLimit (IP fingerprint) and per-shopper rate limits.

Admin / operator

• /admin is gated by a PIN session (requireAdminSession, /api/admin/login, ADMIN_AUTH_EMAIL). All /api/admin/* handlers call requireAdminSession() and return 401 on Unauthorized.

Token encryption

Access tokens are encrypted at rest using TOKEN_ENCRYPTION_KEY. Never log raw tokens.