create-windy 0.5.1 → 0.6.0

package/template/apps/server/src/module-host/module-secret-result.ts

@@ -0,0 +1,274 @@
+import { isProxy } from "node:util/types";
+import type { ModuleSecretSafeValue } from "@southwind-ai/server-sdk";
+
+const MAX_DEPTH = 8;
+const MAX_ENTRIES = 1_024;
+const MAX_KEY_BYTES = 128;
+const MAX_STRING_BYTES = 65_536;
+const MAX_TOTAL_BYTES = 131_072;
+const dangerousKeys = new Set(["__proto__", "constructor", "prototype"]);
+const unsafeResult = Symbol("unsafe-module-secret-result");
+const encoder = new TextEncoder();
+const arrayIsArray = Array.isArray;
+const arrayPrototype = Array.prototype;
+const numberIsFinite = Number.isFinite;
+const numberIsSafeInteger = Number.isSafeInteger;
+const objectCreate = Object.create;
+const objectDefineProperty = Object.defineProperty;
+const objectFreeze = Object.freeze;
+const objectGetOwnPropertyDescriptor = Object.getOwnPropertyDescriptor;
+const objectGetOwnPropertyDescriptors = Object.getOwnPropertyDescriptors;
+const objectGetPrototypeOf = Object.getPrototypeOf;
+const objectIs = Object.is;
+const objectPrototype = Object.prototype;
+const objectSetPrototypeOf = Object.setPrototypeOf;
+const reflectOwnKeys = Reflect.ownKeys;
+const SetConstructor = Set;
+const setAdd = Function.prototype.call.bind(Set.prototype.add) as <T>(
+  set: Set<T>,
+  value: T,
+) => Set<T>;
+const setDelete = Function.prototype.call.bind(Set.prototype.delete) as <T>(
+  set: Set<T>,
+  value: T,
+) => boolean;
+const setHas = Function.prototype.call.bind(Set.prototype.has) as <T>(
+  set: ReadonlySet<T>,
+  value: T,
+) => boolean;
+const stringIncludes = Function.prototype.call.bind(
+  String.prototype.includes,
+) as (value: string, search: string) => boolean;
+const textEncode = Function.prototype.call.bind(
+  TextEncoder.prototype.encode,
+) as (encoder: TextEncoder, value: string) => Uint8Array;
+const safeArrayPrototype = createSafeArrayPrototype();
+
+type CanonicalResult<TResult> =
+  | { readonly ok: true; readonly value: TResult }
+  | { readonly ok: false };
+
+interface Budget {
+  entries: number;
+  bytes: number;
+  readonly seen: Set<object>;
+}
+
+export function canonicalizeModuleSecretResult<
+  TResult extends ModuleSecretSafeValue | void,
+>(value: TResult, secret: string): CanonicalResult<TResult> {
+  try {
+    const snapshot = snapshotValue(
+      value,
+      secret,
+      { entries: 0, bytes: 0, seen: new SetConstructor<object>() },
+      0,
+    );
+    return { ok: true, value: snapshot as TResult };
+  } catch {
+    return { ok: false };
+  }
+}
+
+function snapshotValue(
+  value: unknown,
+  secret: string,
+  budget: Budget,
+  depth: number,
+): ModuleSecretSafeValue | void {
+  if (depth > MAX_DEPTH) reject();
+  if (value === undefined) {
+    if (depth === 0) return undefined;
+    reject();
+  }
+  if (value === null || typeof value === "boolean") return value;
+  if (typeof value === "number") {
+    if (!numberIsFinite(value)) reject();
+    return objectIs(value, -0) ? 0 : value;
+  }
+  if (typeof value === "string") {
+    addBytes(budget, value, MAX_STRING_BYTES);
+    if (stringIncludes(value, secret)) reject();
+    return value;
+  }
+  if (typeof value !== "object" || isProxy(value)) reject();
+  if (setHas(budget.seen, value)) reject();
+  setAdd(budget.seen, value);
+  try {
+    return arrayIsArray(value)
+      ? snapshotArray(value, secret, budget, depth)
+      : snapshotObject(value, secret, budget, depth);
+  } finally {
+    setDelete(budget.seen, value);
+  }
+}
+
+function snapshotArray(
+  value: readonly unknown[],
+  secret: string,
+  budget: Budget,
+  depth: number,
+): readonly ModuleSecretSafeValue[] {
+  const length = value.length;
+  if (
+    !numberIsSafeInteger(length) ||
+    length < 0 ||
+    length > MAX_ENTRIES - budget.entries
+  ) {
+    reject();
+  }
+  const descriptors = ownDescriptors(value);
+  const keys = reflectOwnKeys(descriptors);
+  if (hasSymbolKey(keys)) reject();
+  const lengthDescriptor = descriptors.length;
+  if (!lengthDescriptor || !("value" in lengthDescriptor)) reject();
+  if (lengthDescriptor.value !== length || keys.length !== length + 1) {
+    reject();
+  }
+  addEntries(budget, length);
+  const snapshot: ModuleSecretSafeValue[] = [];
+  objectSetPrototypeOf(snapshot, safeArrayPrototype);
+  for (let index = 0; index < length; index += 1) {
+    const descriptor = descriptors[String(index)];
+    if (!isEnumerableDataDescriptor(descriptor)) reject();
+    const child = snapshotValue(descriptor.value, secret, budget, depth + 1);
+    if (child === undefined) reject();
+    snapshot[index] = child;
+  }
+  return objectFreeze(snapshot);
+}
+
+function snapshotObject(
+  value: object,
+  secret: string,
+  budget: Budget,
+  depth: number,
+): Readonly<Record<string, ModuleSecretSafeValue>> {
+  const prototype = objectGetPrototypeOf(value);
+  if (prototype !== objectPrototype && prototype !== null) reject();
+  const descriptors = ownDescriptors(value);
+  const keys = reflectOwnKeys(descriptors);
+  if (hasSymbolKey(keys)) reject();
+  addEntries(budget, keys.length);
+  const snapshot = objectCreate(null) as Record<string, ModuleSecretSafeValue>;
+  for (let index = 0; index < keys.length; index += 1) {
+    const key = keys[index];
+    if (typeof key !== "string") reject();
+    addBytes(budget, key, MAX_KEY_BYTES);
+    if (setHas(dangerousKeys, key) || stringIncludes(key, secret)) reject();
+    const descriptor = descriptors[key];
+    if (!isEnumerableDataDescriptor(descriptor)) reject();
+    const child = snapshotValue(descriptor.value, secret, budget, depth + 1);
+    if (child === undefined) reject();
+    objectDefineProperty(snapshot, key, {
+      value: child,
+      enumerable: true,
+      configurable: false,
+      writable: false,
+    });
+  }
+  return objectFreeze(snapshot);
+}
+
+function hasSymbolKey(keys: readonly PropertyKey[]): boolean {
+  for (let index = 0; index < keys.length; index += 1) {
+    if (typeof keys[index] === "symbol") return true;
+  }
+  return false;
+}
+
+function isEnumerableDataDescriptor(
+  descriptor: PropertyDescriptor | undefined,
+): descriptor is PropertyDescriptor & { value: unknown } {
+  return Boolean(
+    descriptor && descriptor.enumerable === true && "value" in descriptor,
+  );
+}
+
+function ownDescriptors(
+  value: object,
+): Readonly<Record<PropertyKey, PropertyDescriptor | undefined>> {
+  return objectGetOwnPropertyDescriptors(value) as unknown as Readonly<
+    Record<PropertyKey, PropertyDescriptor | undefined>
+  >;
+}
+
+function addEntries(budget: Budget, count: number): void {
+  budget.entries += count;
+  if (budget.entries > MAX_ENTRIES) reject();
+}
+
+function addBytes(budget: Budget, value: string, perValueLimit: number): void {
+  if (value.length > perValueLimit) reject();
+  const bytes = textEncode(encoder, value).byteLength;
+  if (bytes > perValueLimit) reject();
+  budget.bytes += bytes;
+  if (budget.bytes > MAX_TOTAL_BYTES) reject();
+}
+
+function reject(): never {
+  throw unsafeResult;
+}
+
+function createSafeArrayPrototype(): object {
+  const prototype = objectCreate(null) as Record<PropertyKey, unknown>;
+  const descriptors = objectGetOwnPropertyDescriptors(arrayPrototype);
+  const methodNames = [
+    "at",
+    "concat",
+    "entries",
+    "every",
+    "filter",
+    "find",
+    "findIndex",
+    "findLast",
+    "findLastIndex",
+    "flat",
+    "flatMap",
+    "forEach",
+    "includes",
+    "indexOf",
+    "join",
+    "keys",
+    "lastIndexOf",
+    "map",
+    "reduce",
+    "reduceRight",
+    "slice",
+    "some",
+    "toLocaleString",
+    "toReversed",
+    "toSorted",
+    "toSpliced",
+    "toString",
+    "values",
+    "with",
+  ] as const;
+  for (const name of methodNames) {
+    const descriptor = descriptors[name];
+    if (descriptor && "value" in descriptor) {
+      objectDefineProperty(prototype, name, dataMethod(descriptor.value));
+    }
+  }
+  const iterator = objectGetOwnPropertyDescriptor(
+    arrayPrototype,
+    Symbol.iterator,
+  );
+  if (iterator && "value" in iterator) {
+    objectDefineProperty(
+      prototype,
+      Symbol.iterator,
+      dataMethod(iterator.value),
+    );
+  }
+  return objectFreeze(prototype);
+}
+
+function dataMethod(value: unknown): PropertyDescriptor {
+  return {
+    value,
+    enumerable: false,
+    configurable: false,
+    writable: false,
+  };
+}

package/template/apps/server/src/module-host/module-secret-tool-boundary.test.ts

@@ -0,0 +1,143 @@
+import { expect, test } from "bun:test";
+import { featureKey } from "@southwind-ai/shared";
+import type { RequestActor } from "../guards.js";
+import { createServerRuntime } from "../runtime.js";
+import { initializeModuleHosts } from "./initialize.js";
+import { manifest } from "./test-fixtures.js";
+import { createModuleToolHandlerMap } from "./tool-handlers.js";
+
+const feature = {
+  key: featureKey("archive.connection"),
+  label: "档案连接",
+  module: "archive",
+  visible: "visible" as const,
+  enabled: true,
+  stage: "stable" as const,
+};
+
+test("Agent Tool Context 默认不包含 Secret Port", async () => {
+  let exposed = true;
+  let resolverCalls = 0;
+  const moduleManifest = manifest("archive", {
+    features: [feature],
+    permissions: [
+      {
+        key: "archive.connection.read",
+        label: "读取档案连接",
+        module: "archive",
+        moduleLabel: "档案",
+        resource: "connection",
+        resourceLabel: "外部连接",
+        action: "read",
+      },
+    ],
+    secrets: [
+      {
+        handle: "archive.connection.password",
+        connection: "archive.connection.primary",
+        purpose: "archive.connection.read",
+        permissionKey: "archive.connection.read",
+        featureKey: "archive.connection",
+        auditAction: "archive.secret.resolve",
+      },
+    ],
+    auditActions: [
+      {
+        key: "archive.secret.resolve",
+        label: "解析档案连接凭据",
+        description: "为已授权连接短暂解析凭据。",
+      },
+    ],
+    jsonSchemas: [
+      { key: "archive.tool.input.v1", schema: { type: "object" } },
+      { key: "archive.tool.output.v1", schema: { type: "object" } },
+    ],
+    tools: [
+      {
+        key: "archive.tool",
+        label: "档案查询",
+        description: "查询外部档案。",
+        inputSchemaKey: "archive.tool.input.v1",
+        outputSchemaKey: "archive.tool.output.v1",
+        operation: "query",
+        permissionKey: "archive.connection.read",
+        featureKey: "archive.connection",
+        auditAction: "archive.secret.resolve",
+        scopeMode: "request",
+        dataClassification: "sensitive",
+        idempotency: "none",
+        approval: "none",
+        limits: {
+          maxDurationSeconds: 10,
+          maxInputBytes: 1024,
+          maxOutputBytes: 1024,
+        },
+      },
+    ],
+  });
+  const hosts = await initializeModuleHosts({
+    modules: [moduleManifest],
+    secretBindings: [
+      {
+        moduleName: "archive",
+        handle: "archive.connection.password",
+        connection: "archive.connection.primary",
+        purpose: "archive.connection.read",
+        resolve() {
+          resolverCalls += 1;
+          return { status: "active", value: "must-not-resolve" };
+        },
+      },
+    ],
+    installations: [
+      {
+        manifest: moduleManifest,
+        setup(host) {
+          host.registerToolHandlers([
+            {
+              toolKey: "archive.tool",
+              scopeMode: "request",
+              execute(_input, context) {
+                exposed = "secrets" in context;
+                return {};
+              },
+            },
+          ]);
+        },
+      },
+    ],
+  });
+  const runtime = createServerRuntime(
+    { NODE_ENV: "test" },
+    { featureCatalog: [feature] },
+  );
+  const guardContext = await runtime.createGuardContextForActor(
+    new Request("http://module.test/tool"),
+    currentActor(),
+  );
+  const handler = createModuleToolHandlerMap(hosts, {
+    runtime,
+    features: [feature],
+  }).get("archive.tool");
+
+  await handler!.execute(
+    {},
+    {
+      guardContext,
+      signal: new AbortController().signal,
+      toolCallId: "tool-call-1",
+    },
+  );
+  expect(exposed).toBe(false);
+  expect(resolverCalls).toBe(0);
+});
+
+function currentActor(): RequestActor {
+  return {
+    id: "archive-user",
+    type: "user",
+    name: "档案用户",
+    roleCodes: ["archive-reader"],
+    permissionKeys: ["archive.connection.read"],
+  };
+}

package/template/apps/server/src/module-host/project-composition.ts

@@ -165,6 +165,7 @@ function assertRuntimeDisableSafe(manifest: ModuleManifest): void {
     ...manifest.tools.map(({ featureKey }) => featureKey),
     ...(manifest.aiOperations ?? []).map(({ featureKey }) => featureKey),
     ...manifest.providers.map(({ featureKey }) => featureKey),
+    ...(manifest.secrets ?? []).map(({ featureKey }) => featureKey),
     ...(manifest.dataPolicies ?? []).map(({ featureKey }) => featureKey),
   ].filter((key): key is string => Boolean(key));
   if (guardedFeatureKeys.some((key) => !ownedFeatures.has(key))) {

package/template/apps/server/src/module-host/report-staging-port.ts

@@ -0,0 +1,55 @@
+import { randomUUIDv7 } from "bun";
+import type {
+  ModuleReportStagingPolicyV1,
+  ModuleReportStagingPortV1,
+  ModuleReportStagingSourceReader,
+} from "@southwind-ai/server-sdk";
+import type { AuditOutcome } from "@southwind-ai/shared";
+import { auditActor, type RequestGuardContext } from "../guards.js";
+import type { ReportStagingService } from "../report-staging/service.js";
+import type { createServerRuntime } from "../runtime.js";
+import type { ModuleStorageScope } from "./storage-port.js";
+
+export function createModuleReportStagingPort(input: {
+  readonly service: ReportStagingService;
+  readonly policies: readonly ModuleReportStagingPolicyV1[];
+  readonly storage: ModuleReportStagingSourceReader;
+  readonly storageScope: ModuleStorageScope;
+  readonly guardContext: RequestGuardContext;
+  readonly runtime: ReturnType<typeof createServerRuntime>;
+  readonly reauthorize: () => Promise<boolean>;
+  readonly auditMetadata?: Readonly<Record<string, string | number>>;
+}): ModuleReportStagingPortV1 | undefined {
+  const binding = input.storageScope.authorizationBinding;
+  if (!binding || !input.storageScope.actor || input.policies.length === 0) {
+    return undefined;
+  }
+  return input.service.createPort({
+    moduleName: input.storageScope.moduleName,
+    ownerId: input.storageScope.ownerId,
+    scopeHash: binding.scopeHash,
+    policies: new Map(input.policies.map((policy) => [policy.purpose, policy])),
+    reader: { open: (request) => input.storage.open(request) },
+    signal: input.storageScope.signal ?? new AbortController().signal,
+    reauthorize: input.reauthorize,
+    record(action, outcome, groupId, metadata) {
+      input.runtime.auditSink.recordEvent({
+        id: randomUUIDv7(),
+        action,
+        outcome: auditOutcome(outcome),
+        actor: auditActor(input.guardContext),
+        ...(groupId
+          ? { target: { type: "report-staging-group", id: groupId } }
+          : {}),
+        module: input.storageScope.moduleName,
+        requestId: input.guardContext.requestId,
+        metadata: { ...input.auditMetadata, ...metadata },
+        occurredAt: new Date().toISOString(),
+      });
+    },
+  });
+}
+
+function auditOutcome(outcome: "success" | "failure" | "denied"): AuditOutcome {
+  return outcome === "denied" ? "denied" : outcome;
+}

package/template/apps/server/src/module-host/report-staging-registration.test.ts

@@ -0,0 +1,104 @@
+import { describe, expect, test } from "bun:test";
+import type { ModuleReportStagingPolicyV1 } from "@southwind-ai/server-sdk";
+import { initializeModuleHosts } from "./initialize.js";
+import { manifest } from "./test-fixtures.js";
+
+describe("模块大报告暂存策略注册", () => {
+  test("只投影当前模块注册的 Host 治理策略", async () => {
+    const policy = reportPolicy();
+    const hosts = await initializeModuleHosts({
+      modules: [manifest("evidence")],
+      initializers: [
+        {
+          moduleName: "evidence",
+          initialize(host) {
+            host.registerUploadPolicy(uploadPolicy());
+            host.registerReportStagingPolicy(policy);
+          },
+        },
+      ],
+    });
+
+    expect(hosts.reportStagingPoliciesOf("evidence")).toEqual([policy]);
+    expect(hosts.reportStagingPolicies).toEqual([policy]);
+  });
+
+  test("源用途、命名空间、重复与全局资源上限均 fail closed", async () => {
+    await expectRegistration({
+      sourcePurposes: ["evidence.unknown"],
+    }).rejects.toThrow("报告暂存源用途未由模块 evidence 注册");
+    await expectRegistration({
+      purpose: "other.report-staging",
+    }).rejects.toThrow("报告暂存用途不属于模块 evidence");
+    await expectRegistration({ maxEntries: 200_001 }).rejects.toThrow(
+      "maxEntries 超出宿主上限",
+    );
+    await expectRegistration({ maxSources: 10_001 }).rejects.toThrow(
+      "maxSources 超出宿主上限",
+    );
+    await expectRegistration({}, (host, policy) => {
+      host.registerReportStagingPolicy(policy);
+      host.registerReportStagingPolicy(policy);
+    }).rejects.toThrow("报告暂存用途重复注册");
+  });
+});
+
+function expectRegistration(
+  overrides: Partial<ModuleReportStagingPolicyV1>,
+  register: (
+    host: Parameters<
+      NonNullable<
+        Parameters<typeof initializeModuleHosts>[0]["initializers"]
+      >[number]["initialize"]
+    >[0],
+    policy: ModuleReportStagingPolicyV1,
+  ) => void = (host, policy) => host.registerReportStagingPolicy(policy),
+) {
+  return expect(
+    initializeModuleHosts({
+      modules: [manifest("evidence")],
+      initializers: [
+        {
+          moduleName: "evidence",
+          initialize(host) {
+            host.registerUploadPolicy(uploadPolicy());
+            register(host, { ...reportPolicy(), ...overrides });
+          },
+        },
+      ],
+    }),
+  );
+}
+
+function uploadPolicy() {
+  return {
+    purpose: "evidence.original",
+    maxByteSize: 16 * 1024 ** 3,
+    maxPartByteSize: 16 * 1024 ** 2,
+    sessionTtlMs: 24 * 60 * 60_000,
+    fileRetentionMs: 30 * 24 * 60 * 60_000,
+    allowedTypes: {
+      "application/vnd.rar": ["rar"],
+      "application/octet-stream": ["001"],
+    },
+    signature: "none" as const,
+  };
+}
+
+function reportPolicy(): ModuleReportStagingPolicyV1 {
+  return {
+    purpose: "evidence.report-staging",
+    sourcePurposes: ["evidence.original"],
+    retentionMs: 24 * 60 * 60_000,
+    claimTtlMs: 10 * 60_000,
+    maxReadLeaseMs: 10 * 60_000,
+    maxProcessMs: 60 * 60_000,
+    maxSources: 32,
+    maxArchiveBytes: 8 * 1024 ** 3,
+    maxExpandedBytes: 16 * 1024 ** 3,
+    maxEntryBytes: 2 * 1024 ** 3,
+    maxEntries: 100_000,
+    maxCompressionRatio: 100,
+    maxPathDepth: 32,
+  };
+}