Subchapter 15.31

Generate Invoice Download Backend

Workflow

Scripts

scripts/37 files

scripts/lib/18 files

28 more in the appendix

async function main

This file

Number: 15.31
Position: 31 of 93
Type: JavaScript
Size: 17 KB
Lines: 342

Nearby

Source

scripts/generate-invoice-download-backend.mjs

JavaScript342 lines17 KB

1#!/usr/bin/env node
2import { createRequire } from "node:module";
3import path from "node:path";
4import { parseArgs, readJson, resolveOutputDir, writeJson, writeText } from "./lib/common.mjs";
5
6// Generates the server-side backend that hands a member their preserved invoice document: a pure
7// handler, the Wix adapters that give it real data, and the route that wires them together.
8//
9// This is the one place the invoice feature can leak BETWEEN customers, so the shape is not
10// negotiable: the handler accepts an ORDER id and nothing else, checks that the calling member
11

generate-invoice-download-backend.mjs on GitHub

// 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();

}