Buyer browser                Storefront                   Your app server
─────────────                ──────────                   ───────────────
GET                          1. Match /apps/{handle}/*    4. Verify signature
/apps/shiprocket/api/                                        from query
  tracking?awb=ABC123  ───►  2. Look up your appProxy   ──► 5. Run handler
                                manifest (URL + secret)     6. Respond
                             3. Forward + sign:               (JSON or
                                ?shop=…&path_prefix=…         application/liquid)
                                &timestamp=…&signature=…
                                                       ◄──
                          ◄──  7. Stream body back
                               (Liquid responses are
                                rendered through the
                                theme first)

{
  "handle": "shiprocket",
  "name": "Shiprocket",
  "version": "1.0.0",
  "extensions": {
    "appProxy": {
      "url":            "https://shiprocket.your-domain.app",
      "subpath":        "shiprocket",
      "subpath_prefix": "apps",
      "description":    "Storefront proxy for tracking + AWB lookup."
    }
  }
}

awb=ABC123path_prefix=/apps/shiprocketshop=acme-storetimestamp=1716700000

signature = hex(HMAC-SHA256(canonical, your_app.clientSecret))

import express from 'express';
import { requireAppProxySignature } from '@launchmystore/apps-shared';

const app = express();

const requireProxy = requireAppProxySignature({
  clientSecret: process.env.CLIENT_SECRET,
  // Reject timestamps older than 5 minutes (default).
  maxSkewSeconds: 300,
  // Set true in dev so unsigned curl requests still go through.
  // ALWAYS false in production.
  optional: process.env.NODE_ENV !== 'production',
});

app.get('/api/tracking', requireProxy, (req, res) => {
  // Verified context attached by the middleware:
  //   req.appProxy = { shop, pathPrefix, timestamp, verified }
  const shop = req.appProxy.shop;
  const awb  = req.query.awb;

  // ...look up the merchant's carrier creds by `shop`, call the carrier...
  res.json({ status: 'In Transit', shop, awb });
});

import crypto from 'node:crypto';

function verify(query, clientSecret) {
  const { signature, ...rest } = query;
  if (!signature) return false;

  const canonical = Object.keys(rest)
    .sort()
    .map((k) => {
      const v = Array.isArray(rest[k]) ? rest[k].join(',') : String(rest[k]);
      return `${k}=${v}`;
    })
    .join('');

  const expected = crypto.createHmac('sha256', clientSecret)
    .update(canonical)
    .digest('hex');

  // Constant-time compare
  return signature.length === expected.length
    && crypto.timingSafeEqual(Buffer.from(signature, 'hex'), Buffer.from(expected, 'hex'));
}

const skew = Math.abs(Math.floor(Date.now() / 1000) - Number(query.timestamp));
if (skew > 300) return false; // 5-minute window

app.get('/api/tracking', requireProxy, async (req, res) => {
  const data = await fetchCarrierStatus(req.query.awb);
  res.json(data);
});

// From a storefront block's JS:
fetch('/apps/shiprocket/api/tracking?awb=' + awb)
  .then(r => r.json())
  .then(renderStatus);

app.get('/dashboard', requireProxy, (req, res) => {
  res.setHeader('Content-Type', 'application/liquid');
  res.send(`
    {% layout 'theme' %}
    <main class="page-wrap">
      <h1>Welcome back, {{ customer.first_name | default: 'friend' }}</h1>
      <p>Your loyalty points: <strong>{{ customer.metafields.app_loyalty.points }}</strong></p>
    </main>
  `);
});

{% comment %} snippets/shiprocket-tracking.aqua {% endcomment %}
<div id="shiprocket-tracking" data-awb="{{ order.metafields.app_shiprocket.awb }}">
  Loading shipment status...
</div>
<script>
  (function() {
    var el = document.getElementById('shiprocket-tracking');
    var awb = el.dataset.awb;
    if (!awb) return;
    fetch('/apps/shiprocket/api/tracking?awb=' + encodeURIComponent(awb))
      .then(function(r) { return r.json(); })
      .then(function(d) {
        el.innerHTML = '<strong>' + d.status + '</strong><br>' + d.last_scan;
      });
  })();
</script>

Cache-Control: public, max-age=60, s-maxage=300

// app.json — dev variant
"extensions": {
  "appProxy": {
    "url":            "https://your-tunnel.ngrok.app",
    "subpath":        "shiprocket",
    "subpath_prefix": "apps"
  }
}

import { signAppProxyUrl } from '@launchmystore/apps-shared';

const url = signAppProxyUrl({
  baseUrl:      'http://localhost:4101',
  subPath:      '/api/tracking',
  extraQuery:   { awb: 'ABC123' },
  shop:         'acme-store',
  pathPrefix:   '/apps/shiprocket',
  clientSecret: process.env.CLIENT_SECRET,
});

const res = await fetch(url);
// → exercises the same canonical-string + HMAC path the platform uses.