@svadmin/core 0.49.1 → 0.52.0

package/src/auth-mutation-contract.ts

@@ -0,0 +1,143 @@
+import { Type, type Static } from '@sinclair/typebox';
+import type { AuthProvider } from './types';
+import { authErrorSchema, authRedirectSchema, decodeIdentity } from './auth-query-contract';
+import { snapshotPlainData } from './plain-data';
+import { checkExact } from './schema-validation';
+
+const actionResultSchema = Type.Object({
+  success: Type.Boolean(),
+  redirectTo: Type.Optional(authRedirectSchema),
+  error: Type.Optional(authErrorSchema),
+}, { additionalProperties: false });
+const parametersSchema = Type.Record(Type.String(), Type.Unknown());
+const profileSchema = Type.Object({
+  name: Type.Optional(Type.String()),
+  avatar: Type.Optional(Type.String()),
+});
+
+export type AuthActionResult = Static<typeof actionResultSchema>;
+export type AuthMutationMethod =
+  | 'login' | 'logout' | 'register' | 'forgotPassword'
+  | 'updatePassword' | 'updateIdentity' | 'updateProfile';
+export type AuthMutationArgs<M extends AuthMutationMethod> = Parameters<NonNullable<AuthProvider[M]>>;
+
+export class AuthMutationError extends Error {
+  constructor(readonly code:
+    | 'INVALID_AUTH_INPUT' | 'AUTH_METHOD_UNAVAILABLE' | 'AUTH_REQUEST_FAILED'
+    | 'INVALID_AUTH_RESULT' | 'AUTH_REJECTED' | 'AUTH_RESULT_SUPERSEDED',
+  ) {
+    super({
+      INVALID_AUTH_INPUT: 'Invalid authentication input.',
+      AUTH_METHOD_UNAVAILABLE: 'Authentication method is unavailable.',
+      AUTH_REQUEST_FAILED: 'Authentication request failed; its outcome could not be confirmed.',
+      INVALID_AUTH_RESULT: 'Invalid authentication result; its outcome could not be confirmed.',
+      AUTH_REJECTED: 'Authentication request was rejected.',
+      AUTH_RESULT_SUPERSEDED: 'Authentication result belongs to an inactive request.',
+    }[code]);
+    this.name = 'AuthMutationError';
+  }
+}
+
+export function authMutationFailure(code: AuthMutationError['code']): AuthActionResult {
+  const error = new AuthMutationError(code);
+  return Object.freeze({ success: false, error: Object.freeze({ name: error.code, message: error.message }) });
+}
+
+export function decodeAuthAction(value: unknown): AuthActionResult {
+  try {
+    const candidate = snapshotPlainData(value);
+    if (checkExact(actionResultSchema, candidate) && !(candidate.success && candidate.error !== undefined)) {
+      return candidate.success ? Object.freeze(candidate) : authMutationFailure('AUTH_REJECTED');
+    }
+  } catch {
+    // Never expose provider payloads, exception text, or reflection failures.
+  }
+  throw new AuthMutationError('INVALID_AUTH_RESULT');
+}
+
+export function decodeAuthParameters(value: unknown): Record<string, unknown> {
+  try {
+    const candidate = snapshotPlainData(value);
+    if (checkExact(parametersSchema, candidate)) return candidate;
+  } catch {
+    // Business-specific fields are validated by the selected provider.
+  }
+  throw new AuthMutationError('INVALID_AUTH_INPUT');
+}
+
+function decodeProfile(value: unknown): Parameters<NonNullable<AuthProvider['updateProfile']>>[0] {
+  try {
+    if (typeof value !== 'object' || value === null) throw new Error();
+    const descriptor = Object.getOwnPropertyDescriptor(value, 'avatar');
+    const avatar: unknown = descriptor && 'value' in descriptor ? descriptor.value : undefined;
+    if (typeof File !== 'undefined' && avatar instanceof File) {
+      // File is immutable upload data. Validate every other field without reading accessors.
+      const descriptors = Object.getOwnPropertyDescriptors(value);
+      delete descriptors['avatar'];
+      if (Object.getOwnPropertySymbols(value).length > 0 ||
+          (Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null) ||
+          descriptor?.enumerable !== true) throw new Error();
+      const rest: unknown = Object.defineProperties({}, descriptors);
+      const candidate = decodeAuthParameters(rest);
+      if (checkExact(profileSchema, candidate)) return { ...candidate, avatar };
+    } else {
+      const candidate = decodeAuthParameters(value);
+      if (checkExact(profileSchema, candidate)) return candidate;
+    }
+  } catch {
+    // Invalid metadata must not turn into a partial profile update.
+  }
+  throw new AuthMutationError('INVALID_AUTH_INPUT');
+}
+
+function captureMethod<P>(
+  provider: AuthProvider,
+  select: () => ((params: P) => Promise<AuthActionResult>) | undefined,
+): (params: P) => Promise<unknown> {
+  try {
+    const method = select();
+    if (typeof method === 'function') return params => method.call(provider, params);
+  } catch {
+    // A throwing method accessor is unavailable, not an input or server error.
+  }
+  throw new AuthMutationError('AUTH_METHOD_UNAVAILABLE');
+}
+
+/** Validate and snapshot before dispatch, retaining the exact method and receiver. */
+export function prepareAuthMutation(provider: AuthProvider, method: AuthMutationMethod, value: unknown): () => Promise<unknown> {
+  switch (method) {
+    case 'logout': {
+      const invoke = captureMethod(provider, () => provider.logout);
+      const input = value === undefined ? undefined : decodeAuthParameters(value);
+      return () => invoke(input);
+    }
+    case 'updateProfile': {
+      const invoke = captureMethod(provider, () => provider.updateProfile);
+      const input = decodeProfile(value);
+      return () => invoke(input);
+    }
+    case 'updateIdentity': {
+      const invoke = captureMethod(provider, () => provider.updateIdentity);
+      try {
+        const input = decodeIdentity(value);
+        if (input !== null) return () => invoke(input);
+      } catch {
+        // Query decoder errors are normalized to this input boundary.
+      }
+      throw new AuthMutationError('INVALID_AUTH_INPUT');
+    }
+    case 'login':
+    case 'register':
+    case 'forgotPassword':
+    case 'updatePassword': {
+      const invoke = captureMethod(provider, () => provider[method]);
+      const input = decodeAuthParameters(value);
+      return () => invoke(input);
+    }
+    default: {
+      const invalid: never = method;
+      void invalid;
+      throw new AuthMutationError('AUTH_METHOD_UNAVAILABLE');
+    }
+  }
+}

package/src/auth-query-contract.ts

@@ -0,0 +1,97 @@
+import { Type, type Static, type TSchema } from '@sinclair/typebox';
+import { snapshotPlainData } from './plain-data';
+import { checkExact } from './schema-validation';
+
+export const authErrorSchema = Type.Object({
+  message: Type.String(),
+  name: Type.Optional(Type.String()),
+}, { additionalProperties: false });
+
+// Auth hooks navigate within this application; external redirects belong to the provider.
+export const authRedirectSchema = Type.String({ pattern: '^/(?![/\\\\])[^\\\\\\x00-\\x20\\x7f]*$' });
+const identitySchema = Type.Intersect([
+  Type.Object({
+    id: Type.Optional(Type.String()),
+    name: Type.Optional(Type.String()),
+    email: Type.Optional(Type.String()),
+    avatar: Type.Optional(Type.String()),
+  }),
+  Type.Record(Type.String(), Type.Unknown()),
+]);
+const checkResultSchema = Type.Object({
+  authenticated: Type.Boolean(),
+  redirectTo: Type.Optional(authRedirectSchema),
+  error: Type.Optional(authErrorSchema),
+  logout: Type.Optional(Type.Boolean()),
+}, { additionalProperties: false });
+const errorResultSchema = Type.Object({
+  redirectTo: Type.Optional(authRedirectSchema),
+  logout: Type.Optional(Type.Boolean()),
+}, { additionalProperties: false });
+
+export type Identity = Static<typeof identitySchema>;
+export type CheckResult = Static<typeof checkResultSchema>;
+export type AuthErrorResult = Static<typeof errorResultSchema>;
+
+export class AuthErrorHandlingError extends Error {
+  constructor(readonly code: 'AUTH_ERROR_HANDLER_FAILED' | 'INVALID_AUTH_ERROR_RESULT' | 'AUTH_LOGOUT_FAILED') {
+    super({
+      AUTH_ERROR_HANDLER_FAILED: 'Authentication error handling failed.',
+      INVALID_AUTH_ERROR_RESULT: 'Invalid authentication error handling result.',
+      AUTH_LOGOUT_FAILED: 'Authentication logout could not be confirmed.',
+    }[code]);
+    this.name = 'AuthErrorHandlingError';
+  }
+}
+
+export type AuthErrorHandlingResult =
+  | { status: 'ignored' | 'handled' | 'superseded' }
+  | { status: 'failed'; error: AuthErrorHandlingError };
+
+export function decodeAuthErrorResult(value: unknown): AuthErrorResult {
+  try {
+    const candidate = snapshotPlainData(value);
+    if (checkExact(errorResultSchema, candidate)) return Object.freeze(candidate);
+  } catch {
+    // Invalid provider instructions never become navigation or logout requests.
+  }
+  throw new AuthErrorHandlingError('INVALID_AUTH_ERROR_RESULT');
+}
+
+export class AuthQueryError extends Error {
+  constructor(readonly code: 'AUTH_QUERY_FAILED' | 'INVALID_AUTH_IDENTITY' | 'INVALID_AUTH_CHECK') {
+    super({
+      AUTH_QUERY_FAILED: 'Authentication query failed.',
+      INVALID_AUTH_IDENTITY: 'Invalid authentication identity.',
+      INVALID_AUTH_CHECK: 'Invalid authentication check result.',
+    }[code]);
+    this.name = 'AuthQueryError';
+  }
+}
+
+function decode<S extends TSchema>(schema: S, value: unknown, code: AuthQueryError['code']): Static<S> {
+  try {
+    const candidate = snapshotPlainData(value);
+    if (checkExact(schema, candidate)) return candidate;
+  } catch {
+    // Provider values and reflection errors must not escape the boundary.
+  }
+  throw new AuthQueryError(code);
+}
+
+export function decodeIdentity(value: unknown): Identity | null {
+  if (value === null) return null;
+  return Object.freeze(decode(identitySchema, value, 'INVALID_AUTH_IDENTITY'));
+}
+
+export function decodeAuthCheck(value: unknown): CheckResult {
+  const result = decode(checkResultSchema, value, 'INVALID_AUTH_CHECK');
+  if (result.authenticated && (result.logout === true || result.error !== undefined)) {
+    throw new AuthQueryError('INVALID_AUTH_CHECK');
+  }
+  // A validated string can still contain upstream credentials or private diagnostics.
+  if (result.error !== undefined) {
+    result.error = Object.freeze({ message: 'Authentication check failed.', name: 'AUTH_CHECK_REJECTED' });
+  }
+  return Object.freeze(result);
+}

package/src/captured-mutation.svelte.ts

@@ -0,0 +1,45 @@
+import { createMutation, type CreateMutationOptions, type MutateOptions } from '@tanstack/svelte-query';
+import { replaceReactiveUnionMembers } from './reactive-projection';
+
+interface Invocation<TParams, TScope> {
+  readonly params: TParams;
+  readonly scope: TScope | undefined;
+  readScope(): TScope;
+}
+
+/** Capture before the query runtime awaits callbacks, without keying state by user params. */
+export function createCapturedMutation<TData, TParams extends object, TScope, TContext = unknown>(
+  capture: (params: TParams) => TScope,
+  options: () => CreateMutationOptions<TData, unknown, Invocation<TParams, TScope>, TContext>,
+  projectContext: (value: TContext | undefined) => unknown,
+) {
+  function prepare(params: TParams): Invocation<TParams, TScope> {
+    try {
+      const scope = capture(params);
+      return Object.freeze({ params, scope, readScope: () => scope });
+    } catch (error) {
+      return Object.freeze({ params, scope: undefined, readScope: (): never => { throw error; } });
+    }
+  }
+  const mutation = createMutation<TData, unknown, Invocation<TParams, TScope>, TContext>(options);
+  function callbacks(value: MutateOptions<TData, unknown, TParams, unknown> = {}): MutateOptions<TData, unknown, Invocation<TParams, TScope>, TContext> {
+    return {
+      onSuccess: (data, invocation, context, execution) =>
+        value.onSuccess?.(data, invocation.params, projectContext(context), execution),
+      onError: (error, invocation, context, execution) =>
+        value.onError?.(error, invocation.params, projectContext(context), execution),
+      onSettled: (data, error, invocation, context, execution) =>
+        value.onSettled?.(data, error, invocation.params, projectContext(context), execution),
+    };
+  }
+  return replaceReactiveUnionMembers(mutation, {
+    get variables() { return mutation.variables?.params; },
+    get context() { return projectContext(mutation.context); },
+    mutate(params: TParams, value?: MutateOptions<TData, unknown, TParams, unknown>): void {
+      mutation.mutate(prepare(params), callbacks(value));
+    },
+    mutateAsync(params: TParams, value?: MutateOptions<TData, unknown, TParams, unknown>): Promise<TData> {
+      return mutation.mutateAsync(prepare(params), callbacks(value));
+    },
+  });
+}

package/src/chatProvider.svelte.ts

@@ -27,7 +27,7 @@ export interface ChatAttachment {
   mediaType?: string;
   url?: string;
   size?: number;
-  /** 原始浏览器文件，供上传适配器直接读取；持久化恢复时不会保留。 */
+  /** Original browser file for upload adapters; it is not retained after persistence restore. */
   file?: File;
 }
 

package/src/command-contract.ts

@@ -0,0 +1,195 @@
+import { Type, type TObject, type TSchema } from '@sinclair/typebox';
+import { TypeGuard } from '@sinclair/typebox/type';
+import { checkExact } from './schema-validation';
+import { closeContractSchema, type SafeSchema, type SchemaValue } from './resource-contract';
+import { snapshotPlainData } from './plain-data';
+import { HttpError, type DataProvider } from './types';
+
+const brand: unique symbol = Symbol('CommandContract');
+export interface CommandContract<I extends TObject = TObject, O extends TSchema = TSchema> {
+  readonly name: string;
+  readonly [brand]: { input: I; output: O };
+}
+export type CommandInput<I extends TObject> = SchemaValue<I> extends infer Input extends Record<string, unknown> ? Input : Record<string, unknown>;
+export type CommandOutput<O extends TSchema> = SchemaValue<O>;
+interface Definition {
+  key: string;
+  url: string;
+  method: 'get' | 'post' | 'put' | 'patch' | 'delete';
+  input: TSchema;
+  response: TSchema;
+}
+const definitions = new WeakMap<CommandContract, Definition>();
+let nextKey = 0;
+
+function invalidContract(): never {
+  throw new HttpError('Invalid command contract', 400, undefined, { code: 'INVALID_COMMAND_CONTRACT' });
+}
+
+function matches(schema: TSchema, value: unknown): boolean {
+  return checkExact(schema, value);
+}
+
+function inputSnapshot(definition: Definition, input: unknown): Record<string, unknown> {
+  try {
+    const candidate = snapshotPlainData(input);
+    if (typeof candidate === 'object' && candidate !== null && !Array.isArray(candidate) &&
+        matches(definition.input, candidate)) return candidate;
+  } catch {
+    // Reflection and validation errors must not expose submitted values.
+  }
+  throw new HttpError('Invalid command input', 422, undefined, { code: 'INVALID_COMMAND_INPUT' });
+}
+
+function responseSnapshot(definition: Definition, response: unknown): { data: unknown } {
+  try {
+    const candidate = snapshotPlainData(response);
+    if (typeof candidate === 'object' && candidate !== null && !Array.isArray(candidate) &&
+        Object.hasOwn(candidate, 'data') && matches(definition.response, candidate)) {
+      return { data: candidate['data'] };
+    }
+  } catch {
+    // Never retain a rejected response or execute its getters/serialization hooks.
+  }
+  throw new HttpError('Invalid command response', 502, undefined, {
+    code: 'INVALID_COMMAND_RESPONSE',
+    details: { writeMayHaveSucceeded: definition.method !== 'get' },
+  });
+}
+
+function executionError(error: unknown, writeMayHaveSucceeded: boolean): HttpError {
+  let status = 502;
+  try {
+    if (typeof error === 'object' && error !== null) {
+      const candidate: unknown = Object.getOwnPropertyDescriptor(error, 'statusCode')?.value;
+      if (typeof candidate === 'number' && Number.isInteger(candidate) && candidate >= 400 && candidate <= 599) {
+        status = candidate;
+      }
+    }
+  } catch {
+    // Error reflection failures are not authentication instructions.
+  }
+  return new HttpError('Command execution failed', status, undefined, {
+    code: 'COMMAND_FAILED', details: { writeMayHaveSucceeded },
+  });
+}
+
+export function defineCommand<I extends TObject, O extends TSchema>(
+  name: string,
+  definition: {
+    url: string;
+    method: Definition['method'];
+    input: I & SafeSchema<I>;
+    output: O & SafeSchema<O>;
+  },
+): CommandContract<I, O>;
+export function defineCommand(name: string, definition: {
+  url: string; method: Definition['method']; input: TObject; output: TSchema;
+}): CommandContract {
+  try {
+    if (typeof name !== 'string' || !name.trim() || typeof definition !== 'object' || definition === null) {
+      return invalidContract();
+    }
+    const fields = Object.getOwnPropertyDescriptors(definition);
+    for (const key of ['url', 'method', 'input', 'output']) {
+      const descriptor = fields[key];
+      if (!descriptor || !('value' in descriptor)) return invalidContract();
+    }
+    const url: unknown = fields['url']?.value;
+    const method: unknown = fields['method']?.value;
+    const inputSchema: unknown = fields['input']?.value;
+    const outputSchema: unknown = fields['output']?.value;
+    if (typeof url !== 'string' || !url.trim() ||
+        (method !== 'get' && method !== 'post' && method !== 'put' && method !== 'patch' && method !== 'delete') ||
+        !TypeGuard.IsObject(inputSchema) || !TypeGuard.IsSchema(outputSchema)) {
+      return invalidContract();
+    }
+    const input = closeContractSchema(inputSchema);
+    const response = Type.Object({ data: closeContractSchema(outputSchema) }, { additionalProperties: false });
+    const contract: CommandContract = Object.freeze({
+      name, [brand]: Object.freeze({ input: inputSchema, output: outputSchema }),
+    });
+    definitions.set(contract, {
+      key: JSON.stringify([++nextKey, name, url, method, input, response]),
+      url, method, input, response,
+    });
+    return contract;
+  } catch {
+    return invalidContract();
+  }
+}
+
+function definitionOf(command: CommandContract): Definition {
+  const definition = definitions.get(command);
+  if (!definition) throw new HttpError('Use defineCommand to create a command contract', 400, undefined, { code: 'INVALID_COMMAND_CONTRACT' });
+  return definition;
+}
+
+export function commandDefinition(command: CommandContract): Readonly<Pick<Definition, 'key' | 'url' | 'method'>> {
+  const { key, url, method } = definitionOf(command);
+  return Object.freeze({ key, url, method });
+}
+
+export function parseCommandInput<I extends TObject, O extends TSchema>(
+  command: CommandContract<I, O>, input: unknown,
+): CommandInput<I>;
+export function parseCommandInput(command: CommandContract, input: unknown): Record<string, unknown> {
+  return inputSnapshot(definitionOf(command), input);
+}
+
+export function parseCommandResponse<I extends TObject, O extends TSchema>(
+  command: CommandContract<I, O>, response: unknown,
+): { data: CommandOutput<O> };
+export function parseCommandResponse(command: CommandContract, response: unknown): { data: unknown } {
+  return responseSnapshot(definitionOf(command), response);
+}
+
+/** Capture transport and checked input before a scheduler can yield to another scope. */
+export function prepareCommand<I extends TObject, O extends TSchema>(
+  provider: DataProvider,
+  command: CommandContract<I, O>,
+  input: NoInfer<CommandInput<I>>,
+): { readonly input: CommandInput<I>; execute(): Promise<{ data: CommandOutput<O> }> };
+export function prepareCommand(
+  provider: DataProvider,
+  command: CommandContract,
+  input: Record<string, unknown>,
+): { readonly input: Record<string, unknown>; execute(): Promise<{ data: unknown }> } {
+  const definition = definitionOf(command);
+  const payload = inputSnapshot(definition, input);
+  let custom: DataProvider['custom'];
+  try {
+    custom = provider.custom;
+  } catch (error) {
+    throw executionError(error, false);
+  }
+  if (typeof custom !== 'function') {
+    throw new HttpError('Provider does not support commands', 400, undefined, { code: 'COMMAND_NOT_SUPPORTED' });
+  }
+  const dispatch = custom;
+  return Object.freeze({
+    get input() { return inputSnapshot(definition, payload); },
+    async execute() {
+      let response: unknown;
+      try {
+        const input = inputSnapshot(definition, payload);
+        const pending: unknown = Reflect.apply(dispatch, provider, [{
+          url: definition.url, method: definition.method,
+          ...(definition.method === 'get' ? { query: input } : { payload: input }),
+        }]);
+        response = await pending;
+      } catch (error) {
+        throw executionError(error, definition.method !== 'get');
+      }
+      return responseSnapshot(definition, response);
+    },
+  });
+}
+
+export async function executeCommand<I extends TObject, O extends TSchema>(
+  provider: DataProvider,
+  command: CommandContract<I, O>,
+  input: NoInfer<CommandInput<I>>,
+): Promise<{ data: CommandOutput<O> }> {
+  return prepareCommand(provider, command, input).execute();
+}