Skip to content

An agentic browser harness: an AI side panel & orb in your own logged-in Chrome, Edge, Arc, Brave or even Firefox run by the agent/subscription you already use (Claude Code, Codex, Antigravity). Free, open source, no API key. Also an MCP server.

feat(secrets): a deterministic sanitizer both sides of the socket can agree on

Shahriar1383b0b4f0bf
diff --git a/lib/secrets/detect.ts b/lib/secrets/detect.ts
new file mode 100644
index 0000000..6d8fb52
--- /dev/null
+++ b/lib/secrets/detect.ts
@@ -0,0 +1,133 @@
+/**
+ * Finding the secrets in a string. Pure, total, and order-independent: the shapes are
+ * tried in declaration order and a later match that overlaps an earlier one is dropped,
+ * so `sk-ant-…` is an Anthropic key rather than the generic `sk-` key it also matches.
+ *
+ * The last pass is the one that needs justifying. Shapes and labels only find secrets
+ * that announce themselves; a bare token sitting on a page under a heading two lines up
+ * announces nothing. The entropy gate catches those, and every clause in it exists to
+ * keep something specific out: digests and ids are hex, identifiers are camel case with
+ * a digit on the end, asset hashes live in a URL path. The threshold sits above where
+ * concatenated English words land and well below where random base64 does.
+ */
+
+import { NOTHING, SHAPES, type Reveal, type SecretKind } from './shapes';
+
+export interface Span {
+ readonly start: number;
+ readonly end: number;
+ readonly value: string;
+ readonly kind: SecretKind;
+ readonly shape: string;
+ readonly reveal: Reveal;
+}
+
+export interface Range {
+ readonly start: number;
+ readonly end: number;
+}
+
+const CANDIDATE = /(?<![A-Za-z0-9+/_=-])[A-Za-z0-9+/_-]{32,4096}={0,2}(?![A-Za-z0-9+/_-])/g;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const ENTROPY_BITS = 4.3;
+/**
+ * How often case flips between adjacent letters. Random credentials flip about half the
+ * time; identifiers written by a person flip once per word. Measured over both, the two
+ * populations do not overlap, and requiring both signals is what keeps a page's
+ * `ContinueReadingTheFullArticle` out of the vault.
+ */
+const CASE_FLIPS = 0.5;
+
+/** Inline data URLs are image bytes, not credentials, and scanning them is pure cost. */
+const DATA_URL = /\bdata:[^\s;,]{0,80};base64,[A-Za-z0-9+/=]+/g;
+
+export function findSecrets(text: string, immune: readonly Range[] = []): Span[] {
+ if (!text) return [];
+ const claimed = [...immune, ...rangesOf(text, DATA_URL)].sort((a, b) => a.start - b.start);
+ const lower = text.toLowerCase();
+ const found: Span[] = [];
+
+ const take = (span: Span) => {
+ if (overlaps(claimed, span)) return;
+ claimed.push(span);
+ claimed.sort((a, b) => a.start - b.start);
+ found.push(span);
+ };
+
+ for (const shape of SHAPES) {
+ if (shape.guard && !lower.includes(shape.guard)) continue;
+ for (const match of text.matchAll(shape.pattern)) {
+ const at = secretIn(match);
+ if (!at) continue;
+ if (shape.validate && !shape.validate(at.value)) continue;
+ take({ ...at, kind: shape.kind, shape: shape.id, reveal: shape.reveal ?? NOTHING });
+ }
+ }
+
+ for (const match of text.matchAll(CANDIDATE)) {
+ const value = match[0];
+ if (!looksHighEntropy(value)) continue;
+ take({
+ start: match.index,
+ end: match.index + value.length,
+ value,
+ kind: 'secret',
+ shape: 'high-entropy',
+ reveal: NOTHING,
+ });
+ }
+
+ return found.sort((a, b) => a.start - b.start);
+}
+
+/** The first defined capture group is the secret; with no groups, the whole match is. */
+function secretIn(match: RegExpExecArray | RegExpMatchArray): { start: number; end: number; value: string } | null {
+ if (match.index === undefined) return null;
+ const captured = match.slice(1).find((group) => group !== undefined);
+ if (captured === undefined) {
+ return { start: match.index, end: match.index + match[0].length, value: match[0] };
+ }
+ if (!captured) return null;
+ const offset = match[0].lastIndexOf(captured);
+ if (offset < 0) return null;
+ return { start: match.index + offset, end: match.index + offset + captured.length, value: captured };
+}
+
+function looksHighEntropy(value: string): boolean {
+ if (value.length < 32) return false;
+ if (UUID.test(value)) return false;
+ if (/^[0-9a-f]+$/i.test(value)) return false;
+ if (!/[a-z]/.test(value) || !/[A-Z]/.test(value) || !/[0-9]/.test(value)) return false;
+ return entropy(value) >= ENTROPY_BITS && caseFlips(value) >= CASE_FLIPS;
+}
+
+export function caseFlips(value: string): number {
+ const letters = value.replace(/[^A-Za-z]/g, '');
+ if (letters.length < 2) return 0;
+ let flips = 0;
+ for (let at = 1; at < letters.length; at += 1) {
+ if (isUpper(letters[at]) !== isUpper(letters[at - 1])) flips += 1;
+ }
+ return flips / (letters.length - 1);
+}
+
+const isUpper = (char: string) => char === char.toUpperCase();
+
+export function entropy(value: string): number {
+ const counts = new Map<string, number>();
+ for (const char of value) counts.set(char, (counts.get(char) ?? 0) + 1);
+ let bits = 0;
+ for (const count of counts.values()) {
+ const p = count / value.length;
+ bits -= p * Math.log2(p);
+ }
+ return bits;
+}
+
+export function rangesOf(text: string, pattern: RegExp): Range[] {
+ return [...text.matchAll(pattern)].map((match) => ({ start: match.index, end: match.index + match[0].length }));
+}
+
+function overlaps(claimed: readonly Range[], span: Range): boolean {
+ return claimed.some((range) => span.start < range.end && range.start < span.end);
+}
diff --git a/lib/secrets/index.ts b/lib/secrets/index.ts
new file mode 100644
index 0000000..8b8db33
--- /dev/null
+++ b/lib/secrets/index.ts
@@ -0,0 +1,33 @@
+/**
+ * The deterministic sanitizer, shared by both sides of the socket.
+ *
+ * shapes.ts what a secret looks like — patterns, labels, what may be revealed
+ * detect.ts finding them in a string, including the entropy gate
+ * seal.ts the handle grammar, sealing a value, releasing one back
+ * release.ts the two fields a secret may become plaintext in
+ * stream.ts sealing text that arrives in deltas
+ *
+ * Nothing here holds a secret. The vault that does lives in the extension
+ * (`lib/bridge/secret-vault.ts`) and only there, so the daemon — which spawns an agent
+ * CLI and talks to MCP clients — never has a plaintext credential to leak.
+ */
+
+export { caseFlips, entropy, findSecrets, type Range, type Span } from './detect';
+export { EXPIRED_MESSAGE, REFUSED_MESSAGE, RELEASE_FIELDS, releasableFields, releaseInput, type Release } from './release';
+export {
+ CLOSE,
+ OPEN,
+ handleFor,
+ handlesIn,
+ releaseText,
+ sealText,
+ sealValue,
+ sealedHandles,
+ type Handle,
+ type Mint,
+ type SealOptions,
+ type Sealed,
+ type SealedFinding,
+} from './seal';
+export { NOTHING, SECRET_WORDS, SHAPES, kindForKey, looksLikeCredential, notAPlaceholder, type Reveal, type SecretKind, type Shape } from './shapes';
+export { streamSealer, type StreamSealer } from './stream';
diff --git a/lib/secrets/release.ts b/lib/secrets/release.ts
new file mode 100644
index 0000000..52707e0
--- /dev/null
+++ b/lib/secrets/release.ts
@@ -0,0 +1,80 @@
+/**
+ * Where a sealed secret is allowed to become plaintext again.
+ *
+ * One list, and it is short on purpose: the fields that type into a page. A secret
+ * released into a URL, a selector or a search box has left the browser, which is the
+ * exact thing the seal exists to prevent — so a handle anywhere else is refused rather
+ * than quietly passed through as a placeholder, because a form filled with `⟦…⟧` fails
+ * in a way nobody can read.
+ *
+ * The release happens in the extension, one hop before the content script, so the
+ * plaintext exists only in the message that carries it into the page. It is never in a
+ * tool result, never in a transcript, and never on the daemon's side of the socket.
+ */
+
+import { handlesIn, releaseText, type Handle } from './seal';
+
+export const RELEASE_FIELDS: Readonly<Record<string, readonly string[]>> = {
+ 'page.fillInput': ['value'],
+ 'page.typeText': ['text'],
+};
+
+export const REFUSED_MESSAGE =
+ 'A sealed secret can only be released into page.fillInput “value” or page.typeText “text”. ' +
+ 'Browsentic swaps the placeholder for the real value at the moment it reaches the page, so the secret is never ' +
+ 'yours to move: pass the placeholder through unchanged and let the field it belongs in do it.';
+
+export const EXPIRED_MESSAGE =
+ 'That sealed secret is no longer held — it expired, or it was read in an earlier browser session. ' +
+ 'Read the value from the page again, or ask the user for it.';
+
+export function releasableFields(action: string): readonly string[] {
+ return RELEASE_FIELDS[action] ?? [];
+}
+
+export interface Release {
+ readonly input: unknown;
+ readonly released: Handle[];
+ /** Handles sitting in a field that may not carry one. */
+ readonly refused: Handle[];
+ /** Ours by shape but not by tag, or gone from the vault. */
+ readonly unresolved: Handle[];
+}
+
+export function releaseInput(
+ action: string,
+ input: unknown,
+ tag: string,
+ resolve: (handle: Handle) => string | null,
+): Release {
+ const allowed = releasableFields(action);
+ const released: Handle[] = [];
+ const refused: Handle[] = [];
+ const unresolved: Handle[] = [];
+
+ if (!input || typeof input !== 'object' || Array.isArray(input)) {
+ return { input, released, refused: handlesAnywhere(input, refused), unresolved };
+ }
+
+ const out: Record<string, unknown> = {};
+ for (const [key, value] of Object.entries(input as Record<string, unknown>)) {
+ if (allowed.includes(key) && typeof value === 'string') {
+ const result = releaseText(value, tag, resolve);
+ released.push(...result.released);
+ unresolved.push(...result.unresolved);
+ out[key] = result.text;
+ continue;
+ }
+ handlesAnywhere(value, refused);
+ out[key] = value;
+ }
+ return { input: out, released, refused, unresolved };
+}
+
+function handlesAnywhere(value: unknown, into: Handle[], depth = 0): Handle[] {
+ if (typeof value === 'string') into.push(...handlesIn(value));
+ else if (depth < 12 && value && typeof value === 'object') {
+ for (const nested of Object.values(value as Record<string, unknown>)) handlesAnywhere(nested, into, depth + 1);
+ }
+ return into;
+}
diff --git a/lib/secrets/seal.ts b/lib/secrets/seal.ts
new file mode 100644
index 0000000..de57aed
--- /dev/null
+++ b/lib/secrets/seal.ts
@@ -0,0 +1,227 @@
+/**
+ * Sealing: turning a found secret into a placeholder that says what it was without
+ * being it, and back again at the one place it is allowed to become plaintext.
+ *
+ * A handle reads `⟦kind:id@host#tag⟧`. Everything in it is public — the kind and the
+ * host are what make a truncated value still useful to reason about — except the tag,
+ * which is minted once per browser session and never rendered anywhere a page can read
+ * it. That is the whole trick: a page can author the brackets, but it cannot author the
+ * tag, so a page-planted handle resolves to nothing. Sealing in strict mode also
+ * rewrites any bracket that is not one of our own handles, so a forgery does not even
+ * survive the trip out of the page.
+ *
+ * Sealing is idempotent. An already-sealed handle is an immune range, never rescanned,
+ * which is what lets the extension seal on the way out and the daemon seal again on the
+ * way through without the second pass mangling the first.
+ */
+
+import { findSecrets, rangesOf, type Range } from './detect';
+import { NOTHING, kindForKey, notAPlaceholder, type Reveal, type SecretKind } from './shapes';
+
+export const OPEN = '⟦';
+export const CLOSE = '⟧';
+
+const ANY_HANDLE = /⟦([a-z-]+):([0-9a-z]+)(?:@([A-Za-z0-9._:\[\]-]{1,255}))?#([0-9a-f]{6,32})⟧/g;
+
+export interface Handle {
+ readonly kind: SecretKind;
+ readonly id: string;
+ readonly origin?: string;
+ readonly tag: string;
+ readonly text: string;
+}
+
+export interface SealedFinding {
+ readonly kind: SecretKind;
+ readonly shape: string;
+ readonly handle: string;
+}
+
+/** Mints the handle for one found secret. The caller owns the id space and the vault. */
+export type Mint = (value: string, kind: SecretKind, shape: string) => string;
+
+export interface SealOptions {
+ readonly mint: Mint;
+ /**
+ * Our own tag. Given, sealing is strict: only our handles survive and every other
+ * bracket is rewritten. Omitted, any well-formed handle passes through untouched —
+ * what a downstream sealer wants, since it is not the one that minted them.
+ */
+ readonly tag?: string;
+}
+
+export interface Sealed<T> {
+ readonly value: T;
+ readonly found: SealedFinding[];
+}
+
+export function handleFor(part: { kind: SecretKind; id: string; origin?: string }, tag: string): string {
+ const origin = part.origin ? `@${part.origin}` : '';
+ return `${OPEN}${part.kind}:${part.id}${origin}#${tag}${CLOSE}`;
+}
+
+export function handlesIn(text: string, tag?: string): Handle[] {
+ if (!text.includes(OPEN)) return [];
+ return [...text.matchAll(ANY_HANDLE)]
+ .map((match) => ({
+ kind: match[1] as SecretKind,
+ id: match[2],
+ origin: match[3],
+ tag: match[4],
+ text: match[0],
+ }))
+ .filter((handle) => !tag || handle.tag === tag);
+}
+
+/** Every handle anywhere in a JSON value — what a policy decision reads. */
+export function sealedHandles(value: unknown, tag?: string): Handle[] {
+ const found: Handle[] = [];
+ walk(value, 0, (text) => {
+ found.push(...handlesIn(text, tag));
+ return text;
+ });
+ return found;
+}
+
+export function sealText(text: string, options: SealOptions): Sealed<string> {
+ if (!text || text.length < 4) return { value: text, found: [] };
+
+ const immune = ourHandles(text, options.tag);
+ const source = options.tag ? neutralize(text, immune) : text;
+ const spans = findSecrets(source, immune);
+ if (!spans.length) return { value: source, found: [] };
+
+ const found: SealedFinding[] = [];
+ let out = '';
+ let cursor = 0;
+ for (const span of spans) {
+ const handle = options.mint(span.value, span.kind, span.shape);
+ found.push({ kind: span.kind, shape: span.shape, handle });
+ out += source.slice(cursor, span.start) + truncate(span.value, span.reveal, handle);
+ cursor = span.end;
+ }
+ return { value: out + source.slice(cursor), found };
+}
+
+/**
+ * Keys whose value is a round-trip token the agent has to hand back verbatim. Sealing a
+ * selector would break targeting and report it as a refused secret, which reads as a bug
+ * rather than as a policy.
+ */
+const STRUCTURAL_KEYS = new Set(['selector']);
+
+const MIN_KEYED = 4;
+
+/**
+ * Seal every string in a value tree. Two ways in: a string that carries a secret inside
+ * it, and a string that *is* one because of the key it hangs off. The second is what a
+ * walked result needs — `{ password: "hunter2" }` has no label in any string being
+ * scanned, so nothing but the key says what it is.
+ */
+export function sealValue<T>(value: T, options: SealOptions): Sealed<T> {
+ const found: SealedFinding[] = [];
+
+ const keyed = (text: string, kind: SecretKind): string => {
+ const whole = findSecrets(text).find((span) => span.start === 0 && span.end === text.length);
+ const known = whole ? { kind: whole.kind, shape: whole.shape, reveal: whole.reveal } : { kind, shape: 'keyed', reveal: NOTHING };
+ const handle = options.mint(text, known.kind, known.shape);
+ found.push({ kind: known.kind, shape: known.shape, handle });
+ return truncate(text, known.reveal, handle);
+ };
+
+ const visit = (node: unknown, depth: number, kind: SecretKind | null): unknown => {
+ if (typeof node === 'string') {
+ if (node.startsWith('data:')) return node;
+ if (kind && node.length >= MIN_KEYED && notAPlaceholder(node) && !handlesIn(node).length) return keyed(node, kind);
+ const sealed = sealText(node, options);
+ found.push(...sealed.found);
+ return sealed.value;
+ }
+ if (depth >= MAX_DEPTH || node === null || typeof node !== 'object') return node;
+ if (Array.isArray(node)) return node.map((item) => visit(item, depth + 1, kind));
+ const out: Record<string, unknown> = {};
+ for (const [name, nested] of Object.entries(node as Record<string, unknown>)) {
+ out[name] = STRUCTURAL_KEYS.has(name) ? nested : visit(nested, depth + 1, kindForKey(name));
+ }
+ return out;
+ };
+
+ return { value: visit(value, 0, null) as T, found };
+}
+
+/**
+ * Substitute our own handles for the plaintext they stand for. `resolve` returning null
+ * leaves the handle in place and reports it, so the caller can refuse rather than type a
+ * placeholder into someone's login form.
+ */
+export function releaseText(
+ text: string,
+ tag: string,
+ resolve: (handle: Handle) => string | null,
+): { text: string; released: Handle[]; unresolved: Handle[] } {
+ const released: Handle[] = [];
+ const unresolved: Handle[] = [];
+ const out = text.replace(ANY_HANDLE, (match, kind, id, origin, found) => {
+ const handle: Handle = { kind, id, origin, tag: found, text: match };
+ if (found !== tag) {
+ unresolved.push(handle);
+ return match;
+ }
+ const plain = resolve(handle);
+ if (plain === null) {
+ unresolved.push(handle);
+ return match;
+ }
+ released.push(handle);
+ return plain;
+ });
+ return { text: out, released, unresolved };
+}
+
+/**
+ * `head…⟦handle⟧…tail`, with the ellipsis only on a side that kept something. What
+ * survives is the vendor's format marker or a card's last four — never entropy.
+ */
+function truncate(value: string, reveal: Reveal, handle: string): string {
+ const room = Math.max(0, value.length - 4);
+ const head = value.slice(0, Math.min(reveal.head, room));
+ const tail = reveal.tail && value.length - reveal.tail > head.length ? value.slice(-reveal.tail) : '';
+ return `${head}${head ? '…' : ''}${handle}${tail ? '…' : ''}${tail}`;
+}
+
+function ourHandles(text: string, tag?: string): Range[] {
+ if (!text.includes(OPEN)) return [];
+ return [...text.matchAll(ANY_HANDLE)]
+ .filter((match) => !tag || match[4] === tag)
+ .map((match) => ({ start: match.index, end: match.index + match[0].length }));
+}
+
+/** Rewrite every bracket that is not one of our handles, so a page cannot author one. */
+function neutralize(text: string, immune: readonly Range[]): string {
+ if (!text.includes(OPEN) && !text.includes(CLOSE)) return text;
+ const inside = (at: number) => immune.some((range) => at >= range.start && at < range.end);
+ let out = '';
+ for (let at = 0; at < text.length; at += 1) {
+ const char = text[at];
+ if (inside(at)) out += char;
+ else if (char === OPEN) out += '⟨';
+ else if (char === CLOSE) out += '⟩';
+ else out += char;
+ }
+ return out;
+}
+
+const MAX_DEPTH = 12;
+
+function walk(value: unknown, depth: number, onText: (text: string) => string): unknown {
+ if (typeof value === 'string') return value.startsWith('data:') ? value : onText(value);
+ if (depth >= MAX_DEPTH || value === null || typeof value !== 'object') return value;
+ if (Array.isArray(value)) return value.map((item) => walk(item, depth + 1, onText));
+ const out: Record<string, unknown> = {};
+ for (const [key, nested] of Object.entries(value as Record<string, unknown>)) {
+ out[key] = walk(nested, depth + 1, onText);
+ }
+ return out;
+}
+
+export { rangesOf };
diff --git a/lib/secrets/shapes.ts b/lib/secrets/shapes.ts
new file mode 100644
index 0000000..3b094cb
--- /dev/null
+++ b/lib/secrets/shapes.ts
@@ -0,0 +1,191 @@
+/**
+ * What counts as a secret, as data.
+ *
+ * The detector is deliberately dumb: a closed list of patterns, a label vocabulary and
+ * one entropy gate. No model, no heuristic that depends on what was asked — the same
+ * text always yields the same findings, on both sides of the socket, which is the only
+ * way a client-side seal and a daemon-side seal can agree about what is already sealed.
+ *
+ * `reveal` is the interesting field. Truncating from the middle is useful to a reader
+ * only if what survives says something, and the only characters that say something
+ * without giving anything away are the ones a vendor puts there as a format marker:
+ * `sk-ant-`, `ghp_`, `AKIA`. Those are public by construction. Everything else — a
+ * password, a cookie, a bare high-entropy blob — reveals nothing, because four
+ * characters of a password is four characters of a password.
+ */
+
+import { looksLikeCardNumber } from '@/lib/recordings/events';
+
+export type SecretKind = 'api-key' | 'token' | 'jwt' | 'password' | 'cookie' | 'private-key' | 'card' | 'secret';
+
+export interface Reveal {
+ /** Leading characters that are a public format marker, not entropy. */
+ readonly head: number;
+ readonly tail: number;
+}
+
+export interface Shape {
+ readonly id: string;
+ readonly kind: SecretKind;
+ /** Global. When it captures, the first defined capture group is the secret. */
+ readonly pattern: RegExp;
+ /** Lowercase substring the text must contain before the pattern is worth running. */
+ readonly guard?: string;
+ readonly reveal?: Reveal;
+ readonly validate?: (value: string) => boolean;
+}
+
+export const NOTHING: Reveal = { head: 0, tail: 0 };
+
+/**
+ * The label vocabulary, as word parts. Both readers derive from it and cannot drift:
+ * `labelled()` joins the parts with an optional separator to find `api_key: …` inside a
+ * string, and `kindForKey()` joins them bare to recognise `apiKey` as an object key. The
+ * second reader is the one that matters client-side, where a result is walked as a value
+ * tree and `{ password: "hunter2" }` has no label anywhere in the string being scanned.
+ */
+type Word = readonly string[];
+
+const PASSWORD_WORDS: readonly Word[] = [
+ ['pass', 'word'],
+ ['pass', 'wd'],
+ ['pass', 'phrase'],
+ ['pass', 'code'],
+ ['pwd'],
+ ['otp'],
+ ['one', 'time', 'code'],
+];
+
+const TOKEN_WORDS: readonly Word[] = [
+ ['secret'],
+ ['token'],
+ ['api', 'key'],
+ ['access', 'key'],
+ ['access', 'token'],
+ ['secret', 'key'],
+ ['client', 'secret'],
+ ['refresh', 'token'],
+ ['auth', 'token'],
+ ['authorization'],
+ ['bearer'],
+ ['credential'],
+ ['credentials'],
+ ['signing', 'key'],
+ ['private', 'key'],
+ ['connection', 'string'],
+];
+
+const COOKIE_WORDS: readonly Word[] = [
+ ['cookie'],
+ ['session', 'id'],
+ ['session', 'key'],
+ ['session', 'token'],
+ ['csrf', 'token'],
+ ['xsrf', 'token'],
+];
+
+const inline = (words: readonly Word[]) => words.map((word) => word.join(String.raw`[_\-\s]?`)).join('|');
+
+const PASSWORD_LABEL = inline(PASSWORD_WORDS);
+const TOKEN_LABEL = inline(TOKEN_WORDS);
+const COOKIE_LABEL = inline(COOKIE_WORDS);
+
+const KEY_WORDS: readonly (readonly [SecretKind, readonly Word[]])[] = [
+ ['password', PASSWORD_WORDS],
+ ['token', TOKEN_WORDS],
+ ['cookie', COOKIE_WORDS],
+];
+
+/**
+ * The kind an object key names, or null. Matched on the key with its separators removed,
+ * so `newPassword`, `new_password` and `NEW-PASSWORD` all read the same.
+ */
+export function kindForKey(key: string): SecretKind | null {
+ const normalized = key.toLowerCase().replace(/[^a-z0-9]/g, '');
+ if (!normalized) return null;
+ const forms = normalized.endsWith('s') ? [normalized, normalized.slice(0, -1)] : [normalized];
+ for (const [kind, words] of KEY_WORDS) {
+ if (words.some((word) => forms.some((form) => form.endsWith(word.join(''))))) return kind;
+ }
+ return null;
+}
+
+/** Every label in canonical form, for docs and for the check that the two readers agree. */
+export const SECRET_WORDS: readonly string[] = [...PASSWORD_WORDS, ...TOKEN_WORDS, ...COOKIE_WORDS].map((word) =>
+ word.join('_'),
+);
+
+/** Quoted or bare, with the scheme words a header puts in front of the value stripped off. */
+const VALUE = String.raw`(?:Bearer\s+|Basic\s+|Token\s+)?(?:"([^"\r\n]{4,400})"|'([^'\r\n]{4,400})'|([^\s,;&"'<>{}\[\]]{4,400}))`;
+
+const labelled = (label: string) =>
+ new RegExp(String.raw`(?<![A-Za-z0-9])(?:${label})["']?\s*[:=]\s*${VALUE}`, 'gi');
+
+/**
+ * The same labels joined by an English verb rather than a colon, because that is how a
+ * page actually hands someone a credential: “your temporary password is …”. The value
+ * runs to whitespace and may hold the punctuation a password holds, but not the
+ * punctuation a sentence ends on.
+ */
+const PROSE_VALUE = String.raw`(?:"([^"\r\n]{4,400})"|'([^'\r\n]{4,400})'|([^\s"'<>]{3,399}[^\s"'<>.,;:!?]))`;
+
+const prose = (label: string) =>
+ new RegExp(String.raw`(?<![A-Za-z0-9])(?:${label})\s+(?:is|are|was|will\s+be)\s*:?\s+${PROSE_VALUE}`, 'gi');
+
+/**
+ * Prose is mostly ordinary words, so a value that follows “password is” only counts when
+ * it looks unlike one: a digit, a symbol a password uses, or a case change mid-word.
+ * “The password is required” stays a sentence.
+ */
+const CREDENTIAL_SIGNAL = /\d|[!@#$%^&*()_+=\[\]{}|\\<>~/&]|[a-z][A-Z]/;
+
+export function looksLikeCredential(value: string): boolean {
+ return value.length >= 6 && notAPlaceholder(value) && CREDENTIAL_SIGNAL.test(value);
+}
+
+/**
+ * Values that occupy a secret's slot without being one. Left in place so a page that
+ * says `password: ********` still reads as a page that says nothing.
+ */
+const PLACEHOLDER =
+ /^(?:null|nil|none|true|false|undefined|n\/?a|empty|blank|test|demo|example|sample|changeme|hidden|redacted|your[-_\s].*|my[-_\s].*|x{3,}|\*+|•+|\.{3,}|…+|-+|_+|\[[^\]]*\]|<[^>]*>|\{\{.*\}\}|\$\{.*\})$/i;
+
+export function notAPlaceholder(value: string): boolean {
+ if (PLACEHOLDER.test(value)) return false;
+ if (/^(.)\1*$/.test(value)) return false;
+ return !value.includes('…');
+}
+
+export const SHAPES: readonly Shape[] = [
+ {
+ id: 'private-key',
+ kind: 'private-key',
+ guard: '-----begin',
+ pattern: /-----BEGIN(?:[A-Z ]{0,32})PRIVATE KEY-----[A-Za-z0-9+/=\s]{0,8000}-----END(?:[A-Z ]{0,32})PRIVATE KEY-----/g,
+ },
+ { id: 'jwt', kind: 'jwt', guard: 'eyj', pattern: /\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{6,}\.[A-Za-z0-9_-]{6,}/g },
+
+ { id: 'anthropic-key', kind: 'api-key', guard: 'sk-ant-', pattern: /\bsk-ant-[A-Za-z0-9_-]{16,}/g, reveal: { head: 7, tail: 0 } },
+ { id: 'openai-key', kind: 'api-key', guard: 'sk-', pattern: /\bsk-(?:proj-|svcacct-|admin-)?[A-Za-z0-9_-]{20,}/g, reveal: { head: 3, tail: 0 } },
+ { id: 'google-key', kind: 'api-key', guard: 'aiza', pattern: /\bAIza[0-9A-Za-z_-]{35}\b/g, reveal: { head: 4, tail: 0 } },
+ { id: 'aws-access-key', kind: 'api-key', pattern: /\b(?:AKIA|ASIA|AIDA|AROA|AGPA|ANPA)[0-9A-Z]{16}\b/g, reveal: { head: 4, tail: 0 } },
+ { id: 'github-pat', kind: 'token', guard: 'github_pat_', pattern: /\bgithub_pat_[A-Za-z0-9_]{40,}/g, reveal: { head: 11, tail: 0 } },
+ { id: 'github-token', kind: 'token', guard: 'gh', pattern: /\bgh[pousr]_[A-Za-z0-9]{30,}/g, reveal: { head: 4, tail: 0 } },
+ { id: 'slack-token', kind: 'token', guard: 'xox', pattern: /\bxox[abposr]-[A-Za-z0-9-]{10,}/g, reveal: { head: 4, tail: 0 } },
+ { id: 'stripe-key', kind: 'api-key', guard: 'k_', pattern: /\b[rs]k_(?:live|test)_[A-Za-z0-9]{16,}/g, reveal: { head: 8, tail: 0 } },
+ { id: 'npm-token', kind: 'token', guard: 'npm_', pattern: /\bnpm_[A-Za-z0-9]{36}\b/g, reveal: { head: 4, tail: 0 } },
+ { id: 'gitlab-token', kind: 'token', guard: 'glpat-', pattern: /\bglpat-[A-Za-z0-9_-]{20,}/g, reveal: { head: 6, tail: 0 } },
+ { id: 'sendgrid-key', kind: 'api-key', guard: 'sg.', pattern: /\bSG\.[A-Za-z0-9_-]{16,}\.[A-Za-z0-9_-]{16,}/g, reveal: { head: 3, tail: 0 } },
+
+ { id: 'basic-auth', kind: 'password', guard: '@', pattern: /\bhttps?:\/\/[^\s/:@]{1,64}:([^\s/@]{3,128})@/g },
+ { id: 'cookie-header', kind: 'cookie', guard: 'cookie', pattern: /(?:^|\n)[ \t]*(?:set-)?cookie[ \t]*:[ \t]*([^\r\n]{4,4000})/gi },
+
+ { id: 'labelled-password', kind: 'password', pattern: labelled(PASSWORD_LABEL), validate: notAPlaceholder },
+ { id: 'labelled-token', kind: 'token', pattern: labelled(TOKEN_LABEL), validate: notAPlaceholder },
+ { id: 'labelled-cookie', kind: 'cookie', pattern: labelled(COOKIE_LABEL), validate: notAPlaceholder },
+
+ { id: 'prose-password', kind: 'password', pattern: prose(PASSWORD_LABEL), validate: looksLikeCredential },
+ { id: 'prose-token', kind: 'token', pattern: prose(TOKEN_LABEL), validate: looksLikeCredential },
+
+ { id: 'card', kind: 'card', pattern: /\b\d(?:[ -]?\d){12,18}\b/g, reveal: { head: 0, tail: 4 }, validate: looksLikeCardNumber },
+];
diff --git a/lib/secrets/stream.ts b/lib/secrets/stream.ts
new file mode 100644
index 0000000..6a7ec13
--- /dev/null
+++ b/lib/secrets/stream.ts
@@ -0,0 +1,67 @@
+/**
+ * Sealing text that arrives a few characters at a time.
+ *
+ * A model streams `sk-ant-` in one delta and the rest of the key in the next. Sealing
+ * each delta on its own finds neither half, so the sealer holds back the tail of what
+ * it has until enough has arrived to be sure a secret is not straddling the edge, and
+ * only cuts at a boundary a secret cannot contain.
+ *
+ * It also refuses to cut immediately after a label: `password:` emitted alone would
+ * leave the value to be scanned later with nothing to identify it.
+ */
+
+const HOLD = 256;
+const MAX_HOLD = 2_048;
+const LABEL_TAIL = /[\w-]{2,32}["']?\s*[:=]\s*$/;
+const PEM = '-----BEGIN';
+
+export interface StreamSealer {
+ push(delta: string): string;
+ flush(): string;
+}
+
+export function streamSealer(seal: (text: string) => string): StreamSealer {
+ let held = '';
+
+ return {
+ push(delta) {
+ held += delta;
+ const cut = cutPoint(held);
+ if (cut <= 0) return '';
+ const out = held.slice(0, cut);
+ held = held.slice(cut);
+ return seal(out);
+ },
+ flush() {
+ if (!held) return '';
+ const out = held;
+ held = '';
+ return seal(out);
+ },
+ };
+}
+
+function cutPoint(held: string): number {
+ const limit = held.length - HOLD;
+ if (limit <= 0) return 0;
+
+ let cut = held.lastIndexOf('\n', limit);
+ if (cut < 0) {
+ if (held.length <= MAX_HOLD) return 0;
+ cut = lastWhitespace(held, limit);
+ if (cut < 0) return limit;
+ }
+
+ const label = LABEL_TAIL.exec(held.slice(Math.max(0, cut - 48), cut));
+ if (label) cut = Math.max(0, cut - 48) + label.index;
+
+ const begin = held.lastIndexOf(PEM);
+ if (begin >= 0 && begin < cut && !held.includes('-----END', begin)) cut = begin;
+
+ return cut > 0 ? cut : 0;
+}
+
+function lastWhitespace(held: string, limit: number): number {
+ for (let at = limit; at > 0; at -= 1) if (/\s/.test(held[at])) return at;
+ return -1;
+}