oct.mcp.policy_loader Namespace Reference

Functions
None	_dbg (*args, **kwargs)
dict	load_policy_source (str source, int timeout_s=5)
object	apply_policy_overrides (object config, dict overrides)
bytes|None	_fetch_url (str url, int timeout_s)
bytes|None	_read_file (str path)
dict	_validate_overrides (dict data)

Variables
int	_POLICY_MAX_BYTES = 64 * 1024
frozenset	_ALLOWED_OVERRIDE_KEYS

Detailed Description

Purpose
-------
Centralised policy loader for the ``oct-mcp`` server (Phase 5C, M-C7).

Loads policy override JSON from a local filesystem path or an HTTPS URL
at server startup. The loaded overrides are applied on top of the base
:class:`~oct.mcp.config.McpConfig` before the policy engine is
instantiated, enabling enterprise deployments to distribute a shared
security policy from a central location.

Configuration
-------------
Set ``policy_source`` in ``~/.oct-mcp/config.json``::

    {
        "policy_source": "https://internal.company.com/oct-policy.json"
    }

Or provide a local path::

    {
        "policy_source": "/etc/oct/policy.json"
    }

Policy JSON schema (all fields optional)::

    {
        "profile": "strict",
        "rate_limit_per_minute": 20,
        "timeout_default_seconds": 30,
        "max_output_bytes": 524288,
        "dry_run_default_for_writes": true
    }

Only the keys listed in :data:`_ALLOWED_OVERRIDE_KEYS` are honoured.
Unknown keys are silently dropped. Type mismatches are silently ignored.

Security
--------
- HTTPS URLs only. HTTP URLs are rejected to prevent cleartext policy
  transmission.
- File size capped at 64 KB (same as ``config.json``).
- Schema is an allowlist — no arbitrary key injection possible.
- Any failure (network error, parse error, schema violation) falls back
  to built-in defaults silently without crashing the server.

Diagnostics
-----------
Domain: MCP
Levels:
    L1 — errors: load failures, schema violations
    L2 — lifecycle: policy loaded, overrides applied
    L4 — deep trace: resolved field values

Contracts
---------
- :func:`load_policy_source` never raises — returns ``{}`` on any error.
- :func:`apply_policy_overrides` never raises — returns *config* unchanged
  on any error.
- No ``http://`` URLs are accepted — HTTPS only.

Function Documentation

_dbg()

None oct.mcp.policy_loader._dbg ( * args, ** kwargs )

protected

Definition at line 77 of file policy_loader.py.

Here is the caller graph for this function:

_fetch_url()

bytes | None oct.mcp.policy_loader._fetch_url ( str url, int timeout_s )

protected

Fetch *url* via HTTPS and return raw bytes, or ``None`` on error.

Definition at line 191 of file policy_loader.py.

Here is the call graph for this function:

Here is the caller graph for this function:

_read_file()

bytes | None oct.mcp.policy_loader._read_file ( str path )

protected

Read *path* from the filesystem and return raw bytes, or ``None``.

Definition at line 211 of file policy_loader.py.

Here is the call graph for this function:

Here is the caller graph for this function:

_validate_overrides()

dict oct.mcp.policy_loader._validate_overrides ( dict data )

protected

Return a sanitised override dict with only allowed, well-typed values.

Definition at line 226 of file policy_loader.py.

Here is the caller graph for this function:

apply_policy_overrides()

object oct.mcp.policy_loader.apply_policy_overrides	(	object	config,
		dict	overrides )

Return a new :class:`~oct.mcp.config.McpConfig` with *overrides* applied.

Parameters
----------
config
    The base :class:`~oct.mcp.config.McpConfig` instance.
overrides
    Dict of validated overrides from :func:`load_policy_source`.

Returns
-------
A new ``McpConfig`` with the override values merged in. Returns
*config* unchanged if *overrides* is empty or an error occurs.

Definition at line 159 of file policy_loader.py.

Here is the call graph for this function:

load_policy_source()

dict oct.mcp.policy_loader.load_policy_source	(	str	source,
		int	timeout_s = 5 )

Load policy override JSON from *source*.

Parameters
----------
source
    A local filesystem path or an ``https://`` URL. ``http://`` URLs
    are rejected. Local paths may be absolute or relative.
timeout_s
    Network timeout in seconds for HTTPS requests (default 5).

Returns
-------
A ``dict`` containing only the keys in :data:`_ALLOWED_OVERRIDE_KEYS`
with validated values. Returns ``{}`` on any failure.

Definition at line 107 of file policy_loader.py.

Here is the call graph for this function:

Variable Documentation

_ALLOWED_OVERRIDE_KEYS

frozenset oct.mcp.policy_loader._ALLOWED_OVERRIDE_KEYS

protected

Initial value:

=  frozenset({
    "profile",
    "rate_limit_per_minute",
    "timeout_default_seconds",
    "max_output_bytes",
    "dry_run_default_for_writes",
})

Definition at line 93 of file policy_loader.py.

_POLICY_MAX_BYTES

int oct.mcp.policy_loader._POLICY_MAX_BYTES = 64 * 1024

protected

Definition at line 89 of file policy_loader.py.