@cortexkit/opencode-antigravity-auth 3.0.5 → 3.0.6

package/dist/types/src/common-auth-embedded/claustrum/roster.d.ts

@@ -0,0 +1,221 @@
+import { type QuotaMap, type QuotaObservation } from '../quota/index.js';
+import type { RoutingRow } from '../routing/index.js';
+import type { ClaustrumScopedAttempt, ClaustrumScopedCustody, SkippedVaultRecord, VaultCredential, VaultCredentialType, VaultInventory } from './custody.js';
+import { type DeclinedAccount } from './interlock.js';
+/**
+ * One vault account as the pool sees it. It carries no bearer material: the
+ * access token is fetched from the vault for every send. Several vault
+ * records logged into the same provider account collapse into one row, so
+ * duplicate logins never count as extra quota.
+ */
+export interface VaultRosterRow {
+    routeId: string;
+    credentialId: string;
+    credentialType: VaultCredentialType;
+    accountIdentity?: string;
+    /** Other credential ids logged into the same provider account. */
+    aliases?: string[];
+    state: string;
+    label: string;
+    email?: string;
+    orgName?: string;
+    enabled: boolean;
+    addedAt: number;
+    quota?: QuotaMap;
+    /**
+     * The vault listed this record in a form this consumer could not use, so the
+     * row is the last good projection kept as it was rather than dropped.
+     */
+    stale?: true;
+    /**
+     * The vault's latest list named no account for `credentialId`, so
+     * `accountIdentity` is the last account that credential was known to log
+     * into, kept until the vault names one again. It proves neither that the
+     * credential still logs into that account nor that it changed accounts.
+     */
+    unclaimed?: true;
+}
+export interface VaultRosterFile {
+    version: 1;
+    view?: string;
+    /**
+     * False when the vault's reply carried records this consumer could not use.
+     * An incomplete reply never removes an account it may still hold: every
+     * previous member it does not account for is kept.
+     */
+    complete: boolean;
+    /** The unusable records of an incomplete reply: a safe id and a fixed reason. */
+    rejected?: SkippedVaultRecord[];
+    rows: VaultRosterRow[];
+    declined: DeclinedAccount[];
+}
+/** How a vault credential is presented in the pool. */
+export type AccountMapper = (credential: VaultCredential) => {
+    label?: string;
+};
+export interface ProjectionOptions {
+    /** Ids already used by local rows; a vault route never takes one. */
+    reservedRouteIds?: ReadonlySet<string>;
+    /** Prefix for vault route ids, so they read differently from local ids. */
+    routePrefix?: string;
+    mapAccount?: AccountMapper;
+    now?: number;
+}
+export declare const DEFAULT_ROUTE_PREFIX = "vault:";
+/**
+ * Project the vault's list onto the previous roster. Pure: callers serialize
+ * discovery and commit. Route ids, quota and the time an account was added
+ * survive for the same account; a credential that now logs into a different
+ * known account gets a new route id and no inherited quota.
+ *
+ * A record listed without an identity keeps the last account it was known to
+ * log into (the row is marked `unclaimed`). Dropping that binding would let a
+ * later different account look like an identity learned for the first time
+ * and inherit the first account's route and quota.
+ *
+ * A reply with unusable records is incomplete: a previous member it does not
+ * account for (its record was rejected, or a rejected record has no usable id
+ * and could be any of them) is kept, as an alias of its live account or as a
+ * `stale` row. Only a complete reply removes an account.
+ */
+export declare function projectVaultRoster(previous: VaultRosterFile | undefined, inventory: VaultInventory, options?: ProjectionOptions): VaultRosterFile;
+/**
+ * The rows `/routing` selects among. Only enabled, active accounts route;
+ * a declined or cold vault account stays listed for the menu but never
+ * reaches admission.
+ */
+export declare function vaultRoutingRows(roster: VaultRosterFile | undefined): RoutingRow[];
+export declare function readVaultRoster(path: string): Promise<VaultRosterFile | undefined>;
+/** The ownership assertion available to a roster mutation callback. */
+export interface VaultRosterLockContext {
+    assertOwned: () => Promise<void>;
+}
+export interface MutateVaultRosterOptions {
+    /**
+     * Runs when the new roster is fully staged on disk, immediately before the
+     * rename that publishes it, so a caller can confirm a lease of its own at
+     * the moment of publication rather than when `change` returned. If it
+     * throws, nothing is published and the staged file is removed. The
+     * roster's own write lock is reasserted right after it.
+     */
+    beforePublish?: () => Promise<void>;
+}
+/**
+ * Read, change and write the roster under its write lock. `change` returns
+ * undefined to leave the file as it is. Call `assertOwned()` immediately
+ * before any rename performed inside `change`; if it throws, do not rename.
+ */
+export declare function mutateVaultRoster<T>(path: string, change: (current: VaultRosterFile | undefined, context: VaultRosterLockContext) => Promise<{
+    next?: VaultRosterFile;
+    result: T;
+}> | {
+    next?: VaultRosterFile;
+    result: T;
+}, options?: MutateVaultRosterOptions): Promise<T>;
+/** Mark a vault account declined; it stays listed but never routes. */
+export declare function declineVaultRoute(path: string, routeId: string): Promise<undefined>;
+/** Lift the user's decline for a vault account and every alias of it. */
+export declare function acceptVaultRoute(path: string, routeId: string): Promise<undefined>;
+/**
+ * The receipt fields a quota or profile observation must carry to say which
+ * send (credential and account) it came from. Pass the
+ * `ClaustrumScopedAttempt` that send was authorized with.
+ */
+export type QuotaReceipt = Pick<ClaustrumScopedAttempt, 'credentialId' | 'accountIdentity' | 'accountIdentitySource' | 'expectedAccountIdentity'>;
+/**
+ * Merge a quota observation into a vault row through `/quota`'s merge. The
+ * write is fenced on the receipt the reading was taken with: it lands only
+ * while the row still holds that receipt's credential (as representative or
+ * alias) and account, so a slow read for a replaced account can never land on
+ * its successor. Returns whether the observation was kept.
+ */
+export declare function recordVaultQuota(path: string, input: QuotaReceipt & {
+    routeId: string;
+    observation: QuotaObservation;
+}): Promise<boolean>;
+/**
+ * Merge a quota observation that belongs to an account rather than to a
+ * served credential, such as a background reading from insula. The write
+ * lands only while the row is still bound to that exact known account, so a
+ * reading taken before a replacement never reaches the successor. Unlike
+ * `recordVaultQuota` it never binds an account: a row without a known account
+ * is refused. Returns whether the observation was kept.
+ */
+export declare function recordVaultAccountQuota(path: string, input: {
+    routeId: string;
+    accountIdentity: string;
+    observation: QuotaObservation;
+}): Promise<boolean>;
+/**
+ * Discover and commit the roster. The lease covers the list call and the
+ * commit, not just the write: an opaque view cannot tell a delayed old reply
+ * from a newer one, so a run that lost its lease is refused at commit. A
+ * failed list, or custody switching off mid-run, never writes anything; a
+ * peer holding the lease means its last committed roster is served instead.
+ */
+export declare function refreshVaultRoster(options: {
+    path: string;
+    custody: Pick<ClaustrumScopedCustody, 'discover'>;
+    isActive?: () => boolean | Promise<boolean>;
+    signal?: AbortSignal;
+    projection?: ProjectionOptions | (() => ProjectionOptions);
+}): Promise<VaultRosterFile | undefined>;
+/**
+ * A host-owned main account as last verified from the vault: the plugin's
+ * logical route, the credential that serves it and the account it logs into.
+ */
+export interface VaultPrimaryBinding {
+    routeId: string;
+    credentialId: string;
+    accountIdentity: string;
+    view: string;
+}
+export type VaultPrimaryUnavailableReason = 'malformed' | 'unclaimed' | 'incomplete' | 'identity-changed';
+export type VaultPrimary = 
+/**
+ * Main is bound. `replaced` is the previous binding when it named a
+ * different account: everything owned by that account (quota, profile,
+ * backoff, cache affinity) must be dropped, and outstanding observations
+ * for it fenced, even though the logical route stays the same.
+ */
+{
+    status: 'ready';
+    binding: VaultPrimaryBinding;
+    replaced?: VaultPrimaryBinding;
+}
+/** A complete reply lists no primary record: there is no main. */
+ | {
+    status: 'absent';
+}
+/**
+ * The reply cannot say who main is. Not the same as absent: the last
+ * verified binding is handed back untouched, and serving it still needs a
+ * fresh receipt that matches it.
+ */
+ | {
+    status: 'unavailable';
+    reason: VaultPrimaryUnavailableReason;
+    lastVerified?: VaultPrimaryBinding;
+};
+/**
+ * The seam for a plugin that keeps a main account: one fixed account the host
+ * owns under a logical route, outside the pool's rotating rows. The library
+ * has no main convention of its own: the plugin names the
+ * vault record that holds the role (`primaryCredentialId`) and its logical
+ * route. Main follows the account that record claims; another credential of
+ * that same account may serve it when the record itself is not active, but a
+ * credential of any other account is never promoted into main.
+ *
+ * Inputs are the plugin's filtered inventory, whether that inventory is
+ * complete (defaults to the reply having no unusable records; pass the
+ * roster's `complete` or false to override), the previous verified binding
+ * and, on the request path, the account the chosen request expects.
+ */
+export declare function resolveVaultPrimary(input: {
+    inventory: VaultInventory;
+    complete?: boolean;
+    previous?: VaultPrimaryBinding;
+    expectedAccountIdentity?: string;
+    primaryCredentialId: string;
+    routeId: string;
+}): VaultPrimary;

package/dist/types/src/common-auth-embedded/opencode2/errors.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Why an OpenCode 2 auth hook refused a request.
+ *
+ * - `no-account`: the adapter had no account to offer for this request, so
+ *   the request is stopped before the host picks a transport. Also used when
+ *   session forgetting or installation disposal revokes an in-flight auth
+ *   selection: that selection no longer has an account it may send under.
+ * - `host-credential-on-wire`: after every rewrite, a header still carried
+ *   one of the host's placeholder credentials. Sending it would leak a
+ *   non-routable value to the provider and fail with a confusing error.
+ */
+export type OpenCode2AuthFailureKind = 'no-account' | 'host-credential-on-wire';
+export declare class OpenCode2AuthError extends Error {
+    readonly kind: OpenCode2AuthFailureKind;
+    readonly providerID: string;
+    readonly sessionID: string;
+    readonly requestKind: string;
+    constructor(details: {
+        kind: OpenCode2AuthFailureKind;
+        providerID: string;
+        sessionID: string;
+        requestKind: string;
+        message?: string;
+    });
+}

package/dist/types/src/common-auth-embedded/opencode2/index.d.ts

@@ -0,0 +1,8 @@
+export type { OpenCode2AuthFailureKind } from './errors.js';
+export { OpenCode2AuthError } from './errors.js';
+export { ATTEMPT_HEADER, applyHeaderEdits, DEFAULT_MAX_RECORDS, installOpenCode2Auth, } from './install.js';
+export type { FormAnswer, LoginContext, PoolAuthorization, PoolLoginMethod, RegisterOpenCode2AuthMethodsOptions, VaultActivationMethod, } from './integration.js';
+export { isPlaceholderCredential, PLACEHOLDER_LIFETIME_MS, PLACEHOLDER_METADATA_KEY, PLACEHOLDER_PREFIX, placeholderCredential, placeholderSecret, registerOpenCode2AuthMethods, VAULT_ACTIVATION_INSTRUCTIONS, } from './integration.js';
+export type { ServerSentEvent } from './sse.js';
+export { watchServerSentEvents } from './sse.js';
+export type { AccountHeadersResult, AccountRequest, Attempt, AttemptEndReason, AttemptOutcome, ChooseAccountInput, EventVerdict, HeaderEdits, HostError, InstallOpenCode2AuthOptions, LimitSignal, OpenCode2AuthAdapter, OpenCode2AuthEventName, OpenCode2AuthEvents, OpenCode2AuthInstallation, OpenCode2AuthLogger, OpenCode2HookContext, RequestKind, RequestScope, ResponseAccount, RetryReason, SelectingHook, Transport, } from './types.js';

package/dist/types/src/common-auth-embedded/opencode2/install.d.ts

@@ -0,0 +1,55 @@
+import type { HeaderEdits, InstallOpenCode2AuthOptions, OpenCode2AuthAdapter, OpenCode2AuthInstallation, OpenCode2HookContext } from './types.js';
+export declare const DEFAULT_MAX_RECORDS = 512;
+/**
+ * The request header `model.request` sets to the attempt it started. The
+ * host builds the HTTP request and the WebSocket handshake from the headers
+ * `model.request` leaves, so `http.request` and `experimental.ws.handshake`
+ * read it to find their own attempt among several of one session and kind,
+ * and remove it: it never reaches the wire.
+ */
+export declare const ATTEMPT_HEADER = "x-common-auth-attempt";
+/** Applies edits to a plain header record, replacing every spelling of each name. */
+export declare function applyHeaderEdits(target: Record<string, string>, edits: HeaderEdits): void;
+/**
+ * Installs multi-account auth on OpenCode 2's own provider drivers. Every
+ * hook is scoped to `adapter.providerID`:
+ *
+ * - `model.request` picks the account for one model call of a session and
+ *   request kind, which starts a new attempt, sets its headers and marks the
+ *   request with the attempt (`ATTEMPT_HEADER`);
+ * - `http.request` and `experimental.ws.handshake` find the attempt by that
+ *   mark, remove it and set the account headers again, because the host
+ *   applies its own credential after `model.request`;
+ * - `experimental.ws.send` (only when the adapter rewrites frames) rewrites
+ *   each outgoing frame;
+ * - `http.response` and `experimental.ws.receive` read quota, refusals,
+ *   whether output has started and when the response ended, attributed to
+ *   an attempt by the rules below;
+ * - `retry` asks the host to retry at once when an account was refused
+ *   before any output, so `model.request` runs again and can pick another
+ *   account, and refuses to retry once output has started.
+ *
+ * Attribution. A send belongs to the attempt named by the mark
+ * `model.request` left on it, so several attempts of one session and kind
+ * can be in flight at once, each on its own account. An HTTP response
+ * belongs to the attempt whose `http.request` produced its request object,
+ * and to nothing else. The host hands `http.response` the request object the
+ * `http.request` hooks left, so a different object means a later hook
+ * replaced it; nothing then proves which send the response answers, and its
+ * feedback is dropped rather than guessed by recency. A WebSocket frame
+ * names no attempt, so frames go to the newest open attempt of their session
+ * and kind that went out over WebSocket, and an older one is abandoned as
+ * soon as a newer attempt of that session and kind begins or goes out over
+ * WebSocket: the host runs one exchange at a time on a session's socket.
+ * Anything else is attributed to no attempt and reaches no adapter callback
+ * or listener.
+ *
+ * With `gateOnPlaceholder`, `model.request` is a no-op. Each transport hook
+ * compares the host-prepared secret exactly, then selects a fresh attempt only
+ * for an owned send. Request-object attribution therefore needs no attempt
+ * header. Frames are owned by the latest handshake of their session and kind;
+ * retry runs only when the session's latest transport was owned. The host's
+ * retry hook has no request identity, so concurrent mixed-ownership calls
+ * cannot be distinguished there; owned retries retain the heuristic above.
+ */
+export declare function installOpenCode2Auth<Q, A = unknown>(ctx: OpenCode2HookContext, adapter: OpenCode2AuthAdapter<Q, A>, options?: InstallOpenCode2AuthOptions): Promise<OpenCode2AuthInstallation<Q, A>>;

package/dist/types/src/common-auth-embedded/opencode2/integration.d.ts

@@ -0,0 +1,112 @@
+import type { Credential, Plugin } from '@opencode/plugin';
+import type { IntegrationOAuthMethod, IntegrationOAuthMethodRegistration } from '@opencode/plugin/promise/integration';
+import type { Registration } from '@opencode/plugin/promise/registration';
+/** The host's form answer handed to `authorize`. */
+export type FormAnswer = Parameters<IntegrationOAuthMethodRegistration['authorize']>[0];
+/**
+ * Prefix of every placeholder secret. No provider issues tokens of this
+ * shape, so a placeholder that escaped to the wire is refused by the
+ * provider and recognisable in any log.
+ */
+export declare const PLACEHOLDER_PREFIX = "common-auth-placeholder";
+/** How long a placeholder claims to be valid; refresh simply issues another. */
+export declare const PLACEHOLDER_LIFETIME_MS: number;
+/** Metadata key marking a host credential as a placeholder. */
+export declare const PLACEHOLDER_METADATA_KEY = "commonAuthPlaceholder";
+/** The non-routable secret the host holds for an integration. */
+export declare function placeholderSecret(integrationID: string): string;
+/**
+ * The credential the host stores for an integration whose real accounts live
+ * in the plugin's pool. It keeps the provider catalogued and usable in the
+ * host, and carries nothing that works against the provider.
+ */
+export declare function placeholderCredential(input: {
+    integrationID: string;
+    methodID: string;
+    now: number;
+}): Credential.OAuth;
+/** Whether a host credential is a placeholder (for any integration, or the one named). */
+export declare function isPlaceholderCredential(value: Credential.Value | undefined, integrationID?: string): boolean;
+/**
+ * The plugin's half of an OAuth login. It has the same shape as the host's
+ * authorization, except that `callback` resolves to the plugin's own login
+ * result instead of a host credential.
+ */
+export type PoolAuthorization<T> = {
+    readonly url: string;
+    readonly instructions: string;
+    readonly expiresAt?: number;
+} & ({
+    readonly mode: 'auto';
+    readonly callback: Promise<T>;
+} | {
+    readonly mode: 'code';
+    readonly callback: (code: string) => Promise<T>;
+});
+export interface PoolLoginMethod<T> {
+    readonly method: IntegrationOAuthMethod;
+    authorize(answer: FormAnswer): Promise<PoolAuthorization<T>>;
+}
+/** What `activate` and `onLogin` are told about the login they serve. */
+export interface LoginContext {
+    readonly integrationID: string;
+    readonly methodID: string;
+}
+/**
+ * Shown by `opencode auth login` when the vault method starts. The host has no
+ * page to open for this method, so the text only says what happens instead.
+ */
+export declare const VAULT_ACTIVATION_INSTRUCTIONS = "No browser sign-in: this connects the plugin to the accounts in its vault.";
+/**
+ * A login method for a host whose accounts all come from a vault. Choosing it
+ * signs in to nothing and writes nothing to the plugin's pool: once
+ * `activate` resolves, the host only receives this integration's placeholder,
+ * which marks later requests as the plugin's to serve from the vault.
+ */
+export interface VaultActivationMethod {
+    /** Must not share an ID with any of the pool login methods. */
+    readonly method: IntegrationOAuthMethod;
+    /**
+     * Confirms the host may use this method, normally by checking that
+     * `enrollmentAuthority` reports `'vault'`. Throw to refuse: the host shows
+     * the error's message and stores nothing, so it must be a fixed text that
+     * carries no credential.
+     */
+    activate(context: LoginContext): Promise<void> | void;
+    /** Replaces `VAULT_ACTIVATION_INSTRUCTIONS`. */
+    readonly instructions?: string;
+}
+export interface RegisterOpenCode2AuthMethodsOptions<T> {
+    readonly integrationID: string;
+    readonly methods: readonly PoolLoginMethod<T>[];
+    /**
+     * Adds a login method that activates the plugin for vault accounts without
+     * creating a local account. Leave it out when the plugin has no vault.
+     */
+    readonly vault?: VaultActivationMethod;
+    /**
+     * Writes a completed login into the plugin's pool. The host only receives
+     * a placeholder once this resolves; if it throws, the login fails in the
+     * host and nothing is stored there.
+     */
+    onLogin(result: T, context: LoginContext): Promise<void> | void;
+    /** Label the host shows for its (placeholder) connection. */
+    readonly label?: string;
+    readonly now?: () => number;
+}
+/**
+ * Registers the plugin's own login methods with the host so that a login lands
+ * in the plugin's pool and the host keeps only a placeholder credential.
+ *
+ * With `vault`, one more method lets a host whose accounts all live in a vault
+ * activate the plugin: it calls `activate`, writes nothing to the pool and
+ * hands the host the same placeholder under its own method ID.
+ *
+ * Host-driven refresh never reaches the pool: it renews only this integration's
+ * placeholder and refuses every other credential without replacing it. Plugins
+ * must register under their own method IDs; a plugin importing an existing
+ * host login should read it through `ctx.integration.connection` instead.
+ */
+export declare function registerOpenCode2AuthMethods<T>(ctx: {
+    readonly integration: Pick<Plugin.Context['integration'], 'transform'>;
+}, options: RegisterOpenCode2AuthMethodsOptions<T>): Promise<Registration>;

package/dist/types/src/common-auth-embedded/opencode2/sse.d.ts

@@ -0,0 +1,12 @@
+/** One server-sent event: its `event:` name, if any, and its joined `data:` lines. */
+export interface ServerSentEvent {
+    readonly event?: string;
+    readonly data: string;
+}
+/**
+ * A pass-through stream that hands every complete server-sent event to
+ * `onEvent` while forwarding the original bytes unchanged, so the host still
+ * consumes the body exactly once. A throwing `onEvent` is reported to
+ * `onError` and never breaks the stream.
+ */
+export declare function watchServerSentEvents(onEvent: (event: ServerSentEvent) => void, onError: (error: unknown) => void): TransformStream<Uint8Array, Uint8Array>;