@svadmin/core 0.49.1 → 0.52.0

package/src/permission-catalog.ts

@@ -0,0 +1,121 @@
+import { Type, type Static } from '@sinclair/typebox';
+import { checkExact } from './schema-validation';
+import { snapshotPlainData } from './plain-data';
+import type { AccessControlOptions, AccessControlProvider, CanParams } from './permissions.svelte';
+
+const applicationId = Type.String({ minLength: 1, maxLength: 512, pattern: '^\\S+$' });
+const version = Type.String({ minLength: 1, maxLength: 64, pattern: '^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$' });
+const digest = Type.String({ minLength: 64, maxLength: 64, pattern: '^[a-fA-F0-9]{64}$' });
+const permission = Type.String({ minLength: 3, maxLength: 512, pattern: '^[a-z][a-z0-9._-]*:[a-z][a-z0-9._-]*$' });
+
+// 内部契约复用同一 schema，避免注册选项、权限提示与适配器校验漂移。
+export const permissionCatalogBindingSchema = Type.Object({
+  applicationId,
+  version,
+  digest: Type.Optional(digest),
+}, { additionalProperties: false });
+const catalog = Type.Object({
+  ...permissionCatalogBindingSchema.properties,
+  permissions: Type.Array(permission, { minItems: 1 }),
+}, { additionalProperties: false });
+export const permissionSnapshotSchema = Type.Object({
+  applicationId,
+  catalogVersion: version,
+  catalogDigest: Type.Optional(digest),
+  permissions: Type.Array(permission),
+}, { additionalProperties: false });
+
+export type PermissionCatalogBinding = Readonly<Static<typeof permissionCatalogBindingSchema>>;
+export type PermissionCatalog = Readonly<{
+  applicationId: string;
+  version: string;
+  digest?: string;
+  permissions: readonly string[];
+}>;
+export type PermissionSnapshot = Readonly<{
+  applicationId: string;
+  catalogVersion: string;
+  catalogDigest?: string;
+  permissions: readonly string[];
+}>;
+
+function freezeUnique(values: readonly string[], label: string): readonly string[] {
+  if (new Set(values).size !== values.length) throw new TypeError(`${label} contains duplicate permissions`);
+  return Object.freeze([...values]);
+}
+
+export function canonicalPermission(resource: string, action: string): string {
+  if (typeof resource !== 'string' || typeof action !== 'string') throw new TypeError('Permission resource and action must be strings');
+  const value = `${resource}:${action}`;
+  if (value.length > 512 || !/^[a-z][a-z0-9._-]*:[a-z][a-z0-9._-]*$/.test(value)) {
+    throw new TypeError('Permission must use canonical resource:action syntax');
+  }
+  return value;
+}
+
+export function decodePermissionCatalog(value: unknown): PermissionCatalog {
+  const candidate = snapshotPlainData(value);
+  if (!checkExact(catalog, candidate)) throw new TypeError('Invalid permission catalog');
+  return Object.freeze({
+    ...candidate,
+    ...(candidate.digest === undefined ? {} : { digest: candidate.digest.toLowerCase() }),
+    permissions: freezeUnique(candidate.permissions, 'Permission catalog'),
+  });
+}
+
+export function decodePermissionSnapshot(value: unknown): PermissionSnapshot {
+  const candidate = snapshotPlainData(value);
+  if (!checkExact(permissionSnapshotSchema, candidate)) throw new TypeError('Invalid permission snapshot');
+  return Object.freeze({
+    ...candidate,
+    ...(candidate.catalogDigest === undefined ? {} : { catalogDigest: candidate.catalogDigest.toLowerCase() }),
+    permissions: freezeUnique(candidate.permissions, 'Permission snapshot'),
+  });
+}
+
+export interface PermissionProjectionOptions {
+  readonly buttons?: AccessControlOptions['buttons'];
+  /** Application-owned expected catalog; mismatches and unknown grants fail closed. */
+  readonly catalog?: PermissionCatalog;
+}
+
+function assertCatalogBinding(snapshot: PermissionSnapshot, expected: PermissionCatalog): void {
+  if (snapshot.applicationId !== expected.applicationId
+      || snapshot.catalogVersion !== expected.version
+      || (expected.digest !== undefined && snapshot.catalogDigest !== expected.digest)) {
+    throw new TypeError('Permission snapshot does not match the expected application catalog');
+  }
+  const known = new Set(expected.permissions);
+  if (snapshot.permissions.some(grant => !known.has(grant))) {
+    throw new TypeError('Permission snapshot contains grants outside the expected catalog');
+  }
+}
+
+/**
+ * Projects a backend-verified snapshot into a UI-only provider.
+ * Supply catalog to check the application's expected binding. This is not
+ * signature verification and never replaces server-side authorization.
+ */
+export function createPermissionAccessControlProvider(
+  value: unknown,
+  options: PermissionProjectionOptions = {},
+): AccessControlProvider {
+  const permissions = decodePermissionSnapshot(value);
+  if (options.catalog !== undefined) assertCatalogBinding(permissions, decodePermissionCatalog(options.catalog));
+  const granted = new Set(permissions.permissions);
+  const permissionCatalog = Object.freeze({
+    applicationId: permissions.applicationId,
+    version: permissions.catalogVersion,
+    ...(permissions.catalogDigest === undefined ? {} : { digest: permissions.catalogDigest }),
+  });
+  return {
+    async can(params: CanParams) {
+      const required = canonicalPermission(params.resource, params.action);
+      return granted.has(required) ? { can: true } : { can: false, reason: `Missing permission: ${required}` };
+    },
+    options: Object.freeze({
+      ...(options.buttons === undefined ? {} : { buttons: Object.freeze({ ...options.buttons }) }),
+      permissionCatalog,
+    }),
+  };
+}

package/src/permission-hints-contract.ts

@@ -0,0 +1,48 @@
+import { Type } from '@sinclair/typebox';
+import { checkExact } from './schema-validation';
+import { snapshotPlainData } from './plain-data';
+import { decodePermissionSnapshot, permissionSnapshotSchema, type PermissionSnapshot } from './permission-catalog';
+
+const permissionName = Type.String({ minLength: 1, pattern: '\\S' });
+const permissionHintsSchema = Type.Union([
+  Type.Null(),
+  Type.Array(permissionName),
+  Type.Record(Type.String({ pattern: '\\S' }), Type.Boolean(), { additionalProperties: false }),
+  permissionSnapshotSchema,
+]);
+
+export type PermissionHints = null | readonly string[] | Readonly<Record<string, boolean>> | PermissionSnapshot;
+
+export class PermissionHintsError extends Error {
+  constructor(readonly code: 'INVALID_PERMISSION_HINTS' | 'PERMISSION_HINTS_FAILED') {
+    super(code === 'INVALID_PERMISSION_HINTS' ? 'Invalid permission hints.' : 'Permission hints request failed.');
+    this.name = 'PermissionHintsError';
+  }
+}
+
+export function decodePermissionHints(value: unknown): PermissionHints {
+  try {
+    const candidate = snapshotPlainData(value);
+    if (checkExact(permissionHintsSchema, candidate)) {
+      if (candidate === null) return null;
+      // 旧式布尔映射允许 applicationId 作为权限名称，不能仅凭键名识别快照。
+      if (!Array.isArray(candidate) && typeof candidate === 'object'
+          && 'applicationId' in candidate && typeof candidate.applicationId === 'string') {
+        return decodePermissionSnapshot(candidate);
+      }
+      return Object.freeze(candidate);
+    }
+  } catch {
+    // Do not expose provider data or reflection errors.
+  }
+  throw new PermissionHintsError('INVALID_PERMISSION_HINTS');
+}
+
+export function hasPermissionHint(hints: PermissionHints, permission: string): boolean {
+  if (hints === null) return false;
+  if (Array.isArray(hints)) return hints.includes(permission);
+  if ('permissions' in hints && Array.isArray(hints.permissions)) return hints.permissions.includes(permission);
+  const descriptor = Object.getOwnPropertyDescriptor(hints, permission);
+  const value: unknown = descriptor && 'value' in descriptor ? descriptor.value : undefined;
+  return value === true;
+}

package/src/permissions.svelte.ts

@@ -1,15 +1,23 @@
+import { definedOptions } from './defined-options';
+import {
+  accessControlFailure, prepareCanCheck, prepareCanBatchCheck, snapshotCanParams,
+  supersededAccessControl, captureAccessControlProvider,
+} from './access-control-contract';
+import { HttpError } from './types';
+import { parseFeatureGateUser, snapshotFeatureGateConfig } from './feature-gate-contract';
+import type { PermissionCatalogBinding } from './permission-catalog';
 // Permission / Access Control
 
 // ─── Types ────────────────────────────────────────────────────
 
 /** Actions that can be checked for access control. Extensible via string literal union. */
-export type Action = 'list' | 'show' | 'create' | 'edit' | 'delete' | 'export' | 'field' | (string & {});
+export type Action='list'|'show'|'create'|'edit'|'delete'|'export'|'field'|(string&{});
 
 export interface CanParams {
   resource: string;
   action: Action;
-  params?: { id?: string | number; [key: string]: unknown };
-  meta?: Record<string, unknown>;
+  params?: { id?: string|number;[key: string]: unknown };
+  meta?: Record<string,unknown>;
 }
 
 export interface CanResult {
@@ -40,7 +48,9 @@ export interface CanResult {
  * ```
  */
 export interface AccessControlProvider {
-  can: (params: CanParams | CanParams[]) => Promise<CanResult | CanResult[]>;
+  can: (params: CanParams) => Promise<CanResult>;
+  /** Optional native batch capability; otherwise the framework checks each item through can. */
+  canMany?: (params: readonly CanParams[]) => Promise<CanResult[]>;
   options?: {
     buttons?: {
       /** Enable access control checks on CRUD buttons globally. Default: false */
@@ -48,85 +58,132 @@ export interface AccessControlProvider {
       /** Hide buttons when unauthorized instead of disabling. Default: false */
       hideIfUnauthorized?: boolean;
     };
+    permissionCatalog?: PermissionCatalogBinding;
   };
 }
 
+export interface AccessControlOptions {
+  readonly buttons?: {
+    readonly enableAccessControl?: boolean;
+    readonly hideIfUnauthorized?: boolean;
+  };
+  readonly permissionCatalog?: PermissionCatalogBinding;
+}
+
+/** Checked, immutable projection. Use a new input object when changing provider configuration. */
+export interface RegisteredAccessControlProvider {
+  readonly can: AccessControlProvider['can'];
+  readonly canMany?: NonNullable<AccessControlProvider['canMany']>;
+  readonly options: AccessControlOptions;
+}
+
 // ─── State ────────────────────────────────────────────────────
 
-let provider: AccessControlProvider | null = $state(null);
+let provider: RegisteredAccessControlProvider|null=$state.raw(null);
+let providerRevision = 0;
+let registrationIntent = 0;
+const emptyOptions: AccessControlOptions = Object.freeze({});
 
 // ─── API ──────────────────────────────────────────────────────
 
 /**
- * Register an AccessControlProvider.
+ * Register a checked snapshot. Input object identity denotes immutable configuration.
  */
 export function setAccessControlProvider(p: AccessControlProvider): void {
-  provider = p;
+  const intent = ++registrationIntent;
+  let candidate: RegisteredAccessControlProvider;
+  try {
+    candidate = captureAccessControlProvider(p);
+  } catch (error) {
+    if (intent !== registrationIntent) throw supersededAccessControl();
+    throw error;
+  }
+  if (intent !== registrationIntent) throw supersededAccessControl();
+  providerRevision++;
+  provider=candidate;
 }
 
 /** Get the current AccessControlProvider (or null) */
-export function getAccessControlProvider(): AccessControlProvider | null {
+export function getAccessControlProvider(): RegisteredAccessControlProvider|null {
   return provider;
 }
 
 export function resetAccessControlProvider(): void {
-  provider = null;
+  registrationIntent++;
+  providerRevision++;
+  provider=null;
 }
 
 /** Get global button options from the AccessControlProvider */
-export function getAccessControlOptions() {
-  return provider?.options ?? {};
+export function getAccessControlOptions(): AccessControlOptions {
+  return provider?.options??emptyOptions;
 }
 
 /**
  * UI access check supporting single capabilities or a batch.
  * Its result can change browser presentation but never authorizes the backend action.
  */
-export async function canAccessAsync(params: CanParams[]): Promise<CanResult[]>;
-export async function canAccessAsync(resource: string, action: Action, params?: Record<string, unknown>, meta?: Record<string, unknown>): Promise<CanResult>;
-export async function canAccessAsync(resourceOrBatch: string | CanParams[], action?: Action, params?: Record<string, unknown>, meta?: Record<string, unknown>): Promise<CanResult | CanResult[]> {
-  if (!provider) {
-    return Array.isArray(resourceOrBatch)
-      ? resourceOrBatch.map(() => ({ can: true }))
-      : { can: true };
-  }
-  
-  if (Array.isArray(resourceOrBatch)) {
-    return provider.can(resourceOrBatch);
+export async function canAccessAsync(params: readonly CanParams[]): Promise<CanResult[]>;
+export async function canAccessAsync(resource: string,action: Action,params?: CanParams['params'],meta?: CanParams['meta']): Promise<CanResult>;
+export async function canAccessAsync(resourceOrBatch: string|readonly CanParams[],action?: Action,params?: CanParams['params'],meta?: CanParams['meta']): Promise<CanResult|CanResult[]> {
+  const captured = provider;
+  const revision = providerRevision;
+  const current = () => provider === captured && providerRevision === revision;
+  const checkCurrent = () => { if (!current()) throw supersededAccessControl(); };
+  try {
+    let execute: () => Promise<CanResult | CanResult[]>;
+    if (typeof resourceOrBatch === 'string') {
+      const request = snapshotCanParams({
+        resource: resourceOrBatch, ...definedOptions({ action, params, meta }),
+      });
+      execute = prepareCanCheck(captured, request);
+    } else {
+      if (action !== undefined || params !== undefined || meta !== undefined) {
+        throw new HttpError('Invalid access control request', 422, undefined, { code: 'INVALID_ACCESS_CONTROL_INPUT' });
+      }
+      execute = prepareCanBatchCheck(captured, resourceOrBatch, current);
+    }
+    checkCurrent();
+    const result = await execute();
+    checkCurrent();
+    return result;
+  } catch (error) {
+    const failure = accessControlFailure(error);
+    checkCurrent();
+    throw failure;
   }
-  
-  return provider.can({ resource: resourceOrBatch, action: action as string, params, meta }) as Promise<CanResult>;
 }
 
 // ─── Feature Gate ─────────────────────────────────────────────
 
-export interface FeatureGateConfig {
-  /** 仅用于前端展示的角色列表。 */
-  roles?: string[];
-  /**
-   * 需要的最低角色 (含以上所有角色)。
-   * 使用 minRole 时必须同时提供 roleHierarchy。
-   */
-  minRole?: string;
-  /**
-   * 角色层级定义 (高权 → 低权)，用于 minRole 比较。
-   * 由调用方按自身业务定义，框架不预设任何角色。
-   */
-  roleHierarchy?: string[];
-  /** 仅用于前端展示的权限列表 (全部匹配)。 */
-  permissions?: string[];
+interface FeatureGateConstraints {
+  /** Role list used only for frontend presentation. */
+  readonly roles?: readonly string[];
+  /** Permission list used only for frontend presentation; all entries must match. */
+  readonly permissions?: readonly string[];
 }
 
-/** 浏览器中的角色和权限提示，不是授权凭据。 */
+export type FeatureGateConfig = FeatureGateConstraints & (
+  | {
+    /** Minimum required role, including all higher roles. Must occur in roleHierarchy. */
+    readonly minRole: string;
+    /** Nonempty unique roles, ordered from highest to lowest privilege. */
+    readonly roleHierarchy: readonly string[];
+  }
+  | { readonly minRole?: never; readonly roleHierarchy?: never }
+);
+
+/** Browser-side role and permission hints, not authorization credentials. */
 export interface FeatureGateUser {
-  role: string;
-  permissions: string[];
+  readonly role: string;
+  readonly permissions: readonly string[];
 }
 
 /**
- * 创建仅用于前端展示的功能门控函数。
- * 只做客户端 UI 门控；输入可被篡改，后端必须独立完成令牌验证和操作授权。
- * 不预设任何角色层级，也不解释通配符权限。
+ * Creates a feature gate used only for frontend presentation.
+ * Configuration is captured as a checked snapshot. User hints remain client-side
+ * presentation data; the backend must independently authorize operations.
+ * It assumes no role hierarchy and does not interpret wildcard permissions.
  *
  * @example
  * ```ts
@@ -141,26 +198,22 @@ export interface FeatureGateUser {
  * ```
  */
 export function createFeatureGate(config: FeatureGateConfig): (user: FeatureGateUser) => boolean {
+  const rule = snapshotFeatureGateConfig(config);
   return (user: FeatureGateUser): boolean => {
-    if (config.roles && !config.roles.includes(user.role)) {
+    const subject = parseFeatureGateUser(user);
+    if (!subject) return false;
+    if(rule.roles&&!rule.roles.includes(subject.role)) {
       return false;
     }
 
-    if (config.minRole) {
-      const hierarchy = config.roleHierarchy;
-      if (!hierarchy || hierarchy.length === 0) {
-        if (user.role !== config.minRole) return false;
-      } else {
-        const userIndex = hierarchy.indexOf(user.role);
-        const minIndex = hierarchy.indexOf(config.minRole);
-        if (userIndex === -1 || minIndex === -1 || userIndex > minIndex) {
-          return false;
-        }
-      }
+    if(rule.minRole !== undefined) {
+      const userIndex=rule.roleHierarchy.indexOf(subject.role);
+      const minIndex=rule.roleHierarchy.indexOf(rule.minRole);
+      if(userIndex===-1||userIndex>minIndex) return false;
     }
 
-    if (config.permissions && config.permissions.length > 0) {
-      if (!config.permissions.every((permission) => user.permissions.includes(permission))) return false;
+    if(rule.permissions&&rule.permissions.length>0) {
+      if(!rule.permissions.every((permission) => subject.permissions.includes(permission))) return false;
     }
 
     return true;

package/src/plain-data.ts

@@ -0,0 +1,61 @@
+export type JsonValue = null | string | number | boolean | JsonValue[] | { [key: string]: JsonValue };
+
+/** Copy validated JSON data without invoking getters or serialization hooks. */
+export function snapshotPlainData(value: unknown): JsonValue {
+  function snapshot(value: unknown, ancestors: Set<object>): JsonValue {
+    if (value === null || typeof value === 'string' || typeof value === 'boolean') return value;
+    if (typeof value === 'number' && Number.isFinite(value)) return value;
+    if (typeof value !== 'object' || value === null || ancestors.has(value)) {
+      throw new TypeError('Invalid plain data');
+    }
+    const array = Array.isArray(value);
+    const prototype: unknown = Object.getPrototypeOf(value);
+    if ((!array && prototype !== Object.prototype && prototype !== null) ||
+        Object.getOwnPropertySymbols(value).length > 0) throw new TypeError('Invalid plain data');
+    ancestors.add(value);
+    try {
+      const descriptors = Object.getOwnPropertyDescriptors(value);
+      const read = (key: string): JsonValue => {
+        const descriptor = descriptors[key];
+        if (!descriptor || !descriptor.enumerable || !('value' in descriptor)) throw new TypeError('Invalid plain data');
+        const field: unknown = descriptor.value;
+        return snapshot(field, ancestors);
+      };
+      if (array) {
+        const length: unknown = descriptors['length']?.value;
+        if (typeof length !== 'number' || !Number.isInteger(length) || length < 0 ||
+            Object.keys(descriptors).length !== length + 1) throw new TypeError('Invalid plain data');
+        return Array.from({ length }, (_, index) => read(String(index)));
+      }
+      const entries: [string, JsonValue][] = Object.keys(descriptors).map(key => [key, read(key)]);
+      return Object.fromEntries<JsonValue>(entries);
+    } finally {
+      ancestors.delete(value);
+    }
+  }
+  try {
+    return snapshot(value, new Set());
+  } catch {
+    // Reflection can throw for proxies; never retain the submitted value or error.
+    throw new TypeError('Invalid plain data');
+  }
+}
+
+/** Query cancellation is not JSON. Peel it before snapshots and reattach after. */
+export function detachAbortSignal(value: unknown): { signal?: AbortSignal; rest: unknown } {
+  if (typeof value !== 'object' || value === null) return { rest: value };
+  const descriptor = Object.getOwnPropertyDescriptor(value, 'signal');
+  const signal: unknown = descriptor && 'value' in descriptor ? descriptor.value : undefined;
+  if (!(signal instanceof AbortSignal)) return { rest: value };
+  const descriptors = Object.getOwnPropertyDescriptors(value);
+  delete descriptors['signal'];
+  const prototype: unknown = Object.getPrototypeOf(value);
+  if (Array.isArray(value) || (prototype !== Object.prototype && prototype !== null)) return { rest: value };
+  return { signal, rest: Object.defineProperties({}, descriptors) };
+}
+
+/** Reattach a query-owned signal after JSON snapshots. */
+export function attachAbortSignal<T extends object>(value: T, signal?: AbortSignal): T {
+  if (signal === undefined) return value;
+  return Object.assign(Object.create(Object.getPrototypeOf(value)), value, { signal });
+}