@cortexkit/anthropic-auth-core 1.21.0 → 1.23.0

package/dist/claustrum.d.ts

@@ -0,0 +1,252 @@
+import { type BindIdentity, type CatalogEntry, type CloseRouteOptions, type ManagedCallOptions, type ManagedCloseRouteOptions, type RequestOptions, type RouteHandle, type RouteOpenOptions, type RouteTarget, SubcClient, type SubscribeOptions, type Subscription } from '@cortexkit/subc-client';
+import type { ClaustrumConfig, OAuthAccount } from './accounts.ts';
+export type ClaustrumEndpoint = {
+    host: string;
+    port: number;
+};
+export type ClaustrumDetection = {
+    status: 'available';
+    schema: number;
+    wireVersion: number;
+    endpoints: ClaustrumEndpoint[];
+} | {
+    status: 'absent';
+    path: string;
+} | {
+    status: 'malformed';
+    path: string;
+    reason: string;
+};
+export declare const PRODUCTION_CLAUSTRUM_CONNECTION_FILE_NAME = "subc-connection.json";
+export declare function findExistingClaustrumConnectionPath(env?: NodeJS.ProcessEnv): string | undefined;
+export declare function getDefaultClaustrumConnectionPath(env?: NodeJS.ProcessEnv): string;
+export declare function resolveClaustrumConnectionPath(explicit?: string, env?: NodeJS.ProcessEnv): string;
+type CustodyHandlesEnvironment = Readonly<Record<string, string | undefined>>;
+export declare function resolveCustodyHandlesPath(config: Pick<ClaustrumConfig, 'handlesFile'> | undefined, env: CustodyHandlesEnvironment): string;
+export declare function getDefaultClaustrumHandlesPath(): string;
+export declare function detectClaustrumConnection(explicitPath?: string): Promise<ClaustrumDetection>;
+export declare const CUSTODY_TOMBSTONE_PREFIX = "claustrum-tombstone:v1:";
+export declare function custodyTombstoneKey(provider: string): string;
+export declare function custodyTombstoneOAuth(provider: string): {
+    type: 'oauth';
+    access: '';
+    refresh: string;
+    expires: 0;
+};
+export declare function isCustodyTombstoneValue(value: unknown): value is string;
+export declare function isCustodyTombstoneOAuth(auth: unknown, provider: string): boolean;
+export declare class CustodyTombstoneRefreshError extends Error {
+    readonly provider: string;
+    readonly code = "custody_tombstone_refresh";
+    constructor(provider: string);
+}
+export declare class CustodyTombstoneLoginError extends Error {
+    readonly provider: string;
+    readonly code = "custody_tombstone_login";
+    constructor(provider: string);
+}
+export declare function assertNotCustodyTombstone(refreshToken: unknown, provider: string): void;
+export type CustodyHandleAccount = {
+    label: string;
+    handle: string;
+    credentialId: string;
+};
+export type CustodyHandleManifest = {
+    version: 1;
+    provider: 'anthropic';
+    serve: 'anthropic-auth';
+    accounts: ReadonlyArray<CustodyHandleAccount>;
+    superseded: ReadonlySet<string>;
+    corruptLabels?: ReadonlySet<string>;
+};
+export type CustodyHandleResolution = {
+    status: 'resolved';
+    source: 'manifest';
+    handle: string;
+    credentialId: string;
+} | {
+    status: 'resolved';
+    source: 'legacy';
+    handle: string;
+} | {
+    status: 'unresolved';
+    reason: 'missing-label' | 'invalid-label' | 'duplicate-label' | 'missing-entry' | 'foreign-serve' | 'superseded' | 'corrupt-binding' | 'unknown-identity';
+};
+type ParsedCustodyHandleManifest = {
+    version: 1;
+    provider: string;
+    serve: string;
+    accounts: ReadonlyArray<CustodyHandleAccount>;
+    superseded: ReadonlySet<string>;
+    corruptLabels: ReadonlySet<string>;
+};
+export declare function isValidCustodyLabel(value: unknown): value is string;
+export declare function isValidCustodyHandle(value: unknown): value is string;
+export declare function custodyCredentialId(label: string): string;
+export declare function custodyCredentialIdFromResolution(resolution: CustodyHandleResolution, label: string): string;
+/**
+ * | manifest state | legacy handle | result |
+ * | --- | --- | --- |
+ * | matching ready entry | any | manifest handle |
+ * | absent or invalid | present | legacy handle |
+ * | no matching ready entry | present | legacy handle |
+ * | foreign serve | any | unresolved |
+ * | superseded matching entry | any | unresolved |
+ */
+export declare function resolveCustodyHandle(input: {
+    account: OAuthAccount;
+    manifest: CustodyHandleManifest | undefined;
+    duplicateOAuthLabels?: ReadonlySet<string>;
+}): CustodyHandleResolution;
+export declare function readCustodyHandles(json: unknown, provider: string, serve: string): ParsedCustodyHandleManifest;
+type CustodyHandleManifestReadResult = {
+    status: 'ready';
+    manifest: CustodyHandleManifest;
+} | {
+    status: 'absent';
+} | {
+    status: 'ignored';
+    reason: 'foreign-serve' | 'missing-provider';
+} | {
+    status: 'invalid';
+    reason: string;
+};
+export declare const CUSTODY_MANIFEST_SELECTION_ERROR_CODES: readonly ['foreign-serve', 'invalid-label', 'missing-provider'];
+type CustodyManifestSelectionErrorCode = (typeof CUSTODY_MANIFEST_SELECTION_ERROR_CODES)[number];
+export declare class CustodyManifestSelectionError extends Error {
+    readonly code: CustodyManifestSelectionErrorCode;
+    constructor(code: CustodyManifestSelectionErrorCode);
+}
+export declare class CustodyHandleManifestReader {
+    #private;
+    constructor(options: {
+        path: string;
+        provider: 'anthropic';
+        serve: 'anthropic-auth';
+        expectedUid?: number;
+    });
+    read(): Promise<CustodyHandleManifestReadResult>;
+}
+export type CustodyHandleManifestWriteResult = {
+    status: 'written' | 'unchanged';
+} | {
+    status: 'refused';
+    reason: string;
+    code?: CustodyManifestLockErrorCode;
+};
+export type CustodyHandleManifestRemovalResult = 'removed' | 'missing' | {
+    status: 'refused';
+    code?: CustodyManifestLockErrorCode;
+};
+export declare const CUSTODY_MANIFEST_LOCK_TTL_MS = 30000;
+export declare const CUSTODY_MANIFEST_LOCK_RENEW_MS = 10000;
+export declare const CUSTODY_MANIFEST_LOCK_RETRY_MIN_MS = 50;
+export declare const CUSTODY_MANIFEST_LOCK_RETRY_MAX_MS = 150;
+export type CustodyManifestLockTestOptions = Partial<{
+    ttlMs: number;
+    retryMinMs: number;
+    retryMaxMs: number;
+    renewalIntervalMs: number;
+    now: () => number;
+    setIntervalImpl: typeof globalThis.setInterval;
+    clearIntervalImpl: typeof globalThis.clearInterval;
+    afterStaleOwnerRead: () => void | Promise<void>;
+    beforeRename: () => void | Promise<void>;
+}>;
+export declare function __setCustodyManifestLockTestOptions(options?: CustodyManifestLockTestOptions): void;
+export declare const CUSTODY_MANIFEST_LOCK_ERROR_CODES: readonly ['lock_busy', 'owner_invalid', 'renewal_failed'];
+export type CustodyManifestLockErrorCode = (typeof CUSTODY_MANIFEST_LOCK_ERROR_CODES)[number];
+export declare class CustodyManifestLockError extends Error {
+    readonly code: CustodyManifestLockErrorCode;
+    constructor(message: string, code: CustodyManifestLockErrorCode);
+}
+export declare class CustodyManifestLockBusyError extends CustodyManifestLockError {
+    constructor(message: string);
+}
+export declare class CustodyManifestLockOwnerInvalidError extends CustodyManifestLockError {
+    constructor(message: string);
+}
+export declare class CustodyManifestLockLeaseLostError extends CustodyManifestLockError {
+    constructor(message: string);
+}
+export declare function __deriveCustodyManifestStaleLockPrefix(lockPath: string, pathBasename: (path: string) => string): string;
+export declare function withCustodyManifestLock<T>(path: string, fn: (assertLease: () => Promise<void>, nonce: string) => Promise<T>): Promise<T>;
+type CustodyHandleManifestWriteInput = {
+    path: string;
+    entry: CustodyHandleAccount;
+    expectedUid?: number;
+};
+export declare function writeCustodyHandleManifestEntry(input: CustodyHandleManifestWriteInput): Promise<CustodyHandleManifestWriteResult>;
+export declare function removeCustodyHandleManifestEntry(input: CustodyHandleManifestWriteInput): Promise<CustodyHandleManifestRemovalResult>;
+export declare function writeCustodyHandleManifestEntryLocked(input: CustodyHandleManifestWriteInput, assertLease: () => Promise<void>, lockNonce: string): Promise<CustodyHandleManifestWriteResult>;
+export type ClaustrumClientOptions = {
+    connectionFile?: string;
+    handshakeTimeoutMs?: number;
+    connector?: ClaustrumConnector;
+};
+export type ClaustrumConnector = (options: {
+    connectionFile: string;
+    handshakeTimeoutMs?: number;
+}) => Promise<SubcClient>;
+export declare class ClaustrumClient {
+    #private;
+    private constructor();
+    static connect(options?: ClaustrumClientOptions): Promise<ClaustrumClient>;
+    catalogList(moduleId?: string): Promise<CatalogEntry[]>;
+    routeOpen(target: RouteTarget, identity: BindIdentity, options?: Omit<RouteOpenOptions, 'consumerIdentity'>): Promise<RouteHandle>;
+    request(handle: RouteHandle, body: unknown, options?: RequestOptions): Promise<unknown>;
+    call<Response = unknown>(moduleId: string, method: string, params?: unknown, options?: Omit<ManagedCallOptions, 'consumerIdentity'>): Promise<Response>;
+    subscribe(handle: RouteHandle, body: unknown, onEvent: (event: Uint8Array) => void, options?: SubscribeOptions): Subscription;
+    closeRoute(handle: RouteHandle, options?: CloseRouteOptions): Promise<void>;
+    closeManagedRoute(target: Extract<RouteTarget, {
+        kind: 'management_surface' | 'tool_provider';
+    }>, identity: BindIdentity, options?: Omit<ManagedCloseRouteOptions, 'consumerIdentity'>): Promise<void>;
+    close(): void;
+}
+export declare function connectClaustrumClient(options?: ClaustrumClientOptions): Promise<ClaustrumClient>;
+export declare const CLAUSTRUM_MODULE_ID = "claustrum";
+export declare const DEFAULT_CLAUSTRUM_CREDENTIAL_MIN_TTL_MS = 120000;
+export declare const ERROR_CLASS_WIRE_SET: readonly ['transient', 'permanent', 'auth_required', 'context_overflow'];
+export type ClaustrumCredentialErrorClass = (typeof ERROR_CLASS_WIRE_SET)[number];
+export type ClaustrumCredentialErrorAction = 'gone' | 'reauth' | 'retry' | 'reduce_and_retry';
+export type ClaustrumCredential = {
+    payload: string;
+    expiresAtMs: number | null;
+    recordVersion: number;
+    projectId?: string;
+    accountId?: string;
+    credentialId?: string;
+};
+export type ClaustrumServedCredential = Pick<ClaustrumCredential, 'recordVersion'>;
+export type ClaustrumReporterSource = 'direct' | 'relay_status_field' | 'relay_message_parse';
+export declare class ClaustrumCredentialError extends Error {
+    readonly code: string;
+    readonly action: ClaustrumCredentialErrorAction;
+    readonly errorClass: ClaustrumCredentialErrorClass;
+    constructor(message: string, code: string, errorClass: ClaustrumCredentialErrorClass, action: ClaustrumCredentialErrorAction);
+}
+export type ClaustrumCredentialCacheOptions = {
+    identity?: BindIdentity;
+    now?: () => number;
+    minTtlMs?: number;
+};
+export declare class ClaustrumCredentialCache {
+    #private;
+    constructor(client: ClaustrumClient, options?: ClaustrumCredentialCacheOptions);
+    get(handle: string, minTtlMs?: number, options?: {
+        cacheIf?: () => boolean;
+    }): Promise<ClaustrumCredential>;
+    peek(handle: string): ClaustrumCredential | undefined;
+    abandonPending(handle: string): void;
+    seedForTest(handle: string, credential: ClaustrumCredential): void;
+    reduceMinTtlMs(): number;
+    reportAuthFailure(handle: string, providerStatus: number, servedCredential: ClaustrumServedCredential, reporterSource?: ClaustrumReporterSource): Promise<void>;
+    reportAuthFailure(handle: string, servedCredential: ClaustrumServedCredential, providerStatus?: number, reporterSource?: ClaustrumReporterSource): Promise<void>;
+    invalidate(handle: string, recordVersion?: number): void;
+    close(): void;
+}
+export type ConnectClaustrumCredentialCacheOptions = ClaustrumClientOptions & ClaustrumCredentialCacheOptions & {
+    enabled?: boolean;
+};
+export declare function connectClaustrumCredentialCache(options?: ConnectClaustrumCredentialCacheOptions): Promise<ClaustrumCredentialCache | null>;
+export {};