SMRT Integration

Headers at a glance

Verifying a JWT (both headers)

Both shapes are RS256-signed with the same key. Fetch the JWKS, cache by kid, and verify locally.

Expected issuer on all v2 JWTs: boxowl.me. Identity-tier JWTs additionally carry an org claim; receivers MUST verify org matches the configured org slug.

import jwt from 'jsonwebtoken';
import jwksClient from 'jwks-rsa';

const client = jwksClient({
  jwksUri: 'https://api.boxowl.me/.well-known/smrt-jwks.json',
  cache: true,
  rateLimit: true,
});

function verifySmrtJwt(token, opts = {}) {
  const decoded = jwt.decode(token, { complete: true });
  const kid = decoded.header.kid;
  return new Promise((resolve, reject) => {
    client.getSigningKey(kid, (err, key) => {
      if (err) return reject(err);
      jwt.verify(token, key.getPublicKey(), {
        algorithms: ['RS256'],
        issuer: 'boxowl.me',
      }, (err, claims) => {
        if (err) return reject(err);
        // For X-BoxOwl-Identity, also assert the org claim matches.
        if (opts.expectedOrg && claims.org !== opts.expectedOrg) {
          return reject(new Error('org claim mismatch'));
        }
        resolve(claims);
      });
    });
  });
}

Reference implementation: backend/src/main/java/com/boxowl/api/controller/SmrtJwksController.java (the mint side) and demo/api/src/main/java/com/boxowl/perch/security/SmrtJwksVerifier.java (the verification side, Java/Spring).

JWT shape — X-BoxOwl-Smrt

Mintable via POST /api/v1/smrt/session (user JWT auth). The extension calls this at login and every 10 minutes; the rotating sub is what bounds cross-site behavioral tracking to a 10-minute window.

Embedded smrt claim

Every field is optional — empty values drop out entirely. Treat all keys as missing-by-default. All fields are intentionally low-entropy so the SMRT-tier surface stays anonymous; exact-value variants of the same signals are reserved for the PDaaS Identity JWT below.

JWT shape — X-BoxOwl-Identity

Mintable via POST /api/v1/smrt/batch-mint (user JWT auth). The extension calls this on webNavigation.onCommitted for connected-org domains; the response is per-slug so a single call can warm multiple JWTs.

The handle claim is intentionally absent — the pairwise orgUid is the only identifier.

Mint endpoints

The extension is the only normal caller. Each endpoint requires a user JWT in Authorization: Bearer.

Domain-list endpoints

The extension drives its two stores from these endpoints. Both are ETag-conditional — send If-None-Match with the cached ETag; on 304 keep your current payload.

User-side: SMRT profile settings

Users configure their SMRT profile in the BoxOwl app. These endpoints power the Android Settings > Privacy > SMRT Profile screen and the equivalent in the web SPA.

Server-side: receive + verify

Read the inbound header, verify via JWKS, then route on tier. The two header names are mutually exclusive on the wire (the extension's higher-priority rule strips X-BoxOwl-Smrt when X-BoxOwl-Identity is injected).

app.use(async (req, res, next) => {
  const identityToken = req.get('X-BoxOwl-Identity');
  if (identityToken) {
    try {
      const claims = await verifySmrtJwt(identityToken, { expectedOrg: 'acme-coffee' });
      req.boxowlUser = {
        orgUid: claims.sub,
        name: claims.name,
        preferredName: claims.preferredName,       // "Hi Alice"
        verified: claims.verified,
        tier: claims.tier,                         // "pdaas" | "pdaas_true"
        tags: claims.tags || null,                 // PDaaS True only
        smrt: claims.smrt,                         // see SMRT shape
        sizes: claims.sizes || null,               // exact sizes for filtering / pre-pick
        defaultShippingSpeed: claims.defaultShippingSpeed || null,
      };
      return next();
    } catch (e) { /* fall through to SMRT tier */ }
  }

  const smrtToken = req.get('X-BoxOwl-Smrt');
  if (smrtToken) {
    try {
      const claims = await verifySmrtJwt(smrtToken);
      req.boxowlVisitor = {
        sessionUid: claims.sub,                    // rotates every 10 min
        smrt: claims.smrt,                         // anonymous preference signals
        // claims.smrt also carries: language, fit, sizeBuckets
        // — bucketed signals safe to consume even at SMRT tier.
      };
    } catch (e) { /* invalid; treat as anonymous */ }
  }
  next();
});

MV3 first-request constraint

Manifest V3 does not allow async-blocking HTTP requests. The extension installs identity-tier rules on webNavigation.onCommitted, which fires after the initial HTML request is already in flight.

• Tier 1 (X-BoxOwl-Smrt) — installed at extension boot, present from the very first request.
• Tier 2 + 3 (X-BoxOwl-Identity) — the first navigation HTML request to a connected-org domain after extension startup will NOT carry the header. All subsequent in-page requests (XHR, fetch, form submissions, the next click) carry it.

This is acceptable for org integrations that read identity on API calls rather than the document request itself. If your authentication path absolutely needs identity on the first HTML request, fall back to the standard PDaaS exchange / connection flow.

Privacy model

• No PII at Tier 1 — the SMRT JWT carries no name, handle, email, or stable UID. sub rotates every 10 minutes.
• Pairwise orgUid at Tier 2 + 3 — every (user, org) pair gets a unique sub. Two orgs cannot link the same person.
• User-controlled profile — every SMRT field is opt-in; empty values drop out of the JWT.
• Registered-domain-only injection — the extension never injects on unregistered sites. BoxOwl presence isn't revealed.
• BoxOwl doesn't see your traffic — JWTs travel browser → your server. BoxOwl signs and serves JWKS only.