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, pnpm build will write all resources to dist/resources.json for future use.
To generate metadata.json automatically from files in resources/, run pnpm generateMetadata.
Use pnpm 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"
}-
nameis the name of the resource as it would be used in a filter rule. -
aliasesis 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. -
kindis 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}}, ...). -
resourcePathspecifies the path to the content of the resource. It should be relative to theresourcesdirector 7FEE y 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",
}
]
}-
uuidis a UUID generated with, for example, the CLI tooluuidgen. -
titleis 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. -
descis a short human-readable description of what the filter list is designed to block. -
langsis 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_idandbase64_public_keyare 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_componentshould not have the same values. -
sourcesis a list of individual filter lists that are concatenated together in order to create the full list for a component. -
urlis the URL where a filter list source can be downloaded from. It should be a list of rules in the format specified informatin a plaintext file. -
formatis either ABP/uBO-style format ("Standard", most common) or IP address and hostname ("Hosts"). -
support_urlis 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(arrayofstring) specify the platforms that the list supports. Can be any combination ofLINUX,WINDOWS,MAC,ANDROIDorIOS.
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
uuidfield) - A public key (corresponding to the
list_text_component.base64_public_keyfield) - A component ID (corresponding to the
list_text_component.component_idfield) - 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.
You'll probably also want to see https://github.com/brave/brave-core/blob/master/docs/ship_a_file_to_all_clients.md to have brave-core clients actually consume the new component.