JavaScript SDK and DSN

Install

npm install @shellorbit/sdk

import { init } from "@shellorbit/sdk";

init({ dsn: process.env.SHELLORBIT_DSN });

Call init once, as early as your app starts. Create a project in Leak Alarm, SDK to get its DSN; an account can hold 20 projects. Like a Sentry DSN, it can report findings for its own project and nothing else: it cannot read your findings, your account, or any other project, so it is safe in your app’s configuration. Rotate the key for a new DSN, and the old one is refused at once; delete the project to revoke it for good.

What it does

• Masks keys in logs. It hooks console, pino, and winston, replaces a key with a masked form such as sk_…a1b2 before the line is written, and reports where it was logged.
• Guards responses. It notices a server only key, such as a Supabase service role key, in a page or API response, and reports it as critical. Blocking the response instead is your choice in the SDK’s options and is off by default.
• Fingerprints your own keys. At start up it sends one way, salted fingerprints of your app’s real keys, using a salt only your project has. On Starter, Pro, and Business, when ShellOrbit later finds a matching string in a repo, a log drain, or a scan, it tells you your real key turned up there, without ever holding it.
• Plants a tripwire. It asks for a fake AWS key and puts it in your app’s environment as BACKUP_AWS_ACCESS_KEY_ID, so a dumped environment that turns up somewhere trips the alarm. It uses one of your plan’s tripwires; if they are all in use, none is planted.

What it never does

It never sends a key in full, never slows a request down to talk to ShellOrbit, and never throws: if ShellOrbit cannot be reached, your app carries on and the SDK tries again later. Blocking stays off unless you turn it on.

ShellOrbit enforces the first rule too: a finding whose value is not masked, with more than a few characters showing, is refused and never stored.

Limits

Each project may send 10 requests a second, 60 a minute, and 200 a day, with up to 50 findings in a request. Past that, ShellOrbit answers 429 with Retry-After and the SDK waits. Each new finding is one event; the same finding reported again is not.