Hosted viewer

The viewer has archive-wide read access. Hosting it makes every session, memory, attachment preview, and other archive object available to anyone who can authenticate to that process. Hansard does not provide per-user, per-repository, or per-session read authorization.

Do not expose the viewer directly to the public internet

Use a trusted LAN, a private overlay network such as a VPN, or a TLS reverse proxy with network access controls. Hansard’s password protects application access, but the built-in HTTP server does not provide TLS and does not set a Secure cookie over plain HTTP.

Loopback is the default

hansard web

Without --host, Hansard binds to 127.0.0.1:7824. A random per-launch token is handed to the local browser and exchanged for an HttpOnly, SameSite=Strict cookie. Local import, search, and viewing do not require an external network service.

Use --no-open to start the loopback server without opening a browser:

hansard web --no-open --port 7825

Bind to another interface

Every non-loopback bind requires a password. Bare --host and --host 0.0.0.0 listen on all interfaces.

1. Choose a long, unique password and provide it through the environment.

   HANSARD_WEB_PASSWORD='replace-with-a-long-random-password' \
     hansard web --host 0.0.0.0 --read-only --no-open

   --password is also supported, but an inline value can be retained in shell history. The process refuses a non-loopback bind when neither source provides a password.

2. Restrict the network path.

   Permit only intended devices at the host firewall, VPN, or reverse proxy. When the viewer crosses an untrusted network, terminate TLS before traffic reaches the Hansard process.

3. Open the served address from the trusted client and sign in.

   Standalone and hosted cookies have a 12-hour maximum age. Logging out or restarting the server invalidates the corresponding in-memory password sessions.

Read-only behavior

Remote requests are always blocked from mutation endpoints. --read-only also blocks mutations that arrive over loopback, which is useful when a reverse proxy and a local browser share one process.

Read-only mode does not narrow what can be read. An authenticated browser can still search and view the archive available to the process. It also does not prevent a browser, proxy, screenshot, or downloaded response from retaining data.

Process lifetime

By default, the standalone server stops when its launching shell is orphaned. Use --keep-alive only when the viewer is meant to continue serving after that shell exits:

HANSARD_WEB_PASSWORD='replace-with-a-long-random-password' \
  hansard web --host 0.0.0.0 --read-only --no-open --keep-alive

The native desktop app uses an internal loopback --parent-pipe lifecycle. Its browser-session cookie lasts only for the child viewer process and is not the hosted-server model.

Operational checklist

• Keep the bind address and firewall rule as narrow as possible.
• Require the Hansard password even when an upstream proxy also authenticates.
• Use TLS for any path that leaves the local machine.
• Run with --read-only for shared viewing.
• Restart the process after changing access policy or when active sessions should be revoked.
• Treat proxy logs, browser caches, and screenshots as additional copies of the archive.