@serviceme/devtools-core 2.0.0 → 2.0.2

package/dist/index-CoA6y0MP.d.mts

@@ -0,0 +1,498 @@
+import { AuthAccountMeta, AuthLoginResult, AuthProvider, AuthStatus, AuthSwitchResult, AuthWhoamiResult } from "@serviceme/devtools-protocol";
+//#region src/auth/AccessControl.d.ts
+/** Core-local mirror of `GitHubOrgMembershipCheckResult` (defined in `@serviceme/devtools-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/devtools-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;
+}
+//#endregion
+//#region src/logger.d.ts
+interface ServiceMeLogger {
+  debug(message: string, ...args: unknown[]): void;
+  info(message: string, ...args: unknown[]): void;
+  warn(message: string, ...args: unknown[]): void;
+  error(message: string, ...args: unknown[]): void;
+}
+declare const noopLogger: ServiceMeLogger;
+declare function createConsoleLogger(prefix?: string): ServiceMeLogger;
+//#endregion
+//#region src/auth/AuthStateManager.d.ts
+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;
+}
+//#endregion
+//#region src/auth/KeychainAuthTokenStore.d.ts
+/**
+ * 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>;
+}
+//#endregion
+//#region src/auth/providers/IAuthProvider.d.ts
+/** 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.).
+   * @param initialPollIntervalMs The `pollIntervalMs` from the matching
+   *   `requestDeviceFlow()` result (per the Device Flow spec's `interval`
+   *   field). Implementations should never poll faster than this — doing
+   *   so can put the device code into a `slow_down` state that never
+   *   clears even after the user authorizes.
+   */
+  completeDeviceFlow(deviceCode: string, shouldContinue?: () => boolean, initialPollIntervalMs?: number): 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>;
+}
+//#endregion
+//#region src/auth/ProviderRegistry.d.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;
+}
+//#endregion
+//#region src/auth/AuthCore.d.ts
+interface AuthCoreOptions {
+  providers: IAuthProvider[];
+  tokenStore: KeychainAuthTokenStore;
+  accessControl?: AccessControl;
+  stateManager?: AuthStateManager;
+  /** Diagnostic logger for login/logout lifecycle events (never receives token bytes). */
+  logger?: ServiceMeLogger;
+}
+/**
+ * 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?;
+  private readonly logger;
+  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;
+}
+//#endregion
+//#region src/auth/providers/GitHubAuthProvider.d.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 back-off. Must stay generous — GitHub's
+   * `slow_down` response requires adding a fixed step to the interval each
+   * time it occurs (see `completeDeviceFlow`), and capping this too low
+   * prevents the interval from ever satisfying GitHub's actual requirement,
+   * causing a permanent `slow_down` loop that never clears even after the
+   * user authorizes.
+   */
+  maxPollIntervalMs?: number;
+  /** Fetch override (for tests + DI). */
+  fetchImpl?: typeof fetch;
+  /** Poll-delay override (for tests + DI). Defaults to a real timer-based sleep. */
+  sleepImpl?: (ms: number) => Promise<void>;
+  /** 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;
+  /**
+   * Diagnostic logger — never receives token bytes or the raw `device_code`,
+   * only user-facing codes, HTTP statuses, and poll-loop timing so callers
+   * can troubleshoot a stuck / slow device-flow login.
+   */
+  logger?: ServiceMeLogger;
+}
+declare class GitHubAuthProvider implements IAuthProvider {
+  readonly providerId: AuthProvider;
+  private readonly cfg;
+  private readonly logger;
+  private readonly sleepImpl;
+  constructor(config: GitHubAuthProviderConfig);
+  requestDeviceFlow(opts?: {
+    scope?: string;
+  }): Promise<AuthLoginResult>;
+  completeDeviceFlow(deviceCode: string, shouldContinue?: () => boolean, initialPollIntervalMs?: number): 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;
+}
+//#endregion
+//#region src/auth/providers/MicrosoftAuthProvider.d.ts
+/**
+ * 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>;
+}
+//#endregion
+//#region src/auth/utils/githubUserEmail.d.ts
+/**
+ * AuthCore — Pure local utilities for GitHub local email handling.
+ *
+ * Copied verbatim from `@serviceme/devtools-shared/src/github-user-email.ts` (15 LOC)
+ * because ADL-003 forbids Core from depending on `@serviceme/devtools-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/devtools-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;
+//#endregion
+export { KeyValueStore as A, AuthStateManagerOptions as C, AccessCheckResult as D, noopLogger as E, AccessControl as O, AuthStateManager as S, createConsoleLogger as T, KeychainAccountKey as _, MicrosoftProviderNotHostedError as a, KeychainTokenMetadata as b, AuthCore as c, DeviceFlowUiCallback as d, ProviderRegistry as f, InMemoryKeychainAuthTokenStore as g, IAuthProviderUserInfo as h, MicrosoftAuthProvider as i, OrgMembershipFetcher as j, AccessControlOptions as k, AuthCoreOptions as l, IAuthProviderSession as m, isGitHubLocalEmail as n, GitHubAuthProvider as o, IAuthProvider as p, resolvePrimaryEmail as r, GitHubAuthProviderConfig as s, buildGitHubLocalEmail as t, CancellationCheck as u, KeychainAuthTokenStore as v, ServiceMeLogger as w, KeychainUnavailableError as x, KeychainTokenEnvelope as y };
+//# sourceMappingURL=index-CoA6y0MP.d.mts.map