The badge wall package

What it does

1. It fetches your badge wall. On your server, with your project's API key, from api.submitium.com. The answer is kept for an hour, so a busy page doesn't ask again on every visit. If the API is slow or down, the last good wall stays.
2. It checks it. First our signature, then every link, image and text (see below).
3. It shows it. With your framework's own elements: React (Next.js), Vue (Nuxt), Svelte (SvelteKit) or Astro. The badges are in the HTML your server sends, which is what directories read when they check for their badge.

What it never does

• It never runs a script in your visitors' browsers. The badges move with CSS only.
• It never inserts HTML that comes from our servers. We send data, the package writes the elements.
• It sets no cookies and sends nothing about your visitors anywhere.
• It never breaks your page: if anything goes wrong, the wall is simply not shown.

Two things your visitors' browsers do load, and why:

• Each badge's image, from the directory's own site. Directories check that their badge is their own image, at its own address.
• One link to submitium.com, the “Badge wall by Submitium” line. It's a dofollow link by default; you can make it nofollow from your dashboard.

What it checks first

Every badge wall we send is signed with our private key (Ed25519). The package holds our public key and checks the signature before it reads anything: a wall that didn't come from us, or was changed on the way, is refused. Then it checks every value:

• Every link is https and points to the directory's own domain.
• Every image is https.
• A link's rel only holds known values: nofollow, noopener, noreferrer, sponsored, ugc.
• Texts are plain, short and hold no control characters.
• The wall is less than a week old, and holds 300 badges at most.

If a single value is outside these rules, the whole wall is refused, never repaired. The styles are written by the package itself, never received from us.

Your API key

• It can only read your project's badge wall. It can't change anything.
• Keep it on your server, in an environment variable. Never put it in code your visitors' browsers receive.
• We keep only a fingerprint of it, and show it to you once, when you create it.
• You can revoke it at any time from your dashboard. Your site then shows no badge wall until it has a new key.
• We record when a key was last used, to show it in your dashboard.

Open source

The package is published under the MIT licence. It has no dependencies of its own: it uses only what your framework already brings. You can read every line before you install it.

npm install @submitium/badges

Questions

Something here isn't clear, or your security team wants more detail? Write to [email protected]. We answer within one business day.