redac---n 0.0.0-stage → 0.0.2

package/dist/types.d.ts

@@ -0,0 +1,81 @@
+/** One secret found in a text: where it is, what it is, and which rule found it. */
+export interface Finding {
+    /** Where the secret starts in the text passed in, in UTF-16 code units. */
+    start: number;
+    /** Where it ends (exclusive). */
+    end: number;
+    /** What the secret is, shown in the placeholder: "GitHub token", "password", "private key". */
+    kind: string;
+    /** The rule that found it, `layer:rule` (`format:GitHub token`, `named:assign`, `known`), for debugging and evaluation. */
+    rule: string;
+    /**
+     * How sure the rule is, 0 to 1. Formats and whole known values are 1; a known value found by one end, 0.95. A finding
+     * of 0.9 or more may be learned and hidden wherever its value turns up again (spans.ts isLearnable: not a guess, 8
+     * characters or more); one below is hidden only where found.
+     */
+    confidence: number;
+    /** The name the value sat under, when a rule read one (`DB_PASSWORD`, `apiKey`). */
+    name?: string;
+    /** Whether the rule read the value where only a literal can stand (an env line, YAML, XML text, a CLI flag). */
+    literal?: boolean;
+    /**
+     * From `detect`: the secret as the program reads it, where that differs from the text the span covers (a known
+     * value written another way, a literal split in pieces joined, `"xoxb-12" "34ab"`, invisible characters dropped,
+     * a JSON escape decoded). May be unset; then the secret is the text the span covers.
+     */
+    value?: string;
+}
+/** Where a text came from, which changes what counts as a secret in it. */
+export interface Hint {
+    /** The shell command whose output this is. `cat .env` makes the whole output a secret file. */
+    command?: string;
+    /** The file this text was read from. `.env`, `id_rsa`, `credentials.json` are secret files. */
+    path?: string;
+    /**
+     * The text is a secret file's contents, whatever its path or command says: for a caller that knows by rules of its
+     * own (a configured secrets directory, `deploy/prod.conf`). Read as `cat .env` output is.
+     */
+    secretFile?: boolean;
+}
+export type Guessing = "off" | "confident" | "eager";
+/** What one call is told about its text: where it came from, and how much to guess. */
+export interface DetectOptions {
+    hint?: Hint;
+    /** Overrides the redactor's `guessing` for this call. */
+    guessing?: Guessing;
+}
+export interface RedactOptions {
+    /**
+     * How hard to guess at random-looking tokens that have no name or format next to them, the one thing a model
+     * decides; every rule runs whatever this says (known values, formats, structure, credential names, secret files
+     * and commands, encoded secrets).
+     * - "off": no guesses. (In a secret file, the hint's or one written inside the text, the model always sorts the
+     *   values under neutral names into generated ones, hidden, and settings, kept: the hint already says secrets are
+     *   there.)
+     * - "confident" (default): tokens the model is confident about: in a key-like context, or long ones anywhere.
+     * - "eager": shorter and less certain ones too, accepting more false redactions.
+     */
+    guessing?: Guessing;
+    /**
+     * Password hashes (bcrypt, argon2, crypt, SCRAM, LDAP, MySQL, Postgres): "keep" (default) leaves them,
+     * as most labelled data does; "hide" redacts them whole, since a weak password's hash can be cracked
+     * offline.
+     */
+    hashes?: "keep" | "hide";
+    /**
+     * Values that are secret wherever they appear, in every encoding: credentials the caller holds, each with a label
+     * for its placeholders. Values are trimmed. Empty entries are skipped, and so are values too short or ordinary to
+     * hide everywhere (under 6 characters, letters only and under 14, digits only and up to 8 digits) or over 16,384
+     * characters: `addKnown` returns false for those.
+     */
+    known?: Iterable<string | {
+        value: string;
+        label?: string;
+    } | undefined | null>;
+    /**
+     * Builds the text that replaces a secret, from its finding and its value as the program reads it (decoded where it
+     * was escaped). Default: `[REDACTED <kind> #<fingerprint>]`; `redactor.fingerprint(value)` gives the tag. Its text
+     * must not look like a secret itself.
+     */
+    placeholder?: (finding: Finding, value: string) => string;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/unnamed.d.ts

@@ -0,0 +1,59 @@
+import { type Context, Doc } from "./context.ts";
+import { type Alphabet } from "./random.ts";
+import type { Finding, Guessing } from "./types.ts";
+export interface Candidate {
+    start: number;
+    end: number;
+    token: string;
+    /**
+     * What the run had before the token that the token drops (`_`, `-`, `+`, `=`): its context is read from before it,
+     * as `Client("` and not `Client("_`.
+     */
+    lead?: string;
+}
+/**
+ * Runs of token characters long enough to be a key. A run that is a path (`/api/v1/<id>/users`) or
+ * dotted (`a.b.c`) is split into its segments, each judged alone. A percent-encoded run that decodes to one token is
+ * judged whole, as its decoded value (`token` then differs from the text it spans); its pieces between the escapes
+ * aren't judged apart.
+ */
+export declare function candidates(text: string): Candidate[];
+export interface Features {
+    token: string;
+    alphabet: Alphabet;
+    length: number;
+    natural: number;
+    entropyZ: number;
+    switches: number;
+    digits: number;
+    upper: number;
+    lower: number;
+    vendorPrefix: boolean;
+    decodes: "text" | "binary" | "none";
+    hashSize: boolean;
+    leftHashy: boolean;
+    ctx: Context;
+    /** What the token dropped from the front of its run (Candidate.lead); its context's left side ends before it. */
+    lead: string;
+    secretFile: boolean;
+}
+export declare function features(doc: Doc, c: Candidate, secretFile: boolean): Features;
+/**
+ * Why the value at `[start, end)` is public by design, by the vetoes in PUBLIC_VETOES; undefined if none says so. Only
+ * of a value the random layer would judge, one run of token characters as long as MIN_TOKEN, which they're written for.
+ */
+export declare function publicReason(doc: Doc, start: number, end: number): string | undefined;
+/** Every hard rule that rules the candidate out (see VETOES), by its reason: for tracing, where vetoed() stops at the first. */
+export declare function vetoes(f: Features): string[];
+/** The first hard rule that rules the candidate out, or undefined. */
+export declare function vetoed(f: Features, { statistical }?: {
+    statistical?: boolean | undefined;
+}): string | undefined;
+/** The model's probability that the candidate is a secret: boosted trees trained by scripts/train-unnamed.py. */
+export declare function score(f: Features): number;
+export declare function vector(f: Features): number[];
+/** The model's inputs by name, as vector() gives them. */
+export declare function namedVector(f: Features): Record<string, number>;
+/** The score a token needs to be hidden; undefined where nothing is guessed ("off", outside a secret file). */
+export declare function thresholdFor(guessing: Guessing, secretFile: boolean): number | undefined;
+export declare function findUnnamed(text: string, taken: (start: number, end: number) => boolean, guessing: Guessing, secretFile: boolean, without?: ReadonlySet<string>): Finding[];