Skip to content

link_utils: exposing whitelisted protocols to user settings #1467

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
+46 −1
Open

link_utils: exposing whitelisted protocols to user settings #1467

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions app/common/config-schemata.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,7 @@ export const configSchemata = {
useManualProxy: z.boolean(),
useProxy: z.boolean(),
useSystemProxy: z.boolean(),
whitelistedProtocols: z.string().array(),
};
export type ConfigSchemata = typeof configSchemata;

Expand Down
11 changes: 10 additions & 1 deletion app/common/link-util.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,11 +3,20 @@ import fs from "node:fs";
import os from "node:os";
import path from "node:path";

import * as ConfigUtil from "./config-util.ts";
import {Html, html} from "./html.ts";
import * as t from "./translation-util.ts";

const whitelistedProtocols = ConfigUtil.getConfigItem("whitelistedProtocols", [
"http:",
"https:",
"mailto:",
"tel:",
"sip:",
]);
Comment on lines +10 to +16
Copy link
Member

@andersk andersk Nov 12, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

getConfigItem writes the default value into the config file if it’s missing, so if we ever add new default protocols they’ll never be visible to someone who’s ever launched an old version.

(Was this a bad design decision for getConfigItem? Yes.)


export async function openBrowser(url: URL): Promise<void> {
if (["http:", "https:", "mailto:"].includes(url.protocol)) {
if (whitelistedProtocols.includes(url.protocol)) {
await shell.openExternal(url.href);
} else {
// For security, indirect links to non-whitelisted protocols
Expand Down
35 changes: 35 additions & 0 deletions docs/howto/customize-link-protocols.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
# Customizing Link Protocols
Copy link
Collaborator

@alya alya Nov 10, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should be using standard Zulip capitalization throughout (sentence case).


The Zulip app supports opening certain link protocols directly in their associated system applications. These are known as **whitelisted protocols**.

## Default Whitelisted Protocols

By default, the following protocols are whitelisted:

```
http, https, mailto, tel, sip
```

Links using these protocols are opened directly by the system.

All other protocols are considered potentially unsafe and are therefore opened indirectly—through a local HTML file in your default web browser.

## Extending the Whitelisted Protocols

It is possible to customize the list of whitelisted protocols by editing the `settings.json` file located at: `userdata/Zulip/config/settings.json`

To modify the list, the `whitelistedProtocols` key can be updated. For example:

```json
{
...
"whitelistedProtocols": [
"http:",
"https:",
"mailto:"
]
...
}
```

Note: Each protocol should include the trailing colon (:), e.g., "mailto:" instead of "mailto".
Copy link
Collaborator

@alya alya Nov 10, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Note: Each protocol should include the trailing colon (:), e.g., "mailto:" instead of "mailto".
Note: Each protocol should include the trailing `:`, e.g., "mailto:" instead of "mailto".