parse-stack-next 5.8.1 → 5.8.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: de8e9c2d24346754146f36a8c24b272840456010e08bf86f71b11d38741abad8
-  data.tar.gz: 83df07a458c9e00cae15f63fe12d4e8c19bc6913f60b297e1fa402985b2073ce
+  metadata.gz: d49d6371c1e6873ea48401f789d9087e23870530ae405bf2629ea9db67360995
+  data.tar.gz: 9589dfb1ec150a78d527c6ad0097a3ee4263701b104baf7b54afb73e73ec3bdf
 SHA512:
-  metadata.gz: ead735d8d48a495293b810f2b6100327869ae68051d9e1aaee87b43d51aeb51b1323e6f29a9b823a40ec0ac15b52bfc91eb838009524239bd7f1f42a63d7e02d
-  data.tar.gz: 0666b77620a76d2b19a81a5a43f3a9cd61f94661568c269ac07e612c71ff25642c4759d93f0e0b7d7370bb3930447f1fa39ed3eb986fa9bf73a63a072009cbb8
+  metadata.gz: 22998b27d0f277d174759d29c5087675628eee3a9a24ed460c82c87deda6a28252ed1d1ad78daee9a2438b2a7b1c4f8995197450d9eb5922b5689e58bda52bdb
+  data.tar.gz: 5ef7ef2f07269ca95bbd985c806250ca7d93d02c7c6bccd83a9d72a0c9a57b990bac63e977ddfbd1c601481562fb12d5c0272639ec415787cef0cc76fc4dd3c0

data/CHANGELOG.md

@@ -1,5 +1,317 @@
 ## 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,

data/README.md

@@ -3069,8 +3069,13 @@ songs.save
 
 # you can also destroy a set of objects
 songs.destroy
+
+# send every write as a specific user (ACL and CLP enforced)
+songs.save(session: user)
 ```
 
+Each write in a batch keeps the credentials it was built for. Parse Server runs a `POST /batch` under one credential, so objects whose classes use clients with different credentials (for example a class bound to `Parse.client.become(token)`; identically configured clients are merged), or raw `Parse::Request`s carrying different `session_token:` or `use_master_key:` options, are sent as separate batch calls, each with its own credentials. Responses still come back in request order.
+
 ### Magic `save_all`
 By default, all Parse queries have a maximum fetch limit of 1000. While using the `:max` option, Parse-Stack can increase this up to 11,000. In the cases where you need to update a large number of objects, you can utilize the `Parse::Object#save_all` method to fetch, modify and save objects.
 
@@ -3131,6 +3136,7 @@ end
 - **Mixed operations**: Support create, update, and delete operations in single transaction
 - **Error handling**: Comprehensive error handling with meaningful exception messages
 - **Object ID assignment**: New objects automatically receive their `objectId`, `createdAt`, and `updatedAt` from the server response after successful transaction
+- **One credential**: A transaction runs with the credentials of its objects' class client, or as a given user with `Parse::Object.transaction(session: user)`. Objects bound to clients with different credentials raise `Parse::BatchOperation::MixedAuthorityError` before anything is sent, because a transaction cannot be split.
 
 ```ruby
 # Transaction with custom retry limit and error handling

data/docs/caching.md

@@ -230,6 +230,38 @@ caching path the two never meet. Three points are worth knowing anyway.
 
 ## Auth scoping of cached responses
 
+### Session reads are not cached by default
+
+A read made with a session token is never read from or stored in the response
+cache unless the application opts in:
+
+```ruby
+Parse::Middleware::Caching.cache_session_requests = true   # every client
+Parse.setup(cache_session_requests: true, ...)            # one client
+```
+
+Only `true` enables it (a `"true"` String from an environment variable does
+not). A client's own `cache_session_requests:` option overrides the class
+default in either direction.
+
+A cached answer is served without contacting Parse Server, so it cannot notice
+that the session was revoked (logout, `Parse::Session#destroy`, `logout_all!`,
+a password change) or that the user lost a role or row access through a change
+this process did not make. With the default, every REST session read reaches
+Parse Server, which checks the token and the current ACLs and CLPs each time.
+Mongo-direct reads, including agent tools that route there, do not go through
+this cache; they resolve the session through the identity plane, whose
+revocation behavior is described in
+[Identity and role caching](#identity-and-role-caching). This
+applies however the session reached the request: an explicit `session_token:`,
+`Parse.with_session`, or a client bound to a session. Master-key and
+anonymous reads cache as before, and writes made with a session still
+invalidate cached entries. Turning the option on trades that guarantee for
+speed: a revoked or narrowed session keeps reading its cached responses until
+they expire, so keep `expires:` short if you enable it.
+
+### The auth discriminator
+
 The cache key carries an auth discriminator, and this is a correctness property
 rather than an optimization.
 
@@ -251,9 +283,9 @@ URL digest is placed before the discriminator, so every auth variant of one
 resource shares a prefix, which is exactly what lets a write invalidate the
 resource for all callers with a single pattern delete.
 
-One consequence worth planning for: a heavily multi-user endpoint produces one
-cache entry per session per URL. Cardinality scales with active sessions, not
-with distinct resources.
+One consequence worth planning for, once session caching is enabled: a heavily
+multi-user endpoint produces one cache entry per session per URL. Cardinality
+scales with active sessions, not with distinct resources.
 
 ## Identity and role caching
 
@@ -703,8 +735,10 @@ Work down this list.
    so deliberately.
 5. Is this a `fetch!` or `reload!`? Those default to write-only mode, which by
    design never reads from the cache. Use `fetch_cache!` to accept a cached body.
-6. Is the caller a different session? Entries are not shared across auth
-   identities, so the first request for each session is always a miss.
+6. Is the read made with a session token? Session reads bypass the cache
+   unless `Parse::Middleware::Caching.cache_session_requests = true`. With it
+   on, entries are not shared across auth identities, so the first request for
+   each session is always a miss.
 7. Is the store process-local? A Moneta memory store behind several workers hits
    only when the same worker handles the repeat.
 8. Has something set `Parse::Middleware::Caching.enabled = false`? That is the
@@ -725,6 +759,7 @@ All events are `ActiveSupport::Notifications`.
 | `parse.cache.store` | the same, plus `duration_ms` |
 | `parse.cache.delete` | the same, emitted on an invalidating write |
 | `parse.cache.error` | the same, plus `error` (the exception class name only) |
+| `parse.cache.bypass` | the same, plus `reason: :session` for a session read kept out of the cache |
 | `parse.cache.evict` | `pattern_digest`, `deleted`, `duration_ms` |
 | `parse.synchronize_create.acquired` | `key_digest`, `wait_ms` |
 | `parse.synchronize_create.contended` | `key_digest`, `elapsed_ms` |

data/docs/mcp_guide.md

@@ -1672,7 +1672,12 @@ class Project < Parse::Object
     # Forward the agent's scope to any internal query — pre-filtering by
     # _wperm so the update only sees rows the agent's scope is allowed
     # to modify, defense-in-depth alongside Parse Server's own ACL.
-    Audit.all(**agent.acl_scope_kwargs).each { |a| a.cancel! } if agent&.acl_scope
+    # acl_scope? is true for any scoped agent, including a session agent whose
+    # token has not resolved yet (acl_scope itself would raise
+    # Parse::Agent::UnresolvedIdentity for that one); acl_scope_kwargs
+    # forwards the identity, and the scoped read fails closed if it cannot
+    # be resolved.
+    Audit.all(**agent.acl_scope_kwargs).each { |a| a.cancel! } if agent&.acl_scope?
     self.archived = true              # property :archived, :boolean
     self.archive_reason = reason      # property :archive_reason, :string
     save
@@ -3439,7 +3444,7 @@ Parse::Agent.rack_app(logger: Rails.logger) { |env| ... }
 
 **Sub-agent auth-scope inheritance and permissions clamp (v4.2).** When a tool handler constructs a sub-agent with `Parse::Agent.new(parent: agent, ...)`, the sub inherits `session_token` and `tenant_id` from the parent unless explicitly overridden. Without this inheritance, a session-token parent would silently produce a master-key sub-agent — the constructor default `session_token: nil` resolves to master-key mode — escalating privilege through the very kwarg meant to close sub-agent footguns. Explicit overrides still work (`Parse::Agent.new(parent: agent, session_token: nil)` produces a master-key sub if that is genuinely what the handler wants), but the default is fail-safe inheritance. `permissions:` is NOT inherited and defaults to `:readonly`, but the constructor enforces a clamp: an explicit `permissions:` override on a sub-agent is accepted only if `≤ parent.permissions`, otherwise `ArgumentError` is raised at construction. The clamp is the structural guarantee that a delegation chain cannot escape the parent's tier through sub-agent construction. See [Per-Agent Tool Filtering & Sub-Agent Delegation](#per-agent-tool-filtering--sub-agent-delegation-v42) for the full inheritance table.
 
-**Agent-level ACL scope: `session_token:` / `acl_user:` / `acl_role:` (v4.4.0).** `Parse::Agent.new` accepts three mutually-exclusive identity inputs. `session_token:` round-trips Parse Server's `/users/me` at construction (or defers to per-call REST if the server is unreachable). `acl_user:` takes a `Parse::User` or User-pointer and expands the user's role subscription via `Parse::Role.all_for_user` — no token round-trip, the SDK enforces the resulting `_rperm` filter itself. `acl_role:` is service-account-style scoping — no user_id, just the role plus parent-role inheritance. Master-key posture (none of the three supplied) remains the default and still emits the one-time `[Parse::Agent:SECURITY]` banner at construction. Every built-in tool reads `agent.acl_scope_kwargs` (single point of truth) to forward identity into `Parse::MongoDB.aggregate`, `Parse::Query#results_direct`, and `Parse::AtlasSearch.{search,autocomplete}`. Developer-registered tool handlers and `agent_method` bodies can reach `agent.acl_scope`, `agent.acl_permission_strings`, `agent.acl_read_match_stage` (a `_rperm` `$match`), or `agent.acl_write_match_stage` (a `_wperm` `$match`) to apply the agent's identity to their own queries.
+**Agent-level ACL scope: `session_token:` / `acl_user:` / `acl_role:` (v4.4.0).** `Parse::Agent.new` accepts three mutually-exclusive identity inputs. `session_token:` round-trips Parse Server's `/users/me` at construction. If the server is unreachable then, the agent retries on the first tool call that needs its permissions; if that also fails, the call raises `Parse::Agent::UnresolvedIdentity` (reported as `:access_denied`, `kind: :unresolved_identity`) instead of running without the SDK-side check, and further calls within the next few seconds are refused without another lookup (5.8.2). `acl_user:` takes a `Parse::User` or User-pointer and expands the user's role subscription via `Parse::Role.all_for_user`. It makes no token round-trip, and the SDK enforces the resulting `_rperm` filter itself. `acl_role:` is service-account-style scoping: no user_id, just the role plus parent-role inheritance. Master-key posture (none of the three supplied) remains the default and still emits the one-time `[Parse::Agent:SECURITY]` banner at construction. Every built-in tool reads `agent.acl_scope_kwargs` (single point of truth) to forward identity into `Parse::MongoDB.aggregate`, `Parse::Query#results_direct`, and `Parse::AtlasSearch.{search,autocomplete}`. Developer-registered tool handlers and `agent_method` bodies can reach `agent.acl_scope`, `agent.acl_permission_strings`, `agent.acl_read_match_stage` (a `_rperm` `$match`), or `agent.acl_write_match_stage` (a `_wperm` `$match`) to apply the agent's identity to their own queries.
 
 **ACL composition on the mongo-direct aggregate path (v4.4.0).** When `aggregate` routes through `Parse::MongoDB.aggregate` (the default when `Parse::MongoDB.enabled?` is true), the agent layer derives the auth posture from the agent instance and forwards it to ACLScope — session-tokened / acl_user / acl_role agents get the same row-level `_rperm` `$match` injection regardless of identity mode; master-key agents pass `master: true` (the agent's class/field/tenant/canonical-filter gates are the security boundary for that posture). The posture is built in `Parse::Agent#acl_scope_kwargs`, not from tool-call JSON arguments; LLM-supplied `master:`, `session_token:`, `acl_user:`, or `acl_role:` kwargs are silently swallowed by the tool signature's `**_kwargs` catchall and never reach `Parse::MongoDB.aggregate`. An LLM cannot escalate from a scoped posture to master-key by injecting `master: true` into the tool arguments.
 

data/docs/mongodb_direct_guide.md

@@ -287,6 +287,9 @@ raw = Parse::MongoDB.find(
 Convenience wrapper around `db.find`. Accepts `limit:`, `skip:`, `sort:`,
 `projection:`, `hint:`, `max_time_ms:`. When `:limit` is omitted the call applies
 `DEFAULT_FIND_LIMIT = 1000` and warns; pass `limit: 0` to opt out.
+`find` reads raw documents unscoped, so it raises `Parse::ACLScope::ACLRequired`
+inside `Parse.without_master_key`; `Parse::MongoDB.indexes` (metadata only) is
+allowed there.
 
 ### Forcing an index with `hint`
 
@@ -761,6 +764,32 @@ legitimate read stages — but they read from arbitrary collections. Never
 pass attacker-controlled input into a pipeline; build the pipeline in
 trusted code and interpolate only validated values.
 
+#### Regex patterns and the default time limit
+
+Every caller-supplied regex on these paths (`$regex` strings, Ruby
+`Regexp` and BSON regex values, and the `regex` operand of `$regexMatch`,
+`$regexFind`, and `$regexFindAll`) goes through `Parse::RegexSecurity`,
+which parses the pattern and refuses shapes that backtrack heavily on
+PCRE: nested or overlapping repeats such as `(a+)+` or `(a|aa)+`, more
+than three unbounded quantifiers in a row with no separating literal
+(`\d+\d+\d+\d+`), subroutine calls (`\g<1>`), inline comments, and
+extended mode. Escaped literal text, such as the patterns `starts_with`,
+`ends_with`, and `contains` build, always passes the shape check.
+
+A pattern check cannot prove every regex is cheap, so mongo-direct reads
+whose filter or pipeline carries a regex that is not escaped literal text
+also get a server-side `max_time_ms` of
+`Parse::PipelineSecurity.default_regex_max_time_ms` (5000 ms by default)
+when the caller passed none. This covers `Parse::MongoDB.aggregate` and
+`find`, `results_direct`, `count_direct`, Atlas Search, and vector and
+hybrid search. Set the attribute to a different value, or to `nil` to
+turn the default off; an explicit `max_time_ms:` always wins. A query that
+runs past the limit raises `Parse::MongoDB::ExecutionTimeout`.
+
+REST queries are executed by Parse Server, which applies no regex check of
+its own. Set `databaseOptions.maxTimeMS` in the Parse Server configuration
+to bound those.
+
 ### Layer 2: Row-level ACL enforcement (`Parse::ACLScope`) — scoped only
 
 When `Parse::MongoDB.aggregate` is called with `session_token:`,

data/docs/webhooks_guide.md

@@ -210,6 +210,36 @@ run Parse::Webhooks
 See [`examples/webhook_server.rb`](../examples/webhook_server.rb) for a complete,
 runnable setup.
 
+### Authenticating requests, and what `master?` means
+
+Requests are accepted only when `X-Parse-Webhook-Key` matches
+`Parse::Webhooks.key` (`PARSE_SERVER_WEBHOOK_KEY`). With no key configured the
+Rack app refuses every request unless you opt in with
+`Parse::Webhooks.allow_unauthenticated = true` (or
+`PARSE_WEBHOOK_ALLOW_UNAUTHENTICATED=true`), which is meant for local
+development and tests. A signing secret does not replace the key: with no key
+configured, a signed request is still refused unless `allow_unauthenticated`
+is on. When both are configured, the key must match and the signature must
+verify.
+
+`payload.master?` is true only when the body says the master key was used (a
+JSON `true`; Parse Server never sends a string) AND
+the request was authenticated: the webhook key matched, or a configured
+signature (`PARSE_WEBHOOK_SIGNING_SECRET`) verified. On unauthenticated ingress
+any caller can put `"master": true` in the body, so `master?` returns false
+there. Master-only field guards, ACL owner resolution, and handler checks
+built on `master?` therefore treat such a request as a normal client request.
+The Ruby-initiated callback dedup uses `master?` too, so a forged `_RB_`
+request id plus `"master": true` cannot make a request skip model callbacks
+(including a `before_save` that would reject it). `payload.claimed_master?`
+returns the body's raw claim and `payload.authenticated?` reports whether the
+request was authenticated; both are for diagnostics only.
+
+The trade-off: on unauthenticated ingress, a save made by the SDK itself is
+not recognized as Ruby-initiated, so its model callbacks can run twice (once
+in process, once through the webhook). Configure a webhook key or a signing
+secret to keep the dedup.
+
 ## Auditing trigger coverage
 
 The wiring above has three independent moving parts, and a callback runs
@@ -486,8 +516,11 @@ master key). It has already run the model's `before_save` / `after_save` /
 The intent is to keep trigger logic local when possible and run it exactly once.
 Note that any logic in the **webhook block itself** still runs; only the
 duplicate ActiveModel callback pass is skipped. A spoofed `_RB_` marker without
-the master key does not get this treatment — the callbacks run in the webhook as
-usual.
+the master key does not get this treatment, and neither does a claimed master
+key on an unauthenticated request (no webhook key match and no verified
+signature): the callbacks run in the webhook as usual. On unauthenticated
+ingress this means SDK-initiated saves run their callbacks twice; configure a
+webhook key or signing secret to keep the dedup.
 
 ### 2. Server-initiated replay / freshness protection (inbound)
 

data/lib/parse/agent/constraint_translator.rb

@@ -117,17 +117,16 @@ module Parse
       # worst-case backtracking cost on any one pattern bounded.
       MAX_REGEX_PATTERN_LENGTH = 256
 
-      # Allowed $options flag characters. MongoDB accepts i (case
-      # insensitive), m (multi-line), x (extended/whitespace-ignored),
-      # s (dot-all). The dot-all `s` flag is intentionally omitted: it
-      # makes `.` cross newlines, which extends the search frontier on
-      # multi-line text fields and amplifies catastrophic-backtracking
-      # cost for the worst patterns. `imx` covers every real use case
-      # the agent surface needs.
-      ALLOWED_REGEX_OPTIONS = "imx"
-
-      # Heuristic for nested-quantifier ReDoS patterns (catastrophic
-      # backtracking). Matches a quantifier (`+` or `*`) INSIDE a
+      # Allowed $options flag characters: the shared
+      # {Parse::RegexSecurity::ALLOWED_OPTIONS} list (`imsu`). The extended
+      # flag `x` is refused because it lets comments hide a quantifier from
+      # the pattern check.
+      ALLOWED_REGEX_OPTIONS = defined?(Parse::RegexSecurity::ALLOWED_OPTIONS) ? Parse::RegexSecurity::ALLOWED_OPTIONS : "imsu"
+
+      # Older heuristic for nested-quantifier ReDoS patterns, kept for
+      # callers that reference it. Patterns are now checked by
+      # {Parse::RegexSecurity.validate!}, which parses the pattern. This
+      # heuristic matches a quantifier (`+` or `*`) INSIDE a
       # parenthesized group that is itself followed by a quantifier
       # (`+`, `*`, or `?`) — the structural shape that drives
       # exponential time on adversarial inputs (`(a+)+`, `(a*)*`,
@@ -435,15 +434,17 @@ module Parse
       #
       #   1. $regex must be a String. No Hash/Array/Numeric values.
       #   2. Pattern length ≤ MAX_REGEX_PATTERN_LENGTH (256 chars).
-      #   3. Pattern must not match the nested-quantifier heuristic
-      #      (REDOS_NESTED_QUANTIFIER_RE).
+      #   3. Pattern must pass Parse::RegexSecurity.validate!, which
+      #      parses it and refuses repeated groups holding a quantifier,
+      #      alternation, or backreference, inline comments, and extended
+      #      mode.
       #
       # For $options:
       #
       #   1. Must be a String.
       #   2. Length ≤ 8 (defensive — real-world usage is 0-3 chars).
-      #   3. Every character must appear in ALLOWED_REGEX_OPTIONS (imx).
-      #      The `s` (dot-all) flag is intentionally rejected.
+      #   3. Every character must appear in ALLOWED_REGEX_OPTIONS (imsu).
+      #      The extended `x` flag is rejected.
       #
       # @raise [ConstraintSecurityError] on any rule violation.
       def assert_regex_operand_safe!(op, val)
@@ -465,12 +466,12 @@ module Parse
               reason: :regex_too_long,
             )
           end
-          if REDOS_NESTED_QUANTIFIER_RE.match?(val)
+          unless Parse::RegexSecurity.safe?(val, max_length: MAX_REGEX_PATTERN_LENGTH)
             raise ConstraintSecurityError.new(
               "$regex pattern #{val.inspect} contains a nested quantifier " \
-              "(`(...x+...)+` shape) that can trigger catastrophic " \
-              "backtracking on MongoDB's PCRE engine. Rewrite the pattern " \
-              "without nested quantifier groups.",
+              "or another backtracking-prone construct that can trigger " \
+              "catastrophic backtracking on MongoDB's PCRE engine. Rewrite " \
+              "the pattern without nested quantifier groups.",
               operator: op,
               reason: :regex_redos,
             )
@@ -495,8 +496,8 @@ module Parse
             raise ConstraintSecurityError.new(
               "$options contains disallowed flag(s) " \
               "#{unrecognized.uniq.inspect}. Allowed flags: " \
-              "#{ALLOWED_REGEX_OPTIONS.chars.inspect}. The dot-all " \
-              "`s` flag is intentionally rejected.",
+              "#{ALLOWED_REGEX_OPTIONS.chars.inspect}. The extended " \
+              "`x` flag is rejected.",
               operator: op,
               reason: :invalid_regex,
             )