From 84ef8ee07999e9d107ea8f76eb9224065a2844c0 Mon Sep 17 00:00:00 2001 From: leemour Date: Thu, 19 Nov 2026 00:01:28 +0100 Subject: [PATCH 1/2] feat(codegen,http): WordPress paging by header, force-delete key, date publish rule, path-scoped sign-in - Page style takes `start` and `pagesHeader`, and `items: ""` for an answer that is the list. wpJsonToOpenApi returns `overrides` giving every collection read page-from-1 by X-WP-TotalPages. - permissions.forceFlags: a delete taking `force` also gets `.delete.force`, applying when true. - valueKeys[].also: setting `date`/`date_gmt` needs the publish key unless the call itself sets status to draft, pending or private (written as body fields plus `unless`). - hostFetch credentialScope: a signed request outside the site's path is refused before sending, and a redirect out of it drops the credential headers. - wpJsonToOpenApi refuses the batch/v1 namespace. Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 23 +++++++++++++ docs/REFERENCE.md | 11 ++++-- docs/standards/kit-surface.md | 15 ++++++-- src/codegen/manifest.ts | 14 +++++--- src/codegen/model.ts | 18 +++++++++- src/codegen/openapi.ts | 3 +- src/codegen/pipeline.ts | 65 ++++++++++++++++++++++++++++++----- src/codegen/wp-json.test.ts | 55 +++++++++++++++++++++++++++-- src/codegen/wp-json.ts | 26 ++++++++++++++ src/http/fetch.test.ts | 32 +++++++++++++++++ src/http/fetch.ts | 26 +++++++++++++- 11 files changed, 264 insertions(+), 24 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index b8d7aef..a6de3c4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -19,6 +19,29 @@ Every entry says what changed as a caller sees it, why, and what to watch for never a contract. Braze's collection gives 95 operations from 99 requests (four documented twice). See [the reference](docs/REFERENCE.md). Watch for: a POST that only reads keeps the write effect its method gives, so the CLI corrects it with an override. +- **A WordPress list pages by its header.** The page style takes `start` (the first page's number) and `pagesHeader` + (a response header with the number of pages), and `items: ""` when the answer itself is the list. + `wpJsonToOpenApi` returns `overrides` that give every collection read this style, from 1, by `X-WP-TotalPages`; + pass them to `generate`. Before, a WordPress read had no paging, so `api … --all` refused it. Watch for: an executor + that reads `pagination` must handle the two new fields; cli-core does from its next release. +- **A permanent delete gets its own key: `permissions.forceFlags`.** WordPress's `force=true` deletes for good, while a + delete without it moves the item to the trash. `forceFlags: ["force"]` gives such a delete `.delete.force` + besides `.delete`, applying when the flag is `true`, so a CLI can ask before a permanent delete and still + allow the trash. See [the generator's options](docs/standards/kit-surface.md). +- **A publish key covers a date change: `valueKeys[].also`.** WordPress publishes a scheduled post whose `date` moves + into the past, with no `status` in the call. `also: ["date", "date_gmt"]` makes setting either need the key, unless + the call itself sets `status` to a value outside `values` (`draft`, `pending` or `private`). The manifest carries it + as the key's `body` fields with `unless`. Watch for: an executor that does not read `unless` asks for the key on a + draft's date change too, which is safe. +- **A sign-in stays under its site's path: `hostFetch`'s `credentialScope`.** Sites under a path share a host + (`host/blog`, a WordPress multisite in subfolders), and the origin check let a redirect carry the sign-in to + `host/other`. With `credentialScope: "https://host/blog/wp-json"`, a signed request outside it is refused before it + is sent, and a redirect out of it drops `authorization`, `cookie` and `proxy-authorization`. + +### Changed — may break callers + +- **`wpJsonToOpenApi` refuses the `batch/v1` namespace.** A batch call carries requests to other routes in its body, + past the keys those routes need, so a CLI never offers it. A CLI that listed it stops generating. ## 0.119.0 — 18.11.2026 diff --git a/docs/REFERENCE.md b/docs/REFERENCE.md index 8c99a28..b875a8b 100644 --- a/docs/REFERENCE.md +++ b/docs/REFERENCE.md @@ -50,13 +50,16 @@ positive byte budget, then decodes strict UTF-8 JSON. It bounds declared length bytes, cancels on rejection/interruption and releases its own reader. It never fetches or interprets HTTP status, provider fields or credentials. A caller still owns those policies and its deadline. -`hostFetch({ hosts, fetch?, timeoutMs?, redirects? })` is the `fetch` a CLI sends HTTP through +`hostFetch({ hosts, fetch?, timeoutMs?, redirects?, credentialScope? })` is the `fetch` a CLI sends HTTP through ([WC-CMD-32](standards/commands.md#wc-cmd-32--declare-every-host-the-cli-contacts-and-reach-them-only-through-hostfetch)). It returns a `FetchLike` that refuses, before anything is sent, a URL whose host is not in `hosts` (`configuration_error`, reason `network.host-undeclared`, the message naming the host and `hosts`), and any scheme but http and https. It follows redirects itself, at most `redirects` (5), so every hop is checked; a 303, or a 301 or 302 after a POST, goes on as a GET without the body; a hop to another origin drops `authorization`, `cookie` and -`proxy-authorization`. A caller's `redirect: "manual"` or `"error"` is passed on. `timeoutMs` (30 s, +`proxy-authorization`. A site under a path shares its host with others (`host/blog`, a WordPress multisite in +subfolders): `credentialScope` (`https://host/blog/wp-json`) then limits the sign-in to that origin and path. A request +outside it that carries one of those headers is refused before it is sent (`configuration_error`), and a hop out of it +drops them. A caller's `redirect: "manual"` or `"error"` is passed on. `timeoutMs` (30 s, `HOST_FETCH_TIMEOUT_MS`) bounds the whole exchange, body included, beside the caller's own `signal`; a timeout is `timeout` and a failed connection `network_error`. `hostCovered(hostname, hosts)` and `hostProblems(hosts)` are the matching and the check it uses: `*.acme.example` covers `api.acme.example`, never `acme.example`. @@ -289,7 +292,9 @@ template's `theme//slug`, a plugin's `dir/file`) fits no path segment and is lef namespaces not offered; a route that is still a pattern, a second route on one path or an argument with no type stops generation, unless `exclude` names the route with a reason. WordPress answers a list without its page count in the body, so `pagination: true` -finds no paging for it. +finds no paging for it; the result's `overrides`, passed to `generate`, give each collection read the page style from 1 +with the count in `X-WP-TotalPages`. The `batch/v1` namespace is refused: one batch call runs other routes' writes +past the keys they need. **A Postman collection becomes OpenAPI.** `postmanToOpenApi(collection, { variables, exclude, version })` takes a parsed collection, v2.0 or v2.1, and returns an OpenAPI 3.1 document for `adaptOpenApi` with its `omissions`. Commit diff --git a/docs/standards/kit-surface.md b/docs/standards/kit-surface.md index 7b6a6ef..5e9528d 100644 --- a/docs/standards/kit-surface.md +++ b/docs/standards/kit-surface.md @@ -108,7 +108,7 @@ From the source the generator reads: empty or not in kebab case stops generation; map that operation in `commands`. `segments` renames a path segment or, with `""`, leaves it out: `{ "0-3": "deals", crm: "", objects: "" }`. Without `names` the command is the operation id in kebab case, as before. -- **`permissions`**: `{ group, deletingFlags, shares, valueKeys }`. `group` is a name (`files`) or a function of the operation, for +- **`permissions`**: `{ group, deletingFlags, forceFlags, shares, valueKeys }`. `group` is a name (`files`) or a function of the operation, for example the first word of its `command` (set only with `names`). Each key lands in the manifest as the operation's `permissions`. - `.delete` for every destructive operation (Yandex Disk's `DELETE /trash/resources` empties the whole trash), and for every operation that takes a flag in `deletingFlags`, as a top-level body field (Notion's @@ -122,7 +122,14 @@ From the source the generator reads: `posts.publish` and `pages.publish`. The key applies when the call sends one of those values, in the body or the query; where the field's default is one of them (a WordPress template), leaving it out publishes too, and the key always applies. A read that filters by the value gets no key, nor a field of that name without such an enum (a - comment's `status`); a rule no write matches stops generation. + comment's `status`); a rule no write matches stops generation. `also` names fields that make the same change + another way: WordPress publishes a scheduled post whose `date` moves into the past, so with + `also: ["date", "date_gmt"]` setting either needs the key too, unless the call itself sets `field` to a value + outside `values` (`draft`, `pending`, `private`). A call that leaves `field` out needs the key: the stored value is + unknown without a read. + - `.delete.force` beside `.delete` on every delete that takes a flag in `forceFlags`: WordPress's + `force=true` deletes for good, where a delete without it moves to the trash. The key applies when the flag is + `true`. A flag no delete takes stops generation. Which flags delete is the CLI's call: read the service's documentation, and count an undocumented flag as a delete. A flag counts on every method, a GET included: Yandex Disk's upload link is a GET whose `overwrite` replaces a file. @@ -134,7 +141,9 @@ From the source the generator reads: string, so a `start` date is not taken for an offset. Answer fields are dotted paths. Only reads page: a POST search pages once `readingPosts` or an override makes it a read. An override's `pagination` sets it where detection misses or misreads, and `pagination: null` says the read does not page; a - parameter the operation does not take stops generation. + parameter the operation does not take stops generation. A page style may say where the first page is (`start: 1`) + and name a response header with the number of pages (`pagesHeader: "x-wp-totalpages"`), with `items: ""` when the + answer itself is the list: WordPress's, which `wpJsonToOpenApi` gives in its `overrides`. - **`auth`**: `{ securitySchemes, security, reason }` replaces the source's sign-in, the operations' own requirements included. Yandex Disk's Swagger 1.2 has no scheme, and its header is `Authorization: OAuth `: `{ oauth: { type: "http", scheme: "OAuth" } }`. HubSpot's spec has no private app token. An operation keeps its own diff --git a/src/codegen/manifest.ts b/src/codegen/manifest.ts index 0cbc7e4..d28f13b 100644 --- a/src/codegen/manifest.ts +++ b/src/codegen/manifest.ts @@ -197,12 +197,17 @@ export const coverageGenerator = const guarded = model.operations.flatMap((operation) => (operation.permissions ?? []).map((permission) => ({ id: operation.id, permission })), ) - const when = ({ body, query, values }: OperationPermission) => - [ - ...(body ?? []).map((flag) => `body \`${flag}\` is true`), - ...(query ?? []).map((flag) => `query \`${flag}\` is true`), + const when = ({ body, query, values, unless }: OperationPermission) => { + const set = [ ...Object.entries(values ?? {}).map(([field, listed]) => `\`${field}\` is ${listed.join(" or ")}`), + ...(body ?? []).map((flag) => `body \`${flag}\` is ${unless ? "set" : "true"}`), + ...(query ?? []).map((flag) => `query \`${flag}\` is ${unless ? "set" : "true"}`), ].join(" or ") + const except = Object.entries(unless ?? {}).map( + ([field, listed]) => `the call sets \`${field}\` to ${listed.join(" or ")}`, + ) + return except.length > 0 ? `${set}, unless ${except.join(" or ")}` : set + } const content = [ `# ${options.title}`, "", @@ -241,6 +246,7 @@ export const coverageGenerator = page.items ? `items \`${page.items}\`` : undefined, "hasMore" in page && page.hasMore ? `more \`${page.hasMore}\`` : undefined, "total" in page && page.total ? `total \`${page.total}\`` : undefined, + "pagesHeader" in page && page.pagesHeader ? `pages header \`${page.pagesHeader}\`` : undefined, ].filter(Boolean) return `| \`${id}\` | ${page.style} | ${request.join(", ") || "—"} | ${answer.join(", ")} | ${cell(paginationSource)} |` }), diff --git a/src/codegen/model.ts b/src/codegen/model.ts index 57a54dd..f222b32 100644 --- a/src/codegen/model.ts +++ b/src/codegen/model.ts @@ -171,7 +171,18 @@ export type Pagination = limit?: PageParameter } | { style: "offset"; offset: PageParameter; limit?: PageParameter; items: string; total?: string } - | { style: "page"; page: PageParameter; limit?: PageParameter; items: string; total?: string } + | { + style: "page" + page: PageParameter + limit?: PageParameter + /** `""` when the answer itself is the list, as WordPress's. */ + items: string + total?: string + /** The first page's number, where the source says it (WordPress counts from 1): `--all` then needs none given. */ + start?: number + /** A response header holding the number of pages, as WordPress's `X-WP-TotalPages`: that page is the last. */ + pagesHeader?: string + } /** The answer holds the next page's whole URL. */ | { style: "link"; next: string; items?: string } @@ -190,6 +201,11 @@ export interface OperationPermission { * Both places count, as a service that merges them (WordPress) publishes from either. */ values?: Readonly> + /** + * The key does not apply when the call itself sets a field to one of these: `{ status: ["draft", "pending"] }` keeps + * a draft's date change free. A call that leaves the field out still needs the key, as the stored value is unknown. + */ + unless?: Readonly> } /** The scheme names an operation needs, each with its OAuth scopes; one requirement of the list is enough. */ diff --git a/src/codegen/openapi.ts b/src/codegen/openapi.ts index eba1c20..dc88df1 100644 --- a/src/codegen/openapi.ts +++ b/src/codegen/openapi.ts @@ -133,7 +133,8 @@ const SCHEME_TYPES = new Set(["apiKey", "http", "oauth2" const FLOWS = ["implicit", "password", "clientCredentials", "authorizationCode"] as const /** A spec without a single operationId (Attio's) still has calls: `get /v2/objects/{object}` → `getV2ObjectsByObject`. */ -const derivedId = (method: string, path: string): string => +/** The id `adaptOpenApi` gives an operation without an `operationId`: `getWpV2PostsById`. */ +export const derivedId = (method: string, path: string): string => method + path .split("/") diff --git a/src/codegen/pipeline.ts b/src/codegen/pipeline.ts index 0b0b252..6f7c555 100644 --- a/src/codegen/pipeline.ts +++ b/src/codegen/pipeline.ts @@ -145,8 +145,10 @@ export const applyPagination = ( if (operation.effect !== "read") problems.push(`${at} on an operation that is not a read`) const request = requestParameters(operation, schemas) const answer = answerPaths(operation, schemas) - const { style: _, ...fields } = override.pagination as Record + const { style: _, start: __, pagesHeader: ___, ...fields } = override.pagination as Record for (const [field, value] of Object.entries(fields)) { + // `""`: the answer itself is the list. + if (value === "") continue if (typeof value === "string") { // An answer without a schema has nothing to check the path against. if (answer.size > 0 && !answer.has(value)) @@ -207,8 +209,17 @@ export interface PermissionRule { * `enum`, so a field of the same name that means something else (a comment's `status`) gets no key, nor does a read * that filters by the value. Where the field's default is one of `values` (a WordPress template), leaving it out * publishes too, and the key always applies. + * + * `also` names fields that make the same change through another door: WordPress publishes a scheduled post whose + * `date` moves into the past. Setting one applies the key too, unless the call itself sets `field` to a value + * outside `values` (a draft's new date); a call that leaves `field` out cannot say what is stored, so it needs the key. */ - valueKeys?: readonly { key: string; field: string; values: readonly string[] }[] + valueKeys?: readonly { key: string; field: string; values: readonly string[]; also?: readonly string[] }[] + /** + * Flags that make a delete permanent instead of a move to the trash: WordPress's `force`. A delete that takes one + * also needs `.delete.force` when the flag is `true`; without it the trash is `.delete` alone. + */ + forceFlags?: readonly string[] } /** The top-level properties a body may carry, through references, inheritance, unions and subtypes. */ @@ -280,16 +291,38 @@ export const applyPermissionRule = (model: ApiModel, rule: PermissionRule): ApiM } const valueKeys = rule.valueKeys ?? [] // A field whose default is one of the values publishes when the call leaves it out: the key then always applies. + const takes = (operation: ApiOperation, names: readonly string[]) => ({ + body: names.filter((name) => fieldsOf(operation).has(name)), + query: names.filter((name) => + operation.parameters.some((parameter) => parameter.in === "query" && parameter.name === name), + ), + }) + const flagged = ({ body, query }: { body: string[]; query: string[] }) => ({ + ...(body.length > 0 ? { body } : {}), + ...(query.length > 0 ? { query } : {}), + }) const valued = (operation: ApiOperation): OperationPermission[] => operation.effect === "read" ? [] - : valueKeys.flatMap(({ key, field, values }) => { + : valueKeys.flatMap(({ key, field, values, also = [] }) => { const { enums, defaults } = valuesOf(operation, field) const named = values.filter((value) => enums.includes(value)) if (named.length === 0) return [] - return defaults.some((value) => values.includes(value as string)) - ? [{ key }] - : [{ key, values: { [field]: named } }] + if (defaults.some((value) => values.includes(value as string))) return [{ key }] + const others = takes(operation, also) + const unless = [...new Set(enums.filter((value): value is string => typeof value === "string"))].filter( + (value) => !values.includes(value), + ) + return [ + { + key, + values: { [field]: named }, + ...flagged(others), + ...(others.body.length + others.query.length > 0 && unless.length > 0 + ? { unless: { [field]: unless } } + : {}), + }, + ] }) const idle = valueKeys.filter( ({ key }) => !model.operations.some((operation) => valued(operation).some((one) => one.key === key)), @@ -308,14 +341,30 @@ export const applyPermissionRule = (model: ApiModel, rule: PermissionRule): ApiM ) if (unused.length > 0) throw new CodegenError(unused.map((flag) => `deletingFlags: "${flag}" is in no request body or query`)) + const forceFlags = rule.forceFlags ?? [] + const forcing = (operation: ApiOperation) => takes(operation, forceFlags) + const idleForce = forceFlags.filter( + (flag) => + !model.operations.some((operation) => { + if (operation.effect !== "destructive") return false + const { body, query } = forcing(operation) + return body.includes(flag) || query.includes(flag) + }), + ) + if (idleForce.length > 0) + throw new CodegenError(idleForce.map((flag) => `forceFlags: "${flag}" is in no delete's request body or query`)) return { ...model, operations: model.operations.map((operation) => { const group = typeof rule.group === "string" ? rule.group : rule.group(operation) const permissions: OperationPermission[] = [] if (rule.shares?.includes(operation.id)) permissions.push({ key: `${group}.share` }) - if (operation.effect === "destructive") permissions.push({ key: `${group}.delete` }) - else { + if (operation.effect === "destructive") { + permissions.push({ key: `${group}.delete` }) + const force = forcing(operation) + if (force.body.length + force.query.length > 0) + permissions.push({ key: `${group}.delete.force`, ...flagged(force) }) + } else { const body = flags.filter((flag) => fieldsOf(operation).has(flag)) const query = flags.filter((flag) => operation.parameters.some((parameter) => parameter.in === "query" && parameter.name === flag), diff --git a/src/codegen/wp-json.test.ts b/src/codegen/wp-json.test.ts index 8519e76..7d51b27 100644 --- a/src/codegen/wp-json.test.ts +++ b/src/codegen/wp-json.test.ts @@ -12,6 +12,7 @@ import { generate, type ManifestOperation, manifestGenerator, + type PermissionRule, readWpJson, type SchemaNode, syncWpJson, @@ -76,6 +77,9 @@ describe("wpJsonToOpenApi", () => { it("leaves out other namespaces, the namespace's own index, and a route whose value may hold a slash", () => { expect(model.operations.some((one) => one.id.includes("Oembed"))).toBe(false) expect(omissions).toContain("oembed/1.0: not offered, 1 routes") + expect(problems(() => wpJsonToOpenApi(excerpt(), { namespaces: ["wp/v2", "batch/v1"] }))).toEqual([ + "batch/v1 is never offered: a batch call runs other routes' writes past their own keys", + ]) expect(operation("getWpV2")).toBeUndefined() expect(model.operations.some((one) => one.id.includes("Templates"))).toBe(false) expect(omissions).toContain(`${TEMPLATE}: left out, as its value may hold a slash, which no path segment carries`) @@ -161,9 +165,10 @@ describe("wpJsonToOpenApi", () => { }) describe("the api group of a WordPress CLI from its snapshot", () => { - const model = adaptOpenApi(wpJsonToOpenApi(excerpt(), { namespaces: ["wp/v2"] }).document) + const converted = wpJsonToOpenApi(excerpt(), { namespaces: ["wp/v2"] }) + const model = adaptOpenApi(converted.document) const group = (one: ApiOperation) => (one.binding.kind === "http" ? (one.binding.path.split("/")[3] ?? "wp") : "wp") - const build = (valueKeys: readonly { key: string; field: string; values: readonly string[] }[]) => + const build = (valueKeys: NonNullable, rule: Pick = {}) => generate( model, [ @@ -173,7 +178,7 @@ describe("the api group of a WordPress CLI from its snapshot", () => { typesGenerator({ path: "types.ts" }), valibotGenerator({ path: "schemas.ts", typesImport: "./types.js" }), ], - { banner: [], permissions: { group, valueKeys } }, + { banner: [], overrides: converted.overrides, permissions: { group, valueKeys, ...rule } }, ) const [manifest, definitions, coverage] = build([{ key: "publish", field: "status", values: ["publish", "future"] }]) const operations = exported(manifest?.content, "operations") as ManifestOperation[] @@ -246,6 +251,50 @@ describe("the api group of a WordPress CLI from its snapshot", () => { ]) }) + it("needs posts.publish to set a post's date unless the call itself keeps it a draft, pending or private", () => { + const [dated] = build([ + { key: "publish", field: "status", values: ["publish", "future"], also: ["date", "date_gmt"] }, + ]) + const listed = exported(dated?.content, "operations") as ManifestOperation[] + const keyOf = (id: string) => listed.find((one) => one.id === id)?.permissions + expect(keyOf("postWpV2PostsById")).toEqual([ + { + key: "posts.publish", + values: { status: ["publish", "future"] }, + body: ["date", "date_gmt"], + unless: { status: ["draft", "pending", "private"] }, + }, + ]) + expect(keyOf("postWpV2MenuItems")).toEqual([{ key: "menu-items.publish" }]) + }) + + it("needs a delete.force key besides delete when force=true deletes for good instead of moving to the trash", () => { + const [forced, , listing] = build([{ key: "publish", field: "status", values: ["publish", "future"] }], { + forceFlags: ["force"], + }) + const listed = exported(forced?.content, "operations") as ManifestOperation[] + expect(listed.find((one) => one.id === "deleteWpV2PostsById")?.permissions).toEqual([ + { key: "posts.delete" }, + { key: "posts.delete.force", query: ["force"] }, + ]) + expect(listing?.content).toContain("| `deleteWpV2PostsById` | `posts.delete.force` | query `force` is true |") + expect(problems(() => build([], { forceFlags: ["purge"] }))).toEqual([ + 'forceFlags: "purge" is in no delete\'s request body or query', + ]) + }) + + it("pages a collection read from 1 by the X-WP-TotalPages header, the answer itself being the list", () => { + const read = operations.find((one) => one.id === "getWpV2Posts") + expect(read?.pagination).toEqual({ + style: "page", + page: { in: "query", name: "page" }, + limit: { in: "query", name: "per_page" }, + items: "", + start: 1, + pagesHeader: "x-wp-totalpages", + }) + }) + it("serves the generated calls from a fake that checks the application password", async () => { const fake = fakeApi({ operations, diff --git a/src/codegen/wp-json.ts b/src/codegen/wp-json.ts index 0049595..4ad52dd 100644 --- a/src/codegen/wp-json.ts +++ b/src/codegen/wp-json.ts @@ -10,6 +10,8 @@ */ import { mkdirSync, readFileSync, writeFileSync } from "node:fs" import { join } from "node:path" +import type { Override } from "./model.js" +import { derivedId } from "./openapi.js" import { CodegenError } from "./pipeline.js" import { sha256, sortKeys } from "./snapshot.js" @@ -31,6 +33,11 @@ export interface WpJsonOptions { export interface WpJsonResult { /** An OpenAPI 3.1 document for `adaptOpenApi`. */ document: Json + /** + * For `generate`'s `overrides`: how each collection read pages. WordPress answers the list itself, counts pages from + * 1 and gives their number in `X-WP-TotalPages`; a page past it is an error, not an empty list. + */ + overrides: Record /** What the document leaves out, one line each, for a reviewer. */ omissions: string[] } @@ -145,6 +152,8 @@ const template = (route: string): { path: string; patterns: Record "per_page" in args && "page" in args @@ -156,11 +165,15 @@ const isList = (args: Json) => "per_page" in args && "page" in args */ export const wpJsonToOpenApi = (index: unknown, options: WpJsonOptions): WpJsonResult => { if (!object(index) || !object(index.routes)) throw new CodegenError(["not a WordPress REST index: no routes"]) + // One batch call carries requests to other routes in its body, past every key those routes need. + if (options.namespaces.includes(BATCH)) + throw new CodegenError([`${BATCH} is never offered: a batch call runs other routes' writes past their own keys`]) const exclude = options.exclude ?? {} const used = new Set() const problems: string[] = [] const omissions: string[] = [] const paths: Record = {} + const overrides: Record = {} const schemas: Record = {} const left = new Map() const schemaRef = (route: string, schema: unknown): Json => { @@ -255,6 +268,18 @@ export const wpJsonToOpenApi = (index: unknown, options: WpJsonOptions): WpJsonR if (raw.schema !== undefined && method !== "DELETE") { const ref = schemaRef(route, raw.schema) const answer = method === "GET" && isList(args) ? { type: "array", items: ref } : ref + if (method === "GET" && isList(args)) + overrides[derivedId("get", path)] = { + pagination: { + style: "page", + page: { in: "query", name: "page" }, + limit: { in: "query", name: "per_page" }, + items: "", + start: 1, + pagesHeader: "x-wp-totalpages", + }, + reason: "WordPress counts pages from 1 and gives their number in X-WP-TotalPages", + } operation.responses = { "200": { description: "OK", content: { "application/json": { schema: answer } } } } } else operation.responses = { "200": { description: "OK" } } item[verb] = operation @@ -283,6 +308,7 @@ export const wpJsonToOpenApi = (index: unknown, options: WpJsonOptions): WpJsonR paths, }, omissions, + overrides, } } diff --git a/src/http/fetch.test.ts b/src/http/fetch.test.ts index f48bce9..5e4539d 100644 --- a/src/http/fetch.test.ts +++ b/src/http/fetch.test.ts @@ -83,6 +83,38 @@ describe("hostFetch", () => { expect(hop?.headers.get("x-trace")).toBe("1") }) + it("keeps a site's sign-in under its path: refused outside it, dropped on a hop out of it, kept on one within", async () => { + const { sent, send } = recorder({ + "https://host.example/blog/wp-json/a": redirect(302, "/other/wp-json/a"), + "https://host.example/blog/wp-json/b": redirect(302, "/blog/wp-json/c"), + "https://host.example/blog/wp-json/c": ok, + "https://host.example/other/wp-json/a": ok, + }) + const fetch = hostFetch({ + hosts: ["host.example"], + fetch: send, + credentialScope: "https://host.example/blog/wp-json", + }) + const signed = { headers: { authorization: "Basic eA==" } } + await expect(fetch("https://host.example/blog/wp-json/../../other/wp-json/x", signed)).rejects.toMatchObject({ + code: "configuration_error", + details: { sent: false }, + }) + await expect(fetch("https://host.example/blog/wp-jsonx/x", signed)).rejects.toMatchObject({ + code: "configuration_error", + }) + expect(sent).toEqual([]) + await fetch("https://host.example/blog/wp-json/a", signed) + await fetch("https://host.example/blog/wp-json/b", signed) + expect(sent.map((one) => [one.url, one.headers.get("authorization")])).toEqual([ + ["https://host.example/blog/wp-json/a", "Basic eA=="], + ["https://host.example/other/wp-json/a", null], + ["https://host.example/blog/wp-json/b", "Basic eA=="], + ["https://host.example/blog/wp-json/c", "Basic eA=="], + ]) + expect((await fetch("https://host.example/other/wp-json/a")).status).toBe(200) + }) + it("hands back the redirect itself when the caller asked for manual redirects", async () => { const { send } = recorder({ "https://api.acme.example/a": redirect(302, "https://evil.example.net/") }) const fetch = hostFetch({ hosts: ["api.acme.example"], fetch: send }) diff --git a/src/http/fetch.ts b/src/http/fetch.ts index 4be39c5..fcd5c7c 100644 --- a/src/http/fetch.ts +++ b/src/http/fetch.ts @@ -9,6 +9,11 @@ export interface HostFetchOptions { /** For the whole exchange, every redirect and the body. */ timeoutMs?: number redirects?: number + /** + * Where the sign-in may go, as `https://host/blog/wp-json`: a site under a path shares its host with others. A signed + * request outside it is refused, and a redirect out of it drops the sign-in. Without it, the origin is the limit. + */ + credentialScope?: string } export const HOST_FETCH_TIMEOUT_MS = 30_000 @@ -58,6 +63,15 @@ const checked = (url: URL, hosts: readonly string[]): URL => { return url } +const scopeOf = (scope: string | undefined) => { + if (scope === undefined) return undefined + const { origin, pathname } = new URL(scope) + const prefix = pathname.endsWith("/") ? pathname : `${pathname}/` + return (url: URL) => url.origin === origin && (url.pathname === pathname || url.pathname.startsWith(prefix)) +} + +const signedHeaders = (headers: Headers) => CREDENTIAL_HEADERS.some((name) => headers.has(name)) + /** * A name lookup or a connection the host refused fails before a byte of the request leaves, so even a write may be sent * again. Node's fetch puts the system's code on the cause, an AggregateError when it tried several addresses; a @@ -77,6 +91,7 @@ export const hostFetch = (options: HostFetchOptions): FetchLike => { const problems = hostProblems(options.hosts) if (problems.length > 0) throw new CliError("configuration_error", problems.join("; ")) const { hosts, fetch: send = globalThis.fetch, timeoutMs = HOST_FETCH_TIMEOUT_MS, redirects = REDIRECTS } = options + const inScope = scopeOf(options.credentialScope) return async (input, init = {}) => { const request = input instanceof Request ? input : undefined @@ -88,6 +103,14 @@ export const hostFetch = (options: HostFetchOptions): FetchLike => { let method = (init.method ?? request?.method ?? "GET").toUpperCase() let body = init.body ?? request?.body ?? undefined const headers = new Headers(init.headers ?? request?.headers) + if (inScope && signedHeaders(headers) && !inScope(url)) + throw new CliError( + "configuration_error", + `the sign-in goes only under ${options.credentialScope}, not ${url.origin}${url.pathname}`, + { + sent: false, + }, + ) // A redirect means the first request arrived: a later hop's failure no longer proves nothing was sent. let answered = false @@ -111,7 +134,8 @@ export const hostFetch = (options: HostFetchOptions): FetchLike => { "invalid_response", `${url.hostname} redirected a streamed body, which cannot be sent again`, ) - if (next.origin !== url.origin) for (const name of CREDENTIAL_HEADERS) headers.delete(name) + if (inScope ? !inScope(next) : next.origin !== url.origin) + for (const name of CREDENTIAL_HEADERS) headers.delete(name) url = next response = await send(url, { ...init, method, headers, body, signal, redirect: "manual" }) } From 25852c9f0000adea690833045207232046aebab9 Mon Sep 17 00:00:00 2001 From: leemour Date: Thu, 19 Nov 2026 00:08:15 +0100 Subject: [PATCH 2/2] fix(codegen,http): review findings: encoded slash leaves the scope, a misspelt also stops generation, pagination checks stay strict Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 3 ++- docs/standards/kit-surface.md | 6 +++--- src/codegen/model.ts | 2 +- src/codegen/pipeline.ts | 22 +++++++++++++++++++--- src/codegen/wp-json.test.ts | 7 +++++++ src/http/fetch.test.ts | 3 +++ src/http/fetch.ts | 9 ++++++++- 7 files changed, 43 insertions(+), 9 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index a6de3c4..c8ea85c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -36,7 +36,8 @@ Every entry says what changed as a caller sees it, why, and what to watch for - **A sign-in stays under its site's path: `hostFetch`'s `credentialScope`.** Sites under a path share a host (`host/blog`, a WordPress multisite in subfolders), and the origin check let a redirect carry the sign-in to `host/other`. With `credentialScope: "https://host/blog/wp-json"`, a signed request outside it is refused before it - is sent, and a redirect out of it drops `authorization`, `cookie` and `proxy-authorization`. + is sent, and a redirect out of it drops `authorization`, `cookie` and `proxy-authorization`. A path with an encoded + slash (`%2F`, `%5C`) counts as outside, as a server that decodes it before routing could leave the scope. ### Changed — may break callers diff --git a/docs/standards/kit-surface.md b/docs/standards/kit-surface.md index 5e9528d..ec5b79d 100644 --- a/docs/standards/kit-surface.md +++ b/docs/standards/kit-surface.md @@ -124,9 +124,9 @@ From the source the generator reads: always applies. A read that filters by the value gets no key, nor a field of that name without such an enum (a comment's `status`); a rule no write matches stops generation. `also` names fields that make the same change another way: WordPress publishes a scheduled post whose `date` moves into the past, so with - `also: ["date", "date_gmt"]` setting either needs the key too, unless the call itself sets `field` to a value - outside `values` (`draft`, `pending`, `private`). A call that leaves `field` out needs the key: the stored value is - unknown without a read. + `also: ["date", "date_gmt"]` setting either needs the key too, unless the call itself sets `field` to another value + its enum lists (for WordPress `draft`, `pending`, `private`). A call that leaves `field` out needs the key: the + stored value is unknown without a read. An `also` field no guarded write takes stops generation. - `.delete.force` beside `.delete` on every delete that takes a flag in `forceFlags`: WordPress's `force=true` deletes for good, where a delete without it moves to the trash. The key applies when the flag is `true`. A flag no delete takes stops generation. diff --git a/src/codegen/model.ts b/src/codegen/model.ts index f222b32..8f1b6e4 100644 --- a/src/codegen/model.ts +++ b/src/codegen/model.ts @@ -202,7 +202,7 @@ export interface OperationPermission { */ values?: Readonly> /** - * The key does not apply when the call itself sets a field to one of these: `{ status: ["draft", "pending"] }` keeps + * The key does not apply when the call itself sets a field to one of these: `{ status: ["draft", "pending", "private"] }` keeps * a draft's date change free. A call that leaves the field out still needs the key, as the stored value is unknown. */ unless?: Readonly> diff --git a/src/codegen/pipeline.ts b/src/codegen/pipeline.ts index 6f7c555..23e00e3 100644 --- a/src/codegen/pipeline.ts +++ b/src/codegen/pipeline.ts @@ -145,10 +145,14 @@ export const applyPagination = ( if (operation.effect !== "read") problems.push(`${at} on an operation that is not a read`) const request = requestParameters(operation, schemas) const answer = answerPaths(operation, schemas) - const { style: _, start: __, pagesHeader: ___, ...fields } = override.pagination as Record + const { style, start, pagesHeader, ...fields } = override.pagination as Record + if (start !== undefined && (style !== "page" || !Number.isInteger(start) || (start as number) < 0)) + problems.push(`${at}: start must be a whole number from 0, on the page style`) + if (pagesHeader !== undefined && (style !== "page" || typeof pagesHeader !== "string" || pagesHeader === "")) + problems.push(`${at}: pagesHeader must name a header, on the page style`) for (const [field, value] of Object.entries(fields)) { - // `""`: the answer itself is the list. - if (value === "") continue + // `items: ""`: the answer itself is the list. + if (field === "items" && value === "") continue if (typeof value === "string") { // An answer without a schema has nothing to check the path against. if (answer.size > 0 && !answer.has(value)) @@ -331,6 +335,18 @@ export const applyPermissionRule = (model: ApiModel, rule: PermissionRule): ApiM throw new CodegenError( idle.map(({ field, values }) => `valueKeys: no write lists ${values.join(" or ")} in the enum of "${field}"`), ) + // A misspelt `also` would leave the other door open without a word. + const idleAlso = valueKeys.flatMap(({ key, also = [] }) => + also + .filter( + (name) => + !model.operations.some((operation) => + valued(operation).some((one) => one.key === key && (one.body?.includes(name) || one.query?.includes(name))), + ), + ) + .map((name) => `valueKeys: also "${name}" is in no write that "${key}" guards`), + ) + if (idleAlso.length > 0) throw new CodegenError(idleAlso) const unused = flags.filter( (flag) => !model.operations.some( diff --git a/src/codegen/wp-json.test.ts b/src/codegen/wp-json.test.ts index 7d51b27..4daad64 100644 --- a/src/codegen/wp-json.test.ts +++ b/src/codegen/wp-json.test.ts @@ -278,6 +278,13 @@ describe("the api group of a WordPress CLI from its snapshot", () => { { key: "posts.delete.force", query: ["force"] }, ]) expect(listing?.content).toContain("| `deleteWpV2PostsById` | `posts.delete.force` | query `force` is true |") + expect( + problems(() => + build([{ key: "publish", field: "status", values: ["publish", "future"], also: ["dat"] }], { + forceFlags: ["force"], + }), + ), + ).toEqual(['valueKeys: also "dat" is in no write that "publish" guards']) expect(problems(() => build([], { forceFlags: ["purge"] }))).toEqual([ 'forceFlags: "purge" is in no delete\'s request body or query', ]) diff --git a/src/http/fetch.test.ts b/src/http/fetch.test.ts index 5e4539d..1a8e6eb 100644 --- a/src/http/fetch.test.ts +++ b/src/http/fetch.test.ts @@ -103,6 +103,9 @@ describe("hostFetch", () => { await expect(fetch("https://host.example/blog/wp-jsonx/x", signed)).rejects.toMatchObject({ code: "configuration_error", }) + await expect(fetch("https://host.example/blog/wp-json/..%2F..%2Fother/x", signed)).rejects.toMatchObject({ + code: "configuration_error", + }) expect(sent).toEqual([]) await fetch("https://host.example/blog/wp-json/a", signed) await fetch("https://host.example/blog/wp-json/b", signed) diff --git a/src/http/fetch.ts b/src/http/fetch.ts index fcd5c7c..93c984a 100644 --- a/src/http/fetch.ts +++ b/src/http/fetch.ts @@ -63,11 +63,18 @@ const checked = (url: URL, hosts: readonly string[]): URL => { return url } +// A server that decodes `%2F` before it routes would take `/blog/..%2F..%2Fother` out of the scope the prefix saw. +const ENCODED_SLASH = /%2f|%5c/i + const scopeOf = (scope: string | undefined) => { if (scope === undefined) return undefined + if (!URL.canParse(scope)) throw new CliError("configuration_error", `credentialScope ${scope} is not a URL`) const { origin, pathname } = new URL(scope) const prefix = pathname.endsWith("/") ? pathname : `${pathname}/` - return (url: URL) => url.origin === origin && (url.pathname === pathname || url.pathname.startsWith(prefix)) + return (url: URL) => + url.origin === origin && + (url.pathname === pathname || url.pathname.startsWith(prefix)) && + !ENCODED_SLASH.test(url.pathname) } const signedHeaders = (headers: Headers) => CREDENTIAL_HEADERS.some((name) => headers.has(name))