@republicroad/zen-udf 0.2.0

package/src/roster.ts

@@ -0,0 +1,129 @@
+export interface Roster {
+  name: string;
+  description?: string;
+  items: string[];
+}
+
+/**
+ * 名单作用域（U5 租户化）：tenantId 必填；actor 缺省 = 租户共享，指定 actor = 该用户私有。
+ * 可见性：自有 > 租户共享 > 不可见他人；无 actor（管理员）遍历本租户全域。跨租户永不可见。
+ */
+export interface RosterScope {
+  tenantId: string;
+  actor?: string;
+}
+
+interface TenantStore {
+  /** 租户共享名单 */
+  shared: Map<string, Roster>;
+  /** actor → name → roster（用户私有名单） */
+  private: Map<string, Map<string, Roster>>;
+}
+
+const tenants = new Map<string, TenantStore>();
+
+const tenantOf = (tenantId: string): TenantStore => {
+  let store = tenants.get(tenantId);
+  if (!store) {
+    store = { shared: new Map(), private: new Map() };
+    tenants.set(tenantId, store);
+  }
+  return store;
+};
+
+interface ResolvedEntry {
+  roster: Roster;
+  /** 私有名单命中时的属主 actor；共享名单无属主 */
+  ownerActor?: string;
+}
+
+const resolveRosterEntry = (name: string, scope: RosterScope): ResolvedEntry | null => {
+  const tenant = tenants.get(scope.tenantId);
+  if (!tenant) return null;
+  if (scope.actor) {
+    const own = tenant.private.get(scope.actor)?.get(name);
+    if (own) return { roster: own, ownerActor: scope.actor };
+    const shared = tenant.shared.get(name);
+    if (shared) return { roster: shared };
+    return null;
+  }
+  // 管理员（无 actor）：租户共享优先，其次遍历本租户私有域
+  const shared = tenant.shared.get(name);
+  if (shared) return { roster: shared };
+  for (const [actor, map] of tenant.private) {
+    const hit = map.get(name);
+    if (hit) return { roster: hit, ownerActor: actor };
+  }
+  return null;
+};
+
+const assertScope = (scope: RosterScope): void => {
+  if (!scope?.tenantId) {
+    throw new Error('[roster] scope.tenantId is required');
+  }
+};
+
+export const registerRoster = (roster: Roster, scope: RosterScope): void => {
+  assertScope(scope);
+  const tenant = tenantOf(scope.tenantId);
+  const stored: Roster = { ...roster };
+  if (scope.actor) {
+    let own = tenant.private.get(scope.actor);
+    if (!own) {
+      own = new Map();
+      tenant.private.set(scope.actor, own);
+    }
+    own.set(stored.name, stored);
+  } else {
+    tenant.shared.set(stored.name, stored);
+  }
+};
+
+/** 解析 actor 可访问的名单：有 actor 时自有优先、租户共享次之、他人私有不可见；无 actor（管理员）共享优先、遍历本租户私有域 */
+export const getRoster = (name: string, scope: RosterScope): Roster | undefined => {
+  assertScope(scope);
+  return resolveRosterEntry(name, scope)?.roster;
+};
+
+export const listRosters = (query: string | undefined, scope: RosterScope): Roster[] => {
+  assertScope(scope);
+  const tenant = tenants.get(scope.tenantId);
+  if (!tenant) return [];
+  const collected: Roster[] = [];
+  if (scope.actor) {
+    collected.push(...(tenant.private.get(scope.actor)?.values() ?? []));
+    collected.push(...tenant.shared.values());
+  } else {
+    collected.push(...tenant.shared.values());
+    for (const map of tenant.private.values()) collected.push(...map.values());
+  }
+  const q = query?.trim().toLowerCase() ?? '';
+  const visible = q ? collected.filter((roster) => roster.name.toLowerCase().includes(q)) : collected;
+  return visible.map((roster) => ({ ...roster }));
+};
+
+/** 删除名单；私有仅 owner 或本租户管理员可删，共享本租户任意调用方可删；返回是否存在且有权（便于 API 层区分 404） */
+export const deleteRoster = (name: string, scope: RosterScope): boolean => {
+  assertScope(scope);
+  const entry = resolveRosterEntry(name, scope);
+  if (!entry) return false;
+  if (entry.ownerActor !== undefined && scope.actor !== undefined && scope.actor !== entry.ownerActor) {
+    return false;
+  }
+  const tenant = tenants.get(scope.tenantId)!;
+  if (entry.ownerActor !== undefined) {
+    return tenant.private.get(entry.ownerActor)?.delete(name) ?? false;
+  }
+  return tenant.shared.delete(name);
+};
+
+export const queryRoster = (
+  name: string,
+  value: unknown,
+  scope: RosterScope,
+): { hit: boolean; roster: string; value: unknown } => {
+  assertScope(scope);
+  const roster = resolveRosterEntry(name, scope)?.roster;
+  const hit = roster ? roster.items.some((item) => String(item) === String(value)) : false;
+  return { hit, roster: roster?.name ?? name, value };
+};

package/src/sanitize.test.ts

@@ -0,0 +1,65 @@
+import { describe, expect, test } from 'vitest';
+
+import { DecisionRuntime } from './engine.ts';
+import { runWithExecContext } from './exec-context.ts';
+import { UdfRegistry } from './register.ts';
+
+const graph = {
+  id: 'g-sanitize',
+  nodes: [
+    { id: 'in', type: 'inputNode', name: 'Request' },
+    {
+      id: 'c1',
+      type: 'customNode',
+      name: 'custom',
+      content: { kind: 'UDF', config: { expressions: [{ id: 'e1', key: 'out', value: 'boom_udf' }] } },
+    },
+    { id: 'out', type: 'outputNode', name: 'Response' },
+  ],
+  edges: [
+    { id: 'ed1', sourceId: 'in', targetId: 'c1', type: 'edge' },
+    { id: 'ed2', sourceId: 'c1', targetId: 'out', type: 'edge' },
+  ],
+};
+
+const evalOut = async (runtime: DecisionRuntime): Promise<string | undefined> => {
+  const result = await runWithExecContext({ tenantId: 't-1' }, () => runtime.evaluateAsync('k', {}));
+  return (result.result as { out?: { error?: string } }).out?.error;
+};
+
+describe('V4 表达式错误脱敏（§6.7）', () => {
+  test('内置规则：绝对路径占位 + 敏感环境变量值替换', async () => {
+    process.env.ZUDF_TEST_SECRET = 'supersecret42';
+    const registry = new UdfRegistry();
+    registry.registerFunction(function boom_udf() {
+      throw new Error('read failed at C:\\Users\\op\\secret.txt with token supersecret42');
+    }, 'target');
+    const runtime = new DecisionRuntime({ registry });
+    await runWithExecContext({ tenantId: 't-1' }, () => {
+      runtime.createDecisionWithCacheKey('k', graph);
+      return Promise.resolve();
+    });
+
+    const error = await evalOut(runtime);
+    expect(error).toBeDefined();
+    expect(error).not.toContain('C:\\Users\\op\\secret.txt');
+    expect(error).not.toContain('supersecret42');
+    expect(error).toContain('[path]');
+    expect(error).toContain('[ZUDF_TEST_SECRET]');
+    delete process.env.ZUDF_TEST_SECRET;
+  });
+
+  test('可注入脱敏器替换内置规则', async () => {
+    const registry = new UdfRegistry();
+    registry.registerFunction(function boom_udf() {
+      throw new Error('plain message');
+    }, 'target');
+    const runtime = new DecisionRuntime({ registry, sanitizer: () => '[redacted]' });
+    await runWithExecContext({ tenantId: 't-1' }, () => {
+      runtime.createDecisionWithCacheKey('k', graph);
+      return Promise.resolve();
+    });
+
+    expect(await evalOut(runtime)).toBe('[redacted]');
+  });
+});

package/src/udf-pack.test.ts

@@ -0,0 +1,107 @@
+import { describe, expect, test } from 'vitest';
+
+import { DecisionRuntime } from './engine.ts';
+import { runWithExecContext } from './exec-context.ts';
+import { type UdfPack, createUdfRegistry, validatePack } from './register.ts';
+
+const fraudPack: UdfPack = {
+  namespace: 'fraud',
+  tools: [
+    {
+      name: 'device_fingerprint_query',
+      description: '设备指纹查询（探针）',
+      parametersSchema: {
+        properties: { deviceId: { type: 'string', title: 'DeviceId' } },
+        required: ['deviceId'],
+        title: 'device_fingerprint_query',
+        type: 'object',
+      },
+      returnsSchema: { type: 'object', title: 'result', properties: {} },
+      fn: function deviceFingerprintQueryUdf(kwargs: Record<string, unknown>) {
+        return { deviceId: kwargs?.deviceId ?? null, marker: 'fraud-pack' };
+      },
+    },
+  ],
+};
+
+describe('UdfPack 契约（U6）', () => {
+  test('validatePack：合法包通过', () => {
+    expect(validatePack(fraudPack)).toEqual([]);
+  });
+
+  test('validatePack：缺 namespace / 空 tools / 缺 fn / 重名 / 缺 properties 逐项报错', () => {
+    const errors = validatePack({
+      namespace: '',
+      tools: [
+        { name: '', fn: () => null },
+        { name: 't1', fn: 'not-a-fn' as unknown as () => null },
+        {
+          name: 't2',
+          fn: () => null,
+          parametersSchema: { title: 'no-properties', type: 'object' } as never,
+        },
+        { name: 't2', fn: () => null },
+      ],
+    });
+    expect(errors.length).toBeGreaterThanOrEqual(5);
+    expect(errors.join('\n')).toContain('namespace is required');
+    expect(errors.join('\n')).toContain("tool 't1' requires a function fn");
+    expect(errors.join('\n')).toContain("duplicate tool name 't2'");
+  });
+
+  test('createUdfRegistry：pack 注册 → schema 下发 → 调用 round-trip', async () => {
+    const registry = createUdfRegistry({ packs: [fraudPack] });
+
+    const schema = registry.udfFunctionSchema('device_fingerprint_query');
+    expect(schema?.namespace).toBe('fraud');
+    expect(schema?.parametersSchema?.properties?.['deviceId']).toBeDefined();
+
+    const namespaces = registry.udfFunctionSchemaNamespaces();
+    expect(namespaces).toHaveLength(1);
+    expect(namespaces[0]).toMatchObject({ name: 'fraud', title: 'fraud', type: 'namespace' });
+    expect(namespaces[0].tools[0]).toMatchObject({ name: 'device_fingerprint_query', kind: 'fraud' });
+
+    const bound = registry.funcBindParams('device_fingerprint_query', ['dev-1']);
+    const result = (await registry.call('device_fingerprint_query', bound)) as { marker: string };
+    expect(result.marker).toBe('fraud-pack');
+  });
+
+  test('createUdfRegistry：非法 pack 整体失败且不产生半注册状态', () => {
+    const badPack: UdfPack = { namespace: 'bad', tools: [{ name: 't', fn: undefined as never }] };
+    expect(() => createUdfRegistry({ packs: [badPack] })).toThrow(/invalid UdfPack 'bad'/);
+  });
+
+  test('pack 注入的注册表 + DecisionRuntime 端到端执行', async () => {
+    const registry = createUdfRegistry({ packs: [fraudPack] });
+    const runtime = new DecisionRuntime({ registry });
+    const graph = {
+      id: 'g-pack',
+      nodes: [
+        { id: 'in', type: 'inputNode', name: 'Request' },
+        {
+          id: 'c1',
+          type: 'customNode',
+          name: 'custom',
+          content: {
+            kind: 'UDF',
+            config: { expressions: [{ id: 'e1', key: 'fp', value: 'device_fingerprint_query;;deviceId' }] },
+          },
+        },
+        { id: 'out', type: 'outputNode', name: 'Response' },
+      ],
+      edges: [
+        { id: 'ed1', sourceId: 'in', targetId: 'c1', type: 'edge' },
+        { id: 'ed2', sourceId: 'c1', targetId: 'out', type: 'edge' },
+      ],
+    };
+
+    await runWithExecContext({ tenantId: 't-1' }, () => {
+      runtime.createDecisionWithCacheKey('fraud-model', graph, 'v1');
+      return Promise.resolve();
+    });
+    const result = await runWithExecContext({ tenantId: 't-1' }, () =>
+      runtime.evaluateAsync('fraud-model', { deviceId: 'dev-9' }, undefined, 'v1'),
+    );
+    expect((result.result as { fp: { marker: string } }).fp.marker).toBe('fraud-pack');
+  });
+});

package/src/udf-trace.test.ts

@@ -0,0 +1,137 @@
+import { describe, expect, test } from 'vitest';
+
+import { DecisionRuntime } from './engine.ts';
+import { runWithExecContext } from './exec-context.ts';
+import { UdfRegistry } from './register.ts';
+
+/** customNode 图：target_udf 返回值写入 out 字段 */
+const graph = (id: string) => ({
+  id,
+  nodes: [
+    { id: 'in', type: 'inputNode', name: 'Request' },
+    {
+      id: 'c1',
+      type: 'customNode',
+      name: 'custom',
+      content: { kind: 'UDF', config: { expressions: [{ id: 'e1', key: 'out', value: 'target_udf' }] } },
+    },
+    { id: 'out', type: 'outputNode', name: 'Response' },
+  ],
+  edges: [
+    { id: 'ed1', sourceId: 'in', targetId: 'c1', type: 'edge' },
+    { id: 'ed2', sourceId: 'c1', targetId: 'out', type: 'edge' },
+  ],
+});
+
+const makeRegistry = (fn: (kwargs: Record<string, unknown>) => unknown): UdfRegistry => {
+  const registry = new UdfRegistry();
+  registry.registerFunction(
+    fn,
+    'target',
+    {
+      description: 'target udf',
+      returnsSchema: {
+        type: 'object',
+        title: 'TargetResult',
+        properties: { ok: { type: 'boolean', title: 'Ok' } },
+        required: ['ok'],
+      },
+    },
+    'target_udf',
+  );
+  return registry;
+};
+
+/** 断言 c1 节点 traceData.udf 存在并返回首条 */
+const firstUdfTrace = (result: { trace?: unknown }): Record<string, unknown> | undefined => {
+  const trace = result.trace as Record<string, { traceData?: { udf?: Array<Record<string, unknown>> } }> | undefined;
+  return trace?.['c1']?.traceData?.udf?.[0];
+};
+
+describe('V2 返回值契约（resultValidation）', () => {
+  test('warn（缺省）：违例结果原样下发，traceData 记 INVALID_RESULT', async () => {
+    const registry = makeRegistry(() => 'not-an-object');
+    const runtime = new DecisionRuntime({ registry }); // 缺省 warn
+    await runWithExecContext({ tenantId: 't-1' }, () => {
+      runtime.createDecisionWithCacheKey('k', graph('g-warn'));
+      return Promise.resolve();
+    });
+
+    const result = await runWithExecContext({ tenantId: 't-1' }, () => runtime.evaluateAsync('k', {}, { trace: true }));
+    expect((result.result as { out?: unknown }).out).toBe('not-an-object'); // 行为不变
+    const trace = firstUdfTrace(result);
+    expect(trace?.code).toBe('INVALID_RESULT');
+    expect(JSON.stringify(trace?.issues)).toContain('result type expected object, got string');
+  });
+
+  test('enforce：违例结果替换为 INVALID_RESULT 结构化错误', async () => {
+    const registry = makeRegistry(() => 'not-an-object');
+    const runtime = new DecisionRuntime({ registry, resultValidation: 'enforce' });
+    await runWithExecContext({ tenantId: 't-1' }, () => {
+      runtime.createDecisionWithCacheKey('k', graph('g-enforce'));
+      return Promise.resolve();
+    });
+
+    const result = await runWithExecContext({ tenantId: 't-1' }, () => runtime.evaluateAsync('k', {}, { trace: true }));
+    const out = (result.result as { out?: { error?: { code?: string } } }).out;
+    expect(out?.error?.code).toBe('INVALID_RESULT');
+    expect(firstUdfTrace(result)?.code).toBe('INVALID_RESULT');
+  });
+
+  test('off：不校验不记违例', async () => {
+    const registry = makeRegistry(() => 'not-an-object');
+    const runtime = new DecisionRuntime({ registry, resultValidation: 'off' });
+    await runWithExecContext({ tenantId: 't-1' }, () => {
+      runtime.createDecisionWithCacheKey('k', graph('g-off'));
+      return Promise.resolve();
+    });
+
+    const result = await runWithExecContext({ tenantId: 't-1' }, () => runtime.evaluateAsync('k', {}, { trace: true }));
+    expect((result.result as { out?: unknown }).out).toBe('not-an-object');
+    expect(firstUdfTrace(result)?.code).toBeUndefined();
+  });
+
+  test('合规返回值不产生违例记录', async () => {
+    const registry = makeRegistry(() => ({ ok: true }));
+    const runtime = new DecisionRuntime({ registry });
+    await runWithExecContext({ tenantId: 't-1' }, () => {
+      runtime.createDecisionWithCacheKey('k', graph('g-ok'));
+      return Promise.resolve();
+    });
+
+    const result = await runWithExecContext({ tenantId: 't-1' }, () => runtime.evaluateAsync('k', {}, { trace: true }));
+    expect(firstUdfTrace(result)?.code).toBeUndefined();
+  });
+});
+
+describe('V3 UDF 级 traceData', () => {
+  test('正常调用记录 key/name/micros', async () => {
+    const registry = makeRegistry(() => ({ ok: true }));
+    const runtime = new DecisionRuntime({ registry });
+    await runWithExecContext({ tenantId: 't-1' }, () => {
+      runtime.createDecisionWithCacheKey('k', graph('g-trace'));
+      return Promise.resolve();
+    });
+
+    const result = await runWithExecContext({ tenantId: 't-1' }, () => runtime.evaluateAsync('k', {}, { trace: true }));
+    const trace = firstUdfTrace(result);
+    expect(trace?.key).toBe('out');
+    expect(trace?.name).toBe('target_udf');
+    expect(trace?.micros).toBeGreaterThanOrEqual(0);
+  });
+
+  test('无返回值声明的 UDF 不产生违例（returnsSchema 缺省豁免）', async () => {
+    const registry = new UdfRegistry();
+    registry.registerFunction(function target_udf() {
+      return 12345;
+    }, 'target');
+    const runtime = new DecisionRuntime({ registry });
+    await runWithExecContext({ tenantId: 't-1' }, () => {
+      runtime.createDecisionWithCacheKey('k', graph('g-noschema'));
+      return Promise.resolve();
+    });
+
+    const result = await runWithExecContext({ tenantId: 't-1' }, () => runtime.evaluateAsync('k', {}, { trace: true }));
+    expect(firstUdfTrace(result)?.code).toBeUndefined();
+  });
+});