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

package/dist/oauth.js

@@ -0,0 +1,539 @@
+import { authorizedFetch, tokenValue } from './token-provider.js';
+import { materialStream } from './material-stream.js';
+import { knowledgeMcpProviderContractV12Schema, oauthMaterialCapabilityResponseSchema, oauthMaterialCapabilityPageSchema, oauthMaterialMediaCapabilityPageSchema, oauthMaterialIndexStatusSchema } from './internal/serving-contracts/index.js';
+/** OAuth 文件客户端只消费调用方已取得的 token，并从通用 Provider 发现完整字节端点。 */
+import { createHash } from 'node:crypto';
+import { consumerProjectRefSchema, knowledgeMcpProviderContractV3Schema, knowledgeMcpProviderContractV6Schema, knowledgeMcpProviderContractV7Schema, knowledgeMcpProviderContractV8Schema, knowledgeMcpProviderContractV9Schema, knowledgeMcpProviderContractV10Schema, knowledgeMcpProviderContractV11Schema, materialOutboxWindowSchema, knowledgeMaterialSearchInputSchema, knowledgeMaterialSearchResponseSchema, oauthMaterialPageResponseSchema, oauthMaterialRoutePageResponseSchema, oauthMaterialPartitionsResponseSchema, oauthMaterialPartitionPageResponseSchema, oauthMaterialPresentationResponseSchema, servingDecisionSchema } from './internal/serving-contracts/index.js';
+const digest = (bytes) => `sha256:${createHash('sha256').update(bytes).digest('hex')}`;
+function serviceUrl(value, allowInsecureHttp) {
+    const url = new URL(value);
+    if (url.username || url.password || url.search || url.hash || !['http:', 'https:'].includes(url.protocol))
+        throw new Error('OAUTH_FILE_BASE_URL_INVALID');
+    if (url.protocol === 'http:' && !allowInsecureHttp)
+        throw new Error('OAUTH_FILE_HTTPS_REQUIRED');
+    url.pathname = url.pathname.replace(/\/+$/, '');
+    return url;
+}
+function parseEndpoint(value, origin) {
+    const url = new URL(value);
+    // Bearer 只能发送到执行发现的服务源，禁止 Provider 元数据把凭据导向别处。
+    if (url.origin !== origin || url.username || url.password || url.search || url.hash)
+        throw new Error('OAUTH_FILE_ENDPOINT_INVALID');
+    return url;
+}
+export class KnowledgeOAuthFileClient {
+    projectRef;
+    root;
+    credentials;
+    fetchImpl;
+    providerPromise = null;
+    materialProviderPromise = null;
+    agentMaterialProviderPromise = null;
+    searchMaterialProviderPromise = null;
+    routeMaterialProviderPromise = null;
+    syncMaterialProviderPromise = null;
+    capabilityProviderPromise = null;
+    partitionMaterialProviderPromise = null;
+    constructor(options) {
+        this.root = serviceUrl(options.baseUrl, options.allowInsecureHttp === true);
+        this.projectRef = consumerProjectRefSchema.parse(options.projectRef);
+        if (!options.tokenProvider && (!options.token || options.token.length < 16 || options.token.length > 4096))
+            throw new Error('OAUTH_FILE_TOKEN_INVALID');
+        this.credentials = options;
+        const authenticated = authorizedFetch(options.fetchImpl ?? fetch, options, this.root.origin);
+        this.fetchImpl = (input, init) => new Headers(init?.headers).has('authorization') ? authenticated(input, init) : (options.fetchImpl ?? fetch)(input, init);
+    }
+    /** 公开 v3 元数据无需凭据；读取失败时清除缓存以便下次重试。 */
+    async discover() {
+        if (!this.providerPromise) {
+            this.providerPromise = (async () => {
+                const url = new URL(`${this.root.pathname === '/' ? '' : this.root.pathname}/v3/provider`, this.root.origin);
+                let response;
+                try {
+                    response = await this.fetchImpl(url, { method: 'GET', headers: { accept: 'application/json' }, redirect: 'error' });
+                }
+                catch {
+                    throw new Error('OAUTH_FILE_DISCOVERY_FAILURE');
+                }
+                if (!response.ok)
+                    throw new Error('OAUTH_FILE_DISCOVERY_FAILURE');
+                let raw;
+                try {
+                    raw = await response.json();
+                }
+                catch {
+                    throw new Error('OAUTH_FILE_DISCOVERY_INVALID');
+                }
+                const provider = knowledgeMcpProviderContractV3Schema.parse(raw);
+                for (const value of [provider.contentEndpoint, provider.evidenceFileEndpoint, provider.mediaEndpoint])
+                    if (!value)
+                        throw new Error('OAUTH_FILE_ENDPOINT_MISSING');
+                    else
+                        parseEndpoint(value, this.root.origin);
+                return provider;
+            })().catch(error => { this.providerPromise = null; throw error; });
+        }
+        return this.providerPromise;
+    }
+    async discoverMaterials() {
+        if (!this.materialProviderPromise) {
+            this.materialProviderPromise = (async () => {
+                const url = new URL(`${this.root.pathname === '/' ? '' : this.root.pathname}/v6/provider`, this.root.origin);
+                let response;
+                try {
+                    response = await this.fetchImpl(url, { method: 'GET', headers: { accept: 'application/json' }, redirect: 'error' });
+                }
+                catch {
+                    throw new Error('OAUTH_MATERIAL_DISCOVERY_FAILURE');
+                }
+                if (!response.ok)
+                    throw new Error('OAUTH_MATERIAL_DISCOVERY_FAILURE');
+                let raw;
+                try {
+                    raw = await response.json();
+                }
+                catch {
+                    throw new Error('OAUTH_MATERIAL_DISCOVERY_INVALID');
+                }
+                const provider = knowledgeMcpProviderContractV6Schema.parse(raw);
+                parseEndpoint(provider.materialPageEndpoint, this.root.origin);
+                parseEndpoint(provider.materialEndpoint, this.root.origin);
+                parseEndpoint(provider.materialPresentationEndpoint, this.root.origin);
+                return provider;
+            })().catch(error => { this.materialProviderPromise = null; throw error; });
+        }
+        return this.materialProviderPromise;
+    }
+    /** Explicit v7 Agent discovery leaves the stable v6 HTTP file contract untouched. */
+    async discoverAgentMaterials() {
+        if (!this.agentMaterialProviderPromise) {
+            this.agentMaterialProviderPromise = (async () => {
+                const url = new URL(`${this.root.pathname === '/' ? '' : this.root.pathname}/v7/provider`, this.root.origin);
+                let response;
+                try {
+                    response = await this.fetchImpl(url, { method: 'GET', headers: { accept: 'application/json' }, redirect: 'error' });
+                }
+                catch {
+                    throw new Error('OAUTH_AGENT_DISCOVERY_FAILURE');
+                }
+                if (!response.ok)
+                    throw new Error('OAUTH_AGENT_DISCOVERY_FAILURE');
+                let raw;
+                try {
+                    raw = await response.json();
+                }
+                catch {
+                    throw new Error('OAUTH_AGENT_DISCOVERY_INVALID');
+                }
+                const provider = knowledgeMcpProviderContractV7Schema.parse(raw);
+                for (const value of [provider.endpoint, provider.materialPageEndpoint, provider.materialEndpoint, provider.materialPresentationEndpoint])
+                    if (!value)
+                        throw new Error('OAUTH_AGENT_ENDPOINT_MISSING');
+                    else
+                        parseEndpoint(value, this.root.origin);
+                for (const name of ['knowledge_material_list', 'knowledge_material_describe', 'knowledge_material_read', 'knowledge_material_changes'])
+                    if (!provider.tools.some(tool => tool.name === name && tool.requiredScope === 'knowledge.material.read'))
+                        throw new Error('OAUTH_AGENT_TOOL_MISSING');
+                return provider;
+            })().catch(error => { this.agentMaterialProviderPromise = null; throw error; });
+        }
+        return this.agentMaterialProviderPromise;
+    }
+    /** v8 only describes the bounded descriptive index; result coverage is reported per query. */
+    async discoverSearchMaterials() {
+        if (!this.searchMaterialProviderPromise) {
+            this.searchMaterialProviderPromise = (async () => {
+                const url = new URL(`${this.root.pathname === '/' ? '' : this.root.pathname}/v8/provider`, this.root.origin);
+                let response;
+                try {
+                    response = await this.fetchImpl(url, { method: 'GET', headers: { accept: 'application/json' }, redirect: 'error' });
+                }
+                catch {
+                    throw new Error('OAUTH_MATERIAL_SEARCH_DISCOVERY_FAILURE');
+                }
+                if (!response.ok)
+                    throw new Error('OAUTH_MATERIAL_SEARCH_DISCOVERY_FAILURE');
+                let raw;
+                try {
+                    raw = await response.json();
+                }
+                catch {
+                    throw new Error('OAUTH_MATERIAL_SEARCH_DISCOVERY_INVALID');
+                }
+                const provider = knowledgeMcpProviderContractV8Schema.parse(raw);
+                for (const value of [provider.endpoint, provider.materialPageEndpoint, provider.materialEndpoint, provider.materialPresentationEndpoint, provider.materialSearchEndpoint])
+                    if (!value)
+                        throw new Error('OAUTH_MATERIAL_SEARCH_ENDPOINT_MISSING');
+                    else
+                        parseEndpoint(value, this.root.origin);
+                if (!provider.tools.some(tool => tool.name === 'knowledge_material_search' && tool.requiredScope === 'knowledge.material.read'))
+                    throw new Error('OAUTH_MATERIAL_SEARCH_TOOL_MISSING');
+                return provider;
+            })().catch(error => { this.searchMaterialProviderPromise = null; throw error; });
+        }
+        return this.searchMaterialProviderPromise;
+    }
+    async discoverRouteMaterials() {
+        if (!this.routeMaterialProviderPromise) {
+            this.routeMaterialProviderPromise = (async () => {
+                const url = new URL(`${this.root.pathname === '/' ? '' : this.root.pathname}/v9/provider`, this.root.origin);
+                let response;
+                try {
+                    response = await this.fetchImpl(url, { method: 'GET', headers: { accept: 'application/json' }, redirect: 'error' });
+                }
+                catch {
+                    throw new Error('OAUTH_MATERIAL_ROUTE_DISCOVERY_FAILURE');
+                }
+                if (!response.ok)
+                    throw new Error('OAUTH_MATERIAL_ROUTE_DISCOVERY_FAILURE');
+                let raw;
+                try {
+                    raw = await response.json();
+                }
+                catch {
+                    throw new Error('OAUTH_MATERIAL_ROUTE_DISCOVERY_INVALID');
+                }
+                const provider = knowledgeMcpProviderContractV9Schema.parse(raw);
+                parseEndpoint(provider.materialRoutePageEndpoint, this.root.origin);
+                return provider;
+            })().catch(error => { this.routeMaterialProviderPromise = null; throw error; });
+        }
+        return this.routeMaterialProviderPromise;
+    }
+    async discoverPartitionedMaterials() {
+        if (!this.partitionMaterialProviderPromise) {
+            this.partitionMaterialProviderPromise = (async () => {
+                const url = new URL(`${this.root.pathname === '/' ? '' : this.root.pathname}/v10/provider`, this.root.origin);
+                let response;
+                try {
+                    response = await this.fetchImpl(url, { method: 'GET', headers: { accept: 'application/json' }, redirect: 'error' });
+                }
+                catch {
+                    throw new Error('OAUTH_MATERIAL_PARTITION_DISCOVERY_FAILURE');
+                }
+                if (!response.ok)
+                    throw new Error('OAUTH_MATERIAL_PARTITION_DISCOVERY_FAILURE');
+                let raw;
+                try {
+                    raw = await response.json();
+                }
+                catch {
+                    throw new Error('OAUTH_MATERIAL_PARTITION_DISCOVERY_INVALID');
+                }
+                const provider = knowledgeMcpProviderContractV10Schema.parse(raw);
+                parseEndpoint(provider.materialPartitionsEndpoint, this.root.origin);
+                parseEndpoint(provider.materialPartitionPageEndpoint, this.root.origin);
+                parseEndpoint(provider.materialRoutePageEndpoint, this.root.origin);
+                return provider;
+            })().catch(error => { this.partitionMaterialProviderPromise = null; throw error; });
+        }
+        return this.partitionMaterialProviderPromise;
+    }
+    async discoverMaterialSync() {
+        if (!this.syncMaterialProviderPromise) {
+            this.syncMaterialProviderPromise = (async () => {
+                const url = new URL(`${this.root.pathname === '/' ? '' : this.root.pathname}/v11/provider`, this.root.origin);
+                let response;
+                try {
+                    response = await this.fetchImpl(url, { method: 'GET', headers: { accept: 'application/json' }, redirect: 'error' });
+                }
+                catch {
+                    throw new Error('OAUTH_MATERIAL_SYNC_DISCOVERY_FAILURE');
+                }
+                if (!response.ok)
+                    throw new Error('OAUTH_MATERIAL_SYNC_DISCOVERY_FAILURE');
+                const provider = knowledgeMcpProviderContractV11Schema.parse(await response.json());
+                parseEndpoint(provider.materialOutboxWindowEndpoint, this.root.origin);
+                if (!provider.tools.some(tool => tool.name === 'knowledge_material_window' && tool.requiredScope === 'knowledge.material.read'))
+                    throw new Error('OAUTH_MATERIAL_SYNC_TOOL_MISSING');
+                return provider;
+            })().catch(error => { this.syncMaterialProviderPromise = null; throw error; });
+        }
+        return this.syncMaterialProviderPromise;
+    }
+    async discoverMaterialCapabilities() {
+        if (!this.capabilityProviderPromise)
+            this.capabilityProviderPromise = (async () => {
+                const url = new URL(`${this.root.pathname === '/' ? '' : this.root.pathname}/v12/provider`, this.root.origin), response = await this.fetchImpl(url, { method: 'GET', headers: { accept: 'application/json' }, redirect: 'error' });
+                if (!response.ok)
+                    throw new Error('OAUTH_MATERIAL_CAPABILITY_DISCOVERY_FAILURE');
+                const provider = knowledgeMcpProviderContractV12Schema.parse(await response.json());
+                for (const endpoint of [provider.materialEndpoint, provider.materialCapabilitiesEndpoint, provider.materialCapabilityPageEndpoint, provider.materialMediaPageEndpoint, provider.materialIndexStatusEndpoint])
+                    parseEndpoint(endpoint, this.root.origin);
+                for (const name of ['knowledge_material_capabilities', 'knowledge_material_media', 'knowledge_material_index_status'])
+                    if (!provider.tools.some(tool => tool.name === name && tool.requiredScope === 'knowledge.material.read'))
+                        throw new Error('OAUTH_MATERIAL_CAPABILITY_TOOL_MISSING');
+                return provider;
+            })().catch(error => { this.capabilityProviderPromise = null; throw error; });
+        return this.capabilityProviderPromise;
+    }
+    async capabilityGet(endpoint, params, schema) {
+        const value = await this.partitionGet(endpoint, params, schema);
+        if (value.projectRef !== this.projectRef)
+            throw new Error('OAUTH_MATERIAL_CAPABILITY_SCOPE_MISMATCH');
+        return value;
+    }
+    async getMaterialCapabilities(ref) { const provider = await this.discoverMaterialCapabilities(); return this.capabilityGet(provider.materialCapabilitiesEndpoint, { ref }, oauthMaterialCapabilityResponseSchema); }
+    async pageMaterialCapabilities(options = {}) { const provider = await this.discoverMaterialCapabilities(); return this.capabilityGet(provider.materialCapabilityPageEndpoint, options, oauthMaterialCapabilityPageSchema); }
+    async pageMaterialMedia(ref, options = {}) { const provider = await this.discoverMaterialCapabilities(); return this.capabilityGet(provider.materialMediaPageEndpoint, { ref, ...options }, oauthMaterialMediaCapabilityPageSchema); }
+    async getMaterialIndexStatus(options = {}) { const provider = await this.discoverMaterialCapabilities(); return this.capabilityGet(provider.materialIndexStatusEndpoint, options, oauthMaterialIndexStatusSchema); }
+    async openMaterialStream(ref, options = {}) { const provider = await this.discoverMaterialCapabilities(), url = parseEndpoint(provider.materialEndpoint, this.root.origin); url.searchParams.set('project_ref', this.projectRef); url.searchParams.set('ref', ref); return materialStream(this.fetchImpl, url, await tokenValue(this.credentials), options); }
+    async getMaterialOutboxWindow() {
+        const provider = await this.discoverMaterialSync();
+        return this.partitionGet(provider.materialOutboxWindowEndpoint, {}, materialOutboxWindowSchema);
+    }
+    async partitionGet(endpoint, params, schema) {
+        const url = parseEndpoint(endpoint, this.root.origin);
+        url.searchParams.set('project_ref', this.projectRef);
+        for (const [key, value] of Object.entries(params))
+            if (value !== undefined)
+                url.searchParams.set(key, String(value));
+        let response;
+        try {
+            response = await this.fetchImpl(url, { method: 'GET', headers: { authorization: `Bearer ${await tokenValue(this.credentials)}`, accept: 'application/json' }, redirect: 'error' });
+        }
+        catch {
+            throw new Error('OAUTH_MATERIAL_PARTITION_TRANSPORT_FAILURE');
+        }
+        if (!response.ok)
+            throw new Error(response.status === 401 ? 'OAUTH_FILE_UNAUTHORIZED' : response.status === 403 ? 'OAUTH_FILE_FORBIDDEN' : 'OAUTH_MATERIAL_PARTITION_PAGE_FAILURE');
+        let raw;
+        try {
+            raw = await response.json();
+        }
+        catch {
+            throw new Error('OAUTH_MATERIAL_PARTITION_PAGE_INVALID');
+        }
+        return schema.parse(raw);
+    }
+    async pageMaterialPartitions(options = {}) {
+        const provider = await this.discoverPartitionedMaterials();
+        if (options.afterRouteId && !/^[a-f0-9]{64}$/.test(options.afterRouteId))
+            throw new Error('OAUTH_MATERIAL_ROUTE_ID_INVALID');
+        const page = await this.partitionGet(provider.materialPartitionsEndpoint, { after_route_id: options.afterRouteId, limit: options.limit }, oauthMaterialPartitionsResponseSchema);
+        if (page.projectRef !== this.projectRef)
+            throw new Error('OAUTH_MATERIAL_PARTITION_SCOPE_MISMATCH');
+        return page;
+    }
+    async pageMaterialPartition(partition, options = {}) {
+        const provider = await this.discoverPartitionedMaterials();
+        const page = await this.partitionGet(provider.materialPartitionPageEndpoint, { partition, after: options.after, limit: options.limit }, oauthMaterialPartitionPageResponseSchema);
+        if (page.projectRef !== this.projectRef || page.partition !== partition)
+            throw new Error('OAUTH_MATERIAL_PARTITION_SCOPE_MISMATCH');
+        return page;
+    }
+    async searchMaterials(query, options = {}) {
+        const input = knowledgeMaterialSearchInputSchema.parse({ projectRef: this.projectRef, query, ...options });
+        const provider = await this.discoverSearchMaterials(), url = parseEndpoint(provider.materialSearchEndpoint, this.root.origin);
+        url.searchParams.set('project_ref', input.projectRef);
+        url.searchParams.set('query', input.query);
+        if (input.afterId !== undefined)
+            url.searchParams.set('after_id', String(input.afterId));
+        if (input.limit !== undefined)
+            url.searchParams.set('limit', String(input.limit));
+        if (input.resourceType)
+            url.searchParams.set('resource_type', input.resourceType);
+        if (input.sourceProjectKey)
+            url.searchParams.set('source_project_key', input.sourceProjectKey);
+        let response;
+        try {
+            response = await this.fetchImpl(url, { method: 'GET', headers: { authorization: `Bearer ${await tokenValue(this.credentials)}`, accept: 'application/json' }, redirect: 'error' });
+        }
+        catch {
+            throw new Error('OAUTH_MATERIAL_SEARCH_TRANSPORT_FAILURE');
+        }
+        if (!response.ok)
+            throw new Error(response.status === 401 ? 'OAUTH_FILE_UNAUTHORIZED' : response.status === 403 ? 'OAUTH_FILE_FORBIDDEN' : 'OAUTH_MATERIAL_SEARCH_FAILURE');
+        let raw;
+        try {
+            raw = await response.json();
+        }
+        catch {
+            throw new Error('OAUTH_MATERIAL_SEARCH_RESPONSE_INVALID');
+        }
+        const result = knowledgeMaterialSearchResponseSchema.parse(raw);
+        if (result.projectRef !== this.projectRef)
+            throw new Error('OAUTH_MATERIAL_SEARCH_SCOPE_MISMATCH');
+        return result;
+    }
+    async pageMaterials(resourceType, options = {}) {
+        const provider = await this.discoverMaterials(), url = parseEndpoint(provider.materialPageEndpoint, this.root.origin);
+        url.searchParams.set('project_ref', this.projectRef);
+        url.searchParams.set('resource_type', resourceType);
+        if (options.after)
+            url.searchParams.set('after', options.after);
+        if (options.limit !== undefined)
+            url.searchParams.set('limit', String(options.limit));
+        let response;
+        try {
+            response = await this.fetchImpl(url, { method: 'GET', headers: { authorization: `Bearer ${await tokenValue(this.credentials)}`, accept: 'application/json' }, redirect: 'error' });
+        }
+        catch {
+            throw new Error('OAUTH_MATERIAL_TRANSPORT_FAILURE');
+        }
+        if (!response.ok)
+            throw new Error(response.status === 401 ? 'OAUTH_FILE_UNAUTHORIZED' : response.status === 403 ? 'OAUTH_FILE_FORBIDDEN' : 'OAUTH_MATERIAL_PAGE_FAILURE');
+        let raw;
+        try {
+            raw = await response.json();
+        }
+        catch {
+            throw new Error('OAUTH_MATERIAL_PAGE_INVALID');
+        }
+        const page = oauthMaterialPageResponseSchema.parse(raw);
+        if (page.projectRef !== this.projectRef || page.resourceType !== resourceType)
+            throw new Error('OAUTH_MATERIAL_PAGE_SCOPE_MISMATCH');
+        return page;
+    }
+    pageAllMaterials(options = {}) { return this.pageMaterials('all', options); }
+    async pageRouteMaterials(routeId, options = {}) {
+        if (!/^[a-f0-9]{64}$/.test(routeId))
+            throw new Error('OAUTH_MATERIAL_ROUTE_ID_INVALID');
+        const provider = await this.discoverRouteMaterials(), url = parseEndpoint(provider.materialRoutePageEndpoint, this.root.origin);
+        url.searchParams.set('project_ref', this.projectRef);
+        url.searchParams.set('route_id', routeId);
+        if (options.after)
+            url.searchParams.set('after', options.after);
+        if (options.limit !== undefined)
+            url.searchParams.set('limit', String(options.limit));
+        let response;
+        try {
+            response = await this.fetchImpl(url, { method: 'GET', headers: { authorization: `Bearer ${await tokenValue(this.credentials)}`, accept: 'application/json' }, redirect: 'error' });
+        }
+        catch {
+            throw new Error('OAUTH_MATERIAL_ROUTE_TRANSPORT_FAILURE');
+        }
+        if (!response.ok)
+            throw new Error(response.status === 401 ? 'OAUTH_FILE_UNAUTHORIZED' : response.status === 403 ? 'OAUTH_FILE_FORBIDDEN' : 'OAUTH_MATERIAL_ROUTE_PAGE_FAILURE');
+        let raw;
+        try {
+            raw = await response.json();
+        }
+        catch {
+            throw new Error('OAUTH_MATERIAL_ROUTE_PAGE_INVALID');
+        }
+        const page = oauthMaterialRoutePageResponseSchema.parse(raw);
+        if (page.projectRef !== this.projectRef || page.routeId !== routeId)
+            throw new Error('OAUTH_MATERIAL_ROUTE_PAGE_SCOPE_MISMATCH');
+        return page;
+    }
+    async getMaterialPresentation(ref) {
+        if (!ref.startsWith('evidence://') || ref.length > 4096)
+            throw new Error('OAUTH_FILE_REF_INVALID');
+        const provider = await this.discoverMaterials(), url = parseEndpoint(provider.materialPresentationEndpoint, this.root.origin);
+        url.searchParams.set('project_ref', this.projectRef);
+        url.searchParams.set('ref', ref);
+        let response;
+        try {
+            response = await this.fetchImpl(url, { method: 'GET', headers: { authorization: `Bearer ${await tokenValue(this.credentials)}`, accept: 'application/json' }, redirect: 'error' });
+        }
+        catch {
+            throw new Error('OAUTH_MATERIAL_TRANSPORT_FAILURE');
+        }
+        if (response.status === 401)
+            throw new Error('OAUTH_FILE_UNAUTHORIZED');
+        let raw;
+        try {
+            raw = await response.json();
+        }
+        catch {
+            throw new Error('OAUTH_MATERIAL_PRESENTATION_INVALID');
+        }
+        const result = oauthMaterialPresentationResponseSchema.parse(raw);
+        if (result.projectRef !== this.projectRef || result.presentation && result.presentation.sourceEvidenceRef !== ref)
+            throw new Error('OAUTH_MATERIAL_PRESENTATION_SCOPE_MISMATCH');
+        return result;
+    }
+    async getMaterial(ref, expected) {
+        if (!ref || ref.length > 4096)
+            throw new Error('OAUTH_FILE_REF_INVALID');
+        const provider = await this.discoverMaterials(), url = parseEndpoint(provider.materialEndpoint, this.root.origin);
+        url.searchParams.set('project_ref', this.projectRef);
+        url.searchParams.set('ref', ref);
+        let response;
+        try {
+            response = await this.fetchImpl(url, { method: 'GET', headers: { authorization: `Bearer ${await tokenValue(this.credentials)}`, accept: 'application/octet-stream,application/json' }, redirect: 'error' });
+        }
+        catch {
+            throw new Error('OAUTH_FILE_TRANSPORT_FAILURE');
+        }
+        if (response.status === 200) {
+            const expectedClass = ref.startsWith('evidence://') ? 'RAW_EVIDENCE' : ref.startsWith('rich-media://') ? 'RAW_EVIDENCE_MEDIA' : ref.startsWith('reference://') ? 'REFERENCE_SNAPSHOT' : null, actualClass = response.headers.get('x-knowledge-content-class');
+            if (response.headers.get('x-knowledge-serving-action') !== 'ALLOW' || (expectedClass ? actualClass !== expectedClass : !['ARTIFACT_SNAPSHOT', 'REGISTERED_MATERIAL'].includes(actualClass ?? '')))
+                throw new Error('OAUTH_MATERIAL_CLASS_INVALID');
+            const content = Buffer.from(await response.arrayBuffer()), contentHash = response.headers.get('x-knowledge-content-hash'), mediaType = response.headers.get('content-type'), rawLength = response.headers.get('content-length'), assessedAt = response.headers.get('x-knowledge-assessed-at'), byteLength = Number(rawLength);
+            if (!contentHash || !mediaType || !rawLength || !assessedAt || !Number.isSafeInteger(byteLength) || byteLength !== content.byteLength || digest(content) !== contentHash || expected && (expected.contentHash !== contentHash || expected.mediaType !== mediaType || expected.byteLength !== byteLength))
+                throw new Error('OAUTH_FILE_INTEGRITY_MISMATCH');
+            return { decision: servingDecisionSchema.parse({ schemaVersion: 1, action: 'ALLOW', reasonCodes: [], assessedAt }), descriptor: { contentHash, mediaType, byteLength }, content };
+        }
+        if (response.status === 401)
+            throw new Error('OAUTH_FILE_UNAUTHORIZED');
+        let raw;
+        try {
+            raw = await response.json();
+        }
+        catch {
+            throw new Error('OAUTH_FILE_RESPONSE_INVALID');
+        }
+        if (raw && typeof raw === 'object' && !Array.isArray(raw)) {
+            const body = raw, decision = servingDecisionSchema.safeParse(body.decision);
+            if (decision.success && typeof body.error === 'string')
+                return { decision: decision.data, error: body.error };
+        }
+        throw new Error(response.status === 403 ? 'OAUTH_FILE_FORBIDDEN' : 'OAUTH_FILE_HTTP_FAILURE');
+    }
+    async read(kind, ref, expected) {
+        if (!ref || ref.length > 4096)
+            throw new Error('OAUTH_FILE_REF_INVALID');
+        const provider = await this.discover(), endpoint = kind === 'content' ? provider.contentEndpoint : kind === 'evidenceFile' ? provider.evidenceFileEndpoint : provider.mediaEndpoint;
+        if (!endpoint)
+            throw new Error('OAUTH_FILE_ENDPOINT_MISSING');
+        const url = parseEndpoint(endpoint, this.root.origin);
+        url.searchParams.set('project_ref', this.projectRef);
+        url.searchParams.set('ref', ref);
+        let response;
+        try {
+            response = await this.fetchImpl(url, { method: 'GET', headers: { authorization: `Bearer ${await tokenValue(this.credentials)}`, accept: 'application/octet-stream,application/json' }, redirect: 'error' });
+        }
+        catch {
+            throw new Error('OAUTH_FILE_TRANSPORT_FAILURE');
+        }
+        if (response.status === 200) {
+            if (response.headers.get('x-knowledge-serving-action') !== 'ALLOW')
+                throw new Error('OAUTH_FILE_ACTION_INVALID');
+            if (kind === 'evidenceFile' && response.headers.get('x-knowledge-evidence-class') !== 'RAW_EVIDENCE')
+                throw new Error('OAUTH_FILE_EVIDENCE_CLASS_MISSING');
+            const content = Buffer.from(await response.arrayBuffer()), contentHash = response.headers.get('x-knowledge-content-hash'), mediaType = response.headers.get('content-type'), rawLength = response.headers.get('content-length'), assessedAt = response.headers.get('x-knowledge-assessed-at');
+            if (!contentHash || !mediaType || !rawLength || !assessedAt || !/^[-\w.+]+\/[-\w.+]+(?:\s*;.*)?$/i.test(mediaType))
+                throw new Error('OAUTH_FILE_HEADERS_INVALID');
+            const byteLength = Number(rawLength);
+            if (!Number.isSafeInteger(byteLength) || byteLength !== content.byteLength || digest(content) !== contentHash || expected && (expected.contentHash !== contentHash || expected.mediaType !== mediaType || expected.byteLength !== byteLength))
+                throw new Error('OAUTH_FILE_INTEGRITY_MISMATCH');
+            const decision = servingDecisionSchema.parse({ schemaVersion: 1, action: 'ALLOW', reasonCodes: [], assessedAt });
+            return { decision, descriptor: { contentHash, mediaType, byteLength }, content };
+        }
+        if (response.status === 401)
+            throw new Error('OAUTH_FILE_UNAUTHORIZED');
+        let raw;
+        try {
+            raw = await response.json();
+        }
+        catch {
+            throw new Error('OAUTH_FILE_RESPONSE_INVALID');
+        }
+        if (raw && typeof raw === 'object' && !Array.isArray(raw)) {
+            const body = raw, decision = servingDecisionSchema.safeParse(body.decision);
+            if (decision.success && typeof body.error === 'string' && ['DENY', 'REVIEW_REQUIRED'].includes(decision.data.action))
+                return { decision: decision.data, error: body.error };
+        }
+        if (response.status === 403)
+            throw new Error('OAUTH_FILE_FORBIDDEN');
+        if (response.status === 503)
+            throw new Error('OAUTH_FILE_UNAVAILABLE');
+        throw new Error('OAUTH_FILE_HTTP_FAILURE');
+    }
+    getContent(ref, expected) { return this.read('content', ref, expected); }
+    /** 原始 Evidence 文件只代表已采集证据，不自动获得知识审核或 currentness 许可。 */
+    getEvidenceFile(ref, expected) { return this.read('evidenceFile', ref, expected); }
+    getMedia(ref, expected) { return this.read('media', ref, expected); }
+}

package/dist/resource.d.ts

@@ -0,0 +1,88 @@
+import { type TokenProvider } from './token-provider.js';
+/** Provider 16 客户端：Tenant 默认，Project 仅为显式收窄；正文复用既有有界流合同。 */
+import { resourceToolSchemas, resourceDataSchemas, type ResourceToolName, type MaterialContext, type MaterialAuthorityPolicy } from './internal/contracts/index.js';
+import { type MaterialStreamOptions } from './material-stream.js';
+type SharedOptions = {
+    baseUrl: string;
+    token?: string;
+    tokenProvider?: TokenProvider;
+    fetchImpl?: typeof fetch;
+    allowInsecureHttp?: boolean;
+    expectedTenantId?: string;
+};
+export type KnowledgeResourceClientOptions = SharedOptions & ({
+    authentication: 'API_KEY';
+    tenantId: string;
+} | {
+    authentication?: 'OAUTH';
+    tenantId?: never;
+});
+export type ResourceToolInput<K extends ResourceToolName> = ReturnType<(typeof resourceToolSchemas)[K]['parse']>;
+export type ResourceToolResponse<K extends ResourceToolName> = {
+    schemaVersion: 2;
+    context: MaterialContext;
+    policy: MaterialAuthorityPolicy;
+    data: ReturnType<(typeof resourceDataSchemas)[K]['parse']>;
+};
+export declare class ResourceSdkError extends Error {
+    readonly code: string;
+    readonly status: number;
+    readonly recovery: 'CAPTURE_WINDOW_AND_REBOOTSTRAP' | null;
+    constructor(code: string, status: number);
+}
+export declare class KnowledgeResourceClient {
+    private readonly options;
+    private readonly root;
+    private readonly basePath;
+    private readonly fetchImpl;
+    constructor(options: KnowledgeResourceClientOptions);
+    private url;
+    private request;
+    private json;
+    private context;
+    tool<K extends ResourceToolName>(name: K, raw: ResourceToolInput<K>): Promise<ResourceToolResponse<K>>;
+    contract(projectRef?: string): Promise<{
+        schemaVersion: 2;
+        context: {
+            type: "TENANT";
+            tenantId: string;
+            tenantRef: string;
+        } | {
+            type: "PROJECT";
+            tenantId: string;
+            projectKey: string;
+            projectRef: string;
+        };
+        policy: "LEGACY_PROJECT" | "TENANT_NATIVE" | "TENANT_PROJECT_SCOPE";
+        capabilities: ["TENANT_RESOURCE_V1", "TENANT_AUTHORITY_V1"];
+        callEndpoint: string;
+        fileEndpoint: string;
+        tools: string[];
+        inlineMaxBytes: 32768;
+        readBufferMaxBytes: 16777216;
+        fileMethods: ["GET", "HEAD", "POST"];
+        verificationChunkBytes: 65536;
+        requestMaxBytes: 131072;
+        resultMaxBytes: 524288;
+    }>;
+    list(input?: ResourceToolInput<'knowledge_resource_list'>): Promise<ResourceToolResponse<"knowledge_resource_list">>;
+    describe(ref: string, input?: {
+        projectRef?: string;
+    }): Promise<ResourceToolResponse<"knowledge_resource_describe">>;
+    read(ref: string, input?: {
+        projectRef?: string;
+    }): Promise<ResourceToolResponse<"knowledge_resource_read">>;
+    capabilities(ref: string, input?: {
+        projectRef?: string;
+    }): Promise<ResourceToolResponse<"knowledge_resource_capabilities">>;
+    search(query: string, input?: Omit<ResourceToolInput<'knowledge_resource_search'>, 'query'>): Promise<ResourceToolResponse<"knowledge_resource_search">>;
+    window(input?: ResourceToolInput<'knowledge_resource_window'>): Promise<ResourceToolResponse<"knowledge_resource_window">>;
+    changes(input?: ResourceToolInput<'knowledge_resource_changes'>): Promise<ResourceToolResponse<"knowledge_resource_changes">>;
+    counts(input?: ResourceToolInput<'knowledge_resource_counts'>): Promise<ResourceToolResponse<"knowledge_resource_counts">>;
+    indexStatus(input?: ResourceToolInput<'knowledge_resource_index_status'>): Promise<ResourceToolResponse<"knowledge_resource_index_status">>;
+    media(ref: string, input?: Omit<ResourceToolInput<'knowledge_resource_media'>, 'ref'>): Promise<ResourceToolResponse<"knowledge_resource_media">>;
+    stream(ref: string, options?: MaterialStreamOptions & {
+        projectRef?: string;
+    }): Promise<import("./material-stream.js").MaterialStreamResponse>;
+}
+export {};