@redential/cli 0.1.0

package/dist/login.js

@@ -0,0 +1,133 @@
+import { spawn } from "node:child_process";
+import { AuthError } from "./errors.js";
+import { getSiteUrl } from "./config.js";
+import { saveCredentials } from "./credentials.js";
+import { postJson, pollJson } from "./http-client.js";
+import { checkForUpdate } from "./version-check.js";
+function requestDeviceAuthorization(siteUrl) {
+    return postJson(`${siteUrl}/api/cli/device/authorize`, {});
+}
+function pollDeviceToken(siteUrl, deviceCode) {
+    // Not postJson: this endpoint returns HTTP 400 for authorization_pending/
+    // slow_down too (RFC 8628 shape), which postJson would treat as a fatal
+    // NetworkError before ever reading the body.
+    return pollJson(`${siteUrl}/api/cli/device/token`, { device_code: deviceCode });
+}
+const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * Best-effort auto-open of verification_uri in the default browser — never
+ * fatal, never blocks login: the printed URL/code are the fallback for any
+ * failure here (headless box, SSH session, unknown platform, no browser).
+ * `verification_uri` comes from the server's JSON response, so it's treated
+ * as untrusted input: only http/https is ever handed to a native opener
+ * (never file://, an app-custom scheme, etc.), and the re-serialized
+ * `URL#href` is passed — never the raw string — so it can't carry stray
+ * whitespace/quotes into the child process's argv.
+ *
+ * Uses `spawn`, never `exec`/a shell string: the URL is always its own argv
+ * element, so a URL crafted with shell metacharacters can't inject a second
+ * command. Windows is the one platform where even that isn't enough — `cmd
+ * /c start` re-parses the command line, and a legal URL character like `&`
+ * would split it into a second command — so win32 shells out to
+ * `rundll32 url.dll,FileProtocolHandler` instead, which never touches a
+ * shell at all. `detached` + `unref` + `stdio: "ignore"` keep the opener
+ * from holding the CLI's event loop open or inheriting its file
+ * descriptors; the `error` listener is required because `spawn` emits
+ * `error` asynchronously on ENOENT (missing `open`/`xdg-open`/`rundll32`) —
+ * without a listener that's an unhandled `error` event that crashes the
+ * whole process.
+ */
+function openBrowser(url) {
+    let target;
+    try {
+        const parsed = new URL(url);
+        if (parsed.protocol !== "https:" && parsed.protocol !== "http:")
+            return;
+        target = parsed.href;
+    }
+    catch {
+        return;
+    }
+    let command;
+    let args;
+    if (process.platform === "darwin") {
+        command = "open";
+        args = [target];
+    }
+    else if (process.platform === "win32") {
+        command = "rundll32";
+        args = ["url.dll,FileProtocolHandler", target];
+    }
+    else {
+        command = "xdg-open";
+        args = [target];
+    }
+    try {
+        const child = spawn(command, args, { detached: true, stdio: "ignore" });
+        child.on("error", () => { });
+        child.unref();
+    }
+    catch {
+        // Synchronous spawn failures (e.g. EACCES) are equally non-fatal.
+    }
+}
+/**
+ * RFC 8628-shaped device authorization grant. Nothing on the server side of
+ * this exists yet (redence has no /api/cli/* routes at the time of writing —
+ * this repo defines the contract; redence implements to match, see
+ * docs/login-submit.md). Never sends anything except the device code itself.
+ */
+export async function runLogin(opts = {}) {
+    const log = opts.log ?? console.log;
+    const sleep = opts.sleepFn ?? defaultSleep;
+    const open = opts.openFn ?? openBrowser;
+    const siteUrl = getSiteUrl();
+    const auth = await requestDeviceAuthorization(siteUrl);
+    log(`First, go to: ${auth.verification_uri}`);
+    log(`Then enter this code: ${auth.user_code}`);
+    // Printed above first, so the URL/code are on screen even if the browser
+    // steals focus or auto-open silently does nothing. Guarded here too, not
+    // just inside the default openBrowser: an injected openFn (test or
+    // future caller) must never be able to fail login either — including one
+    // that returns a rejecting promise, which a synchronous try/catch alone
+    // wouldn't catch (openFn's type is synchronous, but nothing stops a
+    // caller from assigning an async function to it).
+    try {
+        void Promise.resolve(open(auth.verification_uri)).catch(() => { });
+    }
+    catch {
+        // Auto-open is a convenience, never load-bearing.
+    }
+    log("Waiting for confirmation...");
+    let intervalMs = Math.max(auth.interval, 1) * 1000;
+    const deadline = Date.now() + auth.expires_in * 1000;
+    for (;;) {
+        if (Date.now() > deadline) {
+            throw new AuthError("Login timed out before the code was confirmed. Run `redential login` again.");
+        }
+        await sleep(intervalMs);
+        const result = await pollDeviceToken(siteUrl, auth.device_code);
+        if (result.access_token) {
+            saveCredentials({ access_token: result.access_token, site_url: siteUrl, obtained_at: new Date().toISOString() }, opts.configDir);
+            log("Logged in.");
+            // Best-effort only, after the login itself has already fully
+            // succeeded — never allowed to turn a successful login into a
+            // failure (checkForUpdate never throws by contract).
+            await (opts.checkForUpdateFn ?? (() => checkForUpdate({ log })))();
+            return;
+        }
+        switch (result.error) {
+            case "authorization_pending":
+                continue;
+            case "slow_down":
+                intervalMs += 5000;
+                continue;
+            case "access_denied":
+                throw new AuthError("Login was denied.");
+            case "expired_token":
+                throw new AuthError("The login code expired before it was confirmed. Run `redential login` again.");
+            default:
+                throw new AuthError("Unexpected response from the login server.");
+        }
+    }
+}

package/dist/logout.js

@@ -0,0 +1,6 @@
+import { deleteCredentials } from "./credentials.js";
+export function runLogout(opts = {}) {
+    const log = opts.log ?? console.log;
+    const deleted = deleteCredentials(opts.configDir);
+    log(deleted ? "Logged out." : "Not logged in — nothing to do.");
+}

package/dist/merkle.js

@@ -0,0 +1,20 @@
+import { createHash } from "node:crypto";
+function sha256hex(value) {
+    return createHash("sha256").update(value).digest("hex");
+}
+/** Plain pairwise-sha256 Merkle root over the user's commit shas. */
+export function merkleRoot(leaves) {
+    let level = leaves.map(sha256hex);
+    if (level.length === 0)
+        return sha256hex("");
+    while (level.length > 1) {
+        const next = [];
+        for (let i = 0; i < level.length; i += 2) {
+            const left = level[i];
+            const right = i + 1 < level.length ? level[i + 1] : left;
+            next.push(sha256hex(left + right));
+        }
+        level = next;
+    }
+    return level[0];
+}

package/dist/prompt.js

@@ -0,0 +1,70 @@
+import { createInterface } from "node:readline/promises";
+import { ScanError } from "./errors.js";
+const DEFAULT_STREAMS = { input: process.stdin, output: process.stdout };
+/**
+ * `rl.question()` never settles if the input stream hits EOF before an
+ * answer arrives (e.g. closed/piped stdin in a script or CI) — the process
+ * would then idle with nothing keeping the event loop alive and exit 0
+ * without ever producing a bundle. Racing against the interface's own
+ * "close" event turns that silent non-answer into an explicit failure.
+ */
+function questionOrThrowOnClose(rl, prompt, closeMessage) {
+    const closed = new Promise((_, reject) => {
+        rl.once("close", () => reject(new ScanError(closeMessage)));
+    });
+    return Promise.race([rl.question(prompt), closed]);
+}
+function formatCandidate(c) {
+    return `${c.email} (${c.count} commit${c.count === 1 ? "" : "s"})`;
+}
+export async function promptAuthors(candidates, streams = DEFAULT_STREAMS) {
+    const rl = createInterface(streams);
+    try {
+        // A single candidate is almost always "you" — a Y/n confirmation (Y
+        // default, so pressing Enter accepts) is faster than making the user
+        // type "1" for the only option. 2+ candidates keep the numbered list:
+        // there's no single obvious default to pick for them.
+        if (candidates.length === 1) {
+            const [only] = candidates;
+            const answer = await questionOrThrowOnClose(rl, `Found 1 identity: ${formatCandidate(only)}. Is this you? (Y/n) `, "Input closed before an author identity was selected.");
+            const trimmed = answer.trim().toLowerCase();
+            return trimmed === "" || trimmed.startsWith("y") ? [only.email] : [];
+        }
+        console.log("Which of these author identities are yours?");
+        candidates.forEach((c, i) => {
+            console.log(`  ${i + 1}. ${formatCandidate(c)}`);
+        });
+        const answer = await questionOrThrowOnClose(rl, "Enter the numbers, comma-separated (e.g. 1,3): ", "Input closed before an author identity was selected.");
+        const indices = answer
+            .split(",")
+            .map((s) => parseInt(s.trim(), 10) - 1)
+            .filter((i) => i >= 0 && i < candidates.length);
+        return [...new Set(indices.map((i) => candidates[i].email))];
+    }
+    finally {
+        rl.close();
+    }
+}
+const ATTESTATION_TEXT = "I am authorized to analyze this repository.";
+export async function promptConfirmAttestation(streams = DEFAULT_STREAMS) {
+    const rl = createInterface(streams);
+    try {
+        const answer = await questionOrThrowOnClose(rl, `${ATTESTATION_TEXT} Confirm? (y/n) `, "Input closed before authorization was confirmed.");
+        return answer.trim().toLowerCase().startsWith("y");
+    }
+    finally {
+        rl.close();
+    }
+}
+/** Separate confirmation from promptConfirmAttestation — "I'm authorized to
+ * scan" and "upload this specific bundle" are different questions. */
+export async function promptConfirmUpload(streams = DEFAULT_STREAMS) {
+    const rl = createInterface(streams);
+    try {
+        const answer = await questionOrThrowOnClose(rl, "Upload this bundle? (y/n) ", "Input closed before the upload was confirmed.");
+        return answer.trim().toLowerCase().startsWith("y");
+    }
+    finally {
+        rl.close();
+    }
+}

package/dist/public-remote.js

@@ -0,0 +1,43 @@
+const KNOWN_PUBLIC_HOSTS = [/github\.com/, /gitlab\.com/, /bitbucket\.org/];
+/**
+ * Heuristic only — NOT a network-verified "is this actually publicly
+ * fetchable" check (that would require a request, and `scan` never makes
+ * one). True accessibility depends on the repo's own visibility setting on
+ * that host, which only the host itself knows. This only recognizes
+ * well-known public-hosting domains and rules out URLs carrying embedded
+ * credentials (a strong signal of gated, non-public access).
+ *
+ * Known host != publicly accessible: the CLI's PRIMARY use case is a
+ * private employer repo hosted on github.com, so this must never block
+ * scanning — see publicHostWarning below and docs/privacy-tests.md.
+ *
+ * The real, network-backed check lives in submit.ts's checkVisibilityGate:
+ * an anonymous HEAD request made directly to the remote URL itself (never
+ * to Redential's servers), gated on isKnownPublicHost being true here
+ * first. `scan` never calls it — only `submit`, which already makes
+ * network calls, may.
+ */
+export function isKnownPublicHost(remoteUrl) {
+    if (!remoteUrl)
+        return false;
+    if (/:\/\/[^/@]+:[^/@]+@/.test(remoteUrl))
+        return false; // embedded user:pass or token-as-password
+    if (/[?&](?:token|access_token)=/i.test(remoteUrl))
+        return false; // token in the URL itself
+    return KNOWN_PUBLIC_HOSTS.some((host) => host.test(remoteUrl));
+}
+/**
+ * Informational only — returns a message to print, or null. Never a
+ * reason to skip scanning: this heuristic can say "this MIGHT be
+ * connectable", never "this IS public", so blocking on it would break the
+ * CLI's main use case (a private employer repo that happens to be hosted
+ * on github.com). The user decides; `scan` always proceeds.
+ */
+export function publicHostWarning(remoteUrl) {
+    if (!isKnownPublicHost(remoteUrl))
+        return null;
+    return ("Note: this repository's remote looks like it's hosted on GitHub, GitLab, or Bitbucket. " +
+        "If it's your own project and you can connect it directly, the GitHub App reads the actual " +
+        "code and grants a stronger tier than a local metadata scan. If this is a private/employer " +
+        "repo you can't connect that way, scanning normally (as below) is the right call — continuing.");
+}

package/dist/salt.js

@@ -0,0 +1,20 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { randomBytes } from "node:crypto";
+import { DEFAULT_CONFIG_DIR } from "./config.js";
+/**
+ * Device-local salt, persisted once per machine (same 0600 pattern as
+ * credentials.json). Its only job is to prevent rainbow-table lookups on
+ * repo_fingerprint / author_identity_hashes — not to anchor identity to an
+ * account, which is `login`'s job in a later milestone.
+ */
+export function getOrCreateSalt(configDir = DEFAULT_CONFIG_DIR) {
+    const saltPath = join(configDir, "salt");
+    if (existsSync(saltPath)) {
+        return readFileSync(saltPath, "utf8").trim();
+    }
+    mkdirSync(configDir, { recursive: true });
+    const salt = randomBytes(32).toString("hex");
+    writeFileSync(saltPath, salt, { mode: 0o600 });
+    return salt;
+}

package/dist/scan-command.js

@@ -0,0 +1,24 @@
+import { buildBundleInteractively } from "./build-bundle.js";
+import { formatSummary } from "./summary.js";
+/**
+ * The `scan` command's actual behavior, independent of commander wiring —
+ * exists mainly so the public-host warning ("warn, never block") is
+ * testable without spawning the built CLI.
+ *
+ * Output contract: piped/redirected stdout (or `--json`) always gets ONLY
+ * the raw bundle JSON, byte-identical to before the summary existed, so
+ * `scan | jq` keeps working. A real TTY (and no `--json`) gets the same
+ * JSON printed first, then the human-readable "wrapped" summary below it
+ * — JSON first so the summary is what's left on screen once the JSON has
+ * scrolled up. The summary is pure formatting over the bundle `runScan`
+ * already computed, not a second data source.
+ */
+export async function executeScanCommand(opts) {
+    const log = opts.log ?? console.log;
+    const bundle = await buildBundleInteractively(opts);
+    const bundleJson = JSON.stringify(bundle, null, 2);
+    log(bundleJson);
+    if (opts.isTTY && !opts.json) {
+        log(formatSummary(bundle));
+    }
+}

package/dist/scan.js

@@ -0,0 +1,145 @@
+import { extname } from "node:path";
+import { getAllCommits, getRemoteHostType, getRootCommitSha } from "./git.js";
+import { saltedHash } from "./hash.js";
+import { getOrCreateSalt } from "./salt.js";
+import { merkleRoot } from "./merkle.js";
+import { categorize } from "./categorize.js";
+import { isExcludedPath, heuristicallyGeneratedPaths } from "./churn-exclusions.js";
+import { detectSkills } from "./skill-detect.js";
+import { assertNoSecrets } from "./secret-scan.js";
+export { ScanError } from "./errors.js";
+import { ScanError } from "./errors.js";
+export function listAuthors(repoPath) {
+    const counts = new Map();
+    for (const c of getAllCommits(repoPath)) {
+        counts.set(c.email, (counts.get(c.email) ?? 0) + 1);
+    }
+    return [...counts.entries()]
+        .map(([email, count]) => ({ email, count }))
+        .sort((a, b) => b.count - a.count);
+}
+const MS_PER_DAY = 86_400_000;
+function normalizeExtension(filePath) {
+    const ext = extname(filePath).toLowerCase();
+    return /^\.[a-z0-9]+$/.test(ext) ? ext : null;
+}
+export function runScan(opts) {
+    if (!opts.confirmed) {
+        throw new ScanError("Authorization not confirmed. Re-run with --yes after confirming you are authorized to analyze this repository, or answer the interactive prompt.");
+    }
+    if (opts.authors.length === 0) {
+        throw new ScanError("No author identity selected. Pass --author <email> (repeatable) or select interactively.");
+    }
+    const allCommits = getAllCommits(opts.repoPath);
+    if (allCommits.length === 0) {
+        throw new ScanError("This repository has no commits yet — nothing to scan.");
+    }
+    const authorSet = new Set(opts.authors);
+    const userCommits = allCommits.filter((c) => authorSet.has(c.email));
+    if (userCommits.length === 0) {
+        throw new ScanError(`No commits found for the selected author(s): ${opts.authors.join(", ")}`);
+    }
+    const now = opts.now ?? new Date();
+    const distinctAuthors = new Set(allCommits.map((c) => c.email));
+    const otherContributorsCount = [...distinctAuthors].filter((e) => !authorSet.has(e)).length;
+    const salt = getOrCreateSalt(opts.configDir);
+    const authorHashes = opts.authors.map((e) => saltedHash(salt, e));
+    const rootSha = getRootCommitSha(opts.repoPath);
+    const repoFirstCommitDate = allCommits[0].authorDate;
+    const ageDays = Math.floor((now.getTime() - repoFirstCommitDate.getTime()) / MS_PER_DAY);
+    const hostType = getRemoteHostType(opts.repoPath);
+    const repoFingerprint = saltedHash(salt, rootSha);
+    const firstAt = userCommits[0].authorDate;
+    const lastAt = userCommits[userCommits.length - 1].authorDate;
+    const spanDays = Math.floor((lastAt.getTime() - firstAt.getTime()) / MS_PER_DAY);
+    const hourHistogram = new Array(24).fill(0);
+    const weekdayHistogram = new Array(7).fill(0);
+    for (const c of userCommits) {
+        hourHistogram[c.authorDate.getUTCHours()]++;
+        weekdayHistogram[c.authorDate.getUTCDay()]++;
+    }
+    const signedCount = userCommits.filter((c) => c.signed).length;
+    const { languages, categories } = computeChurnBreakdown(userCommits);
+    const detectedSkills = detectSkills(userCommits, opts.repoPath, opts.skillDetectOptions);
+    const bundle = {
+        schema_version: "1.0.0",
+        runner: "local",
+        tool_version: opts.toolVersion,
+        created_at: now.toISOString(),
+        repo: { host_type: hostType, age_days: ageDays, repo_fingerprint: repoFingerprint },
+        identity: {
+            author_identity_hashes: authorHashes,
+            other_contributors_count: otherContributorsCount,
+        },
+        commits: {
+            user_total: userCommits.length,
+            first_at: firstAt.toISOString(),
+            last_at: lastAt.toISOString(),
+            span_days: spanDays,
+            hour_histogram: hourHistogram,
+            weekday_histogram: weekdayHistogram,
+        },
+        signed: { count: signedCount, ratio: signedCount / userCommits.length },
+        languages,
+        categories,
+        detected_skills: detectedSkills,
+        ownership: { user_commit_ratio: userCommits.length / allCommits.length },
+        integrity: { merkle_root: merkleRoot(userCommits.map((c) => c.sha)), algorithm: "sha256" },
+        attestation: { authorized_confirmation: true, confirmed_at: now.toISOString() },
+    };
+    // Final gate before the bundle reaches any caller (scan's stdout, a
+    // future submit): the bundle's fields are all structurally bounded today
+    // and can't carry a secret, but this is the regression guard for the
+    // day a bug or a new field lets one through.
+    assertNoSecrets(JSON.stringify(bundle));
+    return bundle;
+}
+function computeChurnBreakdown(userCommits) {
+    const generatedPaths = heuristicallyGeneratedPaths(userCommits);
+    const churnByExt = new Map();
+    const churnByCategory = new Map();
+    const commitsByCategory = new Map();
+    let langChurnTotal = 0;
+    let categoryChurnTotal = 0;
+    for (const c of userCommits) {
+        const categoriesTouched = new Set();
+        for (const f of c.churn) {
+            const churn = f.added + f.deleted;
+            if (churn === 0)
+                continue;
+            // Lockfiles, minified bundles, build-output dirs, and single-commit
+            // generated dumps are checked-in artifacts, not authored work — see
+            // docs/schema.md's "What is excluded from churn".
+            if (isExcludedPath(f.path) || generatedPaths.has(f.path))
+                continue;
+            const ext = normalizeExtension(f.path);
+            if (ext) {
+                langChurnTotal += churn;
+                churnByExt.set(ext, (churnByExt.get(ext) ?? 0) + churn);
+            }
+            categoryChurnTotal += churn;
+            const category = categorize(f.path);
+            churnByCategory.set(category, (churnByCategory.get(category) ?? 0) + churn);
+            categoriesTouched.add(category);
+        }
+        for (const category of categoriesTouched) {
+            if (!commitsByCategory.has(category))
+                commitsByCategory.set(category, new Set());
+            commitsByCategory.get(category).add(c.sha);
+        }
+    }
+    const languages = langChurnTotal > 0
+        ? [...churnByExt.entries()].map(([extension, churn]) => ({
+            extension,
+            share: churn / langChurnTotal,
+        }))
+        : [];
+    const categories = categoryChurnTotal > 0
+        ? [...churnByCategory.entries()].map(([name, churn]) => ({
+            name,
+            commit_count: commitsByCategory.get(name).size,
+            churn_share: churn / categoryChurnTotal,
+        }))
+        : [];
+    return { languages, categories };
+}

package/dist/secret-scan.js

@@ -0,0 +1,37 @@
+import { ScanError } from "./errors.js";
+/**
+ * Deliberately narrow, low-noise patterns — this scans the FINAL serialized
+ * bundle (see docs/principles.md, "Bounded output"), not raw diff content.
+ * Every current bundle field is an enum, a hash, or a number, so none of
+ * these should ever fire on correctly-built output; this exists as a
+ * regression guard against a future bug or a careless new field, not as a
+ * general-purpose secret detector.
+ */
+const SECRET_PATTERNS = [
+    { name: "AWS access key ID", pattern: /\bAKIA[0-9A-Z]{16}\b/ },
+    {
+        name: "PEM private key",
+        pattern: /-----BEGIN (?:RSA |EC |OPENSSH |DSA |ENCRYPTED )?PRIVATE KEY-----/,
+    },
+    {
+        name: "API key/secret/token/password assignment",
+        pattern: /\b(?:api[_-]?key|secret|token|password)\b\s*[:=]\s*["']?[A-Za-z0-9_\-]{16,}/i,
+    },
+    { name: ".env-style KEY=VALUE assignment", pattern: /^[A-Z][A-Z0-9_]{2,}=\S+/m },
+];
+/** Names of the patterns that matched `payload` — never the matched text itself. */
+export function findSecretPatterns(payload) {
+    return SECRET_PATTERNS.filter(({ pattern }) => pattern.test(payload)).map(({ name }) => name);
+}
+/**
+ * Throws rather than returning a boolean so callers can't accidentally
+ * ignore the result. Never includes the matched substring in the error —
+ * only the pattern name — so the error itself can't leak the secret.
+ */
+export function assertNoSecrets(payload) {
+    const matches = findSecretPatterns(payload);
+    if (matches.length > 0) {
+        throw new ScanError(`Refusing to output: the bundle appears to contain a secret (${matches.join(", ")}). ` +
+            "This should never happen with normal usage — please report it.");
+    }
+}