@native-knowledge/knowledge-sdk 0.0.0-stage → 0.1.0-rc.2

package/dist/agent-entry.js

@@ -0,0 +1,153 @@
+/** Explicit v26 task entry; existing clients and default protocol versions stay independent. */
+import { KnowledgeAgentGuidanceError, validateGuidanceActions, agentGuidanceFailure } from './agent-guidance-error.js';
+import { agentGuidanceHeader, agentResupplyGuidanceFeature, agentGuidedToolSchemas, agentGuidedDataSchemas, agentGuidedEnvelopeSchema } from './internal/serving-contracts/index.js';
+import { createHash } from 'node:crypto';
+import { resourceToolSchemas, tenantWebJobRef, tenantProjectOperationRef } from './internal/contracts/index.js';
+import { agentBodySearchHeader, agentBodySearchFeature, bodySearchToolSchemas, bodyCitationSchema, agentEntryToolSchemas, agentEntryDataSchemas, agentEntryEnvelopeSchema, agentEntryProviderSchema, agentCapabilityEnvelopeSchema, agentCapabilitySchemas, agentCapabilityDataSchemas } from './internal/serving-contracts/index.js';
+import { KnowledgeTenantManagementClient, TenantManagementSdkError } from './tenant-management.js';
+import { KnowledgeResourceClient } from './resource.js';
+const paged = new Set(['knowledge_resource_search_body', 'knowledge_resource_list', 'knowledge_resource_search', 'knowledge_resource_counts', 'knowledge_resource_changes', 'tenant_material_routes', 'tenant_source_list', 'tenant_source_inventory', 'tenant_work_queue', 'tenant_project_list', 'tenant_project_materials', 'tenant_runtime_status', 'tenant_web_collect_results', 'tenant_web_collect_cycles']);
+const object = (v) => v && typeof v === 'object' && !Array.isArray(v) ? v : {};
+function pageBudget(value = 10) { if (!Number.isSafeInteger(value) || value < 1 || value > 100)
+    throw new TenantManagementSdkError('AGENT_SDK_PAGE_BUDGET_INVALID', 0); return value; }
+export class KnowledgeAgentClient extends KnowledgeTenantManagementClient {
+    failure(raw, status) { return agentGuidanceFailure(raw, status, this.options.expectedTenantId); }
+    async entry(tool, raw, signal, guided = false) {
+        const input = (guided ? agentGuidedToolSchemas : agentEntryToolSchemas)[tool].parse(raw), body = JSON.stringify({ tool, arguments: input });
+        if (Buffer.byteLength(body) > 131072)
+            throw new TenantManagementSdkError('TENANT_MANAGEMENT_SDK_REQUEST_TOO_LARGE', 0);
+        const response = await this.request(this.url('call', 26), { method: 'POST', headers: { 'content-type': 'application/json', [agentBodySearchHeader]: agentBodySearchFeature, ...(guided ? { [agentGuidanceHeader]: agentResupplyGuidanceFeature } : {}) }, body, ...(signal ? { signal } : {}) }), v = (guided ? agentGuidedEnvelopeSchema : agentEntryEnvelopeSchema)(tool).safeParse(await this.json(response));
+        if (!v.success)
+            throw new TenantManagementSdkError('TENANT_MANAGEMENT_SDK_RESPONSE_INVALID', response.status);
+        if (v.data.tenantId !== this.options.expectedTenantId)
+            throw new TenantManagementSdkError('TENANT_MANAGEMENT_SDK_CONTEXT_MISMATCH', response.status);
+        return v.data;
+    }
+    async agentProvider() { const r = await this.request(this.url('provider', 26)), v = agentEntryProviderSchema.safeParse(await this.json(r)); if (!v.success)
+        throw new TenantManagementSdkError('TENANT_MANAGEMENT_SDK_RESPONSE_INVALID', r.status); return v.data; }
+    async discover(input = {}, options = {}) {
+        const result = await this.entry('knowledge_discover', input, options.signal), data = agentEntryDataSchemas.knowledge_discover.parse(result.data);
+        if (input.tool && data.detail?.name !== input.tool || !input.tool && data.detail !== null)
+            throw new TenantManagementSdkError('TENANT_MANAGEMENT_SDK_CONTEXT_MISMATCH', 200);
+        return { ...result, tool: 'knowledge_discover', data };
+    }
+    async execute(tool, input, options = {}) { return await this.executeChecked(tool, input, options, false); }
+    async guidedDiscover(input = {}, options = {}) {
+        const result = await this.entry('knowledge_discover', input, options.signal, true), data = agentGuidedDataSchemas.knowledge_discover.parse(result.data);
+        if (input.tool && data.detail?.name !== input.tool || !input.tool && data.detail !== null || Boolean(input.task) !== (data.mode === 'TASK') || Boolean(data.taskPlan) !== (data.mode === 'TASK'))
+            throw new TenantManagementSdkError('TENANT_MANAGEMENT_SDK_CONTEXT_MISMATCH', 200);
+        validateGuidanceActions(data.nextActions);
+        for (const step of data.taskPlan?.steps ?? [])
+            if (step.action)
+                validateGuidanceActions([step.action]);
+        return { ...result, tool: 'knowledge_discover', data };
+    }
+    planTask(task, options = {}) { return this.guidedDiscover({ task }, options); }
+    inputGuide(tool, input = {}, options = {}) { return this.guidedDiscover({ tool, arguments: JSON.parse(JSON.stringify(input)), ...(options.resupplyFields ? { resupplyFields: options.resupplyFields } : {}) }, options); }
+    async guidedExecute(tool, input, options = {}) {
+        try {
+            return await this.executeChecked(tool, input, options, true);
+        }
+        catch (error) {
+            if (error instanceof KnowledgeAgentGuidanceError)
+                throw error;
+            if (error instanceof TenantManagementSdkError)
+                throw new KnowledgeAgentGuidanceError(error.code, error.status, { reasonCode: 'OUTCOME_UNKNOWN', summary: '先检查当前授权及准确目标状态，不自动重试写入。', inputHints: [], nextActions: [] }, { ...(error.completedPhase ? { completedPhase: error.completedPhase } : {}), ...(error.ref ? { ref: error.ref } : {}) });
+            throw error;
+        }
+    }
+    async executeChecked(tool, input, options, guided) {
+        const parsedInput = Object.hasOwn(agentCapabilitySchemas, tool) ? agentCapabilitySchemas[tool].safeParse(input) : null, wireInput = parsedInput?.success ? JSON.parse(JSON.stringify(parsedInput.data)) : input;
+        const response = await this.entry('knowledge_execute', { tool, arguments: wireInput }, options.signal, guided), data = (guided ? agentGuidedDataSchemas : agentEntryDataSchemas).knowledge_execute.parse(response.data);
+        if (data.capability !== tool)
+            throw new TenantManagementSdkError('TENANT_MANAGEMENT_SDK_CONTEXT_MISMATCH', 200);
+        if (data.status === 'COMPLETED') {
+            const parsed = agentCapabilityEnvelopeSchema(tool).safeParse(data.result);
+            if (!parsed.success)
+                throw new TenantManagementSdkError('TENANT_MANAGEMENT_SDK_RESPONSE_INVALID', 200);
+            const inner = object(parsed.data), context = object(inner.context), raw = object(wireInput), d = object(inner.data);
+            if ((Object.hasOwn(resourceToolSchemas, tool) || Object.hasOwn(bodySearchToolSchemas, tool)) ? context.tenantId !== this.options.expectedTenantId || (raw.projectRef ? context.type !== 'PROJECT' || context.projectRef !== raw.projectRef || inner.policy !== 'TENANT_PROJECT_SCOPE' : context.type !== 'TENANT' || inner.policy !== 'TENANT_NATIVE') : inner.tenantId !== this.options.expectedTenantId || inner.tool !== tool)
+                throw new TenantManagementSdkError('TENANT_MANAGEMENT_SDK_CONTEXT_MISMATCH', 200);
+            if (tool.startsWith('tenant_project_')) {
+                const receipt = object(d.receipt), expected = typeof raw.requestId === 'string' ? tenantProjectOperationRef(this.options.expectedTenantId, raw.requestId) : null;
+                if (raw.projectKey && d.projectKey !== raw.projectKey || expected && (d.operationRef && d.operationRef !== expected || receipt.operationRef && receipt.operationRef !== expected))
+                    throw new TenantManagementSdkError('TENANT_MANAGEMENT_SDK_CONTEXT_MISMATCH', 200);
+            }
+            if (tool === 'tenant_web_collect_control') {
+                const operation = object(object(d.receipt).operation);
+                if (operation.requestId !== raw.requestId || operation.action !== raw.action || operation.expectedEpoch !== raw.expectedEpoch || operation.jobRef !== object(d.job).rootJobRef)
+                    throw new TenantManagementSdkError('TENANT_MANAGEMENT_SDK_CONTEXT_MISMATCH', 200);
+            }
+            const source = tool === 'tenant_source_get' ? d : object(d.head), expectedSource = raw.sourceId ?? object(raw.definition).sourceId, request = object(d.request);
+            if (d.tenantId && d.tenantId !== this.options.expectedTenantId || source.tenantId && source.tenantId !== this.options.expectedTenantId || request.tenantId && request.tenantId !== this.options.expectedTenantId || expectedSource && source.sourceId && source.sourceId !== expectedSource || ['tenant_collection_request', 'tenant_collection_status'].includes(tool) && request.requestId && request.requestId !== raw.requestId || tool === 'tenant_workflow_advance' && (d.previousRef !== raw.ref || d.action !== raw.action))
+                throw new TenantManagementSdkError('TENANT_MANAGEMENT_SDK_CONTEXT_MISMATCH', 200);
+            const expectedJob = tool === 'tenant_web_collect_submit' || tool === 'tenant_web_collect_refresh' ? tenantWebJobRef(this.options.expectedTenantId, String(raw.requestId)) : raw.jobRef;
+            if (expectedJob && (d.jobRef ?? object(d.job).jobRef) !== expectedJob || raw.ref && object(d.item).ref && object(d.item).ref !== raw.ref || ['tenant_workflow_plan', 'tenant_knowledge_read'].includes(tool) && d.ref !== raw.ref || tool === 'tenant_snapshot_status' && d.subjectRef !== raw.ref || tool === 'knowledge_resource_media' && (d.ref && d.ref !== raw.ref || raw.documentRef && d.state === 'READY' && d.documentRef !== raw.documentRef))
+                throw new TenantManagementSdkError('TENANT_MANAGEMENT_SDK_CONTEXT_MISMATCH', 200);
+            if (tool === 'knowledge_resource_search_body')
+                for (const item of d.items) {
+                    const citation = bodyCitationSchema.parse(item.citation);
+                    if (citation.ref !== item.item.ref || citation.contentHash !== item.item.identityHash)
+                        throw new TenantManagementSdkError('TENANT_MANAGEMENT_SDK_CONTEXT_MISMATCH', 200);
+                }
+            if (tool === 'knowledge_resource_read_passage' && JSON.stringify(d.citation) !== JSON.stringify(bodyCitationSchema.parse(raw.citation)))
+                throw new TenantManagementSdkError('TENANT_MANAGEMENT_SDK_CONTEXT_MISMATCH', 200);
+            const read = tool === 'tenant_web_collect_read' ? object(d.result) : d;
+            if (read.delivery === 'INLINE_BASE64') {
+                if (typeof read.contentBase64 !== 'string' || !object(read.item).ref)
+                    throw new TenantManagementSdkError('TENANT_MANAGEMENT_SDK_RESPONSE_INVALID', 200);
+                const text = String(read.contentBase64), bytes = Buffer.from(text, 'base64'), descriptor = object(read.descriptor), item = object(read.item);
+                if (bytes.toString('base64') !== text || bytes.length !== descriptor.byteLength || read.byteLength !== null && bytes.length !== read.byteLength || 'sha256:' + createHash('sha256').update(bytes).digest('hex') !== descriptor.contentHash || item.identityKind === 'CAS_BYTES' && descriptor.contentHash !== item.identityHash)
+                    throw new TenantManagementSdkError('TENANT_MANAGEMENT_SDK_CONTENT_IDENTITY_MISMATCH', 200);
+            }
+        }
+        else if (data.result !== null || !data.missingFields.length)
+            throw new TenantManagementSdkError('TENANT_MANAGEMENT_SDK_RESPONSE_INVALID', 200);
+        if (guided)
+            validateGuidanceActions(data.nextActions);
+        return { ...response, tool: 'knowledge_execute', data };
+    }
+    openMaterialStream(ref, options = {}) { return new KnowledgeResourceClient({ ...this.options, authentication: 'OAUTH' }).stream(ref, options); }
+    async *discoverPages(input, options = {}) {
+        const max = pageBudget(options.maxPages), seen = new Set(input.after ? [input.after] : []);
+        let request = { ...input };
+        for (let i = 0; i < max; i++) {
+            const page = await this.discover(request, options), after = page.data.nextAfter;
+            if (after && seen.has(after))
+                throw new TenantManagementSdkError('AGENT_SDK_CURSOR_REPEATED', 200);
+            if (after)
+                seen.add(after);
+            yield page;
+            if (!after)
+                return;
+            request = { ...request, after };
+        }
+    }
+    async *pages(tool, input, options = {}) {
+        const media = tool === 'knowledge_resource_media', project = tool === 'tenant_project_get', continuation = options.continuation;
+        if (!paged.has(tool) && !media && !project)
+            throw new TenantManagementSdkError('AGENT_SDK_OPERATION_NOT_PAGEABLE', 0);
+        if (project ? !['purpose', 'selection'].includes(continuation ?? '') : continuation !== undefined)
+            throw new TenantManagementSdkError('AGENT_SDK_CONTINUATION_INVALID', 0);
+        const max = pageBudget(options.maxPages), cursor = media ? 'afterOrdinal' : project ? continuation + 'After' : 'after';
+        let request = { ...object(input) };
+        const initial = request[cursor], seen = new Set(typeof initial === 'string' || typeof initial === 'number' ? [initial] : []);
+        for (let i = 0; i < max; i++) {
+            const page = await this.execute(tool, request, options), completed = page.data.status === 'COMPLETED', data = object(page.data.result?.data), after = media ? data.nextAfterOrdinal : project ? object(data[continuation]).nextAfter : data.nextAfter;
+            const more = media ? typeof after === 'number' : typeof after === 'string' && after.length > 0;
+            if (more) {
+                if (seen.has(after) || media && typeof request[cursor] === 'number' && after <= request[cursor])
+                    throw new TenantManagementSdkError('AGENT_SDK_CURSOR_REPEATED', 200);
+                if (media && (data.state !== 'READY' || typeof data.documentRef !== 'string'))
+                    throw new TenantManagementSdkError('TENANT_MANAGEMENT_SDK_RESPONSE_INVALID', 200);
+                seen.add(after);
+            }
+            // Capture the exact continuation before yielding: consumers may retain or edit the returned page.
+            const next = { ...request, [cursor]: after, ...(media && more ? { documentRef: data.documentRef } : {}) };
+            yield page;
+            if (!completed || !more)
+                return;
+            request = next;
+        }
+    }
+}

package/dist/agent-guidance-error.d.ts

@@ -0,0 +1,15 @@
+import { type AgentRecovery } from './internal/serving-contracts/index.js';
+import { TenantManagementSdkError } from './tenant-management.js';
+export declare function validateGuidanceActions(actions: AgentRecovery['nextActions'], options?: {
+    status?: number;
+    recoveryOnly?: boolean;
+}): void;
+export declare class KnowledgeAgentGuidanceError extends TenantManagementSdkError<string> {
+    readonly guidance: AgentRecovery;
+    constructor(code: string, status: number, guidance: AgentRecovery, details?: {
+        completedPhase?: string;
+        ref?: string;
+    });
+}
+/** Invalid optional guidance cannot erase a validated durable failure receipt. */
+export declare function agentGuidanceFailure(raw: unknown, status: number, tenantId: string): TenantManagementSdkError<string> | null;

package/dist/agent-guidance-error.js

@@ -0,0 +1,46 @@
+import { agentGuidedToolSchemas, agentEntryToolSchemas, agentCapabilitySchemas, agentCatalog, agentRecoverySchema, tenantWebWorkflowErrorSchema, tenantWebSafeErrorRef } from './internal/serving-contracts/index.js';
+import { TenantManagementSdkError } from './tenant-management.js';
+export function validateGuidanceActions(actions, options = {}) {
+    const invalid = () => new TenantManagementSdkError('TENANT_MANAGEMENT_SDK_RESPONSE_INVALID', options.status ?? 200);
+    for (const action of actions) {
+        if (action.canExecute && action.missingFields.length)
+            throw invalid();
+        const entry = agentGuidedToolSchemas[action.tool].safeParse(action.arguments);
+        if (!entry.success)
+            throw invalid();
+        if (action.tool === 'knowledge_execute') {
+            const input = agentEntryToolSchemas.knowledge_execute.parse(action.arguments);
+            if (options.recoveryOnly && !agentCatalog[input.tool].readOnly || action.canExecute && !agentCapabilitySchemas[input.tool].safeParse(input.arguments).success)
+                throw invalid();
+        }
+    }
+}
+export class KnowledgeAgentGuidanceError extends TenantManagementSdkError {
+    guidance;
+    constructor(code, status, guidance, details) {
+        super(code, status, details);
+        this.guidance = guidance;
+        this.name = 'KnowledgeAgentGuidanceError';
+    }
+}
+/** Invalid optional guidance cannot erase a validated durable failure receipt. */
+export function agentGuidanceFailure(raw, status, tenantId) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return null;
+    const { guidance, ...base } = raw, parsed = tenantWebWorkflowErrorSchema.safeParse(base);
+    if (!parsed.success)
+        return null;
+    const failure = parsed.data, ref = tenantWebSafeErrorRef(failure.ref, tenantId), details = { ...(failure.completedPhase ? { completedPhase: failure.completedPhase } : {}), ...(ref ? { ref } : {}) };
+    if (!Object.hasOwn(raw, 'guidance'))
+        return new TenantManagementSdkError(failure.errorCode, status, details);
+    try {
+        const checked = agentRecoverySchema.parse(guidance);
+        validateGuidanceActions(checked.nextActions, { status, recoveryOnly: true });
+        if (/AUTHORITY_CHANGED|FORBIDDEN/.test(failure.errorCode) && checked.nextActions.length)
+            throw new Error('invalid revoked actions');
+        return new KnowledgeAgentGuidanceError(failure.errorCode, status, checked, details);
+    }
+    catch {
+        return new KnowledgeAgentGuidanceError('TENANT_MANAGEMENT_SDK_RESPONSE_INVALID', status, { reasonCode: /AUTHORITY_CHANGED|FORBIDDEN/.test(failure.errorCode) ? 'AUTHORITY_REQUIRED' : 'OUTCOME_UNKNOWN', summary: '错误引导无效；保留已知阶段和安全引用，检查当前授权及准确结果，不重放写入。', inputHints: [], nextActions: [] }, details);
+    }
+}

package/dist/auth.d.ts

@@ -0,0 +1,124 @@
+/// <reference types="node" />
+import { type TenantClientProvider, type TenantSession } from './internal/serving-contracts/index.js';
+export { type TenantSession, type TenantClientProvider };
+export interface OAuthTokens {
+    accessToken: string;
+    refreshToken: string;
+    expiresAt: string;
+    scopes: string[];
+}
+export interface AuthorizationTransaction {
+    issuer: string;
+    resource: string;
+    clientId: string;
+    redirectUri: string;
+    state: string;
+    verifier: string;
+    authorizationUrl: string;
+    expiresAt: number;
+    scopes: string[];
+}
+export interface AuthClientOptions {
+    baseUrl: string;
+    expectedIssuer?: string;
+    expectedResource?: string;
+    allowInsecureHttp?: boolean;
+    fetchImpl?: typeof fetch;
+}
+export declare class AuthError extends Error {
+    readonly code: string;
+    readonly status: number;
+    constructor(code: string, status?: number);
+}
+export declare function authUrl(raw: string, insecure?: boolean): URL;
+export declare class KnowledgeAuthClient {
+    private options;
+    private root;
+    private fetchImpl;
+    private cached;
+    constructor(options: AuthClientOptions);
+    private request;
+    discover(): Promise<{
+        schemaVersion: 26;
+        provider: "knowledge-v2";
+        revision: string;
+        issuer: string;
+        resource: string;
+        authorizationServerMetadataUrl: string;
+        tenantSessionEndpoint: string;
+        tenantOperationStatusEndpoint: string;
+        resourceCallEndpoint: string;
+        resourceFileEndpoint: string;
+        registrationModes: ("PRE_REGISTERED_NATIVE" | "CIMD_READ_ONLY")[];
+        callbackModes: "NATIVE_LOOPBACK_PORT_V1"[];
+        providers: {
+            version: number;
+            endpoint: string;
+        }[];
+        tools: {
+            name: string;
+            endpoint: string;
+            method: "GET" | "POST";
+            inputSchema: import("zod").JSONType;
+            outputSchema: import("zod").JSONType;
+            scopeAlternatives: string[][];
+        }[];
+        limits: {
+            requestMaxBytes: 131072;
+            resultMaxBytes: 524288;
+        };
+    }>;
+    metadata(): Promise<{
+        issuer: string;
+        authorizationEndpoint: string;
+        tokenEndpoint: string;
+        revocationEndpoint: string;
+    }>;
+    begin(input: {
+        clientId: string;
+        redirectUri: string;
+        scopes: string[];
+        authorityVersion?: 1 | 2;
+        expectedTenantRef?: string;
+    }): Promise<{
+        issuer: string;
+        resource: string;
+        clientId: string;
+        redirectUri: string;
+        state: string;
+        verifier: string;
+        authorizationUrl: string;
+        expiresAt: number;
+        scopes: string[];
+    }>;
+    exchange(t: AuthorizationTransaction, callback: URL): Promise<OAuthTokens>;
+    private tokens;
+    refresh(clientId: string, refreshToken: string, scopes?: string[]): Promise<OAuthTokens>;
+    session(token: string, expected?: Partial<Pick<TenantSession, 'issuer' | 'resource' | 'clientId' | 'userId' | 'tenantId' | 'authorityVersion'>>): Promise<{
+        schemaVersion: 1;
+        issuer: string;
+        resource: string;
+        clientId: string;
+        userId: string;
+        tenantId: string;
+        tenantRef: string;
+        contextType: "TENANT";
+        authorityVersion: 2 | 1;
+        tokenScopes: string[];
+        effectiveScopes: string[];
+        expiresAt: string;
+        managementConfigured: boolean;
+        blockers: string[];
+    }>;
+    operationStatus(token: string, raw: unknown, expectedTenantId?: string): Promise<{
+        schemaVersion: 1;
+        tenantId: string;
+        requestId: string;
+        state: "NOT_FOUND" | "INTENT_PERSISTED";
+        operationRef: string | null;
+        action: string | null;
+        receivedAt: string | null;
+        completion: "NOT_PROVEN";
+    }>;
+    revoke(clientId: string, token: string): Promise<void>;
+}

package/dist/auth.js

@@ -0,0 +1,165 @@
+import { randomBytes, createHash } from 'node:crypto';
+import { tenantClientProviderSchema, tenantSessionSchema, tenantOperationStatusInputSchema, tenantOperationStatusSchema } from './internal/serving-contracts/index.js';
+export {};
+export class AuthError extends Error {
+    code;
+    status;
+    constructor(code, status = 0) {
+        super(code);
+        this.code = code;
+        this.status = status;
+        this.name = 'AuthError';
+    }
+}
+export function authUrl(raw, insecure = false) { let u; try {
+    u = new URL(raw);
+}
+catch {
+    throw new AuthError('AUTH_URL_INVALID');
+} if (u.username || u.password || u.search || u.hash || u.protocol !== 'https:' && !(insecure && u.protocol === 'http:' && ['127.0.0.1', '[::1]', 'localhost'].includes(u.hostname)))
+    throw new AuthError('AUTH_URL_INVALID'); return u; }
+export class KnowledgeAuthClient {
+    options;
+    root;
+    fetchImpl;
+    cached;
+    constructor(options) {
+        this.options = options;
+        this.root = authUrl(options.baseUrl, options.allowInsecureHttp);
+        this.fetchImpl = options.fetchImpl ?? fetch;
+    }
+    async request(url, init = {}) {
+        let response;
+        try {
+            response = await this.fetchImpl(url, { ...init, redirect: 'error', signal: AbortSignal.timeout(15000) });
+        }
+        catch {
+            throw new AuthError('AUTH_TRANSPORT_FAILURE');
+        }
+        if (!response.body)
+            throw new AuthError('AUTH_RESPONSE_INVALID', response.status);
+        const reader = response.body.getReader(), chunks = [];
+        let n = 0;
+        try {
+            while (true) {
+                const p = await reader.read();
+                if (p.done)
+                    break;
+                n += p.value.length;
+                if (n > 524288) {
+                    await reader.cancel();
+                    throw new AuthError('AUTH_RESPONSE_BUDGET');
+                }
+                chunks.push(p.value);
+            }
+        }
+        finally {
+            reader.releaseLock();
+        }
+        let data;
+        try {
+            data = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(Buffer.concat(chunks)));
+        }
+        catch {
+            throw new AuthError('AUTH_RESPONSE_INVALID', response.status);
+        }
+        if (!response.ok)
+            throw new AuthError(response.status === 401 ? 'AUTH_REQUIRED' : response.status === 403 ? 'AUTH_FORBIDDEN' : response.status === 404 ? 'SERVER_CAPABILITY_UNAVAILABLE' : 'AUTH_REQUEST_FAILED', response.status);
+        return data;
+    }
+    async discover() {
+        if (this.cached)
+            return this.cached;
+        let p;
+        try {
+            p = tenantClientProviderSchema.parse(await this.request(new URL(this.root.pathname.replace(/\/$/, '') + '/v1/tenant/client-provider', this.root.origin)));
+        }
+        catch (e) {
+            if (e instanceof AuthError)
+                throw e;
+            throw new AuthError('AUTH_DISCOVERY_INVALID');
+        }
+        if (this.options.expectedIssuer && p.issuer !== this.options.expectedIssuer || this.options.expectedResource && p.resource !== this.options.expectedResource)
+            throw new AuthError('AUTH_ISSUER_MISMATCH');
+        authUrl(p.issuer, this.options.allowInsecureHttp);
+        authUrl(p.resource, this.options.allowInsecureHttp);
+        for (const raw of [p.tenantSessionEndpoint, p.tenantOperationStatusEndpoint, p.resourceCallEndpoint, p.resourceFileEndpoint, ...p.tools.map(t => t.endpoint), ...p.providers.map(t => t.endpoint)])
+            if (authUrl(raw, this.options.allowInsecureHttp).origin !== this.root.origin)
+                throw new AuthError('AUTH_ENDPOINT_MISMATCH');
+        const issuer = authUrl(p.issuer, this.options.allowInsecureHttp);
+        if (authUrl(p.authorizationServerMetadataUrl, this.options.allowInsecureHttp).origin !== issuer.origin)
+            throw new AuthError('AUTH_ISSUER_MISMATCH');
+        this.cached = p;
+        return p;
+    }
+    async metadata() { const p = await this.discover(), m = await this.request(p.authorizationServerMetadataUrl); if (m.issuer !== p.issuer || !Array.isArray(m.code_challenge_methods_supported) || !m.code_challenge_methods_supported.includes('S256') || !Array.isArray(m.grant_types_supported) || !m.grant_types_supported.includes('authorization_code'))
+        throw new AuthError('AUTH_DISCOVERY_INVALID'); for (const key of ['authorization_endpoint', 'token_endpoint', 'revocation_endpoint'])
+        if (typeof m[key] !== 'string' || (key !== 'authorization_endpoint' && authUrl(m[key], this.options.allowInsecureHttp).origin !== new URL(p.issuer).origin))
+            throw new AuthError('AUTH_ENDPOINT_MISMATCH'); authUrl(m.authorization_endpoint, this.options.allowInsecureHttp); return { issuer: p.issuer, authorizationEndpoint: m.authorization_endpoint, tokenEndpoint: m.token_endpoint, revocationEndpoint: m.revocation_endpoint }; }
+    async begin(input) {
+        const p = await this.discover();
+        if (!p.registrationModes.includes('PRE_REGISTERED_NATIVE'))
+            throw new AuthError('SERVER_CAPABILITY_UNAVAILABLE');
+        const m = await this.metadata(), state = randomBytes(32).toString('base64url'), verifier = randomBytes(48).toString('base64url'), u = new URL(m.authorizationEndpoint);
+        const redirect = new URL(input.redirectUri);
+        if (redirect.protocol !== 'http:' || !['127.0.0.1', '[::1]'].includes(redirect.hostname) || redirect.search || redirect.hash || redirect.username || redirect.password || !input.scopes.length || input.scopes.length > 32)
+            throw new AuthError('AUTH_INPUT_INVALID');
+        for (const [k, v] of Object.entries({ response_type: 'code', client_id: input.clientId, redirect_uri: redirect.href, resource: p.resource, scope: input.scopes.join(' '), authority_version: String(input.authorityVersion ?? 1), state, code_challenge: createHash('sha256').update(verifier).digest('base64url'), code_challenge_method: 'S256', ...(input.expectedTenantRef ? { tenant_ref: input.expectedTenantRef } : {}) }))
+            u.searchParams.set(k, v);
+        return { issuer: p.issuer, resource: p.resource, clientId: input.clientId, redirectUri: redirect.href, state, verifier, authorizationUrl: u.href, expiresAt: Date.now() + 300000, scopes: input.scopes };
+    }
+    async exchange(t, callback) {
+        if (Date.now() >= t.expiresAt || callback.origin !== new URL(t.redirectUri).origin || callback.pathname !== new URL(t.redirectUri).pathname || callback.hash || callback.username || callback.password)
+            throw new AuthError('AUTH_CALLBACK_INVALID');
+        for (const k of callback.searchParams.keys())
+            if (!['state', 'iss', 'code', 'error', 'error_description', 'error_uri'].includes(k) || callback.searchParams.getAll(k).length !== 1)
+                throw new AuthError('AUTH_CALLBACK_INVALID');
+        if (callback.searchParams.get('state') !== t.state || callback.searchParams.get('iss') !== t.issuer)
+            throw new AuthError('AUTH_CALLBACK_INVALID');
+        if (callback.searchParams.has('error'))
+            throw new AuthError('AUTH_CONSENT_DENIED');
+        const code = callback.searchParams.get('code');
+        if (!code)
+            throw new AuthError('AUTH_CALLBACK_INVALID');
+        const p = await this.discover();
+        if (p.issuer !== t.issuer || p.resource !== t.resource)
+            throw new AuthError('AUTH_ISSUER_MISMATCH');
+        return this.tokens(new URLSearchParams({ grant_type: 'authorization_code', client_id: t.clientId, resource: t.resource, redirect_uri: t.redirectUri, code, code_verifier: t.verifier }), t.scopes);
+    }
+    async tokens(body, allowed) {
+        const m = await this.metadata();
+        let raw;
+        try {
+            raw = await this.request(m.tokenEndpoint, { method: 'POST', headers: { 'content-type': 'application/x-www-form-urlencoded' }, body });
+        }
+        catch (e) {
+            throw new AuthError(e instanceof AuthError && e.status === 400 ? 'AUTH_REAUTH_REQUIRED' : 'AUTH_TOKEN_RESULT_UNKNOWN');
+        }
+        const r = raw;
+        if (r.token_type !== 'Bearer' || typeof r.access_token !== 'string' || typeof r.refresh_token !== 'string' || !/^[-\w]{43}$/.test(r.access_token) || !/^[-\w]{43}$/.test(r.refresh_token) || typeof r.expires_in !== 'number' || !Number.isSafeInteger(r.expires_in) || r.expires_in < 1 || r.expires_in > 86400 || typeof r.scope !== 'string')
+            throw new AuthError('AUTH_TOKEN_RESULT_UNKNOWN');
+        const scopes = r.scope.split(' ');
+        if (allowed && scopes.some(s => !allowed.includes(s)))
+            throw new AuthError('AUTH_SCOPE_MISMATCH');
+        return { accessToken: r.access_token, refreshToken: r.refresh_token, expiresAt: new Date(Date.now() + r.expires_in * 1000).toISOString(), scopes };
+    }
+    async refresh(clientId, refreshToken, scopes) { const p = await this.discover(); return this.tokens(new URLSearchParams({ grant_type: 'refresh_token', client_id: clientId, resource: p.resource, refresh_token: refreshToken }), scopes); }
+    async session(token, expected) {
+        const p = await this.discover();
+        let s;
+        try {
+            s = tenantSessionSchema.parse(await this.request(p.tenantSessionEndpoint, { headers: { authorization: 'Bearer ' + token } }));
+        }
+        catch (e) {
+            if (e instanceof AuthError)
+                throw e;
+            throw new AuthError('AUTH_SESSION_INVALID');
+        }
+        if (s.issuer !== p.issuer || s.resource !== p.resource || expected && Object.entries(expected).some(([k, v]) => s[k] !== v))
+            throw new AuthError('AUTH_CONTEXT_MISMATCH');
+        return s;
+    }
+    async operationStatus(token, raw, expectedTenantId) { const input = tenantOperationStatusInputSchema.parse(raw), p = await this.discover(), url = new URL(p.tenantOperationStatusEndpoint); url.searchParams.set('requestId', input.requestId); const result = tenantOperationStatusSchema.parse(await this.request(url, { headers: { authorization: 'Bearer ' + token } })); if (expectedTenantId && result.tenantId !== expectedTenantId)
+        throw new AuthError('AUTH_CONTEXT_MISMATCH'); return result; }
+    async revoke(clientId, token) { const m = await this.metadata(); await this.request(m.revocationEndpoint, { method: 'POST', headers: { 'content-type': 'application/x-www-form-urlencoded' }, body: new URLSearchParams({ client_id: clientId, token }) }); }
+}