@native-knowledge/knowledge-sdk 0.1.0-rc.1 → 0.1.0-rc.2

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 }) }); }
+}

package/dist/{types/sdk/index.d.ts → index.d.ts}

@@ -1,11 +1,10 @@
-import { type SdkTransportOptions } from './transport.js';
-export type { SdkTransportOptions } from './transport.js';
+/// <reference types="node" />
 import { type MaterialStreamOptions } from './material-stream.js';
 export * from './resource.js';
 export type { MaterialStreamOptions, MaterialStreamResponse } from './material-stream.js';
 export * from './oauth.js';
-import { type MaterialOutboxWindow, type ServingArtifactListResponse, type ServingArtifactPageResponse, type ServingArtifactMaterialPageResponse, type ServingArtifactMaterialResponse, type ServingMaterialPageResponse, type ServingMaterialRoutePageResponse, type ServingMaterialPartitionsResponse, type ServingMaterialPartitionPageResponse, type ServingMaterialSearchResponse, type ServingArtifactResponse, type ServingContentDecisionResponse, type ServingCurrentnessResponse, type ServingEvidenceListResponse, type ServingEvidencePageResponse, type ServingEvidencePresentationResponse, type ServingEvidenceResponse, type ServingHealthResponse, type ServingReferenceListResponse, type ServingReferenceLookupResponse, type ServingReferenceResponse, type ServingReferenceMaterialPageResponse, type ServingReferenceMaterialResponse, type ReferenceLookupFilter, type ServingProjectIntentResponse, type ServingProjectSourceListResponse, type ServingProjectSourceResponse, type ServingSourceResponse } from '../serving-contracts/index.js';
-export interface KnowledgeServingClientOptions extends SdkTransportOptions {
+import { type MaterialOutboxWindow, type ServingArtifactListResponse, type ServingArtifactPageResponse, type ServingArtifactMaterialPageResponse, type ServingArtifactMaterialResponse, type ServingMaterialPageResponse, type ServingMaterialRoutePageResponse, type ServingMaterialPartitionsResponse, type ServingMaterialPartitionPageResponse, type ServingMaterialSearchResponse, type ServingArtifactResponse, type ServingContentDecisionResponse, type ServingCurrentnessResponse, type ServingEvidenceListResponse, type ServingEvidencePageResponse, type ServingEvidencePresentationResponse, type ServingEvidenceResponse, type ServingHealthResponse, type ServingReferenceListResponse, type ServingReferenceLookupResponse, type ServingReferenceResponse, type ServingReferenceMaterialPageResponse, type ServingReferenceMaterialResponse, type ReferenceLookupFilter, type ServingProjectIntentResponse, type ServingProjectSourceListResponse, type ServingProjectSourceResponse, type ServingSourceResponse } from './internal/serving-contracts/index.js';
+export interface KnowledgeServingClientOptions {
     baseUrl: string;
     token: string;
     projectKey: string;
@@ -22,7 +21,6 @@ export interface ServingContentResponse {
     content: Buffer;
 }
 export declare class KnowledgeServingClient {
-    private readonly limits;
     readonly projectKey: string;
     private readonly root;
     private readonly basePath;
@@ -128,19 +126,19 @@ export declare class KnowledgeServingClient {
                 sourceProjectKey: string;
                 identityHash: string;
                 kind: string;
-                classification: "PUBLIC" | "PUBLIC_METADATA" | "TENANT" | "INTERNAL" | "FDE_INTERNAL" | "ACCESS_CONTROLLED" | "UNKNOWN";
+                classification: "TENANT" | "PUBLIC" | "PUBLIC_METADATA" | "INTERNAL" | "FDE_INTERNAL" | "ACCESS_CONTROLLED" | "UNKNOWN";
                 mediaType: string;
                 decision: {
                     schemaVersion: 1;
                     action: "ALLOW" | "DENY";
-                    reasonCodes: ("UNAVAILABLE" | "INTEGRITY_MISMATCH" | "NOT_FOUND" | "CONTENT_ACCESS_DENIED" | "UNSUPPORTED_RESOURCE")[];
+                    reasonCodes: ("NOT_FOUND" | "UNAVAILABLE" | "INTEGRITY_MISMATCH" | "CONTENT_ACCESS_DENIED" | "UNSUPPORTED_RESOURCE")[];
                     assessedAt: string;
                 };
             };
             materialAccess: {
                 schemaVersion: 1;
                 action: "ALLOW" | "DENY";
-                reasonCodes: ("UNAVAILABLE" | "INTEGRITY_MISMATCH" | "NOT_FOUND" | "CONTENT_ACCESS_DENIED" | "UNSUPPORTED_RESOURCE")[];
+                reasonCodes: ("NOT_FOUND" | "UNAVAILABLE" | "INTEGRITY_MISMATCH" | "CONTENT_ACCESS_DENIED" | "UNSUPPORTED_RESOURCE")[];
                 assessedAt: string;
             };
             representation: {
@@ -150,7 +148,7 @@ export declare class KnowledgeServingClient {
                 contentHash: string | null;
                 mediaType: string;
                 byteLength: number | null;
-                methods: ("HEAD" | "GET")[];
+                methods: ("GET" | "HEAD")[];
                 range: "NONE" | "SINGLE";
                 verification: "ON_READ";
                 verificationChunkBytes: number | null;
@@ -173,19 +171,19 @@ export declare class KnowledgeServingClient {
                 sourceProjectKey: string;
                 identityHash: string;
                 kind: string;
-                classification: "PUBLIC" | "PUBLIC_METADATA" | "TENANT" | "INTERNAL" | "FDE_INTERNAL" | "ACCESS_CONTROLLED" | "UNKNOWN";
+                classification: "TENANT" | "PUBLIC" | "PUBLIC_METADATA" | "INTERNAL" | "FDE_INTERNAL" | "ACCESS_CONTROLLED" | "UNKNOWN";
                 mediaType: string;
                 decision: {
                     schemaVersion: 1;
                     action: "ALLOW" | "DENY";
-                    reasonCodes: ("UNAVAILABLE" | "INTEGRITY_MISMATCH" | "NOT_FOUND" | "CONTENT_ACCESS_DENIED" | "UNSUPPORTED_RESOURCE")[];
+                    reasonCodes: ("NOT_FOUND" | "UNAVAILABLE" | "INTEGRITY_MISMATCH" | "CONTENT_ACCESS_DENIED" | "UNSUPPORTED_RESOURCE")[];
                     assessedAt: string;
                 };
             };
             materialAccess: {
                 schemaVersion: 1;
                 action: "ALLOW" | "DENY";
-                reasonCodes: ("UNAVAILABLE" | "INTEGRITY_MISMATCH" | "NOT_FOUND" | "CONTENT_ACCESS_DENIED" | "UNSUPPORTED_RESOURCE")[];
+                reasonCodes: ("NOT_FOUND" | "UNAVAILABLE" | "INTEGRITY_MISMATCH" | "CONTENT_ACCESS_DENIED" | "UNSUPPORTED_RESOURCE")[];
                 assessedAt: string;
             };
             representation: {
@@ -195,7 +193,7 @@ export declare class KnowledgeServingClient {
                 contentHash: string | null;
                 mediaType: string;
                 byteLength: number | null;
-                methods: ("HEAD" | "GET")[];
+                methods: ("GET" | "HEAD")[];
                 range: "NONE" | "SINGLE";
                 verification: "ON_READ";
                 verificationChunkBytes: number | null;
@@ -233,7 +231,7 @@ export declare class KnowledgeServingClient {
                 contentHash: string | null;
                 mediaType: string;
                 byteLength: number | null;
-                methods: ("HEAD" | "GET")[];
+                methods: ("GET" | "HEAD")[];
                 range: "NONE" | "SINGLE";
                 verification: "ON_READ";
                 verificationChunkBytes: number | null;
@@ -285,5 +283,8 @@ export * from './tenant-web-crawl.js';
 export * from './tenant-web-dynamic.js';
 export * from './tenant-web-content.js';
 export * from './tenant-web-workflow.js';
+export * from './auth.js';
+export * from './token-provider.js';
+export * from './tenant-client.js';
 export * from './agent-entry.js';
 export * from './agent-guidance-error.js';