/**
 * Shared on-demand download + verification for the macOS native helper `.app`
 * bundles that ship as signed + notarized GitHub release assets on each helper's
 * OWN tag (`ComputerHelper.app`, `MenubarHelper.app`, `Agents CLI.app`) — see
 * `helper-versions.ts` for why they are no longer keyed to the CLI's tag.
 *
 * A `.app` is a directory, so each asset is a zip (`ditto -c -k --keepParent`);
 * a fresh `npm i -g` machine with no bundled copy fetches the asset for the
 * pinned helper version, verifies its sha256 against the published `.sha256`,
 * then verifies the code signature (Developer ID Team + notarization — and, for
 * the menu-bar helper, its designated requirement) before it is ever installed.
 *
 * `computer/download.ts` (ComputerHelper) and `menubar/download-menubar.ts`
 * (MenubarHelper) are thin per-helper wrappers over the primitives here — one
 * download+verify machinery, two specs — so a fix to the verify/download logic
 * lands for both helpers at once.
 */
import { type HelperName } from './helper-versions.js';
/**
 * GitHub repo whose `<helper>/v<version>` releases carry the helper assets.
 *
 * This is the SLUG, which is not the npm package name: the package is still
 * `@phnx-labs/agents-cli`, but the repository was renamed to `agi-cli`. The old
 * slug kept working only because GitHub redirects a renamed repo, which is a
 * poor thing to hang signed-binary delivery on — a redirect is one re-created
 * repo away from resolving somewhere else. What actually protects the download
 * is the sha256 + codesign + designated-requirement + Team ID verification
 * below; this just stops relying on the redirect.
 */
export declare const HELPER_RELEASE_REPO = "phnx-labs/agi-cli";
/** Apple Developer ID Team every helper must be signed by ("Developer ID
 *  Application: Muqit Nawaz"). Defense in depth on top of `spctl` notarization. */
export declare const EXPECTED_TEAM_ID = "2HTP252L87";
/** One helper's identity + verification policy — everything that differs between
 *  the computer helper and the menu-bar helper. */
export interface HelperSpec {
    /**
     * Which helper this is — the key into the independent release train
     * (`helper-versions.ts`). This is what makes the download URL a function of
     * the HELPER's version rather than the CLI's.
     */
    helper: HelperName;
    /** The zipped `.app` release asset name, e.g. `ComputerHelper.app.zip`. */
    assetName: string;
    /** The bundle directory name once extracted, e.g. `ComputerHelper.app`. */
    appName: string;
    /** Cache dir components under `getCacheDir()`, e.g. `['computer', 'mac-helper']`. */
    cacheSubdir: string[];
    /** Developer ID Team the bundle must be signed by. */
    expectedTeamId: string;
    /**
     * When set, the bundle's designated requirement MUST pin this
     * CFBundleIdentifier in addition to `expectedTeamId`. Used by the menu-bar
     * helper: macOS keys the Accessibility (TCC) grant to this requirement, so a
     * substituted bundle whose DR does not pin (id, team) would silently revoke
     * the user's grant on the next paste. Left undefined for the computer helper,
     * which has no such upgrade-stable grant to protect (matching its behavior
     * before this shared primitive existed).
     */
    expectedBundleId?: string;
    /** Local-build command named in the "asset missing" error, for a repo checkout. */
    localBuildHint: string;
}
/** Cache dir for a downloaded helper, one subdir per release tag. */
export declare function helperCacheDir(spec: HelperSpec, version: string): string;
/**
 * Release-asset URLs for one helper build, at that HELPER's own tag.
 *
 * The tag is `<helper>/v<version>` (e.g. `menubar/v1.0.0`), never the CLI's
 * `v<cliVersion>`. Keying these to the CLI tag is what forced every CLI release
 * to re-stage every helper asset, and simultaneously made a helper fix
 * unreachable without a CLI release — see `helper-versions.ts` for the full why.
 *
 * `version` is a HELPER version. Passing a CLI version here yields a tag that
 * does not exist; callers default it from {@link helperFloor}.
 */
export declare function helperAssetUrls(spec: HelperSpec, version: string): {
    zip: string;
    sha256: string;
};
/** Extract `TeamIdentifier=XXXX` from `codesign -dv --verbose=4` output (which is
 *  emitted on stderr). Returns null when absent (ad-hoc / unsigned). */
export declare function parseTeamId(codesignInfo: string): string | null;
/** Read the bundle's designated requirement string (`codesign -d --requirements -`).
 *  codesign writes it to stdout, but capture both streams so a diagnostic on
 *  stderr can never make the pin-check read empty and falsely pass. */
export declare function readDesignatedRequirement(appPath: string): string;
/**
 * Pure predicate (no I/O) behind the DR pin: does the requirement string pin
 * BOTH the expected CFBundleIdentifier and the Developer ID Team? Returns null
 * when it does, else an actionable error message naming the missing pin. Kept
 * pure so the truth table is unit-testable without a signed bundle or codesign.
 * Mirrors the release-time gate in `scripts/verify-menubar-helper.sh` (identifier
 * + team substring check against the same requirement string).
 */
export declare function checkDesignatedRequirement(req: string, bundleId: string, teamId: string): string | null;
/**
 * Verify the bundle's designated requirement pins the expected CFBundleIdentifier
 * AND Developer ID Team. macOS re-validates each new version against this stored
 * requirement to keep an Accessibility grant alive across upgrades; a downloaded
 * bundle whose DR drops either pin would silently revoke that grant on the next
 * paste, so refuse it.
 */
export declare function verifyDesignatedRequirement(appPath: string, bundleId: string, teamId: string): void;
/**
 * Verify a helper `.app` bundle is intact, signed by the expected Developer ID
 * Team, (for the menu-bar helper) pinned by its designated requirement, and
 * notarized (Gatekeeper-accepted). Throws with an actionable message on any
 * failure — a downloaded bundle is never trusted without this.
 */
export declare function verifyHelperApp(appPath: string, spec: HelperSpec): void;
/**
 * Download a helper release asset for `version`, verify sha256, extract the
 * `.app`, and verify its signature (+ DR pin when the spec requires one).
 * Returns the path to the extracted bundle. A missing asset is a hard error
 * naming the exact tag — never a silent fallback to another release.
 */
export declare function downloadHelperApp(spec: HelperSpec, version: string): Promise<string>;
