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

package/dist/internal/serving-contracts/tenant-management.js

@@ -0,0 +1,89 @@
+/** 新 Tenant 管理工具共同合同；认证 context/actor/authority 只由 adapter 注入。 */
+import { z } from 'zod';
+import { parseTenantResourceRef, tenantStorageKey, tenantRawSubmissionSchema, tenantArtifactDraftSchema, tenantComposeInputSchema, tenantReviewInputSchema, tenantPromoteInputSchema, tenantSnapshotInputSchema, tenantShareInputSchema, tenantRevokeShareInputSchema, tenantResourceManifestSchema, tenantMaterialCurrentnessSchema, tenantSourceSemanticsSchema, tenantSourceIdSchema, tenantSourceSnapshotSchema, collectionRefreshSchema, tenantCollectionCycleSchema, tenantCollectionRequestSchema, tenantCollectionBatchSchema, tenantCollectionCompletionSchema, tenantCollectionFailureSchema, tenantResourceRefSchema, materialTenantIdSchema, sha256Schema, isoDateTimeSchema, stableUriSchema } from '../contracts/index.js';
+import { tenantWorkflowPlanSchema, tenantWorkflowPlanInputSchema, tenantWorkflowAdvanceInputSchema, tenantGovernedReadResultSchema } from './tenant-governance.js';
+const base64 = z.string().min(4).max(87384).regex(/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/), ref = z.object({ ref: tenantResourceRefSchema }).strict(), page = z.object({ after: z.string().min(1).max(128).optional(), limit: z.number().int().min(1).max(100).optional() }).strict(), source = z.object({ sourceId: tenantSourceIdSchema }).strict();
+export const tenantManagementToolSchemas = {
+    tenant_material_submit: tenantRawSubmissionSchema.extend({ contentBase64: base64 }).strict(),
+    tenant_artifact_draft: tenantArtifactDraftSchema.extend({ contentBase64: base64 }).strict(),
+    tenant_knowledge_compose: tenantComposeInputSchema,
+    tenant_knowledge_review: tenantReviewInputSchema,
+    tenant_artifact_promote: tenantPromoteInputSchema,
+    tenant_snapshot_declare: tenantSnapshotInputSchema,
+    tenant_snapshot_status: ref,
+    tenant_material_share: tenantShareInputSchema,
+    tenant_material_revoke: tenantRevokeShareInputSchema,
+    tenant_material_routes: page,
+    tenant_workflow_guide: z.object({}).strict(),
+    tenant_workflow_plan: tenantWorkflowPlanInputSchema,
+    tenant_workflow_advance: tenantWorkflowAdvanceInputSchema,
+    tenant_knowledge_read: ref,
+    tenant_source_define: z.object({ definition: z.object({ schemaVersion: z.literal(1), sourceId: tenantSourceIdSchema, title: z.string().trim().min(1).max(512), semantics: tenantSourceSemanticsSchema }).strict(), expectedGeneration: z.number().int().positive().safe().nullable() }).strict(),
+    tenant_source_configure: source.extend({ expectedGeneration: z.number().int().positive().safe(), paused: z.boolean(), tenantEnabled: z.boolean(), refresh: collectionRefreshSchema }).strict(),
+    tenant_source_get: source,
+    tenant_source_list: page,
+    tenant_collection_request: z.object({ requestId: tenantCollectionCycleSchema, sourceId: tenantSourceIdSchema, expectedSourceRevisionRef: stableUriSchema.optional(), cycleId: tenantCollectionCycleSchema.optional() }).strict(),
+    tenant_collection_status: z.object({ requestId: tenantCollectionCycleSchema }).strict(),
+};
+/** 固定能力索引；promote/advance 的调用鉴权必须使用 scopesForInput，发现使用 Authorization。 */
+export const tenantManagementToolScopes = { tenant_material_submit: 'knowledge.material.write', tenant_artifact_draft: 'knowledge.material.write', tenant_knowledge_compose: 'knowledge.compose', tenant_knowledge_review: 'knowledge.review', tenant_artifact_promote: 'knowledge.material.write', tenant_snapshot_declare: 'knowledge.review', tenant_snapshot_status: 'knowledge.workflow.read', tenant_material_share: 'knowledge.material.route', tenant_material_revoke: 'knowledge.material.route', tenant_material_routes: 'knowledge.material.route', tenant_workflow_guide: 'knowledge.workflow.read', tenant_workflow_plan: 'knowledge.workflow.read', tenant_workflow_advance: 'knowledge.workflow.read', tenant_knowledge_read: 'knowledge.read', tenant_source_define: 'knowledge.source.manage', tenant_source_configure: 'knowledge.source.manage', tenant_source_get: 'knowledge.source.manage', tenant_source_list: 'knowledge.source.manage', tenant_collection_request: 'knowledge.collect', tenant_collection_status: 'knowledge.collect' };
+/** 初始动作能力来自同一输入合同；依赖原件读取等附加检查仍在 application。 */
+export function tenantManagementScopesForInput(name, raw) {
+    const input = tenantManagementToolSchemas[name].parse(raw);
+    if (name === 'tenant_artifact_promote')
+        return [tenantPromoteInputSchema.parse(input).nextStatus === 'READY_FOR_REVIEW' ? 'knowledge.material.write' : 'knowledge.approve'];
+    if (name === 'tenant_workflow_advance')
+        return ['knowledge.workflow.read', tenantWorkflowAdvanceInputSchema.parse(input).action === 'SUBMIT_REVIEW' ? 'knowledge.material.write' : 'knowledge.approve'];
+    return [tenantManagementToolScopes[name]];
+}
+export function tenantManagementAuthorization(name) {
+    if (name === 'tenant_artifact_promote')
+        return { selection: 'NEXT_STATUS', scopeAlternatives: [['knowledge.material.write'], ['knowledge.approve']] };
+    if (name === 'tenant_workflow_advance')
+        return { selection: 'WORKFLOW_ACTION', scopeAlternatives: [['knowledge.workflow.read', 'knowledge.material.write'], ['knowledge.workflow.read', 'knowledge.approve']] };
+    return { selection: 'FIXED', scopeAlternatives: [[tenantManagementToolScopes[name]]] };
+}
+// advance/promote 的实际动作、来源/审核读取能力继续由 application/context 逐项复核。
+const production = z.object({ phase: z.literal('REGISTERED'), ref: tenantResourceRefSchema, registered: z.boolean(), seq: z.number().int().positive(), manifestRevision: sha256Schema }).strict();
+const write = z.object({ inserted: z.boolean(), manifest: tenantResourceManifestSchema, production }).strict();
+const projection = z.object({ changed: z.boolean(), seq: z.number().int().positive(), assessmentRevision: sha256Schema }).strict();
+const route = z.object({ routeId: z.string().regex(/^[a-f0-9]{64}$/), ownerTenantId: materialTenantIdSchema, recipientTenantId: materialTenantIdSchema, sourceProjectKey: z.null(), matchType: z.enum(['SOURCE', 'REF']), matchValue: stableUriSchema, effect: z.enum(['ALLOW', 'DENY']), revokedAt: isoDateTimeSchema.nullable() }).strict();
+const routeChange = z.object({ changed: z.boolean(), route, completedPhase: z.literal('ROUTE_COMMITTED'), operationRef: stableUriSchema }).strict();
+const sourceHead = z.object({ tenantId: materialTenantIdSchema, sourceId: tenantSourceIdSchema, revisionRef: stableUriSchema, semanticKey: sha256Schema, generation: z.number().int().positive().safe(), paused: z.boolean(), tenantEnabled: z.boolean(), refresh: collectionRefreshSchema, snapshot: tenantSourceSnapshotSchema }).strict().superRefine((v, ctx) => { if (v.tenantId !== v.snapshot.tenantId || v.sourceId !== v.snapshot.sourceId || v.revisionRef !== v.snapshot.revisionRef || v.semanticKey !== v.snapshot.semanticKey)
+    ctx.addIssue({ code: 'custom', message: 'Source head preserves its exact snapshot identity' }); });
+const governedRead = tenantGovernedReadResultSchema.extend({ contentBase64: base64.max(43692).nullable(), truncated: z.boolean(), continuation: z.object({ kind: z.literal('AUTHENTICATED_TENANT_GOVERNED_CONTENT'), ref: tenantResourceRefSchema }).strict().nullable() }).strict().superRefine((v, ctx) => {
+    const length = v.contentBase64 === null ? 0 : v.contentBase64.length / 4 * 3 - (v.contentBase64.endsWith('==') ? 2 : v.contentBase64.endsWith('=') ? 1 : 0);
+    if (v.decision.action === 'ALLOW' ? (!v.descriptor || v.contentBase64 === null || length > 32768 || (v.truncated ? (!v.continuation || v.continuation.ref !== v.ref || v.descriptor.byteLength <= length) : (v.continuation !== null || v.descriptor.byteLength !== length))) : (v.descriptor !== null || v.contentBase64 !== null || v.truncated || v.continuation !== null))
+        ctx.addIssue({ code: 'custom', message: 'Governed inline data and continuation must match the actual content decision and full length' });
+});
+const guide = z.object({ schemaVersion: z.literal(2), tenantId: materialTenantIdSchema, authorityVersion: z.literal(2), scopes: z.array(z.string()).max(32), tools: z.array(z.object({ name: z.string(), authorization: z.object({ selection: z.enum(['FIXED', 'NEXT_STATUS', 'WORKFLOW_ACTION']), scopeAlternatives: z.array(z.array(z.string()).min(1).max(8)).min(1).max(4) }).strict(), inputSchema: z.json(), outputSchema: z.json() }).strict()).max(64), rules: z.array(z.string()).max(32), limits: z.object({ requestMaxBytes: z.literal(131072), resultMaxBytes: z.literal(524288), submissionMaxBytes: z.literal(65536) }).strict() }).strict();
+export const tenantManagementDataSchemas = {
+    tenant_material_submit: write, tenant_artifact_draft: write, tenant_knowledge_compose: write, tenant_knowledge_review: write, tenant_artifact_promote: write,
+    tenant_snapshot_declare: z.object({ subjectRef: tenantResourceRefSchema, declared: z.boolean(), declarationRef: stableUriSchema, assessment: tenantMaterialCurrentnessSchema, projection, completedPhase: z.literal('CURRENTNESS_NOTIFIED'), operationRef: stableUriSchema }).strict(),
+    tenant_snapshot_status: z.object({ subjectRef: tenantResourceRefSchema, state: z.enum(['NOT_AVAILABLE', 'NOT_DECLARED', 'PROJECTION_PENDING', 'READY', 'INTEGRITY_MISMATCH', 'UNAVAILABLE']), assessment: tenantMaterialCurrentnessSchema.nullable() }).strict(),
+    tenant_material_share: routeChange, tenant_material_revoke: routeChange, tenant_material_routes: z.object({ items: z.array(route).max(100), nextAfter: z.string().nullable() }).strict(),
+    tenant_workflow_guide: guide, tenant_workflow_plan: tenantWorkflowPlanSchema,
+    tenant_workflow_advance: z.object({ schemaVersion: z.literal(2), action: z.enum(['SUBMIT_REVIEW', 'FINALIZE_REVIEW']), previousRef: tenantResourceRefSchema, inserted: z.boolean(), production, plan: tenantWorkflowPlanSchema }).strict(),
+    tenant_knowledge_read: governedRead,
+    tenant_source_define: z.object({ changed: z.boolean(), reused: z.boolean(), phase: z.literal('SOURCE_REGISTERED'), head: sourceHead }).strict(),
+    tenant_source_configure: z.object({ changed: z.boolean(), head: sourceHead }).strict(), tenant_source_get: sourceHead.nullable(), tenant_source_list: z.object({ items: z.array(sourceHead).max(100), nextAfter: tenantSourceIdSchema.nullable() }).strict(),
+    tenant_collection_request: z.object({ inserted: z.boolean(), request: tenantCollectionRequestSchema, batch: tenantCollectionBatchSchema, phase: z.literal('BATCH_PERSISTED') }).strict(),
+    tenant_collection_status: z.object({ request: tenantCollectionRequestSchema, completion: tenantCollectionCompletionSchema.nullable(), failure: tenantCollectionFailureSchema.nullable().optional() }).strict().nullable(),
+};
+export const tenantManagementErrorCodeSchema = z.enum(['TENANT_MANAGEMENT_INVALID_INPUT', 'TENANT_MANAGEMENT_FORBIDDEN', 'TENANT_MANAGEMENT_AUTHORITY_CHANGED', 'TENANT_MANAGEMENT_RUNTIME_OWNER_REQUIRED', 'TENANT_MANAGEMENT_IDEMPOTENCY_CONFLICT', 'TENANT_MANAGEMENT_VERSION_CONFLICT', 'TENANT_MANAGEMENT_SOURCE_FORBIDDEN', 'TENANT_MANAGEMENT_REVIEW_REQUIRED', 'TENANT_MANAGEMENT_POLICY_BLOCKED', 'TENANT_MANAGEMENT_UNAVAILABLE', 'TENANT_MANAGEMENT_INCOMPLETE', 'TENANT_MANAGEMENT_INPUT_BUDGET', 'TENANT_MANAGEMENT_NOT_FOUND']);
+export const tenantManagementErrorSchema = z.object({ errorCode: tenantManagementErrorCodeSchema, completedPhase: z.enum(['VALIDATED', 'PERSISTED', 'CATALOG_PROJECTED', 'REGISTERED', 'ROUTE_COMMITTED', 'DECLARATION_PERSISTED', 'CURRENTNESS_RECORDED', 'CURRENTNESS_NOTIFIED', 'SOURCE_PERSISTED', 'SOURCE_REGISTERED', 'REQUEST_PERSISTED', 'BATCH_PERSISTED']).optional(), ref: stableUriSchema.optional() }).strict();
+export function tenantManagementEnvelopeSchema(tool) { return z.object({ schemaVersion: z.literal(2), tenantId: materialTenantIdSchema, tool: z.literal(tool), data: tenantManagementDataSchemas[tool] }).strict(); }
+export const tenantManagementInputJsonSchemas = Object.fromEntries(Object.entries(tenantManagementToolSchemas).map(([name, schema]) => [name, z.toJSONSchema(schema, { target: 'draft-07' })]));
+export const tenantManagementOutputJsonSchemas = Object.fromEntries(Object.keys(tenantManagementToolSchemas).map(name => [name, { type: 'object', oneOf: [z.toJSONSchema(tenantManagementEnvelopeSchema(name), { target: 'draft-07' }), z.toJSONSchema(tenantManagementErrorSchema, { target: 'draft-07' })] }]));
+export const tenantManagementProviderBaseSchema = z.object({ schemaVersion: z.literal(17), provider: z.literal('knowledge-v2'), codeRevision: z.string().min(1).max(128), authorityVersion: z.literal(2), context: z.literal('TENANT_EXPLICIT_MANAGEMENT_V1'), managementConfigured: z.boolean(), resource: stableUriSchema, issuer: stableUriSchema, authorizationEndpoint: stableUriSchema, tokenEndpoint: stableUriSchema, revocationEndpoint: stableUriSchema, mcpEndpoint: stableUriSchema, callEndpoint: stableUriSchema, contentEndpoint: stableUriSchema, contentContextHeader: z.literal('x-knowledge-tenant-id'), legacyProviderEndpoint: stableUriSchema, protocols: z.array(z.enum(['2026-07-28', '2025-06-18'])).min(1).max(2), tools: z.array(z.string()).length(Object.keys(tenantManagementToolSchemas).length), requestMaxBytes: z.literal(131072), resultMaxBytes: z.literal(524288), submissionMaxBytes: z.literal(65536), inlineContentMaxBytes: z.literal(32768), contentReadMaxBytes: z.literal(16777216), collectionMode: z.literal('MANUAL_ONLY_OAUTH'), capabilities: z.tuple([z.literal('TENANT_MANAGEMENT_V1'), z.literal('TENANT_WORKFLOW_V1'), z.literal('TENANT_CURRENTNESS_V2'), z.literal('TENANT_SOURCE_V1')]) }).strict();
+export const tenantManagementProviderSchema = tenantManagementProviderBaseSchema.superRefine((v, ctx) => { if (new Set(v.tools).size !== Object.keys(tenantManagementToolSchemas).length || v.tools.some(name => !Object.hasOwn(tenantManagementToolSchemas, name)))
+    ctx.addIssue({ code: 'custom', message: 'Provider tools must match the exact native tool contract' }); });
+/** 诊断 ref 只允许当前访问 Tenant 的 canonical 原生身份；不接受 URL/本机路径。 */
+export function tenantManagementSafeErrorRef(ref, tenantId) {
+    if (typeof ref !== 'string' || ref.length > 2048)
+        return undefined;
+    const key = tenantStorageKey(tenantId), resource = parseTenantResourceRef(ref);
+    if (resource?.storageKey === key)
+        return ref;
+    return new RegExp(`^(?:tenant-operation://${key}/[a-f0-9]{64}|tenant-collection-request://${key}/[a-f0-9]{64}|tenant-currentness://${key}/snapshot/[a-f0-9]{64}|tenant-source://${key}/[A-Za-z0-9][A-Za-z0-9._-]{0,127}(?:/v/[a-f0-9]{64})?)$`).test(ref) ? ref : undefined;
+}