[nicolaj0]

Summary

Closes #9885 (labelled contribution-welcome).

POST /api/applications and PATCH /api/applications/:id accept customClientMetadata through a plain z.object(...), which strips unknown keys. A misspelled or unsupported key was therefore answered 200 and silently dropped: a typo in refreshTokenTtlInDays from a script looked applied while the sessions kept the default TTL.

This PR makes the API input guard strict on that object. An unknown key is now rejected with a 400 guard.invalid_input whose message names the key:

{ "code": "guard.invalid_input", "message": "...", "data": [{ "code": "unrecognized_keys", "keys": ["refreshTokenTtlInDay"], "path": ["customClientMetadata"] }] }

Why only the API guard

• customClientMetadataGuard is also the row guard (Applications.guard / createGuard) and is used by oidc/utils.ts through .shape. Making it strict there would make a stored application with a removed legacy key fail to parse, so the override lives in applicationCreateGuard (packages/schemas/src/types/application.ts), which applicationPatchGuard derives from. Same reasoning as the comment on passwordExpirationPolicyGuard.
• Console is not affected: it only sends known keys, and koaGuard overwrites responses with the parsed value, so a legacy key stored in a row is never echoed back to a client that would then re-send it on PATCH.
• SAML application guards pick only name, description and customData, so they are untouched.

Tests

• Two integration tests in application.test.ts: an unknown key is rejected on create and on update, and the update leaves the stored value unchanged.
• Verified locally against the rebuilt @logto/schemas: create/patch with refreshTokenTtlInDay ⇒ unrecognized_keys, patch with a valid key ⇒ ok, row guard with an extra legacy key ⇒ still parses. tsc for schemas, core and integration-tests, eslint and prettier are clean on the changed files.

Changeset

@logto/schemas + @logto/core patch: callers that relied on the lenient behaviour now get a 400 instead of a silent drop, so this is called out as a behaviour change.

🤖 Generated with Claude Code

[simeng-li]

Since this input is now .strict(), the set of keys in customClientMetadataGuard becomes part of the API contract. Could you add a note for future maintainers, ideally right on customClientMetadataGuard in packages/schemas/src/foundations/jsonb-types/oidc-module.ts, since that's where keys get added and removed:

• Never remove or rename an existing key. A client that still sends it would go from 200 to 400. Keep it and mark it @deprecated instead, the way refreshTokenTtl is handled.
• New keys must be .optional(). A required key would reject every existing create/update payload that sends customClientMetadata without it, and PATCH replaces the whole object.

Also, the last sentence here ("legacy rows carrying removed keys still parse") reads as though removing keys is a supported path, which is the opposite of what we want now. Could you reword it to point at the rule above?

[nicolaj0]

Done in 9e729a1. The two rules (never remove or rename a key, mark it @deprecated like refreshTokenTtl; new keys must be .optional() since PATCH replaces the whole object) now sit in a doc comment right on customClientMetadataGuard, and the comment on applicationCreateGuard no longer mentions legacy rows: it says the keys are part of the API contract and points to those rules.

[simeng-li]

This goes into the user-facing changelog, so I'd drop the row-guard wording (no key has ever been removed from this guard anyway). Also, the guard.invalid_input message itself is generic; the key name is in the error data. Suggest:

An unknown key is now rejected with a 400 guard.invalid_input error whose data lists the key. Existing applications are not affected.

[nicolaj0]

Done in 9e729a1, using your wording.

[simeng-li]

The generated OpenAPI spec won't show that customClientMetadata now rejects unknown keys, because zodTypeToSwagger doesn't emit additionalProperties: false for a strict object. Could you add a short customClientMetadata description to the POST /api/applications and PATCH /api/applications/{id} request bodies in application.openapi.json saying unknown keys return 400?

[nicolaj0]

Thanks for the review. OpenAPI: added a customClientMetadata description to the POST /api/applications and PATCH /api/applications/{id} request bodies stating that unknown keys are rejected with a 400 guard.invalid_input whose data lists the key (9e729a1).