Contains resources and scriptlets designed for use with Brave's adblock-rust library.
Custom resources should be added to the resources
directory, and a corresponding entry should be added to the metadata.json
file.
This package can be imported as a library, exposing the function readResources
which will produce the correctly formatted list of resources for use with adblock-rust.
Alternatively, npm run build
will write all resources to dist/resources.json
for future use.
To generate metadata.json
automatically from files in resources/
, run npm run generateMetadata
.
Use npm run test
after modifying the resources or metadata file to ensure the format can be accepted by adblock-rust
.
metadata.json
is a list of elements of the following format:
{
"name": "name-of-my-resource",
"aliases": ["an-alias-for-my-resource"],
"kind": {"mime":"application/javascript"},
"resourcePath": "pathRelativeToResources.js"
}
-
name
is the name of the resource as it would be used in a filter rule. -
aliases
is a list containing optional additional (usually shorter) identifiers that could be used instead of thename
. Usually this is empty or contains a single entry that is an abbreviation of thename
. -
kind
is either a MIME type as shown above, or simply the string"template"
to specify that the resource is a scriptlet with optional template parameters (i.e.,{{1}}
,{{2}}
, ...). -
resourcePath
specifies the path to the content of the resource. It should be relative to theresources
directory in the root of this repository.
In general, this format corresponds to the Resource
struct from adblock-rust, but the base64-encoded content
field is replaced by a path to a file for better maintainability. This library will translate the resourcePath
field back to a base64-encoded content
field when ready for use.
The filter_lists/*.json
files are lists of elements, each describing a filter list. The format for each element is:
{
"title": "New Filter Rules",
"desc": "Removes new elements"
"langs": [],
"component_id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"base64_public_key": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAs...IDAQAB",
"list_text_component": {
"component_id": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
"base64_public_key": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAs...IDAQAB",
},
"sources": [
{
"url": "https://raw.githubusercontent.com/brave/adblock-lists/master/brave-lists/new-list.txt",
"title": "Brave New List",
"format": "Standard",
"support_url": "https://github.com/brave/adblock-lists",
}
]
}
-
uuid
is a UUID generated with, for example, the CLI tooluuidgen
. -
title
is a human-readable title for the filter list component. Each source also has a title, which is a human-readable title for each individual list making up the full component. -
desc
is a short human-readable description of what the filter list is designed to block. -
langs
is a list of locale codes for the given component, allowing it to be preselected in-browser by users in the corresponding regions. Note that despite the name, it should not list language codes. -
component_id
andbase64_public_key
are unique constants generated per-list such that the lists can be served in CRX components created by brave-core-crx-packager. Note that the ones insidelist_text_component
should not have the same values. -
sources
is a list of individual filter lists that are concatenated together in order to create the full list for a component. -
url
is the URL where a filter list source can be downloaded from. It should be a list of rules in the format specified informat
in a plaintext file. -
format
is either ABP/uBO-style format ("Standard", most common) or IP address and hostname ("Hosts"). -
support_url
is somewhere a user can ask for help with the filter list.
The following 4 fields are all optional and default to false
or 0
if omitted.
hidden
(boolean
) should the component be displayed in brave://settings/shields/filters as an additional list option?default_enabled
(boolean
) should the component be enabled by default?first_party_protections
(boolean
) should first-party heuristics be applied to rules from the list?permission_mask
(number
) what scriptlet permissions should be granted to rules from the list? The bits of the bitmask are currently assigned as follows:- Bit
0
: "trusted" resources from the uBlock Origin project - Bit
1
: resources only intended for use by Brave-authored lists - Bits
2
-7
: reserved
- Bit
platforms
(array
ofstring
) specify the platforms that the list supports. Can be any combination ofLINUX
,WINDOWS
,MAC
,ANDROID
orIOS
.
The generate_component.sh
script can be used to help create a new filter list component.
It will generate:
- A UUID (for the top-level
uuid
field) - A public key (corresponding to the
list_text_component.base64_public_key
field) - A component ID (corresponding to the
list_text_component.component_id
field) - The component's private key (in a new PEM file)
The script should be run with no arguments.
The resulting PEM file will be named ad-block-updater-<component_id>.pem
. This new PEM file has to be uploaded to 1Password. See instructions here.
We will need to run this script a second time to get values for the top-level base64_public_key
and component_id
fields. These will be different from the values for list_text_component.base64_public_key
and list_text_component.component_id
fields. This is necessary for iOS, see tracking issue.