`RestApiConfigSchema` constrains `api.version` with a regex the REST server never runs — the seam casts instead of parsing, so `api.version: ''` is accepted and mounts the whole API at `/api//`

[os-zhuang]

Found while implementing #11546 (openapi info.version). Filed, not fixed — #11546's declared surface is the openapi info construction in packages/rest/src/rest-server.ts, and this is a contract-enforcement question with its own gate family.

Corrected after filing. The first version of this issue said PluginRestApiSchema.version is a bare z.string(), so '' is schema-valid. Both halves were wrong and the correction inverts the mechanism, so the whole body is restated rather than patched. There is no PluginRestApiSchema in the repo; the symbol I meant is RestApiPluginConfigSchema (packages/spec/src/api/plugin-rest-api.zod.ts:625), and it governs nothing on this path. The schema that does govern this field forbids ''. The defect is that nothing enforces it. Thanks to the PM seat for catching the dangling symbol.

What was measured

On origin/main @ e3f056fc.

The governing schema, packages/spec/src/api/rest-server.zod.ts:48-52:

export const RestApiConfigSchema = lazySchema(() => z.object({
 version: z.string().regex(/^[a-zA-Z0-9_\-\.]+$/).default('v1').describe('API version (e.g., v1, v2, 2024-01)'),

The + quantifier means '' does not match: this schema rejects an empty version, and .default('v1') only fires on undefined.

That it is the governing schema is a chain, each link measured:

• packages/rest/src/rest-api-plugin.ts:68 — RestApiPluginConfig.api?: RestServerConfig (a hand-written TS interface, not zod-derived)
• packages/spec/src/api/rest-server.zod.ts:485 — api: RestApiConfigSchema.optional()
• packages/spec/src/api/rest-server.zod.ts:164 — RestApiConfig = z.input<typeof RestApiConfigSchema>, which is what the server casts to

The defect: declared, never enforced

Nothing parses a deployment's config against that schema. Every hop is a cast:

// packages/rest/src/rest-api-plugin.ts:388
restServer = new RestServer(server, protocol, config.api as any, /* … */);

// packages/rest/src/rest-server.ts:2916
const api = (config.api ?? {}) as Partial<RestApiConfig>;

and the guard that remains is ??, which only substitutes null/undefined:

// packages/rest/src/rest-server.ts:2924
version: api.version ?? 'v1',

Three independent confirmations that no parse happens on any deployment path:

1. createRestApiPlugin declares no configSchema, so packages/core/src/security/plugin-config-validator.ts — which does plugin.configSchema.parse(config) when one is declared — never runs for this plugin. (git grep configSchema packages/rest/src/rest-api-plugin.ts → zero hits.)
2. The repo's only RestApiConfigSchema.parse call is RestApiConfigSchema.parse({}) in packages/core/src/qa/http-adapter.ts:43, a QA helper deriving default conventions from an empty object — not deployment config.
3. RestApiPluginConfigSchema, the sibling that does declare a bare z.string() for its own version, is referenced nowhere outside its own file, its own test, and packages/spec/api-surface/api.json. It is not the type of anything on this path, so its permissiveness is not what lets '' through either.

So the regex is a declared constraint that never executes.

Observed consequence

Driving a real RestServer with api: { version: '' }:

• getApiBasePath() returns "/api/" (from api.apiPath ?? \${api.basePath}/${api.version}``)
• every route mounts under it — the openapi route registers at the literal path "/api//openapi.json", with the doubled slash, and the same applies to /data, /meta, /discovery and the rest of the surface, since they all share this one base

A configuration the spec rejects is accepted by the server and produces a deployment whose every route carries a doubled slash. Which URLs that actually answers depends on the HTTP adapter's path normalization rather than on anything this repo declares.

The empty string is only the most visible instance. The regex also forbids /, whitespace and every other character outside [a-zA-Z0-9_\-\.], and none of those are refused either — version: 'v1/beta' would splice a path segment into the mount for every route.

Not prejudged

The root fix is to make this seam parse rather than cast, but where that belongs is a real call:

• Parse in normalizeConfig() — replace the cast with RestApiConfigSchema.parse(config.api ?? {}). Declared = enforced at the point of use, and the ?? defaults become redundant because the schema's own .default() supplies them. Risk: any deployment currently booting on a config the schema rejects would start failing at boot — which is the point, but it is a behaviour change that wants measuring first.
• Declare configSchema on the REST plugin — let the kernel's existing plugin-config-validator do it, which is the mechanism already built for this and would cover the plugin's other config too.
• Both — the plugin validator for the authoring path, the server parse as the invariant for programmatic construction.

Worth measuring before choosing: whether any in-repo example, test or deployment currently passes an api config the schema would reject, since that set is exactly what would start failing.

Scope note

#11546 does not address this and does not depend on it. That card removed a || enriched.info.version fallback whose only trigger was this same unvalidated falsy value; it deliberately serves the configured value as written so a misconfigured deployment stays visible rather than being papered over at one of the two faces. Fixing this one would make that fallback's trigger unreachable through the authoring path, which is the correct order — the fallback should not be the thing enforcing the contract.

[os-zhuang]

Symbol-name correction — the finding itself is confirmed, only the identifier is off.

The schema exported at packages/spec/src/api/plugin-rest-api.zod.ts:625 is RestApiPluginConfigSchema, not PluginRestApiSchema. The file name (plugin-rest-api) got transposed into the symbol; there is no PluginRestApiSchema anywhere in the repo, so a reader who greps the name in this card's title dead-ends.

Everything else here holds, verified at origin/main e3f056fc — line 639 is exactly what the card says:

version: z.string().default('v1').describe('API version identifier'),

A bare z.string() with a default, so '' is schema-valid, and .default() only fires on undefined.

⚠️ Worth recording how this correction arose, because the near-miss is the useful part. Reviewing PR
#11641 I grepped for PluginRestApiSchema, got zero hits, found a different schema —
RestApiConfigSchema in packages/spec/src/api/rest-server.zod.ts:52, which does carry
.regex(/^[a-zA-Z0-9_\-\.]+$/) — and concluded the "bare z.string()" claim was false on the
merits. It was not: those are two different schemas for two different config objects, and I compared
the wrong pair.

The zero-hit that started it was never properly checked either. I "reverse-checked" the grep with
PluginRest in packages/spec/src — a substring of the very term under test, which can only
return zero when the term is absent. It confirmed nothing. A real reverse-check needed a term
independently known to be in that directory.

⇒ Two things for whoever picks this up: the identifier above, and the fact that RestApiConfigSchema
constrains a sibling version field with a regex while RestApiPluginConfigSchema does not. That
divergence may be relevant to which of the two candidate fixes this card lands on, or it may be
irrelevant — ⛔ this seat is not grading it, only recording that the two schemas disagree.

---

Generated by Claude Code

[os-zhuang]

⚠️ My earlier comment (5393957346) is superseded — ignore its "symbol-name correction".

It told the filer the symbol should be RestApiPluginConfigSchema (plugin-rest-api.zod.ts:625).
That was true of the line this card cited at the time, and it is wrong for the card as now
rewritten — and the underlying reasoning in that comment was wrong too.

Measured at origin/main cad8b42f, the schema that actually governs api.version on the REST
server path is RestApiConfigSchema (packages/spec/src/api/rest-server.zod.ts:52), reached by:

rest-api-plugin.ts:77 api?: RestServerConfig
rest-server.zod.ts:485 api: RestApiConfigSchema.optional()
rest-server.zod.ts:164 type RestApiConfig = z.input<typeof RestApiConfigSchema>

RestApiPluginConfigSchema's bare z.string() is real but inert on this path — it is referenced
nowhere outside its own file, its own test, and the api-surface manifest.

So the card's current framing is the right one and is stronger than the original: the spec
does constrain the field (.regex(/^[a-zA-Z0-9_\-\.]+$/), which refuses ''), and the server
never applies it because both hops in are casts and the plugin declares no configSchema for the
kernel validator. Declared-not-enforced, with '' and 'v1/beta' both admitted.

For the record, since it bears on how much weight to give a PM comment on this card: I reached the
wrong conclusion twice here — first by grepping a symbol, getting a zero I "reverse-checked" with a
substring of the term under test (which can only ever return zero), then by over-correcting onto
the wrong schema. The dev seat measured the chain and declined to defer, which is what settled it.

---

Generated by Claude Code

[os-zhuang]

Triage: lands at the REST server config seam (parse instead of cast where RestApiConfigSchema enters @objectstack/rest) → domain:cli, type Bug, pm:queue. Rationale: the schema declares a regex the runtime never runs — declared≠enforced restoration, no design question about the vocabulary itself (api.version: '' mounting at /api// is indefensible under the declared constraint).

⚠️ Clause-② heads-up for the claiming seat: enforcing the declared regex narrows the accepted config set — configs that boot today start being refused loudly. That is contract accept/reject behaviour change ⇒ Clause-②: yes in the claim, contract-review tier per the standing rule, and the changeset must name the newly-refused shapes. Check whether any in-repo example/preset config relies on the unvalidated path before flipping.

---

Generated by Claude Code