BRT website extension developer kit

Build a website extension that a store can install, configure, and run without giving your code access to the storefront session or DOM.

This directory is the source for the public contract at https://developers.battlereadytech.com/extensions/v1. The files here explain how to build against extension protocol version 1.

Start in five minutes

Requirements: Node.js 20 or newer. The developer CLI has no package dependencies.

node tools/web-extensions/brt-extension.mjs init ./my-extension \
  --namespace your-company/my-extension \
  --name "My extension"

node tools/web-extensions/brt-extension.mjs preview ./my-extension
node tools/web-extensions/brt-extension.mjs check ./my-extension

Open the preview URL printed by the command. Stop it with Ctrl+C.

When the extension is ready, generate a publisher key once. Keep the private key outside the project and outside source control.

node tools/web-extensions/brt-extension.mjs keygen \
  --private-key ~/.config/brt/extensions/publisher-private.pem \
  --public-key ./publisher-public-key.txt

node tools/web-extensions/brt-extension.mjs package ./my-extension \
  --out ./dist/my-extension-0.1.0 \
  --private-key ~/.config/brt/extensions/publisher-private.pem

node tools/web-extensions/brt-extension.mjs verify ./dist/my-extension-0.1.0

Upload the complete output directory in the developer console. It contains only public release material:

bundle.zip
manifest.json
publisher-public-key.txt
signature.txt
submission.json

Never send or commit the private key.

Project layout

my-extension/
├── .brt/
│   ├── brt-extension.d.ts
│   ├── contract.json
│   └── manifest.schema.json
├── .vscode/settings.json
├── AGENTS.md
├── BRT_EXTENSION_CONTEXT.md
├── README.md
├── jsconfig.json
├── manifest.json
└── runtime/
    ├── index.html
    ├── main.js
    └── styles.css

Only files inside runtime/ are placed in bundle.zip. manifest.json stays beside the signed bundle so BRT can validate its exact bytes.

The scaffold includes a versioned contract snapshot, editor configuration, JavaScript type checking, and one self-contained LLM context file. Keep them in the project. Regenerate the scaffold or context when adopting a newer protocol contract. Do not edit the files under .brt/ by hand.

How an extension reaches a store

A developer creates and checks a project with this kit.
The publisher signs an immutable release and submits the five generated review files.
BRT verifies the publisher, permissions, code, signature, and user experience.
A BRT operator separately trusts the publisher, approves the release, and reviews any public marketplace listing. If a BRT operator submitted the release, a different operator must approve it.
The extension appears in the store user's extension catalog. Nothing runs until that user installs it and approves its requested capabilities.

There is no self-publishing path and no unsigned upload path. Passing automated validation does not approve or publish a release. Publishers can issue expiring, limited-use links for private packages or publisher-managed paid access. Opening a private link only shows its terms. The signed-in store must explicitly accept it before access is granted.

One file for an LLM

Every new scaffold includes BRT_EXTENSION_CONTEXT.md. Give that file and the project directory to the developer's LLM. For an existing project or a context-only handoff, generate a fresh self-contained file:

node tools/web-extensions/brt-extension.mjs context \
  --out ./brt-extension-context.md

Then ask the LLM to follow the instructions in that file. The generated context includes the contract, schema, API declarations, and reference extension.

An LLM with web access can read the current hosted source directly:

https://developers.battlereadytech.com/llms.txt
https://developers.battlereadytech.com/llms-full.txt
https://developers.battlereadytech.com/extensions/v1/contract.json
https://developers.battlereadytech.com/extensions/v1/manifest.schema.json

Contract authority

The production PHP validators are the final authority during BRT review. The developer CLI catches the same common failures before submission. CI tests keep the public capability list and reference extension aligned with the production validators.