@cortexkit/common-auth 0.2.7 → 0.2.8

package/dist/opencode2/errors.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 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.
+ * - `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/opencode2/errors.js

@@ -0,0 +1,15 @@
+export class OpenCode2AuthError extends Error {
+    kind;
+    providerID;
+    sessionID;
+    requestKind;
+    constructor(details) {
+        super(details.message ??
+            `${details.providerID} ${details.requestKind} request refused (${details.kind})`);
+        this.name = 'OpenCode2AuthError';
+        this.kind = details.kind;
+        this.providerID = details.providerID;
+        this.sessionID = details.sessionID;
+        this.requestKind = details.requestKind;
+    }
+}

package/dist/opencode2/index.d.ts

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

package/dist/opencode2/index.js

@@ -1,2 +1,4 @@
-// Placeholder so the export resolves until this subpath is built.
-export {};
+export { OpenCode2AuthError } from './errors.js';
+export { applyHeaderEdits, DEFAULT_MAX_RECORDS, installOpenCode2Auth, } from './install.js';
+export { isPlaceholderCredential, PLACEHOLDER_LIFETIME_MS, PLACEHOLDER_METADATA_KEY, PLACEHOLDER_PREFIX, placeholderCredential, placeholderSecret, registerOpenCode2AuthMethods, } from './integration.js';
+export { watchServerSentEvents } from './sse.js';

package/dist/opencode2/install.d.ts

@@ -0,0 +1,19 @@
+import type { HeaderEdits, InstallOpenCode2AuthOptions, OpenCode2AuthAdapter, OpenCode2AuthInstallation, OpenCode2HookContext } from './types.js';
+export declare const DEFAULT_MAX_RECORDS = 512;
+/** 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 the request's `sessionID:kind` and
+ *   sets its headers;
+ * - `http.request` and `experimental.ws.handshake` set them again, because
+ *   the host applies its own credential after `model.request`;
+ * - `http.response` and `experimental.ws.receive` read quota, refusals and
+ *   whether output has started, attributed through the record above;
+ * - `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.
+ */
+export declare function installOpenCode2Auth<Q>(ctx: OpenCode2HookContext, adapter: OpenCode2AuthAdapter<Q>, options?: InstallOpenCode2AuthOptions): Promise<OpenCode2AuthInstallation<Q>>;

package/dist/opencode2/install.js

@@ -0,0 +1,415 @@
+import { OpenCode2AuthError } from './errors.js';
+import { placeholderSecret } from './integration.js';
+import { watchServerSentEvents } from './sse.js';
+export const DEFAULT_MAX_RECORDS = 512;
+const keyOf = (sessionID, kind) => JSON.stringify([sessionID, kind]);
+const scopeOf = (draft) => ({
+    providerID: draft.model.providerID,
+    modelID: draft.model.id,
+    sessionID: draft.sessionID,
+    agent: draft.agent,
+    kind: draft.kind,
+});
+/** Applies edits to a plain header record, replacing every spelling of each name. */
+export function applyHeaderEdits(target, edits) {
+    for (const [name, value] of Object.entries(edits)) {
+        const lower = name.toLowerCase();
+        for (const existing of Object.keys(target)) {
+            if (existing.toLowerCase() === lower)
+                delete target[existing];
+        }
+        if (value !== null)
+            target[name] = value;
+    }
+}
+function applyHeaderEditsTo(target, edits) {
+    for (const [name, value] of Object.entries(edits)) {
+        if (value === null)
+            target.delete(name);
+        else
+            target.set(name, value);
+    }
+}
+/**
+ * Installs multi-account auth on OpenCode 2's own provider drivers. Every
+ * hook is scoped to `adapter.providerID`:
+ *
+ * - `model.request` picks the account for the request's `sessionID:kind` and
+ *   sets its headers;
+ * - `http.request` and `experimental.ws.handshake` set them again, because
+ *   the host applies its own credential after `model.request`;
+ * - `http.response` and `experimental.ws.receive` read quota, refusals and
+ *   whether output has started, attributed through the record above;
+ * - `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.
+ */
+export async function installOpenCode2Auth(ctx, adapter, options = {}) {
+    const { providerID } = adapter;
+    const logger = options.logger;
+    const maxRecords = Math.max(1, options.maxRecords ?? DEFAULT_MAX_RECORDS);
+    const forbidden = (options.hostCredentials ?? [placeholderSecret(providerID)]).filter((value) => value !== '');
+    const records = new Map();
+    const byRequest = new WeakMap();
+    const listeners = new Map();
+    let seq = 0;
+    const warn = (message, data) => {
+        try {
+            logger?.warn(message, data);
+        }
+        catch { }
+    };
+    const describe = (error) => error instanceof Error ? error.message : String(error);
+    const emit = async (event, payload) => {
+        const set = listeners.get(event);
+        if (!set || set.size === 0)
+            return;
+        await Promise.all([...set].map(async (listener) => {
+            try {
+                await listener(payload);
+            }
+            catch (error) {
+                warn('opencode2 auth listener threw; the request is unaffected', {
+                    event,
+                    error: describe(error),
+                });
+            }
+        }));
+    };
+    const remember = (rec) => {
+        const key = keyOf(rec.scope.sessionID, rec.scope.kind);
+        records.delete(key);
+        records.set(key, rec);
+        while (records.size > maxRecords) {
+            const oldest = records.keys().next().value;
+            if (oldest === undefined)
+                break;
+            records.delete(oldest);
+        }
+    };
+    const accountOf = (rec) => rec.accountId === undefined
+        ? undefined
+        : { ...rec.scope, accountId: rec.accountId };
+    const noAccount = (scope) => new OpenCode2AuthError({
+        kind: 'no-account',
+        providerID,
+        sessionID: scope.sessionID,
+        requestKind: scope.kind,
+    });
+    const guard = (scope, headers) => {
+        for (const [name, value] of headers) {
+            if (forbidden.some((secret) => value.includes(secret))) {
+                throw new OpenCode2AuthError({
+                    kind: 'host-credential-on-wire',
+                    providerID,
+                    sessionID: scope.sessionID,
+                    requestKind: scope.kind,
+                    message: `${providerID} ${scope.kind} request still carries the host's placeholder credential in ${name}; the adapter's account headers must replace it`,
+                });
+            }
+        }
+    };
+    const select = async (scope, hook) => {
+        const prior = records.get(keyOf(scope.sessionID, scope.kind));
+        const input = {
+            ...scope,
+            ...(prior?.accountId === undefined
+                ? {}
+                : { previousAccountId: prior.accountId }),
+            ...(prior?.rerouteFrom === undefined
+                ? {}
+                : { rerouteFrom: prior.rerouteFrom }),
+        };
+        const accountId = await adapter.chooseAccount(input);
+        const headers = accountId === undefined
+            ? {}
+            : await adapter.accountHeaders({ ...scope, accountId });
+        const rec = {
+            scope,
+            accountId,
+            headers,
+            seq: ++seq,
+            outputStarted: false,
+        };
+        remember(rec);
+        if (accountId !== undefined) {
+            void emit('select', {
+                ...scope,
+                accountId,
+                hook,
+                ...(input.previousAccountId === undefined
+                    ? {}
+                    : { previousAccountId: input.previousAccountId }),
+                ...(input.rerouteFrom === undefined
+                    ? {}
+                    : { rerouteFrom: input.rerouteFrom }),
+            });
+        }
+        return rec;
+    };
+    // The transport hooks normally follow `model.request`; choosing here too
+    // keeps a request that skipped it from going out under the host credential.
+    const ensure = async (scope, hook) => records.get(keyOf(scope.sessionID, scope.kind)) ??
+        (await select(scope, hook));
+    const noteLimit = (rec, signal, via) => {
+        const account = accountOf(rec);
+        if (!account || rec.limit)
+            return;
+        rec.limit = {
+            signal,
+            delivered: emit('limit', {
+                ...account,
+                via,
+                limit: signal,
+                outputStarted: rec.outputStarted,
+            }),
+        };
+    };
+    const noteQuota = (rec, transport, quota, status) => {
+        const account = accountOf(rec);
+        if (!account)
+            return;
+        void emit('quota', {
+            ...account,
+            transport,
+            ...(status === undefined ? {} : { status }),
+            quota,
+        });
+    };
+    const inspect = (rec, transport, data, event) => {
+        const verdict = adapter.inspectEvent?.(event === undefined ? { transport, data } : { transport, data, event });
+        if (!verdict)
+            return;
+        if (verdict.quota !== undefined)
+            noteQuota(rec, transport, verdict.quota);
+        if (verdict.outputStarted)
+            rec.outputStarted = true;
+        if (verdict.limit)
+            noteLimit(rec, verdict.limit, transport);
+    };
+    const pickForRetry = (sessionID) => {
+        let refused;
+        let primary;
+        let latest;
+        for (const rec of records.values()) {
+            if (rec.scope.sessionID !== sessionID)
+                continue;
+            if (!latest || rec.seq > latest.seq)
+                latest = rec;
+            if (rec.scope.kind === 'primary')
+                primary = rec;
+            if (rec.limit && !rec.rerouteFrom && (!refused || rec.seq > refused.seq))
+                refused = rec;
+        }
+        return refused ?? primary ?? latest;
+    };
+    const scoped = { providerID };
+    const registrations = [
+        await ctx.session.hook('model.request', async (draft) => {
+            const rec = await select(scopeOf(draft), 'model.request');
+            if (rec.accountId === undefined)
+                throw noAccount(rec.scope);
+            applyHeaderEdits(draft.headers, rec.headers);
+        }, scoped),
+        await ctx.session.hook('http.request', async (draft) => {
+            const rec = await ensure(scopeOf(draft), 'http.request');
+            const account = accountOf(rec);
+            if (!account)
+                throw noAccount(rec.scope);
+            let request = draft.request;
+            if (adapter.rewriteRequest) {
+                request =
+                    (await adapter.rewriteRequest({ ...account, request })) ?? request;
+            }
+            const headers = new Headers(request.headers);
+            applyHeaderEditsTo(headers, rec.headers);
+            guard(rec.scope, headers.entries());
+            const final = new Request(request, { headers });
+            byRequest.set(final, rec);
+            draft.request = final;
+        }, scoped),
+        await ctx.session.hook('http.response', async (draft) => {
+            const rec = byRequest.get(draft.request) ??
+                records.get(keyOf(draft.sessionID, draft.kind));
+            const account = rec && accountOf(rec);
+            if (!rec || !account)
+                return;
+            const original = draft.response;
+            const quota = adapter.quotaFromHeaders?.(original.headers, original.status);
+            if (quota !== undefined)
+                noteQuota(rec, 'http', quota, original.status);
+            if (!original.ok && adapter.limitFromResponse) {
+                const signal = await adapter.limitFromResponse({
+                    status: original.status,
+                    headers: original.headers,
+                    body: () => original.clone().text(),
+                });
+                if (signal)
+                    noteLimit(rec, signal, 'http');
+            }
+            let response = original;
+            if (original.body && adapter.inspectEvent) {
+                const watch = watchServerSentEvents((event) => inspect(rec, 'http', event.data, event.event), (error) => warn('opencode2 auth event inspection threw', {
+                    error: describe(error),
+                }));
+                response = new Response(original.body.pipeThrough(watch), {
+                    status: original.status,
+                    statusText: original.statusText,
+                    headers: original.headers,
+                });
+            }
+            if (adapter.rewriteResponse) {
+                response =
+                    (await adapter.rewriteResponse({
+                        ...account,
+                        request: draft.request,
+                        response,
+                    })) ?? response;
+            }
+            if (response !== original)
+                draft.response = response;
+        }, scoped),
+        await ctx.session.hook('experimental.ws.handshake', async (draft) => {
+            const rec = await ensure(scopeOf(draft), 'experimental.ws.handshake');
+            const account = accountOf(rec);
+            if (!account)
+                throw noAccount(rec.scope);
+            applyHeaderEdits(draft.headers, rec.headers);
+            const url = adapter.rewriteHandshakeURL?.({
+                ...account,
+                url: draft.url,
+            });
+            if (url !== undefined)
+                draft.url = url;
+            guard(rec.scope, Object.entries(draft.headers));
+        }, scoped),
+        await ctx.session.hook('experimental.ws.receive', (draft) => {
+            const rec = records.get(keyOf(draft.sessionID, draft.kind));
+            if (!rec || rec.accountId === undefined)
+                return;
+            try {
+                inspect(rec, 'ws', draft.frame);
+            }
+            catch (error) {
+                warn('opencode2 auth frame inspection threw', {
+                    error: describe(error),
+                });
+            }
+        }, scoped),
+        await ctx.session.hook('retry', async (draft) => {
+            const rec = pickForRetry(draft.sessionID);
+            if (!rec)
+                return;
+            const hostDecision = draft.decision;
+            let decision = hostDecision;
+            let reason;
+            if (rec.accountId === undefined) {
+                decision = { retry: false };
+                reason = 'no-account';
+            }
+            else if (rec.outputStarted) {
+                // The user has already seen part of this answer; a retry would
+                // send it again.
+                decision = { retry: false };
+                reason = 'output-started';
+            }
+            else {
+                if (!rec.limit) {
+                    const signal = adapter.limitFromError?.(draft.error);
+                    if (signal)
+                        noteLimit(rec, signal, 'error');
+                }
+                if (rec.limit) {
+                    await rec.limit.delivered;
+                    rec.rerouteFrom = {
+                        accountId: rec.accountId,
+                        limit: rec.limit.signal,
+                    };
+                    // No delay: the next attempt goes to another account, and the
+                    // host would otherwise wait out the refused account's backoff,
+                    // or not retry at all for errors it deems final.
+                    decision = { retry: true, delay: 0 };
+                    reason = 'reroute';
+                }
+                else {
+                    reason = 'host-decides';
+                }
+            }
+            draft.decision = decision;
+            await emit('retry', {
+                sessionID: draft.sessionID,
+                ...(rec.accountId === undefined ? {} : { accountId: rec.accountId }),
+                kind: rec.scope.kind,
+                attempt: draft.attempt,
+                reason,
+                hostDecision,
+                decision,
+            });
+        }, scoped),
+    ];
+    const forgetSession = (sessionID) => {
+        for (const [key, rec] of records) {
+            if (rec.scope.sessionID === sessionID)
+                records.delete(key);
+        }
+    };
+    const abort = new AbortController();
+    const events = ctx.event;
+    if (events) {
+        void (async () => {
+            try {
+                for await (const event of events.subscribe({ signal: abort.signal })) {
+                    if (event.type === 'session.deleted')
+                        forgetSession(event.data.sessionID);
+                }
+            }
+            catch (error) {
+                if (!abort.signal.aborted) {
+                    warn('opencode2 auth stopped listening for session deletion', {
+                        error: describe(error),
+                    });
+                }
+            }
+        })();
+    }
+    let disposed = false;
+    return {
+        on(event, listener) {
+            let set = listeners.get(event);
+            if (!set) {
+                set = new Set();
+                listeners.set(event, set);
+            }
+            const entry = listener;
+            set.add(entry);
+            return () => {
+                set.delete(entry);
+            };
+        },
+        accountFor(sessionID, kind) {
+            return records.get(keyOf(sessionID, kind))?.accountId;
+        },
+        forgetSession,
+        get size() {
+            return records.size;
+        },
+        async dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            abort.abort();
+            records.clear();
+            listeners.clear();
+            await Promise.all(registrations.map(async (registration) => {
+                try {
+                    await registration.dispose();
+                }
+                catch (error) {
+                    warn('opencode2 auth hook did not dispose cleanly', {
+                        error: describe(error),
+                    });
+                }
+            }));
+        },
+    };
+}

package/dist/opencode2/integration.d.ts

@@ -0,0 +1,78 @@
+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>>;
+}
+export interface RegisterOpenCode2AuthMethodsOptions<T> {
+    readonly integrationID: string;
+    readonly methods: readonly PoolLoginMethod<T>[];
+    /**
+     * 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: {
+        readonly integrationID: string;
+        readonly methodID: string;
+    }): Promise<void> | void;
+    /** Label the host shows for its (placeholder) connection. */
+    readonly label?: string;
+    readonly now?: () => number;
+}
+/**
+ * Registers the plugin's login methods with the host so that a login lands in
+ * the plugin's pool and the host keeps only a placeholder credential.
+ *
+ * Host-driven refresh never reaches the pool: it hands back a fresh
+ * placeholder whatever it is given. A real credential stored by an earlier
+ * login under one of these method IDs is therefore replaced by a placeholder
+ * at its first refresh; a plugin that wants to import such a login must read
+ * it (`ctx.integration.connection`) before that happens.
+ */
+export declare function registerOpenCode2AuthMethods<T>(ctx: {
+    readonly integration: Pick<Plugin.Context['integration'], 'transform'>;
+}, options: RegisterOpenCode2AuthMethodsOptions<T>): Promise<Registration>;

package/dist/opencode2/integration.js

@@ -0,0 +1,94 @@
+/**
+ * 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 const PLACEHOLDER_PREFIX = 'common-auth-placeholder';
+/** How long a placeholder claims to be valid; refresh simply issues another. */
+export const PLACEHOLDER_LIFETIME_MS = 365 * 24 * 60 * 60 * 1000;
+/** Metadata key marking a host credential as a placeholder. */
+export const PLACEHOLDER_METADATA_KEY = 'commonAuthPlaceholder';
+/** The non-routable secret the host holds for an integration. */
+export function placeholderSecret(integrationID) {
+    return `${PLACEHOLDER_PREFIX}.${integrationID}`;
+}
+/**
+ * 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 function placeholderCredential(input) {
+    const secret = placeholderSecret(input.integrationID);
+    return {
+        type: 'oauth',
+        methodID: input.methodID,
+        access: secret,
+        refresh: secret,
+        expires: input.now + PLACEHOLDER_LIFETIME_MS,
+        metadata: { [PLACEHOLDER_METADATA_KEY]: true },
+    };
+}
+/** Whether a host credential is a placeholder (for any integration, or the one named). */
+export function isPlaceholderCredential(value, integrationID) {
+    if (value?.type !== 'oauth')
+        return false;
+    const expected = integrationID === undefined ? undefined : placeholderSecret(integrationID);
+    const matches = (secret) => expected === undefined
+        ? secret.startsWith(`${PLACEHOLDER_PREFIX}.`)
+        : secret === expected;
+    return matches(value.access) && matches(value.refresh);
+}
+/**
+ * Registers the plugin's login methods with the host so that a login lands in
+ * the plugin's pool and the host keeps only a placeholder credential.
+ *
+ * Host-driven refresh never reaches the pool: it hands back a fresh
+ * placeholder whatever it is given. A real credential stored by an earlier
+ * login under one of these method IDs is therefore replaced by a placeholder
+ * at its first refresh; a plugin that wants to import such a login must read
+ * it (`ctx.integration.connection`) before that happens.
+ */
+export async function registerOpenCode2AuthMethods(ctx, options) {
+    const now = options.now ?? Date.now;
+    const { integrationID } = options;
+    const placeholderFor = (methodID) => placeholderCredential({ integrationID, methodID, now: now() });
+    const store = async (result, methodID) => {
+        await options.onLogin(result, { integrationID, methodID });
+        return placeholderFor(methodID);
+    };
+    const authorizeWith = (login) => async (answer) => {
+        const methodID = login.method.id;
+        const pending = await login.authorize(answer);
+        const common = {
+            url: pending.url,
+            instructions: pending.instructions,
+            ...(pending.expiresAt === undefined
+                ? {}
+                : { expiresAt: pending.expiresAt }),
+        };
+        if (pending.mode === 'auto') {
+            return {
+                ...common,
+                mode: 'auto',
+                callback: pending.callback.then((result) => store(result, methodID)),
+            };
+        }
+        const callback = pending.callback;
+        return {
+            ...common,
+            mode: 'code',
+            callback: async (code) => store(await callback(code), methodID),
+        };
+    };
+    return ctx.integration.transform((editor) => {
+        for (const login of options.methods) {
+            editor.method.update({
+                integrationID,
+                method: login.method,
+                authorize: authorizeWith(login),
+                refresh: async (credential) => placeholderFor(credential.methodID),
+                ...(options.label === undefined ? {} : { label: () => options.label }),
+            });
+        }
+    });
+}

package/dist/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>;

package/dist/opencode2/sse.js

@@ -0,0 +1,60 @@
+function parseBlock(block) {
+    const data = [];
+    let event;
+    for (const line of block.split(/\r?\n/)) {
+        if (line.startsWith('data:'))
+            data.push(line.slice(5).replace(/^ /, ''));
+        else if (line.startsWith('event:'))
+            event = line.slice(6).trim();
+    }
+    if (data.length === 0)
+        return undefined;
+    return event === undefined
+        ? { data: data.join('\n') }
+        : { event, data: data.join('\n') };
+}
+/**
+ * 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 function watchServerSentEvents(onEvent, onError) {
+    const decoder = new TextDecoder();
+    let buffer = '';
+    const emit = (block) => {
+        const event = parseBlock(block);
+        if (!event)
+            return;
+        try {
+            onEvent(event);
+        }
+        catch (error) {
+            onError(error);
+        }
+    };
+    const drain = () => {
+        for (;;) {
+            const match = /\r?\n\r?\n/.exec(buffer);
+            if (!match)
+                return;
+            const block = buffer.slice(0, match.index);
+            buffer = buffer.slice(match.index + match[0].length);
+            emit(block);
+        }
+    };
+    return new TransformStream({
+        transform(chunk, controller) {
+            controller.enqueue(chunk);
+            buffer += decoder.decode(chunk, { stream: true });
+            drain();
+        },
+        flush() {
+            buffer += decoder.decode();
+            drain();
+            if (buffer.trim() !== '')
+                emit(buffer);
+            buffer = '';
+        },
+    });
+}

package/dist/opencode2/types.d.ts

@@ -0,0 +1,202 @@
+import type { Plugin } from '@opencode/plugin';
+import type { SessionRequestKind, SessionRetryDecision } from '@opencode/plugin/promise/session';
+/** The parts of the OpenCode 2 plugin context the installer uses. */
+export type OpenCode2HookContext = {
+    readonly session: Pick<Plugin.Context['session'], 'hook'>;
+    /** Used only to forget per-session records when a session is deleted. */
+    readonly event?: Pick<Plugin.Context['event'], 'subscribe'>;
+};
+export type RequestKind = SessionRequestKind;
+/** Which request a hook call belongs to, as the host reports it. */
+export interface RequestScope {
+    readonly providerID: string;
+    readonly modelID: string;
+    readonly sessionID: string;
+    readonly agent: string;
+    readonly kind: RequestKind;
+}
+/** Where a reading or a refusal was seen. */
+export type Transport = 'http' | 'ws';
+/**
+ * A provider refusal that should move the request to another account: a rate
+ * limit, an exhausted usage window, or anything else the adapter decides is
+ * tied to the account rather than to the request.
+ */
+export interface LimitSignal {
+    /** Short machine-readable reason, such as the provider's error code. */
+    readonly reason: string;
+    readonly status?: number;
+    /** How long the provider asked the account to wait, when it said. */
+    readonly retryAfterMs?: number;
+}
+/** What the adapter learned from one streamed event or WebSocket frame. */
+export interface EventVerdict<Q> {
+    /** The user has seen output from this response: a retry would repeat it. */
+    readonly outputStarted?: boolean;
+    readonly quota?: Q;
+    readonly limit?: LimitSignal;
+}
+/**
+ * Header changes for one account. A string sets the header (replacing every
+ * spelling of its name); `null` removes it.
+ */
+export type HeaderEdits = Readonly<Record<string, string | null>>;
+export interface ChooseAccountInput extends RequestScope {
+    /** The account the previous attempt of this session and kind used. */
+    readonly previousAccountId?: string;
+    /**
+     * Set when the previous attempt was refused for a limit before any output
+     * and the retry hook asked the host to try again. The adapter should not
+     * pick `accountId` again unless it has nothing else.
+     */
+    readonly rerouteFrom?: {
+        readonly accountId: string;
+        readonly limit: LimitSignal;
+    };
+}
+export interface AccountRequest extends RequestScope {
+    readonly accountId: string;
+}
+/** A host-supplied error, as the retry hook reports it. */
+export interface HostError {
+    readonly type: string;
+    readonly message: string;
+    readonly status?: number;
+}
+/**
+ * Everything provider-specific the installer needs. `Q` is the plugin's own
+ * quota reading type; the installer only carries it to the `quota` event.
+ */
+export interface OpenCode2AuthAdapter<Q = unknown> {
+    /** Every hook is scoped to this provider; other providers are untouched. */
+    readonly providerID: string;
+    /**
+     * Picks the account for one model request. Called again for every retry,
+     * so a refused account can be skipped. Returning `undefined` stops the
+     * request with `OpenCode2AuthError` kind `no-account`.
+     */
+    chooseAccount(input: ChooseAccountInput): Promise<string | undefined> | string | undefined;
+    /**
+     * The credential and per-account headers for an account, applied in
+     * `model.request`, `http.request` and `experimental.ws.handshake`. The last
+     * two run after the host has applied its own credential, so these headers
+     * win on the wire.
+     */
+    accountHeaders(input: AccountRequest): Promise<HeaderEdits> | HeaderEdits;
+    /**
+     * Optional request rewrite (URL, body) before the account headers are
+     * applied. Return `undefined` to keep the request.
+     */
+    rewriteRequest?(input: AccountRequest & {
+        readonly request: Request;
+    }): Promise<Request | undefined> | Request | undefined;
+    /**
+     * Optional response rewrite (body stream, status). It receives the
+     * response after quota, limit and output detection have been attached, so
+     * detection always sees the provider's own events.
+     */
+    rewriteResponse?(input: AccountRequest & {
+        readonly request: Request;
+        readonly response: Response;
+    }): Promise<Response | undefined> | Response | undefined;
+    /** Optional WebSocket URL rewrite. Return `undefined` to keep the URL. */
+    rewriteHandshakeURL?(input: AccountRequest & {
+        readonly url: string;
+    }): string | undefined;
+    /** Quota carried in HTTP response headers. */
+    quotaFromHeaders?(headers: Headers, status: number): Q | undefined;
+    /**
+     * Recognises an account-level refusal from an HTTP response before its
+     * body is streamed. `body()` reads a copy, so the host still gets the body.
+     */
+    limitFromResponse?(input: {
+        readonly status: number;
+        readonly headers: Headers;
+        readonly body: () => Promise<string>;
+    }): Promise<LimitSignal | undefined> | LimitSignal | undefined;
+    /**
+     * Inspects one server-sent event (`data` payload) or one WebSocket frame.
+     * Detects output, quota and refusals inside the stream.
+     */
+    inspectEvent?(input: {
+        readonly transport: Transport;
+        readonly data: string;
+        readonly event?: string;
+    }): EventVerdict<Q> | undefined;
+    /**
+     * Recognises an account-level refusal from the error the host hands the
+     * retry hook, for refusals no other hook saw.
+     */
+    limitFromError?(error: HostError): LimitSignal | undefined;
+}
+export interface OpenCode2AuthLogger {
+    warn(message: string, data?: unknown): void;
+}
+export interface InstallOpenCode2AuthOptions {
+    /**
+     * Values that must never reach the wire, normally the placeholder the host
+     * holds as its credential. Defaults to the placeholder secret for the
+     * adapter's provider.
+     */
+    readonly hostCredentials?: readonly string[];
+    /** Most `sessionID:kind` records kept before the oldest is dropped. */
+    readonly maxRecords?: number;
+    readonly logger?: OpenCode2AuthLogger;
+}
+export type RetryReason = 'reroute' | 'output-started' | 'no-account' | 'host-decides';
+/**
+ * The hook that picked an account. Normally `model.request`; a transport hook
+ * picks only when the host skipped `model.request` for that request, which a
+ * plugin may want to log as a host change.
+ */
+export type SelectingHook = 'model.request' | 'http.request' | 'experimental.ws.handshake';
+export interface OpenCode2AuthEvents<Q> {
+    /** An account was picked for a model request. */
+    readonly select: AccountRequest & {
+        readonly hook: SelectingHook;
+        readonly previousAccountId?: string;
+        readonly rerouteFrom?: ChooseAccountInput['rerouteFrom'];
+    };
+    /** A quota reading, attributed through this installer's own record. */
+    readonly quota: AccountRequest & {
+        readonly transport: Transport;
+        readonly status?: number;
+        readonly quota: Q;
+    };
+    /**
+     * An account-level refusal. The retry hook waits for every listener of
+     * this event before asking the host to retry, so a plugin that marks the
+     * account limited here has the mark in place when `chooseAccount` runs.
+     */
+    readonly limit: AccountRequest & {
+        readonly via: Transport | 'error';
+        readonly limit: LimitSignal;
+        readonly outputStarted: boolean;
+    };
+    /** The retry hook ran for this provider. */
+    readonly retry: {
+        readonly sessionID: string;
+        readonly accountId?: string;
+        readonly kind?: RequestKind;
+        readonly attempt: number;
+        readonly reason: RetryReason;
+        readonly hostDecision: SessionRetryDecision;
+        readonly decision: SessionRetryDecision;
+    };
+}
+export type OpenCode2AuthEventName = keyof OpenCode2AuthEvents<unknown>;
+export interface OpenCode2AuthInstallation<Q> {
+    /**
+     * Listens to an event. Listener errors are logged and never reach the
+     * host. Returns a function that removes the listener.
+     */
+    on<E extends OpenCode2AuthEventName>(event: E, listener: (payload: OpenCode2AuthEvents<Q>[E]) => void | Promise<void>): () => void;
+    /** The account last chosen for a session and request kind. */
+    accountFor(sessionID: string, kind: RequestKind): string | undefined;
+    /** Drops every record of a session. Session deletion does this itself. */
+    forgetSession(sessionID: string): void;
+    /** Number of `sessionID:kind` records held. */
+    readonly size: number;
+    /** Removes every hook and stops listening for session deletion. */
+    dispose(): Promise<void>;
+}

package/dist/opencode2/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cortexkit/common-auth",
-  "version": "0.2.7",
+  "version": "0.2.8",
   "description": "Shared code for the CortexKit auth plugins: account pool, quota and routing, commands and auth menu, OpenCode 2 hooks, Claustrum custody, and plumbing (loopback RPC, file locks, logger, sidebar state, TUI preferences and build).",
   "license": "MIT",
   "repository": {