@serviceme/devtools-core 0.1.9 → 0.2.1

package/dist/auth.d.mts

@@ -0,0 +1,592 @@
+import { AuthProvider, AuthAccountMeta, AuthStatus, AuthLoginResult, AuthWhoamiResult, AuthSwitchResult } from '@serviceme/devtools-protocol';
+
+/**
+ * AccessControl — Pure logic for org-membership gating.
+ *
+ * Ported from `apps/extension/src/services/auth/AccessControlService.ts`
+ * but stripped of all VSCode dependencies:
+ *   - No `vscode.window.showWarningMessage` — callers render the notice.
+ *   - No `vscode.context.globalState` — callers inject a `KeyValueStore`.
+ *   - No `vscode.Event` — uses a plain `onDidChange` callback.
+ *
+ * The class is generic over the membership-fetcher function so it can
+ * run identically with the CLI's `@serviceme/shared` `getGitHubOrgMembership`
+ * or with the Extension's bundled copy. ADL-003 forbids Core from
+ * importing `@serviceme/shared` directly, so the org membership
+ * result type is defined locally and the runtime adapter wraps the
+ * shared helper at the boundary (Phase 5.3+).
+ *
+ * Refs:
+ * - 4.功能规划.md §2.1 — `AccessControl.ts 从 AccessControlService 改写`
+ * - ADL-003 — `@serviceme/shared` boundary (Core MUST NOT import shared)
+ */
+
+/** Core-local mirror of `GitHubOrgMembershipCheckResult` (defined in `@serviceme/shared`). */
+interface CoreOrgMembershipResult {
+    status: "active" | "pending" | "not_member" | "unknown";
+    httpStatus?: number;
+    role?: string;
+    directMembership?: boolean;
+}
+/**
+ * Upstream org-membership fetcher. CLI / Extension adapters wrap
+ * `getGitHubOrgMembership` (or the local extension copy) to match
+ * this signature.
+ */
+type OrgMembershipFetcher = (token: string, org: string) => Promise<CoreOrgMembershipResult>;
+/** Pluggable key/value store. Extension injects `globalState`-backed impl; CLI injects a file-backed impl. */
+interface KeyValueStore {
+    get<T>(key: string): T | undefined;
+    update<T>(key: string, value: T): Promise<void>;
+}
+interface AccessCheckResult {
+    allowed: boolean;
+    reason?: "not_authenticated" | "not_member";
+    username?: string;
+}
+interface AccessControlOptions {
+    org: string;
+    /** Domains that auto-qualify Microsoft users without a GitHub link. */
+    microsoftEmailDomains?: readonly string[];
+    /** TTL for in-memory membership cache (ms). */
+    cacheTtlMs?: number;
+    /** TTL for persisted membership cache (ms). */
+    persistentCacheTtlMs?: number;
+    /** Tokens whose bearer can be supplied to `OrgMembershipFetcher`. */
+    tokenFetcher: (provider: AuthProvider) => Promise<string | null>;
+    /** Upstream org-membership fetcher (typically `getGitHubOrgMembership` from `@serviceme/shared`). */
+    orgFetcher: OrgMembershipFetcher;
+    /** Clock seam for tests. */
+    now?: () => number;
+}
+declare class AccessControl {
+    private readonly kv;
+    private readonly memCache;
+    private readonly serverInOrgMem;
+    private readonly listeners;
+    private readonly opts;
+    constructor(kv: KeyValueStore, options: AccessControlOptions);
+    /** Subscribe to inOrg changes (used by extension to refresh access-gated UI). */
+    onDidChange(listener: () => void): () => void;
+    /** Full check: requires authentication + org membership / admin grant. */
+    checkAccess(user: AuthAccountMeta | null): Promise<AccessCheckResult>;
+    /** Admin: grant access to a GitHub username (bypasses org check). */
+    grantAccess(username: string): Promise<void>;
+    /** Admin: revoke a previously granted access. */
+    revokeAccess(username: string): Promise<void>;
+    /** Snapshot of all admin-granted usernames (lowercased). */
+    getGrantedUsers(): string[];
+    /** Cached membership lookup with both in-memory + persistent layers. */
+    checkOrgMembership(username: string): Promise<boolean>;
+    /** Server-confirmed inOrg status (set by device claim flow). */
+    setServerInOrg(username: string, inOrg: boolean): void;
+    /** Inspect server-confirmed inOrg for a username; returns undefined when unknown. */
+    getServerInOrg(username: string): boolean | undefined;
+    private resolveDecision;
+    private updateCache;
+    private notifyListeners;
+}
+
+/**
+ * AuthStateManager — In-memory mirror of the persisted auth state.
+ *
+ * Holds the multi-account map (provider + accountId keyed) plus the
+ * "active" provider/account pair. Emits change events via Node's
+ * built-in `events.EventEmitter` so listeners stay decoupled.
+ *
+ * Important: this class does NOT touch `vscode.SecretStorage` or any
+ * file — it only keeps the metadata (`AuthAccountMeta`) and the
+ * `activeProvider` selection. Token bytes are looked up via the
+ * `KeychainAuthTokenStore` on demand. This separation is what lets
+ * `AuthCore` run identically in CLI + Extension.
+ *
+ * Refs:
+ * - 4.功能规划.md §2.1 — `AuthStateManager.ts events.EventEmitter, NO VSCode dep`
+ * - ADL-004 — token bytes never enter Core state
+ */
+
+interface AuthStateManagerOptions {
+    /** EventEmitter listener cap; defaults to 32 (Node default) but raised for hot test paths. */
+    maxListeners?: number;
+}
+declare class AuthStateManager {
+    private readonly emitter;
+    private accounts;
+    private activeProvider;
+    private activeAccountId;
+    private lastError;
+    constructor(opts?: AuthStateManagerOptions);
+    /** Subscribe to state-change events. Returns a disposer. */
+    onDidChange(listener: () => void): () => void;
+    /** Snapshot of all known accounts (immutable copy). */
+    listAccounts(): AuthAccountMeta[];
+    /** Find an account by `(provider, accountId)` tuple; returns `null` when absent. */
+    findAccount(provider: AuthProvider, accountId: string): AuthAccountMeta | null;
+    /** First account for the requested provider — used for "switch to GitHub" UX. */
+    findFirstForProvider(provider: AuthProvider): AuthAccountMeta | null;
+    /** Insert or update an account entry. New accounts land at the head of the list. */
+    upsertAccount(meta: AuthAccountMeta): void;
+    /** Remove an account entry. Returns `true` when an entry was removed. */
+    removeAccount(provider: AuthProvider, accountId: string): boolean;
+    /** Set the active provider. When `accountId` is omitted, picks the first account for that provider. */
+    setActive(provider: AuthProvider, accountId?: string): boolean;
+    /** Currently active provider — `null` when no session is active. */
+    getActiveProvider(): AuthProvider | null;
+    /** Currently active account metadata — `null` when none. */
+    getActiveAccount(): AuthAccountMeta | null;
+    /** True when at least one provider has an account entry. */
+    hasAnySession(): boolean;
+    /** Snapshot of the state for `auth.status` and bridge serialization. */
+    getStatus(): AuthStatus;
+    /** Record a non-fatal error from the last login/refresh attempt. */
+    recordError(message: string): void;
+    /** Clear the recorded error (e.g. after a successful login). */
+    clearError(): void;
+    /** Drop every account — used by `auth.logout` with no provider. */
+    clearAll(): void;
+    private fire;
+}
+
+/**
+ * KeychainAuthTokenStore — abstract adapter for token byte persistence.
+ *
+ * Per ADL-004 the OAuth token bytes live in one of three places:
+ *   (a) VSCode `SecretStorage` (Extension process)
+ *   (b) `@napi-rs/keyring` Entry (CLI process)
+ *   (c) HTTP request `Authorization` header
+ *
+ * `AuthCore` MUST NOT call any of these directly. Instead it receives
+ * a `KeychainAuthTokenStore` via DI; CLI provides a `@napi-rs/keyring`
+ * adapter, Extension provides a `SecretStorage` adapter. This keeps
+ * Core free of native-binding concerns and lets the same business
+ * logic power both runtimes.
+ *
+ * Implementations:
+ * - CLI: `apps/serviceme-cli/src/.../KeyringTokenStore.ts` (Phase 5.3)
+ * - Extension: `apps/extension/src/.../SecretStorageTokenStore.ts` (Phase 5.5)
+ *
+ * Failure semantics — `get()` returns `null` when no token is stored
+ * (cold-start), throws when the underlying keychain is unavailable
+ * (rare on Linux without libsecret). Callers should surface the throw
+ * as `AUTH_KEYRING_UNAVAILABLE` rather than silently falling back to
+ * in-memory storage (per ADL-004 §不变量).
+ *
+ * Refs:
+ * - ADL-004 — CLI 端 Auth Token 存储选型
+ * - 4.功能规划.md §2.1 — "Core MUST NOT directly depend on `@napi-rs/keyring`"
+ */
+/** Opaque account identifier (provider + upstream user id). */
+interface KeychainAccountKey {
+    provider: string;
+    accountId: string;
+}
+/** Non-secret metadata returned alongside a `get()` so callers can audit. */
+interface KeychainTokenMetadata {
+    provider: string;
+    accountId: string;
+    expiresAt?: number | null;
+    storedAt?: number;
+}
+/**
+ * Result envelope — callers receive the token bytes (for immediate use
+ * in an HTTP `Authorization` header) plus optional non-secret metadata.
+ *
+ * IMPORTANT: the `token` field is plain `string` here, not the
+ * `SecretToken` brand. The provider -> store -> HTTP-header pipeline
+ * runs inside a single trust boundary; crossing that boundary requires
+ * `KeychainTokenEnvelope<SecretToken>` and the `auth.tokenRead`
+ * capability gate (see ADL-004 §不变量).
+ */
+interface KeychainTokenEnvelope {
+    token: string;
+    metadata: KeychainTokenMetadata;
+}
+/**
+ * Abstract token-storage adapter. All methods are async because the
+ * keyring / SecretStorage backends are async-by-nature.
+ *
+ * Thread-safety: implementations MUST be safe for concurrent calls;
+ * `AuthCore` will multiplex over multiple providers on the same
+ * runtime.
+ */
+interface KeychainAuthTokenStore {
+    /** Persist token bytes for the given provider + account pair. */
+    set(key: KeychainAccountKey, token: string, opts?: {
+        expiresAt?: number | null;
+    }): Promise<void>;
+    /** Fetch the token bytes; returns `null` when none is stored. */
+    get(key: KeychainAccountKey): Promise<KeychainTokenEnvelope | null>;
+    /** Remove the token entry. Idempotent — removing a missing entry is not an error. */
+    delete(key: KeychainAccountKey): Promise<void>;
+    /**
+     * List all stored token keys (metadata only — never the token bytes).
+     * Useful for multi-account enumeration and bridge `auth.status`.
+     */
+    list(): Promise<KeychainAccountKey[]>;
+    /**
+     * Health probe — returns `false` when the keychain is unreachable
+     * (e.g. Linux without libsecret). Callers SHOULD probe on first
+     * use and surface `AUTH_KEYRING_UNAVAILABLE` rather than degrade.
+     */
+    isAvailable(): Promise<boolean>;
+}
+/**
+ * Sentinel error thrown by `KeychainAuthTokenStore.get()` / `.set()`
+ * when the underlying keychain is unavailable. Callers map this to
+ * `AUTH_KEYRING_UNAVAILABLE` (Phase 5.3 error code).
+ */
+declare class KeychainUnavailableError extends Error {
+    constructor(message: string, cause?: unknown);
+}
+/**
+ * In-memory `KeychainAuthTokenStore` — test/dev fallback. NEVER use
+ * in production: tokens live in process memory and disappear on exit.
+ * Production wiring is `KeyringTokenStore` (CLI) / `SecretStorageTokenStore`
+ * (Extension).
+ */
+declare class InMemoryKeychainAuthTokenStore implements KeychainAuthTokenStore {
+    private readonly entries;
+    private compositeKey;
+    set(key: KeychainAccountKey, token: string, opts?: {
+        expiresAt?: number | null;
+    }): Promise<void>;
+    get(key: KeychainAccountKey): Promise<KeychainTokenEnvelope | null>;
+    delete(key: KeychainAccountKey): Promise<void>;
+    list(): Promise<KeychainAccountKey[]>;
+    isAvailable(): Promise<boolean>;
+}
+
+/**
+ * IAuthProvider — Provider abstraction used by `AuthCore`.
+ *
+ * Each provider (GitHub / Microsoft / future) exposes the same minimal
+ * surface so `AuthCore` can drive device-flow style handshakes without
+ * coupling to a specific OAuth server. Implementations MUST NOT touch
+ * `vscode`, `globalState`, or `SecretStorage` — those concerns live in
+ * the CLI / Extension adapters (see ADL-004).
+ *
+ * Per ADL-004 the **token bytes** never leave the provider's runtime
+ * — `requestDeviceFlow()` returns enough metadata for the caller to
+ * display the verification URL + user code; the actual `token` is
+ * persisted via the `KeychainAuthTokenStore` interface (DI) immediately
+ * after `completeDeviceFlow()` resolves.
+ *
+ * Refs:
+ * - 4.功能规划.md §2.1 — `providers/IAuthProvider.ts`
+ * - ADL-002 — Device Flow OAuth (locked)
+ * - ADL-004 — token storage boundary
+ */
+
+/** Public, non-secret user metadata fetched right after device-flow success. */
+interface IAuthProviderUserInfo {
+    id: string;
+    login?: string;
+    name?: string;
+    email?: string | null;
+    avatarUrl?: string;
+}
+/**
+ * Outcome of `completeDeviceFlow()`. The token is returned ONLY so the
+ * caller can immediately persist it via `KeychainAuthTokenStore`; it
+ * must not be logged, JSON.stringify'd, or stored on disk by callers.
+ */
+interface IAuthProviderSession {
+    token: string;
+    refreshToken?: string;
+    expiresIn?: number;
+    user: IAuthProviderUserInfo;
+}
+/**
+ * Abstraction for any auth provider that supports OAuth Device Flow
+ * (ADL-002). The provider is responsible for:
+ *   1. Talking to the upstream `POST <deviceCodeUrl>` to obtain the
+ *      user-visible code + verification URL.
+ *   2. Polling the upstream `POST <tokenUrl>` until the user grants
+ *      access (or the device code expires).
+ *   3. Fetching user metadata so the account is recognizable on the
+ *      bridge side.
+ */
+interface IAuthProvider {
+    readonly providerId: AuthProvider;
+    /**
+     * Step 1: ask the upstream for a fresh device-flow code.
+     * Returns the user-visible code, verification URL, and the
+     * caller-supplied callback for the polling loop.
+     */
+    requestDeviceFlow(opts?: {
+        scope?: string;
+    }): Promise<AuthLoginResult>;
+    /**
+     * Step 2: poll until the user authorizes (or the code expires).
+     * Returns the session including the token bytes — callers MUST
+     * immediately hand the token to a `KeychainAuthTokenStore` and
+     * discard the returned reference.
+     *
+     * @param shouldContinue Aborts the poll loop when it returns false
+     *   (used by callers to wire up Ctrl-C, QuickPick cancel, etc.).
+     */
+    completeDeviceFlow(deviceCode: string, shouldContinue?: () => boolean): Promise<IAuthProviderSession>;
+    /**
+     * Refresh an expiring access token. Throws when the provider has no
+     * refresh-token grant (GitHub user-to-server tokens, for instance,
+     * cannot be refreshed and must be re-issued via device flow).
+     */
+    refreshAccessToken(refreshToken: string): Promise<IAuthProviderSession>;
+    /** Validate a token by hitting the provider's `GET /user`-style endpoint. */
+    validateToken(token: string): Promise<boolean>;
+    /** Fetch non-secret user metadata (used by `auth.whoami` and `auth.switch`). */
+    fetchAccountMeta(token: string): Promise<AuthAccountMeta>;
+}
+
+/**
+ * ProviderRegistry — Maps `AuthProvider` ids to `IAuthProvider` instances.
+ *
+ * `AuthCore` looks up providers by `AuthProvider` enum (string union
+ * per the protocol). The registry is mutable so that callers can
+ * replace a provider (e.g. swap a real keyring-backed implementation
+ * in tests), but providers must be registered before `AuthCore.login()`
+ * is called.
+ *
+ * Refs:
+ * - 4.功能规划.md §2.1 — `ProviderRegistry.ts`
+ */
+
+declare class ProviderRegistry {
+    private readonly providers;
+    /** Register or replace a provider implementation. */
+    register(provider: IAuthProvider): void;
+    /** Look up a registered provider by id; throws when missing. */
+    get(providerId: AuthProvider): IAuthProvider;
+    /** Non-throwing lookup; returns `undefined` when the provider is unknown. */
+    tryGet(providerId: AuthProvider): IAuthProvider | undefined;
+    /** Return all registered provider ids — used by `auth.status` and bridge capability hints. */
+    list(): AuthProvider[];
+    /** True when a provider has been registered for this id. */
+    has(providerId: AuthProvider): boolean;
+}
+
+/**
+ * AuthCore — Main entry for the auth domain.
+ *
+ * Owns the `ProviderRegistry` + `AuthStateManager` + `KeychainAuthTokenStore`.
+ * Provides a small, side-effectful surface that CLI / Extension / Bridge
+ * handlers can call:
+ *
+ *   - `login(provider)`    → drives Device Flow, persists token via store.
+ *   - `logout(provider?)`  → clears the active session (and token bytes).
+ *   - `status()`           → snapshot for `auth.status`.
+ *   - `whoami()`           → minimal identity for `auth.whoami`.
+ *   - `switchProvider(p)`  → flip the active provider (multi-account).
+ *
+ * Core NEVER holds token bytes past the `KeychainAuthTokenStore.set()`
+ * boundary — callers pass the token to the store immediately, then
+ * drop the local reference. Per ADL-004 the token bytes only live in
+ * (a) SecretStorage / (b) keyring / (c) HTTP Authorization header.
+ *
+ * Refs:
+ * - 4.功能规划.md §2.1 — `AuthCore.ts 主入口`
+ * - ADL-002 — Device Flow OAuth
+ * - ADL-004 — Auth token storage
+ */
+
+interface AuthCoreOptions {
+    providers: IAuthProvider[];
+    tokenStore: KeychainAuthTokenStore;
+    accessControl?: AccessControl;
+    stateManager?: AuthStateManager;
+}
+/**
+ * Callback invoked once the user finishes the device-flow handshake but
+ * BEFORE the token is written to the keychain. Lets the caller display
+ * the `userCode` + `verificationUrl` to the user (Phase 5.3 CLI prints to
+ * stdout; Phase 5.5 Extension pops a webview notification).
+ */
+type DeviceFlowUiCallback = (result: AuthLoginResult) => void | Promise<void>;
+/**
+ * Optional cancellation handle — when `shouldContinue()` returns false,
+ * the polling loop exits with a clear error so callers can render
+ * "Login cancelled" UX.
+ */
+type CancellationCheck = () => boolean;
+declare class AuthCore {
+    private readonly registry;
+    private readonly state;
+    private readonly tokenStore;
+    private readonly accessControl?;
+    constructor(opts: AuthCoreOptions);
+    /** Snapshot of every account, the active provider, and the last error. */
+    status(): AuthStatus;
+    /** List accounts (immutable copy). */
+    listAccounts(): AuthAccountMeta[];
+    /**
+     * Drive the device-flow login for `provider`.
+     *
+     * Sequence:
+     *   1. Ask the provider for the user code + verification URL.
+     *   2. Surface the code to the user (via `ui`).
+     *   3. Poll until the user authorizes (or `shouldContinue` aborts).
+     *   4. Persist the token via `KeychainAuthTokenStore.set()`.
+     *   5. Insert the resulting `AuthAccountMeta` into state and mark active.
+     */
+    login(provider: AuthProvider, ui: DeviceFlowUiCallback, shouldContinue?: CancellationCheck): Promise<AuthLoginResult>;
+    /**
+     * Complete the device-flow handshake given a pre-fetched user code.
+     * Useful when the caller (Phase 5.3 CLI) wants to fetch the code,
+     * print the URL, and then poll on a subsequent invocation.
+     */
+    completeLogin(provider: AuthProvider, deviceCode: string, shouldContinue?: CancellationCheck): Promise<AuthLoginResult>;
+    /** Resolve the provider + token for the active session; returns null when no session is active. */
+    resolveActiveToken(): Promise<{
+        provider: AuthProvider;
+        account: AuthAccountMeta;
+        token: string;
+    } | null>;
+    /**
+     * Logout: removes the token bytes from the keychain + drops the
+     * account entry from state. When `provider` is omitted, clears
+     * every account.
+     */
+    logout(provider?: AuthProvider): Promise<{
+        provider: AuthProvider | null;
+        success: boolean;
+    }>;
+    /** Minimal identity for `auth.whoami`. */
+    whoami(): Promise<AuthWhoamiResult>;
+    /** Switch the active provider. Returns the resulting active account. */
+    switchProvider(provider: AuthProvider, accountId?: string): AuthSwitchResult;
+    /** Run the access-control check against the active account (optional, requires AccessControl). */
+    checkAccess(): Promise<AccessCheckResult | null>;
+    /** Expose the state manager for test inspection (not for mutation). */
+    getStateManager(): AuthStateManager;
+    /** Expose the provider registry for test inspection. */
+    getProviderRegistry(): ProviderRegistry;
+    /** Expose the access control (or undefined when not configured). */
+    getAccessControl(): AccessControl | undefined;
+    private persistSession;
+}
+
+/**
+ * GitHubAuthProvider — Device Flow OAuth implementation.
+ *
+ * Implements the GitHub OAuth Device Flow per the official spec
+ * (https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps#device-flow).
+ *
+ * Per ADL-002 the device flow is the locked authentication strategy for
+ * SERVICEME — no localhost callback server, no PAT. This class is a
+ * pure HTTP client (uses native `fetch`, no vscode dependency) that
+ * returns the token bytes for the caller's `KeychainAuthTokenStore` to
+ * persist immediately.
+ *
+ * Token bytes NEVER enter logs / errors / debug output. The provider
+ * exposes only the user-visible code + verification URL during the
+ * device-flow handshake.
+ *
+ * Refs:
+ * - ADL-002 — Device Flow OAuth (locked)
+ * - 4.功能规划.md §2.1 — `providers/GitHubAuthProvider.ts`
+ */
+
+/** Tunable provider config — exposed for tests + forks. */
+interface GitHubAuthProviderConfig {
+    clientId: string;
+    deviceCodeUrl?: string;
+    tokenUrl?: string;
+    userUrl?: string;
+    scope?: string;
+    /** Polling interval (ms) floor. The device-flow response's `interval` wins when larger. */
+    minPollIntervalMs?: number;
+    /** Maximum poll interval after exponential back-off. */
+    maxPollIntervalMs?: number;
+    /** Fetch override (for tests + DI). */
+    fetchImpl?: typeof fetch;
+    /** Maximum wall-clock time to wait for the user before giving up (ms). Defaults to `expires_in * 1000`. */
+    maxWaitMs?: number;
+    /** Base delay (ms) before retrying the device-code request after a transient network error. */
+    deviceCodeRetryBaseDelayMs?: number;
+}
+declare class GitHubAuthProvider implements IAuthProvider {
+    readonly providerId: AuthProvider;
+    private readonly cfg;
+    constructor(config: GitHubAuthProviderConfig);
+    requestDeviceFlow(opts?: {
+        scope?: string;
+    }): Promise<AuthLoginResult>;
+    completeDeviceFlow(deviceCode: string, shouldContinue?: () => boolean): Promise<IAuthProviderSession>;
+    refreshAccessToken(refreshToken: string): Promise<IAuthProviderSession>;
+    validateToken(token: string): Promise<boolean>;
+    fetchAccountMeta(token: string): Promise<AuthAccountMeta>;
+    private fetchGitHubUser;
+    /**
+     * GitHub's `/user` endpoint returns `null` when the user kept their
+     * email private. The `/user/emails` endpoint reveals verified emails;
+     * we pick the primary one, falling back to the synthetic
+     * `<login>@github.local` form so the account is never email-less.
+     */
+    private resolveEmail;
+}
+
+/**
+ * MicrosoftAuthProvider — Microsoft Account (MSA) OAuth Device Flow stub.
+ *
+ * The Extension's existing `MicrosoftAuthProvider` (`apps/extension/src/services/auth/providers/MicrosoftAuthProvider.ts`)
+ * delegates to VSCode's built-in `vscode.authentication.getSession()` API
+ * — there's no direct Microsoft device-flow endpoint exposed for
+ * first-party apps. To keep Core usable from the CLI without VSCode,
+ * we expose a minimal stub that throws "not implemented in Core" so
+ * callers can detect and route back to the Extension adapter.
+ *
+ * The reason this lives in Core at all (instead of being purely
+ * Extension-side) is the cross-runtime registry: `AuthCore` needs to
+ * know which providers it MIGHT support, even if only the Extension
+ * process can actually fulfil the Microsoft login.
+ *
+ * Refs:
+ * - 4.功能规划.md §2.1 — `providers/MicrosoftAuthProvider.ts 从 extension 整体迁移`
+ * - ADL-002 — Device Flow OAuth (locked, GitHub-only)
+ */
+
+/**
+ * Error thrown when callers invoke Microsoft auth from a non-Extension
+ * runtime (CLI / Bridge). The CLI maps this to `AUTH_PROVIDER_REQUIRES_HOST`
+ * so the user is prompted to retry inside VSCode.
+ */
+declare class MicrosoftProviderNotHostedError extends Error {
+    constructor(message?: string);
+}
+declare class MicrosoftAuthProvider implements IAuthProvider {
+    readonly providerId: AuthProvider;
+    requestDeviceFlow(): Promise<AuthLoginResult>;
+    completeDeviceFlow(_deviceCode: string, _shouldContinue?: () => boolean): Promise<IAuthProviderSession>;
+    refreshAccessToken(_refreshToken: string): Promise<IAuthProviderSession>;
+    validateToken(_token: string): Promise<boolean>;
+    fetchAccountMeta(_token: string): Promise<AuthAccountMeta>;
+}
+
+/**
+ * AuthCore — Pure local utilities for GitHub local email handling.
+ *
+ * Copied verbatim from `@serviceme/shared/src/github-user-email.ts` (15 LOC)
+ * because ADL-003 forbids Core from depending on `@serviceme/shared`. These
+ * helpers are pure functions with zero side effects, so the duplication is
+ * trivial to keep in sync.
+ *
+ * Refs:
+ * - 4.功能规划.md §2.1 — "utils/githubUserEmail.ts 纯函数,直接搬"
+ * - ADL-003 — `@serviceme/shared` boundary decision
+ */
+/**
+ * Returns true when the supplied address is a synthetic GitHub "local" email
+ * (suffixed with `@github.local`). Real GitHub OAuth clients often return
+ * `null` for `email` (user kept it private) and the application substitutes
+ * `<login>@github.local` to keep the field non-null.
+ */
+declare function isGitHubLocalEmail(email: string | null | undefined): boolean;
+/** Build a synthetic `<login>@github.local` address. */
+declare function buildGitHubLocalEmail(login: string): string;
+/**
+ * Resolve the user's primary email address — falling back to the synthetic
+ * `<login>@github.local` form when the upstream email is missing or blank.
+ */
+declare function resolvePrimaryEmail(login: string, email: string | null | undefined): string;
+
+export { type AccessCheckResult, AccessControl, type AccessControlOptions, AuthCore, type AuthCoreOptions, AuthStateManager, type AuthStateManagerOptions, type CancellationCheck, type DeviceFlowUiCallback, GitHubAuthProvider, type GitHubAuthProviderConfig, type IAuthProvider, type IAuthProviderSession, type IAuthProviderUserInfo, InMemoryKeychainAuthTokenStore, type KeyValueStore, type KeychainAccountKey, type KeychainAuthTokenStore, type KeychainTokenEnvelope, type KeychainTokenMetadata, KeychainUnavailableError, MicrosoftAuthProvider, MicrosoftProviderNotHostedError, type OrgMembershipFetcher, ProviderRegistry, buildGitHubLocalEmail, isGitHubLocalEmail, resolvePrimaryEmail };