create-windy 0.2.33 → 0.2.34

package/template/packages/server-sdk/src/module-host.ts

@@ -3,6 +3,7 @@ import type { ModuleAiOperationHandlerRegistration } from "./ai-operation-regist
 import type { ModuleRolePreset } from "./role-preset.js";
 import type { ModuleRouteDefinition } from "./route-definition.js";
 import type { ModuleSearchProvider } from "./search-provider-port.js";
+import type { ModuleResourceFileAccessPolicy } from "./storage-port.js";
 import type { ModuleTaskHandlerRegistration } from "./task-registration.js";
 import type { ModuleToolHandlerRegistration } from "./tool-registration.js";
 
@@ -25,6 +26,13 @@ export interface ModuleUploadPolicy {
 export interface ModuleHost {
   readonly moduleName: string;
   registerUploadPolicy(policy: ModuleUploadPolicy): void;
+  /**
+   * 注册跨上传者资源文件读取策略；purpose 必须由本模块或 Manifest 显式依赖模块的
+   * Upload Policy 声明，Feature、Permission 与 Audit Action 必须来自当前 Manifest。
+   */
+  registerResourceFileAccessPolicies(
+    policies: readonly ModuleResourceFileAccessPolicy[],
+  ): void;
   registerDurableHandler<T>(definition: DurableHandlerDefinition<T>): void;
   /** 注册 Guarded API 路由；须与 Manifest `apiPermissions` 声明一致。 */
   registerRoutes(routes: readonly ModuleRouteDefinition[]): void;

package/template/packages/server-sdk/src/request-context.ts

@@ -2,6 +2,7 @@ import type { ModuleActor } from "./actor.js";
 import type { ModuleAuditEmitter } from "./audit-port.js";
 import type { ModuleJobSubmitter } from "./jobs-port.js";
 import type { ModuleStoragePort } from "./storage-port.js";
+import type { ModuleUserDirectoryPort } from "./user-directory-port.js";
 
 /**
  * 模块路由 Handler 的受限请求上下文。
@@ -18,4 +19,5 @@ export interface ModuleRequestContext {
   readonly audit: ModuleAuditEmitter;
   readonly jobs: ModuleJobSubmitter;
   readonly storage: ModuleStoragePort;
+  readonly userDirectory: ModuleUserDirectoryPort;
 }

package/template/packages/server-sdk/src/storage-port.ts

@@ -1,4 +1,5 @@
 import type { OpenedFile, UploadSession } from "@southwind-ai/storage";
+import type { ModuleActor } from "./actor.js";
 
 export interface ModuleUploadSessionInput {
   readonly purpose: string;
@@ -9,6 +10,62 @@ export interface ModuleUploadSessionInput {
   readonly fileExpiresAt?: Date;
 }
 
+export interface ModuleResourceFileRequest {
+  /** 平台文件元数据 ID；不能是 ArtifactRef、对象存储 Key 或主机路径。 */
+  readonly fileId: string;
+  /**
+   * 必须与本模块或 Manifest 显式依赖模块注册的 Upload Policy，以及当前模块的
+   * 资源文件访问策略完全一致。
+   */
+  readonly purpose: string;
+  /** 本模块命名空间内的稳定业务资源类型，例如 `evidence.file`。 */
+  readonly resourceType: string;
+  /** 由授权策略回查业务 Repository 的稳定资源 ID。 */
+  readonly resourceId: string;
+}
+
+/** 资源授权读取仅返回业务所需的最小元数据与受限文件流。 */
+export interface ModuleOpenedResourceFile {
+  readonly id: string;
+  readonly purpose: string;
+  readonly filename: string;
+  readonly mimeType: string;
+  readonly byteSize: number;
+  readonly sha256: string;
+  readonly body: ReadableStream<Uint8Array>;
+}
+
+export interface ModuleResourceFileAccessContext {
+  readonly actor: ModuleActor;
+  readonly requestId: string;
+  readonly signal: AbortSignal;
+}
+
+/**
+ * 业务模块注册的资源到平台文件关联授权策略。
+ *
+ * `authorize` 必须从 project-owned Repository 回查 resourceId，确认当前 Actor
+ * 可访问该业务资源且该资源实际绑定 fileId；客户端或 Tool 输入不是授权证据。
+ */
+export interface ModuleResourceFileAccessPolicy {
+  /**
+   * 本模块或 Manifest 显式依赖模块拥有的 Upload Policy purpose；
+   * 平台基础 purpose 与未声明跨模块 purpose 均不可引用。
+   */
+  readonly purpose: string;
+  readonly resourceType: string;
+  readonly featureKey: string;
+  readonly permissionKey: string;
+  readonly auditAction: string;
+  authorize(
+    input: Readonly<{
+      fileId: string;
+      resourceId: string;
+    }>,
+    context: ModuleResourceFileAccessContext,
+  ): Promise<boolean> | boolean;
+}
+
 /**
  * 模块受限 Upload / BlobRead Port。
  *
@@ -22,4 +79,13 @@ export interface ModuleStoragePort {
   createUploadSession(input: ModuleUploadSessionInput): Promise<UploadSession>;
   openFile(fileId: string): Promise<OpenedFile>;
   openPublicFile(fileId: string, purpose: string): Promise<OpenedFile>;
+  /**
+   * 经 Host Feature / Permission 与业务资源策略双重授权后读取文件。
+   *
+   * 允许同一业务范围内跨上传者读取，但不授予任意 manage、Repository、BlobStore
+   * 或 ArtifactRef 能力。
+   */
+  openResourceFile(
+    input: ModuleResourceFileRequest,
+  ): Promise<ModuleOpenedResourceFile>;
 }

package/template/packages/server-sdk/src/tool-registration.ts

@@ -1,10 +1,16 @@
 import type { ModuleActor } from "./actor.js";
 import type { ModuleAiJsonValue } from "./ai-operation-registration.js";
+import type { ModuleStoragePort } from "./storage-port.js";
 
 export interface ModuleToolContext {
   readonly actor: ModuleActor;
   readonly requestId: string;
   readonly signal: AbortSignal;
+  /**
+   * 与当前 Tool Actor、请求范围和模块命名空间绑定的受限存储 Port。
+   * Host 未安装 Storage 时为 fail-closed 实现。
+   */
+  readonly storage: ModuleStoragePort;
 }
 
 export type ModuleToolInput = Readonly<Record<string, ModuleAiJsonValue>>;

package/template/packages/server-sdk/src/user-directory-port.ts

@@ -0,0 +1,42 @@
+export interface ModuleUserDirectoryQuery {
+  readonly page?: number;
+  readonly pageSize?: number;
+  readonly q?: string;
+}
+
+export interface ModuleUserDirectoryEntry {
+  readonly id: string;
+  readonly displayName: string;
+}
+
+export interface ModuleUserDirectoryPage {
+  readonly items: readonly ModuleUserDirectoryEntry[];
+  readonly total: number;
+  readonly page: number;
+  readonly pageSize: number;
+}
+
+export type ModuleUserDirectoryErrorCode =
+  | "USER_DIRECTORY_FORBIDDEN"
+  | "USER_DIRECTORY_UNAVAILABLE"
+  | "USER_DIRECTORY_INVALID_QUERY";
+
+export class ModuleUserDirectoryError extends Error {
+  constructor(
+    readonly code: ModuleUserDirectoryErrorCode,
+    message: string,
+  ) {
+    super(message);
+    this.name = "ModuleUserDirectoryError";
+  }
+}
+
+/**
+ * 业务模块使用的只读启用用户目录。
+ *
+ * Actor、租户、部门与 Data Scope 全部由宿主绑定；调用方只能提交分页和搜索条件。
+ * 宿主会执行 Feature、Permission、数据范围与审计，失败时不会降级为全量用户查询。
+ */
+export interface ModuleUserDirectoryPort {
+  list(query?: ModuleUserDirectoryQuery): Promise<ModuleUserDirectoryPage>;
+}