parse-stack-next 5.8.0 → 5.8.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ca6cbc923754826337ad1abf67ad900d15ac483cef4d03536862923491eaf64c
-  data.tar.gz: 3c5c10805ec33190f755e8a745c4b6cbac2fd2bd458f1032b57e125e86ed6e73
+  metadata.gz: d49d6371c1e6873ea48401f789d9087e23870530ae405bf2629ea9db67360995
+  data.tar.gz: 9589dfb1ec150a78d527c6ad0097a3ee4263701b104baf7b54afb73e73ec3bdf
 SHA512:
-  metadata.gz: a34e92d57d8cfbd3ba87bbe21baad8995a7dd1f3aba09a980ab3ed364ab961e5f8934a6bd73f4c097895cdfc5a427e5e4b3c01e0405c6647731384bbb9fd2747
-  data.tar.gz: f7898ed1327fb0f316bda290f36b1cf8a4ab74d4d510243b276e408dd7d7d95e1e97e96e13d5c784b39c83c262574b57c34ce8b4d15983603e19194d477883fe
+  metadata.gz: 22998b27d0f277d174759d29c5087675628eee3a9a24ed460c82c87deda6a28252ed1d1ad78daee9a2438b2a7b1c4f8995197450d9eb5922b5689e58bda52bdb
+  data.tar.gz: 5ef7ef2f07269ca95bbd985c806250ca7d93d02c7c6bccd83a9d72a0c9a57b990bac63e977ddfbd1c601481562fb12d5c0272639ec415787cef0cc76fc4dd3c0

data/CHANGELOG.md

@@ -1,5 +1,635 @@
 ## parse-stack-next Changelog
 
+### 5.8.2
+
+A security and correctness patch. No new features beyond the `session:`
+arguments and the cache opt-in the fixes need; intentional master-key and
+analytics access is unchanged. Outcomes that change are listed under
+Behavior Notes.
+
+#### Transport and MCP authentication
+
+- **FIXED**: A whitespace-only MCP API key (`api_key: "   "`,
+  `MCP_API_KEY="   "`, or a non-breaking-space key) now counts as no key.
+  Before, it passed the check that refuses a non-loopback bind without a key
+  and then disabled request authentication, leaving a public MCP endpoint
+  open. The configured key and the provided `X-MCP-API-Key` header are
+  stripped the same way, an explicit blank `api_key:` no longer hides
+  `MCP_API_KEY`, and a non-loopback bind with a key shorter than 16
+  characters warns.
+- **FIXED**: HTTPS and WebSocket scheme checks parse the URL and compare the
+  scheme case-insensitively. Before, `HTTP://` passed `require_https`,
+  `HTTPS://` with TLS verification turned off was not refused, and `WS://` got
+  past the plaintext LiveQuery guard.
+- **FIXED**: The TLS guard also refuses `ssl: { verify_mode:
+  OpenSSL::SSL::VERIFY_NONE }`, `ssl: { verify_hostname: false }`, and a
+  `Faraday::SSLOptions` with verification off on an https server URL. Before,
+  only a Hash with `verify: false` was caught. A `faraday:` option passed as
+  `Faraday::ConnectionOptions` gets the same TLS and proxy guards as a Hash,
+  and any other non-Hash value raises.
+- **FIXED**: `Parse::LiveQuery::Client.new` validates an explicit or
+  configured URL, as `Parse.setup` does. Plaintext `ws://` to a routable host
+  is refused without `allow_insecure`, and a URL whose scheme is not `ws`,
+  `wss`, `http`, or `https` raises `ArgumentError`. **CHANGED**: an
+  `https://` LiveQuery URL is used as `wss://` (it used to be opened without
+  TLS), and an `http://` URL as `ws://` under the same loopback rule, each
+  with a one-time deprecation warning.
+- **FIXED**: `Parse::File` URLs hydrated from Parse JSON no longer skip the
+  `trusted_url_hosts` check when the scheme is uppercase (`HTTPS://`), the
+  URL has leading whitespace, or the URL is malformed (`https:host`,
+  `https:\\host`, `https:///host`), all of which browsers resolve to the
+  remote host. Under
+  `untrusted_url_policy = :raise` or `:strip`, a malformed http(s) URL is
+  treated as untrusted. `force_ssl` upgrades `HTTP://` URLs too. Hydration
+  reads a URL the way a browser does (tabs and newlines removed, leading
+  control characters stripped), checks scheme-relative values (`//host`,
+  `\\host`) against `trusted_url_hosts`, and treats `javascript:`, `data:`,
+  and other non-http(s) URLs as untrusted.
+- **NEW**: `Parse::File.trust_legacy_tfss_on_any_host = false` requires
+  `tfss-` file URLs to come from `trusted_url_hosts`. The default (`true`)
+  keeps accepting them from any host.
+- **FIXED**: `Parse::Response#inspect` prints only the status and the
+  result's shape, and `#to_s` replaces credential fields with `[FILTERED]`:
+  session tokens, passwords, `authData`, access and refresh tokens, API,
+  master, client, and JavaScript keys, MFA recovery codes and secrets
+  (`recovery`, `recoveryCodes`, `secret`, `authDataResponse`), and
+  storage-form columns (`_session_token`, `_hashed_password`,
+  `_email_verify_token`, `_perishable_token`, `_password_history`,
+  `_auth_data_*`). The same list drives log redaction, which also covers
+  header-shaped text (`X-Parse-Master-Key: ...`, `X-Parse-REST-API-Key`,
+  `X-Parse-Session-Token`, `X-Parse-Javascript-Key`, `X-Parse-Client-Key`,
+  `X-Parse-Webhook-Key`, `Authorization: Bearer ...`). `to_s` also filters
+  credential text inside string values (`password=...`), and its error form
+  redacts the request line and error text. Text patterns run on string values
+  before encoding, and a quoted value is redacted whole (spaces included,
+  and after an auth scheme: `password="a b"`, `Authorization: Bearer "x"`),
+  so the output stays valid JSON; log redaction of JSON bodies works the same
+  way. `#result` is unchanged.
+- **IMPROVED**: Webhook endpoint registration accepts the scheme in any case
+  and warns when an `http://` endpoint on a routable host would carry the
+  webhook key in cleartext.
+
+#### Batches and transactions
+
+- **FIXED**: A batch keeps each write's credentials. Parse Server runs every
+  sub-request of a `POST /batch` under that call's own credentials and ignores
+  per-sub-request headers. Before, `Array#save`, `Array#destroy`,
+  `Parse.batch`, and `Parse::Object.transaction` sent everything through the
+  default client, so a write built for a user session (a class bound to
+  `Parse.client.become(token)`, or a `Parse::Request` with `session_token:` /
+  `use_master_key: false`) ran with the master key and bypassed ACLs and CLPs.
+  Writes are now sent through their own client and options, and a batch with
+  mixed credentials goes out as separate calls with responses in request
+  order. Credentials resolve exactly as for a single request: a request's
+  `session_token:` / `use_master_key:` options, its `X-Parse-Session-Token`
+  header, and its master-key suppression header (which keeps the master key
+  off even with `use_master_key: true`). The same rules apply to direct
+  `Parse::Client#batch_request` calls. A client chosen explicitly
+  (`BatchOperation#client=`, or the client `batch_request` is called on) is
+  used for every request, as `Parse::Client#request` uses it for a single
+  request; an object's class client applies only to implicit batches
+  (`Array#save`, `Array#destroy`, `Parse.batch`). A `use_master_key:` that is
+  not exactly `true` or `false` is treated as unset, a `session_token:` that
+  resolves to no token fails closed, and narrowing `batch_request` options
+  (`use_master_key: false`) override a request's own `use_master_key: true`.
+- **FIXED**: `Parse::Object.transaction` runs with its objects' class client.
+  A transaction that mixes credentials raises
+  `Parse::BatchOperation::MixedAuthorityError` before anything is sent,
+  because Parse Server runs a transaction under one credential and it cannot
+  be split. Clients are compared by their credentials (server, application,
+  keys, and bound session), not by object identity, so classes whose clients
+  were configured identically, such as before and after a second
+  `Parse.setup`, still share one transaction. Requests that name their own
+  session token are compared without the master key or bound session, so
+  `transaction(session:)` across clients that differ only in those is sent as
+  one call.
+- **FIXED**: `Array#destroy(session:)` on sessions looks up their tokens and
+  owners as that user, so deleting session ids the user cannot see no longer
+  evicts other users' cached identities or triggers a reset. A session the
+  caller could not read is still treated as deleted when its delete succeeds:
+  its recorded owner is invalidated, or the rate-limited reset applies. A
+  denied or not-found delete of such a row forgets nothing.
+- **NEW**: `Array#save(session:)`, `Array#destroy(session:)`, and
+  `Parse::Object.transaction(session:)` send every write in the call as the
+  given user.
+
+#### Agents
+
+- **FIXED**: A session-token agent whose token could not be resolved when it
+  was built (for example, Parse Server unreachable) is no longer treated as
+  master-key posture by the SDK-side permission checks. The scope is resolved
+  again on first use; if it still cannot be, the call fails with
+  `Parse::Agent::UnresolvedIdentity` (reported as `:access_denied`,
+  `kind: :unresolved_identity`) instead of skipping the CLP check. Parse
+  Server already validated the token on REST calls.
+- **FIXED**: `Parse::Agent#inspect`, `to_s`, and `pp` print a redacted summary
+  and no longer show the session token, the client's keys, the conversation,
+  or the last request and response.
+- **FIXED**: `Parse::Agent#as_json`, `#to_json`, and `#to_yaml`, and the same
+  methods on `Parse::Client`, return a redacted summary, so JSON log
+  formatters and error trackers that serialize an agent or client no longer
+  emit its session token, master key, or REST key.
+- **FIXED**: A sub-agent that holds its parent's session token on the
+  parent's client reuses the parent's resolved scope instead of resolving it again. A failed resolution
+  of a different child token is reported as `Parse::Agent::UnresolvedIdentity`,
+  not as an attempt to widen the parent's scope.
+- **FIXED**: Lazy session resolution, `impersonate`, and `refresh_scope!` are
+  serialized per agent, so a concurrent `impersonate` cannot leave one
+  token's scope bound to another token. A failed lazy resolution is retried
+  after 5 seconds, not on every call. `refresh_scope!` resolves or raises for
+  a session agent instead of returning nil, and an invalid or expired token
+  gets its own error message. `acl_scope` checks and reads the scope under
+  the same lock, and `acl_permission_strings` never returns nil for a
+  session-token agent.
+- **FIXED**: A session agent whose token cannot be resolved records the
+  failure at construction too, so the first use inside the 5-second window is
+  refused without a second lookup, and a token Parse Server rejected is not
+  retried. The lookup runs outside the agent's scope lock, so other threads
+  using the agent are not blocked for a request timeout, and the result binds
+  only if the token is unchanged. A sub-agent reuses its parent's scope only
+  from a token-and-scope snapshot taken under the parent's lock.
+- **FIXED**: `Parse::Client` and `Parse::Agent` refuse `Marshal.dump`
+  (`TypeError`), so a client's master key or an agent's session token cannot
+  land in a marshaled cache or job payload.
+- **CHANGED**: `Parse::Agent#stop_impersonating!` is a no-op on an agent that
+  is not impersonating, instead of dropping a constructor-supplied session
+  token and leaving master-key posture.
+
+#### Response cache
+
+- **FIXED**: Reads made with a session token are no longer served from the
+  response cache. A cached answer was returned without contacting Parse
+  Server, so a revoked session (logout, `Parse::Session#destroy`,
+  `logout_all!`, a password change), or a user who lost a role or row access,
+  kept reading the cached rows until the entry expired. Session reads now
+  always reach Parse Server, whether the session came from `session_token:`,
+  `Parse.with_session`, or a session-bound client. Master-key and anonymous
+  reads are cached as before, and writes made with a session still invalidate
+  cached entries.
+- **NEW**: `Parse::Middleware::Caching.cache_session_requests = true` (or
+  per client, `Parse.setup(cache_session_requests: true)`, which overrides the
+  class default either way) opts back into caching session reads, for apps
+  that accept revocation being bounded by the cache TTL. The
+  `parse.cache.bypass` event includes `cache_tenant`.
+
+#### Regex validation and direct reads
+
+- **FIXED**: A raw `$regex` in a where hash
+  (`Model.query(name: { "$regex" => ... })`, `:field.eq`, `:field.not`,
+  `$elemMatch`, and `:or` branches) goes through the same ReDoS check as
+  `:field.like`. Before, only the regex constraints themselves were checked.
+  Ruby `Regexp` and BSON regex values under `$not`, `$in`, `$nin`, and `$all`
+  are checked too.
+- **FIXED**: Mongo-direct filters and pipelines (`results_direct`,
+  `count_direct`, `Query#aggregate`, `Parse::MongoDB.aggregate` and `find`,
+  Atlas Search and vector filters, LiveQuery `where`, and the agent
+  `aggregate` tool) run every `$regex`, Ruby `Regexp`, BSON regex, and
+  `$regexMatch` / `$regexFind` / `$regexFindAll` pattern through the ReDoS
+  check. Before, only the pattern length was capped. The agent constraint
+  translator applies the same check.
+- **FIXED**: `Parse::RegexSecurity` parses each caller-supplied pattern
+  instead of matching a few substrings. It refuses a group repeated more than
+  once whose body holds a variable-count quantifier (including an optional
+  `?`), an alternation, or a backreference (`(a+)+`, `(a|aa)+$`, `((a+))+`,
+  `(a+){2,}`, `(a+){20}`, `^(a?){100}a{100}$`), inline comments
+  `(?#...)`, extended mode, and patterns it cannot read. Before, several of
+  these shapes passed. Repeats of a single atom (`^.{1,255}$`, `\d{1,100}`)
+  and simple lookarounds (`^(?!test)`) are accepted; the old checker refused
+  them for `:field.like`. Escaped literal patterns
+  built by `contains`, `starts_with`, and `ends_with` get a longer length cap,
+  so long values keep compiling. It also refuses subroutine calls (`\g<1>`,
+  `\g'1'`), more than three unbounded or wide quantifiers in a row with no
+  separating literal they cannot match (`\d+\d+\d+\d+`, `.*a.*a.*a.*a`),
+  and whitespace inside a repeat count (`{ 2,}`), and reads `[:` that is not a
+  complete POSIX class as a literal, as PCRE2 does. A repeated group is
+  allowed when each repeat cannot split its input two ways: fixed
+  alternatives whose first characters differ even ignoring case
+  (`^(foo|bar)+$`, but not `(?i)^(a|Aa)+$`) or a literal
+  separator next to one run that cannot match it
+  (`^[a-z0-9]+(?:-[a-z0-9]+)*$`, `(\.[\w-]+)+`, `([\w-]+\.)+`).
+- **FIXED**: `$regexMatch`, `$regexFind`, and `$regexFindAll` in
+  caller-supplied pipelines require a literal `regex` (a String that is not a
+  field path or variable, a Regexp, or a BSON regex). An expression or
+  `"$field"` operand raises `Parse::PipelineSecurity::Error`
+  (`reason: :regex_not_literal`).
+- **IMPROVED**: Mongo-direct reads (`Parse::MongoDB.aggregate` and `find`,
+  `results_direct`, `count_direct`, Atlas Search, and vector and hybrid
+  search) whose filter or pipeline carries a regex that is not escaped literal
+  text get a server-side `max_time_ms` of
+  `Parse::PipelineSecurity.default_regex_max_time_ms` (5000 ms) when the
+  caller passed none. Set it to nil to turn this off; an explicit
+  `max_time_ms:` always wins. For REST queries, set Parse Server's
+  `databaseOptions.maxTimeMS`.
+- **FIXED**: `Parse::MongoDB.find` raises `Parse::ACLScope::ACLRequired` inside
+  `Parse.without_master_key` instead of reading raw documents unscoped.
+  `Parse::MongoDB.indexes` (metadata only) stays available.
+
+#### Webhooks
+
+- **FIXED**: A webhook request's `master` flag is trusted only when the
+  request is authenticated: the webhook key matched, or a configured
+  signature verified. Under `Parse::Webhooks.allow_unauthenticated` with no
+  signature, a body claiming `"master": true` no longer passes master-only
+  field guards, ACL owner resolution, or handler `payload.master?` checks, and
+  no longer triggers the Ruby-initiated callback dedup, so a forged `_RB_`
+  request id cannot make a write skip model callbacks (including a
+  `before_save` that rejects it). Only a JSON `true` counts as master.
+  `payload.authenticated?` reports whether the request was authenticated, and
+  `payload.claimed_master?` exposes the raw claim; both are for diagnostics
+  only. Signature verification and the authenticated flag come from one read
+  of the signing secret.
+
+#### Behavior Notes
+
+- **Transport.** A LiveQuery `https://` URL is used as `wss://` (and a
+  loopback `http://` as `ws://`) with a deprecation warning; configure the
+  `ws(s)://` URL directly. Other LiveQuery schemes raise. `HTTP://` with
+  `require_https`, and an https server URL with TLS verification disabled
+  (`verify: false`, `verify_mode`, `verify_hostname`, or `SSLOptions`), raise.
+  Loopback hosts for these checks are `localhost`, `127.0.0.0/8`, `::1`, and
+  `0.0.0.0`, parsed as addresses (`127.999.1.1` and `localhost.` are not
+  loopback). A padded MCP API key is enforced without its surrounding
+  whitespace. Hydrated `Parse::File` URLs with an uppercase scheme or leading
+  whitespace are checked against `trusted_url_hosts`; malformed http(s) URLs
+  are refused or stripped under `:raise` / `:strip` and warn under `:warn`,
+  as are non-http(s) schemes (`javascript:`, `data:`, `file:`) and
+  scheme-relative values pointing at an untrusted host.
+- **Printing.** `Parse::Response#to_s` replaces credential-bearing values with
+  `"[FILTERED]"` and `#inspect` no longer shows values; read `#result` (or
+  `#result.to_json`) for raw data. `to_s` may also filter text in string
+  values that looks like a credential (`password=...`). `Parse::Agent` and `Parse::Client`
+  `inspect`, `to_s`, `as_json`, `to_json`, and `to_yaml` print redacted
+  summaries.
+- **Agents.** A session-token agent that cannot resolve its token refuses
+  tool calls that need its permissions. `Agent#acl_scope` can now raise
+  `Parse::Agent::UnresolvedIdentity`, and `acl_scope?` is true for any
+  session-token agent; custom handlers that test `agent.acl_scope` for
+  truthiness should use `agent.acl_scope?`. A sub-agent of an unresolved
+  parent can inherit the parent's token, but one with a different identity
+  raises until the parent's token resolves. A session agent built while Parse
+  Server is unreachable refuses calls for 5 seconds before retrying.
+  Marshaling a `Parse::Client` or `Parse::Agent` raises `TypeError`; store the
+  configuration and build a new client instead.
+- **Response cache.** Queries that set `cache: true` (or run under
+  `Parse.default_query_cache = true`) with a session token no longer get cache
+  hits. Set `cache_session_requests` to `true` (only a literal `true`
+  enables it) to restore the old behavior, and keep `expires:` short if you
+  do.
+- **Regex.** A raw `$regex`, or a `Regexp` in a mongo-direct filter, that the
+  ReDoS check rejects now raises: `ArgumentError` on REST queries,
+  `Parse::PipelineSecurity::Error` (or `Parse::MongoDB::DeniedOperator`) on
+  direct paths. Escaped literal patterns, including those built by
+  `starts_with`, `ends_with`, and `contains`, pass the shape check and get a
+  length cap about twice the normal one. Caller-supplied `$options` accept
+  `i`, `m`, `s`, and `u`; an unknown flag, a non-String value, the extended
+  flag `x`, or a Regexp built with `Regexp::EXTENDED` raises. The agent
+  translator now accepts `s` and `u` and no longer accepts `x`. A pattern with
+  more than three unbounded quantifiers in a row and no literal between them
+  (for example `^\w+\s+\w+\s+\w+\s+\w+$`) is refused; add a literal
+  separator or split the query. A mongo-direct read carrying a non-literal
+  regex and no `max_time_ms` times out after 5 seconds with
+  `Parse::MongoDB::ExecutionTimeout`; pass `max_time_ms:` or set
+  `Parse::PipelineSecurity.default_regex_max_time_ms` to change it.
+- **Direct reads.** Code that calls `Parse::MongoDB.find` inside
+  `Parse.without_master_key` should wrap it in `Parse.with_master_key` or use
+  a scoped read. `Parse::MongoDB.collection` returns raw driver access with no
+  scope and is not refused inside the block.
+- **Batches.** A batch or transaction of objects whose class is bound to a
+  session client now runs as that user, as a single save does. A transaction
+  mixing credentials raises `MixedAuthorityError`, and a non-transactional
+  batch with mixed credentials is sent as several calls. An explicitly chosen
+  batch client (`client=` or the `batch_request` receiver) is used for every
+  request instead of each object's class client.
+  `Client#batch_request` accepts `session_token:` and `use_master_key:`. A
+  blank `session:`, or a user with no session token, raises `ArgumentError`.
+- **Webhooks.** `payload.master?` and `payload.claimed_master?` no longer
+  treat the string `"true"` as master; Parse Server always sends a JSON
+  boolean. Under `Parse::Webhooks.allow_unauthenticated` with no signing
+  secret, `payload.master?` is false even for a master-key request Parse
+  Server forwards, so master-only field guards and handler `master?` checks
+  refuse it, and saves made by the SDK itself run their model callbacks in
+  process and again through the webhook. Configure a webhook key
+  (`PARSE_SERVER_WEBHOOK_KEY` on Parse Server and `Parse::Webhooks.key` in the
+  app) or a signing secret to restore master trust and dedup.
+
+### 5.8.1
+
+A correctness release for webhooks, sessions, associations, queries, search,
+and agent policies. No new defaults and no API changes; every corrected
+outcome is listed under Behavior Notes.
+
+#### Webhooks
+
+- **FIXED**: A client create through a `before_save` webhook whose handler
+  returns `parse_object` now gets the ACL its class policy resolves, exactly
+  as an SDK-side create would. Owner-based policies (`:owner_else_private`,
+  the default, plus `:owner_else_public` and `:owner_but_public_read`) take the
+  owner from the declared `owner:` field, or from the requesting user when that
+  field is empty. Before, a signed-in client got the policy's no-owner
+  fallback (`{}` under `:owner_else_private`) and could not read its own
+  record. A request without a user, or a master-key request, gets the policy
+  fallback. A `_User` class declared with `owner: :self` is owned by the new
+  user, never the requester. An ACL the client sent is kept, and an ACL the
+  handler sets always wins (through `acl=` or mass assignment), even when it
+  equals the class default. A `guard :acl, :master_only` revert on a create
+  returns the ACL to the class policy instead of `{}`. A handler-assigned ACL
+  is written whatever the handler returns (`parse_object`, `true`, `nil`, or
+  a Hash that does not set `ACL` itself).
+- **FIXED**: When a `before_save` handler changes a record, a sub-document the
+  client changed is written back as one-level dotted paths (`"meta.count":
+  {...}`) instead of the whole field, so concurrent writes to other sub-keys
+  survive. A removed sub-key is written as a `Delete`. Dotted keys in a
+  returned Hash are folded into the field or `field.sub` write they belong to,
+  with operators (`Increment`, `Add`, `AddUnique`, `Remove`, `Delete`) applied
+  rather than stored. Hash keys may use Ruby names.
+
+#### Sessions and master-key scope
+
+- **FIXED**: Deleting `Parse::Session` or `Parse::User` objects, one at a time
+  or with a batch `Array#destroy`, drops their identity-cache entries when the
+  delete succeeds or reports the row already gone. A denied delete leaves the
+  cache alone. A session that does not carry its token or owner (built from
+  its objectId alone, fetched without the master key, or fetched with `keys:`
+  leaving them out) has them looked up first, in one query per batch: with the
+  master key when the client has one, otherwise with the delete's `session:`.
+  A lookup that finds no row leaves nothing to forget; only a lookup that
+  fails resets the client's identity cache, at most once every 5 seconds per
+  client. When the lookup finds no row, the delete uses the owner recorded
+  when a `_Session` query or `Parse::Session.session` last fetched that
+  session through the same client (only the user id, never the token, in a
+  store separate from the identity plane,
+  `client.authorization.session_owner_cache`). Without one, a batch delete
+  that applied or reported the row gone falls back to the rate-limited reset;
+  a denied delete never resets, and a single `destroy` never resets. The
+  looked-up token is used only for the delete, is never kept on the object,
+  and never enters the response cache. A token resolution in flight when an
+  invalidation lands, in this process or, on the Redis identity plane, in any
+  other, does not cache its answer: the resolver checks a shared invalidation
+  marker before and after writing and evicts its own write when the marker
+  moved.
+- **FIXED**: `Parse::User#signup!`, signup on save, and `upgrade_anonymous!`
+  store `created_at` / `updated_at` as `Parse::Date` values. Reading
+  `updated_at` on a newly signed-up user no longer marks it dirty.
+- **FIXED**: Inside `Parse.without_master_key`, an explicit `master: true`
+  passed to `Parse::MongoDB.aggregate`, `Parse::ACLScope`, `Parse::Query`
+  direct reads, vector and hybrid search, Atlas Search, or agent tools for
+  master-key agents no longer runs as master. The call runs in the public
+  scope, as the REST request does once the block strips its master key, and
+  the `parse.mongodb.aggregate` notification reports `master_dropped: true`.
+  The SDK's own metadata reads keep the master key without lifting the block:
+  the class schema and role graph read to enforce a scope, index statistics,
+  and the Atlas Search index listing. Before, a schema read refused inside the
+  block was cached and denied every scoped mongo-direct read of that class,
+  for all callers, for 5 seconds. `Parse::AtlasSearch.faceted_search` raises
+  `FacetedSearchNotACLSafe` inside the block, because its bucket counts are
+  not ACL-filtered. The metadata marker rides only on the outgoing request
+  copy, never on `response.request` or an error's request. A schema read that
+  fails inside the block is retried at most every 2 seconds there. A LiveQuery
+  admin client that first connected inside the block keeps withholding its
+  master key on every reconnect until `allow_master_key_connection!`.
+
+#### Agent policies
+
+- **FIXED**: A sub-agent's `tools:` and `methods:` filters now only narrow its
+  parent's, as `classes:` already did. A child `tools: { only: }` is
+  intersected with the parent's allowlist and `except:` sets are unioned; for
+  `methods:` the parent's filters stay in force alongside the child's. Before,
+  the child's filter replaced the parent's, so a sub-agent could enable a tool
+  or `agent_method` within its tier that the parent was not given. A child
+  `only:` list with nothing its parent allows raises `ArgumentError` at
+  construction.
+- **FIXED**: A sub-agent built with `parent:` uses its parent's approval gate,
+  read at call time, unless given its own. Before, it fell back to
+  `NullGate`, so a sub-agent built inside an MCP `tools/call` ran tools in
+  `require_approval_for` tiers without approval.
+- **FIXED**: Qualified `methods:` entries compare the class by its Parse class
+  name, so `"User.x"` and `"_User.x"` (and the `Role`, `Session`, and
+  `Installation` aliases) match whichever spelling the entry or the
+  `call_method` caller uses. Before, `methods: { except: ["_User.x"] }` could
+  be bypassed by calling the method on `"User"`.
+- **FIXED**: A sub-agent can no longer turn on `master_atlas` when its parent
+  does not have it. `Parse::Agent.new(parent: scoped_parent, master_atlas:
+  true)` raises `ArgumentError`; before, the child's `atlas_faceted_search` ran
+  with master-key semantics and returned every row under the parent's scoped
+  identity. Omitting `master_atlas` still inherits, and `false` still drops
+  it.
+- **FIXED**: The MCP dispatcher snapshots and restores an agent's own approval
+  gate, so driving a sub-agent through `tools/call` no longer pins its
+  parent's gate onto it. Assigning `approval_gate = nil` makes a sub-agent use
+  its parent's gate again.
+- **FIXED**: Qualified `methods:` entries may name a model by its Ruby
+  constant (`"Artist.purge"` for a class whose `parse_class` is `"Musician"`)
+  and are compared by Parse class name, so such an `except:` entry is no
+  longer bypassed through the Parse class name. An entry whose class resolves
+  to no loaded model warns at construction.
+- **IMPROVED**: The `parse.agent.tool_call` audit payload adds
+  `methods_layers` whenever a sub-agent inherits a `methods:` filter
+  (including a single parent layer), and `describe[:methods][:layers]` lists
+  every `methods:` filter in force, parent first.
+
+#### Associations
+
+- **FIXED**: `add!`, `add_unique!`, and `remove!` on a
+  `has_many through: :array` collection take the array Parse Server returns,
+  as plain array properties already did. A stale local copy is corrected,
+  objects already fetched locally are kept, and the field is not marked
+  changed. The array is adopted only when every entry is a pointer to the
+  declared class; otherwise the operation is applied locally.
+- **FIXED**: Saving a relation collection on its own (`owner.likes.save`)
+  sends the staged additions and removals and returns whether they were
+  applied. Before, it silently sent nothing.
+- **FIXED**: `Parse::Object#clear_changes!` (also called by `reload!`) drops
+  a relation's staged additions and removals and clears array collection
+  dirty state. Before, discarded relation changes were sent with the next
+  change to that relation. A fetch (`fetch!`, partial fetch, autofetch, with
+  or without `preserve_changes:`) keeps a relation's staged additions and
+  removals and leaves the relation marked changed, including when the response
+  carries the relation's descriptor, so the next save sends them.
+  `rollback!` drops a relation's staged additions and removals too, including
+  after a fetch.
+- **IMPROVED**: `RelationCollectionProxy#save` accepts `session:` to send the
+  staged operations as a given user (`nil` for no session token). Relation
+  writes on an owner whose objectId was assigned client-side during a create
+  are staged rather than sent until the create returns.
+- **FIXED**: Atomic relation operations (`add!` / `remove!` on a
+  `through: :relation` collection) write to the relation's Parse column when
+  its name differs from the Ruby name (`has_many :liked_items` maps to
+  `likedItems`, or a relation declared with `field:`). Before, they targeted
+  the Ruby name.
+
+#### Queries
+
+- **FIXED**: An OR whose branch has no constraints now matches every row.
+  Previously `query | Model.query` and `Parse::Query.or(query, Model.query)`
+  dropped that branch and returned only the other side. An empty receiver of
+  `|` still starts a new OR, as `or_where` does, so
+  `[q1, q2].reduce(Model.query, :|)` builds `q1 OR q2`.
+- **FIXED**: `Model.query(:or => [{...}, {...}])` builds a `$or` group ANDed
+  with the query's other constraints, instead of a constraint on a literal
+  field named `or`. Branches can be constraint hashes, `Parse::Query` objects
+  of the same class, or arrays of constraints.
+- **FIXED**: A constraint that needs the aggregation pipeline or mongo-direct
+  (`readable_by`, `:ACL.readable_by`, `:field.array_size`, the mongo-direct geo
+  operators) raises `ArgumentError` inside an OR (`:or`, `or_where`, `|`,
+  `Parse::Query.or`). Before, the branch was emitted as `{}` and matched every
+  row, or lost part of its conditions, including in push targeting, which
+  could reach every installation.
+- **FIXED**: `Parse::Query#clone`, `|`, `or_where`, `Parse::Query.or`, `:or`
+  branches (including Hash branches with `session:` / `use_master_key:` keys
+  or nested scoped queries), and subqueries (`$inQuery`, `$notInQuery`,
+  `$select`, `$dontSelect`) keep the query's authority and application:
+  session token, a session-bound client from `Parse::Client#become`, scoped
+  user or role, master-key flag, read preference, and the Parse application
+  the query targets. Queries combined this way must run under the same
+  authority against the same application. An unscoped query takes the
+  other's authority, and different authorities or applications raise
+  `ArgumentError`. Before, a session combined with `scope_to_user` ran as the
+  scoped user, a `become`-client query composed into an OR ran as the master
+  key, a scoped subquery ran under the outer query's master key, and a clone
+  could send one application's session token to the default application.
+  Changing the authority or client of a combined query raises and leaves the
+  query unchanged. A combined query re-checks its authority before it runs,
+  and explicit auth passed to `results_direct`, `count_direct`,
+  `distinct_direct`, or `atlas_search` must match it.
+- **FIXED**: LiveQuery subscriptions and push targeting refuse constraints that
+  only the aggregation pipeline or mongo-direct can run (`array_size`,
+  `set_equals`, `not_empty`, `elem_match`, `readable_by`, mongo-direct geo
+  operators). Before, those constraints were dropped and the subscription or
+  push reached a wider audience. A subquery with such a constraint is also
+  refused, where it used to match every row. `Parse::Query#subscribe` and
+  `client.subscribe(query)` run under the query's own session or `become`
+  client, and such a subscription is refused with `ArgumentError` when the
+  LiveQuery client targets a different Parse application id than the query,
+  so one application's session token is never sent to another application's
+  LiveQuery server.
+- **FIXED**: A field repeated in `order` is sent once, at its first position
+  with the last direction given, matching what MongoDB applies on direct
+  reads. String forms such as `"-title"` are parsed as descending, so they
+  deduplicate too, and the direct `$sort` stage sorts on the real field.
+  `order("title,-plays")` is parsed as two fields.
+- **FIXED**: A bare objectId compared to a declared pointer field
+  (`Song.query(:artist => "abc123")`, `:artist.ne`, `:artist.in`) now matches
+  on REST, in `Parse::Push` targeting, and in LiveQuery subscriptions from
+  `Parse::Query#subscribe`, `Model.subscribe`, and `client.subscribe(query)`.
+  Equality and `$in` used to return no rows and `$ne` every row, while direct
+  and aggregate reads already matched. The new
+  `Parse::Query#compile_rest_where` returns the where clause in that form.
+
+#### Search
+
+- **FIXED**: Atlas Search (`Parse::AtlasSearch.search`, `search_with_stage`,
+  `autocomplete`, `Parse::Query#atlas_search`) and native hybrid search apply
+  the CLP `pointerFields` / `readUserFields` ownership constraint before the
+  page is cut. For native hybrid, the lexical input filters before its
+  per-input `$limit`, and the fused result is filtered again before the final
+  `$limit`. Rows used to be filtered after the page was cut, so when the
+  top-ranked hits belonged to other users a scoped caller got a short or empty
+  page. Inaccessible rows are still never returned.
+- **IMPROVED**: `Parse::VectorSearch.search` and native hybrid search enforce
+  the `pointerFields` ownership constraint server-side across the whole
+  candidate window. When every owner field is declared as a scalar pointer
+  (`belongs_to`) and its storage path (`_p_<field>`) is a `type: "filter"`
+  field of the vectorSearch index, the constraint also goes
+  into `$vectorSearch.filter`, so other users' rows no longer use up the
+  candidate window. The prefilter is used only while the index is READY and
+  serving its latest definition. If Atlas refuses it (for example mid-rebuild),
+  the search reruns once without it and skips it for the index cache TTL. A
+  failed index lookup is also remembered for that TTL.
+
+- **FIXED**: A `$vectorSearch` refusal caused by the caller's own
+  `vector_filter` on an unindexed path no longer switches off the owner
+  prefilter for every caller on that index or clears the index cache; only a
+  refusal naming an owner `_p_<field>` path does. Native hybrid search uses
+  `Parse::VectorSearch.default_index` when the vector branch names no index.
+
+#### Documentation
+
+- **FIXED**: README and query YARD examples use `:field.pointer_id` and
+  `:field.array_size`, the names the DSL has used since 5.8.0.
+
+#### Behavior Notes
+
+- An OR that includes an unconstrained branch now returns every row. The one
+  exception is an empty receiver of `|`, which starts the OR. Code that passed
+  an empty query for "no filter" should leave that branch out. `:or => []`
+  matches no rows.
+- A pipeline-only constraint inside an OR now raises `ArgumentError`. Apply it
+  outside the OR, or run the branches as separate queries.
+- Combining queries that run under different authorities or against
+  different Parse applications now raises `ArgumentError`. That covers OR
+  composition, `:or` Hash branches, and subqueries, and includes different
+  session tokens, a session against `scope_to_user` / `scope_to_role` / the
+  master key, and different scoped users or roles. Setting a new session
+  token, master-key flag, scope, or client on a query that took its authority
+  from another query also raises, as does passing different explicit auth to
+  a direct or Atlas terminal. Query-shaping options (`limit`, `order`, `keys`,
+  `skip`, `include`) inside an `:or` branch raise.
+- LiveQuery subscriptions, push targeting, and subqueries with pipeline-only
+  constraints raise `ArgumentError`. Subscribing to a `scope_to_user` /
+  `scope_to_role` query, or passing a `session_token:` that differs from the
+  query's session, raises.
+- REST queries, LiveQuery subscriptions, and push targeting that compare a
+  bare objectId to a declared pointer field now return the matching rows.
+  Undeclared fields are unchanged. If a model declares `belongs_to` for a
+  field whose server column holds a plain String, a bare string compared to
+  that field is now sent as a Pointer and stops matching those values;
+  declare such a field as a `:string` property instead.
+- Code that relied on `master: true` keeping master authority inside
+  `Parse.without_master_key` should wrap that call in `Parse.with_master_key`.
+  A dropped `master: true` raises `ACLRequired` under either
+  `Parse::ACLScope.require_session_token` or
+  `Parse::AtlasSearch.require_session_token`, with a message naming the block,
+  and no longer emits the no-ACL banner. The role-graph helpers
+  (`users_in_role_subtree` and related) raise `ACLRequired` for
+  `master: true` inside the block; pass `as:` instead.
+- A LiveQuery connection that already connected with the master key outside
+  `Parse.without_master_key` stays elevated for subscriptions made inside the
+  block, because Parse Server authorizes per connection; the SDK warns.
+- `Parse.without_master_key` guards against accidental master-key use and is
+  not an isolation boundary.
+- `Parse::Role.all_for_user` and `Parse::Role#all_parent_role_names` without
+  `master:` or `as:` return the full role closure inside
+  `Parse.without_master_key`, because the role graph is read as SDK metadata.
+- `Parse::Session._preload_identity_for_destroy!` and the
+  `_after_batch_destroy` hooks are now private.
+- A session deleted elsewhere whose owner this process never recorded keeps
+  resolving until the next rate-limited reset or `identity_cache_ttl`.
+- A custom identity plane gets the cross-process revocation-race guarantee by
+  implementing `invalidation_nonce` and `bump_invalidation_nonce`, as the
+  built-in Redis plane does. One with generation counters only is covered for
+  single-token and per-user invalidations, but a lookup racing another
+  process's full reset is bounded by `identity_cache_ttl` when the plane's
+  `clear` also deletes its counters.
+- A sub-agent's `tools:` or `methods:` `only:` list that leaves nothing once
+  the parent's `only:` and `except:` lists apply now raises `ArgumentError`.
+  An explicitly empty `only: []` is accepted. A sub-agent passing
+  `master_atlas: true` under a parent without it raises `ArgumentError`.
+- Parse Server sends a `before_save` webhook only the resulting value of a
+  dotted operator. When the handler changes the record, the SDK writes back
+  changed sub-keys one level deep and deletes removed ones by path. Two
+  concurrent writes inside the same sub-key (including deeper paths under it)
+  can still overwrite each other, an array is written whole, and a changed
+  sub-key carrying a typed value (Date, Bytes, Pointer) makes the whole field
+  be written. A client's whole replace of a sub-document becomes a merge. The
+  save response reports the dotted keys; the JavaScript SDK applies them, and
+  other clients may need a fetch. A handler operator that cannot be folded,
+  or two conflicting dotted keys from the handler, fail the save with an
+  error.
+- A `before_save` handler that returns `true`, `nil`, or a Hash keeps the
+  client's write as sent, so a client create without an ACL through such a
+  handler is stored public read and write, as before, unless the handler
+  assigns an ACL on `parse_object`.
+- Saving a relation collection on its own sends removals and additions as two
+  requests. If the second fails, the first stays applied and the unsent
+  operations stay staged.
+- Owner fields stored as arrays of pointers, undeclared, or not filter-indexed
+  get no `$vectorSearch` prefilter. Vector search then fills results only from
+  its existing candidate window.
+- A custom identity cache with neither `invalidate_value` nor generation
+  support (`generation`, `generation_current?`, `bump_generation`) only
+  expires a user's tokens at `identity_cache_ttl` after a password change,
+  account deletion, `logout_all!`, or a batch destroy of sessions.
+
 ### 5.8.0
 
 #### Breaking Changes