# URL Safety Restrictions for Remote Sources in claude-obsidian: A Complete Security Guide

> Learn claude-obsidian URL safety restrictions for remote sources. Discover HTTPS-only endpoints, localhost blocking, and explicit consent requirements to prevent data leakage. Secure your remote connections now.

- Repository: [Agrici.Daniel/claude-obsidian](https://github.com/AgriciDaniel/claude-obsidian)
- Tags: security-guide
- Published: 2026-08-28

---

**To prevent accidental data leakage, claude-obsidian treats all external requests as remote egress and enforces strict URL safety rules including HTTPS-only endpoints, localhost blocking, and mandatory explicit user consent via the `--allow-remote-ollama` flag.**

The **AgriciDaniel/claude-obsidian** repository implements a defense-in-depth strategy for URL safety restrictions for remote sources in claude-obsidian. Every external network request undergoes multiple validation layers to ensure that sensitive vault data cannot be exfiltrated to unauthorized endpoints without deliberate user approval.

## HTTPS-Only Enforcement

Any remote source must use an absolute URL with the `https` scheme. The validation logic in [`claude_obsidian/ledgers.py`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/claude_obsidian/ledgers.py) (lines 531–542) explicitly rejects plain HTTP, protocol-relative URLs, or malformed strings before any network connection is attempted.

This check ensures that data transmitted outside the local vault benefits from TLS encryption. If you attempt to pass an insecure URL, the system raises a `ValueError` with the message that remote sources require an absolute HTTPS URL.

## Localhost and Private Network Blocking

By default, claude-obsidian denies URLs that resolve to local addresses such as `http://localhost:11434`. The blocking logic resides in [`scripts/tiling-check.py`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/scripts/tiling-check.py) (lines 544–562), which screens for loopback and private IP ranges during the URL validation phase.

This restriction prevents plugins or scripts from accidentally sending vault contents to a locally running service that the user did not intend to expose. Access to localhost Ollama instances requires an explicit opt-in flag rather than implicit trust.

## Explicit Consent Architecture

Remote egress is governed by a contract-driven policy defined in [`claude_obsidian/contracts.py`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/claude_obsidian/contracts.py) (line 476). The product contract specifies `remote_egress: "explicit_consent"`, which runtime checks consult before allowing any external request.

At the CLI level, [`scripts/retrieve.py`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/scripts/retrieve.py) (line 244) implements this requirement through the `--allow-remote-ollama` flag. When present, this flag is forwarded to low-level helpers such as the `rerank` module, signaling that the user has deliberately approved remote communication. Without this flag, the system exits with a "remote Ollama default-deny" error.

## Centralized URL Validation

The [`claude_obsidian/url_safety.py`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/claude_obsidian/url_safety.py) module centralizes all safety checks into a single `validate_remote_url()` function. This utility validates the URL scheme, ensures the path is absolute, and confirms the host is not local. If any test fails, the function raises a `ValueError` immediately, preventing the request from reaching the network stack.

## Practical Implementation Examples

### Rejecting Non-HTTPS URLs

```python
from claude_obsidian.url_safety import validate_remote_url

# This raises ValueError: "remote sources require an absolute HTTPS URL"

validate_remote_url("http://example.com/data.json")

```

### Enabling Localhost Ollama Access

```bash

# Without the flag → exit with error "remote Ollama default-deny"

claude-obsidian retrieve --model my-model

# With the explicit opt-in flag → request is permitted

claude-obsidian retrieve --model my-model --allow-remote-ollama

```

### Using the Low-Level Rerank Helper

```bash
python -m claude_obsidian.rerank \
    --query "What is AI?" \
    --candidates candidates.json \
    --allow-remote-ollama   # ← enables remote OLLAMA_URL

```

### Verifying the Contract Policy

```python
from claude_obsidian.contracts import get_product_contract

contract = get_product_contract()
assert contract["privacy_defaults"]["remote_egress"] == "explicit_consent"

```

## Summary

- **HTTPS is mandatory**: Absolute URLs must use the `https` scheme as enforced in [`claude_obsidian/ledgers.py`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/claude_obsidian/ledgers.py).
- **Localhost is blocked by default**: Private addresses like `localhost:11434` are rejected unless explicitly allowed via [`scripts/tiling-check.py`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/scripts/tiling-check.py) logic.
- **Explicit consent required**: The `--allow-remote-ollama` flag and the contract-defined `remote_egress: "explicit_consent"` policy ensure users must deliberately approve remote egress.
- **Centralized validation**: All URL checks run through [`claude_obsidian/url_safety.py`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/claude_obsidian/url_safety.py), raising `ValueError` for any violation before network access occurs.

## Frequently Asked Questions

### What happens if I try to use an HTTP URL instead of HTTPS?

The `validate_remote_url()` function in [`claude_obsidian/url_safety.py`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/claude_obsidian/url_safety.py) raises a `ValueError` stating that remote sources require an absolute HTTPS URL. This check occurs in [`claude_obsidian/ledgers.py`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/claude_obsidian/ledgers.py) (lines 531–542) before any network request is dispatched, ensuring unencrypted transmission is impossible.

### How do I enable remote Ollama endpoints on localhost?

You must provide the `--allow-remote-ollama` flag when running CLI commands such as `retrieve` or `rerank`. This flag signals explicit consent as required by the contract policy in [`claude_obsidian/contracts.py`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/claude_obsidian/contracts.py), overriding the default localhost block implemented in [`scripts/tiling-check.py`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/scripts/tiling-check.py).

### Where is the remote egress policy defined in the codebase?

The policy is codified in [`claude_obsidian/contracts.py`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/claude_obsidian/contracts.py) (line 476) as `remote_egress: "explicit_consent"`. This contract value is consulted by validation logic throughout the repository, ensuring the safety rules cannot be bypassed without modifying the contract itself.

### Can the URL safety restrictions be bypassed or disabled?

No. The restrictions are enforced at multiple layers: the contract definition in [`contracts.py`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/contracts.py), the validation logic in [`url_safety.py`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/url_safety.py), and the CLI argument parsing in [`scripts/retrieve.py`](https://github.com/AgriciDaniel/claude-obsidian/blob/main/scripts/retrieve.py). Because the contract-driven policy is checked at runtime, disabling the safety features requires changing the contract source code and rebuilding the package, not merely toggling a configuration option.