ghost 6.60.0 → 6.61.0

package/core/server/services/tier-checkout-config/service.js

@@ -0,0 +1,303 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TierCheckoutConfigService = void 0;
+const bson_objectid_1 = __importDefault(require("bson-objectid"));
+const errors_1 = __importDefault(require("@tryghost/errors"));
+const zod_1 = require("zod");
+const schema_1 = require("../members-custom-fields/schema");
+const field_ports_1 = require("../stripe/services/checkout/field-ports");
+const codec_1 = require("./codec");
+const queries_1 = require("./queries");
+const models_1 = require("./models");
+const destinations_1 = require("./destinations");
+const serializers_1 = require("./serializers");
+/**
+ * A request states its settings in named sections: one for shipping, one for phone. Each
+ * section stands for one or more of the values Stripe hands back when a checkout is
+ * completed — shipping covers both the recipient's name and their address, phone covers
+ * only the phone number.
+ *
+ * Naming those values here means that a request which includes a section settles every
+ * value in it: each one is either given a destination or has its old one removed. Without
+ * this list, a value the request never mentioned could keep a destination from an earlier
+ * save that the publisher believes they have turned off.
+ */
+const BLOCK_PORTS = {
+    shipping: [field_ports_1.STRIPE_PORT.shippingName, field_ports_1.STRIPE_PORT.shippingAddress],
+    phone: [field_ports_1.STRIPE_PORT.phone],
+};
+class TierCheckoutConfigService {
+    knex;
+    bindings;
+    fields;
+    constructor({ knex, bindings, fields, }) {
+        this.knex = knex;
+        this.bindings = bindings;
+        this.fields = fields;
+    }
+    async browse() {
+        const rows = decodeCollection(await (0, queries_1.configuredCollectionRows)(this.knex));
+        if (rows.length === 0) {
+            return [];
+        }
+        const asked = await this.questions();
+        return rows.map((row) => assemble(row, asked.get(row.tierId) ?? []));
+    }
+    async read(productId) {
+        const [row] = decodeCollection(await (0, queries_1.collectionRowsForTier)(this.knex, productId));
+        if (!row) {
+            throw new errors_1.default.NotFoundError({ message: 'Tier not found.' });
+        }
+        if (!row.configured) {
+            return null;
+        }
+        const asked = await this.questions(productId);
+        return assemble(row, asked.get(productId) ?? []);
+    }
+    async resolve(productId) {
+        const [row] = decodeCollection(await (0, queries_1.collectionRowsForTier)(this.knex, productId));
+        if (!row?.configured) {
+            return { customFields: [], ...(0, models_1.emptyCollection)() };
+        }
+        const asked = await this.questions(productId);
+        const customFields = (asked.get(productId) ?? []).flatMap((entry) => entry.askable ? [{ ...entry.question, ...entry.askable }] : []);
+        return { customFields, ...row.collecting };
+    }
+    /**
+     * Saves the checkout settings a request states, and leaves the rest alone.
+     *
+     * A request only has to include the sections it wants to change. Say nothing about
+     * shipping and the shipping settings stay exactly as they were, so a client that only
+     * knows how to edit the questions cannot wipe out the shipping settings by omitting
+     * them.
+     */
+    async edit(context, productId, input) {
+        const stated = parseInput(input);
+        const now = new Date();
+        if (stated.custom_fields) {
+            await assertQuestionsAskable(this.knex, stated.custom_fields);
+        }
+        const plan = await this.planCollection(stated);
+        const created = await this.knex.transaction(async (trx) => {
+            await assertTierExists(trx, productId);
+            await writeOptions(trx, productId, stated, now);
+            for (const port of plan.clear) {
+                await this.bindings.remove(trx, productId, port);
+            }
+            const made = [];
+            for (const wanted of plan.create) {
+                made.push(await this.fields.addOne(wanted, { executor: trx }));
+            }
+            for (const { port, key } of plan.bind) {
+                await this.bindings.bind(trx, productId, port, key, now);
+            }
+            if (stated.custom_fields) {
+                await this.writeQuestions(trx, productId, stated.custom_fields, now);
+            }
+            return made;
+        });
+        await this.fields.recordCreated(context, created);
+    }
+    async questions(productId) {
+        const rows = await (0, queries_1.questionRows)(this.knex, productId);
+        const byTier = new Map();
+        for (const row of rows) {
+            const parts = zod_1.z.decode(codec_1.questionRowCodec, row);
+            const forTier = byTier.get(parts.tierId) ?? [];
+            forTier.push(parts);
+            byTier.set(parts.tierId, forTier);
+        }
+        return byTier;
+    }
+    async planCollection(stated) {
+        const wanted = [];
+        if (stated.shipping?.collect) {
+            wanted.push({ port: field_ports_1.STRIPE_PORT.shippingName, key: stated.shipping.name.custom_field_key }, { port: field_ports_1.STRIPE_PORT.shippingAddress, key: stated.shipping.address.custom_field_key });
+        }
+        if (stated.phone?.collect) {
+            wanted.push({ port: field_ports_1.STRIPE_PORT.phone, key: stated.phone.custom_field_key });
+        }
+        const bound = new Set(wanted.map(({ port }) => port));
+        const clear = [];
+        for (const block of ['shipping', 'phone']) {
+            if (stated[block]) {
+                clear.push(...BLOCK_PORTS[block].filter((port) => !bound.has(port)));
+            }
+        }
+        const create = new Map();
+        for (const { port, key } of wanted) {
+            const wants = destinations_1.PORT_FIELD[port];
+            const existing = await this.fields.findByKey(key);
+            if (existing) {
+                assertCollectableInto(port, existing, wants.type);
+                continue;
+            }
+            const alreadyPlanned = create.get(key);
+            if (alreadyPlanned && alreadyPlanned.type !== wants.type) {
+                throw new errors_1.default.ValidationError({
+                    message: `This can only be collected into a ${wants.type} field.`,
+                    property: `checkout.${port}.custom_field_key`,
+                });
+            }
+            if (!alreadyPlanned) {
+                create.set(key, { key, name: wants.name, type: wants.type });
+            }
+        }
+        return { clear, create: [...create.values()], bind: wanted };
+    }
+    /**
+     * Saves the questions this tier asks its buyers during checkout.
+     *
+     * A binding records that one value coming back from Stripe belongs in one custom field,
+     * and it identifies the value by the name Stripe uses for it. For a question that name
+     * is the custom field's own key: Ghost sends the key to Stripe as the question's
+     * identifier, and Stripe returns the buyer's answer labelled with that same key. That is
+     * why the key is passed twice below — once as the name Stripe will answer under, and
+     * once as the field the answer is stored in.
+     */
+    async writeQuestions(trx, productId, questions, now) {
+        const asked = new Set(questions.map((question) => question.key));
+        const alreadyAsked = await trx(queries_1.QUESTIONS_TABLE)
+            .join(queries_1.BINDINGS_TABLE, `${queries_1.BINDINGS_TABLE}.id`, `${queries_1.QUESTIONS_TABLE}.binding_id`)
+            .where(`${queries_1.BINDINGS_TABLE}.product_id`, productId)
+            .select(`${queries_1.BINDINGS_TABLE}.port`);
+        for (const { port } of alreadyAsked) {
+            if (!asked.has(port)) {
+                await this.bindings.remove(trx, productId, port);
+            }
+        }
+        for (const [index, question] of questions.entries()) {
+            const bindingId = await this.bindings.bind(trx, productId, question.key, question.key, now);
+            await trx(queries_1.QUESTIONS_TABLE).where('binding_id', bindingId).del();
+            await trx(queries_1.QUESTIONS_TABLE).insert({
+                id: new bson_objectid_1.default().toHexString(),
+                binding_id: bindingId,
+                sort_order: index,
+                label: question.label ?? null,
+                optional: question.optional ?? true,
+                created_at: now,
+            });
+        }
+    }
+}
+exports.TierCheckoutConfigService = TierCheckoutConfigService;
+function parseInput(input) {
+    const parsed = serializers_1.CheckoutConfigInput.safeParse(input);
+    if (parsed.success) {
+        return parsed.data;
+    }
+    const issue = parsed.error.issues[0];
+    throw new errors_1.default.ValidationError({
+        message: issue.message,
+        property: issue.path.join('.') || 'checkout',
+    });
+}
+function decodeCollection(rows) {
+    return rows.map((row) => zod_1.z.decode(codec_1.collectionRowCodec, row));
+}
+function assemble(row, asked) {
+    return {
+        tierId: row.tierId,
+        customFields: asked.map((entry) => entry.question),
+        ...row.collection,
+    };
+}
+async function assertTierExists(db, productId) {
+    const tier = await db('products').where('id', productId).first();
+    if (!tier) {
+        throw new errors_1.default.NotFoundError({ message: 'Tier not found.' });
+    }
+}
+/**
+ * Refuses a custom field that cannot hold what Stripe will send back.
+ *
+ * A request names the custom field each collected value should be saved into. That field
+ * has to be active, because an archived field accepts no new values, and it has to store
+ * the right kind of data: Stripe returns a structured address for the shipping address,
+ * and plain text for a name or a phone number.
+ *
+ * Both refusals are deliberate rather than defensive. Ghost could save the value into some
+ * other field, or accept the request and quietly collect nothing, but a publisher who named
+ * a field meant that field. Being told now is better than finding out weeks later that
+ * nothing was ever recorded.
+ */
+function assertCollectableInto(port, field, valueType) {
+    if (field.status !== schema_1.FIELD_STATUS.active) {
+        throw new errors_1.default.ValidationError({
+            message: 'An archived custom field cannot receive collected data. Restore it first.',
+            property: `checkout.${port}.custom_field_key`,
+        });
+    }
+    if (field.type !== valueType) {
+        throw new errors_1.default.ValidationError({
+            message: `This can only be collected into a ${valueType} field.`,
+            property: `checkout.${port}.custom_field_key`,
+        });
+    }
+}
+async function writeOptions(trx, productId, stated, now) {
+    const all = zod_1.z.encode(codec_1.optionsCodec, {
+        shippingAllowedCountries: stated.shipping?.collect ? stated.shipping.allowed_countries : [],
+        taxNumber: stated.tax_number?.collect ?? false,
+    });
+    // Only the columns this request spoke about are written, so two requests changing
+    // different parts of the same tier cannot undo each other, and a request that mentions
+    // neither still leaves the row behind as the record that this tier has been set up.
+    const columns = {
+        ...(stated.shipping ? { shipping_allowed_countries: all.shipping_allowed_countries } : {}),
+        ...(stated.tax_number ? { tax_number_collect: all.tax_number_collect } : {}),
+    };
+    await trx(queries_1.CONFIG_TABLE)
+        .insert({
+        id: new bson_objectid_1.default().toHexString(),
+        product_id: productId,
+        created_at: now,
+        updated_at: now,
+        ...columns,
+    })
+        .onConflict('product_id')
+        .merge({ ...columns, updated_at: now });
+}
+async function assertQuestionsAskable(db, questions) {
+    const collides = questions.find((question) => (0, field_ports_1.isStripePort)(question.key));
+    if (collides) {
+        throw new errors_1.default.ValidationError({
+            message: `A field keyed ${collides.key} cannot be asked at checkout, because that is what this checkout calls something it collects for itself.`,
+            property: 'checkout.custom_fields',
+        });
+    }
+    const keys = questions.map((question) => question.key);
+    if (keys.length === 0) {
+        return;
+    }
+    const rows = await db(queries_1.FIELDS_TABLE)
+        .whereIn(`${queries_1.FIELDS_TABLE}.key`, keys)
+        .where(`${queries_1.FIELDS_TABLE}.status`, schema_1.FIELD_STATUS.active)
+        .select(`${queries_1.FIELDS_TABLE}.key`, `${queries_1.FIELDS_TABLE}.name`, `${queries_1.FIELDS_TABLE}.type`, `${queries_1.FIELDS_TABLE}.status`);
+    const byKey = new Map(rows.map((row) => [row.key, row]));
+    for (const question of questions) {
+        const field = byKey.get(question.key);
+        if (!field) {
+            throw new errors_1.default.ValidationError({
+                message: `Unknown custom field: ${question.key}`,
+                property: 'checkout.custom_fields',
+            });
+        }
+        if (!(0, field_ports_1.isCheckoutEligible)(field.type)) {
+            throw new errors_1.default.ValidationError({
+                message: `A ${field.type} field cannot be asked for at checkout.`,
+                property: 'checkout.custom_fields',
+            });
+        }
+        const prompt = question.label ?? field.name;
+        if (prompt.length > field_ports_1.MAX_CHECKOUT_LABEL_LENGTH) {
+            throw new errors_1.default.ValidationError({
+                message: `A checkout question can be at most ${field_ports_1.MAX_CHECKOUT_LABEL_LENGTH} characters. Give this one a shorter label.`,
+                property: 'checkout.custom_fields',
+            });
+        }
+    }
+}

package/core/server/services/tiers/service.js

@@ -30,6 +30,27 @@ class TiersServiceWrapper {
       repository,
       slugService,
     });
+
+    // What a tier's checkout asks, kept beside the tier rather than inside it: these
+    // rows are read live on every request, because deleting a custom field cascades a
+    // question away without the repository above ever seeing it, and a cached copy
+    // would go on naming a field the site no longer has.
+    //
+    // Boot builds the custom fields services before this one, so both collaborators
+    // are ready by the time this runs.
+    const { TierCheckoutConfigService } = require('../tier-checkout-config');
+    const { bindings, definitions } = require('../members-custom-fields');
+    this.checkout = new TierCheckoutConfigService({
+      knex: models.Base.knex,
+      // A binding is where a collected value lands, and the same rows are what a completed
+      // checkout is routed through later. Handed over rather than reached for, so the
+      // checkout domain states what it needs of them and nothing more.
+      bindings,
+      // Turning a collection on has to leave it somewhere to land, and making a field is
+      // the definitions' to do. A separate collaborator because it is a separate act, and
+      // because deciding whether one is needed belongs to the checkout rather than to them.
+      fields: definitions,
+    });
   }
 }
 

package/core/server/web/api/endpoints/admin/routes.js

@@ -146,6 +146,25 @@ module.exports = function apiRoutes() {
   // Tiers
   router.get('/tiers', mw.authAdminApi, http(api.tiers.browse));
   router.post('/tiers', mw.authAdminApi, http(api.tiers.add));
+  // What a tier's checkout asks for, read when a Stripe checkout session is built.
+  // Registered before /tiers/:id so the literal path isn't captured by :id.
+  //
+  // A sub-resource rather than a key on the tier, because the tier payload is a public
+  // projection: `tiers-public` shares this docName's serializer, so anything on a tier is
+  // rendered by themes. This is admin-only configuration that no client renders, since
+  // the questions are drawn by Stripe's own checkout page rather than by Portal.
+  //
+  // Named for the configuration rather than the checkout, so it cannot be mistaken for
+  // the session that `create-stripe-checkout-session` creates from it.
+  router.get('/tiers/checkout_config', mw.authAdminApi, http(api.tiersCheckoutConfig.browse));
+  router.get('/tiers/:id/checkout_config', mw.authAdminApi, http(api.tiersCheckoutConfig.read));
+  router.put(
+    '/tiers/:id/checkout_config',
+    mw.authAdminApi,
+    labs.enabledMiddleware('membersCustomFields'),
+    http(api.tiersCheckoutConfig.edit),
+  );
+
   router.get('/tiers/:id', mw.authAdminApi, http(api.tiers.read));
   router.put('/tiers/:id', mw.authAdminApi, http(api.tiers.edit));
 
@@ -176,14 +195,11 @@ module.exports = function apiRoutes() {
 
   router.get('/members/stripe_connect', mw.authAdminApi, http(api.membersStripeConnect.auth));
 
-  // Member custom field definitions — gated by the members_custom_fields flag.
+  // Member custom field definitions. Reading them is open: a site that has never
+  // turned the flag on has none, so the answer is an empty list rather than a 404, and
+  // Admin can ask without first knowing whether it may. Changing them is gated.
   // Registered before /members/:id so the literal path isn't captured by :id.
-  router.get(
-    '/members/custom_fields',
-    mw.authAdminApi,
-    labs.enabledMiddleware('membersCustomFields'),
-    http(api.membersCustomFields.browse),
-  );
+  router.get('/members/custom_fields', mw.authAdminApi, http(api.membersCustomFields.browse));
   router.post(
     '/members/custom_fields',
     mw.authAdminApi,
@@ -197,12 +213,7 @@ module.exports = function apiRoutes() {
     labs.enabledMiddleware('membersCustomFields'),
     http(api.membersCustomFields.reorder),
   );
-  router.get(
-    '/members/custom_fields/:key',
-    mw.authAdminApi,
-    labs.enabledMiddleware('membersCustomFields'),
-    http(api.membersCustomFields.read),
-  );
+  router.get('/members/custom_fields/:key', mw.authAdminApi, http(api.membersCustomFields.read));
   router.put(
     '/members/custom_fields/:key',
     mw.authAdminApi,

package/core/server/web/api/middleware/upload.js

@@ -37,8 +37,8 @@ const messages = {
     invalidFile: 'Please select a valid CSV file.',
   },
   posts: {
-    missingFile: 'Please select a posts CSV file.',
-    invalidFile: 'Please select a valid CSV file.',
+    missingFile: 'Please select a posts CSV or ZIP file.',
+    invalidFile: 'Please select a valid CSV or ZIP file.',
   },
   images: {
     missingFile: 'Please select an image.',

package/core/server/web/parent/app.js

@@ -12,6 +12,11 @@ module.exports = function setupParentApp() {
   const parentApp = express('parent');
 
   parentApp.use(mw.requestId);
+
+  if (config.get('queryParameterFiltering:enabled')) {
+    parentApp.use(mw.filterQueryParameters);
+  }
+
   parentApp.use(mw.logRequest);
 
   // Register event emitter on req/res to trigger cache invalidation webhook event

package/core/server/web/parent/middleware/filter-query-parameters.js

@@ -0,0 +1,94 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.filterQueryParameters = filterQueryParameters;
+const logging_1 = __importDefault(require("@tryghost/logging"));
+const query_parameter_policy_1 = require("../../query-parameter-policy");
+const allowedQueryParameters = new Set(query_parameter_policy_1.queryParameterPolicy.public.map((entry) => entry.name));
+const allowedContentApiQueryParameters = new Set(query_parameter_policy_1.queryParameterPolicy.contentApi.map((entry) => entry.name));
+const CONTENT_API_PATH_PATTERN = /\/ghost\/api\/(?:(?:v[0-9]+|canary)\/content|content)(?:\/|$)/;
+const EXEMPT_PATH_PATTERNS = [
+    /\/ghost\/api(?:\/|$)/,
+    /\/\.ghost(?:\/|$)/,
+    /\/\.well-known(?:\/|$)/,
+    /\/socket\.io(?:\/|$)/,
+];
+const MAX_LOGGED_PARAMETERS = 10;
+const REQUEST_URL_BASE = 'http://ignored.example';
+const replaceQueryString = (requestTarget, filteredRequestTarget) => {
+    const requestUrl = new URL(requestTarget, REQUEST_URL_BASE);
+    const filteredUrl = new URL(filteredRequestTarget, REQUEST_URL_BASE);
+    return `${requestUrl.pathname}${filteredUrl.search}`;
+};
+const replaceParsedQuery = (query, requestTarget) => {
+    for (const parameter of Object.keys(query)) {
+        delete query[parameter];
+    }
+    const { searchParams } = new URL(requestTarget, REQUEST_URL_BASE);
+    for (const parameter of new Set(searchParams.keys())) {
+        const values = searchParams.getAll(parameter);
+        query[parameter] = values.length === 1 ? values[0] : values;
+    }
+};
+const removeUnknownParameters = (searchParams, allowlist) => {
+    const removed = new Set();
+    for (const parameter of [...searchParams.keys()]) {
+        if (!allowlist.has(parameter)) {
+            searchParams.delete(parameter);
+            removed.add(parameter);
+        }
+    }
+    return removed;
+};
+const filterRequestTarget = (requestTarget) => {
+    const { pathname, searchParams } = new URL(requestTarget, REQUEST_URL_BASE);
+    const contentApiRequest = CONTENT_API_PATH_PATTERN.test(pathname);
+    const exemptPath = EXEMPT_PATH_PATTERNS.some((pattern) => pattern.test(pathname));
+    if (!contentApiRequest && exemptPath) {
+        return {
+            requestTarget,
+            removedUnknownParameters: [],
+        };
+    }
+    const allowlist = contentApiRequest ? allowedContentApiQueryParameters : allowedQueryParameters;
+    const removedUnknownParameters = removeUnknownParameters(searchParams, allowlist);
+    if (removedUnknownParameters.size === 0) {
+        return {
+            requestTarget,
+            removedUnknownParameters: [],
+        };
+    }
+    const query = searchParams.toString();
+    return {
+        requestTarget: query ? `${pathname}?${query}` : pathname,
+        removedUnknownParameters: [...removedUnknownParameters].sort(),
+    };
+};
+/**
+ * Applies Ghost(Pro)'s public query parameter allowlist in local development.
+ *
+ * Update the production policy and this manifest together when adding a parameter.
+ * This middleware is enabled by the root pnpm dev Docker Compose configuration.
+ */
+function filterQueryParameters(req, _res, next) {
+    const requestTarget = req.originalUrl;
+    const result = filterRequestTarget(requestTarget);
+    if (result.requestTarget !== requestTarget) {
+        const query = req.query;
+        req.originalUrl = result.requestTarget;
+        req.url = replaceQueryString(req.url, result.requestTarget);
+        replaceParsedQuery(query, result.requestTarget);
+    }
+    if (result.removedUnknownParameters.length > 0) {
+        const strippedParameters = result.removedUnknownParameters
+            .slice(0, MAX_LOGGED_PARAMETERS)
+            .map(encodeURIComponent)
+            .join(', ');
+        const omittedParameterCount = result.removedUnknownParameters.length - MAX_LOGGED_PARAMETERS;
+        const omittedParameters = omittedParameterCount > 0 ? `, and ${omittedParameterCount} more` : '';
+        logging_1.default.warn(`[query-parameter-filter] Stripped undeclared query parameter(s) from ${req.path}: ${strippedParameters}${omittedParameters}`);
+    }
+    next();
+}

package/core/server/web/parent/middleware/index.js

@@ -1,5 +1,6 @@
 module.exports = {
   emitEvents: require('./emit-events'),
+  filterQueryParameters: require('./filter-query-parameters').filterQueryParameters,
   ghostLocals: require('./ghost-locals').ghostLocals,
   logRequest: require('./log-request'),
   queueRequest: require('./queue-request'),

package/core/server/web/query-parameter-policy/index.js

@@ -0,0 +1,9 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.queryParameterPolicy = void 0;
+const policy_json_1 = __importDefault(require("./policy.json"));
+const schema_1 = require("./schema");
+exports.queryParameterPolicy = (0, schema_1.parseQueryParameterPolicy)(policy_json_1.default);

package/core/server/web/query-parameter-policy/policy.json

@@ -0,0 +1,58 @@
+{
+  "schemaVersion": 1,
+  "public": [
+    { "name": "m", "reason": "Link tracking" },
+    { "name": "v", "reason": "Asset invalidation" },
+    { "name": "r", "reason": "Password-protected site redirects" },
+    { "name": "token", "reason": "Members API authentication" },
+    { "name": "action", "reason": "Unsubscribe links" },
+    { "name": "ssml", "reason": "Ghost SSO" },
+    { "name": "ssts", "reason": "Ghost SSO" },
+    { "name": "uuid", "reason": "Member UUID used for unsubscribing" },
+    { "name": "key", "reason": "Members key used to sign unsubscribe paths" },
+    { "name": "portal-action", "reason": "Members Portal actions" },
+    { "name": "newsletter", "reason": "Multiple newsletters, including unsubscribe links" },
+    { "name": "comments", "reason": "Unsubscribing from comment notifications" },
+    { "name": "updatesandannouncements", "reason": "Unsubscribing from automations emails" },
+    { "name": "firstStart", "reason": "Opening the getting-started modal" },
+    { "name": "include", "reason": "Frontend comments API includes" },
+    { "name": "fields", "reason": "Frontend comments API field selection" },
+    { "name": "limit", "reason": "Frontend comments API pagination" },
+    { "name": "order", "reason": "Frontend comments API sorting" },
+    { "name": "filter", "reason": "Frontend comments API filtering" },
+    { "name": "page", "reason": "Frontend comments API pagination" },
+    { "name": "ids", "reason": "Frontend comments counts API" },
+    { "name": "via", "reason": "FirstPromoter referral tracking" },
+    { "name": "ref", "reason": "Attribution tracking" },
+    { "name": "source", "reason": "Attribution tracking" },
+    { "name": "utm_source", "reason": "Attribution tracking" },
+    { "name": "utm_medium", "reason": "Attribution tracking" },
+    { "name": "attribution_id", "reason": "Attribution tracking" },
+    { "name": "attribution_type", "reason": "Attribution tracking" },
+    { "name": "resource", "reason": "WebFinger resource lookup" },
+    { "name": "sr_id", "reason": "Signup redirect tracking" },
+    { "name": "member_status", "reason": "Testing card and paywall content visibility" },
+    {
+      "name": "member_tier",
+      "reason": "Previewing card and paywall visibility for a specific tier"
+    },
+    { "name": "otc_verification", "reason": "One-time codes in member sign-ins" },
+    { "name": "admin", "reason": "Admin toolbar activation" },
+    { "name": "admin_toolbar", "reason": "Admin toolbar suppression" },
+    { "name": "gift", "reason": "Gift-link unlock token on canonical post URLs" },
+    { "name": "step", "reason": "Automations analytics" }
+  ],
+  "contentApi": [
+    { "name": "absolute_urls", "reason": "Converts relative URLs to absolute URLs" },
+    { "name": "collection", "reason": "Filters resources by collection" },
+    { "name": "debug", "reason": "Enables debug mode where available" },
+    { "name": "fields", "reason": "Limits returned fields" },
+    { "name": "filter", "reason": "Filters resources using NQL" },
+    { "name": "formats", "reason": "Selects content formats" },
+    { "name": "include", "reason": "Includes related resources" },
+    { "name": "key", "reason": "Content API authentication key" },
+    { "name": "limit", "reason": "Number of resources per page" },
+    { "name": "order", "reason": "Sort order" },
+    { "name": "page", "reason": "Page number for paginated results" }
+  ]
+}

package/core/server/web/query-parameter-policy/schema.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseQueryParameterPolicy = parseQueryParameterPolicy;
+const zod_1 = require("zod");
+const ALLOWED_NAME_CHARACTERS = /^[A-Za-z_-]+$/;
+const QueryParameterPolicyEntrySchema = zod_1.z.object({
+    name: zod_1.z
+        .string()
+        .min(1, { error: 'Parameter names must be nonempty.' })
+        .regex(ALLOWED_NAME_CHARACTERS, {
+        error: 'Parameter names must only contain letters, underscores, and hyphens.',
+    }),
+    reason: zod_1.z
+        .string()
+        .refine((reason) => reason.trim().length > 0, { error: 'Parameter reasons must be nonempty.' }),
+});
+const QueryParameterListSchema = zod_1.z
+    .array(QueryParameterPolicyEntrySchema)
+    .superRefine((entries, context) => {
+    const names = new Set();
+    for (const entry of entries) {
+        if (names.has(entry.name)) {
+            context.addIssue({
+                code: 'custom',
+                message: `Duplicate parameter name "${entry.name}".`,
+            });
+        }
+        names.add(entry.name);
+    }
+});
+const QueryParameterPolicySchema = zod_1.z.object({
+    schemaVersion: zod_1.z.literal(1, { error: 'Unsupported schema version; expected 1.' }),
+    public: QueryParameterListSchema,
+    contentApi: QueryParameterListSchema,
+});
+function parseQueryParameterPolicy(value) {
+    return QueryParameterPolicySchema.parse(value);
+}

package/core/shared/config/defaults.json

@@ -31,6 +31,9 @@
   },
   "useMinFiles": true,
   "verifyRequestIntegrity": true,
+  "queryParameterFiltering": {
+    "enabled": false
+  },
   "paths": {
     "contentPath": "content/",
     "fixtures": "core/server/data/schema/fixtures/fixtures",

package/core/shared/config/env/config.testing-mysql.json

@@ -19,6 +19,9 @@
     "level": "error",
     "logClientErrorsAsError": false
   },
+  "queryParameterFiltering": {
+    "enabled": true
+  },
   "adapters": {
     "Redis": {
       "host": "127.0.0.1",

package/core/shared/config/env/config.testing.json

@@ -15,6 +15,9 @@
     "level": "error",
     "logClientErrorsAsError": false
   },
+  "queryParameterFiltering": {
+    "enabled": true
+  },
   "adapters": {
     "Redis": {
       "host": "127.0.0.1",