Add docs for Perforce IP enforcement (#691)

Author: pjlast

docs/admin/repo/perforce.mdx

@@ -60,7 +60,7 @@ Sourcegraph will now talk to the Perforce host and sync the configured `depots`
 
 It's worthwhile to note some limitations of this process:
 
-- When syncing depots either [git p4](https://git-scm.com/docs/git-p4) or [p4-fusion](https://github.com/salesforce/p4-fusion) (recommended) are used to convert Perforce depots into git repositories so that Sourcegraph can index them.
+- When syncing depots [p4-fusion](https://github.com/salesforce/p4-fusion) is used to convert Perforce depots into git repositories so that Sourcegraph can index them.
 - Rename of a Perforce depot, including changing the depot on the Perforce server or the `repositoryPathPattern` config option, will cause a re-import of the depot.
 - Unless [permissions syncing](#repository-permissions) is enabled, Sourcegraph is not aware of the depot permissions, so it can't enforce access restrictions.
 
@@ -126,11 +126,11 @@ If file-level permissions is not enabled, Sourcegraph provides limited support f
 
 ### File-level permissions
 
-File-level permissions make the [syncing of subdirectories to match permission boundaries](#syncing-subdirectories-to-match-permission-boundaries) unnecessary.
+File-level permissions eliminate the need for [syncing subdirectories to match permission boundaries](#syncing-subdirectories-to-match-permission-boundaries).
 
 To enable file-level permissions:
 
-1. Enable [the feature in the site config](https://sourcegraph.com/github.com/sourcegraph/sourcegraph@2a716bd/-/blob/schema/site.schema.json?L227-249):
+1. Add the following entry to your [site configuration file](https://sourcegraph.com/github.com/sourcegraph/sourcegraph@2a716bd/-/blob/schema/site.schema.json?L227-249):
 
     ```json
     {
@@ -150,27 +150,70 @@ To enable file-level permissions:
     }
     ```
 
-1. Save the configuration. Permissions will be synced in the background based on your [Perforce protects file](https://www.perforce.com/manuals/cmdref/Content/CmdRef/p4_protect.html).
+1. Save the configuration.
 
-#### Handling Host rules in the protects file
+Permissions will be synced in the background based on your [Perforce protects file](https://www.perforce.com/manuals/cmdref/Content/CmdRef/p4_protect.html).
 
-When file-level permissions are enabled, Sourcegraph will read the Perforce protects file to determine what users can access. Because Sourcegraph originates all depot access from one host, protects rules with a Host field cannot be followed exactly. By default, they are parsed as if they apply to all hosts, which can result in users losing access when they should have access. If you have protects rules with hosts that are causing lost access for users, you can set `ignoreRulesWithHost` to `true` in the code host configuration.
+#### Handling IP-based rules
+
+Perforce's `protects` table allows administrators to define fine-grained access controls based on user identities and host IP addresses. By default, Sourcegraph applies all rules from the `protects` table without considering host-specific restrictions, effectively treating all host rules as the wildcard `*`. This behavior can lead to users having unintended access to repositories or files that should be restricted based on their IP addresses.
+
+If your Perforce environment relies heavily on host-based permissions, it's crucial to configure Sourcegraph appropriately to respect these restrictions. This documentation provides detailed instructions on how to enforce or ignore host rules in Sourcegraph when integrating with Perforce.
+
+##### Default Behavior
+
+By default, Sourcegraph:
+
+- **Applies all rules** in the Perforce `protects` table.
+- **Ignores host-specific restrictions**, treating all host fields as `*`.
+
+**Implication**: Users may gain access to resources that should be restricted based on their IP addresses.
+
+##### Configuration Options
+
+To ensure Sourcegraph handles host rules according to your requirements, you have two additional options:
+
+1. **Enforce Host Rules**: Configure Sourcegraph to respect and enforce IP-based restrictions defined in the `protects` table.
+2. **Ignore Host-Specific Rules**: Configure Sourcegraph to disregard any rules with a host value other than `*`.
+
+##### Enforcing host rules
+
+If you want Sourcegraph to enforce host-specific permissions, you need to enable IP restriction enforcement in your [site configuration](https://sourcegraph.com/docs/admin/config/site_config):
 
 ```json
-    {
-      "authorization": {
-        "subRepoPermissions": true,
-        "ignoreRulesWithHost": true
-      }
+{
+  "experimentalFeatures": {
+    "subRepoPermissions": {
+      "enabled": true,
+      "enforceIPRestrictions": true
     }
+  }
+}
 ```
+<Callout type="warning">
+When `enforceIPRestrictions` is set to `true`, Sourcegraph will use the user's IP address to apply Perforce permissions at the user level. It uses the final `X-Forwarded-For` header in the request to identify the user's IP. Note that this header can be easily spoofed, so ensure your load balancer or proxy handles `X-Forwarded-For` headers securely.
+</Callout>
+
+##### Ignore rules with host
+
+To ignore rules that have a host value other than `*`, set `ignoreRulesWithHost` to `true` in your **code host configuration**:
+
+```json
+{
+  "authorization": {
+    "subRepoPermissions": true,
+    "ignoreRulesWithHost": true
+  }
+}
+```
+
+With this setting, Sourcegraph will ignore any rules with a host other than `*`, treating them as if they do not exist.
 
 ### Notes about permissions
 
 - Sourcegraph users are mapped to Perforce users based on their verified email addresses.
 - As long as a user has been granted at least `Read` permissions in Perforce they will be able to view content in Sourcegraph.
 - As a special case, commits in which a user does not have permissions to read any files are hidden. If a user can read a subset of files in a commit, only those files are shown.
-- [The host field from protections are not supported](#known-issues-and-limitations).
 - [file-level permissions must be disabled for Batch Changes to work](#known-issues-and-limitations).
 - Setting `authz.enforceForSiteAdmins` to `true` in the site configuration will enforce permissions for admin users. They may not be able to see repositories and their contents if their Sourcegraph user account email does not match with their email on the Perforce server.
 
@@ -228,7 +271,6 @@ When file-level permissions are enabled, Sourcegraph will read the Perforce prot
 We are actively working to significantly improve Sourcegraph's Perforce support. Please [file an issue](https://github.com/sourcegraph/sourcegraph/issues) to help us prioritize any specific improvements you'd like to see.
 
 - Sourcegraph was initially built for Git repositories only, so it stores Perforce depots as Git repositories when syncing. Perforce concepts and languages are expressed in the UI, but under the hood, Git tools are used.
-- The [host field](https://www.perforce.com/manuals/cmdref/Content/CmdRef/p4_protect.html#Form_Fields_..361) in protections is not supported.
 - Batch Changes does not support [file-level permissions](#file-level-permissions) (also known as sub-repo permissions)
 - Batch Changes does not handle the shelved changelist other than to query the Perforce server for its status.
 - Permalinks with Changelist Id do not work yet