Protocol Handlers

Protocol handlers translate URLs into HPPR operations. Each scheme serves a different purpose: content retrieval, trust establishment, sandboxed preview, or browser configuration.

URL Format

All HPPR-related schemes use this format:

scheme:[endpoint]//group/app/location

The endpoint is optional for most schemes. Default port is 4777.

Schemes

Scheme	Endpoint	Purpose
`hppr`	Optional	Content retrieval (uses route lookup)
`hppr-setup`	Required	Trust establishment for new servers
`hppr-sandbox`	Required	Sandboxed preview (no JavaScript)
`hppr-browse`	Optional	Directory browser
`hppr-editor`	Forbidden	Local packet editor
`havi`	N/A	Browser internal pages

Reserved endpoint keywords: - route — force route lookup (explicit) - repo — force localhost (bypass route)

hppr://

The main scheme for browsing HPPR content.

Fetching content (no trailing slash):

hppr://mygroup/myapp/index.html

Issues a GET request, returns the packet body with Content-Type derived from the file extension:

Extension	Content-Type
`.html`	`text/html`
`.js`	`application/javascript`
`.json`	`application/json`
`.css`	`text/css`
`.png`	`image/png`
`.md`	`text/markdown`
(unknown)	`application/octet-stream`

A Content-Type header in the packet overrides the extension mapping.

Listing directories (trailing slash):

hppr://mygroup/myapp/docs/

Issues a LIST request, renders an HTML directory listing.

Direct connection redirect:

If you navigate to hppr:[endpoint]//g/a/path and no route exists for that group/app, HAVI redirects to hppr-setup:[endpoint]//g/a/path so you can review and accept the connection.

hppr-setup://

Trust establishment for connecting to a new server. This scheme has window.ring0 access to store configuration locally.

The setup flow:

Fetch the remote server’s HELLO greeting
Fetch site-trust information via MEMBERS
Display server details for user review
If user accepts: store route and site-trust packets locally
Navigate to hppr://group/app/

The setup page can preview the remote site using a sandboxed iframe:

<x src="hppr-sandbox:[endpoint]//g/a/index.html"></x>

See 060-SITE-RING1.md for details on site trust.

hppr-sandbox://

Sandboxed preview mode. Used to show content without trusting it.

Uses anonymous (anyone) connection only
Strict CSP blocks JavaScript, forms, and navigation
Safe for previewing untrusted content

hppr-browse://

Directory browser for exploring repository contents. Clicking entries stays in browse mode; an “open” button switches to hppr:// for normal viewing.

hppr-editor://

Local packet editor for creating and modifying content. Has both window.ring0 and window.repo access.

Features: - Textarea for headers and data - Ctrl+S to save (PAC command) - Redirects to hppr:// on successful save

Endpoint is forbidden—this scheme only works with localhost.

havi://

Browser internal pages for configuration and management.

URL	Content
`havi://home`	New tab page
`havi:///`	Dashboard
`havi:///server`	Server configuration
`havi:///routes`	Routes and trust settings
`havi:///ring0`	Ring0 proxy approval queue

All havi:// pages have window.ring0 access (pre-fetched, no prompt required).

Credentials

HAVI stores admin credentials for your local repository at:

~/.config/HAVI/credentials/<server-key>

File format:

ring1_name
token

On startup, HAVI: 1. Sends HELLO to get the server key 2. Loads credentials for that key 3. If no credentials exist, bootstraps with ring0/init

Site credentials (for remote servers) are cached in memory per (group, app) combination.