@cortexkit/common-auth 0.2.6 → 0.2.8

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>;