xref: /plugin/extranet/README_EN.md (revision ef5bb1f3884025c3556b3c46e33332ca386a73a6)

# Extranet

[���� Français](README.md) | ���� English | [���� Deutsch](README_DE.md) | [���� Español](README_ES.md)

DokuWiki plugin to restrict the display of pages, media files and some actions when the request comes from the extranet.

The plugin can:
- detect the extranet from a configurable `$_SERVER` value;
- apply a default policy of `allow`, `block`, `force_allow` or `force_block`;
- filter pages and media files by exact ID, namespace, wildcard or regex;
- replace restricted page content with a configurable message;
- replace restricted media files with a neutral image;
- disable selected DokuWiki actions for extranet visitors;
- handle the `~~NOEXTRANET~~` and `~~EXTRANET~~` macros;
- integrate with ProseMirror so this state is preserved correctly in WYSIWYG mode.

## Usage

Two macros are available in pages:

- `~~NOEXTRANET~~`: blocks the page from the extranet when the policy allows it;
- `~~EXTRANET~~`: allows the page from the extranet when the policy allows it.

The exact behavior depends on `default_policy`:

- `allow`: everything is allowed except filtered pages or pages marked with `~~NOEXTRANET~~`
- `block`: everything is blocked except filtered pages or pages marked with `~~EXTRANET~~`
- `force_allow`: only filter rules apply, `~~NOEXTRANET~~` is ignored
- `force_block`: only filter rules apply, `~~EXTRANET~~` is ignored

## Configuration

In the configuration manager:

- `request_match_key`: `$_SERVER` key used to detect the extranet, for example `REMOTE_ADDR` or an `HTTP_*` header
- `extranet_match_list`: comma-separated list of values treated as extranet
- `extranet_match_regex`: regex used to identify the extranet from the configured value
- `default_policy`: default access policy
- `filter_list`: list of pages or media files affected by the policy
- `filter_regex`: additional regex to target pages or media files
- `hide_files`: whether restrictions also apply to media files
- `disable_actions`: DokuWiki actions disabled for extranet visitors
- `restricted_disable_actions`: additional actions disabled only when the current page is restricted
- `preserve_first_title`: keeps the first heading when a page is hidden
- `message_prefix`: content inserted before the restriction message
- `message_suffix`: content inserted after the restriction message

Compatibility:

- `server_ip_key`
- `extranet_ip_list`
- `extranet_ip_regex`

These legacy settings are still supported for compatibility, but the new names should be preferred.

## Examples

Detection by direct IP:

- `request_match_key = REMOTE_ADDR`
- `extranet_match_regex = /^10\.100\./`

Detection by proxy header:

- `request_match_key = HTTP_X_NETWORK_ZONE`
- `extranet_match_list = extranet`

Detection by upstream host name:

- `request_match_key = HTTP_X_UPSTREAM_HOST`
- `extranet_match_regex = /^frontend-ext-/`

## What the helper provides

Load the helper:

```php
$extranet = plugin_load('helper', 'extranet');
```

Main methods:

- `getDefaultPolicy()`: returns the effective default policy
- `getRequestMatchKey()`: returns the `$_SERVER` key used for detection
- `getExtranetMatchList()`: returns the configured list of values
- `getExtranetMatchRegex()`: returns the configured regex
- `isExtranetRequest()`: tells whether the current request is treated as extranet
- `isPageVisibleFromExtranet()`: tells whether a page is visible from the extranet
- `isMediaVisibleFromExtranet()`: tells whether a media file is visible from the extranet
- `isPageAllowed()`: tells whether a page is allowed in the current context
- `isMediaAllowed()`: tells whether a media file is allowed in the current context
- `parseRuleList()`: converts a list of rules into a usable array
- `idMatchesRule()`: tests an ID against a rule

## Cache and behavior

The plugin splits the render cache to distinguish intranet and extranet visitors.

When a page is restricted, its content is replaced with a configurable message. If `preserve_first_title` is enabled, the first heading is kept.

If `hide_files` is enabled, restricted media files are replaced with a dedicated image.

## Note

The plugin relies on a request marker provided by the web infrastructure. It is suitable for intranet/extranet segmentation, but should not be treated as a replacement for ACLs or strong access control.