@visiblebase/core 0.2.0

package/README.md

@@ -0,0 +1,127 @@
+# @visiblebase/base
+
+`@visiblebase/base` 是 VisibleBase 的服务端 Runtime。
+
+它负责这些共用能力：
+
+- 初始化默认 Runtime 数据库 `products`
+- 校验 `user_token`
+- 提供 Fetch 风格 HTTP handler
+- 管理 Runtime `.env`
+- 用 `base.model(meta).handle()` 注册场景模型和执行 handler
+
+## 安装
+
+```bash
+pnpm add @visiblebase/base
+```
+
+需要 Node `>=22.13.0`。
+
+## 最小示例
+
+```ts
+import { Base } from "@visiblebase/base";
+
+const base = new Base();
+
+base.model({
+  id: "local-echo",
+  name: "Local Echo",
+  default: ["text"],
+}).handle({
+  text: async (ctx) => ({
+    id: crypto.randomUUID(),
+    role: "assistant",
+    parts: [
+      {
+        type: "text",
+        text: `echo: ${ctx.input.prompt}`,
+        state: "done",
+      },
+    ],
+  }),
+});
+
+const server = await base.serve({
+  host: "127.0.0.1",
+  port: 3001,
+});
+
+console.log(`VisibleBase listening on http://${server.host}:${server.port}`);
+```
+
+这段代码不要求你自己打开 SQLite 或手写 `visiblebase_models`。`client.models()` 读取的是 `base.model(meta).handle()` 注册出来的运行时目录。
+
+默认情况下，Base 会在第一次 `serve()`、`handleRequest()`、`models()`、`invoke()` 或 `table()` 操作时自动初始化。常规使用不需要手动调用 `init()`。
+
+## 主要导出
+
+- `Base`
+- `VisibleBase`
+- 模型类型：`ModelMeta`、`ModelHandlers`、`RuntimeModel`
+- 插件类型：`BasePlugin`、`BasePluginRoute`、`BasePluginContext`
+- 默认数据库 schema：`sqliteProducts`、`pgProducts`
+- `DotenvRuntimeEnv`
+
+## 业务表
+
+业务表通过 `new Base({ schema })` 注册，然后用 `base.table(name)` 操作：
+
+```ts
+import { sqliteTable, text } from "drizzle-orm/sqlite-core";
+import { Base } from "@visiblebase/base";
+
+const notes = sqliteTable("notes", {
+  id: text("id").primaryKey(),
+  title: text("title").notNull(),
+});
+
+const base = new Base({
+  schema: {
+    notes,
+  },
+});
+
+await base.table("notes").insert({
+  id: "note_1",
+  title: "First note",
+});
+
+const rows = await base.table("notes").select();
+```
+
+## 插件
+
+插件用于把多个 client 产品会复用的 Base 能力封装起来，例如用户注册登录、支付、订阅权益、usage 扣费或通知。
+
+```ts
+import { Base } from "@visiblebase/base";
+import { authPlugin } from "@visiblebase/plugin-auth";
+import { usagePlugin } from "@visiblebase/plugin-usage";
+import { stripePaymentPlugin } from "@visiblebase/plugin-payment-stripe";
+
+const base = new Base({
+  plugins: [
+    authPlugin(),
+    usagePlugin(),
+    stripePaymentPlugin(),
+  ],
+});
+```
+
+Base 使用者不需要为官方插件定义数据库表。插件包内部会声明自己的表，Base 在首次运行时自动创建。
+
+`models` 和 `products` 也是默认内置插件。你不传 `plugins` 时，Base 会自动启用它们；你传入其他插件时，它们仍然保留；如果你传入同 ID 的 `models` 或 `products` 插件，则会替换默认实现。
+
+插件路由按鉴权模式挂载：
+
+- `auth: "public"` 和 `auth: "user"`：`/v1/plugins/{pluginId}/{path}`
+- `auth: "admin"`：`/api/admin/plugins/{pluginId}/{path}`
+
+如果你在开发插件，插件可以声明自己的 `schema`，并通过 `ctx.table(name)` 读写插件表；也可以通过 `ctx.hook.before()`、`ctx.hook.after()` 和 `ctx.hook.onError()` 介入 service 调用。
+
+## 文档
+
+- 仓库首页：[visiblebase](https://github.com/wangenius/visiblebase)
+- 文档目录：[homepage/content/docs](https://github.com/wangenius/visiblebase/tree/main/homepage/content/docs)

package/bin/core/auth/authenticator.d.ts

@@ -0,0 +1,68 @@
+/**
+ * 统一鉴权模块。
+ *
+ * Authenticator 统一处理 admin（secret key）和 user（JWT token）两种鉴权方式。
+ * 所有鉴权失败统一抛出 httpError（ErrorWithStatus）。
+ *
+ * TokenSigner 实例通过 getSigner() 缓存，避免重复 new TokenSigner(key)。
+ */
+import type { RouteAuth } from "../../service/service.js";
+import type { EnvProvider } from "../runtime.js";
+import type { CreateUserTokenInput, UserTokenPayload, UserTokenIssueResult, RuntimeUser } from "./types.js";
+/** 鉴权级别 */
+/** 鉴权结果 */
+export interface AuthResult {
+    /** 鉴权后的实际级别 */
+    level: RouteAuth;
+    /** 解析出的用户信息（user 级别时可用） */
+    user?: RuntimeUser;
+    /** 解析出的 Product 信息（user 级别时可用） */
+    product?: {
+        product_id: string;
+        status: string;
+    };
+}
+/** 统一鉴权器 */
+export declare class Authenticator {
+    private env;
+    private store;
+    /** 缓存的 TokenSigner 实例 */
+    private tokenSigner?;
+    constructor(env: EnvProvider, store: () => Promise<{
+        product: {
+            get(id: string): Promise<{
+                product_id: string;
+                status: string;
+            } | undefined>;
+        };
+    }>);
+    /**
+     * 获取（或创建）TokenSigner 单例。
+     *
+     * 首次调用时从 env 读取 VISIBLEBASE_TOKEN_SIGNING_KEY 创建实例并缓存。
+     */
+    private getSigner;
+    /**
+     * 对请求执行鉴权。
+     *
+     * @param request - 原始 HTTP Request
+     * @param required - 要求的鉴权级别
+     * @returns 鉴权结果（含 user/product 信息）
+     */
+    authenticate(request: Request, required: RouteAuth): Promise<AuthResult>;
+    /**
+     * 签发 user_token（验证 product 状态后签发）。
+     *
+     * @param input - token 创建参数
+     * @returns 签发结果（含 token 字符串）
+     */
+    createToken(input: CreateUserTokenInput): Promise<UserTokenIssueResult>;
+    /**
+     * 校验 user_token 并返回载荷。
+     *
+     * @param token - user_token 字符串
+     * @returns 解析出的 token 载荷
+     */
+    verifyToken(token: string): Promise<UserTokenPayload>;
+}
+//# sourceMappingURL=authenticator.d.ts.map

package/bin/core/auth/authenticator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"authenticator.d.ts","sourceRoot":"","sources":["../../../src/core/auth/authenticator.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAC1D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAEjD,OAAO,KAAK,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE5G,WAAW;AACX,WAAW;AACX,MAAM,WAAW,UAAU;IACzB,eAAe;IACf,KAAK,EAAE,SAAS,CAAC;IACjB,2BAA2B;IAC3B,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB,kCAAkC;IAClC,OAAO,CAAC,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CAClD;AAED,YAAY;AACZ,qBAAa,aAAa;IAKtB,OAAO,CAAC,GAAG;IACX,OAAO,CAAC,KAAK;IALf,yBAAyB;IACzB,OAAO,CAAC,WAAW,CAAC,CAAc;gBAGxB,GAAG,EAAE,WAAW,EAChB,KAAK,EAAE,MAAM,OAAO,CAAC;QAAE,OAAO,EAAE;YAAE,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC;gBAAE,UAAU,EAAE,MAAM,CAAC;gBAAC,MAAM,EAAE,MAAM,CAAA;aAAE,GAAG,SAAS,CAAC,CAAA;SAAE,CAAA;KAAE,CAAC;IAG7H;;;;OAIG;IACH,OAAO,CAAC,SAAS;IASjB;;;;;;OAMG;IACG,YAAY,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC;IAgC9E;;;;;OAKG;IACG,WAAW,CAAC,KAAK,EAAE,oBAAoB,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAiB7E;;;;;OAKG;IACG,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;CAG5D"}

package/bin/core/auth/authenticator.js

@@ -0,0 +1,106 @@
+/**
+ * 统一鉴权模块。
+ *
+ * Authenticator 统一处理 admin（secret key）和 user（JWT token）两种鉴权方式。
+ * 所有鉴权失败统一抛出 httpError（ErrorWithStatus）。
+ *
+ * TokenSigner 实例通过 getSigner() 缓存，避免重复 new TokenSigner(key)。
+ */
+import { bearerToken, httpError } from "../../utils/helpers.js";
+import { TokenSigner } from "./token-signer.js";
+/** 统一鉴权器 */
+export class Authenticator {
+    env;
+    store;
+    /** 缓存的 TokenSigner 实例 */
+    tokenSigner;
+    constructor(env, store) {
+        this.env = env;
+        this.store = store;
+    }
+    /**
+     * 获取（或创建）TokenSigner 单例。
+     *
+     * 首次调用时从 env 读取 VISIBLEBASE_TOKEN_SIGNING_KEY 创建实例并缓存。
+     */
+    getSigner() {
+        if (!this.tokenSigner) {
+            const signingKey = this.env.get("VISIBLEBASE_TOKEN_SIGNING_KEY");
+            if (!signingKey)
+                throw new Error("VISIBLEBASE_TOKEN_SIGNING_KEY is required");
+            this.tokenSigner = new TokenSigner(signingKey);
+        }
+        return this.tokenSigner;
+    }
+    /**
+     * 对请求执行鉴权。
+     *
+     * @param request - 原始 HTTP Request
+     * @param required - 要求的鉴权级别
+     * @returns 鉴权结果（含 user/product 信息）
+     */
+    async authenticate(request, required) {
+        if (required === "public") {
+            return { level: "public" };
+        }
+        const token = bearerToken(request);
+        if (!token) {
+            throw httpError(401, "Missing authorization token");
+        }
+        // admin 鉴权
+        if (required === "admin") {
+            const adminKey = this.env.get("VISIBLEBASE_ADMIN_SECRET_KEY");
+            if (!adminKey)
+                throw httpError(500, "VISIBLEBASE_ADMIN_SECRET_KEY is required");
+            if (token !== adminKey)
+                throw httpError(401, "Invalid admin_secret_key");
+            return { level: "admin" };
+        }
+        // user 鉴权
+        const payload = await this.getSigner().verify(token);
+        const store = await this.store();
+        const product = await store.product.get(payload.product_id);
+        if (!product)
+            throw httpError(401, "Unknown token product");
+        if (product.status !== "active")
+            throw httpError(403, "Token product is not active");
+        return {
+            level: "user",
+            user: { user_id: payload.user_id, metadata: payload.metadata ?? {} },
+            product,
+        };
+    }
+    /**
+     * 签发 user_token（验证 product 状态后签发）。
+     *
+     * @param input - token 创建参数
+     * @returns 签发结果（含 token 字符串）
+     */
+    async createToken(input) {
+        const store = await this.store();
+        const product = await store.product.get(input.product_id);
+        if (!product)
+            throw new Error(`Unknown product: ${input.product_id}`);
+        if (product.status !== "active")
+            throw new Error(`Product is not active: ${input.product_id}`);
+        const user_token = await this.getSigner().sign(input);
+        return {
+            user_token,
+            product_id: input.product_id,
+            user_id: input.user_id,
+            ...(input.ttl
+                ? { expires_at: new Date(Date.now() + TokenSigner.parseTTL(input.ttl) * 1000).toISOString() }
+                : {}),
+        };
+    }
+    /**
+     * 校验 user_token 并返回载荷。
+     *
+     * @param token - user_token 字符串
+     * @returns 解析出的 token 载荷
+     */
+    async verifyToken(token) {
+        return this.getSigner().verify(token);
+    }
+}
+//# sourceMappingURL=authenticator.js.map

package/bin/core/auth/authenticator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"authenticator.js","sourceRoot":"","sources":["../../../src/core/auth/authenticator.ts"],"names":[],"mappings":"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"}

package/bin/core/auth/token-signer.d.ts

@@ -0,0 +1,27 @@
+/**
+ * user_token 签发与校验模块。
+ *
+ * VisibleBase 使用 Web Crypto API 的 HMAC-SHA256 生成最小可用的 user_token。
+ * 零 Node.js 依赖，兼容所有现代运行时（Node、Workers、Deno、Bun、浏览器）。
+ */
+import type { CreateUserTokenInput, UserTokenPayload } from "./types.js";
+export declare class TokenSigner {
+    readonly signingKey: string;
+    /** 缓存的 CryptoKey，避免每次签名都重新 import */
+    private cryptoKey?;
+    constructor(signingKey: string);
+    /**
+     * 获取（或缓存）HMAC CryptoKey。
+     *
+     * 使用 Web Crypto API 的 crypto.subtle.importKey，
+     * 首次调用时创建并缓存 Promise，后续复用。
+     */
+    private getCryptoKey;
+    /** 签发 user_token */
+    sign(input: CreateUserTokenInput): Promise<string>;
+    /** 校验并解析 user_token，失败抛 httpError(401) */
+    verify(token: string): Promise<UserTokenPayload>;
+    /** 把 ttl 解析成秒数 */
+    static parseTTL(ttl: string | number): number;
+}
+//# sourceMappingURL=token-signer.d.ts.map

package/bin/core/auth/token-signer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-signer.d.ts","sourceRoot":"","sources":["../../../src/core/auth/token-signer.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEzE,qBAAa,WAAW;IACtB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAE5B,qCAAqC;IACrC,OAAO,CAAC,SAAS,CAAC,CAAqB;gBAE3B,UAAU,EAAE,MAAM;IAO9B;;;;;OAKG;IACH,OAAO,CAAC,YAAY;IAcpB,oBAAoB;IACd,IAAI,CAAC,KAAK,EAAE,oBAAoB,GAAG,OAAO,CAAC,MAAM,CAAC;IA4BxD,0CAA0C;IACpC,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;IA6BtD,kBAAkB;IAClB,MAAM,CAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM;CAyB9C"}

package/bin/core/auth/token-signer.js

@@ -0,0 +1,116 @@
+/**
+ * user_token 签发与校验模块。
+ *
+ * VisibleBase 使用 Web Crypto API 的 HMAC-SHA256 生成最小可用的 user_token。
+ * 零 Node.js 依赖，兼容所有现代运行时（Node、Workers、Deno、Bun、浏览器）。
+ */
+import { httpError, base64UrlEncode, base64UrlDecode, base64UrlEncodeBytes, base64UrlDecodeBytes, timingSafeEqualBytes } from "../../utils/helpers.js";
+export class TokenSigner {
+    signingKey;
+    /** 缓存的 CryptoKey，避免每次签名都重新 import */
+    cryptoKey;
+    constructor(signingKey) {
+        if (!signingKey) {
+            throw new Error("TokenSigner requires a signing key");
+        }
+        this.signingKey = signingKey;
+    }
+    /**
+     * 获取（或缓存）HMAC CryptoKey。
+     *
+     * 使用 Web Crypto API 的 crypto.subtle.importKey，
+     * 首次调用时创建并缓存 Promise，后续复用。
+     */
+    getCryptoKey() {
+        if (!this.cryptoKey) {
+            const encoder = new TextEncoder();
+            this.cryptoKey = crypto.subtle.importKey("raw", encoder.encode(this.signingKey), { name: "HMAC", hash: "SHA-256" }, false, ["sign", "verify"]);
+        }
+        return this.cryptoKey;
+    }
+    /** 签发 user_token */
+    async sign(input) {
+        if (!input || typeof input.product_id !== "string" || input.product_id.length === 0) {
+            throw new TypeError("product_id is required");
+        }
+        if (typeof input.user_id !== "string" || input.user_id.length === 0) {
+            throw new TypeError("user_id is required");
+        }
+        const ttl = input.ttl;
+        const now = Math.floor(Date.now() / 1000);
+        const payload = {
+            aud: "visiblebase:user",
+            product_id: input.product_id,
+            user_id: input.user_id,
+            metadata: input.metadata ?? {},
+            iat: now,
+        };
+        if (ttl) {
+            payload.exp = now + TokenSigner.parseTTL(ttl);
+        }
+        const encodedPayload = base64UrlEncode(JSON.stringify(payload));
+        const signature = await signPayload(await this.getCryptoKey(), encodedPayload);
+        return `ub_${encodedPayload}.${signature}`;
+    }
+    /** 校验并解析 user_token，失败抛 httpError(401) */
+    async verify(token) {
+        const rawToken = token.startsWith("ub_") ? token.slice(3) : token;
+        const [encodedPayload, signature] = rawToken.split(".");
+        if (!encodedPayload || !signature) {
+            throw httpError(401, "Invalid user token");
+        }
+        if (!await verifyPayload(await this.getCryptoKey(), encodedPayload, signature)) {
+            throw httpError(401, "Invalid user token signature");
+        }
+        const payload = JSON.parse(base64UrlDecode(encodedPayload));
+        const now = Math.floor(Date.now() / 1000);
+        if (payload.exp && payload.exp <= now) {
+            throw httpError(401, "User token expired");
+        }
+        if (payload.aud !== "visiblebase:user") {
+            throw httpError(401, "Invalid user token audience");
+        }
+        if (!payload.product_id || !payload.user_id) {
+            throw httpError(401, "Invalid user token payload");
+        }
+        return payload;
+    }
+    /** 把 ttl 解析成秒数 */
+    static parseTTL(ttl) {
+        if (typeof ttl === "number" && Number.isFinite(ttl) && ttl > 0) {
+            return ttl;
+        }
+        if (typeof ttl !== "string") {
+            throw new TypeError("ttl must be a positive number of seconds or a string like 1h");
+        }
+        const match = ttl.match(/^(\d+)(s|m|h|d)$/);
+        if (!match) {
+            throw new Error(`Invalid ttl: ${ttl}`);
+        }
+        const value = Number(match[1]);
+        const unit = match[2];
+        const multipliers = {
+            s: 1,
+            m: 60,
+            h: 60 * 60,
+            d: 24 * 60 * 60,
+        };
+        return value * multipliers[unit];
+    }
+}
+/**
+ * 使用 HMAC-SHA256 对 payload 签名，返回 base64url 编码的签名。
+ */
+async function signPayload(cryptoKey, encodedPayload) {
+    const signature = await crypto.subtle.sign("HMAC", cryptoKey, new TextEncoder().encode(encodedPayload));
+    return base64UrlEncodeBytes(new Uint8Array(signature));
+}
+/**
+ * 验证 HMAC-SHA256 签名是否匹配。
+ */
+async function verifyPayload(cryptoKey, encodedPayload, signature) {
+    const expected = base64UrlDecodeBytes(signature);
+    const actual = await crypto.subtle.sign("HMAC", cryptoKey, new TextEncoder().encode(encodedPayload));
+    return timingSafeEqualBytes(new Uint8Array(actual), expected);
+}
+//# sourceMappingURL=token-signer.js.map

package/bin/core/auth/token-signer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-signer.js","sourceRoot":"","sources":["../../../src/core/auth/token-signer.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,eAAe,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAGvJ,MAAM,OAAO,WAAW;IACb,UAAU,CAAS;IAE5B,qCAAqC;IAC7B,SAAS,CAAsB;IAEvC,YAAY,UAAkB;QAC5B,IAAI,CAAC,UAAU,EAAE,CAAC;YAChB,MAAM,IAAI,KAAK,CAAC,oCAAoC,CAAC,CAAC;QACxD,CAAC;QACD,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IAC/B,CAAC;IAED;;;;;OAKG;IACK,YAAY;QAClB,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC;YACpB,MAAM,OAAO,GAAG,IAAI,WAAW,EAAE,CAAC;YAClC,IAAI,CAAC,SAAS,GAAG,MAAM,CAAC,MAAM,CAAC,SAAS,CACtC,KAAK,EACL,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,EAC/B,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,EACjC,KAAK,EACL,CAAC,MAAM,EAAE,QAAQ,CAAC,CACnB,CAAC;QACJ,CAAC;QACD,OAAO,IAAI,CAAC,SAAS,CAAC;IACxB,CAAC;IAED,oBAAoB;IACpB,KAAK,CAAC,IAAI,CAAC,KAA2B;QACpC,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,CAAC,UAAU,KAAK,QAAQ,IAAI,KAAK,CAAC,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACpF,MAAM,IAAI,SAAS,CAAC,wBAAwB,CAAC,CAAC;QAChD,CAAC;QAED,IAAI,OAAO,KAAK,CAAC,OAAO,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACpE,MAAM,IAAI,SAAS,CAAC,qBAAqB,CAAC,CAAC;QAC7C,CAAC;QAED,MAAM,GAAG,GAAG,KAAK,CAAC,GAAG,CAAC;QACtB,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC;QAC1C,MAAM,OAAO,GAAqB;YAChC,GAAG,EAAE,kBAAkB;YACvB,UAAU,EAAE,KAAK,CAAC,UAAU;YAC5B,OAAO,EAAE,KAAK,CAAC,OAAO;YACtB,QAAQ,EAAE,KAAK,CAAC,QAAQ,IAAI,EAAE;YAC9B,GAAG,EAAE,GAAG;SACT,CAAC;QAEF,IAAI,GAAG,EAAE,CAAC;YACR,OAAO,CAAC,GAAG,GAAG,GAAG,GAAG,WAAW,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;QAChD,CAAC;QAED,MAAM,cAAc,GAAG,eAAe,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC;QAChE,MAAM,SAAS,GAAG,MAAM,WAAW,CAAC,MAAM,IAAI,CAAC,YAAY,EAAE,EAAE,cAAc,CAAC,CAAC;QAC/E,OAAO,MAAM,cAAc,IAAI,SAAS,EAAE,CAAC;IAC7C,CAAC;IAED,0CAA0C;IAC1C,KAAK,CAAC,MAAM,CAAC,KAAa;QACxB,MAAM,QAAQ,GAAG,KAAK,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;QAClE,MAAM,CAAC,cAAc,EAAE,SAAS,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAExD,IAAI,CAAC,cAAc,IAAI,CAAC,SAAS,EAAE,CAAC;YAClC,MAAM,SAAS,CAAC,GAAG,EAAE,oBAAoB,CAAC,CAAC;QAC7C,CAAC;QAED,IAAI,CAAC,MAAM,aAAa,CAAC,MAAM,IAAI,CAAC,YAAY,EAAE,EAAE,cAAc,EAAE,SAAS,CAAC,EAAE,CAAC;YAC/E,MAAM,SAAS,CAAC,GAAG,EAAE,8BAA8B,CAAC,CAAC;QACvD,CAAC;QAED,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,eAAe,CAAC,cAAc,CAAC,CAAqB,CAAC;QAChF,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC;QAC1C,IAAI,OAAO,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,IAAI,GAAG,EAAE,CAAC;YACtC,MAAM,SAAS,CAAC,GAAG,EAAE,oBAAoB,CAAC,CAAC;QAC7C,CAAC;QAED,IAAI,OAAO,CAAC,GAAG,KAAK,kBAAkB,EAAE,CAAC;YACvC,MAAM,SAAS,CAAC,GAAG,EAAE,6BAA6B,CAAC,CAAC;QACtD,CAAC;QAED,IAAI,CAAC,OAAO,CAAC,UAAU,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;YAC5C,MAAM,SAAS,CAAC,GAAG,EAAE,4BAA4B,CAAC,CAAC;QACrD,CAAC;QAED,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,kBAAkB;IAClB,MAAM,CAAC,QAAQ,CAAC,GAAoB;QAClC,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,GAAG,GAAG,CAAC,EAAE,CAAC;YAC/D,OAAO,GAAG,CAAC;QACb,CAAC;QAED,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;YAC5B,MAAM,IAAI,SAAS,CAAC,8DAA8D,CAAC,CAAC;QACtF,CAAC;QAED,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,kBAAkB,CAAC,CAAC;QAC5C,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,MAAM,IAAI,KAAK,CAAC,gBAAgB,GAAG,EAAE,CAAC,CAAC;QACzC,CAAC;QAED,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;QAC/B,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAA0B,CAAC;QAC/C,MAAM,WAAW,GAAG;YAClB,CAAC,EAAE,CAAC;YACJ,CAAC,EAAE,EAAE;YACL,CAAC,EAAE,EAAE,GAAG,EAAE;YACV,CAAC,EAAE,EAAE,GAAG,EAAE,GAAG,EAAE;SAChB,CAAC;QAEF,OAAO,KAAK,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC;IACnC,CAAC;CACF;AAED;;GAEG;AACH,KAAK,UAAU,WAAW,CAAC,SAAoB,EAAE,cAAsB;IACrE,MAAM,SAAS,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,IAAI,CACxC,MAAM,EACN,SAAS,EACT,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,cAAc,CAAC,CACzC,CAAC;IACF,OAAO,oBAAoB,CAAC,IAAI,UAAU,CAAC,SAAS,CAAC,CAAC,CAAC;AACzD,CAAC;AAED;;GAEG;AACH,KAAK,UAAU,aAAa,CAAC,SAAoB,EAAE,cAAsB,EAAE,SAAiB;IAC1F,MAAM,QAAQ,GAAG,oBAAoB,CAAC,SAAS,CAAC,CAAC;IACjD,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,IAAI,CACrC,MAAM,EACN,SAAS,EACT,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,cAAc,CAAC,CACzC,CAAC;IACF,OAAO,oBAAoB,CAAC,IAAI,UAAU,CAAC,MAAM,CAAC,EAAE,QAAQ,CAAC,CAAC;AAChE,CAAC"}

package/bin/core/auth/types.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Auth 域公共类型。
+ *
+ * 包含 token 相关的用户、载荷和签发结果类型。
+ */
+/**
+ * Runtime 中的终端用户信息。
+ */
+export interface RuntimeUser {
+    /**
+     * 开发者系统中的用户主键。
+     */
+    user_id: string;
+    /**
+     * 附带在 token 中的业务元数据。
+     */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * 签发 user_token 的输入。
+ */
+export interface CreateUserTokenInput {
+    /**
+     * token 所属的 Product ID。
+     */
+    product_id: string;
+    /**
+     * token 所属的终端用户 ID。
+     */
+    user_id: string;
+    /**
+     * 附带进 token 的业务元数据。
+     */
+    metadata?: Record<string, unknown>;
+    /**
+     * token 有效期。
+     *
+     * 支持 `30m`、`1h`、`7d` 或秒数。
+     */
+    ttl?: string | number;
+}
+/**
+ * user_token 的标准载荷。
+ */
+export interface UserTokenPayload {
+    /**
+     * token 受众。
+     */
+    aud: "visiblebase:user";
+    /**
+     * token 所属 Product ID。
+     */
+    product_id: string;
+    /**
+     * token 所属用户 ID。
+     */
+    user_id: string;
+    /**
+     * 业务元数据。
+     */
+    metadata?: Record<string, unknown>;
+    /**
+     * 签发时间。
+     */
+    iat: number;
+    /**
+     * 过期时间。
+     */
+    exp?: number;
+}
+/**
+ * Base 返回给管理端的发 token 结果。
+ */
+export interface UserTokenIssueResult {
+    /**
+     * 可交给 UserClient 使用的 token。
+     */
+    user_token: string;
+    /**
+     * token 所属 Product ID。
+     */
+    product_id: string;
+    /**
+     * token 所属用户 ID。
+     */
+    user_id: string;
+    /**
+     * token 过期时间。
+     *
+     * 未设置 ttl 时省略。
+     */
+    expires_at?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/bin/core/auth/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/core/auth/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC;;OAEG;IACH,UAAU,EAAE,MAAM,CAAC;IAEnB;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAEnC;;;;OAIG;IACH,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;OAEG;IACH,GAAG,EAAE,kBAAkB,CAAC;IAExB;;OAEG;IACH,UAAU,EAAE,MAAM,CAAC;IAEnB;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAEnC;;OAEG;IACH,GAAG,EAAE,MAAM,CAAC;IAEZ;;OAEG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC;;OAEG;IACH,UAAU,EAAE,MAAM,CAAC;IAEnB;;OAEG;IACH,UAAU,EAAE,MAAM,CAAC;IAEnB;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB"}

package/bin/core/auth/types.js

@@ -0,0 +1,7 @@
+/**
+ * Auth 域公共类型。
+ *
+ * 包含 token 相关的用户、载荷和签发结果类型。
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/bin/core/auth/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/core/auth/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/bin/core/base/base.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Base Runtime 主模块。
+ *
+ * Base 是运行时容器，只负责：Service 路由、鉴权、HTTP。
+ * 不知道任何具体 Service 的实现，所有 Service 通过 _onInit() 自初始化。
+ *
+ * 数据库连接、环境变量存储等运行时特定逻辑由 Runtime 适配器注入。
+ *
+ * 使用方式：
+ * ```ts
+ * import { Base } from "@visiblebase/core";
+ * import { node } from "@visiblebase/node";
+ *
+ * const base = new Base({ runtime: node({ database: "sqlite:./data.sqlite" }) });
+ * base.use(new AIService());
+ * // 路由始终是标准 Hono app
+ * serve({ fetch: base.router().fetch, port: 3000 });
+ * ```
+ */
+import { Hono } from "hono";
+import { type BaseTableApi } from "../../store/table-api.js";
+import { Service } from "../../service/service.js";
+import { type BasePlugin } from "../../service/plugin.js";
+import { Authenticator } from "../auth/authenticator.js";
+import type { BaseOptions, BaseHealthStatus } from "../types.js";
+import type { RuntimeUser } from "../auth/types.js";
+declare module "hono" {
+    interface ContextVariableMap {
+        user?: RuntimeUser;
+        product?: {
+            product_id: string;
+            status: string;
+        };
+    }
+}
+/**
+ * VisibleBase 运行时容器。
+ *
+ * 接收 Service 注册、构建 Hono 路由、管理初始化生命周期。
+ * 数据库和 env 通过 Runtime 适配器注入，不依赖任何特定运行时。
+ */
+export declare class Base {
+    private readonly runtime;
+    private readonly services;
+    private database?;
+    private client?;
+    private tableMap?;
+    private initPromise?;
+    private hono?;
+    private authenticator?;
+    constructor(options: BaseOptions);
+    /**
+     * 注册一个 Service。
+     *
+     * Service 在 Base 初始化时自动获得数据库、鉴权器、env 等基础设施。
+     */
+    use(svc: Service | BasePlugin): this;
+    /** 获取指定 ID 的 Service */
+    getService(id: string): Service | undefined;
+    /** 获取所有已注册的 Service */
+    getServices(): Service[];
+    getAuthenticator(): Promise<Authenticator>;
+    /**
+     * 获取指定名称的数据库表 API。
+     *
+     * @param name - 表名（格式为 "service_id.table_name" 或内置表名）
+     */
+    table<TRow extends Record<string, unknown> = Record<string, unknown>>(name: string): Promise<BaseTableApi<TRow>>;
+    /**
+     * 获取 Hono 路由实例（需先完成初始化）。
+     *
+     * 路由可以直接挂载到任何支持 fetch 的 HTTP 服务器：
+     * ```ts
+     * // Node.js
+     * serve({ fetch: base.router().fetch, port: 3000 });
+     *
+     * // Cloudflare Workers
+     * export default { fetch: base.router().fetch };
+     * ```
+     */
+    router(): Hono;
+    /**
+     * 直接处理一个 Request（用于 Serverless 场景）。
+     */
+    handleRequest(request: Request): Promise<Response>;
+    /**
+     * 健康检查。
+     */
+    health(): Promise<BaseHealthStatus>;
+    private initialize;
+    private collectServiceSchemas;
+    private buildHono;
+    private ensureReady;
+    private requireReadySync;
+    private requireReady;
+}
+export { Base as VisibleBase };
+//# sourceMappingURL=base.d.ts.map