Wix Headless Replatform

scripts/generate-invoice-download-backend.mjs

#!/usr/bin/env node
import { createRequire } from "node:module";
import path from "node:path";
import { parseArgs, readJson, resolveOutputDir, writeJson, writeText } from "./lib/common.mjs";

// Generates the server-side backend that hands a member their preserved invoice document: a pure
// handler, the Wix adapters that give it real data, and the route that wires them together.
//
// This is the one place the invoice feature can leak BETWEEN customers, so the shape is not
// negotiable: the handler accepts an ORDER id and nothing else, checks that the calling member
// can read that order, and resolves the private file id server-side. If it accepted a file id
// from the client, any member could ask for another member's tax invoice by guessing or
// harvesting one — and an invoice carries a name, an address and a purchase history.
//
// The preserved document is a PRIVATE Media file, so it is not reachable by URL without a
// generated download link. That link is minted per request with an explicit short expiry: the
// API's own default is 600 minutes, which is not short-lived for a tax document.
//
// The field names are read from the migration's own contract at GENERATION time rather than
// written out here. Two copies of a field name is exactly the drift the contract adapter exists
// to prevent, and this generator is the third consumer of it.
const require = createRequire(import.meta.url);
const invoiceContract = require("../../wix-replatform/resources/rp-target-wix/lib/order-invoice-contract.js");

// The scaffold ships @wix/sdk, @wix/astro and @wix/essentials, and nothing else. Without these
// the generated route imports modules that are not installed and the build fails — which is
// better than the previous behaviour, where it built fine and answered 401 forever.
export const REQUIRED_DEPENDENCIES = Object.freeze({
  "@wix/ecom": "^1.0.0",
  "@wix/media": "^1.0.0",
  "@wix/members": "^1.0.0",
  "@wix/essentials": "^1.0.6",
});

function handlerSource({ fileIdField, numberField, contractVersion }) {
  return `// GENERATED by generate-invoice-download-backend.mjs — do not edit by hand.
// Field names generated from order-invoice contract ${contractVersion}.
//
// Hands a signed-in member a short-lived download link for the invoice document preserved on one
// of THEIR orders.
//
// The security contract, in order:
//   1. A client-supplied file id is REJECTED outright. The client names an order; the server
//      resolves the file. Accepting a file id would let any member fetch any member's invoice.
//   2. The member must be authenticated.
//   3. The order must be readable BY THAT MEMBER. Order scoping is the authorization boundary.
//   4. The file id is read from the order's own extended fields, server-side.
//   5. The download URL is minted with an explicit short expiry and is never logged.

export const INVOICE_FILE_FIELD = ${JSON.stringify(fileIdField)};
export const INVOICE_NUMBER_FIELD = ${JSON.stringify(numberField)};
export const DOWNLOAD_EXPIRY_MINUTES = 10;

export function createInvoiceDownloadHandler({ getMemberId, getOrderForMember, generateDownloadUrl }) {
  if (typeof getMemberId !== "function") throw new Error("getMemberId is required");
  if (typeof getOrderForMember !== "function") throw new Error("getOrderForMember is required");
  if (typeof generateDownloadUrl !== "function") throw new Error("generateDownloadUrl is required");

  return async function handleInvoiceDownload(request = {}) {
    try {
      return await respond(request);
    } catch (error) {
      // A dependency being down is not a refusal. Reported without detail — the member learns
      // nothing about the order either way — but with a status a client may retry and monitoring
      // can tell apart from a denial.
      if (error && error.transient === true) return { status: 503, error: "service-temporarily-unavailable" };
      throw error;
    }
  };

  async function respond(request) {
    const body = request.body && typeof request.body === "object" ? request.body : {};

    // 1. The client may not name a file. Any attempt is refused rather than ignored, so a
    //    misbuilt caller fails loudly instead of silently working for the wrong reason.
    for (const forbidden of ["fileId", "file_id", "fileID", "mediaId", "media_id"]) {
      if (Object.prototype.hasOwnProperty.call(body, forbidden)) {
        return { status: 400, error: "client-supplied-file-id-rejected" };
      }
    }

    const orderId = typeof body.orderId === "string" ? body.orderId.trim() : "";
    if (!orderId) return { status: 400, error: "order-id-required" };

    // 2. Authentication.
    const memberId = await getMemberId(request);
    if (!memberId) return { status: 401, error: "authentication-required" };

    // 3. Authorization is the order read: if this member cannot read this order, there is nothing
    //    to talk about. Never fall back to an unscoped order read.
    const order = await getOrderForMember({ orderId, memberId });
    if (!order) return { status: 403, error: "order-not-readable-by-member" };

    // 4. Resolve the file server-side.
    const namespaces = (order.extendedFields && order.extendedFields.namespaces) || {};
    const fields = namespaces._user_fields || {};
    const fileId = typeof fields[INVOICE_FILE_FIELD] === "string" ? fields[INVOICE_FILE_FIELD].trim() : "";
    if (!fileId) return { status: 404, error: "no-preserved-invoice-for-order" };

    // 5. Mint a short-lived link. The URL is returned to the caller and never logged.
    const url = await generateDownloadUrl({ fileId, expirationInMinutes: DOWNLOAD_EXPIRY_MINUTES });
    if (!url) return { status: 502, error: "download-url-unavailable" };

    return {
      status: 200,
      url,
      expiresInMinutes: DOWNLOAD_EXPIRY_MINUTES,
      // The invoice number is the merchant's own reference and is safe to show. The file id is
      // internal and is deliberately not echoed.
      invoiceNumber: typeof fields[INVOICE_NUMBER_FIELD] === "string" ? fields[INVOICE_NUMBER_FIELD] : null,
    };
  }
}
`;
}

// The authorization logic, with no Wix import in it. Split out from the adapters deliberately:
// a module that statically imports @wix/ecom cannot be loaded by a test without the whole SDK
// installed, and "we could not test it" is how the previous version of this backend shipped a
// seam that answered 401 to everything. What is left in the adapters file is wiring with no
// branches in it.
const AUTHORIZATION_SOURCE = `// GENERATED by generate-invoice-download-backend.mjs — do not edit by hand.
//
// Who may download which invoice. No Wix imports here on purpose, so this file can be run and
// tested on its own; the adapters supply the four functions that talk to Wix.
//
// Two facts shape it, both from the API docs rather than assumed:
//
//   1. Get Order called with a MEMBER's identity returns the order only if that member placed it.
//      That check is Wix's, not ours, and it is the authorization boundary.
//   2. The migration's invoice fields are declared readable by \`apps\` and \`users\` — deliberately
//      NOT by \`users-of-users\`, because they are merchant data. So the member-identity read that
//      proves ownership does NOT return the field values, and a second, elevated read is needed
//      to get them.
//
// So ownership is established by the unelevated read, and only then is anything elevated. The
// rule is then checked a SECOND time, by us, against the elevated order's buyerInfo.
//
// Be precise about what that second check is worth. It is a second IMPLEMENTATION, not a second
// source of evidence: both it and Wix's check rest on the same stored \`buyerInfo.memberId\`. It
// catches an elevated read that answers about the wrong order, or a change in what elevation
// returns. It does NOT catch an order attributed to the wrong member in the first place -- if the
// import writes Alice's order with Bob's memberId, both checks agree and Bob gets Alice's
// invoice. Correct \`buyerInfo.memberId\` on imported orders is a PREREQUISITE of this feature,
// not something it can verify. An order carrying no memberId fails closed.

// The SDK renames \`id\` to \`_id\`. Read both rather than pick one and be wrong on a version bump.
export function orderIdOf(order) {
  if (!order || typeof order !== "object") return null;
  const value = order._id ?? order.id;
  return typeof value === "string" && value.length > 0 ? value : null;
}

// Not every failure is a refusal. Collapsing them told a member "you are not allowed" during a
// Wix outage, and left monitoring unable to tell a denial from a dependency being down.
//
// The Wix SDK throws \`SDKError\` carrying \`response.status\`. A 401, 403 or 404 is a real answer
// to the question asked, and becomes \`null\` — indistinguishable, on purpose, so a prober cannot
// learn from the difference between "not yours" and "does not exist". Anything else, including a
// 5xx and a network error with no status at all, is us failing rather than the caller being
// refused, and is raised so the route can say so.
const DENIAL_STATUSES = new Set([401, 403, 404]);

export class InvoiceBackendUnavailable extends Error {
  constructor(status) {
    super(\`the invoice backend could not reach Wix (status \${status ?? "unknown"})\`);
    this.name = "InvoiceBackendUnavailable";
    this.transient = true;
    this.status = status ?? null;
  }
}

async function orNull(operation) {
  try {
    return (await operation()) ?? null;
  } catch (error) {
    const status = error && error.response && error.response.status;
    if (DENIAL_STATUSES.has(status)) return null;
    throw new InvoiceBackendUnavailable(status);
  }
}

export function createInvoiceAdapters({
  getCurrentMember,
  getOrderAsCaller,
  getOrderElevated,
  generateDownloadUrlElevated,
}) {
  for (const [name, fn] of Object.entries({ getCurrentMember, getOrderAsCaller, getOrderElevated, generateDownloadUrlElevated })) {
    if (typeof fn !== "function") throw new Error(\`\${name} is required\`);
  }

  return {
    async getMemberId() {
      // \`getCurrentMember()\` resolves to \`{ member }\`, NOT to the member. The docs example shows
      // a bare member object and is wrong; the published type is
      // \`Promise<GetMyMemberResponse>\` with \`member?: Member\`. Reading \`_id\` off the response
      // made every signed-in member resolve as anonymous, so the route answered 401 to everyone
      // — the same failure as the \`locals\` seam it replaced, one layer in.
      //
      // Both shapes are accepted: the wrapper is what ships, the bare member is what the docs
      // promise, and being wrong about which one arrives must not lock members out again.
      const response = await orNull(getCurrentMember);
      const member = (response && response.member) || response;
      const id = member && (member._id ?? member.id);
      return typeof id === "string" && id.length > 0 ? id : null;
    },

    async getOrderForMember({ orderId, memberId }) {
      if (typeof orderId !== "string" || orderId.length === 0) return null;
      if (typeof memberId !== "string" || memberId.length === 0) return null;

      // 1. Wix's check. Nothing is elevated until this passes.
      const asCaller = await orNull(() => getOrderAsCaller(orderId));
      if (!asCaller || orderIdOf(asCaller) !== orderId) return null;

      // 2. Our own read, elevated, because the fields are not member-readable.
      const elevated = await orNull(() => getOrderElevated(orderId));
      if (!elevated || orderIdOf(elevated) !== orderId) return null;

      // 3. Our check, independent of Wix's. An order whose buyer is not this member is not this
      //    member's order, and an order with no member buyer at all belongs to nobody who can ask
      //    for it here. Email is never accepted as proof: it is changeable and guessable.
      const buyerMemberId = elevated.buyerInfo && elevated.buyerInfo.memberId;
      if (typeof buyerMemberId !== "string" || buyerMemberId !== memberId) return null;

      return elevated;
    },

    async generateDownloadUrl({ fileId, expirationInMinutes }) {
      if (typeof fileId !== "string" || fileId.length === 0) return null;
      const result = await orNull(() => generateDownloadUrlElevated(fileId, { expirationInMinutes }));
      const first = result && Array.isArray(result.downloadUrls) ? result.downloadUrls[0] : null;
      const url = first && first.url;
      return typeof url === "string" && url.length > 0 ? url : null;
    },
  };
}
`;

const ADAPTERS_SOURCE = `// GENERATED by generate-invoice-download-backend.mjs — do not edit by hand.
//
// Wiring only. Every decision lives in invoice-download-authorization.mjs; this file exists to
// name the four Wix calls, and there is deliberately no logic in it to get wrong.
import { members } from "@wix/members";
import { orders } from "@wix/ecom";
import { files } from "@wix/media";
import { auth } from "@wix/essentials";
import { createInvoiceAdapters } from "./invoice-download-authorization.mjs";

export const wixInvoiceAdapters = createInvoiceAdapters({
  getCurrentMember: () => members.getCurrentMember(),
  // Unelevated ON PURPOSE. This call running as the caller is the whole authorization mechanism.
  getOrderAsCaller: (id) => orders.getOrder(id),
  getOrderElevated: (id) => auth.elevate(orders.getOrder)(id),
  generateDownloadUrlElevated: (fileId, options) => auth.elevate(files.generateFileDownloadUrl)(fileId, options),
});
`;

const ROUTE_SOURCE = `// GENERATED by generate-invoice-download-backend.mjs — do not edit by hand.
//
// Thin transport wrapper. All authorization lives in the handler and the adapters; this file only
// moves JSON.
import { createInvoiceDownloadHandler } from "../../lib/invoice-download.mjs";
import { wixInvoiceAdapters } from "../../lib/invoice-download-adapters.mjs";

const handler = createInvoiceDownloadHandler(wixInvoiceAdapters);

export async function POST({ request }) {
  let body = {};
  try {
    body = await request.json();
  } catch {
    return new Response(JSON.stringify({ error: "invalid-json" }), { status: 400, headers: { "content-type": "application/json" } });
  }

  const result = await handler({ body });
  const { status, ...payload } = result;
  return new Response(JSON.stringify(payload), { status, headers: { "content-type": "application/json" } });
}
`;

export function buildHandlerSource() {
  return handlerSource({
    fileIdField: invoiceContract.ROLES.fileId,
    numberField: invoiceContract.ROLES.number,
    contractVersion: invoiceContract.version(),
  });
}

// Adds what the generated route imports. Merges rather than overwrites: the scaffold owns its own
// versions, and a project that already pins one of these keeps its pin.
export async function ensureInvoiceDependencies({ outputDir }) {
  const packagePath = path.join(outputDir, "package.json");
  let manifest;
  try {
    manifest = await readJson(packagePath);
  } catch {
    return { packagePath, added: [], skipped: "no package.json at the output dir" };
  }
  const dependencies = manifest.dependencies || {};
  const added = [];
  for (const [name, version] of Object.entries(REQUIRED_DEPENDENCIES)) {
    if (!dependencies[name]) {
      dependencies[name] = version;
      added.push(name);
    }
  }
  if (added.length === 0) return { packagePath, added };
  manifest.dependencies = dependencies;
  await writeJson(packagePath, manifest);
  return { packagePath, added };
}

export async function generateInvoiceDownloadBackend({ outputDir }) {
  const handlerPath = path.join(outputDir, "src", "lib", "invoice-download.mjs");
  const authorizationPath = path.join(outputDir, "src", "lib", "invoice-download-authorization.mjs");
  const adaptersPath = path.join(outputDir, "src", "lib", "invoice-download-adapters.mjs");
  const routePath = path.join(outputDir, "src", "pages", "api", "invoice-download.mjs");
  await writeText(handlerPath, HANDLER_SOURCE);
  await writeText(authorizationPath, AUTHORIZATION_SOURCE);
  await writeText(adaptersPath, ADAPTERS_SOURCE);
  await writeText(routePath, ROUTE_SOURCE);
  const dependencies = await ensureInvoiceDependencies({ outputDir });
  return { handlerPath, authorizationPath, adaptersPath, routePath, dependencies };
}

async function main() {
  const args = parseArgs();
  const outputDir = resolveOutputDir(args._[0] || args.url, args.out);
  const written = await generateInvoiceDownloadBackend({ outputDir });
  if (args.json) process.stdout.write(`${JSON.stringify(written, null, 2)}\n`);
}

// Computed once so consumers -- the tests included -- read exactly the bytes that get written.
export const HANDLER_SOURCE = buildHandlerSource();

export { AUTHORIZATION_SOURCE, ADAPTERS_SOURCE, ROUTE_SOURCE };

if (import.meta.url === `file://${process.argv[1]}`) {
  await main();
}