<!-- Generated by scripts/ax-docs.mts from the JSDoc in registry/ouro/ax/. Do not edit; run `pnpm run docs`. -->

# ax-redact

Redaction for a diagnostics bundle: what leaves the computer for an agent to read or attach keeps categories, counts, times, versions and the tool's own words, and drops tokens, cookies, ids, email addresses, paths in a person's home and what anyone wrote. `redactText` replaces each shape, and `leaks` checks that none is left, which ax-bundle checks before it writes.

```sh
npx shadcn@latest add ourostack/ouro-ui/ax-redact#v1.3.344
```

It installs `lib/ouro/ax/redact.ts`. Its tests are `ax-redact-tests`. Every item runs on Node 22.18 or later as it is copied: the files import each other as `./<file>.ts`. The [Ouro AX guide](ax.md) shows how they fit together.

## Exports

### `isPersonKey`

Whether a JSON key holds who someone is, whatever its value: `name`, `displayName`, `email`, `login`, `handle`, `userId`, `account`, `owner` and the like, by the key's last word.

```ts
function isPersonKey(key: string): boolean
```

Example:

```ts
isPersonKey("displayName"); // true
isPersonKey("version"); // false
```

### `isSecretKey`

Whether a JSON key holds a secret whatever its value: `token`, `refreshToken`, `cookie`, `sessionId`, `password`, `apiKey`, `authorization`, `sid` and the like.

```ts
function isSecretKey(key: string): boolean
```

Example:

```ts
isSecretKey("refresh_token"); // true
isSecretKey("state"); // false
```

### `leaks`

The shapes still in `text` that must never leave, by name; empty when it is clean. A bundle runs it over its whole text after redaction and refuses to write when it finds any (ax-bundle). An app's own `rules` count too.

```ts
function leaks(text: string, { rules }?: Pick<RedactOptions, "rules">): string[]
```

Example:

```ts
leaks("token=abc and jordan@contoso.com"); // ["secret", "email"]
leaks(redactText("token=abc and jordan@contoso.com")); // []
```

### `REDACT_RULES`

Each shape that must never leave in a bundle, with what it becomes. Order matters: whole tokens before their parts, and a URL before the email address its sign-in part would look like.

```ts
const REDACT_RULES: readonly RedactRule[]
```

### `redactEntries`

An object's entries with each value mapped and each key redacted as text, since a key can be an id or an address; two keys that come out the same get a number.

```ts
function redactEntries(v: object, value: (x: unknown, key: string) => unknown, opts?: RedactOptions): Record<string, unknown>
```

Example:

```ts
redactEntries({ "jordan@contoso.com": 3, "sam@contoso.com": 1 }, (n) => n); // { "[email]": 3, "[email] 2": 1 }
```

### `redactLine`

A log line: a JSON line by its values (`redactValue`), any other line as text (`redactText`).

```ts
function redactLine(line: string, opts?: RedactOptions): string
```

Example:

```ts
redactLine(`{"level":"info","event":"sign-in","email":"jordan@contoso.com"}`);
// '{"level":"info","event":"sign-in","email":"[text]"}'
```

### `RedactOptions`

`home` is the person's home folder, which becomes `~`. `rules` are an app's own shapes, such as its chat service's ids, run before the built-in ones; `leaks` reports any match of them left.

```ts
interface RedactOptions {
  home?: string;
  rules?: readonly RedactRule[];
}
```

### `RedactRule`

Redaction for a diagnostics bundle: what leaves the computer for an agent to read or attach keeps categories, counts, times, versions and the tool's own words, and drops tokens, cookies, ids, email addresses, paths in a person's home and what anyone wrote. `redactText` replaces each shape, and `leaks` checks that none is left, which ax-bundle checks before it writes.

```ts
interface RedactRule {
  name: string;
  re: RegExp;
  to: string | ((match: string, ...groups: string[]) => string);
}
```

Example:

```ts
redactText("GET https://api.example.com/v1/me?token=abc Authorization: Bearer eyJhbGciOi.eyJzdWIiOi.c2ln", { home: "/Users/jordan" });
// "GET https://api.example.com/… Authorization: [redacted]"
```

### `redactText`

Free text with every shape replaced by its category: `[token]`, `[redacted]`, `[email]`, `[id]`, `[opaque]`, `[private key]`, `[user]`, a URL cut to its host, and quoted words as `[text]`. The person's home folder becomes `~`. A line longer than 4,000 characters is cut at a space first, and one with no space that early becomes its length, so a huge log line takes no longer than a short one.

```ts
function redactText(s: string, { home, rules }?: RedactOptions): string
```

Example:

```ts
redactText(`signed in as jordan@contoso.com from /Users/jordan/Library`, { home: "/Users/jordan" });
// "signed in as [email] from ~/Library"
```

### `redactValue`

A JSON value with its numbers and booleans kept, and its keys redacted as text. A secret key's value becomes `"[redacted]"`, the value of a key for what someone wrote (`title`, `text`, `message` and the like) or who they are (`name`, `email`, `login` and the like) `"[text]"`, and any other string `"[text]"` unless it is one word: a word the rules leave alone (a time, a version, a code) is kept, and one they redact comes back redacted.

```ts
function redactValue(v: unknown, opts?: RedactOptions, key?: string): unknown
```

Example:

```ts
redactValue({ level: "warn", at: "2026-11-17T19:57:02Z", token: "abc", title: "Plans", n: 3 });
// { level: "warn", at: "2026-11-17T19:57:02Z", token: "[redacted]", title: "[text]", n: 3 }
```
