@_tc/template-core 0.0.1-bate.54 → 0.0.1-bate.56

package/.skills/tc-generator/reference/runtime-extensions.md

@@ -76,6 +76,74 @@ module.exports = (app) => {
 
 If the runtime does not support the built-in SQLite module or the project needs another store, generate `app/extend/db.js` or `app/extend/db.ts` and preserve the same method names so existing controllers keep working.
 
+## Default Crypto
+
+`app.extends.crypto` is available by default for backend code. It uses `app.config.signKey` as the default signing secret.
+
+Use it for lightweight signed payloads, auth tokens, API signatures, base64url encoding, and constant-time string comparison.
+
+Common methods:
+
+```ts
+app.extends.crypto.base64urlEncode(value)
+app.extends.crypto.base64urlDecode(value)
+app.extends.crypto.base64urlDecodeToBuffer(value)
+app.extends.crypto.hmacSign(payload, { secret, algorithm })
+app.extends.crypto.safeEqual(left, right)
+app.extends.crypto.createSignedPayload(payload, { secret, algorithm, separator })
+app.extends.crypto.verifySignedPayload(token, { secret, algorithm, separator })
+```
+
+Signed payload example:
+
+```js
+module.exports = (app) => {
+  return class AuthService {
+    createToken(account) {
+      const now = Date.now();
+
+      return app.extends.crypto.createSignedPayload({
+        account,
+        exp: now + 1000 * 60 * 60 * 24 * 7,
+        iat: now,
+      });
+    }
+
+    verifyToken(token) {
+      const payload = app.extends.crypto.verifySignedPayload(
+        token && token.replace(/^Bearer\s+/i, "")
+      );
+
+      if (!payload || Date.now() > payload.exp) return null;
+
+      return payload;
+    }
+
+    comparePassword(inputPassword, storedPassword) {
+      return app.extends.crypto.safeEqual(inputPassword, storedPassword);
+    }
+  };
+};
+```
+
+Custom signing options:
+
+```js
+const token = app.extends.crypto.createSignedPayload(
+  { id: 1, scope: "admin" },
+  {
+    secret: "custom-secret",
+    algorithm: "sha512",
+    separator: ".",
+  }
+);
+
+const payload = app.extends.crypto.verifySignedPayload(token, {
+  secret: "custom-secret",
+  algorithm: "sha512",
+});
+```
+
 ## Dashboard Component Slot
 
 Use `frontend/extended/dash/components.tsx` to fill supported Dashboard slots. The current slot is:

package/AGENT_README.md

@@ -184,6 +184,7 @@ export default (_app: KoaApp) => {
 内置扩展：
 
 - `app.extends.$fetch`：Node 侧 axios 风格 fetch 实例。
+- `app.extends.crypto`：Node 侧加密辅助方法，支持 base64url 编解码、HMAC 签名、签名 payload 和常量时间比较。
 - `app.extends.db`：默认 SQLite 数据存储，可用业务 `app/extend/db.ts` 覆盖。
 
 ## 4. model 配置

package/README.md

@@ -659,6 +659,7 @@ model/**/*.(js|ts)               -> 项目模型配置
 内置扩展：
 
 - `app.extends.$fetch`：Node 侧基于 `fetch` 的 axios 风格请求实例，支持 `get/post/put/patch/delete` 和 `create(config)`。
+- `app.extends.crypto`：Node 侧加密辅助方法，支持 base64url 编解码、HMAC 签名、签名 payload 和常量时间比较。
 - `app.extends.db`：默认 SQLite 框架数据库，提供 `getDBData/setDBData` 等通用数据方法。
 
 ### 数据库扩展
@@ -722,6 +723,36 @@ SQL 注入边界：
 - `queryDB`、`runDB`、`getDBFirst` 是原始 SQL 入口，用户输入必须放到 `params`，不要拼接到 SQL 字符串里。
 - `execDB` 没有参数绑定能力，只建议用于固定 SQL，例如建表或迁移。
 
+### 加密扩展
+
+`app.extends.crypto` 默认使用 `app.config.signKey` 作为签名密钥，适合生成登录 token、接口签名和安全比较。
+
+常用方法：
+
+- `base64urlEncode(value)`：把字符串或二进制数据编码为 base64url。
+- `base64urlDecode(value)`：把 base64url 解码回 UTF-8 字符串。
+- `base64urlDecodeToBuffer(value)`：把 base64url 解码回 Buffer。
+- `hmacSign(payload, options)`：对文本做 HMAC 签名，默认算法 `sha256`。
+- `safeEqual(left, right)`：常量时间比较字符串。
+- `createSignedPayload(payload, options)`：生成 `payload.signature` 形式的签名串。
+- `verifySignedPayload(token, options)`：验证并解析签名串，失败返回 `null`。
+
+```ts
+const token = app.extends.crypto.createSignedPayload({
+  account: 'admin',
+  exp: Date.now() + 1000 * 60 * 60 * 24 * 7,
+  iat: Date.now(),
+})
+
+const payload = app.extends.crypto.verifySignedPayload<{
+  account: string
+  exp: number
+  iat: number
+}>(token)
+
+const same = app.extends.crypto.safeEqual('abc', 'abc')
+```
+
 ```ts
 // 推荐：参数绑定
 const users = app.extends.db.queryDB(

package/cjs/app/extend/crypto.js

@@ -0,0 +1 @@
+require(`../../_virtual/_rolldown/runtime.js`);let e=require(`node:crypto`);var t=`sha256`,n=`.`,r=`template-core-crypto`,i=(e,t)=>String(t??e.config.signKey??r),a=e=>e??t,o=e=>e||n,s=e=>Buffer.isBuffer(e)?e:Buffer.from(e),c=t=>{let n=e=>s(e).toString(`base64url`),r=e=>Buffer.from(e,`base64url`),c=e=>r(e).toString(`utf8`),l=(n,r)=>(0,e.createHmac)(a(r?.algorithm),i(t,r?.secret)).update(n).digest(`base64url`),u=(t,n)=>{let r=Buffer.from(t),i=Buffer.from(n);return r.length===i.length?(0,e.timingSafeEqual)(r,i):!1};return{base64urlEncode:n,base64urlDecode:c,base64urlDecodeToBuffer:r,hmacSign:l,safeEqual:u,createSignedPayload:(e,t)=>{let r=o(t?.separator),i=n(JSON.stringify(e));return`${i}${r}${l(i,t)}`},verifySignedPayload:(e,t)=>{if(!e)return null;let n=o(t?.separator),[r,i,...a]=e.split(n);if(!r||!i||a.length>0||!u(l(r,t),i))return null;try{return JSON.parse(c(r))}catch{return null}}}};module.exports=c;

package/esm/app/extend/crypto.js

@@ -0,0 +1,31 @@
+import { createHmac as e, timingSafeEqual as t } from "node:crypto";
+//#region app/extend/crypto.ts
+var n = "sha256", r = ".", i = "template-core-crypto", a = (e, t) => String(t ?? e.config.signKey ?? i), o = (e) => e ?? n, s = (e) => e || r, c = (e) => Buffer.isBuffer(e) ? e : Buffer.from(e), l = (n) => {
+	let r = (e) => c(e).toString("base64url"), i = (e) => Buffer.from(e, "base64url"), l = (e) => i(e).toString("utf8"), u = (t, r) => e(o(r?.algorithm), a(n, r?.secret)).update(t).digest("base64url"), d = (e, n) => {
+		let r = Buffer.from(e), i = Buffer.from(n);
+		return r.length === i.length ? t(r, i) : !1;
+	};
+	return {
+		base64urlEncode: r,
+		base64urlDecode: l,
+		base64urlDecodeToBuffer: i,
+		hmacSign: u,
+		safeEqual: d,
+		createSignedPayload: (e, t) => {
+			let n = s(t?.separator), i = r(JSON.stringify(e));
+			return `${i}${n}${u(i, t)}`;
+		},
+		verifySignedPayload: (e, t) => {
+			if (!e) return null;
+			let n = s(t?.separator), [r, i, ...a] = e.split(n);
+			if (!r || !i || a.length > 0 || !d(u(r, t), i)) return null;
+			try {
+				return JSON.parse(l(r));
+			} catch {
+				return null;
+			}
+		}
+	};
+};
+//#endregion
+export { l as default };

package/fe/frontend/apps/dash/Dashboard.js

@@ -1,6 +1,6 @@
+import { getAuthToken } from "../../src/common/auth/index.js";
 import { getText } from "../../src/common/language.js";
 import { generateMenuItemData } from "../../src/common/generateMenuData.js";
-import { getAuthTokenSync } from "../../src/common/auth/index.js";
 import defaultAlias_default from "../../../bundler/defaultAlias.js";
 import { Menu } from "../../../packages/react/ui/components/Menu/Menu.js";
 import "../../../packages/react/ui/components/index.js";
@@ -113,7 +113,7 @@ var Dashboard = () => {
 		if (initData && projectInfo) {
 			if (isInit.current) return;
 			if (typeof defaultRouteGuard_default === "function") {
-				const authToken = getAuthTokenSync();
+				const authToken = getAuthToken();
 				const loginUrl = defaultRouteGuard_default({
 					projectInfo,
 					params,

package/fe/frontend/apps/ui-components/index.js

@@ -1,16 +1,8 @@
-import { frontendLangKeys } from "../../src/language/index.js";
-import { getText } from "../../src/common/language.js";
-import { Button } from "../../../packages/react/ui/components/Button/Button.js";
-import "../../../packages/react/ui/components/index.js";
 import TestPage from "../../../packages/react/ui/components/testPage/index.js";
-import { jsx, jsxs } from "react/jsx-runtime";
+import { jsx } from "react/jsx-runtime";
 //#region frontend/apps/ui-components/index.tsx
 var ui_components_default = () => {
-	return /* @__PURE__ */ jsxs("div", { children: [
-		/* @__PURE__ */ jsx("h1", { children: getText(frontendLangKeys.uiComponentsTitle) }),
-		/* @__PURE__ */ jsx(Button, { children: getText(frontendLangKeys.uiComponentsButton) }),
-		/* @__PURE__ */ jsx(TestPage, {})
-	] });
+	return /* @__PURE__ */ jsx("div", { children: /* @__PURE__ */ jsx(TestPage, {}) });
 };
 //#endregion
 export { ui_components_default as default };

package/fe/frontend/src/common/auth/index.d.ts

@@ -1,6 +1,10 @@
+export declare const localKeyMap: {
+    AUTH_LOCAL_KEY: string;
+    API_AUTH_LOCAL_KEY: string;
+};
 export declare const AUTH_HEADER_KEY = "Authorization";
-export declare function getAuthTokenSync(): string | null;
-export declare function getAuthToken(): Promise<string | null>;
+export declare function getAuthToken(): string | null;
+export declare function setAuthToken(t: string): void | null;
 export declare function clearAuthToken(): Promise<void>;
 export declare const API_AUTH_HEADER_KEY = "projk";
 export declare const getApiAuth: () => string;

package/fe/frontend/src/common/auth/index.js

@@ -1,24 +1,27 @@
 //#region frontend/src/common/auth/index.ts
-var AUTH_LOCAL_KEY = "auth_token";
-var API_AUTH_LOCAL_KEY = "p_J_k";
+var localKeyMap = {
+	AUTH_LOCAL_KEY: "auth_token",
+	API_AUTH_LOCAL_KEY: "p_J_k"
+};
 var AUTH_HEADER_KEY = "Authorization";
-function getAuthTokenSync() {
+function getAuthToken() {
 	if (typeof localStorage === "undefined") return null;
-	return localStorage.getItem(AUTH_LOCAL_KEY);
+	return localStorage.getItem(localKeyMap.AUTH_LOCAL_KEY);
 }
-async function getAuthToken() {
-	return getAuthTokenSync();
+function setAuthToken(t) {
+	if (typeof localStorage === "undefined") return null;
+	return localStorage.setItem(localKeyMap.AUTH_LOCAL_KEY, t);
 }
 async function clearAuthToken() {
 	if (typeof localStorage === "undefined") return;
-	localStorage.removeItem(AUTH_LOCAL_KEY);
+	localStorage.removeItem(localKeyMap.AUTH_LOCAL_KEY);
 }
 var API_AUTH_HEADER_KEY = "projk";
 var getApiAuth = () => {
-	return localStorage.getItem(API_AUTH_LOCAL_KEY) ?? "";
+	return localStorage.getItem(localKeyMap.API_AUTH_LOCAL_KEY) ?? "";
 };
 var setApiAuth = (v) => {
-	return localStorage.setItem(API_AUTH_LOCAL_KEY, v);
+	return localStorage.setItem(localKeyMap.API_AUTH_LOCAL_KEY, v);
 };
 //#endregion
-export { API_AUTH_HEADER_KEY, AUTH_HEADER_KEY, clearAuthToken, getApiAuth, getAuthToken, getAuthTokenSync, setApiAuth };
+export { API_AUTH_HEADER_KEY, AUTH_HEADER_KEY, clearAuthToken, getApiAuth, getAuthToken, localKeyMap, setApiAuth, setAuthToken };

package/fe/frontend/src/common/request.js

@@ -1,6 +1,6 @@
+import { API_AUTH_HEADER_KEY, AUTH_HEADER_KEY, clearAuthToken, getApiAuth, getAuthToken } from "./auth/index.js";
 import { frontendLangKeys } from "../language/index.js";
 import { getText } from "./language.js";
-import { API_AUTH_HEADER_KEY, AUTH_HEADER_KEY, clearAuthToken, getApiAuth, getAuthToken } from "./auth/index.js";
 import { FreezeState, apiFreezerStore } from "../stores/apiFreezer.js";
 import FetchAxios from "../../../packages/common/http/index.js";
 import md5 from "md5";

package/fe/frontend/src/index.d.ts

@@ -2,10 +2,11 @@ import "./typing/scalability";
 export type * from "../apps/dash/types";
 export * from "./main";
 export type { CallComComponentsMap, CallComRenderer } from "./defaultPages/SchemaPage/schemaType";
-export type { FormFieldSchema, SchemaFormComponentsMap, SchemaFormNamespace, SelectProps } from "../../packages/react/ui/index";
 export * from "./components/index";
+export type { FormFieldSchema, SchemaFormComponentsMap, SchemaFormNamespace, SelectProps } from "../../packages/react/ui/index";
 export { del, get, patch, post, put, request } from "./common/request";
 export * from "./defaultPages/SchemaPage/data/eventInfo";
 export { merge } from "./defaultPages/SchemaPage/utils/permissions";
 export * from "./exportStore";
 export { i18n, i18nStore } from "../../packages/react/ui/i18n/index";
+export { getAuthToken, localKeyMap, setAuthToken } from "./common/auth/index";

package/fe/frontend/src/index.js

@@ -1,3 +1,4 @@
+import { getAuthToken, localKeyMap, setAuthToken } from "./common/auth/index.js";
 import { i18n, i18nStore } from "../../packages/common/i18n/index.js";
 import "../../packages/react/ui/i18n/index.js";
 import { FreezeState, apiFreezerStore, useApiFreezer } from "./stores/apiFreezer.js";
@@ -16,4 +17,4 @@ import ThemeSwitch_default from "./components/ThemeSwitch/index.js";
 import "./components/index.js";
 import { eventsInfo } from "./defaultPages/SchemaPage/data/eventInfo.js";
 import { merge } from "./defaultPages/SchemaPage/utils/permissions.js";
-export { AsyncSelect_default as AsyncSelect, FreezeState, HeaderView, LanguageSwitch_default as LanguageSwitch, ThemeSwitch_default as ThemeSwitch, apiFreezerStore, del, eventsInfo, generateRouter, get, i18n, i18nStore, initApp, merge, modeStore, patch, post, put, request, schemaEventBus, schemaStore, themeSwitchStorageKey, useApiFreezer, useModeStore, useSchemaStore };
+export { AsyncSelect_default as AsyncSelect, FreezeState, HeaderView, LanguageSwitch_default as LanguageSwitch, ThemeSwitch_default as ThemeSwitch, apiFreezerStore, del, eventsInfo, generateRouter, get, getAuthToken, i18n, i18nStore, initApp, localKeyMap, merge, modeStore, patch, post, put, request, schemaEventBus, schemaStore, setAuthToken, themeSwitchStorageKey, useApiFreezer, useModeStore, useSchemaStore };

package/fe/frontend/src/stores/mode.js

@@ -1,5 +1,5 @@
-import { createStoreHook } from "../../../packages/react/ui/lib/createStoreHook.js";
 import { setApiAuth } from "../common/auth/index.js";
+import { createStoreHook } from "../../../packages/react/ui/lib/createStoreHook.js";
 import { getModelList, getProjectData } from "../api/baseInfo.js";
 import { deserializationUrlSearch } from "../common/menu.js";
 import { createStore } from "zustand";

package/model/frontend/src/common/auth/index.d.ts

@@ -1,6 +1,10 @@
+export declare const localKeyMap: {
+    AUTH_LOCAL_KEY: string;
+    API_AUTH_LOCAL_KEY: string;
+};
 export declare const AUTH_HEADER_KEY = "Authorization";
-export declare function getAuthTokenSync(): string | null;
-export declare function getAuthToken(): Promise<string | null>;
+export declare function getAuthToken(): string | null;
+export declare function setAuthToken(t: string): void | null;
 export declare function clearAuthToken(): Promise<void>;
 export declare const API_AUTH_HEADER_KEY = "projk";
 export declare const getApiAuth: () => string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@_tc/template-core",
-  "version": "0.0.1-bate.54",
+  "version": "0.0.1-bate.56",
   "description": "A full-stack TypeScript admin framework powered by Koa, React, and Vite - monorepo root",
   "types": "./types/index.d.ts",
   "exports": {

package/types/app/extend/crypto.d.ts

@@ -0,0 +1,64 @@
+import type { KoaApp } from "../type";
+export type CryptoHashAlgorithm = 'sha256' | 'sha384' | 'sha512';
+export interface HmacSignOptions {
+    secret?: string;
+    algorithm?: CryptoHashAlgorithm;
+}
+export interface SignedPayloadOptions extends HmacSignOptions {
+    separator?: string;
+}
+export interface VerifySignedPayloadOptions extends HmacSignOptions {
+    separator?: string;
+}
+export interface CryptoExtend {
+    /**
+     * 将 UTF-8 字符串或二进制数据编码为 base64url 字符串。
+     *
+     * base64url 不包含 `+`、`/` 和结尾 `=`，适合放在 URL、Cookie、Header 或 token 片段中。
+     */
+    base64urlEncode: (value: string | Buffer | Uint8Array) => string;
+    /**
+     * 将 base64url 字符串解码为 UTF-8 字符串。
+     *
+     * 常用于还原 token payload；如果原始内容不是 UTF-8 文本，请使用 `base64urlDecodeToBuffer`。
+     */
+    base64urlDecode: (value: string) => string;
+    /**
+     * 将 base64url 字符串解码为 Buffer。
+     *
+     * 适合处理二进制 payload，避免 UTF-8 字符串转换造成数据损坏。
+     */
+    base64urlDecodeToBuffer: (value: string) => Buffer;
+    /**
+     * 使用 HMAC 对文本内容签名，并返回 base64url 签名。
+     *
+     * 默认使用 `app.config.signKey` 作为密钥、`sha256` 作为算法；可通过 options 覆盖。
+     */
+    hmacSign: (payload: string, options?: HmacSignOptions) => string;
+    /**
+     * 常量时间比较两个字符串是否相等。
+     *
+     * 用于比较密码、签名、token 等敏感值，降低普通字符串比较带来的计时攻击风险。
+     */
+    safeEqual: (left: string, right: string) => boolean;
+    /**
+     * 创建带签名的 payload 字符串。
+     *
+     * 返回格式默认为 `${base64url(JSON.stringify(payload))}.${hmacSign(encodedPayload)}`，
+     * 适合生成轻量登录 token 或一次性校验串。
+     */
+    createSignedPayload: <T>(payload: T, options?: SignedPayloadOptions) => string;
+    /**
+     * 验证带签名的 payload 字符串并还原原始对象。
+     *
+     * 签名不匹配、格式错误或 JSON 解析失败时返回 null，不向外抛出解析异常。
+     */
+    verifySignedPayload: <T = unknown>(signedPayload: string | null | undefined, options?: VerifySignedPayloadOptions) => T | null;
+}
+/**
+ * 创建框架加密扩展对象。
+ *
+ * 该扩展会挂载到 `app.extends.crypto`，用于复用 base64url 编码、HMAC 签名、签名 payload 和安全比较能力。
+ */
+declare const _default: (app: KoaApp) => CryptoExtend;
+export default _default;

package/types/app/type.d.ts

@@ -3,3 +3,4 @@ export type KoaRouter = import('./typings').KoaRouter;
 export type Ctx = KoaApp['context'];
 export type ControllerFN<T extends object = object> = (app: KoaApp) => new () => T;
 export type ServiceFN<T extends object = object> = (app: KoaApp) => new () => T;
+export type RouterFN = (app: KoaApp, router: KoaRouter) => void;

package/types/app/typings.d.ts

@@ -4,6 +4,7 @@ import type { DefaultAppConfig } from "../config/config.default";
 import type getProjectController from "./controller/project";
 import type getViewController from "./controller/view";
 import type getFetch from "./extend/$fetch";
+import type getCrypto from "./extend/crypto";
 import type getDB from "./extend/db";
 import type generateErrorMessage from "./extend/generateErrorMessage";
 import type getLogger from "./extend/logger";
@@ -21,6 +22,7 @@ declare module '../packages/core/index' {
             view: GetInstance<typeof getViewController>;
         }
         interface IExtendsAugmented {
+            crypto: ReturnType<typeof getCrypto>;
             db: UnwrapPromise<ReturnType<typeof getDB>>;
             logger: UnwrapPromise<ReturnType<typeof getLogger>>;
             generateErrorMessage: ReturnType<typeof generateErrorMessage>;

package/types/index.d.ts

@@ -3,8 +3,9 @@ import type Router from "koa-router";
 import "./app/typings";
 import { MOmit } from "./typings/type";
 export type { FrameworkAugment, KoaApp } from "./packages/core/index";
-export type { ControllerFN, Ctx, ServiceFN } from "./app/type";
+export type { CryptoExtend, CryptoHashAlgorithm, HmacSignOptions, SignedPayloadOptions, VerifySignedPayloadOptions, } from "./app/extend/crypto";
 export type { DB, DBDataOptions, DBDataRecord, DBFactory, DBRunResult, FrameworkDB, ListDBDataOptions, SQLiteParams, SQLiteValue, } from "./app/extend/db";
+export type { ControllerFN, Ctx, RouterFN, ServiceFN } from "./app/type";
 export type { Router };
 export declare const serverStart: (options?: MOmit<StartOptions, "frameBaseDir">) => Promise<import("./packages/core/index").KoaApp>;
 export declare const baseFn: {