@raketa-cloud/admin 1.9.0 → 1.9.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@raketa-cloud/admin",
-  "version": "1.9.0",
+  "version": "1.9.2",
   "main": "src/index.js",
   "files": [
     "src/",

package/src/cloud/Resources.js

@@ -1,3 +1,4 @@
+import { buildMagicPreviewAddress } from "../magicPreview";
 import { toDateInput, toDateTimeInput, toUTCISO8601String } from "../utils";
 import RaketaClient from "./RaketaClient";
 import {
@@ -162,6 +163,14 @@ export default class Resources extends RaketaClient {
 
     input.workflow = {
       type: workflow.type,
+      previewUrl: buildMagicPreviewAddress(
+        {
+          slug: input.resource.slug,
+          locale: input.locale,
+          resourceType: input.resource.resourceType,
+        },
+        this.getConfig(),
+      ),
     };
 
     if (workflow.due_date) {

package/src/helpers/AuthHelper.js

@@ -25,7 +25,12 @@ const AuthHelper = {
   isAuthenticated: ({ path, token }) => {
     const ALLOWED_PATHS = ["/login", "/auth/google/callback", "/remote/verify"];
 
-    if (ALLOWED_PATHS.includes(path)) return true;
+    if (
+      ALLOWED_PATHS.includes(path) ||
+      path?.startsWith("/remote/magic-preview/")
+    ) {
+      return true;
+    }
 
     if (token && AuthHelper.verifyJWT(token)) return true;
 

package/src/helpers/reports/googleAuth.js

@@ -1,9 +1,9 @@
 // Service-account auth for the GA4 Data API (the Insights tab).
 //
 // GA is per-property authorized: it rejects API keys and needs a principal. The
-// key file at config.ga.serviceAccountPath (GOOGLE_APPLICATION_CREDENTIALS)
-// provides one with no human in the loop — sign a JWT with it, swap that for an
-// access token. Nothing is persisted, so a restart costs one token exchange.
+// key at config.ga.serviceAccount (GOOGLE_APPLICATION_CREDENTIALS) provides one
+// with no human in the loop — sign a JWT with it, swap that for an access token.
+// Nothing is persisted, so a restart costs one token exchange.
 //
 // The key's client_email needs Viewer access on the GA property.
 import { createSign } from "node:crypto";
@@ -18,44 +18,93 @@ const SCOPE = "https://www.googleapis.com/auth/analytics.readonly";
 const TOKEN_LIFETIME_S = 3600;
 const EXPIRY_SKEW_MS = 60 * 1000;
 
-// Parsed key files by path, access tokens by client_email, plus the in-flight
-// token exchange per client_email (see accessToken).
+// Parsed keys by credential source, access tokens by client_email, plus the
+// in-flight token exchange per client_email (see accessToken).
 const keyCache = new Map();
 const tokenCache = new Map();
 const pendingTokens = new Map();
 
-// True when a key path is configured — gates the Insights tab, so an
+const credentialSource = (ga = {}) => ga.serviceAccount;
+
+// True when a credential is configured — gates the Insights tab, so an
 // unconfigured admin sees no GA UI at all.
 export const serviceAccountConfigured = (ga = {}) =>
-  Boolean(ga.serviceAccountPath);
+  Boolean(credentialSource(ga));
+
+// GOOGLE_APPLICATION_CREDENTIALS now holds the whole key JSON rather than a path
+// to it, so a source can be: an already-parsed object, the JSON itself, that
+// JSON base64-encoded (what most hosts accept without quoting headaches), or a
+// file path.
+function parseCredentialSource(source) {
+  if (typeof source === "object") return { key: source, label: "config" };
+
+  const value = source.trim();
+
+  if (value.startsWith("{")) {
+    try {
+      return {
+        key: JSON.parse(value),
+        label: "GOOGLE_APPLICATION_CREDENTIALS",
+      };
+    } catch (err) {
+      throw new Error(
+        `Could not parse the service-account key JSON in GOOGLE_APPLICATION_CREDENTIALS: ${err.message}`,
+      );
+    }
+  }
 
-function serviceAccountKey(ga = {}) {
-  const path = ga.serviceAccountPath;
+  const decoded = decodeBase64Json(value);
+  if (decoded) {
+    return {
+      key: decoded,
+      label: "GOOGLE_APPLICATION_CREDENTIALS (base64)",
+    };
+  }
 
-  if (!path) {
+  try {
+    return { key: JSON.parse(readFileSync(value, "utf8")), label: value };
+  } catch (err) {
     throw new Error(
-      "Google service-account key is not set. Point GOOGLE_APPLICATION_CREDENTIALS at the key file (surfaced via config.ga.serviceAccountPath).",
+      `Could not read the service-account key at ${value}: ${err.message}`,
     );
   }
+}
 
-  if (keyCache.has(path)) return keyCache.get(path);
+// Only claims a value as base64 when it decodes to a JSON object — anything
+// else is a path, and a path must keep reporting a read error, not a parse one.
+function decodeBase64Json(value) {
+  if (!/^[A-Za-z0-9+/_-]+={0,2}$/.test(value)) return null;
 
-  let key;
   try {
-    key = JSON.parse(readFileSync(path, "utf8"));
-  } catch (err) {
+    const decoded = Buffer.from(value, "base64").toString("utf8").trim();
+    return decoded.startsWith("{") ? JSON.parse(decoded) : null;
+  } catch {
+    return null;
+  }
+}
+
+function serviceAccountKey(ga = {}) {
+  const source = credentialSource(ga);
+
+  if (!source) {
     throw new Error(
-      `Could not read the service-account key at ${path}: ${err.message}`,
+      "Google service-account key is not set. Put the key JSON in GOOGLE_APPLICATION_CREDENTIALS (surfaced via config.ga.serviceAccount).",
     );
   }
 
+  if (typeof source === "string" && keyCache.has(source)) {
+    return keyCache.get(source);
+  }
+
+  const { key, label } = parseCredentialSource(source);
+
   if (!key.client_email || !key.private_key) {
     throw new Error(
-      `The service-account key at ${path} has no client_email / private_key.`,
+      `The service-account key from ${label} has no client_email / private_key.`,
     );
   }
 
-  keyCache.set(path, key);
+  if (typeof source === "string") keyCache.set(source, key);
   return key;
 }
 

package/src/helpers/reports/reportsUtils.js

@@ -135,7 +135,7 @@ async function fetchQuickInsights(ctx, resource, resourceType) {
   try {
     if (!gaEnabled(ctx)) {
       throw new Error(
-        "Google Analytics is not configured. Set config.ga.propertyId and config.ga.serviceAccountPath (GOOGLE_APPLICATION_CREDENTIALS) to enable reports.",
+        "Google Analytics is not configured. Set config.ga.propertyId and config.ga.serviceAccount (GOOGLE_APPLICATION_CREDENTIALS) to enable reports.",
       );
     }
     const pagePath = gaPagePath(ctx, resource, resourceType);

package/src/magicPreview.js

@@ -0,0 +1,103 @@
+import {
+  createCipheriv,
+  createDecipheriv,
+  createHash,
+  randomBytes,
+} from "node:crypto";
+
+const ALGORITHM = "aes-256-gcm";
+const IV_LENGTH = 12;
+const TAG_LENGTH = 16;
+
+function getSecretKey(config = {}) {
+  const secret = config.secrets.crypto_secret;
+
+  if (!secret) {
+    throw new Error(
+      "crypto_secret needs to be setup in the config for the magic preview feature to work",
+    );
+  }
+
+  return createHash("sha256").update(secret).digest();
+}
+
+export function generateMagicPreviewToken(
+  { slug, resourceType, locale } = {},
+  config = {},
+) {
+  const payload = {
+    slug,
+    resourceType,
+    locale,
+  };
+
+  const key = getSecretKey(config);
+  const iv = randomBytes(IV_LENGTH);
+  const cipher = createCipheriv(ALGORITHM, key, iv);
+  const encrypted = Buffer.concat([
+    cipher.update(JSON.stringify(payload), "utf8"),
+    cipher.final(),
+  ]);
+  const tag = cipher.getAuthTag();
+
+  return Buffer.concat([iv, tag, encrypted]).toString("base64url");
+}
+
+export function decipherMagicPreviewToken(token, config) {
+  if (!token || typeof token !== "string") {
+    return null;
+  }
+
+  try {
+    const key = getSecretKey(config);
+    const combined = Buffer.from(token, "base64url");
+
+    if (combined.length < IV_LENGTH + TAG_LENGTH) {
+      return null;
+    }
+
+    const iv = combined.subarray(0, IV_LENGTH);
+    const tag = combined.subarray(IV_LENGTH, IV_LENGTH + TAG_LENGTH);
+    const encrypted = combined.subarray(IV_LENGTH + TAG_LENGTH);
+
+    const decipher = createDecipheriv(ALGORITHM, key, iv);
+    decipher.setAuthTag(tag);
+
+    const decrypted = Buffer.concat([
+      decipher.update(encrypted),
+      decipher.final(),
+    ]).toString("utf8");
+
+    const payload = JSON.parse(decrypted);
+
+    if (!payload || typeof payload !== "object" || !payload.slug) {
+      return null;
+    }
+
+    return payload;
+  } catch {
+    return null;
+  }
+}
+
+export function buildMagicPreviewAddress(
+  { slug, resourceType, locale },
+  globalConfig,
+) {
+  if (!slug || !resourceType || !locale) {
+    throw new Error(
+      "Can't generate a token without a slug, resourceType or locale!",
+    );
+  }
+
+  const token = generateMagicPreviewToken(
+    {
+      slug,
+      resourceType,
+      locale,
+    },
+    globalConfig,
+  );
+
+  return globalConfig.remoteConfig.magicPreviewUrl(token, resourceType, locale);
+}

package/src/setupAuthentication.js

@@ -3,6 +3,7 @@ import { deleteCookie, getCookie, setCookie } from "hono/cookie";
 import currentPath from "./currentPath.cjs";
 import AuthHelper from "./helpers/AuthHelper";
 import cipher from "./cipher";
+import { decipherMagicPreviewToken } from "./magicPreview";
 
 const DELIMITER = ",";
 
@@ -149,6 +150,17 @@ const setupAuthentication = (app, config) => {
 
     return c.json({ token });
   });
+
+  app.get("/remote/magic-preview/:token", (c) => {
+    const token = c.req.param("token") || "";
+    const payload = decipherMagicPreviewToken(token, config);
+
+    if (!payload?.slug) {
+      return c.json({ error: "Invalid or expired preview token" }, 404);
+    }
+
+    return c.json(payload);
+  });
 };
 
 export default setupAuthentication;

package/src/tests/handlers/resources/ReportsAPIHandler.test/show.test.js

@@ -15,7 +15,8 @@ import ReportsAPIHandler from "../../../../handlers/resources/ReportsAPIHandler"
 
 import Factory from "../../../support/factory";
 
-const SERVICE_ACCOUNT_PATH = "/tmp/service-account.json";
+const SERVICE_ACCOUNT =
+  '{"client_email":"reports@project.iam.gserviceaccount.com","private_key":"pem"}';
 
 describe("Reports API Handler", () => {
   function buildCtx(resource, { ga, reports = true } = {}) {
@@ -63,7 +64,7 @@ describe("Reports API Handler", () => {
     const ctx = buildCtx(resource, {
       ga: {
         propertyId: "1234",
-        serviceAccountPath: SERVICE_ACCOUNT_PATH,
+        serviceAccount: SERVICE_ACCOUNT,
         apiKey: "crux-key",
       },
     });
@@ -98,7 +99,7 @@ describe("Reports API Handler", () => {
   test("does not cache the assembled payload", async () => {
     const resource = Factory.build("resource", { translations: {} });
     const ctx = buildCtx(resource, {
-      ga: { propertyId: "1234", serviceAccountPath: SERVICE_ACCOUNT_PATH },
+      ga: { propertyId: "1234", serviceAccount: SERVICE_ACCOUNT },
     });
 
     jest.spyOn(ctx.client.resources, "find").mockImplementation(() => resource);
@@ -117,7 +118,7 @@ describe("Reports API Handler", () => {
   test("passes a failed side through as an error", async () => {
     const resource = Factory.build("resource", { translations: {} });
     const ctx = buildCtx(resource, {
-      ga: { propertyId: "1234", serviceAccountPath: SERVICE_ACCOUNT_PATH },
+      ga: { propertyId: "1234", serviceAccount: SERVICE_ACCOUNT },
     });
 
     jest.spyOn(ctx.client.resources, "find").mockImplementation(() => resource);

package/src/tests/handlers/resources/ResourcesHandler.test/show_reports.test.js

@@ -46,7 +46,7 @@ describe("Resources Handler show reports section", () => {
     const resource = Factory.build("resource", { translations: {} });
     const ctx = buildCtx(resource, {
       propertyId: "1234",
-      serviceAccountPath: "/tmp/service-account.json",
+      serviceAccount: "{}",
       apiKey: "crux-key",
     });
     mockClient(ctx, resource);
@@ -65,7 +65,7 @@ describe("Resources Handler show reports section", () => {
     const resource = Factory.build("resource", { translations: {} });
     const ctx = buildCtx(resource, {
       propertyId: "1234",
-      serviceAccountPath: "/tmp/service-account.json",
+      serviceAccount: "{}",
     });
     mockClient(ctx, resource);
 

package/src/tests/handlers/resources/TranslationsHandler.test/create.test.js

@@ -5,8 +5,26 @@ import Factory from "../../../support/factory";
 
 function buildCtx(params, resource) {
   return {
+    globalConfig: {
+      i18n: { defaultLocale: "en" },
+      remoteConfig: {
+        magicPreviewUrl: (token, type, loc) =>
+          `https://example.com/${loc}/magic-preview/${type}s/${token}`,
+      },
+    },
     client: {
-      resources: new Resources(() => ({}), "token"),
+      resources: new Resources(
+        () => ({
+          secrets: {
+            crypto_secret: "super-secret-for-testing-1234",
+          },
+          remoteConfig: {
+            magicPreviewUrl: (token, type, loc) =>
+              `https://example.com/${loc}/magic-preview/${type}s/${token}`,
+          },
+        }),
+        "token",
+      ),
       resourceRevisions: new ResourceRevisions(() => ({}), "token"),
     },
     params: { parent_id: resource.id },
@@ -327,4 +345,64 @@ describe("Resource Translations Handler", () => {
       },
     });
   });
+
+  test("create generates previewUrl when workflow is provided", async () => {
+    const resource = Factory.build("resource", {
+      translations: {},
+      categories: [{ id: "cat1" }],
+    });
+
+    const params = {
+      languages: ["fr"],
+      workflow: {
+        type: "LOKALISE_TT_AI",
+      },
+    };
+
+    const ctx = buildCtx(params, resource);
+
+    jest.spyOn(ctx.client.resources, "find").mockImplementation(() => resource);
+    const mockQuery = jest
+      .spyOn(ctx.client.resources, "query")
+      .mockImplementation(() => ({
+        translate0: {
+          resource: {
+            id: "translated-resource-fr",
+            slug: "resource-slug",
+            visibility: "public",
+          },
+          errors: null,
+        },
+      }));
+
+    const result = await TranslationsHandler.create(ctx);
+
+    expect(mockQuery).toHaveBeenCalledWith(expect.any(String), {
+      input0: {
+        locale: "fr",
+        resource: {
+          categories: ["cat1"],
+          resourceType: "article",
+          settings:
+            '{"layout":"default","meta":{"title":"Open graph","description":"Open graph???","image":{}}}',
+          slug: "resource-slug",
+          tags: [],
+          title: "Resource Title",
+          visibility: "private",
+          widgets: "[]",
+        },
+        sourceResourceId: "2",
+        workflow: {
+          previewUrl: expect.stringMatching(
+            /^https:\/\/example\.com\/fr\/magic-preview\/articles\/[A-Za-z0-9_-]+$/,
+          ),
+          type: "LOKALISE_TT_AI",
+        },
+      },
+    });
+
+    expect(result).toEqual({
+      redirect: `/en/articles/${resource.id}/translations?translations=fr:translated-resource-fr`,
+    });
+  });
 });

package/src/tests/helpers/AuthHelper.test.js

@@ -69,6 +69,16 @@ describe("AuthHelper", () => {
         AuthHelper.isAuthenticated({ path: "/auth/google/callback" }),
       ).toBe(true);
       expect(AuthHelper.isAuthenticated({ path: "/remote/verify" })).toBe(true);
+      expect(
+        AuthHelper.isAuthenticated({
+          path: "/remote/magic-preview/any-token-here",
+        }),
+      ).toBe(true);
+      expect(
+        AuthHelper.isAuthenticated({
+          path: "/remote/magic-preview/:token",
+        }),
+      ).toBe(true);
     });
 
     test("returns true for valid token", () => {

package/src/tests/helpers/reports/quick-insights.test.js

@@ -14,31 +14,31 @@ import {
 } from "../../../helpers/reports/quick-insights";
 import localCache from "../../../localCache";
 
-// One throwaway RSA key written to a temp file — the module reads the key from
-// ga.serviceAccountPath, exactly like it does in the app.
+// One throwaway RSA key. The app passes the whole key JSON through
+// ga.serviceAccount, so that is the form used here; the same key is also written
+// to a temp file, since that config value also accepts a path.
 const { privateKey } = generateKeyPairSync("rsa", {
   modulusLength: 2048,
   privateKeyEncoding: { type: "pkcs8", format: "pem" },
   publicKeyEncoding: { type: "spki", format: "pem" },
 });
 
+const keyJson = JSON.stringify({
+  type: "service_account",
+  client_email: "reports@project.iam.gserviceaccount.com",
+  private_key_id: "key-1",
+  private_key: privateKey,
+});
+
 const dir = mkdtempSync(join(tmpdir(), "quick-insights-"));
 const keyPath = join(dir, "service-account.json");
 const missingPath = join(dir, "nope.json");
 const brokenPath = join(dir, "broken.json");
 
-writeFileSync(
-  keyPath,
-  JSON.stringify({
-    type: "service_account",
-    client_email: "reports@project.iam.gserviceaccount.com",
-    private_key_id: "key-1",
-    private_key: privateKey,
-  }),
-);
+writeFileSync(keyPath, keyJson);
 writeFileSync(brokenPath, JSON.stringify({ client_email: "a@b.c" }));
 
-const GA = { propertyId: "1234", serviceAccountPath: keyPath };
+const GA = { propertyId: "1234", serviceAccount: keyJson };
 
 const reportBody = {
   rows: [
@@ -80,13 +80,13 @@ describe("quick-insights auth", () => {
     delete global.fetch;
   });
 
-  test("serviceAccountConfigured follows the key path", () => {
+  test("serviceAccountConfigured follows the credential", () => {
     expect(serviceAccountConfigured(GA)).toBe(true);
     expect(serviceAccountConfigured({})).toBe(false);
     expect(serviceAccountConfigured()).toBe(false);
   });
 
-  test("signs a JWT from the key file and calls the Data API with it", async () => {
+  test("signs a JWT from the key JSON and calls the Data API with it", async () => {
     mockGoogle();
 
     const result = await runPageReport({
@@ -129,6 +129,29 @@ describe("quick-insights auth", () => {
     expect(result.rows).toEqual([{ date: "2026-07-01", views: 4 }]);
   });
 
+  // Hosts that dislike raw JSON in an env var get the base64 form; a path is
+  // still accepted for anything pointing at a key file.
+  test.each([
+    ["base64 key JSON", Buffer.from(keyJson).toString("base64")],
+    ["a key file path", keyPath],
+  ])("accepts %s", async (_label, serviceAccount) => {
+    mockGoogle();
+
+    const result = await runPageReport({
+      pagePath: "/pricing",
+      startDate: "2026-07-01",
+      endDate: "2026-07-01",
+      ga: { propertyId: "1234", serviceAccount },
+    });
+
+    const [, tokenOptions] = global.fetch.mock.calls[0];
+    const [, claims] = Object.fromEntries(tokenOptions.body).assertion.split(
+      ".",
+    );
+    expect(decode(claims).iss).toBe("reports@project.iam.gserviceaccount.com");
+    expect(result.rows).toEqual([{ date: "2026-07-01", views: 4 }]);
+  });
+
   test("reuses the access token across reports", async () => {
     mockGoogle();
 
@@ -203,7 +226,7 @@ describe("quick-insights auth", () => {
     await expect(runPageReport(args)).rejects.toThrow(/GA Data API 403/);
   });
 
-  test("reports unusable key paths", async () => {
+  test("reports unusable credentials", async () => {
     // The property id is checked while building the request URL, so every case
     // here keeps it set — otherwise that error would mask the key one.
     mockGoogle();
@@ -220,13 +243,25 @@ describe("quick-insights auth", () => {
     await expect(
       runPageReport({
         ...args,
-        ga: { propertyId: "1234", serviceAccountPath: missingPath },
+        ga: { propertyId: "1234", serviceAccount: '{"client_email":' },
+      }),
+    ).rejects.toThrow(/Could not parse the service-account key JSON/);
+    await expect(
+      runPageReport({
+        ...args,
+        ga: { propertyId: "1234", serviceAccount: '{"client_email":"a@b.c"}' },
+      }),
+    ).rejects.toThrow(/no client_email \/ private_key/);
+    await expect(
+      runPageReport({
+        ...args,
+        ga: { propertyId: "1234", serviceAccount: missingPath },
       }),
     ).rejects.toThrow(/Could not read the service-account key/);
     await expect(
       runPageReport({
         ...args,
-        ga: { propertyId: "1234", serviceAccountPath: brokenPath },
+        ga: { propertyId: "1234", serviceAccount: brokenPath },
       }),
     ).rejects.toThrow(/no client_email \/ private_key/);
   });
@@ -239,7 +274,7 @@ describe("quick-insights auth", () => {
         pagePath: "/pricing",
         startDate: "2026-07-01",
         endDate: "2026-07-01",
-        ga: { serviceAccountPath: keyPath },
+        ga: { serviceAccount: keyJson },
       }),
     ).rejects.toThrow(/GA property id is not set/);
   });

package/src/tests/magicPreview.test.js

@@ -0,0 +1,127 @@
+import {
+  buildMagicPreviewAddress,
+  decipherMagicPreviewToken,
+  generateMagicPreviewToken,
+} from "../magicPreview";
+
+describe("magicPreview helper", () => {
+  const config = {
+    secrets: {
+      crypto_secret: "super-secret-key-for-testing-123456",
+    },
+    i18n: {
+      defaultLocale: "en",
+      locales: { en: {}, de: {}, fr: {} },
+    },
+    remoteConfig: {
+      magicPreviewUrl: (token, resourceType, locale) => {
+        return [
+          "https://example.com",
+          locale === "en" ? "" : locale,
+          "magic-preview",
+          resourceType === "page" ? "" : resourceType,
+          token,
+        ]
+          .filter(Boolean)
+          .join("/");
+      },
+    },
+  };
+
+  describe("buildMagicPreviewAddress", () => {
+    it("builds full preview URL using remoteConfig.magicPreviewUrl", () => {
+      const address = buildMagicPreviewAddress(
+        {
+          slug: "gocardless",
+          resourceType: "customer",
+          locale: "en",
+        },
+        config,
+      );
+
+      expect(address).toMatch(
+        /^https:\/\/example\.com\/magic-preview\/customer\/[A-Za-z0-9_-]+$/,
+      );
+    });
+
+    it("builds localized preview URL for non-default locale", () => {
+      const address = buildMagicPreviewAddress(
+        {
+          slug: "gocardless",
+          resourceType: "customer",
+          locale: "de",
+        },
+        config,
+      );
+
+      expect(address).toMatch(
+        /^https:\/\/example\.com\/de\/magic-preview\/customer\/[A-Za-z0-9_-]+$/,
+      );
+    });
+
+    it("throws an error for missing slug", () => {
+      expect(() => {
+        buildMagicPreviewAddress(
+          { resourceType: "page", locale: "de" },
+          config,
+        );
+      }).toThrow(
+        "Can't generate a token without a slug, resourceType or locale!",
+      );
+    });
+
+    it("throws an error for missing resourceType", () => {
+      expect(() => {
+        buildMagicPreviewAddress({ slug: "page", locale: "de" }, config);
+      }).toThrow(
+        "Can't generate a token without a slug, resourceType or locale!",
+      );
+    });
+
+    it("throws an error for missing locale", () => {
+      expect(() => {
+        buildMagicPreviewAddress(
+          { resourceType: "page", slug: "dada" },
+          config,
+        );
+      }).toThrow(
+        "Can't generate a token without a slug, resourceType or locale!",
+      );
+    });
+  });
+
+  describe("generateMagicPreviewToken & decipherMagicPreviewToken", () => {
+    it("generates an encrypted token and deciphers it back", () => {
+      const token = generateMagicPreviewToken(
+        {
+          slug: "my-first-ebook",
+          resourceType: "ebook",
+          locale: "en",
+        },
+        config,
+      );
+
+      expect(typeof token).toBe("string");
+      expect(token).not.toContain("my-first-ebook");
+
+      const payload = decipherMagicPreviewToken(token, config);
+      expect(payload).not.toBeNull();
+      expect(payload.slug).toBe("my-first-ebook");
+      expect(payload.resourceType).toBe("ebook");
+      expect(payload.locale).toBe("en");
+    });
+
+    it("returns null on invalid / tampered token", () => {
+      expect(decipherMagicPreviewToken("", config)).toBeNull();
+      expect(decipherMagicPreviewToken(null, config)).toBeNull();
+      expect(decipherMagicPreviewToken("invalid-token", config)).toBeNull();
+
+      const token = generateMagicPreviewToken(
+        { slug: "secure", resourceType: "page", locale: "en" },
+        config,
+      );
+      const tampered = `${token.slice(0, -4)}XXXX`;
+      expect(decipherMagicPreviewToken(tampered, config)).toBeNull();
+    });
+  });
+});

package/src/tests/setupAuthentication.test.js

@@ -50,6 +50,7 @@ function makeCtx(overrides = {}) {
       path: "/en/pages",
       url: "https://example.com/en/pages",
       query: jest.fn().mockReturnValue({}),
+      param: jest.fn().mockReturnValue(""),
       json: jest.fn().mockResolvedValue({}),
       ...overrides.req,
     },
@@ -72,6 +73,10 @@ const config = {
     remoteLogin: "https://remote/login",
     remoteLogout: "https://remote/logout",
   },
+  secrets: {
+    crypto_secret:
+      "cafeb74e0fc1079d384f68620dc0b0919c82bd36351a74fb48f3c96562c1bf672ff5fd4db42180bc9550d06f3621edba5305a443a232337e2945d7bb1271cafe",
+  },
 };
 
 describe("setupAuthentication", () => {
@@ -96,6 +101,10 @@ describe("setupAuthentication", () => {
       "/remote/verify",
       expect.any(Function),
     );
+    expect(app.get).toHaveBeenCalledWith(
+      "/remote/magic-preview/:token",
+      expect.any(Function),
+    );
   });
 
   describe("use middleware", () => {
@@ -407,4 +416,50 @@ describe("setupAuthentication", () => {
       expect(result.status).toBe(401);
     });
   });
+
+  describe("/remote/magic-preview/:token", () => {
+    test("returns the token payload for a valid token", async () => {
+      const app = makeApp();
+      setupAuthentication(app, config);
+
+      const { generateMagicPreviewToken } = require("../magicPreview");
+      const token = generateMagicPreviewToken(
+        { slug: "article-slug", resourceType: "article", locale: "es" },
+        config,
+      );
+
+      const ctx = makeCtx({
+        req: {
+          param: jest.fn().mockReturnValue(token),
+        },
+      });
+
+      await app.handlers["GET /remote/magic-preview/:token"](ctx);
+
+      expect(ctx.json).toHaveBeenCalledWith({
+        slug: "article-slug",
+        resourceType: "article",
+        locale: "es",
+      });
+    });
+
+    test("returns 404 for invalid token", async () => {
+      const app = makeApp();
+
+      setupAuthentication(app, config);
+
+      const ctx = makeCtx({
+        req: {
+          param: jest.fn().mockReturnValue("bad-token"),
+        },
+      });
+
+      await app.handlers["GET /remote/magic-preview/:token"](ctx);
+
+      expect(ctx.json).toHaveBeenCalledWith(
+        { error: "Invalid or expired preview token" },
+        404,
+      );
+    });
+  });
 });