@ashlr/hub 3.12.0 → 3.13.0

package/dist/cli/authority.d.ts

@@ -1,4 +1,6 @@
-import type { StandingGrantTrustRoot } from '../core/authority/types.js';
+import type { ResidentAdmission, ResidentPlistState } from '../core/authority/resident.js';
+import type { AuthoritySetupNeed, AuthoritySetupReportV1, AuthoritySetupStepStatus, StandingGrantTrustRoot } from '../core/authority/types.js';
+export type { AuthoritySetupReportV1 } from '../core/authority/types.js';
 export interface GhResult {
     status: number;
     stdout: string;
@@ -11,16 +13,52 @@ export interface AuthorityCliDeps {
     confirm(question: string): Promise<boolean>;
     /** Read a secret without echoing it. */
     readSecret(prompt: string): Promise<string>;
-    /** Run `gh` or `git` with argv — never through a shell. */
+    /**
+     * Run `gh` or `git` with argv — never through a shell. May answer
+     * asynchronously (the Verse server's read-only probe runner must not block
+     * its event loop), so every caller awaits it.
+     */
     run(bin: 'gh' | 'git', args: readonly string[], opts?: {
         cwd?: string;
         input?: string;
-    }): GhResult;
+    }): GhResult | Promise<GhResult>;
     openBrowser(url: string): void;
     fetch: typeof fetch;
     custody: typeof import('../core/authority/custody-client.js');
     /** Read-only: the resident daemon service's state (setup's last step). Never changes launchd. */
     daemonService(): Promise<DaemonServiceState>;
+    /** `resident start|stop|status` and setup's resident step (docs/RESIDENT-RUNTIME.md). */
+    resident: ResidentCliDeps;
+}
+/** What `resident status` and setup read about the installed service. Read-only. */
+export interface ResidentServiceObservation {
+    state: DaemonServiceState;
+    /** The installed plist vs the one `resident start` would write from config now. */
+    plist: ResidentPlistState;
+    plistPath: string | null;
+    installedBudgetUsd: number | null;
+    expectedBudgetUsd: number | null;
+    /** Why the expected plist could not be computed (config unreadable…); null when it could. */
+    problem: string | null;
+}
+export type ResidentEffectResult = {
+    ok: true;
+    detail: string;
+} | {
+    ok: false;
+    reason: string;
+};
+export interface ResidentCliDeps {
+    /** Fresh, read-only admission verdict for the code this process runs. */
+    admission(): Promise<ResidentAdmission>;
+    /** Read-only service + plist observation. Never changes launchd. */
+    observe(): Promise<ResidentServiceObservation>;
+    /** Why this process is not the operator at a terminal; null when it is. */
+    operatorRefusal(): Promise<string | null>;
+    /** Mint the capability (re-verifying everything), record it, install / restart the service. */
+    start(): Promise<ResidentEffectResult>;
+    /** Lowering: boot the service out and remove its plist. Never touches Stop or the grant. */
+    stop(): Promise<ResidentEffectResult>;
 }
 /** The resident daemon service as setup reports it. */
 export type DaemonServiceState = 'running' | 'loaded' | 'not-loaded' | 'absent' | 'unknown';
@@ -45,11 +83,41 @@ export interface RequiredCheck {
     integrationId: number | null;
 }
 export declare function buildFleetRuleset(requiredChecks: readonly (string | RequiredCheck)[]): Record<string, unknown>;
+/** The check the ashlr-fleet App posts on fleet PR heads (core/fleet/verify-check-run.ts ASHLR_VERIFY_CHECK_NAME). */
+export declare const ASHLR_VERIFY_CHECK = "ashlr/verify";
+export interface FleetAppInfo {
+    id: number;
+    slug: string;
+    ownerLogin: string;
+    ownerIsOrg: boolean;
+    /** The App's configured permission for check runs ('write' | 'read' | null = none). */
+    checks: string | null;
+}
+/** The ashlr-fleet App as GitHub describes it to your own gh auth (a `gh api` read); null = unreadable. */
+export declare function readFleetApp(deps: AuthorityCliDeps): Promise<FleetAppInfo | null>;
+/** PURE: where the App's permissions (and then each installation's acceptance) are changed. */
+export declare function fleetAppPermissionUrls(app: Pick<FleetAppInfo, 'slug' | 'ownerLogin' | 'ownerIsOrg'>): {
+    permissions: string;
+    installations: string;
+};
+/**
+ * PURE: `actual` (a ruleset as GitHub returns it) already says everything
+ * `desired` says. GitHub adds ids, links, timestamps and server-side rule
+ * defaults to what it returns, so extra object keys are ignored — but every
+ * field we set must match, and arrays must match one-to-one in any order, so
+ * an extra rule, an extra bypass actor or an extra required check is drift
+ * (re-applying would remove it). Anything unreadable is "not up to date".
+ */
+export declare function rulesetMatches(desired: unknown, actual: unknown): boolean;
 export declare const FLEET_APP_NAME = "ashlr-fleet";
 /**
- * PURE: the App manifest. Contents + pull requests read/write, checks /
- * statuses / metadata read. No workflows, no administration — GitHub itself
- * then refuses CI-config and protection changes from the fleet.
+ * PURE: the App manifest. Contents + pull requests read/write, checks
+ * read/write (3.13: the App posts the host-verified `ashlr/verify` check run
+ * on fleet PR heads — core/fleet/verify-check-run.ts), statuses / metadata
+ * read. No workflows, no administration — GitHub itself then refuses
+ * CI-config and protection changes from the fleet. An App created before 3.13
+ * has `checks: read`; `ashlr authority setup` detects that and prints where
+ * to raise it (fleetAppPermissionUrls).
  */
 export declare function buildGithubAppManifest(redirectUrl: string): Record<string, unknown>;
 /** PURE: the local page that POSTs the manifest to GitHub. */
@@ -68,13 +136,60 @@ export declare function runGithubAppFlow(deps: AuthorityCliDeps, opts: {
     org: string | null;
     timeoutMs?: number;
 }): Promise<GithubAppFlowResult>;
+/** Where Mason installs the App (and picks its repos). */
+export declare const FLEET_APP_INSTALL_URL = "https://github.com/apps/ashlr-fleet/installations/new";
+export interface AppInstallProbe {
+    installed: string[];
+    missing: string[];
+    unknown: {
+        repo: string;
+        reason: string;
+    }[];
+}
+/**
+ * Where the ashlr-fleet App is installed — read-only, in two passes:
+ *
+ *  1. per owner, `gh api orgs/<owner>/installations` with Mason's own gh auth
+ *     (a GET; needs admin:org). An installation on "All repositories" settles
+ *     every repo of that owner; no installation at all settles them as missing.
+ *  2. what that cannot settle (a user account, "Only select repositories", a
+ *     gh token without admin:org) is asked of the App itself: custody's
+ *     gh-token looks the repo up AS the App (GET /repos/<r>/installation under
+ *     the App's JWT), and a 404 there means "not installed". The one-hour token
+ *     the helper mints on success stays in this process's memory, is never
+ *     printed, and changes nothing on GitHub.
+ */
+export declare function probeAppInstallation(deps: AuthorityCliDeps, repos: readonly string[]): Promise<AppInstallProbe>;
+/**
+ * - `rotated`   — the key in place is the one a rotation created (setup must not rotate it again:
+ *                 that would invalidate every pending proposal for nothing);
+ * - `unrotated` — a key no rotation recorded: the one agents could read while confinement was off;
+ * - `missing`   — no key yet (nothing burned; the first one is created fresh);
+ * - `unhealthy` — the key's storage is refused (symlink, mode, length…).
+ */
+export type ProvenanceKeyState = {
+    state: 'rotated';
+    rotatedAt: string;
+} | {
+    state: 'unrotated';
+} | {
+    state: 'missing';
+} | {
+    state: 'unhealthy';
+    reason: string;
+};
+/** Read-only: never creates, repairs or moves the key. */
+export declare function provenanceKeyState(): Promise<ProvenanceKeyState>;
 /**
  * Move the provenance HMAC key aside and create a new one. Every pending
  * provenance signature stops verifying (by design: agents could read the old
  * key while confinement was off), so pending proposals are re-verified.
+ * Records which key it made (provenanceKeyState reads it) so setup can tell
+ * a key it already rotated from the burned one.
  */
 export declare function rotateProvenanceKey(): Promise<{
     retiredAs: string | null;
+    rotatedAt: string;
 }>;
 /** PURE: trust-roots.ts with `root` added, or null when the file is not in its day-0 shape. */
 export declare function renderTrustRootsWithKey(source: string, root: StandingGrantTrustRoot): string | null;
@@ -87,38 +202,35 @@ export declare function renderTrustRootsWithKey(source: string, root: StandingGr
 export declare function validateCustodyRoot(root: StandingGrantTrustRoot, keyIdFor: (pem: string) => string): string | null;
 /** PURE: the canary repo's CI (addendum §7) — a test that can be turned red on purpose. */
 export declare const CANARY_WORKFLOW = "name: CI\non:\n  push:\n    branches: [main]\n  pull_request:\njobs:\n  test:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n      - name: canary\n        run: |\n          if [ -f RED ]; then echo \"canary is red on purpose\"; exit 1; fi\n          echo \"canary green\"\n";
-type StepStatus = 'done' | 'already' | 'waiting-on-you' | 'skipped' | 'blocked' | 'failed';
+type StepStatus = AuthoritySetupStepStatus;
 /** What a setup step needs from Mason himself (a UI renders these as badges). */
-export type SetupNeed = 'sudo' | 'touch-id' | 'browser' | 'github' | 'terminal';
-/** `ashlr authority setup --dry-run --json` — the checklist a UI can render. */
-export interface AuthoritySetupReportV1 {
-    schema: 'ashlr.authority-setup.v1';
-    dryRun: boolean;
-    /** Every step is done or already in place, including resident runtime admission. */
-    complete: boolean;
-    summary: {
-        done: number;
-        already: number;
-        waitingOnYou: number;
-        blocked: number;
-        failed: number;
-        planned: number;
-    };
-    steps: {
-        id: string;
-        step: string;
-        status: StepStatus;
-        detail: string;
-        needs: readonly SetupNeed[];
-    }[];
-    /** The first step that is not done or already in place (null when complete). */
-    next: string | null;
-}
+export type SetupNeed = AuthoritySetupNeed;
+/** The one command that walks every step and resumes where the last run stopped. */
+export declare const AUTHORITY_SETUP_COMMAND = "ashlr authority setup";
 type SetupRow = {
     step: string;
     status: StepStatus;
     detail: string;
+    command?: string | null;
+    link?: string | null;
 };
 /** PURE: the machine-readable form of a setup run. */
 export declare function authoritySetupReport(report: readonly SetupRow[], dryRun: boolean): AuthoritySetupReportV1;
-export {};
+/**
+ * The read-only probe's runner: `gh api <path>` — a GET, since no field,
+ * method or input flag is ever passed — run asynchronously (the Verse server
+ * must not block its event loop) and killed after READ_ONLY_GH_TIMEOUT_MS.
+ * Anything else (git, `gh pr`, `gh repo create`, `--method`) is refused
+ * without running, so a dry-run path that ever grew a write could not reach it.
+ */
+/** PURE: `gh api <path>` with nothing else — the only call the read-only probe runs. */
+export declare function isReadOnlyGhApiCall(bin: 'gh' | 'git', args: readonly string[]): boolean;
+export declare function readOnlyGhRun(bin: 'gh' | 'git', args: readonly string[]): Promise<GhResult>;
+/**
+ * `ashlr authority setup --dry-run --json` as a function: the same planning
+ * path (cmdSetup's steps with --dry-run), with dependencies that cannot ask,
+ * prompt, open a browser, reach the network directly or run anything but a
+ * bounded `gh api` GET. Custody is only asked read-only questions (status,
+ * host binding, public key, and whether the App can see a repo).
+ */
+export declare function planAuthoritySetup(injected?: Partial<AuthorityCliDeps>): Promise<AuthoritySetupReportV1>;