Prism Browser Laravel Package

Getting Started

Upgrade to v0.1.2 before relying on BrowserPolicy for any allow-list that can be influenced by untrusted input. This release is a security fix, not a feature release: shorthand, integer, octal, and hex IPv4 forms are now interpreted with inet_aton rules and refused when they resolve to non-public addresses.

Start by locating:

• Where BrowserPolicy is configured and instantiated.
• Where allow-listed hosts enter the system: user-submitted URLs, webhook targets, redirects, importers, admin forms, or tenant configuration.
• Every outbound request or browser navigation that depends on that allow-list.

A good first use case is a user-submitted URL that must match an allow-list before the application fetches or navigates to it. Add a regression test with 127.1, 0x7f000001, 2130706433, 0177.0.0.1, and 169.254.43518, and confirm they are treated as addresses and refused rather than accepted as hostnames.

Implementation Patterns

Centralize allow-list handling behind BrowserPolicy rather than scattering string comparisons across controllers, jobs, and commands. Treat the policy as the single decision point before any outbound request or browser navigation.

Typical workflow:

1. Normalize and validate the candidate URL.
2. Pass the host/address through BrowserPolicy.
3. Reject non-public addresses by default.
4. Only permit explicitly allow-listed hosts.
5. Re-check after redirects if your HTTP client follows them.

For Laravel applications, this usually means wrapping outbound HTTP calls in a small service or action class. Keep the policy call close to the request boundary so jobs, commands, and queued workflows cannot bypass it.

When allow-listing hosts from untrusted input, prefer explicit hostnames and exact matches. Do not assume a string is “just a name” because it looks unusual. Add test cases for:

• 127.1
• 0x7f000001
• 2130706433
• 0177.0.0.1
• 169.254.43518

Also test that a name containing only digits remains a name, since v0.1.2 deliberately preserves that behavior.

Gotchas and Tips

• v0.1.2 contains a security behavior change even though it is marked as non-breaking. If allow-listed hosts come from untrusted input, treat the upgrade as required.
• Browsers and libc-style parsers accept shorthand IPv4 forms that many PHP validators do not. Do not rely only on filter_var() or a simple regex for host validation.
• 127.1, 0x7f000001, 2130706433, and 0177.0.0.1 all reach 127.0.0.1 in a browser. 169.254.43518 reaches the metadata endpoint.
• These forms are now read with inet_aton rules, without DNS, and refused like other non-public addresses.
• A name that only contains digits stays a name. Avoid overcorrecting by treating every numeric-looking string as an IPv4 address.
• Debug policy decisions by logging the original host, the interpreted address, and the final allow/deny result. Add regression tests around redirects and queued jobs, where checks are commonly skipped.
• If you maintain custom allow-list logic outside BrowserPolicy, align it with the same address parsing rules or delegate to the package to avoid bypasses.