/**
 * Pre-mutation human authentication for `hikoutei setup`.
 *
 * The setup flow creates the spreadsheet as the logged-in human account
 * (service accounts cannot own Workspace assets), so before any cloud or
 * file mutation it retrieves the active user's OAuth access token with
 * `gcloud auth print-access-token` and validates it through the tokeninfo
 * endpoint. The token must include the Drive scope, otherwise setup fails
 * with `gcloud_drive_access_required` and the exact re-login command.
 *
 * The token exists only in memory for the duration of the run: it is never
 * written to the checkpoint, the .env file, or any log/error message.
 */
import { SETUP_ERROR_CODES } from "./errors.js";
import type { GcloudRunner } from "./gcloudRunner.js";
/** Scope required to create and manage the spreadsheet as the human owner. */
export declare const DRIVE_SCOPE = "https://www.googleapis.com/auth/drive";
/** Minimal Drive scope that still allows creating and sharing a spreadsheet. */
export declare const DRIVE_FILE_SCOPE = "https://www.googleapis.com/auth/drive.file";
/**
 * Strict printable Google account email format.
 *
 * The tokeninfo `email` becomes the spreadsheet owner identity: it is
 * persisted in the checkpoint and shown in the summary, so it must be a
 * strict printable email (no whitespace, control characters, or newlines —
 * a `\n` in the email could otherwise smuggle secret-like text into
 * messages or the checkpoint). The pattern allows the ordinary Google
 * account local/domain characters; it is a dedicated email check, never a
 * broad truthiness test.
 */
export declare const GOOGLE_ACCOUNT_EMAIL_PATTERN: RegExp;
/**
 * True when the value is a strict printable Google account email.
 *
 * The pattern alone would accept a trailing newline (JS `$` also matches
 * before a final line break), so the value must also round-trip `trim()`
 * and stay within a sane length. Whitespace, control characters, and
 * newlines anywhere in the value are refused.
 */
export declare function isValidGoogleAccountEmail(value: unknown): value is string;
/** OAuth tokeninfo endpoint used to validate the user access token. */
export declare const TOKENINFO_URL = "https://oauth2.googleapis.com/tokeninfo";
/** Exact command the user must run to re-login with Drive access. */
export declare const DRIVE_ACCESS_COMMAND: readonly ["auth", "login", "--enable-gdrive-access", "--force"];
/** Validated identity information for an OAuth access token. */
export interface TokenInfo {
    /** Email of the account the token belongs to (the future spreadsheet owner). */
    readonly email: string;
    /** Space-delimited list of granted OAuth scopes. */
    readonly scope: string;
}
/**
 * Validates an access token through the tokeninfo endpoint.
 *
 * Throws with a safe reason on HTTP or payload failure; the setup flow maps
 * any throw to `user_token_failed`. The token itself must never be included
 * in messages.
 */
export interface TokenValidator {
    validate(token: string): Promise<TokenInfo>;
}
/** Outcome of the pre-mutation human auth check. */
export type HumanAuthResult = {
    readonly status: "ok";
    readonly accessToken: string;
    readonly ownerEmail: string;
} | {
    readonly status: "error";
    readonly code: typeof SETUP_ERROR_CODES.GCLOUD_DRIVE_ACCESS_REQUIRED | typeof SETUP_ERROR_CODES.USER_TOKEN_FAILED;
    readonly message: string;
};
/**
 * Retrieves the active user token and verifies it grants Drive access.
 *
 * Runs `gcloud auth print-access-token`, validates the token through the
 * injected validator, and requires the Drive or Drive-file scope. Missing
 * scope fails with the exact `gcloud auth login --enable-gdrive-access
 * --force` command; retrieval or validation failures fail with
 * `user_token_failed`. The returned token is memory-only by contract.
 */
export declare function checkHumanDriveAccess(runner: GcloudRunner, validateToken: TokenValidator): Promise<HumanAuthResult>;
/** True when the space-delimited scope list includes Drive or Drive-file. */
export declare function hasDriveScope(scope: string): boolean;
/**
 * Production token validator backed by the tokeninfo endpoint.
 *
 * POSTs the access token to `https://oauth2.googleapis.com/tokeninfo` and
 * promotes the validated email/scope. `fetchImpl` is injectable for tests;
 * it defaults to the global fetch (Node >= 18).
 */
export declare function createTokeninfoValidator(fetchImpl?: typeof fetch): TokenValidator;
/**
 * Validates the raw tokeninfo payload and promotes it into `TokenInfo`.
 *
 * The response is untrusted remote data: `email` must be a strict
 * printable Google account email and `scope` a non-empty string. Throws on
 * malformed payloads; the token is never part of the error text and the
 * raw email is never echoed.
 */
export declare function extractTokenInfo(payload: unknown): TokenInfo;
//# sourceMappingURL=humanAuth.d.ts.map