@agentproto/browser-profiles 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,1272 @@
+import { ToolError } from '@agentproto/tool';
+import { z } from 'zod';
+import { BrowserDriver, BrowserCookie } from '@agentproto/driver-browser';
+export { BrowserProfileRefusedError } from '@agentproto/driver-browser';
+
+declare const SESSION_SOURCE_UNKNOWN_CODE: "browser-profiles:unknown-source";
+declare const SESSION_SOURCE_DUPLICATE_CODE: "browser-profiles:duplicate-source";
+declare const SESSION_DESCRIPTOR_INVALID_CODE: "browser-profiles:invalid-descriptor";
+/** Thrown when a descriptor names a session source kind nobody registered. */
+declare class SessionSourceUnknownError extends ToolError {
+    readonly kind: string;
+    readonly registered: readonly string[];
+    constructor(kind: string, registered: readonly string[]);
+}
+/** Thrown when a session source kind is registered twice. */
+declare class SessionSourceDuplicateError extends ToolError {
+    readonly kind: string;
+    constructor(kind: string);
+}
+/** Thrown when a JSON document is not a readable session descriptor. */
+declare class SessionDescriptorInvalidError extends ToolError {
+    readonly issues: readonly string[];
+    constructor(issues: readonly string[]);
+}
+declare function isSessionSourceUnknownError(value: unknown): value is SessionSourceUnknownError;
+declare const SESSION_SOURCE_RESERVED_CODE: "browser-profiles:reserved-source";
+declare const ACCOUNT_SWITCHER_MISSING_CODE: "browser-profiles:account-switcher-missing";
+declare const CHROME_IDENTITY_CODE: "browser-profiles:chrome-identity";
+declare const SESSION_RESOLVE_CODE: "browser-profiles:resolve";
+/** Thrown when a host tries to register a session source under a built-in strategy kind. */
+declare class SessionSourceReservedError extends ToolError {
+    readonly kind: string;
+    constructor(kind: string);
+}
+/** Thrown when a descriptor pins a sub-account but no `accountSwitcher` hook was provided. */
+declare class AccountSwitcherMissingError extends ToolError {
+    constructor(platform: string);
+}
+/** A Chrome profile could not be confirmed as the pinned, logged-in identity. */
+declare class ChromeIdentityError extends ToolError {
+    constructor(message: string);
+}
+/** A session descriptor could not be turned into a live session. */
+declare class SessionResolveError extends ToolError {
+    constructor(message: string, cause?: unknown);
+}
+
+/**
+ * A value a read might not be able to produce: either a `known` result or an
+ * `unknown` with a human reason. A cookie read that threw (sqlite3 missing, the
+ * DB copy failed, Chrome holding the Cookies lock) is `{ unknown }`, so a caller
+ * can never mistake a failed read for a confident empty or zero result.
+ */
+type Known<T> = {
+    known: T;
+} | {
+    unknown: string;
+};
+declare function isKnown<T>(k: Known<T>): k is {
+    known: T;
+};
+/** Collapse a {@link Known} to a plain value with an explicit fallback (a deliberate, greppable decision). */
+declare function knownOr<T>(k: Known<T>, fallback: T): T;
+
+/** A cookie to inject into a browser session (camofox and Playwright shape). `value` is a secret: never log it. */
+interface SessionCookie {
+    name: string;
+    value: string;
+    domain: string;
+    path?: string;
+    httpOnly?: boolean;
+    secure?: boolean;
+    sameSite?: string;
+    expires?: number;
+}
+/** The loose shape a cookie file or a decrypted jar yields before normalising. */
+interface RawCookie {
+    name: string;
+    value: string;
+    domain: string;
+    path?: string;
+    httpOnly?: boolean;
+    secure?: boolean;
+    sameSite?: string;
+    expires?: number;
+    expirationDate?: number;
+    session?: boolean;
+}
+declare function domainMatches(domain: string | undefined, domains: readonly string[]): boolean;
+declare function toSessionCookie(c: RawCookie): SessionCookie;
+/** Drop duplicates by (name, domain, path); aliased domains otherwise yield the same cookie twice. */
+declare function dedupeCookies(cookies: readonly SessionCookie[]): SessionCookie[];
+
+/**
+ * Per-site "am I signed in" detectors, injected. The package ships none: which
+ * cookie name proves a live login on a given site is site knowledge, so the host
+ * registers it. A detector sees cookie NAMES and expiry only, never values.
+ */
+/** Cookie metadata a detector may look at. No value, by design. */
+interface AuthCookieMeta {
+    name: string;
+    /** Host key without the leading dot, lowercased. */
+    host: string;
+    /** Unix seconds; `undefined` means a session cookie (valid while the browser is open). */
+    expiresUnix: number | undefined;
+}
+interface SiteAuthSignal {
+    /** Registrable domain the detector is about, e.g. `"example.com"`. */
+    readonly domain: string;
+    /** Other hosts whose cookies count as this domain (e.g. a renamed site). */
+    readonly aliases?: readonly string[];
+    /** Cookie NAME(s) that prove a live login. Any one present and unexpired counts. Ignored when `detect` is set. */
+    readonly cookieNames?: readonly string[];
+    /** Custom detector over this domain's cookie metadata; overrides the `cookieNames` rule. */
+    readonly detect?: (cookies: readonly AuthCookieMeta[], nowMs: number) => boolean;
+}
+interface AuthSignalRegistry {
+    register(signal: SiteAuthSignal): void;
+    /** Domains with a registered detector: the KNOWN side of the known/unknown split. */
+    knownDomains(): readonly string[];
+    isKnownDomain(domain: string): boolean;
+    /** Map an alias host onto its registered domain; anything else passes through lowercased. */
+    canonicalDomain(domain: string): string;
+    /** Other hosts that count as the same site as `domain` (its aliases, or its canonical domain plus siblings). */
+    equivalentDomains(domain: string): readonly string[];
+    /** Whether `host` belongs to `domain` (or one of its aliases). */
+    hostBelongsTo(host: string, domain: string): boolean;
+    /** Run the detector for `domain` over the profile's cookie metadata. `false` when no detector is registered. */
+    isAuthed(domain: string, cookies: readonly AuthCookieMeta[], nowMs: number): boolean;
+}
+declare function createAuthSignalRegistry(initial?: readonly SiteAuthSignal[]): AuthSignalRegistry;
+/** Process-wide default registry (empty). Hosts register their detectors here or pass their own. */
+declare const defaultAuthSignalRegistry: AuthSignalRegistry;
+
+/**
+ * Chrome `Local State` parsing: the one implementation, shared by the Chrome
+ * profile scanner here and by `@agentproto/plugin-local-browser`.
+ *
+ * macOS: ~/Library/Application Support/Google/Chrome/Local State
+ * Linux: ~/.config/google-chrome/Local State
+ * Win:   %LOCALAPPDATA%\Google\Chrome\User Data\Local State
+ */
+/** Resolves the platform-specific Chrome user-data-dir root. */
+declare function chromeUserDataDir(home?: string): string;
+declare function chromeLocalStatePath(home?: string): string;
+/** One `profile.info_cache` entry, reduced to the fields callers use. */
+interface LocalStateProfile {
+    /** Directory name under the user-data-dir (`Default`, `Profile 1`). */
+    directory: string;
+    /** Friendly profile name. */
+    name: string | undefined;
+    /** Signed-in Google account email (`user_name`). */
+    userName: string | undefined;
+    /** Google display name. */
+    gaiaName: string | undefined;
+    /** Raw Chrome activity stamp (`active_time`, else `last_active_time`), unconverted. */
+    activeTime: unknown;
+}
+interface ParsedLocalState {
+    profiles: LocalStateProfile[];
+    /** `profile.last_used`, or `null` when absent. */
+    lastUsed: string | null;
+}
+/** Parse Local State JSON text. Throws on malformed JSON. */
+declare function parseLocalState(text: string): ParsedLocalState;
+/** Lenient read of `<chromeRoot>/Local State`: a missing or unreadable file is an empty result. */
+declare function readLocalState(chromeRoot: string): ParsedLocalState;
+/**
+ * Chrome stores timestamps as microseconds since the Windows epoch (1601-01-01
+ * UTC). Convert to ISO-8601, or return "" when the field is missing or out of
+ * plausible range (so callers can't surface 1601 in a UI).
+ */
+declare function chromeTimeToIso(raw: unknown): string;
+
+/**
+ * The session descriptor model: a saveable, named description of a browser
+ * session and EXACTLY which cookies to inject (by domain, never the whole jar).
+ *
+ * Wire compatibility is the contract: descriptors already on disk (written by
+ * the earlier studio code) load unchanged. The schemas below validate shape but
+ * never rewrite it; {@link parseSessionDescriptor} returns the parsed JSON as
+ * written, so a load followed by a save is byte-stable.
+ */
+
+/** Built-in strategy kinds. Any other kind is a registered {@link SessionSource}. */
+declare const BUILTIN_STRATEGY_KINDS: readonly ["chrome-cookie", "stored-credential", "authed-storageState"];
+type BuiltinStrategyKind = (typeof BUILTIN_STRATEGY_KINDS)[number];
+/** Built-in `inject.from` tags. Any other tag is a registered {@link SessionSource}. */
+declare const BUILTIN_INJECT_FROM: readonly ["chrome-profile", "file", "camofox-native"];
+type BuiltinInjectFrom = (typeof BUILTIN_INJECT_FROM)[number];
+interface ChromeProfileInject {
+    from: "chrome-profile";
+    domains: string[];
+    /** Required: with several profiles on one site, "first match" would pick at random. */
+    profile: string;
+    /** Sub-account selector for multi-account profiles; needs an `accountSwitcher` hook. */
+    account?: {
+        platform: string;
+        userId: string;
+    };
+}
+interface FileInject {
+    from: "file";
+    domains: string[];
+    path: string;
+}
+/** The session owns its login (camofox storageState under the descriptor id); nothing is injected. */
+interface CamofoxNativeInject {
+    from: "camofox-native";
+}
+/**
+ * Cookies materialised at resolve time by a registered {@link SessionSource}.
+ * The descriptor carries only the `sessionRef` and `domains`, never cookies.
+ * `from` is the source kind (the studio's private store registers `"guilde"`).
+ */
+interface SourceInject {
+    from: string;
+    domains: string[];
+    sessionRef: string;
+}
+type SessionInject = ChromeProfileInject | FileInject | CamofoxNativeInject | SourceInject;
+type SessionInjectFrom = SessionInject["from"];
+interface ChromeCookieStrategy {
+    kind: "chrome-cookie";
+    domains: string[];
+    /** Chrome profile dir ("Default", "Profile 1"). */
+    profile: string;
+    profileName?: string;
+    profileEmail?: string;
+    account?: {
+        platform: string;
+        userId: string;
+    };
+}
+/** A re-login CAPABILITY: only the credential reference, never the secret. Not a resolve source. */
+interface StoredCredentialStrategy {
+    kind: "stored-credential";
+    platform: string;
+    account: string;
+}
+interface OwnedStorageStateStrategy {
+    kind: "authed-storageState";
+    storageStatePath: string;
+    capturedAt?: string;
+}
+/** A registered-source strategy: `kind` is the source kind. */
+interface SourceStrategy {
+    kind: string;
+    domains: string[];
+    sessionRef: string;
+}
+type Strategy = ChromeCookieStrategy | StoredCredentialStrategy | OwnedStorageStateStrategy | SourceStrategy;
+declare function isBuiltinStrategyKind(kind: string): kind is BuiltinStrategyKind;
+declare const isChromeCookieStrategy: (s: Strategy) => s is ChromeCookieStrategy;
+declare const isStoredCredentialStrategy: (s: Strategy) => s is StoredCredentialStrategy;
+declare const isOwnedStorageStateStrategy: (s: Strategy) => s is OwnedStorageStateStrategy;
+declare const isSourceStrategy: (s: Strategy) => s is SourceStrategy;
+declare const isChromeProfileInject: (i: SessionInject) => i is ChromeProfileInject;
+declare const isFileInject: (i: SessionInject) => i is FileInject;
+declare const isCamofoxNativeInject: (i: SessionInject) => i is CamofoxNativeInject;
+declare const isSourceInject: (i: SessionInject) => i is SourceInject;
+/** The account a session is pinned to: for naming and drift detection. */
+interface SessionIdentity {
+    profile?: string;
+    account?: string;
+    platform?: string;
+    profileName?: string;
+    profileEmail?: string;
+}
+type AuthStatus = "authenticated" | "auth-wall" | "stale" | "unknown";
+interface SessionDescriptor {
+    /** Stable name the agent resolves by. */
+    id: string;
+    /** `camofox`: a stealth browser we inject curated cookies into. `chrome`: the user's own browser over a driver, no injection. */
+    backend: "camofox" | "chrome";
+    identity?: SessionIdentity;
+    /** Legacy single-source seam; {@link strategies} is the multi-source model. */
+    inject?: SessionInject;
+    strategies?: Strategy[];
+    base?: string;
+    url?: string;
+    savedAt?: string;
+    lastVerifiedAt?: string;
+    lastAuthStatus?: AuthStatus;
+    lastCookieRefreshAt?: string;
+}
+declare const sessionInjectSchema: z.ZodUnion<readonly [z.ZodObject<{
+    from: z.ZodLiteral<"chrome-profile">;
+    domains: z.ZodArray<z.ZodString>;
+    profile: z.ZodString;
+    account: z.ZodOptional<z.ZodObject<{
+        platform: z.ZodString;
+        userId: z.ZodString;
+    }, z.core.$loose>>;
+}, z.core.$loose>, z.ZodObject<{
+    from: z.ZodLiteral<"file">;
+    domains: z.ZodArray<z.ZodString>;
+    path: z.ZodString;
+}, z.core.$loose>, z.ZodObject<{
+    from: z.ZodLiteral<"camofox-native">;
+}, z.core.$loose>, z.ZodObject<{
+    from: z.ZodString;
+    domains: z.ZodArray<z.ZodString>;
+    sessionRef: z.ZodString;
+}, z.core.$loose>]>;
+declare const strategySchema: z.ZodUnion<readonly [z.ZodObject<{
+    kind: z.ZodLiteral<"chrome-cookie">;
+    domains: z.ZodArray<z.ZodString>;
+    profile: z.ZodString;
+    profileName: z.ZodOptional<z.ZodString>;
+    profileEmail: z.ZodOptional<z.ZodString>;
+    account: z.ZodOptional<z.ZodObject<{
+        platform: z.ZodString;
+        userId: z.ZodString;
+    }, z.core.$loose>>;
+}, z.core.$loose>, z.ZodObject<{
+    kind: z.ZodLiteral<"stored-credential">;
+    platform: z.ZodString;
+    account: z.ZodString;
+}, z.core.$loose>, z.ZodObject<{
+    kind: z.ZodLiteral<"authed-storageState">;
+    storageStatePath: z.ZodString;
+    capturedAt: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>, z.ZodObject<{
+    kind: z.ZodString;
+    domains: z.ZodArray<z.ZodString>;
+    sessionRef: z.ZodString;
+}, z.core.$loose>]>;
+declare const sessionIdentitySchema: z.ZodObject<{
+    profile: z.ZodOptional<z.ZodString>;
+    account: z.ZodOptional<z.ZodString>;
+    platform: z.ZodOptional<z.ZodString>;
+    profileName: z.ZodOptional<z.ZodString>;
+    profileEmail: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
+declare const authStatusSchema: z.ZodEnum<{
+    authenticated: "authenticated";
+    "auth-wall": "auth-wall";
+    stale: "stale";
+    unknown: "unknown";
+}>;
+declare const sessionDescriptorSchema: z.ZodObject<{
+    id: z.ZodString;
+    backend: z.ZodEnum<{
+        camofox: "camofox";
+        chrome: "chrome";
+    }>;
+    identity: z.ZodOptional<z.ZodObject<{
+        profile: z.ZodOptional<z.ZodString>;
+        account: z.ZodOptional<z.ZodString>;
+        platform: z.ZodOptional<z.ZodString>;
+        profileName: z.ZodOptional<z.ZodString>;
+        profileEmail: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>>;
+    inject: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+        from: z.ZodLiteral<"chrome-profile">;
+        domains: z.ZodArray<z.ZodString>;
+        profile: z.ZodString;
+        account: z.ZodOptional<z.ZodObject<{
+            platform: z.ZodString;
+            userId: z.ZodString;
+        }, z.core.$loose>>;
+    }, z.core.$loose>, z.ZodObject<{
+        from: z.ZodLiteral<"file">;
+        domains: z.ZodArray<z.ZodString>;
+        path: z.ZodString;
+    }, z.core.$loose>, z.ZodObject<{
+        from: z.ZodLiteral<"camofox-native">;
+    }, z.core.$loose>, z.ZodObject<{
+        from: z.ZodString;
+        domains: z.ZodArray<z.ZodString>;
+        sessionRef: z.ZodString;
+    }, z.core.$loose>]>>;
+    strategies: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+        kind: z.ZodLiteral<"chrome-cookie">;
+        domains: z.ZodArray<z.ZodString>;
+        profile: z.ZodString;
+        profileName: z.ZodOptional<z.ZodString>;
+        profileEmail: z.ZodOptional<z.ZodString>;
+        account: z.ZodOptional<z.ZodObject<{
+            platform: z.ZodString;
+            userId: z.ZodString;
+        }, z.core.$loose>>;
+    }, z.core.$loose>, z.ZodObject<{
+        kind: z.ZodLiteral<"stored-credential">;
+        platform: z.ZodString;
+        account: z.ZodString;
+    }, z.core.$loose>, z.ZodObject<{
+        kind: z.ZodLiteral<"authed-storageState">;
+        storageStatePath: z.ZodString;
+        capturedAt: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>, z.ZodObject<{
+        kind: z.ZodString;
+        domains: z.ZodArray<z.ZodString>;
+        sessionRef: z.ZodString;
+    }, z.core.$loose>]>>>;
+    base: z.ZodOptional<z.ZodString>;
+    url: z.ZodOptional<z.ZodString>;
+    savedAt: z.ZodOptional<z.ZodString>;
+    lastVerifiedAt: z.ZodOptional<z.ZodString>;
+    lastAuthStatus: z.ZodOptional<z.ZodEnum<{
+        authenticated: "authenticated";
+        "auth-wall": "auth-wall";
+        stale: "stale";
+        unknown: "unknown";
+    }>>;
+    lastCookieRefreshAt: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
+/**
+ * Validate a parsed JSON document as a {@link SessionDescriptor} and return it AS
+ * WRITTEN (not the zod output, which reorders keys), so a load then a save is
+ * byte-stable. Throws {@link SessionDescriptorInvalidError} on a bad shape.
+ */
+declare function parseSessionDescriptor(json: unknown): SessionDescriptor;
+/** Persisted storageState of an owned camofox session: `<CAMOFOX_PROFILES_DIR or ~/.agentproto/camofox-profiles>/<id>.json`. */
+declare function ownedStorageStatePath(id: string): string;
+/** inject.from to strategy kind: file collapses onto chrome-cookie; a source tag is its own kind. */
+declare function injectKindOf(from: SessionInjectFrom): Strategy["kind"];
+/** strategy kind to inject.from; `stored-credential` has no transport. */
+declare function injectFromOf(kind: Strategy["kind"]): SessionInjectFrom | undefined;
+declare function chromeCookieStrategyOf(inject: ChromeProfileInject, identity?: SessionIdentity): ChromeCookieStrategy;
+interface NormalizeOptions {
+    /** (platform, account) credential index: a match synthesizes a `stored-credential` strategy. Never secrets. */
+    credentials?: ReadonlyArray<{
+        platform: string;
+        account: string;
+    }>;
+}
+/**
+ * The single migration seam: when `strategies` is absent, derive them from the
+ * legacy `inject`/`identity` (plus a credential match); when present, return the
+ * descriptor unchanged. Never drops or rewrites legacy fields.
+ */
+declare function normalizeDescriptor(raw: SessionDescriptor, opts?: NormalizeOptions): SessionDescriptor;
+/**
+ * Resolution precedence: `authed-storageState` (unless it last hit an auth wall),
+ * then `chrome-cookie`, then any registered-source strategy. `stored-credential`
+ * is never selected: it is a recovery capability, not a resolve source.
+ */
+declare function selectResolutionStrategy(desc: SessionDescriptor): Strategy | undefined;
+/** The effective `SessionInject` for resolution (see the studio's `resolveInjectFromStrategies`). */
+declare function resolveInjectFromStrategies(desc: SessionDescriptor): SessionInject | undefined;
+/** Default staleness TTL for owned cookies (7 days). */
+declare const COOKIE_STALE_TTL_MS: number;
+/**
+ * Pure staleness verdict computed at read time with no probe. Chrome-cookie and
+ * file sources are always fresh (re-read each resolve); owned and registered
+ * sources go by `lastCookieRefreshAt`.
+ */
+declare function cookieFreshness(desc: SessionDescriptor, now: number, ttlMs?: number): "fresh" | "stale" | "unknown";
+declare function priorChromeStrategy(prev?: SessionDescriptor): ChromeCookieStrategy | undefined;
+interface BuildOwnedDescriptorInput {
+    id: string;
+    platform: string;
+    reuseBase: string;
+    account?: string;
+    url?: string;
+    /** ISO timestamp for `savedAt` and the storageState `capturedAt` (injected, not read from the clock). */
+    now: string;
+    /** Prior descriptor whose chrome provenance is preserved (augment, not replace). */
+    prev?: SessionDescriptor;
+}
+/** Build the `camofox-native` descriptor for an owned login, preserving any prior chrome provenance. */
+declare function buildOwnedSessionDescriptor(input: BuildOwnedDescriptorInput): SessionDescriptor;
+
+/** Saveable store of descriptors, injected so it can be local files or a remote adapter. */
+interface SessionStorePort {
+    save(desc: SessionDescriptor): Promise<void>;
+    load(id: string): Promise<SessionDescriptor | null>;
+    list(): Promise<SessionDescriptor[]>;
+    remove(id: string): Promise<void>;
+}
+interface FileSessionStoreOptions {
+    /** Live credential-index reader (a thunk so it reflects the current index). */
+    credentials?: () => ReadonlyArray<{
+        platform: string;
+        account: string;
+    }>;
+}
+/** Local-file adapter: one `<id>.json` per descriptor under `dir` (dir 0700, file 0600). */
+declare function fileSessionStore(dir: string, opts?: FileSessionStoreOptions): SessionStorePort;
+/**
+ * Resolve a session by name across several stores. `load` returns the first
+ * hit; `list` unions by id (earlier stores win). Writes go to `writeStore`, or
+ * throw when none is given.
+ */
+declare function compositeSessionStore(readStores: SessionStorePort[], writeStore?: SessionStorePort): SessionStorePort;
+
+/**
+ * The `SessionSource` registry: how a host supplies cookies that live somewhere
+ * this package knows nothing about (a managed central store, a vault, a device
+ * bridge). The descriptor carries only a `kind`, a `sessionRef` and `domains`;
+ * the registered source materialises the cookies at resolve time.
+ *
+ * Replaces the hard-wired `guilde` inject: the studio registers a `"guilde"`
+ * source, the open package never mentions it.
+ */
+
+interface SessionSourceRef {
+    sessionRef: string;
+    /** Only these domains' cookies may be returned, never the whole jar. */
+    domains: readonly string[];
+}
+interface SessionSource {
+    /** The `inject.from` / `strategy.kind` this source answers to. Not a built-in kind. */
+    readonly kind: string;
+    materialize(ref: SessionSourceRef): Promise<SessionCookie[]>;
+}
+interface SessionSourceRegistry {
+    /** Register a source. Throws on a duplicate kind or a built-in kind. */
+    register(source: SessionSource): void;
+    list(): readonly SessionSource[];
+    has(kind: string): boolean;
+    /** The source for `kind`, or a typed {@link SessionSourceUnknownError}. */
+    resolve(kind: string): SessionSource;
+    materialize(kind: string, ref: SessionSourceRef): Promise<SessionCookie[]>;
+}
+declare function createSessionSourceRegistry(initial?: readonly SessionSource[]): SessionSourceRegistry;
+/** Catalog row of a centrally managed session. Carries NO cookies. */
+interface SessionSourceMeta {
+    ref: string;
+    domains: string[];
+    identity?: SessionIdentity;
+    url?: string;
+}
+interface SessionSourceCatalog {
+    list(): Promise<SessionSourceMeta[]>;
+    get(ref: string): Promise<SessionSourceMeta | null>;
+}
+/**
+ * Read-only descriptor store over a catalog of managed sessions, resolving them
+ * into `from: <kind>` descriptors. `save` and `remove` throw: sessions are
+ * captured elsewhere, so the contract stays loud.
+ */
+declare function catalogSessionStore(kind: string, catalog: SessionSourceCatalog): SessionStorePort;
+
+/**
+ * Read the logged-in browser on THIS machine, on demand and in memory. Nothing
+ * is persisted: the browser is the source of truth. Cookie DB access is a
+ * read-only copy to a temp dir; only cookie NAMES and expiry are read for the
+ * auth signal, values are decrypted only by {@link decryptChromeCookies}, and
+ * never logged.
+ *
+ * Backend: macOS Chrome/Chromium (Keychain "Chrome Safe Storage", PBKDF2-SHA1,
+ * AES-128-CBC, `v10` prefix, a 32-byte SHA-256(domain) prefix stripped on newer
+ * Chrome). Pass `safeStoragePassword` and `chromeRoot` for anything else.
+ */
+
+interface LocalBrowserSessionOptions {
+    /** Root of the Chrome/Chromium user-data dir. Default: the macOS Chrome path. */
+    chromeRoot?: string;
+    /** Safe-Storage password (e.g. for Chromium's own Keychain service). Default reads the macOS Keychain. */
+    safeStoragePassword?: () => string;
+    /** Per-domain cookie aliases. Default: derived from the auth signal registry's aliases. */
+    domainAliases?: Record<string, string[]>;
+    /** Extra domains for the host-presence scan beyond the registry's known domains. */
+    extraDomains?: readonly string[];
+    /** Per-site "signed in" detectors. Default: {@link defaultAuthSignalRegistry}. */
+    authSignals?: AuthSignalRegistry;
+}
+/** Profiles live as sibling dirs (`Default`, `Profile 1`, ...) each with a `Cookies` DB. */
+declare function profileDirs(chromeRoot: string): string[];
+/** The Chrome user-data root the scanner reads. Reading it is fine; launching Chrome against it is refused by the kit (F11). */
+declare function chromeUserDataRoot(opts?: LocalBrowserSessionOptions): string;
+/** Read the Chrome Safe Storage key from the macOS Keychain. Touches the Keychain: call only on an explicit user action. */
+declare function readSafeStorageKey(): Buffer;
+/** Decrypt one hex-dumped Chrome `encrypted_value`. Exported for the synthetic-data tests. */
+declare function decryptChromeValue(hex: string, key: Buffer): string;
+/** Derive the AES key from a Safe-Storage password (Chrome's constants). */
+declare function safeStorageKey(password: string): Buffer;
+/** Total cookie count (no decryption). A failed read is `{ unknown }`, never 0. */
+declare function countCookies(profileDir: string): Known<number>;
+/** Cookie counts per requested domain (host and subdomains), no decryption. A failed read is `{ unknown }`, never zeros. */
+declare function countCookiesByDomain(profileDir: string, domains: readonly string[]): Known<Record<string, number>>;
+/** Distinct cookie hosts (no decryption) mapped onto the registry's known domains plus `extraDomains`. */
+declare function profileLoggedInDomains(profileDir: string, registry?: AuthSignalRegistry, extraDomains?: readonly string[]): Known<string[]>;
+/**
+ * Known domains the profile holds a valid, non-expired AUTH signal for. Reads
+ * cookie NAME and expiry only (no value decryption), then asks the registry's
+ * detector. A failed read is `{ unknown }`.
+ */
+declare function profileAuthedDomains(profileDir: string, registry?: AuthSignalRegistry, nowMs?: number): Known<string[]>;
+/** A logged-in identity behind a Chrome profile: the unit a person reasons about, not the dir name. */
+interface ChromeIdentity {
+    /** On-disk dir: the addressable key passed back as `label`/`profile`. */
+    profile: string;
+    name: string | null;
+    email: string | null;
+    gaiaName: string | null;
+    lastUsed: boolean;
+    /** Display only; a failed read collapses to 0 here (see `domainsAuthed` for the honest value). */
+    cookieCount: number;
+    /** Weak host-presence signal: any cookie on the domain counts. */
+    domainsLoggedIn: string[];
+    /** Strong signal: a valid, non-expired auth cookie, by name and expiry. `Known` so a failed read is never "authed nowhere". */
+    domainsAuthed: Known<string[]>;
+}
+/** Enumerate the machine's Chrome profiles as named identities. Pure read: Local State JSON plus a host-key scan. */
+declare function scanChromeIdentities(opts?: LocalBrowserSessionOptions): ChromeIdentity[];
+/** Decrypt cookies for `domains` from a single Chrome profile, in memory (the DB copy is removed). */
+declare function decryptChromeCookies(profileDir: string, domains: readonly string[], key: Buffer): SessionCookie[];
+interface LocalBrowserSession {
+    /** Decrypted cookies for `domain` (and its aliases) from `profile`, or the first profile that has one. `null` when none. */
+    getDecryptedForDomain(domain: string, profile?: string): Promise<{
+        cookies: SessionCookie[];
+        capturedAt: string;
+    } | null>;
+    /** One summary per Chrome profile (no decryption). */
+    listProfiles(): Array<{
+        profile: string;
+        cookieCount: Known<number>;
+    }>;
+}
+/** A local, no-persistence provider reading this machine's browser. */
+declare function createLocalBrowserSession(opts?: LocalBrowserSessionOptions): LocalBrowserSession;
+
+interface ChromeIdentityOptions {
+    /** Pre-scanned identities. Injectable so tests never scan a real profile. Scanned lazily when absent. */
+    scan?: ChromeIdentity[];
+    authSignals?: AuthSignalRegistry;
+    /** Options for the lazy scan (`chromeRoot` etc). */
+    scanOptions?: LocalBrowserSessionOptions;
+    /** Receives non-fatal warnings (never cookie values). Default: dropped. */
+    warn?: (message: string) => void;
+}
+/** Three-valued verdict for one domain. `unknown` must never be treated as `authed`. */
+type DomainAuthSignal = "authed" | "not-authed" | "unknown";
+/** {@link DomainAuthSignal} plus `not-checked`: the state where no live auth guard applies at all. */
+type SessionAuthState = DomainAuthSignal | "not-checked";
+interface SessionAuthDescription {
+    state: SessionAuthState;
+    message: string;
+}
+/** Classify `domain` for `found`: `unknown` when no detector is registered or the cookie read failed. */
+declare function domainAuthSignal(domain: string, found: ChromeIdentity, registry?: AuthSignalRegistry): DomainAuthSignal;
+/** Human label for a Chrome identity: friendly name, email, and the dir key. */
+declare function chromeIdentityLabel(s: ChromeIdentity): string;
+/**
+ * Which Chrome profile a chrome-profile session's cookies should actually be
+ * read from: a still-valid pin wins; otherwise a profile authed for the domain
+ * AND on the same Google account; otherwise the pin unchanged. Never heals to a
+ * different account.
+ */
+declare function resolveChromeProfile(inject: SessionInject, identity?: SessionIdentity, opts?: ChromeIdentityOptions): string | undefined;
+/**
+ * Pin guard for chrome-sourced sessions: the profile exists and carries a valid
+ * auth signal for the declared domain. Throws {@link ChromeIdentityError} on a
+ * hard mismatch. A domain with no registered detector is `unknown`: it falls
+ * back to host presence and is never reported as authed.
+ */
+declare function verifyChromeIdentity(inject: SessionInject, identity?: SessionIdentity, opts?: ChromeIdentityOptions): void;
+/**
+ * What {@link verifyChromeIdentity} established, without throwing, so a renderer
+ * can tell "confirmed" from every shade of "not confirmed". Only `authed` should
+ * earn a checkmark. A heuristic (cookie name and expiry, no network).
+ */
+declare function describeSessionAuth(inject: SessionInject, identity?: SessionIdentity, opts?: ChromeIdentityOptions): SessionAuthDescription;
+
+/**
+ * Gate a Chrome launch against `userDataDir` before anything spawns. Delegates
+ * to the kit's F11 refusal (`assertSpawnArgsSafe`); nothing is re-implemented
+ * here. Throws {@link BrowserProfileRefusedError} (`browser:profile-refused`)
+ * when `userDataDir` is, or sits inside, a default Chrome user-data-dir.
+ *
+ * The scanner in this package only READS cookies from a profile. A host that
+ * launches Chrome per profile must pass its `--user-data-dir` through this first.
+ */
+declare function assertChromeLaunchDirSafe(userDataDir: string, providerId: string): void;
+
+/**
+ * A reused camofox tab per `userId`. A camofox `userId` owns one browser context
+ * (cookies); `POST /tabs` always creates a NEW tab, so reuse is the client's job:
+ * the tab id is remembered in a small state file and re-navigated on the next run.
+ *
+ * Public half only: cookie injection, tab reuse, navigation, evaluation, basic
+ * input, screenshots and server-side network capture. Human-mode pacing,
+ * anti-bot challenge handling and passive in-page capture stay private.
+ */
+
+/** Where the reused tab ids are remembered. Computed on call, never at import. */
+declare function camofoxStatePath(): string;
+/** The camofox instance a session resolves against when no base is pinned: `CAMOFOX_URL`, else `localhost:$CAMOFOX_PORT` (9377). */
+declare function defaultCamofoxBase(): string;
+interface OpenSessionOptions {
+    /** The camofox `userId` that owns the browser context. */
+    userId: string;
+    base?: string;
+    /** Curated cookies to inject: the declared domains only, never the whole jar. */
+    cookies?: readonly SessionCookie[];
+    /** Initial URL to land the tab on. Omitted: no landing navigation. */
+    url?: string;
+    /** Inject cookies before use (default true). */
+    injectCookies?: boolean;
+    /** Absolute path to a Playwright storageState JSON loaded when creating a new tab. */
+    storageState?: string;
+    /** Exempt the tab from camofox's idle reaper. */
+    keepAlive?: boolean;
+    /** If a read returns 401, POST this URL in-page (a token-refresh endpoint) and retry once. */
+    refreshUrl?: string;
+    /** Where tab ids are remembered. Default: {@link camofoxStatePath}. */
+    stateFile?: string;
+    /** Injectable transport, for tests. Default: global `fetch`. */
+    fetch?: typeof fetch;
+    /** Injectable settle delay after navigation (ms). Default 2500. */
+    settleMs?: number;
+}
+interface ApiRawResult {
+    status: number;
+    body: unknown;
+}
+interface CamofoxSession {
+    tabId: string;
+    userId: string;
+    /** In-page authed JSON GET; returns the parsed body, throws on non-2xx. */
+    api(pathAndQuery: string): Promise<unknown>;
+    /** In-page GET returning `{ status, body }` without throwing. */
+    apiRaw(pathAndQuery: string): Promise<ApiRawResult>;
+    evaluate<T = unknown>(expression: string): Promise<T>;
+    screenshot(opts?: {
+        selector?: string;
+        format?: "png" | "jpeg";
+        quality?: number;
+    }): Promise<{
+        imageBase64: string;
+        mimeType: string;
+    }>;
+    goto(url: string, waitUntil?: string): Promise<void>;
+    click(selector: string): Promise<void>;
+    type(selector: string, text: string): Promise<void>;
+    press(key: string): Promise<void>;
+    /** Arm server-side network capture (Playwright request events). */
+    startNetCapture(urlPattern?: string, max?: number): Promise<void>;
+    readNetCapture(): Promise<Array<{
+        method: string;
+        url: string;
+        resourceType: string;
+        postData: string | null;
+        headers: Record<string, string>;
+    }>>;
+    /** Close and forget the tab. */
+    close(): Promise<void>;
+}
+declare function openSession(opts: OpenSessionOptions): Promise<CamofoxSession>;
+
+/**
+ * Optional hook that rewrites a gathered jar so `userId` is the active
+ * sub-account on `platform` (for profiles logged into several accounts of one
+ * site). Policy about HOW to switch lives with the host; the default is none.
+ */
+type AccountSwitcher = (platform: string, jar: SessionCookie[], userId: string) => SessionCookie[];
+interface ResolveSessionDeps {
+    /** Single driver, used when a chrome session names no profile. */
+    driver?: BrowserDriver;
+    /** Per-profile driver factory (the multi-account seam). Preferred over `driver`. */
+    driverFor?: (profile: string) => BrowserDriver | Promise<BrowserDriver>;
+    /** Where registered-source cookies come from. Default: an empty registry. */
+    sources?: SessionSourceRegistry;
+    /** Optional sub-account switcher. Never called unless a chrome-profile inject pins an `account`. */
+    accountSwitcher?: AccountSwitcher;
+    /** Per-site "signed in" detectors. Default: {@link defaultAuthSignalRegistry}. */
+    authSignals?: AuthSignalRegistry;
+    /** Chrome scanning options (`chromeRoot`, `safeStoragePassword`, ...). */
+    local?: LocalBrowserSessionOptions;
+    /** Camofox opener. Default: {@link openSession}. Injectable so tests need no network. */
+    openCamofox?: (opts: OpenSessionOptions) => Promise<CamofoxSession>;
+    /** Non-fatal warnings (never cookie values). Default: dropped. */
+    warn?: (message: string) => void;
+}
+/** What a descriptor resolves to: a chrome driver, or a live camofox session. */
+type ResolvedSession = {
+    backend: "chrome";
+    driver: BrowserDriver;
+} | {
+    backend: "camofox";
+    session: CamofoxSession;
+};
+/**
+ * Cookies for a `chrome-cookie` strategy. A file-sourced descriptor keeps its
+ * cookie path in the legacy `file` inject, so `desc` is consulted to recover it.
+ */
+declare function gatherCookiesForStrategy(strategy: Strategy, desc: SessionDescriptor, deps?: ResolveSessionDeps): Promise<SessionCookie[]>;
+/** Gather cookies for a legacy `SessionInject` (chrome-profile or file only). */
+declare function gatherCookies(inject: SessionInject, deps?: ResolveSessionDeps): Promise<SessionCookie[]>;
+/** Turn a saved descriptor into a live session. */
+declare function resolveSession(desc: SessionDescriptor, deps?: ResolveSessionDeps): Promise<ResolvedSession>;
+
+declare const GRANT_DOMAIN_INVALID_CODE: "browser-profiles:grant-domain-invalid";
+declare const CONSENT_REQUIRED_CODE: "browser:consent_required";
+declare const CONSENT_FLAGS_REQUIRED_CODE: "browser-profiles:consent-flags-required";
+declare const CONSENT_DECLINED_CODE: "browser-profiles:consent-declined";
+declare const SINK_ACK_REQUIRED_CODE: "browser-profiles:sink-ack-required";
+declare const AGENT_GRANT_REFUSED_CODE: "browser-profiles:agent-grant-refused";
+declare const FULL_PROFILE_REFUSED_CODE: "browser-profiles:full-profile-refused";
+declare const LEDGER_RECORD_INVALID_CODE: "browser-profiles:ledger-record-invalid";
+declare const GRANT_STORE_INVALID_CODE: "browser-profiles:grant-store-invalid";
+type GrantDomainReason = "empty" | "wildcard" | "leading-dot" | "bare-tld" | "public-suffix" | "invalid";
+/** A grant's domain list broke AIP-63 C2 (wildcard, empty, bare TLD, leading dot, public suffix). */
+declare class GrantDomainError extends ToolError {
+    readonly reason: GrantDomainReason;
+    readonly domain: string | undefined;
+    constructor(reason: GrantDomainReason, domain?: string);
+}
+/** The caller has no usable grant for this. Also what a device sees for another device's grant (C12). */
+declare class ConsentRequiredError extends ToolError {
+    constructor(message?: string);
+}
+/** A non-interactive request lacked `--domains` plus `--yes`, or the named full-profile request (C4). */
+declare class NonInteractiveConsentError extends ToolError {
+    readonly missing: readonly string[];
+    constructor(missing: readonly string[]);
+}
+/** The human declined at the prompt. */
+declare class ConsentDeclinedError extends ToolError {
+    constructor(what: string);
+}
+/** Material would go to a remote sink nobody acknowledged (C6). */
+declare class SinkAckRequiredError extends ToolError {
+    readonly sinkId: string;
+    constructor(sinkId: string);
+}
+/** An agent tried something only a human consent path may do (C7). */
+declare class AgentGrantRefusedError extends ToolError {
+    readonly attempt: string;
+    constructor(attempt: string);
+}
+/** A full-profile grant was requested the wrong way (not by name, or with a remote sink) (C3). */
+declare class FullProfileGrantError extends ToolError {
+    constructor(message: string);
+}
+/** A ledger row broke the AIP-63 `ledgerRecord` shape; nothing was written. */
+declare class LedgerRecordInvalidError extends ToolError {
+    readonly issues: readonly string[];
+    constructor(issues: readonly string[]);
+}
+/** The grants file is not a readable grant list. */
+declare class GrantStoreInvalidError extends ToolError {
+    constructor(message: string);
+}
+
+/** The AIP-63 `domain` pattern: lowercase, ASCII or punycode, at least two labels. */
+declare const GRANT_DOMAIN_PATTERN: RegExp;
+interface GrantDomainPolicy {
+    /** Extra public-suffix check (for example one backed by the full Public Suffix List). */
+    isPublicSuffix?: (domain: string) => boolean;
+}
+/** True for a suffix in the embedded subset. */
+declare function isKnownPublicSuffix(domain: string): boolean;
+/**
+ * Validate a grant's domain list against AIP-63 C2 and return it lowercased and
+ * de-duplicated. Rejects `*`, `*.x`, a leading dot, an empty list, a bare TLD,
+ * a public suffix and anything that is not a plain host, each with a typed
+ * {@link GrantDomainError}. A grant covers the named domain and its subdomains.
+ */
+declare function validateGrantDomains(input: readonly string[], policy?: GrantDomainPolicy): string[];
+/** True when `host` is `domain` or one of its subdomains. */
+declare function hostCoveredBy(host: string, domain: string): boolean;
+
+/**
+ * The consent ledger (AIP-63 C10, C11): an append-only JSONL file, one record per
+ * grant, refresh, revoke, sink-ack or deny. The record shape is closed on purpose
+ * (see `ledgerRecordSchema`): there is no field a cookie value could go in.
+ */
+
+/** `~/.agentproto/bureau/consent.jsonl`. Resolved on call, never at import. */
+declare function defaultConsentLedgerPath(home?: string): string;
+declare const ledgerEventSchema: z.ZodEnum<{
+    grant: "grant";
+    refresh: "refresh";
+    revoke: "revoke";
+    "sink-ack": "sink-ack";
+    deny: "deny";
+}>;
+type LedgerEvent = z.infer<typeof ledgerEventSchema>;
+declare const ledgerActorSchema: z.ZodObject<{
+    kind: z.ZodEnum<{
+        human: "human";
+        agent: "agent";
+        system: "system";
+    }>;
+    via: z.ZodOptional<z.ZodString>;
+    deviceId: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+type LedgerActor = z.infer<typeof ledgerActorSchema>;
+declare const ledgerRecordSchema: z.ZodObject<{
+    seq: z.ZodNumber;
+    at: z.ZodISODateTime;
+    event: z.ZodEnum<{
+        grant: "grant";
+        refresh: "refresh";
+        revoke: "revoke";
+        "sink-ack": "sink-ack";
+        deny: "deny";
+    }>;
+    actor: z.ZodObject<{
+        kind: z.ZodEnum<{
+            human: "human";
+            agent: "agent";
+            system: "system";
+        }>;
+        via: z.ZodOptional<z.ZodString>;
+        deviceId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    grantId: z.ZodOptional<z.ZodString>;
+    sessionId: z.ZodOptional<z.ZodString>;
+    domains: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    fullProfile: z.ZodOptional<z.ZodLiteral<true>>;
+    cookieCount: z.ZodOptional<z.ZodNumber>;
+    nameHashes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    sinkId: z.ZodOptional<z.ZodString>;
+    derived: z.ZodOptional<z.ZodObject<{
+        local: z.ZodEnum<{
+            none: "none";
+            deleted: "deleted";
+        }>;
+        remote: z.ZodEnum<{
+            confirmed: "confirmed";
+            unavailable: "unavailable";
+            failed: "failed";
+            "not-applicable": "not-applicable";
+        }>;
+    }, z.core.$strict>>;
+    reason: z.ZodOptional<z.ZodString>;
+    prev: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+type LedgerRecord = z.infer<typeof ledgerRecordSchema>;
+/** A record before the ledger stamps `seq`, `at` and `prev`. */
+type LedgerEntry = Omit<LedgerRecord, "seq" | "at" | "prev">;
+/** SHA-256 of the grant id, a NUL byte and a cookie name, lowercase hex. Never a value. */
+declare function cookieNameHash(grantId: string, cookieName: string): string;
+interface ConsentLedgerOptions {
+    /** Ledger file. Default {@link defaultConsentLedgerPath}. */
+    path?: string;
+    now?: () => Date;
+}
+interface ConsentLedger {
+    readonly path: string;
+    /** Validate, stamp and append one record. One writer process only: concurrent processes can duplicate `seq` and break the chain, which `verifyChain` reports. Throws {@link LedgerRecordInvalidError} and writes nothing on a bad record. */
+    append(entry: LedgerEntry): LedgerRecord;
+    read(): LedgerRecord[];
+    /** True when every `prev` matches the SHA-256 of the line before it and `seq` counts up from 0. */
+    verifyChain(): boolean;
+}
+declare function createConsentLedger(opts?: ConsentLedgerOptions): ConsentLedger;
+
+/** The grant model of AIP-63 (`$defs/grant`) and where grants are kept. Grants hold no cookie values. */
+
+type GrantSink = {
+    kind: "local";
+} | {
+    kind: "remote";
+    providerId: string;
+    ackSeq: number;
+};
+type GrantSourceKind = "chrome" | "firefox" | "file" | "native-login";
+interface Grant {
+    id: string;
+    sessionId: string;
+    /** Paired device (AIP-59) this grant is scoped to. Absent: usable by any device the host serves (C12). */
+    deviceId?: string;
+    source: {
+        kind: GrantSourceKind;
+        profile: string;
+    };
+    /** Explicit registrable domains. Exactly one of `domains` and `fullProfile`. */
+    domains?: string[];
+    /** The recorded full-profile grant (C3). Not a wildcard domain. */
+    fullProfile?: true;
+    sinks: GrantSink[];
+    grantedAt: string;
+    grantedVia: "interactive" | "flag";
+    expiresAt?: string;
+    cookieCount: number;
+    revokedAt?: string;
+}
+declare const grantSchema: z.ZodObject<{
+    id: z.ZodString;
+    sessionId: z.ZodString;
+    deviceId: z.ZodOptional<z.ZodString>;
+    source: z.ZodObject<{
+        kind: z.ZodEnum<{
+            file: "file";
+            chrome: "chrome";
+            firefox: "firefox";
+            "native-login": "native-login";
+        }>;
+        profile: z.ZodString;
+    }, z.core.$strict>;
+    domains: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    fullProfile: z.ZodOptional<z.ZodLiteral<true>>;
+    sinks: z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+        kind: z.ZodLiteral<"local">;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"remote">;
+        providerId: z.ZodString;
+        ackSeq: z.ZodNumber;
+    }, z.core.$strict>]>>;
+    grantedAt: z.ZodISODateTime;
+    grantedVia: z.ZodEnum<{
+        interactive: "interactive";
+        flag: "flag";
+    }>;
+    expiresAt: z.ZodOptional<z.ZodISODateTime>;
+    cookieCount: z.ZodNumber;
+    revokedAt: z.ZodOptional<z.ZodISODateTime>;
+}, z.core.$strict>;
+/** True while the grant is not revoked and not past `expiresAt`. */
+declare function isGrantActive(grant: Grant, now?: Date): boolean;
+/** True when a call from `deviceId` may use the grant (C12): unscoped grants serve any device. */
+declare function grantServesDevice(grant: Grant, deviceId: string | undefined): boolean;
+/** Where grants live. Synchronous on purpose: a launch asks "is this grant still active" inline. */
+interface GrantStore {
+    list(): Grant[];
+    get(id: string): Grant | undefined;
+    put(grant: Grant): void;
+}
+declare function memoryGrantStore(initial?: readonly Grant[]): GrantStore;
+/** `~/.agentproto/bureau/grants.json`. Resolved on call, never at import. */
+declare function defaultGrantStorePath(home?: string): string;
+/** One JSON file, dir 0700, file 0600, replaced atomically on every write. */
+declare function fileGrantStore(path?: string): GrantStore;
+
+/** Injected seams of the consent host: the human prompt and the Chrome profile reader. */
+
+/** What the human is being asked. Counts only: a prompt never carries a cookie value. */
+type ConsentQuestion = {
+    kind: "domain";
+    domain: string;
+    profile: string;
+    presentCount: number | undefined;
+    deviceId?: string;
+} | {
+    kind: "full-profile";
+    profile: string;
+    warning: string;
+    deviceId?: string;
+} | {
+    kind: "sink";
+    providerId: string;
+    sessionId: string;
+};
+/** The interactive consent port. A CLI wires it to a terminal, a desktop app to a dialog, a test to a fake. */
+interface ConsentPrompt {
+    confirm(question: ConsentQuestion): Promise<boolean>;
+}
+/** Reads a Chrome profile. Every method that decrypts values is only called after consent. */
+interface ChromeProfilePort {
+    /** Presence scan (C5): counts per domain, no values, no Keychain. */
+    countByDomain(profile: string, domains: readonly string[]): Known<Record<string, number>>;
+    /** Whole-profile cookie count, no values. */
+    countAll(profile: string): Known<number>;
+    /** Decrypt the cookies of `domains`. Touches the Keychain: only for an explicit, consented import. */
+    readCookies(profile: string, domains: readonly string[]): SessionCookie[];
+}
+interface LocalChromePortOptions {
+    /** Chrome user-data root. Required: this package never guesses the real one here. */
+    chromeRoot: string;
+    /** Safe-Storage password source. Default reads the macOS Keychain at import time. */
+    safeStoragePassword?: () => string;
+}
+/** The default reader over a Chrome user-data dir. The profile must be a real `Default` or `Profile N` dir. */
+declare function localChromePort(opts: LocalChromePortOptions): ChromeProfilePort;
+
+/**
+ * The consent host: the one place a grant is created, refreshed or revoked.
+ * Human consent paths live here; agents get the narrower surface in `agent.ts`.
+ * No cookie value ever reaches the ledger, a thrown error or a returned result:
+ * values exist only in the per-grant jar file (derived material) and in the
+ * arrays handed to a provider's cookie source.
+ */
+
+/** Returned with every full-profile grant. Shown to the human verbatim. */
+declare const FULL_PROFILE_WARNING: string;
+type SinkRequest = {
+    kind: "local";
+} | {
+    kind: "remote";
+    providerId: string;
+    acknowledged?: boolean;
+};
+interface ImportRequest {
+    sessionId: string;
+    /** Chrome profile dir (`Default`, `Profile 1`). */
+    profile: string;
+    /** Explicit registrable domains. There is no "all". */
+    domains?: readonly string[];
+    /** `--yes`: the human confirmed the named domains without a prompt. */
+    yes?: boolean;
+    deviceId?: string;
+    sinks?: readonly SinkRequest[];
+    expiresAt?: string;
+    /** Defaults to a human. An `agent` here is refused and recorded as a deny row. */
+    actor?: LedgerActor;
+}
+interface FullProfileRequest {
+    sessionId: string;
+    profile: string;
+    yes?: boolean;
+    deviceId?: string;
+    expiresAt?: string;
+    actor?: LedgerActor;
+}
+interface GrantResult {
+    grant: Grant;
+    /** Cookie counts per domain from the presence scan; `undefined` when the scan failed. */
+    presence: Record<string, number> | undefined;
+    warnings: string[];
+}
+interface FullProfileResult {
+    grant: Grant;
+    /** The loud warning to show the human. */
+    warning: string;
+    warnings: string[];
+}
+interface RevokeResult {
+    grant: Grant;
+    derived: {
+        local: "deleted" | "none";
+        remote: "confirmed" | "unavailable" | "failed" | "not-applicable";
+    };
+}
+interface ConsentHostOptions {
+    grants: GrantStore;
+    ledger: ConsentLedger;
+    /** L5a store holding the session descriptor this host derives. */
+    store: SessionStorePort;
+    /** Directory of per-grant cookie jars (0700). Derived material: deleted on revoke. */
+    jarDir: string;
+    chrome: ChromeProfilePort;
+    /** Present: a human can be asked. Absent: non-interactive, so `--domains` and `--yes` are mandatory (C4). */
+    prompt?: ConsentPrompt;
+    domainPolicy?: GrantDomainPolicy;
+    /** C13: a device-scoped grant is honored only while its device is still paired. */
+    isDevicePaired?: (deviceId: string) => boolean;
+    /** Asks a remote sink to delete what it received. Absent: `remote` is recorded as `unavailable`. */
+    revokeRemote?: (grant: Grant) => Promise<"confirmed" | "failed" | "unavailable">;
+    /** Removes material this host does not own, such as a full-profile clone. True when something was deleted. */
+    deleteExtraDerived?: (grant: Grant) => Promise<boolean>;
+    now?: () => Date;
+    newId?: () => string;
+}
+interface FullProfileSelector {
+    grantId?: string;
+    sessionId?: string;
+    profile?: string;
+    deviceId?: string;
+}
+interface FullProfileProof {
+    readonly grantId: string;
+    isActive(): boolean;
+}
+interface ConsentHost {
+    importFromChrome(req: ImportRequest): Promise<GrantResult>;
+    grantFullProfile(req: FullProfileRequest): Promise<FullProfileResult>;
+    /** Re-read the grant's own domains from its own profile. Never widens. Allowed for an agent (C7). */
+    refresh(grantId: string, opts?: {
+        actor?: LedgerActor;
+    }): Promise<{
+        grant: Grant;
+        cookieCount: number;
+    }>;
+    revoke(grantId: string, opts?: {
+        actor?: LedgerActor;
+    }): Promise<RevokeResult>;
+    /** Proof for the kit's `fullProfile` unlock. Throws {@link FullProfileGrantError} when no active full-profile grant matches. */
+    fullProfileProof(selector: FullProfileSelector): FullProfileProof;
+    /** A provider cookie source that serves only this device's active, granted domains. */
+    cookieSourceFor(scope?: {
+        deviceId?: string;
+    }): (request: {
+        providerId: string;
+        profile: string;
+    }) => readonly BrowserCookie[];
+    /** Throws `browser:consent_required` unless an active grant of this session covers `host` for this device. */
+    assertCovered(input: {
+        sessionId: string;
+        host: string;
+        deviceId?: string;
+    }): Grant;
+    /** Record a refused agent attempt and throw {@link AgentGrantRefusedError}. */
+    refuseAgent(attempt: string, ctx: {
+        actor: LedgerActor;
+        grantId?: string;
+        sessionId?: string;
+        domains?: readonly string[];
+    }): never;
+    getGrant(id: string): Grant | undefined;
+    listGrants(): Grant[];
+}
+declare function createConsentHost(opts: ConsentHostOptions): ConsentHost;
+
+/**
+ * The agent-path surface (AIP-63 C7, plan F4). An agent may refresh inside a
+ * grant and revoke. It cannot grant, add a domain, change the profile or add a
+ * sink: each attempt is refused with a typed error and appended as a `deny` row.
+ */
+
+interface AgentSyncInput {
+    grantId: string;
+    /** Accepted only when identical to the grant's own domains. Anything else is a refused widening. */
+    domains?: readonly string[];
+    /** Accepted only when identical to the grant's own profile. */
+    profile?: string;
+}
+interface AgentConsentSurface {
+    /** `session_sync_from_chrome`: refresh within the grant. Cannot add a domain or change profile. */
+    sync(input: AgentSyncInput): Promise<{
+        grantId: string;
+        cookieCount: number;
+    }>;
+    revoke(grantId: string): Promise<void>;
+    /** Always refused: only a human consent path creates a grant. */
+    grant(input: {
+        sessionId: string;
+        domains?: readonly string[];
+    }): Promise<never>;
+    addSink(input: {
+        grantId: string;
+        providerId: string;
+    }): Promise<never>;
+}
+declare function createAgentConsentSurface(host: ConsentHost, who?: {
+    deviceId?: string;
+    via?: string;
+}): AgentConsentSurface;
+
+/**
+ * `doctor`: why can't Bureau read this Chrome profile? Every probe goes through
+ * an injected port, so tests use fakes and never touch a real profile. The
+ * Keychain is probed only when the caller asks for it explicitly.
+ */
+type DoctorFailure = "missing" | "full-disk-access" | "unreadable" | "keychain-denied";
+interface DoctorCheck {
+    id: "local-state" | "cookies-db" | "keychain";
+    status: "ok" | "fail" | "skipped";
+    detail: string;
+    failure?: DoctorFailure;
+    /** What to do about it. */
+    fix?: string;
+}
+interface DoctorReport {
+    ok: boolean;
+    checks: DoctorCheck[];
+    /** Set when any check failed: the way around needing the profile at all. */
+    recommendation?: string;
+}
+/** Probes the doctor runs. Each throws a Node-style error (with `code`) on failure. */
+interface DoctorPort {
+    /** Raw text of `Local State`. */
+    readLocalState(): string;
+    /** Copy the profile's Cookies db somewhere temporary and remove the copy. */
+    copyCookiesDb(profile: string): void;
+    /** Ask the Keychain for the Safe Storage key. Only called when `checkKeychain` is true. */
+    probeKeychain?(): void;
+    /** The exact executable that needs Full Disk Access. */
+    binary: string;
+}
+interface DoctorOptions {
+    port: DoctorPort;
+    profile: string;
+    /** Explicit action: touch the Keychain. Default false. */
+    checkKeychain?: boolean;
+}
+declare function runDoctor(opts: DoctorOptions): DoctorReport;
+interface LocalDoctorPortOptions {
+    chromeRoot: string;
+    binary?: string;
+    probeKeychain?: () => void;
+}
+/** The real-filesystem port. The Cookies copy lives in a temp dir and is removed at once. */
+declare function localDoctorPort(opts: LocalDoctorPortOptions): DoctorPort;
+
+export { ACCOUNT_SWITCHER_MISSING_CODE, AGENT_GRANT_REFUSED_CODE, type AccountSwitcher, AccountSwitcherMissingError, type AgentConsentSurface, AgentGrantRefusedError, type AgentSyncInput, type ApiRawResult, type AuthCookieMeta, type AuthSignalRegistry, type AuthStatus, BUILTIN_INJECT_FROM, BUILTIN_STRATEGY_KINDS, type BuildOwnedDescriptorInput, type BuiltinInjectFrom, type BuiltinStrategyKind, CHROME_IDENTITY_CODE, CONSENT_DECLINED_CODE, CONSENT_FLAGS_REQUIRED_CODE, CONSENT_REQUIRED_CODE, COOKIE_STALE_TTL_MS, type CamofoxNativeInject, type CamofoxSession, type ChromeCookieStrategy, type ChromeIdentity, ChromeIdentityError, type ChromeIdentityOptions, type ChromeProfileInject, type ChromeProfilePort, ConsentDeclinedError, type ConsentHost, type ConsentHostOptions, type ConsentLedger, type ConsentLedgerOptions, type ConsentPrompt, type ConsentQuestion, ConsentRequiredError, type DoctorCheck, type DoctorFailure, type DoctorOptions, type DoctorPort, type DoctorReport, type DomainAuthSignal, FULL_PROFILE_REFUSED_CODE, FULL_PROFILE_WARNING, type FileInject, type FileSessionStoreOptions, FullProfileGrantError, type FullProfileProof, type FullProfileRequest, type FullProfileResult, type FullProfileSelector, GRANT_DOMAIN_INVALID_CODE, GRANT_DOMAIN_PATTERN, GRANT_STORE_INVALID_CODE, type Grant, GrantDomainError, type GrantDomainPolicy, type GrantDomainReason, type GrantResult, type GrantSink, type GrantSourceKind, type GrantStore, GrantStoreInvalidError, type ImportRequest, type Known, LEDGER_RECORD_INVALID_CODE, type LedgerActor, type LedgerEntry, type LedgerEvent, type LedgerRecord, LedgerRecordInvalidError, type LocalBrowserSession, type LocalBrowserSessionOptions, type LocalChromePortOptions, type LocalDoctorPortOptions, type LocalStateProfile, NonInteractiveConsentError, type NormalizeOptions, type OpenSessionOptions, type OwnedStorageStateStrategy, type ParsedLocalState, type RawCookie, type ResolveSessionDeps, type ResolvedSession, type RevokeResult, SESSION_DESCRIPTOR_INVALID_CODE, SESSION_RESOLVE_CODE, SESSION_SOURCE_DUPLICATE_CODE, SESSION_SOURCE_RESERVED_CODE, SESSION_SOURCE_UNKNOWN_CODE, SINK_ACK_REQUIRED_CODE, type SessionAuthDescription, type SessionAuthState, type SessionCookie, type SessionDescriptor, SessionDescriptorInvalidError, type SessionIdentity, type SessionInject, type SessionInjectFrom, SessionResolveError, type SessionSource, type SessionSourceCatalog, SessionSourceDuplicateError, type SessionSourceMeta, type SessionSourceRef, type SessionSourceRegistry, SessionSourceReservedError, SessionSourceUnknownError, type SessionStorePort, SinkAckRequiredError, type SinkRequest, type SiteAuthSignal, type SourceInject, type SourceStrategy, type StoredCredentialStrategy, type Strategy, assertChromeLaunchDirSafe, authStatusSchema, buildOwnedSessionDescriptor, camofoxStatePath, catalogSessionStore, chromeCookieStrategyOf, chromeIdentityLabel, chromeLocalStatePath, chromeTimeToIso, chromeUserDataDir, chromeUserDataRoot, compositeSessionStore, cookieFreshness, cookieNameHash, countCookies, countCookiesByDomain, createAgentConsentSurface, createAuthSignalRegistry, createConsentHost, createConsentLedger, createLocalBrowserSession, createSessionSourceRegistry, decryptChromeCookies, decryptChromeValue, dedupeCookies, defaultAuthSignalRegistry, defaultCamofoxBase, defaultConsentLedgerPath, defaultGrantStorePath, describeSessionAuth, domainAuthSignal, domainMatches, fileGrantStore, fileSessionStore, gatherCookies, gatherCookiesForStrategy, grantSchema, grantServesDevice, hostCoveredBy, injectFromOf, injectKindOf, isBuiltinStrategyKind, isCamofoxNativeInject, isChromeCookieStrategy, isChromeProfileInject, isFileInject, isGrantActive, isKnown, isKnownPublicSuffix, isOwnedStorageStateStrategy, isSessionSourceUnknownError, isSourceInject, isSourceStrategy, isStoredCredentialStrategy, knownOr, ledgerActorSchema, ledgerEventSchema, ledgerRecordSchema, localChromePort, localDoctorPort, memoryGrantStore, normalizeDescriptor, openSession, ownedStorageStatePath, parseLocalState, parseSessionDescriptor, priorChromeStrategy, profileAuthedDomains, profileDirs, profileLoggedInDomains, readLocalState, readSafeStorageKey, resolveChromeProfile, resolveInjectFromStrategies, resolveSession, runDoctor, safeStorageKey, scanChromeIdentities, selectResolutionStrategy, sessionDescriptorSchema, sessionIdentitySchema, sessionInjectSchema, strategySchema, toSessionCookie, validateGrantDomains, verifyChromeIdentity };