@kya-os/cli 1.8.1 → 1.8.3

package/dist/utils/github-credential-stage.d.ts

@@ -0,0 +1,87 @@
+import { type AgentProfile } from "./agent-profiles.js";
+import { type AcquireGithubCredentialOptions, type SaveGithubCredentialResult, type StoredGithubCredential } from "./github-credential.js";
+import { buildGithubCredentialAnchor as defaultBuildGithubCredentialAnchor, identityForAgentProfile as defaultIdentityForAgentProfile, readPendingAnchor as defaultReadPendingAnchor, type BuiltGithubCredentialAnchor, type DeliverGithubCredentialAnchorResult } from "../orchestrator/github-credential-anchor-sender.js";
+import type { ObserverIdentity } from "../orchestrator/hub-observer.js";
+/**
+ * Orchestrates `kya-os init`'s GitHub credential stage (review-loop P16
+ * commit 4): acquire the single per-machine GitHub credential, store it,
+ * and anchor it in the hub, binding it to every agent profile already on
+ * this machine (the P15 profile stage, which this runs strictly after --
+ * an anchor with no `agentDids` to bind is meaningless, so this stage is a
+ * clean skip on a machine with none).
+ *
+ * Every side effect (listing profiles, reading the env, acquiring,
+ * confirming rotation, saving, building, delivering) is an injectable seam,
+ * mirroring `agent-profile-stage.ts`'s pattern, so the whole stage runs in
+ * tests with zero real `gh`, prompt, or network access.
+ */
+export interface GithubCredentialStageOptions {
+    interactive: boolean;
+    /** `--skip-github`: skip this stage entirely. */
+    skipGithub?: boolean;
+    /**
+     * `--github-token-env <NAME>`: read the token from that env var instead
+     * of `gh auth token` or an interactive prompt. The ONLY non-interactive
+     * path -- without it, a non-interactive run skips this stage rather than
+     * risk hanging on a prompt with no TTY to answer it.
+     */
+    githubTokenEnv?: string;
+    /** Resolved hub endpoint (e.g. from `--hub` or `DIDCOMM_HUB_ENDPOINT`), or undefined = not configured. */
+    hubEndpoint?: string;
+    now?: () => string;
+    onNotice?: (message: string) => void;
+    listProfilesImpl?: () => AgentProfile[];
+    readEnvImpl?: (name: string) => string | undefined;
+    acquireCredentialImpl?: (options: AcquireGithubCredentialOptions) => Promise<StoredGithubCredential>;
+    /** Pass-through acquisition seams (gh/prompt mocks) for full test isolation. */
+    acquisitionSeams?: Pick<AcquireGithubCredentialOptions, "isGhInstalledImpl" | "isGhAuthenticatedImpl" | "apiUserWithHeadersImpl" | "apiUserWithHeadersForTokenImpl" | "ghAuthTokenImpl" | "promptForTokenImpl" | "randomBytesImpl">;
+    confirmRotateImpl?: () => Promise<boolean>;
+    saveCredentialImpl?: (credential: StoredGithubCredential, options: {
+        confirmRotateImpl: () => Promise<boolean>;
+    }) => Promise<SaveGithubCredentialResult>;
+    buildAnchorImpl?: typeof defaultBuildGithubCredentialAnchor;
+    deliverAnchorImpl?: (anchor: BuiltGithubCredentialAnchor["anchor"], identity: BuiltGithubCredentialAnchor["identity"], options: {
+        hubEndpoint?: string;
+        onNotice?: (message: string) => void;
+    }) => Promise<DeliverGithubCredentialAnchorResult>;
+    /** Reads `~/.mcpi/github/pending-anchor.json`, or undefined if nothing is queued. */
+    readPendingAnchorImpl?: typeof defaultReadPendingAnchor;
+    /** Derives the signer profile's wire identity for re-authenticating a pending anchor's delivery. */
+    identityForAgentProfileImpl?: typeof defaultIdentityForAgentProfile;
+    deliverPendingAnchorImpl?: (resolveIdentity: (signerDid: string) => ObserverIdentity | undefined, options: {
+        hubEndpoint?: string;
+        onNotice?: (message: string) => void;
+    }) => Promise<DeliverGithubCredentialAnchorResult | {
+        status: "none";
+    }>;
+}
+export type GithubCredentialStageResult = {
+    status: "skipped";
+    reason: "flag" | "no-profiles" | "non-interactive";
+} | {
+    status: "declined-rotation";
+} | {
+    status: "completed";
+    githubLogin: string;
+    anchorDelivery: "delivered" | "pending";
+}
+/**
+ * The credential was acquired and IS saved on disk (usable by `dco setup`
+ * and friends today), but building the signed anchor threw before an
+ * anchor object ever existed -- e.g. the signer profile's signing key file
+ * is missing or unreadable. Distinct from `completed`'s `anchorDelivery:
+ * "pending"` (a valid anchor exists and is queued at
+ * `pending-anchor.json`, just not yet delivered): here there is nothing
+ * valid to queue, since `pending-anchor.json` requires a real signature.
+ * Reported explicitly rather than let the exception propagate into a
+ * generic catch, so the operator learns their credential WAS saved but
+ * is NOT yet anchored anywhere, instead of the two states being
+ * indistinguishable from "something in this stage failed."
+ */
+ | {
+    status: "anchor-build-failed";
+    githubLogin: string;
+    reason: string;
+};
+export declare function runGithubCredentialStage(options: GithubCredentialStageOptions): Promise<GithubCredentialStageResult>;
+//# sourceMappingURL=github-credential-stage.d.ts.map

package/dist/utils/github-credential-stage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"github-credential-stage.d.ts","sourceRoot":"","sources":["../../src/utils/github-credential-stage.ts"],"names":[],"mappings":"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"}

package/dist/utils/github-credential-stage.js

@@ -0,0 +1,168 @@
+import { listProfiles as defaultListProfiles } from "./agent-profiles.js";
+import { acquireGithubCredential as defaultAcquireGithubCredential, fingerprintSecret, saveGithubCredential as defaultSaveGithubCredential, } from "./github-credential.js";
+import { buildGithubCredentialAnchor as defaultBuildGithubCredentialAnchor, deliverGithubCredentialAnchor as defaultDeliverGithubCredentialAnchor, deliverPendingGithubCredentialAnchor as defaultDeliverPendingGithubCredentialAnchor, identityForAgentProfile as defaultIdentityForAgentProfile, readPendingAnchor as defaultReadPendingAnchor, } from "../orchestrator/github-credential-anchor-sender.js";
+/**
+ * Decide where this run's token is coming from, without acquiring it yet:
+ * `--github-token-env` (validated non-empty), or "the normal acquisition
+ * flow decides" (gh-auth or an interactive prompt) when interactive, or a
+ * clean skip when neither applies. Factored out of `runGithubCredentialStage`
+ * so that function reads as one pipeline (resolve source -> acquire -> save
+ * -> anchor -> deliver) instead of interleaving this branch with it.
+ */
+function resolveGithubTokenSource(options, onNotice) {
+    if (!options.githubTokenEnv) {
+        if (options.interactive)
+            return {};
+        // Non-interactive with no explicit token source: never risk hanging on
+        // a masked prompt with no TTY to answer it.
+        onNotice("Non-interactive and no --github-token-env given -- skipping the GitHub credential stage.");
+        return { skip: { status: "skipped", reason: "non-interactive" } };
+    }
+    const readEnvImpl = options.readEnvImpl ?? ((name) => process.env[name]);
+    const presetToken = readEnvImpl(options.githubTokenEnv);
+    if (!presetToken) {
+        throw new Error(`--github-token-env ${options.githubTokenEnv} was given but that environment variable is empty or unset.`);
+    }
+    return { presetToken };
+}
+async function defaultConfirmRotate() {
+    const inquirer = (await import("inquirer")).default;
+    const { confirmed } = await inquirer.prompt([
+        {
+            type: "confirm",
+            name: "confirmed",
+            message: "A GitHub credential is already stored on this machine. Rotate it?",
+            default: false,
+        },
+    ]);
+    return confirmed;
+}
+/** `--github-token-env` always rotates without asking: the operator handed over a specific token value to write, which is itself the confirmation an interactive run gets by prompt. */
+async function autoConfirmRotate() {
+    return true;
+}
+export async function runGithubCredentialStage(options) {
+    const onNotice = options.onNotice ?? (() => { });
+    if (options.skipGithub) {
+        return { status: "skipped", reason: "flag" };
+    }
+    const listProfilesImpl = options.listProfilesImpl ?? defaultListProfiles;
+    const profiles = listProfilesImpl();
+    if (profiles.length === 0) {
+        onNotice("No agent profiles to bind a GitHub credential to yet -- run `kya-os init` again after setting up at least one.");
+        return { status: "skipped", reason: "no-profiles" };
+    }
+    // The first profile on the machine signs a FRESH anchor (see the build
+    // step below) -- but a previously QUEUED anchor may have been signed by
+    // a different profile than whichever one `listProfiles()` happens to
+    // return first today (its order is `readdirSync`'s, not stable), so the
+    // pending-flush path below resolves the signer by the DID actually
+    // recorded at queue time, never by re-deriving "profiles[0]".
+    const signer = profiles[0];
+    // Flush a previously queued anchor before acquiring anything new -- but
+    // ONLY when this run has no explicit intent to acquire a SPECIFIC token
+    // right now. `--github-token-env` IS that explicit intent: flushing
+    // first would either silently skip the rotation the operator just asked
+    // for (flush succeeds, the OLD credential's anchor lands in the hub and
+    // the stage returns before ever reading the env var) or discard the
+    // queued anchor for an unrelated fresh one (flush fails, the normal flow
+    // below auto-rotates per --github-token-env regardless). The plain "just
+    // re-run kya-os init to see if the hub is up now" case -- no token
+    // source override -- is what this retry exists for; without it,
+    // deliverPendingGithubCredentialAnchor was dead code, since this stage
+    // never called it and a queued anchor sat on disk forever.
+    if (!options.githubTokenEnv) {
+        const readPendingAnchorImpl = options.readPendingAnchorImpl ?? defaultReadPendingAnchor;
+        const pending = readPendingAnchorImpl();
+        if (pending) {
+            const identityForAgentProfileImpl = options.identityForAgentProfileImpl ?? defaultIdentityForAgentProfile;
+            const deliverPendingAnchorImpl = options.deliverPendingAnchorImpl ?? defaultDeliverPendingGithubCredentialAnchor;
+            const resolveIdentityForDid = (did) => {
+                const match = profiles.find((p) => p.did === did);
+                return match ? identityForAgentProfileImpl(match.did, match.slug) : undefined;
+            };
+            const pendingResult = await deliverPendingAnchorImpl(resolveIdentityForDid, {
+                hubEndpoint: options.hubEndpoint,
+                onNotice,
+            });
+            if (pendingResult.status === "delivered") {
+                onNotice(`Delivered the previously queued GitHub credential anchor for ${pending.anchor.githubLogin} to the hub.`);
+                return {
+                    status: "completed",
+                    githubLogin: pending.anchor.githubLogin,
+                    anchorDelivery: "delivered",
+                };
+            }
+            // "pending" (still can't reach the hub, or the signer profile is
+            // gone) -- fall through to the normal flow below exactly as before;
+            // re-acquiring will re-queue or redeliver an anchor.
+            // deliverPendingAnchorImpl never returns "none" here: `pending`
+            // above already proved something is queued.
+        }
+    }
+    const tokenSource = resolveGithubTokenSource(options, onNotice);
+    if ("skip" in tokenSource) {
+        return tokenSource.skip;
+    }
+    const { presetToken } = tokenSource;
+    const acquireCredentialImpl = options.acquireCredentialImpl ?? defaultAcquireGithubCredential;
+    const credential = await acquireCredentialImpl({
+        ...options.acquisitionSeams,
+        presetToken,
+        now: options.now,
+        onNotice,
+    });
+    const saveCredentialImpl = options.saveCredentialImpl ?? defaultSaveGithubCredential;
+    // `--github-token-env` is the documented non-interactive rotation path
+    // (docs/single-account-github.md): defaulting to the interactive prompt
+    // here regardless meant a second `--github-token-env` run against an
+    // existing credentials.json hung waiting for a TTY (or threw, off one),
+    // instead of rotating as documented. A `presetToken` came from that exact
+    // flag, which is itself the operator's explicit confirmation -- an
+    // interactive run (no presetToken) still gets asked.
+    const confirmRotateImpl = options.confirmRotateImpl ?? (presetToken !== undefined ? autoConfirmRotate : defaultConfirmRotate);
+    const saveResult = await saveCredentialImpl(credential, { confirmRotateImpl });
+    if (saveResult.status === "declined") {
+        onNotice("Keeping the existing GitHub credential -- rotation was not confirmed.");
+        return { status: "declined-rotation" };
+    }
+    // `signer` (the first profile on the machine, declared above) signs the
+    // anchor -- same "first profile is special" convention
+    // runProfileStageAndUpdateRegistry already uses to pick the review
+    // registry's fixer candidate -- but EVERY profile's DID is bound as
+    // authorized, since the credential is shared machine-wide.
+    const buildAnchorImpl = options.buildAnchorImpl ?? defaultBuildGithubCredentialAnchor;
+    let built;
+    try {
+        built = buildAnchorImpl(credential, {
+            tokenFingerprint: fingerprintSecret(credential.token),
+            webhookSecretFingerprint: fingerprintSecret(credential.webhookSecret),
+        }, {
+            agentDid: signer.did,
+            agentSlug: signer.slug,
+            agentDids: profiles.map((p) => p.did),
+            supersedes: saveResult.supersedesFingerprint,
+            now: options.now,
+        });
+    }
+    catch (error) {
+        // The credential is already saved -- surface that distinctly rather
+        // than let this propagate into a generic "the stage failed" catch that
+        // would leave the operator unsure whether anything was persisted.
+        const reason = error instanceof Error ? error.message : String(error);
+        onNotice(`GitHub credential saved, but the anchor could not be signed (${reason}) -- it is NOT yet anchored in the hub. Run \`kya-os init\` again once this is fixed.`);
+        return { status: "anchor-build-failed", githubLogin: credential.githubLogin, reason };
+    }
+    const { anchor, identity } = built;
+    const deliverAnchorImpl = options.deliverAnchorImpl ?? defaultDeliverGithubCredentialAnchor;
+    const deliveryResult = await deliverAnchorImpl(anchor, identity, {
+        hubEndpoint: options.hubEndpoint,
+        onNotice,
+    });
+    return {
+        status: "completed",
+        githubLogin: credential.githubLogin,
+        anchorDelivery: deliveryResult.status,
+    };
+}
+//# sourceMappingURL=github-credential-stage.js.map

package/dist/utils/github-credential-stage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"github-credential-stage.js","sourceRoot":"","sources":["../../src/utils/github-credential-stage.ts"],"names":[],"mappings":"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"}

package/dist/utils/github-credential.d.ts

@@ -0,0 +1,160 @@
+/**
+ * Single-account GitHub credential onboarding (review-loop P16).
+ *
+ * One person's ONE GitHub credential, acquired once per machine and shared
+ * by every one of that person's agent profiles (P15) -- not one GitHub
+ * account per agent, not a GitHub App. Sentinel's PAT flow is the precedent
+ * (local checkout `/Users/marshall/@kya-os/sentinel` @ 83c0ed5): classic
+ * `repo` + `admin:repo_hook`, or the fine-grained equivalent
+ * ({@link FINE_GRAINED_GRANTS}). No octokit dependency anywhere in this
+ * module -- every GitHub call shells out to `gh`, the same house pattern
+ * `dco/github.ts` uses.
+ *
+ * SECURITY: the token and the webhook secret this module generates must
+ * NEVER be logged, printed, or written anywhere but
+ * {@link credentialsPath}. Read the incident note this module follows
+ * before touching any of the write paths below: checkpoint
+ * `apps/web/scripts/provision-scout.ts:49-56` documents a live credential
+ * that sat one `git add -A` away from being committed because a script
+ * wrote it into the repo checkout's cwd instead of a dedicated,
+ * gitignore-independent location. `credentialsPath()` resolves under
+ * `~/.mcpi/github/`, never the process cwd, for exactly that reason.
+ *
+ * @module cli/utils/github-credential
+ */
+export interface StoredGithubCredential {
+    githubLogin: string;
+    /** The raw PAT. Never logged; never leaves this machine. */
+    token: string;
+    /** 32 random bytes, hex-encoded. Generated at acquisition time (see module doc). */
+    webhookSecret: string;
+    /** Scopes/grants as acquired -- see {@link acquireGithubCredential}. */
+    scopes: string[];
+    createdAt: string;
+}
+/** Absolute path to the credential directory, e.g. ~/.mcpi/github. Overridable for tests via MCPI_GITHUB_DIR. */
+export declare function credentialsDir(): string;
+/** Absolute path to the credential store file. */
+export declare function credentialsPath(): string;
+/**
+ * sha256 hex digest of a secret's raw bytes (the token, or the webhook
+ * secret). GitHub PATs and this module's hex-encoded webhook secrets are
+ * always ASCII, so UTF-8 encoding is exact-byte equivalent to hashing the
+ * secret's actual byte representation. This is the ONLY form either secret
+ * is ever allowed to leave this module in -- the anchor (see
+ * `github-credential-anchor.ts`) carries fingerprints exclusively.
+ */
+export declare function fingerprintSecret(secret: string): string;
+/** The currently stored credential, or undefined if none exists (or the file is unreadable/corrupt). */
+export declare function readStoredCredential(): StoredGithubCredential | undefined;
+export type SaveGithubCredentialResult = {
+    status: "saved";
+    credential: StoredGithubCredential;
+    /** The prior credential's tokenFingerprint, set only when this save rotated an existing one. */
+    supersedesFingerprint?: string;
+} | {
+    status: "declined";
+};
+export interface SaveGithubCredentialOptions {
+    /**
+     * Asked only when a credential file already exists. Declining leaves the
+     * existing file completely untouched. No default: a caller that forgets
+     * to wire this in non-interactive contexts gets a type error, not an
+     * accidental silent overwrite of a live credential.
+     */
+    confirmRotateImpl: () => Promise<boolean>;
+}
+/**
+ * Persist `credential` at {@link credentialsPath}, 0600 inside a 0700
+ * directory ({@link credentialsDir}).
+ *
+ * A pre-existing file is never silently overwritten (sentinel `8297a1e`'s
+ * lesson, transposed: operate only on YOUR OWN prior credential, and only
+ * once that's been confirmed, never by assuming the file is stale). This
+ * check is on FILE PRESENCE, not on `readStoredCredential`'s shape-validated
+ * result: a file that exists but fails the shape guard (corrupt, truncated
+ * by an interrupted prior write, or a future incompatible format) still has
+ * a live token sitting in it and must still gate on confirmation -- treating
+ * "can't parse it" the same as "nothing here" would silently discard that
+ * token with no rotation record, exactly the audit-trail gap anchoring
+ * exists to close. On a confirmed rotation the old file is replaced
+ * atomically (write temp + rename, `writeFileAtomicSafe`) and, when the
+ * prior file WAS well-formed, the result carries its token's fingerprint as
+ * `supersedesFingerprint` for the caller to bind into the next anchor's
+ * `supersedes` field -- absent when the prior file was corrupt, since there
+ * is no valid token to fingerprint.
+ */
+export declare function saveGithubCredential(credential: StoredGithubCredential, options: SaveGithubCredentialOptions): Promise<SaveGithubCredentialResult>;
+/** Sentinel's proven classic-token grant list (README:33-35, `Know-That-Ai/sentinel` @ 83c0ed5). */
+export declare const CLASSIC_REQUIRED_SCOPES: readonly ["repo", "admin:repo_hook"];
+/** Sentinel's proven fine-grained equivalent, printed verbatim for the user to grant. */
+export declare const FINE_GRAINED_GRANTS: readonly ["Metadata: Read", "Pull requests: Read & Write", "Contents: Read", "Webhooks: Read & Write"];
+export declare const GITHUB_PAT_SETTINGS_URL = "https://github.com/settings/personal-access-tokens/new";
+export interface ScopeProbeResult {
+    /**
+     * Which probe actually ran. Classic tokens report scopes via the
+     * `X-OAuth-Scopes` response header; fine-grained tokens report nothing,
+     * so the probe falls back to the least-privileged read available to any
+     * authenticated token (`GET /user`) and can only confirm the token
+     * authenticates, not which grants it actually holds.
+     */
+    probe: "classic-x-oauth-scopes" | "fine-grained-user-read";
+    ok: boolean;
+    login?: string;
+    /** Only ever populated for the classic probe -- see `probe`'s doc. */
+    scopes?: string[];
+    /** Only ever populated for a failed classic probe. */
+    missing?: string[];
+    /** Human-readable, always present, names which probe ran either way. */
+    detail: string;
+}
+/**
+ * Parse `gh api user -i` output (headers followed by a blank line, then the
+ * JSON body) into a {@link ScopeProbeResult}. Pure -- no process spawning --
+ * so this is unit-testable directly against canned `gh` output without a
+ * live GitHub call or even a `gh` binary on PATH.
+ */
+export declare function parseGhApiUserWithHeaders(raw: string): ScopeProbeResult;
+export interface AcquireGithubCredentialOptions {
+    isGhInstalledImpl?: () => Promise<boolean>;
+    isGhAuthenticatedImpl?: () => Promise<boolean>;
+    /** `gh api user -i` using gh's own stored auth. */
+    apiUserWithHeadersImpl?: () => Promise<string>;
+    /** `gh api user -i` authenticated as a pasted token. */
+    apiUserWithHeadersForTokenImpl?: (token: string) => Promise<string>;
+    ghAuthTokenImpl?: () => Promise<string>;
+    promptForTokenImpl?: () => Promise<string>;
+    randomBytesImpl?: (size: number) => Buffer;
+    now?: () => string;
+    /** Surfaces probe/scope detail to the user -- injectable so tests assert on it without a real console write. */
+    onNotice?: (message: string) => void;
+    /**
+     * A token supplied directly (e.g. `kya-os init --github-token-env NAME`),
+     * bypassing BOTH `gh auth token` and the interactive paste prompt. The
+     * caller is responsible for reading it from the named env var and never
+     * logging it; this module still verifies it the same way a pasted token
+     * is verified, and still never echoes it.
+     */
+    presetToken?: string;
+}
+/**
+ * Acquire the single GitHub credential for this person on this machine.
+ *
+ * Acquisition order:
+ *   0. `options.presetToken`, when supplied (`kya-os init --github-token-env
+ *      NAME`) -- skips both of the below entirely, for a fully
+ *      non-interactive run. Verified the same way a pasted token is.
+ *   1. `gh auth token`, when `gh` is installed, authenticated, and the
+ *      scope probe against its stored token passes (classic: all of
+ *      {@link CLASSIC_REQUIRED_SCOPES} present via `X-OAuth-Scopes`;
+ *      fine-grained: the `GET /user` probe authenticates).
+ *   2. Otherwise, prompt for a pasted fine-grained PAT created with
+ *      {@link FINE_GRAINED_GRANTS}, verified the same way.
+ *
+ * Always generates a fresh `webhookSecret` (32 random bytes, hex) even
+ * though the webhook receiver itself ships in P17 -- the anchor binds it
+ * from day one so the rotation history the hub sees is complete from the
+ * very first anchor.
+ */
+export declare function acquireGithubCredential(options?: AcquireGithubCredentialOptions): Promise<StoredGithubCredential>;
+//# sourceMappingURL=github-credential.d.ts.map

package/dist/utils/github-credential.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"github-credential.d.ts","sourceRoot":"","sources":["../../src/utils/github-credential.ts"],"names":[],"mappings":"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"}