@svadmin/core 0.50.0 → 0.53.0

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@svadmin/core",
-  "version": "0.50.0",
+  "version": "0.53.0",
   "author": "zuohuadong",
   "repository": {
     "type": "git",
-    "url": "https://github.com/vibeunion/svadmin.git",
+    "url": "git+https://github.com/vibeunion/svadmin.git",
     "directory": "packages/core"
   },
   "main": "src/index.ts",
@@ -14,7 +14,7 @@
     "@testing-library/dom": "^10.4.1",
     "@testing-library/svelte": "^5.4.2",
     "@testing-library/user-event": "^14.6.6",
-    "@types/bun": "^1.4.0",
+    "@types/bun": "^1.4.2",
     "@types/jsdom": "^30.0.0",
     "happy-dom": "^20.11.12",
     "jsdom": "^30.0.1",
@@ -25,6 +25,22 @@
     "@tanstack/svelte-query": "^6.1.48"
   },
   "exports": {
+    "./schema": {
+      "types": "./src/schema.ts",
+      "default": "./src/schema.ts"
+    },
+    "./options": {
+      "types": "./src/defined-options.ts",
+      "default": "./src/defined-options.ts"
+    },
+    "./resource-contract": {
+      "types": "./src/resource-contract.ts",
+      "default": "./src/resource-contract.ts"
+    },
+    "./unsafe": {
+      "types": "./src/unsafe.ts",
+      "default": "./src/unsafe.ts"
+    },
     ".": {
       "types": "./src/index.ts",
       "default": "./src/index.ts"
@@ -91,7 +107,8 @@
   "type": "module",
   "types": "src/index.ts",
   "dependencies": {
-    "@sinclair/typebox": "^0.34.52"
+    "@sinclair/typebox": "^0.34.52",
+    "papaparse": "^5.5.4"
   },
   "peerDependenciesMeta": {
     "svelte": {

package/src/access-control-contract.ts

@@ -0,0 +1,250 @@
+import { Type } from '@sinclair/typebox';
+import { checkExact } from './schema-validation';
+import { snapshotPlainData } from './plain-data';
+import { HttpError } from './types';
+import { permissionCatalogBindingSchema } from './permission-catalog';
+import type {
+  CanParams, CanResult, AccessControlProvider, AccessControlOptions, RegisteredAccessControlProvider,
+} from './permissions.svelte';
+
+const request = Type.Object({
+  resource: Type.String({ minLength: 1 }),
+  action: Type.String({ minLength: 1 }),
+  params: Type.Optional(Type.Object({
+    id: Type.Optional(Type.Union([Type.String(), Type.Number()])),
+  }, { additionalProperties: Type.Unknown() })),
+  meta: Type.Optional(Type.Record(Type.String(), Type.Unknown())),
+}, { additionalProperties: false });
+const response = Type.Object({
+  can: Type.Boolean(), reason: Type.Optional(Type.String()),
+}, { additionalProperties: false });
+const batchRequest = Type.Array(request);
+const batchResponse = Type.Array(response);
+const providerOptions = Type.Object({
+  buttons: Type.Optional(Type.Object({
+    enableAccessControl: Type.Optional(Type.Boolean()),
+    hideIfUnauthorized: Type.Optional(Type.Boolean()),
+  }, { additionalProperties: false })),
+  permissionCatalog: Type.Optional(permissionCatalogBindingSchema),
+}, { additionalProperties: false });
+const registeredProviders = new WeakMap<object, RegisteredAccessControlProvider>();
+
+export function snapshotAccessControlOptions(value: unknown): AccessControlOptions {
+  try {
+    const candidate = snapshotPlainData(value);
+    if (checkExact(providerOptions, candidate)) {
+      if (candidate.buttons) Object.freeze(candidate.buttons);
+      if (candidate.permissionCatalog) {
+        if (candidate.permissionCatalog.digest !== undefined) {
+          candidate.permissionCatalog.digest = candidate.permissionCatalog.digest.toLowerCase();
+        }
+        Object.freeze(candidate.permissionCatalog);
+      }
+      return Object.freeze(candidate);
+    }
+  } catch {
+    // Options are plain data, never executable configuration.
+  }
+  throw new HttpError('Invalid access control options', 422, undefined, { code: 'INVALID_ACCESS_CONTROL_OPTIONS' });
+}
+
+function invalidAccessControlProvider(): HttpError {
+  return new HttpError('Invalid access control provider', 502, undefined, { code: 'INVALID_ACCESS_CONTROL_PROVIDER' });
+}
+
+/** Class methods are supported, but property accessors and polluted Object.prototype are not. */
+function providerMember(value: object, key: string): { readonly value: unknown } | undefined {
+  const seen = new Set<object>();
+  let target: object | null = value;
+  for (let depth = 0; target !== null && target !== Object.prototype && depth < 32; depth++) {
+    if (seen.has(target)) throw invalidAccessControlProvider();
+    seen.add(target);
+    const descriptor = Object.getOwnPropertyDescriptor(target, key);
+    if (descriptor) {
+      if (!('value' in descriptor)) throw invalidAccessControlProvider();
+      const field: unknown = descriptor.value;
+      return { value: field };
+    }
+    const parent: unknown = Object.getPrototypeOf(target);
+    if (parent !== null && typeof parent !== 'object') throw invalidAccessControlProvider();
+    target = parent;
+  }
+  if (target !== null && target !== Object.prototype) throw invalidAccessControlProvider();
+  return undefined;
+}
+
+/** One input identity owns one captured configuration; raw provider objects never become the public projection. */
+export function captureAccessControlProvider(value: unknown): RegisteredAccessControlProvider {
+  try {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) throw invalidAccessControlProvider();
+    const existing = registeredProviders.get(value);
+    if (existing) return existing;
+    const can = providerMember(value, 'can')?.value;
+    const batch = providerMember(value, 'canMany');
+    const canMany = batch?.value;
+    const config = providerMember(value, 'options');
+    if (typeof can !== 'function' || (batch !== undefined && typeof canMany !== 'function')) throw invalidAccessControlProvider();
+    const options = snapshotAccessControlOptions(config ? config.value : {});
+    const captured: RegisteredAccessControlProvider = Object.freeze({
+      options,
+      can: async (input: CanParams): Promise<CanResult> => {
+        try {
+          const request = snapshotCanParams(input);
+          const result: unknown = await Reflect.apply(can, value, [request]);
+          return decodeCanResult(result);
+        } catch (error) {
+          throw accessControlFailure(error);
+        }
+      },
+      ...(typeof canMany === 'function' ? {
+        canMany: async (input: readonly CanParams[]): Promise<CanResult[]> => {
+          try {
+            const requests = snapshotCanBatchParams(input);
+            const count = requests.length;
+            const result: unknown = await Reflect.apply(canMany, value, [requests]);
+            return decodeCanResults(result, count);
+          } catch (error) {
+            throw accessControlFailure(error);
+          }
+        },
+      } : {}),
+    });
+    registeredProviders.set(value, captured);
+    registeredProviders.set(captured, captured);
+    return captured;
+  } catch (error) {
+    throw accessControlFailure(error);
+  }
+}
+
+export function snapshotCanParams(value: unknown): CanParams {
+  try {
+    const candidate = snapshotPlainData(value);
+    if (checkExact(request, candidate)) return candidate;
+  } catch {
+    // Do not invoke accessors or serialization hooks from permission inputs.
+  }
+  throw new HttpError('Invalid access control request', 422, undefined, { code: 'INVALID_ACCESS_CONTROL_INPUT' });
+}
+
+export function decodeCanResult(value: unknown): CanResult {
+  try {
+    const candidate = snapshotPlainData(value);
+    if (checkExact(response, candidate)) return candidate;
+  } catch {
+    // Malformed decisions must fail closed without exposing provider details.
+  }
+  throw new HttpError('Invalid access control response', 502, undefined, { code: 'INVALID_ACCESS_CONTROL_RESPONSE' });
+}
+
+export function snapshotCanBatchParams(value: unknown): CanParams[] {
+  try {
+    const candidate = snapshotPlainData(value);
+    if (checkExact(batchRequest, candidate)) return candidate;
+  } catch {
+    // Validate the complete batch before invoking even its first capability.
+  }
+  throw new HttpError('Invalid access control request', 422, undefined, { code: 'INVALID_ACCESS_CONTROL_INPUT' });
+}
+
+export function decodeCanResults(value: unknown, count: number): CanResult[] {
+  try {
+    const candidate = snapshotPlainData(value);
+    if (checkExact(batchResponse, candidate) && candidate.length === count) return candidate;
+  } catch {
+    // Never return partially validated batches.
+  }
+  throw new HttpError('Invalid access control response', 502, undefined, { code: 'INVALID_ACCESS_CONTROL_RESPONSE' });
+}
+
+export function supersededAccessControl(): HttpError {
+  return new HttpError('Access control scope changed', 409, undefined, { code: 'ACCESS_CONTROL_SUPERSEDED' });
+}
+
+/** Preserve protocol status and checked codes, not provider diagnostics or getters. */
+export function accessControlFailure(error: unknown): HttpError {
+  let status = 502;
+  let code = 'ACCESS_CONTROL_FAILED';
+  try {
+    if (typeof error === 'object' && error !== null) {
+      const statusValue: unknown = Object.getOwnPropertyDescriptor(error, 'statusCode')?.value;
+      const codeValue: unknown = Object.getOwnPropertyDescriptor(error, 'code')?.value;
+      if (typeof statusValue === 'number' && Number.isInteger(statusValue) && statusValue >= 400 && statusValue <= 599) status = statusValue;
+      if (codeValue === 'INVALID_ACCESS_CONTROL_INPUT' || codeValue === 'INVALID_ACCESS_CONTROL_RESPONSE' ||
+          codeValue === 'INVALID_ACCESS_CONTROL_PROVIDER' || codeValue === 'INVALID_ACCESS_CONTROL_OPTIONS' ||
+          codeValue === 'ACCESS_CONTROL_SUPERSEDED') code = codeValue;
+    }
+  } catch {
+    // Reflection failures cannot disclose private provider errors.
+  }
+  return new HttpError('Access control request failed', status, undefined, { code });
+}
+
+/** Capture a single-decision capability before dispatch and isolate every request. */
+export function prepareCanCheck(provider: AccessControlProvider | null, params: CanParams): () => Promise<CanResult> {
+  const request = snapshotCanParams(params);
+  if (provider === null) return async () => ({ can: true });
+  try {
+    const can = provider.can;
+    if (typeof can === 'function') {
+      return async () => decodeCanResult(await can.call(provider, snapshotCanParams(request)));
+    }
+  } catch {
+    // Capability lookup failures become query errors, not render-time provider diagnostics.
+  }
+  return async () => {
+    throw new HttpError('Invalid access control provider', 502, undefined, { code: 'INVALID_ACCESS_CONTROL_PROVIDER' });
+  };
+}
+
+export function prepareCanBatchCheck(
+  provider: AccessControlProvider | null, params: readonly CanParams[], current: () => boolean = () => true,
+): () => Promise<CanResult[]> {
+  const requests = snapshotCanBatchParams(params);
+  if (provider === null || requests.length === 0) return async () => requests.map(() => ({ can: true }));
+  try {
+    const canMany = provider.canMany;
+    if (typeof canMany === 'function') {
+      return async () => {
+        if (!current()) throw supersededAccessControl();
+        return decodeCanResults(await canMany.call(provider, snapshotCanBatchParams(requests)), requests.length);
+      };
+    }
+    const can = canMany === undefined ? provider.can : undefined;
+    if (typeof can === 'function') {
+      return async () => {
+        const settled = await Promise.allSettled(requests.map(async request => {
+          if (!current()) throw supersededAccessControl();
+          return decodeCanResult(await can.call(provider, snapshotCanParams(request)));
+        }));
+        const results: CanResult[] = [];
+        for (const result of settled) {
+          if (result.status === 'rejected') {
+            const error: unknown = result.reason;
+            throw error;
+          }
+          results.push(result.value);
+        }
+        return results;
+      };
+    }
+  } catch {
+    // A malformed native batch capability must not silently fall back to single calls.
+  }
+  return async () => {
+    throw new HttpError('Invalid access control provider', 502, undefined, { code: 'INVALID_ACCESS_CONTROL_PROVIDER' });
+  };
+}
+
+const sources = new WeakMap<AccessControlProvider, string>();
+const runtime = `${Date.now()}:${Math.random().toString(36).slice(2)}`;
+let next = 0;
+export function accessControlSource(provider: AccessControlProvider | null): string {
+  if (!provider) return 'no-access-control-provider';
+  let source = sources.get(provider);
+  if (source === undefined) {
+    source = `${runtime}:${++next}`;
+    sources.set(provider, source);
+  }
+  return source;
+}

package/src/adapters/casbin.ts

@@ -18,7 +18,10 @@
  * ```
  */
 
-import type { AccessControlProvider, CanParams, CanResult } from '../permissions.svelte';
+import type { AccessControlProvider } from '../permissions.svelte';
+import { definedOptions } from '../defined-options';
+import { accessControlFailure, decodeCanResult, snapshotCanParams } from '../access-control-contract';
+import { HttpError } from '../types';
 
 /** Casbin Enforcer interface (minimal, to avoid hard dependency on casbin) */
 interface CasbinEnforcer {
@@ -48,21 +51,24 @@ export function createCasbinAccessControl(
   options: CasbinAdapterOptions,
 ): AccessControlProvider {
   return {
-    can: async (params: CanParams | CanParams[]): Promise<CanResult | CanResult[]> => {
-      const executeCheck = async ({ resource, action }: CanParams) => {
-        const user = options.getUser();
-        const allowed = await enforcer.enforce(user, resource, action);
-        return {
+    can: async (input) => {
+      try {
+        const { resource, action } = snapshotCanParams(input);
+        const user=options.getUser();
+        if (typeof user !== 'string') {
+          throw new HttpError('Invalid access control provider', 502, undefined, { code: 'INVALID_ACCESS_CONTROL_PROVIDER' });
+        }
+        const allowed=await enforcer.enforce(user,resource,action);
+        return decodeCanResult({
           can: allowed,
-          reason: allowed ? undefined : `User "${user}" cannot "${action}" on "${resource}"`,
-        };
-      };
-
-      if (Array.isArray(params)) {
-        return Promise.all(params.map(p => executeCheck(p)));
+          ...definedOptions({
+            reason: allowed? undefined:`User "${user}" cannot "${action}" on "${resource}"`,
+          }),
+        });
+      } catch (error) {
+        throw accessControlFailure(error);
       }
-      return executeCheck(params);
     },
-    options: options.providerOptions,
+    ...definedOptions({ options: options.providerOptions }),
   };
 }

package/src/adapters/casl.ts

@@ -1,4 +1,3 @@
-/* eslint-disable @typescript-eslint/no-explicit-any */
 /**
  * CASL adapter for svadmin AccessControlProvider.
  *
@@ -20,12 +19,15 @@
  * ```
  */
 
-import type { AccessControlProvider, CanParams, CanResult } from '../permissions.svelte';
+import type { AccessControlProvider } from '../permissions.svelte';
+import { definedOptions } from '../defined-options';
+import { accessControlFailure, decodeCanResult, snapshotCanParams } from '../access-control-contract';
+import { HttpError } from '../types';
 
 /** CASL Ability interface (minimal, to avoid hard dependency on @casl/ability) */
 interface CaslAbility {
-  can: (action: string, subject: string, field?: string) => boolean;
-  cannot: (action: string, subject: string, field?: string) => boolean;
+  can: (action: string,subject: string,field?: string) => boolean;
+  cannot: (action: string,subject: string,field?: string) => boolean;
 }
 
 /**
@@ -39,23 +41,24 @@ export function createCaslAccessControl(
   options?: AccessControlProvider['options'],
 ): AccessControlProvider {
   return {
-    can: async (params: CanParams | CanParams[]): Promise<CanResult | CanResult[]> => {
-      const executeCheck = async ({ resource, action, params: actionParams }: CanParams) => {
-        const field = actionParams?.field as string | undefined;
-        // CaslAbility's can only accepts string for subject based on its internal definition in this file
-        // To support object subjects when CanParams might pass them, cast it to any here to satisfy the local interface
-        const allowed = ability.can(action as string, resource as any, field);
-        return {
+    can: async (input) => {
+      try {
+        const { resource, action, params: actionParams } = snapshotCanParams(input);
+        const field=actionParams?.['field'];
+        if(field!==undefined&&typeof field!=='string') {
+          throw new HttpError('Invalid access control request', 422, undefined, { code: 'INVALID_ACCESS_CONTROL_INPUT' });
+        }
+        const allowed=ability.can(action,resource,field);
+        return decodeCanResult({
           can: allowed,
-          reason: allowed ? undefined : `Cannot "${action}" on "${resource}"${field ? ` (field: ${field})` : ''}`,
-        };
-      };
-
-      if (Array.isArray(params)) {
-        return Promise.all(params.map(p => executeCheck(p)));
+          ...definedOptions({
+            reason: allowed? undefined:`Cannot "${action}" on "${resource}"${field? ` (field: ${field})`:''}`,
+          }),
+        });
+      } catch (error) {
+        throw accessControlFailure(error);
       }
-      return executeCheck(params);
     },
-    options,
+    ...definedOptions({ options }),
   };
 }

package/src/admin-tool.ts

@@ -39,24 +39,24 @@ export interface AdminTool<Schema extends TObject = TObject> {
   parameters: Schema;
   /** Pause execution until the user explicitly approves the invocation. */
   needsApproval?: boolean;
-  /** 显式声明是否为只读操作（只读操作可并发执行，无副作用）。 */
+  /** Declares whether the operation is read-only and safe to execute concurrently. */
   readOnly?: boolean;
-  /** 显式声明是否为破坏性或高风险操作。 */
+  /** Declares whether the operation is destructive or high risk. */
   destructive?: boolean;
-  /** 显式声明是否支持并发调用。 */
+  /** Declares whether concurrent calls are supported. */
   concurrent?: boolean;
   /** Execute the tool with decoded arguments. */
   execute(args: StaticDecode<Schema>): Promise<ToolResult>;
 }
 
-/** 保留具体 TypeBox Schema，让 execute 参数获得精确的静态类型。 */
+/** Preserves the concrete TypeBox schema so execute receives precise static types. */
 export function defineAdminTool<const Schema extends TObject>(
   tool: AdminTool<Schema>,
 ): AdminTool<Schema> {
   return { ...tool, parameters: strictAdminToolSchema(tool.parameters) };
 }
 
-/** 在进入工具实现前统一执行 TypeBox 校验与转换。 */
+/** Applies TypeBox validation and conversion before invoking the tool implementation. */
 export function decodeAdminToolArgs<const Schema extends TObject>(
   tool: AdminTool<Schema>,
   input: unknown,
@@ -64,7 +64,7 @@ export function decodeAdminToolArgs<const Schema extends TObject>(
   return Value.Decode(strictAdminToolSchema(tool.parameters), input);
 }
 
-/** 解码并执行工具，避免调用方绕过运行时参数边界。 */
+/** Decodes and executes a tool without allowing callers to bypass runtime input validation. */
 export async function executeAdminTool<const Schema extends TObject>(
   tool: AdminTool<Schema>,
   input: unknown,
@@ -72,7 +72,7 @@ export async function executeAdminTool<const Schema extends TObject>(
   return tool.execute(decodeAdminToolArgs(tool, input));
 }
 
-/** 将工具投影为发给 LLM 或 MCP 客户端的公开 Schema。 */
+/** Projects a tool into the public schema sent to LLM or MCP clients. */
 export function projectAdminToolSchema<Schema extends TObject>(tool: AdminTool<Schema>): {
   name: string;
   description: string;

package/src/audit-contract.ts

@@ -0,0 +1,105 @@
+import { Type, type Static, type TSchema } from '@sinclair/typebox';
+import { checkExact } from './schema-validation';
+import { snapshotPlainData } from './plain-data';
+
+const text = Type.String({ minLength: 1 });
+const record = Type.Record(Type.String(), Type.Unknown());
+const identifier = Type.Union([
+  text, Type.Integer({ minimum: Number.MIN_SAFE_INTEGER, maximum: Number.MAX_SAFE_INTEGER }),
+]);
+const entrySchema = Type.Object({
+  id: Type.Optional(identifier),
+  timestamp: text,
+  action: text,
+  mutationId: Type.Optional(text),
+  resource: Type.Optional(text),
+  recordId: Type.Optional(identifier),
+  userId: Type.Optional(text),
+  details: Type.Optional(record),
+  data: Type.Optional(record),
+  previousData: Type.Optional(record),
+  meta: Type.Optional(record),
+  outcome: Type.Optional(Type.Union([Type.Literal('success'), Type.Literal('failure')])),
+  tenantId: Type.Optional(identifier),
+  requestId: Type.Optional(text),
+  traceId: Type.Optional(text),
+  ipAddress: Type.Optional(text),
+  userAgent: Type.Optional(text),
+  error: Type.Optional(Type.Object({ message: Type.String(), code: Type.Optional(text) }, { additionalProperties: false })),
+}, { additionalProperties: false });
+const draftSchema = Type.Omit(entrySchema, ['id', 'timestamp']);
+const createSchema = Type.Omit(entrySchema, ['id']);
+const querySchema = Type.Object({
+  resource: Type.Optional(text), action: Type.Optional(text),
+  meta: Type.Optional(record), author: Type.Optional(record),
+}, { additionalProperties: false });
+const entriesSchema = Type.Array(entrySchema);
+
+export type AuditEntry = Static<typeof entrySchema>;
+export type AuditDraft = Static<typeof draftSchema>;
+export type AuditCreateParams = Static<typeof createSchema>;
+export type AuditQueryParams = Static<typeof querySchema>;
+
+const messages = {
+  INVALID_AUDIT_INPUT: 'Invalid audit input.',
+  INVALID_AUDIT_RESPONSE: 'Invalid audit response.',
+  AUDIT_HANDLER_FAILED: 'Audit handler write could not be confirmed.',
+  AUDIT_PROVIDER_FAILED: 'Audit provider request failed.',
+  AUDIT_PROVIDER_REQUIRED: 'Strict audit logging requires an AuditLogProvider.',
+} as const;
+
+export class AuditError extends Error {
+  constructor(readonly code: keyof typeof messages, readonly writeMayHaveSucceeded = false) {
+    super(messages[code]);
+    this.name = 'AuditError';
+  }
+}
+
+function decode<S extends TSchema>(
+  schema: S, value: unknown, phase: 'input' | 'response', write = false,
+): Static<S> {
+  try {
+    const candidate = snapshotPlainData(value);
+    if (checkExact(schema, candidate)) return candidate;
+  } catch {
+    // Never retain the submitted record or a reflection exception.
+  }
+  throw new AuditError(phase === 'input' ? 'INVALID_AUDIT_INPUT' : 'INVALID_AUDIT_RESPONSE', write);
+}
+
+/** Audit timestamps are UTC ISO strings, with seconds or exactly three fractional digits. */
+function validateTimestamp(value: string, phase: 'input' | 'response', write: boolean): void {
+  const date = new Date(value);
+  if (Number.isFinite(date.getTime())) {
+    const iso = date.toISOString();
+    if (iso === value || (iso.endsWith('.000Z') && iso.replace('.000Z', 'Z') === value)) return;
+  }
+  throw new AuditError(phase === 'input' ? 'INVALID_AUDIT_INPUT' : 'INVALID_AUDIT_RESPONSE', write);
+}
+
+export function decodeAuditEntry(value: unknown, phase: 'input' | 'response' = 'input', write = false): AuditEntry {
+  const entry = decode(entrySchema, value, phase, write);
+  validateTimestamp(entry.timestamp, phase, write);
+  return entry;
+}
+
+export function createAuditEntry(value: unknown): AuditEntry {
+  const draft = decode(draftSchema, value, 'input');
+  return { ...draft, timestamp: new Date().toISOString() };
+}
+
+export function decodeAuditCreate(value: unknown): AuditCreateParams {
+  const entry = decode(createSchema, value, 'input');
+  validateTimestamp(entry.timestamp, 'input', false);
+  return entry;
+}
+
+export function decodeAuditQuery(value: unknown): AuditQueryParams {
+  return decode(querySchema, value, 'input');
+}
+
+export function decodeAuditEntries(value: unknown): AuditEntry[] {
+  const entries = decode(entriesSchema, value, 'response');
+  for (const entry of entries) validateTimestamp(entry.timestamp, 'response', false);
+  return entries;
+}