Reject a non-UUID guid before it becomes a file id

[benpeter]

What

A source PUT or POST can send a guid form field. When the object has no stored
file id, that guid becomes the file id. The file id is a path segment in the
reserved .da-versions key space.

The old code took the guid as is. A slash, a .da-versions segment, or any
non-UUID value became the file id and shaped the keys. Now the guid must be a
plain UUID. A file id read back from stored metadata is also untrusted. An unsafe
stored id no longer builds reserved keys.

Change

• Add isValidId to src/storage/version/paths.js. It allowlists the UUID
  shape. It returns true only for a plain UUID.
• In putObjectWithVersion, reject a supplied guid that fails the allowlist
  with a 400. This runs before the guid becomes the file id.
• Add isSafeId to src/storage/version/paths.js. Apply it to the file id from
  stored metadata. Stored metadata is untrusted. An id written before this check
  could carry key steering characters. The storage transport turns the key into a
  URL. That URL collapses a dot or double dot segment, treats a backslash as a
  separator, decodes a percent escape, and strips whitespace. isSafeId refuses
  an id that uses any of those. It also refuses a slash or a .da-versions
  segment. It is weaker than the UUID allowlist on purpose. A benign legacy
  single-segment id still works.
• Document the optional guid field, its UUID constraint, the 400 response, and
  the 409 mismatch response on the source API (docs/openapi/schemas.yaml,
  docs/openapi/source-api.yaml). Regenerate docs/index.html.

A missing or empty guid still falls back to a generated UUID. Normal writes do
not change. A document with a benign stored id still works.

Testing

• Unit tests cover the rejected guid shapes: slash, leading slash,
  .da-versions segment, non-UUID string, and a UUID with a trailing path. A
  valid UUID is still accepted and stored as the document id.
• Unit tests cover isValidId and isSafeId directly. A regression suite
  refuses an unsafe stored id (slash, .da-versions segment, bare .da-versions,
  a single or double dot segment, a backslash, and a percent-encoded dot segment)
  with a 400 and writes nothing. A benign legacy single-segment stored id,
  including one that contains a dot, still updates.
• Integration tests confirm a source PUT with a crafted guid returns 400. A
  source PUT with a valid UUID guid returns 201 with the id in the X-da-id
  header.
• An OpenAPI contract test asserts the source schema and the PUT and POST
  descriptions keep documenting the guid field, the UUID constraint, and the
  400 and 409 responses.
• npm test, npm run lint, and npm run test:it all pass.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[adobe-bot]

🎉 This PR is included in version 1.13.0 🎉

The release is available on:

• v1.13.0
• GitHub release

Your semantic-release bot 📦🚀