redac---n 0.0.0-stage → 0.0.2

package/dist/public.js

@@ -0,0 +1,362 @@
+/**
+ * What a value can be shown to be public or a stand-in by, whatever found it: keys published for browsers (a
+ * publishable key's format, a Google API key used client-side), values published as examples in specifications and
+ * documentation, placeholders and masked or truncated keys, JSON Web Tokens anyone can read or sign, and keys passed to
+ * browser and mobile SDKs. The detectors
+ * consult these to drop stand-ins early; the decision stage (policy.ts) to keep public values whoever proposed them.
+ */
+import { base64Binary } from "./base64.js";
+import { naturalness } from "./charlm.js";
+import { hmacSha256 } from "./hmac.js";
+import { callArguments } from "./calls.js";
+/** Keys that are public by design: publishable, site and project keys meant for browsers. */
+export const PUBLIC_FORMAT = /^(?:pk_(?:live|test)_|NRJS-[0-9a-f]{19}$|rzp_(?:live|test)_[A-Za-z0-9]{14}$|pk\.(?:eyJ|[A-Za-z0-9]{20})|pub[0-9a-f]{32}$|phc_|sb_publishable_|sq0idp-|sqb_[0-9a-f]{40}$)/;
+/** Where the bracket that encloses the end of `before` opens, skipping balanced pairs, or -1. */
+function openingBracket(before) {
+    let depth = 0;
+    for (let i = before.length - 1; i >= 0; i--) {
+        if (before[i] === "}" || before[i] === ")")
+            depth++;
+        else if (before[i] === "{" || before[i] === "(") {
+            if (depth === 0)
+                return i;
+            depth--;
+        }
+    }
+    return -1;
+}
+/** Where the bracket that encloses the start of `after` closes, skipping balanced pairs, or `after.length`. */
+function closingBracket(after) {
+    let depth = 0;
+    for (let i = 0; i < after.length; i++) {
+        if (after[i] === "{" || after[i] === "(")
+            depth++;
+        else if (after[i] === "}" || after[i] === ")") {
+            if (depth === 0)
+                return i;
+            depth--;
+        }
+    }
+    return after.length;
+}
+/**
+ * A Google API key in a client app's configuration, where it ships to every user (Google: "API keys for
+ * Firebase are not secret"): the object a Firebase web or Flutter config builds, `google-services.json`,
+ * the Maps JS loader URL, an Android manifest's or the iOS SDK's Maps key. Elsewhere an `AIza` key is
+ * hidden, whatever it's named (`GOOGLE_MAPS_API_KEY=` in a server's environment, a Gemini key): an
+ * unrestricted server key costs money. Used by the decision stage, policy.ts.
+ */
+export function isClientGoogleKey(text, start) {
+    const before = text.slice(Math.max(0, start - 600), start);
+    const line = before.slice(before.lastIndexOf("\n") + 1);
+    if (/maps\.googleapis\.com\/maps\/api\/js\?(?:[^\s"'&]*&)*key=$/.test(line))
+        return true;
+    // A HAR's record of that loader's request: its `queryString` entry, `{"name": "key", "value": "…"}`.
+    if (/"url"\s*:\s*"https:\/\/maps\.googleapis\.com\/maps\/api\/js\?[^"]*"(?:(?!"url")[^])*"queryString"\s*:\s*\[[^\]]*\{\s*"name"\s*:\s*"key"\s*,\s*"value"\s*:\s*"$/.test(before))
+        return true;
+    // Expo's app config, `ios.config.googleMapsApiKey` and `android.config.googleMaps.apiKey`: the Maps SDKs' keys,
+    // built into the app.
+    if (/\bconfig["']?\s*:\s*\{[^{}]*?(?:["']?googleMapsApiKey|["']?googleMaps["']?\s*:\s*\{[^{}]*?["']?apiKey)["']?\s*:\s*["']$/.test(before))
+        return true;
+    // An Android manifest's Maps key and the iOS SDK's: the app ships them. (The manifest's within its `<meta-data>` tag,
+    // its attributes on one line or several, in either order.)
+    if (/GMSServices\.provideAPIKey\(\s*"$|GMSPlacesClient\.provideAPIKey\(\s*"$/.test(line))
+        return true;
+    const tag = /<meta-data\b[^<>]*android:value="$/.exec(before)?.[0];
+    if (tag &&
+        (/android:name="com\.google\.android\.geo\.API_KEY"/.test(tag) ||
+            /^[^"<>]*"[^<>]*android:name="com\.google\.android\.geo\.API_KEY"/.test(text.slice(start, start + 600))))
+        return true;
+    // A server's key by name (Gemini, Vertex), whatever is around it.
+    if (/server|backend|admin|gemini|genai|generative|vertex|functions:(?:config|secrets)|^[ \t]*export[ \t]/i.test(line))
+        return false;
+    // A Firebase web config: the object the key sits in has `authDomain` or `messagingSenderId`, or is
+    // passed to `initializeApp(` / named `firebaseConfig`; or the line calls the key Firebase's. Not merely
+    // a Firebase config nearby (a Gemini key declared next to one is a server key).
+    const after = text.slice(start, start + 600);
+    const lineAfter = after.split("\n", 1)[0];
+    if (/firebase/i.test(line + lineAfter) || /GoogleService-Info|google-services\.json/.test(before))
+        return true;
+    // The object or call it sits in (`{ … }`, Dart's `FirebaseOptions( … )`), else its paragraph.
+    const open = openingBracket(before);
+    const close = closingBracket(after);
+    let object;
+    if (open >= 0)
+        object = before.slice(open) + after.slice(0, close);
+    else {
+        // No enclosing brackets in view (a fragment of a config): its sibling lines, at the key line's indentation.
+        const indent = /^[ \t]*/.exec(line)[0];
+        const sibling = (l) => l.startsWith(indent) && !/^[ \t]/.test(l.slice(indent.length)) && l.trim() !== "";
+        const up = before.split("\n").slice(0, -1).reverse();
+        const down = after.split("\n").slice(1);
+        const siblings = (ls) => {
+            const stop = ls.findIndex((l) => !sibling(l));
+            return stop < 0 ? ls : ls.slice(0, stop);
+        };
+        object = [...siblings(up), line + lineAfter, ...siblings(down)].join("\n");
+    }
+    // (The bracket must be the config's own: `firebaseConfig = {`, `initializeApp({`, `FirebaseOptions(`.)
+    return (/authDomain|messagingSenderId|"api_key"\s*:\s*\[/.test(object) ||
+        (open >= 0 &&
+            /(?:firebaseConfig\w*\s*[:=]\s*\{|initializeApp\(\s*\{?|FirebaseOptions\(|"api_key"\s*:\s*\[\s*\{)$/.test(before.slice(0, open + 1))));
+}
+/**
+ * Example keys from vendor docs and RFCs, which are published on purpose: RFC 6749's authorization code,
+ * tokens and client credentials, RFC 6750's bearer token, RFC 7636's PKCE verifier and challenge, RFC 5849's
+ * OAuth 1 examples, RFC 6265's and 9110's, and the TOTP secret every authenticator library's docs use. Kept in
+ * every syntax (policy.ts).
+ */
+export const PUBLISHED_EXAMPLE = /SplxlOBeZQQYbYS6WxSbIA|2YotnFZFEjr1zCsicMWpAA|tGzv3JOkF0XG5Qx2TlKWIA|s6BhdRkqt3|7Fjfp0ZBr1KtDRbnfVdmIw|gX1fBat3bV|czZCaGRSa3F0MzpnWDFmQmF0M2JW|mF_9\.B5f-4\.1JqM|8xLOxBtZp8|dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk|E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM|hh5s93j4hdidpola|hdk48Djdsa|kd94hf93k423kf44|pfkkdhi9sl3r4s00|nnch734d00sl2jdk|9djdj82h48djs9d2|kkk9d7dh3k39sjv7|j49sk3j29djd|dh893hdasih9|31d4d96e407aad42|aGVsbG86d29ybGQ=|QWxhZGRpbjpvcGVuIHNlc2FtZQ==|JBSWY3DPEHPK3PXP|frAQBc8Wsa1xVPfvJcrgRYwTiizs2trQ|GEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQ/;
+/**
+ * Published examples by their whole or a fixed part, found anywhere in a value: the vendors' own (AWS's
+ * `AKIAIOSFODNN7EXAMPLE` and the `…EXAMPLE`, `…EXAMPLEKEY` its docs end every key with; Stripe's, GitHub's and jwt.io's
+ * documented keys; MySQL's marker of a locked account's password), and filler (`deadbeefdeadbeef`, `EXAMPLEEXAMPLE`).
+ * (A documented key's vendor prefix is escaped, `ghp\x5f`, so this source isn't taken for a live key by a scanner.)
+ */
+const EXAMPLES = new RegExp(PUBLISHED_EXAMPLE.source +
+    "|" +
+    /(?:deadbeef|DEADBEEF|cafebabe|CAFEBABE){2}|SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c|sk\x5ftest_4eC39HqLyjWDarjtT1zdp7dc|ghp\x5f16C7e42F292c6912E7710c838347Ae178B4a|AKI\x41IOSFODNN7|wJalrXUtnFEMI\/K7MDENG|EXAMPLE(?:KEY)?$|(?:EXAMPLE){2}|AbCdEfGh|aBcDeFgH|THISISACOMBINATIONOFINVALIDSALTANDPASSWORDTHATMUSTNEVERBRBEUSED/
+        .source);
+/**
+ * Words that say a value stands in for one: `YOUR_API_KEY_HERE`, `my-fake-token`, `INVALID_TOKEN`, `sk_test_xxxxxxxx`,
+ * `<redacted>`, `not-a-real-key`, `changeMe`. Whole words, in any of their cases (`There` holds no `here`).
+ */
+const STAND_IN = (() => {
+    const words = [
+        "fake",
+        "invalid",
+        "notvalid",
+        "dummy",
+        "changeme",
+        "change[-_ ]?me",
+        "replace[-_ ]?me",
+        "placeholder",
+        "redacted",
+        "obscured",
+        "masked",
+        "hidden",
+        "removed",
+        "omitted",
+        "scrubbed",
+        "censored",
+        "sanitized",
+        "example",
+        "your",
+        "here",
+        "not[-_ ]?a[-_ ]?real",
+        "not[-_ ]?real",
+        "changed",
+    ];
+    const cases = words.flatMap((w) => [
+        w,
+        w.toUpperCase(),
+        w[0].toUpperCase() + w.slice(1),
+        w.replace(/(\])\?me$/, "$1?Me"),
+    ]);
+    // (A word starts after a non-letter or at a camel-case hump, and ends before a non-lower-case letter.)
+    return new RegExp(String.raw `(?:(?<![A-Za-z])|(?<=[a-z])(?=[A-Z]))(?:${[...new Set(cases)].join("|")}|[xX]{3,})(?![a-z])`, "g");
+})();
+/** What separates the parts of a placeholder: `YOUR_API_KEY_HERE`, `example-token`, `<your-key>`, `sk-[redacted]`. */
+const PLACEHOLDER_SEPARATORS = /[-_. :/[\]<>(){}*]+/;
+/**
+ * A value made of stand-in words and plain ones: each part between separators is a plain one (a small number, a short
+ * part like a vendor's `sk_`, `ghp_`, or a word), or holds a stand-in word joined to a word of its own by a case
+ * boundary (`exampleToken`) or to the last characters a mask shows (`xxxx1234`). A stand-in word joined to anything
+ * else is a weak password built on one, not a placeholder: `Changed2024`, `Example7392`, `ExampleXkqz`,
+ * `Fake!Orbit2291`, `invalidXk9mP2vQ7tL4`, `Q7tL4wR8nZ_HERE91kd`.
+ */
+function isStandIn(token) {
+    if (token.search(STAND_IN) < 0)
+        return false;
+    const isWord = (p) => /^[A-Za-z]+$/.test(p) && naturalness(p.toLowerCase()) > 0.3;
+    return token
+        .split(PLACEHOLDER_SEPARATORS)
+        .filter(Boolean)
+        .every((part) => {
+        const standIns = [...part.matchAll(STAND_IN)];
+        if (!standIns.length)
+            return /^\d{1,4}$/.test(part) || /^[A-Za-z]{1,4}$/.test(part) || isWord(part);
+        // (The parts around the stand-in words; the mask `xxxx` shows the last 1 to 4 characters after it.)
+        let from = 0;
+        return [...standIns.map((m) => m.index), part.length].every((to, i) => {
+            const joined = part.slice(from, to);
+            const mask = /^[xX]+$/.test(standIns[i - 1]?.[0] ?? "");
+            from = to + (standIns[i]?.[0].length ?? 0);
+            return joined === "" || isWord(joined) || (mask && /^[A-Za-z0-9]{1,4}$/.test(joined));
+        });
+    });
+}
+/** A masked key, a few characters shown around the stars: `sk-****abcd`, `ab****yz`. */
+const MASKED = /^[^*\s]{0,8}\*{4,}[^*\s]{0,8}$/;
+/**
+ * A token shown cut short, as tools print keys: a vendor's prefix and a few of the key before an ellipsis and a few
+ * after (`sk-proj-abc...xyz`, `AKIA…WXYZ`, `...4f2a`), or words after it (`sk-...set-in-1password`). Not a password
+ * with an ellipsis in it, a word before it (`Winter...2024`, `Maple...River3012`), or a key with only its front cut
+ * off (`...` then 300 characters).
+ */
+export function isTruncated(token) {
+    const m = /^([\w+/=:.-]{0,16}?)(?:\.\.\.|…)([\w+/=:.-]{0,40})$/.exec(token);
+    if (!m)
+        return false;
+    const runs = (side) => side.match(/[A-Za-z]+/g) ?? [];
+    const isWord = (run) => naturalness(run.toLowerCase()) > 0.3;
+    // (A person's word: capitalised, or five letters that read as one; a vendor's prefix is neither: `sk-proj`, `AKIA`.)
+    return (!runs(m[1]).some((run) => /^[A-Z][a-z]{3,}$/.test(run) || (run.length >= 5 && isWord(run))) &&
+        (m[2].length <= 8 || runs(m[2]).every((run) => run.length <= 2 || isWord(run))));
+}
+/** A template's holes: `{{ secrets.DB }}`, `${API_KEY}`, `%(password)s`, `{db_pass}`, `<password>`. */
+const HOLE = /\{\{[^{}]*\}\}|\$\{[A-Za-z_][\w.:/-]*\}|%\(\w+\)s|\{[a-z_][a-z0-9_.-]{2,60}\}|<[a-z][a-z_ .-]{2,60}>/g;
+/**
+ * A stand-in for a key, not one: mostly one repeated character (`sk_test_xxxxxxxx`, `ghp_0000…`, `AKIAXXXX…`; not
+ * base64 of bytes with many zeros, `TlRMTVNTUAADAAAAGAAY…`, where the other characters vary), a published
+ * example or a placeholder word, a counting sequence, or a template whose literal text is too short or too
+ * plain to be a secret on its own (`Bearer ${TOKEN}`, `postgres://${USER}:${PASS}@db:5432/app`; not
+ * `{;${EC}4S*A)HbUw`).
+ */
+export function isPlaceholder(token) {
+    const counts = new Map();
+    for (let i = 0; i < token.length; i++)
+        counts.set(token.charCodeAt(i), (counts.get(token.charCodeAt(i)) ?? 0) + 1);
+    // (Of the characters that aren't the repeated one or a separator, few: a prefix and the filler.)
+    const separators = (token.match(/[-_.:/]/g) ?? []).length;
+    for (const n of counts.values())
+        if (n >= 6 && n >= token.length * 0.4 && token.length - n - separators <= token.length * 0.35)
+            return true;
+    if (EXAMPLES.test(token) || isStandIn(token) || isSequential(token) || isTruncated(token) || MASKED.test(token))
+        return true;
+    if (!/[{<]|%\(/.test(token))
+        return false;
+    // (A hole in a docs' syntax, `<…>` or `{…}`, names something: `<password>`, not `<qjk>`.)
+    const rest = token.replace(HOLE, (h) => /^[<{][^{$]/.test(h) && naturalness(h.slice(1, -1).replace(/[_ .-]+/g, " ")) <= 0.5 ? h : "");
+    if (rest === token)
+        return false;
+    const letters = rest.replace(/[^A-Za-z0-9]+/g, " ").trim();
+    return rest.replace(/\s/g, "").length < 8 || naturalness(letters) > 0.5;
+}
+/**
+ * Counting sequences, after a vendor's prefix: `abcdef123456`, `sk_test_1234567890abcdef`, hex test vectors like
+ * `000102030405…` or `fffefdfc…`. Four in five characters (or bytes) count; a person's password made of a run and a word
+ * (`123456789Maple6543%`) is a password.
+ */
+function isSequential(token) {
+    const body = token.replace(/^(?:[A-Za-z]{1,8}[_-])+/, "");
+    if (body.length < 8)
+        return false;
+    // Characters inside runs of 4+ counting steps, one step all the way (`abcd`, `4321`, `aaaa`; not `9887`).
+    let inRuns = 0;
+    let run = 1;
+    let step = 2;
+    for (let i = 1; i <= body.length; i++) {
+        const next = i < body.length ? body.charCodeAt(i) - body.charCodeAt(i - 1) : 2;
+        if (Math.abs(next) <= 1 && (run === 1 || next === step))
+            run++;
+        else {
+            if (run >= 4)
+                inRuns += run;
+            // (The pair that broke the run may start the next: `aaab`… `bcd`.)
+            run = Math.abs(next) <= 1 ? 2 : 1;
+        }
+        step = next;
+    }
+    if (inRuns >= body.length * 0.8)
+        return true;
+    // Hex as bytes, the same way: bytes inside runs of 4+ that step by 0, 1 or 0x11, one step all the way (`00010203`,
+    // `aabbccdd`, `fffefdfc`). (`7f3b9c2e1d4a5b6c` has steps of 0x11 here and there, not runs: a key. Digits alone step
+    // by 0x11 as a number's pairs do, `12233445`, `98879887`: a PIN, not bytes counting.)
+    if (/^[0-9a-f]+$/i.test(body) && body.length % 2 === 0) {
+        const strides = /[a-f]/i.test(body) ? [0, 1, 0x11] : [0, 1];
+        const n = body.length / 2;
+        let inByteRuns = 0;
+        let byteRun = 1;
+        let step = NaN;
+        for (let i = 1; i <= n; i++) {
+            const d = i < n ? parseInt(body.slice(i * 2, i * 2 + 2), 16) - parseInt(body.slice(i * 2 - 2, i * 2), 16) : NaN;
+            if (strides.includes(Math.abs(d)) && (byteRun === 1 || d === step))
+                byteRun++;
+            else {
+                if (byteRun >= 4)
+                    inByteRuns += byteRun;
+                // (The pair that broke the run may start the next.)
+                byteRun = strides.includes(Math.abs(d)) ? 2 : 1;
+            }
+            step = d;
+        }
+        return inByteRuns >= n * 0.8;
+    }
+    return false;
+}
+/**
+ * A JWT meant to be public or published: Supabase anon keys, the jwt.io and RFC samples. With
+ * `samplesOnly`, only the published samples (an anon key assigned to a name is still hidden).
+ */
+export function isPublicJwt(token, samplesOnly = false) {
+    if (!token.startsWith("eyJ"))
+        return false;
+    const [head, body] = token.split(".");
+    const payload = base64Binary(body ?? "");
+    if (!payload)
+        return false;
+    // (jwt.io's sample claims say a sample when a public key signed them, RS256's and the others'; an HMAC token is a
+    // sample only by its docs key, signedWithDocsKey, as one signed with a real secret may copy the claims.)
+    const hmac = /"alg"\s*:\s*"HS\d+"/.test(base64Binary(head) ?? "");
+    return ((!samplesOnly && /"role"\s*:\s*"anon"/.test(payload)) ||
+        (!hmac && (/"sub"\s*:\s*"1234567890"/.test(payload) || /"name"\s*:\s*"John Doe"/.test(payload))) ||
+        signedWithDocsKey(token));
+}
+/**
+ * The keys docs and tutorials sign their example HS256 tokens with, each one spelled as a stand-in: jwt.io's, the
+ * jsonwebtoken README's and express-session's.
+ */
+const DOCS_JWT_KEYS = ["your-256-bit-secret", "your-secret-key", "your_jwt_secret", "shhhhh", "keyboard cat"];
+/**
+ * The weak keys both docs and apps in development sign with. A token signed with one is a sample only when its claims
+ * say nothing of a session (PyJWT's `{"a": "b"}`, `{"some": "payload"}`); one with a subject, a user or a time is that
+ * app's bearer credential.
+ */
+const WEAK_JWT_KEYS = ["secret", "test", "key", "changeme", "password"];
+/** Claims a session's token carries: a subject, a user, an expiry or an issue time. */
+const SESSION_CLAIM = /"(?:sub|exp|iat|nbf|jti|uid|user(?:_?id|name)?|email|role|scope|sid|session(?:_?id)?)"\s*:/i;
+/**
+ * Whether an HS256 JWT's signature verifies under a docs key (DOCS_JWT_KEYS), or under a weak key with no session
+ * claims (WEAK_JWT_KEYS): anyone can mint it, so it's a sample.
+ */
+function signedWithDocsKey(token) {
+    const [header, payload, signature] = token.split(".");
+    if (!signature || !/"alg"\s*:\s*"HS256"/.test(base64Binary(header) ?? ""))
+        return false;
+    const utf8 = new TextEncoder();
+    const message = utf8.encode(`${header}.${payload}`);
+    const keys = SESSION_CLAIM.test(base64Binary(payload) ?? "") ? DOCS_JWT_KEYS : [...DOCS_JWT_KEYS, ...WEAK_JWT_KEYS];
+    return keys.some((key) => base64url(hmacSha256(utf8.encode(key), message)) === signature);
+}
+const base64url = (bytes) => btoa(String.fromCharCode(...bytes))
+    .replace(/\+/g, "-")
+    .replace(/\//g, "_")
+    .replace(/=+$/, "");
+/**
+ * Browser and mobile SDK initialisers, whose keys are public by design: calls (`Sentry.init(`, `new Pusher(`,
+ * `loadStripe(`) or config objects (`firebaseConfig = {`, `_rollbarConfig = {`). Not a vendor word alone:
+ * `IntercomClient(…)` is a server SDK, a bare `createInstance(` is any factory unless Optimizely's is imported (see
+ * clientSdkAt), and a comment naming the vendor initialises nothing.
+ */
+const CLIENT_SDK_CALL = /(?:\b(?:AnalyticsBrowser\.load|analytics\.load|Bugsnag\.start|Rollbar\.init|optimizely(?:Sdk)?\.createInstance|createInstance|(?:new\s+)?GrowthBook|Purchases\.configure|braintree\.\w+\.create|(?:new\s+)?AdyenCheckout|branch\.init|initializeApp|new\s+mapboxgl\.\w+|(?:new\s+)?Pusher|Sentry\.init|posthog\.init|amplitude\.(?:init|getInstance\(\)\.init)|mixpanel\.init|LDClient\.initialize|datadogRum\.init|DD_RUM\.init|heap\.load|algoliasearch|docsearch|instantsearch|Intercom|loadStripe|Stripe|Square\.payments)\s*\(|\b(?:_rollbarConfig|firebaseConfig\w*)\s*[:=]\s*\{)/g;
+/**
+ * The client SDK initialiser whose arguments `at` is directly inside, or inside an object or list given as one of them,
+ * if the call starts within 300 characters before it: its call as written (`algoliasearch(`).
+ */
+export function clientSdkAt(text, at) {
+    const from = Math.max(0, at - 300);
+    let last;
+    for (const m of text.slice(from, at).matchAll(CLIENT_SDK_CALL))
+        last = m;
+    if (!last || (/^createInstance/.test(last[0]) && !/@optimizely\//.test(text.slice(0, at))))
+        return undefined;
+    const holding = (args) => args?.find((a) => a.start <= at && at < a.end);
+    const arg = holding(callArguments(text, from + last.index + last[0].length));
+    if (!arg)
+        return undefined;
+    const inside = arg.literal || at === arg.start || (/^[{[]/.test(arg.text) && holding(callArguments(text, arg.start + 1)));
+    return inside ? last[0] : undefined;
+}
+/** The parameters client SDKs take public keys under (positional arguments count too). */
+export const PUBLIC_SDK_PARAM = /^(?:api_?key|key|client_?key|client_?token|sdk_?key|app_?id|application_?id|dsn|authorization|publishable_?key|public_?key|site_?key|access_?token|token|search_?(?:only_?)?api_?key)$/i;

package/dist/publickeys.d.ts

@@ -0,0 +1,41 @@
+import { type ArmoredBlock } from "./pem.ts";
+/**
+ * A SubjectPublicKeyInfo: a SEQUENCE whose first element is the AlgorithmIdentifier, a SEQUENCE that starts with a
+ * public key algorithm's OID. (A private key's PKCS #8 and PKCS #1 encodings start with an INTEGER version instead.)
+ */
+export declare function isDerPublicKey(b64: string): boolean;
+/**
+ * An X.509 certificate's DER (what `-----BEGIN CERTIFICATE-----` holds, `MIIDdzCCAl+gAwIBAgI…`): a SEQUENCE whose first
+ * element, the certificate to be signed, opens with its version (`[0]` holding an INTEGER of 0 to 2) and an INTEGER
+ * serial number of 1 to 21 bytes, then the signature algorithm's SEQUENCE.
+ */
+export declare function isDerCertificate(b64: string): boolean;
+/**
+ * A private key's DER, whatever armor it's in: a SEQUENCE whose first element is a one-byte INTEGER version, 0 to 2
+ * (PKCS #1's RSAPrivateKey and PKCS #8's PrivateKeyInfo start with 0, OneAsymmetricKey with 1, SEC 1's EC key with
+ * 1). No public structure starts so: a SubjectPublicKeyInfo or a certificate opens with a SEQUENCE, an RSAPublicKey
+ * with its modulus. (SEC 1's explicit ECParameters start with version 1 too, then a field's SEQUENCE and the curve's:
+ * PKCS #8 has its key's OCTET STRING after the algorithm's SEQUENCE.)
+ */
+export declare function isDerPrivateKey(b64: string): boolean;
+/**
+ * A PKCS #1 RSAPublicKey (`-----BEGIN RSA PUBLIC KEY-----`, `MIIBCgKCAQEA…`, `MIGJAoGBA…` for 1,024 bits): a SEQUENCE
+ * of the modulus, 1,024 to 8,192 bits in steps of 512 with its top bit set, and an exponent of 1 to 4 bytes, the SEQUENCE's length the
+ * two's.
+ */
+export declare function isRsaPublicKey(b64: string): boolean;
+/**
+ * A DER ECDSA signature, whole: a SEQUENCE of two INTEGERs, r and s, of 1 to 66 bytes (P-256 to P-521; a leading zero
+ * only before a top bit), the SEQUENCE's length theirs and the value's length the SEQUENCE's.
+ */
+export declare function isDerSignature(b64: string): boolean;
+/**
+ * An OpenPGP v4 public key or public subkey packet (tag 6 or 14), in the old or the new packet format: a creation
+ * time since 1995 and not in the future, then an RSA modulus whose bit count agrees with its first byte, or an
+ * elliptic curve's OID.
+ */
+export declare function isPgpPublicKey(b64: string): boolean;
+/** The public armored blocks of a text (PUBLIC_LABEL's), in order. */
+export declare const publicBlocks: (text: string) => ArmoredBlock[];
+/** Whether PEM text is public through and through: it has a BEGIN line, and every one is public armor (a bundle with a key isn't). */
+export declare function isPublicPem(pem: string): boolean;

package/dist/publickeys.js

@@ -0,0 +1,232 @@
+/**
+ * Public keys recognised by their encoding's structure, from the first bytes of their base64: a DER
+ * SubjectPublicKeyInfo (what `-----BEGIN PUBLIC KEY-----` holds) and an OpenPGP public key packet (an armored
+ * `PUBLIC KEY BLOCK`'s body). Each check reads enough fields that agree with each other (a known algorithm's OID, a
+ * key size and the bit it sets, a packet length that is its fields' sum) that random base64 passes with odds below one
+ * in a hundred billion: a value that passes is kept. (Measured for PGP: about 1 random value in 10^8 has the header,
+ * version, creation time and key size, and 1 in 14,000 of those the length.)
+ */
+import { base64Bytes, base64Prefix } from "./base64.js";
+import { armoredBlocks, beginLines } from "./pem.js";
+/** How much base64 text the checks read: 48 bytes cover every header they look at. */
+const HEAD_CHARS = 64;
+/** The first bytes base64 text encodes, or an empty array. */
+function head(b64) {
+    return base64Prefix(b64.slice(0, HEAD_CHARS)) ?? new Uint8Array();
+}
+const hex = (b, from, length) => Array.from(b.subarray(from, from + length), (x) => x.toString(16).padStart(2, "0")).join("");
+/** Where a DER element's content starts, given where its tag is, and how long it is; or undefined for an invalid length. */
+function derElement(b, at) {
+    const first = b[at + 1];
+    if (first === undefined)
+        return undefined;
+    if (first < 0x80)
+        return { content: at + 2, length: first };
+    const size = first & 0x7f;
+    if (size < 1 || size > 3 || b.length < at + 2 + size)
+        return undefined;
+    let length = 0;
+    for (let i = 0; i < size; i++)
+        length = length * 256 + b[at + 2 + i];
+    return { content: at + 2 + size, length };
+}
+/** Where a DER element's content starts, given where its tag is, or -1 for an invalid length. */
+function derContent(b, at) {
+    return derElement(b, at)?.content ?? -1;
+}
+/** Public key algorithms' OIDs: RSA, RSASSA-PSS, DSA, DH, EC, Ed25519, Ed448, X25519, X448. */
+const KEY_ALGORITHMS = new Set([
+    "2a864886f70d010101",
+    "2a864886f70d01010a",
+    "2a8648ce380401",
+    "2a864886f70d010301",
+    "2a8648ce3d0201",
+    "2b6570",
+    "2b6571",
+    "2b656e",
+    "2b656f",
+]);
+/**
+ * A SubjectPublicKeyInfo: a SEQUENCE whose first element is the AlgorithmIdentifier, a SEQUENCE that starts with a
+ * public key algorithm's OID. (A private key's PKCS #8 and PKCS #1 encodings start with an INTEGER version instead.)
+ */
+export function isDerPublicKey(b64) {
+    const b = head(b64);
+    if (b[0] !== 0x30)
+        return false;
+    const inner = derContent(b, 0);
+    if (inner < 0 || b[inner] !== 0x30)
+        return false;
+    const oid = derContent(b, inner);
+    return oid >= 0 && b[oid] === 0x06 && KEY_ALGORITHMS.has(hex(b, oid + 2, b[oid + 1]));
+}
+/**
+ * An X.509 certificate's DER (what `-----BEGIN CERTIFICATE-----` holds, `MIIDdzCCAl+gAwIBAgI…`): a SEQUENCE whose first
+ * element, the certificate to be signed, opens with its version (`[0]` holding an INTEGER of 0 to 2) and an INTEGER
+ * serial number of 1 to 21 bytes, then the signature algorithm's SEQUENCE.
+ */
+export function isDerCertificate(b64) {
+    const b = head(b64);
+    if (b[0] !== 0x30)
+        return false;
+    const tbs = derContent(b, 0);
+    if (tbs < 0 || b[tbs] !== 0x30)
+        return false;
+    const version = derContent(b, tbs);
+    if (version < 0 || hex(b, version, 4) !== "a0030201" || b[version + 4] > 2)
+        return false;
+    const serial = version + 5;
+    return b[serial] === 0x02 && b[serial + 1] >= 1 && b[serial + 1] <= 21 && b[serial + 2 + b[serial + 1]] === 0x30;
+}
+/**
+ * A private key's DER, whatever armor it's in: a SEQUENCE whose first element is a one-byte INTEGER version, 0 to 2
+ * (PKCS #1's RSAPrivateKey and PKCS #8's PrivateKeyInfo start with 0, OneAsymmetricKey with 1, SEC 1's EC key with
+ * 1). No public structure starts so: a SubjectPublicKeyInfo or a certificate opens with a SEQUENCE, an RSAPublicKey
+ * with its modulus. (SEC 1's explicit ECParameters start with version 1 too, then a field's SEQUENCE and the curve's:
+ * PKCS #8 has its key's OCTET STRING after the algorithm's SEQUENCE.)
+ */
+export function isDerPrivateKey(b64) {
+    const b = head(b64);
+    if (b[0] !== 0x30)
+        return false;
+    const inner = derContent(b, 0);
+    if (inner < 0 || b[inner] !== 0x02 || b[inner + 1] !== 0x01 || b[inner + 2] > 2)
+        return false;
+    if (b[inner + 3] !== 0x30)
+        return true;
+    const algorithm = derElement(b, inner + 3);
+    const next = algorithm ? algorithm.content + algorithm.length : -1;
+    return next >= b.length || b[next] === 0x04;
+}
+/**
+ * A PKCS #1 RSAPublicKey (`-----BEGIN RSA PUBLIC KEY-----`, `MIIBCgKCAQEA…`, `MIGJAoGBA…` for 1,024 bits): a SEQUENCE
+ * of the modulus, 1,024 to 8,192 bits in steps of 512 with its top bit set, and an exponent of 1 to 4 bytes, the SEQUENCE's length the
+ * two's.
+ */
+export function isRsaPublicKey(b64) {
+    const b = head(b64);
+    const sequence = derElement(b, 0);
+    const modulus = sequence && derElement(b, sequence.content);
+    if (b[0] !== 0x30 || !sequence || !modulus || b[sequence.content] !== 0x02)
+        return false;
+    const exponent = sequence.length - (modulus.content - sequence.content) - modulus.length - 2; // (the exponent's tag and length)
+    return (modulus.length >= 129 &&
+        modulus.length <= 1025 &&
+        modulus.length % 64 === 1 &&
+        b[modulus.content] === 0 &&
+        b[modulus.content + 1] >= 0x80 &&
+        exponent >= 1 &&
+        exponent <= 4);
+}
+/**
+ * A DER ECDSA signature, whole: a SEQUENCE of two INTEGERs, r and s, of 1 to 66 bytes (P-256 to P-521; a leading zero
+ * only before a top bit), the SEQUENCE's length theirs and the value's length the SEQUENCE's.
+ */
+export function isDerSignature(b64) {
+    if (b64.length > 200)
+        return false;
+    const b = base64Bytes(b64) ?? new Uint8Array();
+    const content = derContent(b, 0);
+    if (b[0] !== 0x30 || content < 0 || content + (b[1] < 0x80 ? b[1] : b[2]) !== b.length)
+        return false;
+    const integer = (at) => b[at] === 0x02 && b[at + 1] >= 1 && b[at + 1] <= 66 && (b[at + 2] !== 0 || b[at + 3] >= 0x80);
+    const s = content + 2 + b[content + 1];
+    return integer(content) && integer(s) && s + 2 + b[s + 1] === b.length;
+}
+/** OpenPGP's elliptic curves by OID: NIST P-256, P-384, P-521, brainpool, secp256k1, Ed25519, Curve25519, Ed448, X448. */
+const PGP_CURVES = new Set([
+    "2a8648ce3d030107",
+    "2b81040022",
+    "2b81040023",
+    "2b2403030208010107",
+    "2b240303020801010b",
+    "2b240303020801010d",
+    "2b8104000a",
+    "2b06010401da470f01",
+    "2b060104019755010501",
+    "2b6571",
+    "2b656f",
+]);
+/** Seconds since 1970 of 1995-01-01: OpenPGP keys made before it don't turn up. */
+const PGP_EPOCH = 788_918_400;
+/**
+ * An OpenPGP v4 public key or public subkey packet (tag 6 or 14), in the old or the new packet format: a creation
+ * time since 1995 and not in the future, then an RSA modulus whose bit count agrees with its first byte, or an
+ * elliptic curve's OID.
+ */
+export function isPgpPublicKey(b64) {
+    const b = head(b64);
+    if (b.length < 16)
+        return false;
+    let tag;
+    let body;
+    let length;
+    if ((b[0] & 0xc0) === 0x80) {
+        // Old format: the tag in bits 5–2, the length's size in bits 1–0 (1, 2 or 4 octets).
+        tag = (b[0] >> 2) & 0x0f;
+        const size = [1, 2, 4][b[0] & 3];
+        if (size === undefined)
+            return false;
+        body = 1 + size;
+        length = 0;
+        for (let i = 1; i < body; i++)
+            length = length * 256 + b[i];
+    }
+    else if ((b[0] & 0xc0) === 0xc0) {
+        // New format: the tag in bits 5–0, a length of 1, 2 or 5 octets.
+        tag = b[0] & 0x3f;
+        body = b[1] < 192 ? 2 : b[1] < 224 ? 3 : b[1] === 255 ? 6 : -1;
+        if (body < 0)
+            return false;
+        length =
+            body === 2
+                ? b[1]
+                : body === 3
+                    ? ((b[1] - 192) << 8) + b[2] + 192
+                    : ((b[2] << 24) | (b[3] << 16) | (b[4] << 8) | b[5]) >>> 0;
+    }
+    else
+        return false;
+    if ((tag !== 6 && tag !== 14) || b[body] !== 4)
+        return false;
+    const created = ((b[body + 1] << 24) | (b[body + 2] << 16) | (b[body + 3] << 8) | b[body + 4]) >>> 0;
+    if (created < PGP_EPOCH || created > Date.now() / 1000 + 86_400)
+        return false;
+    const algorithm = b[body + 5];
+    // (The packet's length is its fields': version, time and algorithm, 6 octets, then the key's.)
+    if (algorithm === 1 || algorithm === 2 || algorithm === 3) {
+        // RSA: the modulus is an MPI, its bit count (1,024 to 16,384) then its bytes, the first holding its top bit; then
+        // the exponent's MPI, of 1 to 4 bytes (65537 takes 3).
+        const bits = (b[body + 6] << 8) | b[body + 7];
+        const top = b[body + 8];
+        const exponent = length - 6 - 2 - Math.ceil(bits / 8) - 2;
+        return (bits >= 1024 &&
+            bits <= 16_384 &&
+            top !== undefined &&
+            31 - Math.clz32(top) === (bits - 1) % 8 &&
+            exponent >= 1 &&
+            exponent <= 4);
+    }
+    // ECDH, ECDSA, EdDSA: the curve's OID, after its length; the point's MPI; for ECDH its KDF parameters, 4 octets.
+    if (algorithm !== 18 && algorithm !== 19 && algorithm !== 22)
+        return false;
+    const oid = b[body + 6];
+    const at = body + 7 + oid;
+    if (!PGP_CURVES.has(hex(b, body + 7, oid)) || at + 1 >= b.length)
+        return false;
+    const point = (b[at] << 8) | b[at + 1];
+    return length === 6 + 1 + oid + 2 + Math.ceil(point / 8) + (algorithm === 18 ? 4 : 0);
+}
+/**
+ * The labels of PEM armor that holds public material or ciphertext, neither of them a secret to redact: certificates
+ * and their requests, CRLs, public keys, PGP public blocks and signatures, parameters; and `ENCRYPTED FILE`,
+ * `PGP MESSAGE`, kept as encrypted values are.
+ */
+const PUBLIC_LABEL = /^(?:[A-Z0-9]+ )*(?:PUBLIC KEY|CERTIFICATE|X509 CRL|CERTIFICATE REQUEST|NEW CERTIFICATE REQUEST|PGP PUBLIC KEY BLOCK|PGP SIGNATURE|PGP MESSAGE|ENCRYPTED FILE|SSH2 PUBLIC KEY|DH PARAMETERS|EC PARAMETERS|PKCS7|CMS)$/;
+/** The public armored blocks of a text (PUBLIC_LABEL's), in order. */
+export const publicBlocks = (text) => armoredBlocks(text).filter((b) => PUBLIC_LABEL.test(b.label));
+/** Whether PEM text is public through and through: it has a BEGIN line, and every one is public armor (a bundle with a key isn't). */
+export function isPublicPem(pem) {
+    const labels = [...beginLines(pem)].map((b) => b.label);
+    return labels.length > 0 && labels.every((label) => PUBLIC_LABEL.test(label));
+}

package/dist/random.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Measures of how random a token looks, from the token alone, for the random layer's model (unnamed.ts): the
+ * alphabet it is drawn from, its entropy as a z-score against a uniformly random string of the same length over that
+ * alphabet (so a 20-character hex string and a 60-character base64 one are judged on one scale), and its character
+ * classes and how often they switch. A random key, a hash and an encrypted blob all look random here; telling them
+ * apart is the context's job.
+ */
+export type Alphabet = "hex" | "HEX" | "b32" | "b36" | "B36" | "b62" | "b64" | "b64url" | "other";
+/** The smallest common alphabet that contains every character of the token. (`=` is base64's padding, in none.) */
+export declare function alphabetOf(token: string): Alphabet;
+/** Shannon entropy of the characters, in bits per character. */
+export declare function entropy(token: string): number;
+/**
+ * How many standard deviations the token's entropy sits from a random string's. Random strings score near 0.
+ * (Measured over the first 512 characters, the longest string randomEntropy simulates.)
+ */
+export declare function entropyZ(token: string, alphabet?: Alphabet): number;
+/** A token's character classes: how many of each, and how often the class changes. */
+export interface Shape {
+    length: number;
+    lower: number;
+    upper: number;
+    digit: number;
+    /** Changes between letter case, digit and symbol, per character boundary. */
+    switches: number;
+    /** What `switches` would be for a random string with these class proportions. */
+    expectedSwitches: number;
+}
+export declare function shape(token: string): Shape;