XRPC Proxy

Control which unrecognized XRPC methods HappyView forwards to their resolved authority. Locally registered lexicons are always served regardless of this setting.

All endpoints require the settings:manage permission.

const TOKEN = "hv_..."; // your API key
const headers = { Authorization: `Bearer ${TOKEN}` };

Get proxy config

GET /admin/settings/xrpc-proxy

interface XrpcProxyConfig {
  mode: string;
  nsids: string[];
}

const response = await fetch("http://127.0.0.1:3000/admin/settings/xrpc-proxy", {
  headers,
});
const data: XrpcProxyConfig = await response.json();

Response: 200 OK

{
  "mode": "allowlist",
  "nsids": ["com.example.feed.*", "games.gamesgamesgamesgames.*"]
}

Returns {"mode": "open", "nsids": []} when no config has been saved.

Update proxy config

PUT /admin/settings/xrpc-proxy

const response = await fetch("http://127.0.0.1:3000/admin/settings/xrpc-proxy", {
  method: "PUT",
  headers: {
    ...headers,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    mode: "allowlist",
    nsids: ["com.example.feed.*"],
  }),
});

Response: 204 No Content

Changes take effect immediately — no restart needed.

Modes

Mode	Behavior
`disabled`	Block all proxy requests. Return `403` for every unrecognized NSID.
`open`	Proxy everything (default). Current behavior on a fresh install.
`allowlist`	Proxy only NSIDs matching a pattern in `nsids`. Return `403` for the rest.
`blocklist`	Proxy everything except NSIDs matching a pattern in `nsids`.

When mode is disabled or open, any nsids in the request body are ignored and stored as [].

NSID patterns

Patterns are dotted NSID identifiers. Trailing wildcards are supported:

com.example.feed.getHot — exact match
com.example.feed.* — matches any NSID starting with com.example.feed.
games.gamesgamesgamesgames.* — matches the entire namespace

Mid-segment wildcards (e.g., com.*.feed) are not supported.

Validation errors

Status	Cause
`400`	An NSID pattern is empty, has fewer than two segments, contains invalid characters, or uses an unsupported wildcard
`422`	`mode` is not one of `disabled`, `open`, `allowlist`, `blocklist`

Blocked request response

When the proxy denies a request, the client receives:

403 Forbidden

{
  "error": "NSID not allowed by proxy policy"
}