| Version | Support |
|---|---|
| 2.0.x | Bug fixes and security fixes |
| 1.5.x | Security fixes only, on the 1.x branch |
| < 1.5 | Unsupported |
Please report suspected vulnerabilities privately via GitHub Security Advisories (the Security tab of this repository) rather than opening a public issue.
This library is a thin JSON-RPC 2.0 transport. The server executes procedures that you register, so the security of a deployment depends heavily on how it is wired up. This document records what the library protects against on its own, and what remains yours to configure.
The hardening that was opt-in in 1.5 is the default behaviour in 2.0.
-
Internal errors are masked. An exception a procedure throws that the library does not recognize is answered as a generic
-32603 Internal error, so database errors, file paths and stack context never reach a client. Thedatamember of-32602 Invalid paramsanswers is suppressed for the same reason, because anInvalidArgumentExceptionraised by application code carries its message there.Intended client-facing errors are still expressed by throwing
JsonRPC\Exception\ResponseException, which carries its own message, code and data, or by handling an exception yourself with$server->withLocalException(MyException::class).$server->withInternalErrorMasking(false)restores the 1.x behaviour. -
Batches are bounded. A batch of more than 100 calls is rejected with
-32600. Adjust with$server->withBatchLimit($max), or0for no limit. Cap the raw request body at the web server or PHP layer as well (post_max_size,client_max_body_size, a reverse proxy limit), so oversized payloads are rejected before they are decoded. -
Objects expose only what you list.
withObject($instance, ['a', 'b'])publishes exactly those two methods. In 1.x every public method of the instance and its parents became an RPC endpoint, so a class growing a helper grew the API surface with it. Magic methods and methods that do not exist are refused when they are registered. -
Errors raised by PHP are contained. The server catches
Throwable, so aTypeErrorinside a procedure becomes a masked internal error instead of a fatal error and a blank response. -
The built-in transports never follow a redirect. A JSON-RPC endpoint is a fixed POST URL; following a redirect would resend the
AuthorizationandCookieheaders to a location the server operator does not necessarily control. A3xxanswer is reported as an error instead. Two things can change that, and both are yours to decide:withTransportOptions()passes raw options to the transport, redirect settings included, and an injected PSR-18 client applies its own policy. Guzzle disables redirects on its PSR-18 entry point, symfony/http-client follows them unless you setmax_redirectsto0, so check the client you inject. -
Headers cannot be injected into a request. A header name or value containing a carriage return, a line feed or a null byte is refused, so an application putting a value it received into
withHeaders()orwithCookies()cannot have extra headers smuggled into its request. -
Cookies a server deletes are forgotten. A
Set-Cookiewith an empty value, aMax-Ageof zero or less, or anExpiresin the past removes the cookie from the jar, so a session is not sent again after a logout. A value carrying a control character or a separator is refused, whether it comes from the server or from the application.The jar is not a browser cookie store: it belongs to one
HttpClient, which talks to one endpoint, soDomain,PathandSecureare not enforced. Point a client at a different host and it sends what the previous one set. -
Credentials are redacted from logs.
Authorization,Cookie,Set-CookieandProxy-Authorizationvalues are replaced by[redacted]before anything is handed to a PSR-3 logger. -
Authentication is timing safe. Credentials are compared as fixed-length digests with
hash_equals(), so neither the existence of a username nor the length of a password can be told from the response time. Entries that are not strings can never match.
-
REMOTE_ADDRis trusted as-is.allowHosts()matches the address PHP reports. Behind a reverse proxy that address is the proxy, so the allowlist is only meaningful if it is also enforced at the proxy. The library intentionally does not trustX-Forwarded-For. IPv4 and IPv6 addresses and CIDR ranges are both supported; anything that cannot be parsed never matches. -
Always use TLS for HTTP Basic authentication. Credentials are Base64 encoded, not encrypted. The client verifies certificates by default;
withoutSslVerification()turns that off and should not be used against anything but a test server. -
Procedures receive whatever the client sent. Parameters are bound to the signature of your procedure, but their values are not validated beyond the types you declare. Treat them as untrusted input.