@chatu-ai/app-sdk 0.8.7 → 0.9.1

package/README.md

@@ -1,6 +1,6 @@
 # @chatu-ai/app-sdk
 
-Data + AI SDK for apps generated by **ChatU Builder**. One API, driver picked from environment variables — works in the Builder preview, on your own server, or with no config at all.
+Data, auth and AI SDK for apps generated by **ChatU Builder**. One API, driver picked from environment variables — works in the Builder preview, on your own server, or with no config at all.
 
 ```ts
 import { kv, storage } from '@chatu-ai/app-sdk'   // server-side only (Route Handlers / Server Components / Server Actions)
@@ -22,6 +22,31 @@ const src = await storage.url('avatars/u1.png', { expiresIn: 3600 })         //
 | `CHATU_DATA_DRIVER=edgeone` (+ optional `CHATU_EDGEONE_KV_STORE` / `CHATU_EDGEONE_STORAGE_STORE`, external access: `EDGEONE_BLOB_PROJECT_ID` + `EDGEONE_BLOB_TOKEN`) | **edgeone** — Tencent EdgeOne Pages Blob for both `kv` (JSON envelope, TTL emulated) and `storage` (presigned PUT via `createUploadUrl`; `storage.url()` returns the in-app proxy path `/_chatu/blob/<key>` served by the template route) | `npm i @edgeone/pages-blob` (preinstalled in the Builder template); credential-free inside Pages Functions. `ai` keeps using `CHATU_DATA_URL` + `CHATU_APP_KEY` |
 | none | **memory** — in-process, lost on restart | local dev / fallback |
 
+## Auth (app users)
+
+`auth` gives the generated app **its own end users** (separate from ChatU platform accounts), scoped per app + environment (`dev`/`prod`). Email code or email + password; sessions are opaque tokens (stored server-side as SHA-256, sliding 30-day expiry). Requires the **platform** driver.
+
+```ts
+import { auth } from '@chatu-ai/app-sdk'
+
+const { devCode } = await auth.sendCode('a@b.com')            // devCode only in dev when no mail channel is configured
+const { token, user } = await auth.verifyCode('a@b.com', code) // first login signs the user up
+const me = await auth.getSession(token)                        // null when expired / disabled
+await auth.signOut(token)
+
+await auth.register('a@b.com', 'secret1')                      // password route (>= 6 chars)
+await auth.login('a@b.com', 'secret1')
+
+const { users, total } = await auth.users.list({ keyword: 'a@' })
+await auth.users.update(id, { disabled: true })                // also revokes that user's sessions
+```
+
+In the Next.js template, `@/lib/platform` wraps this in HttpOnly-cookie helpers: `currentUser()`, `requireUser()`, `signInWithCode()`, `endSession()`.
+
+Limits: 10k users per app/env, 200 codes per day, code valid 10 min / 5 tries, 60s per-email resend window.
+
+Billing: every auth call is metered as `auth_ops` (100 calls = 1 point by default) and each **actually sent** verification email as `auth_emails` (1 email = 1 point). Since `getSession()` runs on every request, the platform driver keeps a 30-second in-process session cache — tune it with `CHATU_AUTH_SESSION_CACHE` (seconds, `0` disables) or `configure({ authSessionCacheSeconds })`. The cache is dropped on `signOut()` and on any `users.update()` / `users.delete()`, so disabling a user takes effect within that window.
+
 ## AI (LLM relay)
 
 `ai` calls the platform's OpenAI-compatible endpoint (`{origin}/v1/chat/completions`) with the same app key used by the Data API. **Server-side only** — call it from a Route Handler / Server Action and let the browser `fetch` your own API; never ship the key to the client. Usage is metered and **billed to the app owner's ChatU points**.
@@ -71,6 +96,6 @@ Never expose `CHATU_APP_KEY` to the browser. MIT.
 
 ## Agent skills
 
-The package ships `skills/chatu-{kv,db,storage,ai}/SKILL.md` — task-focused manuals for coding agents
+The package ships `skills/chatu-{kv,db,storage,ai,auth}/SKILL.md` — task-focused manuals for coding agents
 (standard rules, boilerplate, boundaries, common failure modes). The ChatU Builder sandbox copies them
 into the workspace `.claude/skills/` so Claude Code loads them on demand; they are versioned with the SDK.

package/dist/auth.d.ts

@@ -0,0 +1,64 @@
+/** 应用自己的终端用户（与 ChatU 平台账号无关） */
+export interface AppUser {
+    id: string;
+    email: string;
+    name: string | null;
+    avatar: string | null;
+    createdAt: number;
+    lastLoginAt: number;
+    disabled: boolean;
+    meta: Record<string, unknown>;
+}
+export interface SignInResult {
+    token: string;
+    user: AppUser;
+    created: boolean;
+}
+export interface SendCodeResult {
+    sent: boolean; /** 仅预览环境且平台未配置邮件通道时返回，便于调试 */
+    devCode?: string | null;
+}
+export interface UserListResult {
+    users: AppUser[];
+    total: number;
+    nextSkip: number | null;
+}
+export interface UserPatch {
+    name?: string | null;
+    avatar?: string | null;
+    disabled?: boolean;
+    meta?: Record<string, unknown>;
+    password?: string;
+}
+export interface AuthClient {
+    /** 发送邮箱登录验证码 */
+    sendCode(email: string): Promise<SendCodeResult>;
+    /** 校验验证码；邮箱首次登录自动注册 */
+    verifyCode(email: string, code: string, opts?: {
+        name?: string;
+    }): Promise<SignInResult>;
+    /** 邮箱 + 密码注册 */
+    register(email: string, password: string, opts?: {
+        name?: string;
+    }): Promise<SignInResult>;
+    /** 邮箱 + 密码登录 */
+    login(email: string, password: string): Promise<SignInResult>;
+    /** 用会话 token 换当前用户；无效/过期/被禁用返回 null */
+    getSession(token: string | null | undefined): Promise<AppUser | null>;
+    /** 退出登录（吊销该 token） */
+    signOut(token: string | null | undefined): Promise<boolean>;
+    users: {
+        list(opts?: {
+            skip?: number;
+            limit?: number;
+            keyword?: string;
+        }): Promise<UserListResult>;
+        get(id: string): Promise<AppUser | null>;
+        update(id: string, patch: UserPatch): Promise<AppUser>;
+        delete(id: string): Promise<boolean>;
+    };
+}
+/** 按当前配置取 auth 客户端（惰性、缓存；configure() 后自动重建） */
+export declare function getAuth(): AuthClient;
+/** 便捷单例：`import { auth } from '@chatu-ai/app-sdk'` */
+export declare const auth: AuthClient;

package/dist/auth.js

@@ -0,0 +1,261 @@
+import { configVersion, resolveConfig } from './config.js';
+import { AppSdkError } from './errors.js';
+// ---------- platform driver ----------
+function platformAuth(cfg) {
+    const headers = { 'x-api-key': cfg.apiKey, 'x-chatu-env': cfg.env, 'content-type': 'application/json' };
+    /**
+     * 会话缓存：getSession() 会被每个请求调用，而每次调用都计费（auth_ops）。
+     * 缓存命中期内不再回源；停用/删除用户或退出登录时清掉，最长滞后 cfg.authSessionCacheSeconds。
+     */
+    const sessionCache = new Map();
+    const cacheTtl = cfg.authSessionCacheSeconds * 1000;
+    const dropCache = () => sessionCache.clear();
+    async function call(method, path, body, token) {
+        const res = await cfg.fetchImpl(`${cfg.baseUrl}/auth${path}`, {
+            method,
+            headers: token ? { ...headers, 'x-app-session': token } : headers,
+            body: body === undefined ? undefined : JSON.stringify(body),
+        });
+        let json = null;
+        try {
+            json = await res.json();
+        }
+        catch { /* ignore */ }
+        if (!res.ok || json?.ok === false) {
+            throw new AppSdkError(json?.error ?? `HTTP_${res.status}`, json?.message ?? `auth ${method} ${path} failed (${res.status})`, res.status);
+        }
+        return json;
+    }
+    return {
+        async sendCode(email) {
+            const r = await call('POST', '/code/send', { email });
+            return { sent: r.sent, devCode: r.devCode ?? null };
+        },
+        async verifyCode(email, code, opts) {
+            const r = await call('POST', '/code/verify', { email, code, name: opts?.name });
+            return { token: r.token, user: r.user, created: r.created };
+        },
+        async register(email, password, opts) {
+            const r = await call('POST', '/password/register', { email, password, name: opts?.name });
+            return { token: r.token, user: r.user, created: r.created };
+        },
+        async login(email, password) {
+            const r = await call('POST', '/password/login', { email, password });
+            return { token: r.token, user: r.user, created: false };
+        },
+        async getSession(token) {
+            if (!token)
+                return null;
+            if (cacheTtl > 0) {
+                const hit = sessionCache.get(token);
+                if (hit && hit.expiresAt > Date.now())
+                    return hit.user;
+            }
+            const r = await call('GET', '/session', undefined, token);
+            const user = r.user ?? null;
+            if (cacheTtl > 0) {
+                // 只缓存有限条目，避免伪造 token 打满内存
+                if (sessionCache.size > 1000)
+                    dropCache();
+                sessionCache.set(token, { user, expiresAt: Date.now() + cacheTtl });
+            }
+            return user;
+        },
+        async signOut(token) {
+            if (!token)
+                return false;
+            sessionCache.delete(token);
+            const r = await call('POST', '/logout', {}, token);
+            return r.removed;
+        },
+        users: {
+            async list(opts) {
+                const q = new URLSearchParams({ skip: String(opts?.skip ?? 0), limit: String(opts?.limit ?? 50) });
+                if (opts?.keyword)
+                    q.set('keyword', opts.keyword);
+                const r = await call('GET', `/users?${q.toString()}`);
+                return { users: r.users, total: r.total, nextSkip: r.nextSkip ?? null };
+            },
+            async get(id) {
+                try {
+                    const r = await call('GET', `/users/${encodeURIComponent(id)}`);
+                    return r.user;
+                }
+                catch (err) {
+                    if (err instanceof AppSdkError && err.code === 'USER_NOT_FOUND')
+                        return null;
+                    throw err;
+                }
+            },
+            async update(id, patch) {
+                const r = await call('PATCH', `/users/${encodeURIComponent(id)}`, patch);
+                dropCache(); // 可能刚刚停用了某个用户，缓存里的旧结果必须作废
+                return r.user;
+            },
+            async delete(id) {
+                const r = await call('DELETE', `/users/${encodeURIComponent(id)}`);
+                dropCache();
+                return r.removed;
+            },
+        },
+    };
+}
+// ---------- memory driver（本机开发 / 测试；进程退出即丢失） ----------
+function memoryAuth() {
+    const users = new Map();
+    /** 注册序号：同一毫秒创建的用户也要有稳定的先后顺序 */
+    const seq = new Map();
+    let nextSeq = 0;
+    const byEmail = new Map();
+    const sessions = new Map();
+    const codes = new Map();
+    const norm = (email) => email.trim().toLowerCase();
+    const strip = (u) => { const { pwd: _pwd, ...rest } = u; return rest; };
+    const issue = (id) => { const token = `mem_${Math.random().toString(36).slice(2)}${Date.now().toString(36)}`; sessions.set(token, id); return token; };
+    const create = (email, name, pwd) => {
+        const now = Date.now();
+        const user = { id: `u${now.toString(36)}${Math.random().toString(36).slice(2, 8)}`, email, name: name ?? email.split('@')[0], avatar: null, createdAt: now, lastLoginAt: now, disabled: false, meta: {}, pwd };
+        users.set(user.id, user);
+        seq.set(user.id, nextSeq++);
+        byEmail.set(email, user.id);
+        return user;
+    };
+    return {
+        async sendCode(email) { const code = String(Math.floor(100000 + Math.random() * 900000)); codes.set(norm(email), code); return { sent: true, devCode: code }; },
+        async verifyCode(email, code, opts) {
+            const key = norm(email);
+            if (codes.get(key) !== code.trim())
+                throw new AppSdkError('CODE_INVALID', '验证码不正确');
+            codes.delete(key);
+            const existingId = byEmail.get(key);
+            const user = existingId ? users.get(existingId) : create(key, opts?.name);
+            user.lastLoginAt = Date.now();
+            return { token: issue(user.id), user: strip(user), created: !existingId };
+        },
+        async register(email, password, opts) {
+            const key = norm(email);
+            if (byEmail.has(key))
+                throw new AppSdkError('EMAIL_TAKEN', '该邮箱已注册');
+            if (password.length < 6)
+                throw new AppSdkError('WEAK_PASSWORD', '密码至少 6 位');
+            const user = create(key, opts?.name, password);
+            return { token: issue(user.id), user: strip(user), created: true };
+        },
+        async login(email, password) {
+            const id = byEmail.get(norm(email));
+            const user = id ? users.get(id) : undefined;
+            if (!user || user.pwd !== password)
+                throw new AppSdkError('INVALID_CREDENTIALS', '邮箱或密码不正确');
+            if (user.disabled)
+                throw new AppSdkError('USER_DISABLED', '该账号已被停用');
+            user.lastLoginAt = Date.now();
+            return { token: issue(user.id), user: strip(user), created: false };
+        },
+        async getSession(token) {
+            if (!token)
+                return null;
+            const id = sessions.get(token);
+            const user = id ? users.get(id) : undefined;
+            return !user || user.disabled ? null : strip(user);
+        },
+        async signOut(token) { return token ? sessions.delete(token) : false; },
+        users: {
+            async list(opts) {
+                const kw = opts?.keyword?.trim().toLowerCase();
+                const all = [...users.values()]
+                    .filter(u => !kw || u.email.includes(kw) || (u.name ?? '').toLowerCase().includes(kw))
+                    .sort((a, b) => b.createdAt - a.createdAt || (seq.get(b.id) ?? 0) - (seq.get(a.id) ?? 0));
+                const skip = opts?.skip ?? 0;
+                const limit = opts?.limit ?? 50;
+                const page = all.slice(skip, skip + limit);
+                return { users: page.map(strip), total: all.length, nextSkip: skip + page.length < all.length ? skip + page.length : null };
+            },
+            async get(id) { const u = users.get(id); return u ? strip(u) : null; },
+            async update(id, patch) {
+                const u = users.get(id);
+                if (!u)
+                    throw new AppSdkError('USER_NOT_FOUND', '用户不存在');
+                if (patch.name !== undefined)
+                    u.name = patch.name;
+                if (patch.avatar !== undefined)
+                    u.avatar = patch.avatar;
+                if (patch.meta !== undefined)
+                    u.meta = patch.meta;
+                if (patch.password !== undefined)
+                    u.pwd = patch.password;
+                if (patch.disabled !== undefined) {
+                    u.disabled = patch.disabled;
+                    if (patch.disabled)
+                        for (const [t, uid] of [...sessions])
+                            if (uid === id)
+                                sessions.delete(t);
+                }
+                return strip(u);
+            },
+            async delete(id) {
+                const u = users.get(id);
+                if (!u)
+                    return false;
+                for (const [t, uid] of [...sessions])
+                    if (uid === id)
+                        sessions.delete(t);
+                byEmail.delete(u.email);
+                seq.delete(id);
+                return users.delete(id);
+            },
+        },
+    };
+}
+/** byo / edgeone 等驱动没有用户存储：每个方法都以明确错误 reject，而不是在取客户端时同步抛出 */
+function unsupportedAuth(kind) {
+    const fail = () => {
+        throw new AppSdkError('AUTH_UNSUPPORTED', `当前数据驱动（${kind}）不支持应用用户体系；auth 需要平台数据服务（配置 CHATU_APP_KEY 使用 platform 驱动）`);
+    };
+    return {
+        async sendCode() { return fail(); },
+        async verifyCode() { return fail(); },
+        async register() { return fail(); },
+        async login() { return fail(); },
+        async getSession() { return fail(); },
+        async signOut() { return fail(); },
+        users: {
+            async list() { return fail(); },
+            async get() { return fail(); },
+            async update() { return fail(); },
+            async delete() { return fail(); },
+        },
+    };
+}
+let cached = null;
+/** 按当前配置取 auth 客户端（惰性、缓存；configure() 后自动重建） */
+export function getAuth() {
+    const cfg = resolveConfig();
+    // 两种驱动都带进程内状态（platform 的会话缓存 / memory 的用户表）：并入 configure() 次数，重新配置即重建
+    const key = cfg.kind === 'platform'
+        ? `platform|${cfg.baseUrl}|${cfg.env}|${cfg.apiKey.slice(-4)}|${cfg.authSessionCacheSeconds}|${configVersion()}`
+        : `${cfg.kind}|${configVersion()}`;
+    if (!cached || cached.key !== key) {
+        cached = {
+            key,
+            client: cfg.kind === 'platform' ? platformAuth(cfg)
+                : cfg.kind === 'memory' ? memoryAuth()
+                    : unsupportedAuth(cfg.kind),
+        };
+    }
+    return cached.client;
+}
+/** 便捷单例：`import { auth } from '@chatu-ai/app-sdk'` */
+export const auth = {
+    sendCode: (email) => getAuth().sendCode(email),
+    verifyCode: (email, code, opts) => getAuth().verifyCode(email, code, opts),
+    register: (email, password, opts) => getAuth().register(email, password, opts),
+    login: (email, password) => getAuth().login(email, password),
+    getSession: (token) => getAuth().getSession(token),
+    signOut: (token) => getAuth().signOut(token),
+    users: {
+        list: (opts) => getAuth().users.list(opts),
+        get: (id) => getAuth().users.get(id),
+        update: (id, patch) => getAuth().users.update(id, patch),
+        delete: (id) => getAuth().users.delete(id),
+    },
+};

package/dist/auth.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/auth.test.js

@@ -0,0 +1,131 @@
+import { beforeEach, describe as d, expect, it } from 'vitest';
+import { auth, configure, AppSdkError } from './index';
+d('auth memory driver', () => {
+    beforeEach(() => configure({ driver: 'memory' }));
+    it('signs up on first code verify and keeps the same user on second login', async () => {
+        const { devCode } = await auth.sendCode('Alice@Example.com ');
+        expect(devCode).toMatch(/^\d{6}$/);
+        const first = await auth.verifyCode('alice@example.com', devCode, { name: '爱丽丝' });
+        expect(first.created).toBe(true);
+        expect(first.user.email).toBe('alice@example.com');
+        expect(first.user.name).toBe('爱丽丝');
+        expect(await auth.getSession(first.token)).toMatchObject({ id: first.user.id });
+        const second = await auth.verifyCode('alice@example.com', (await auth.sendCode('alice@example.com')).devCode);
+        expect(second.created).toBe(false);
+        expect(second.user.id).toBe(first.user.id);
+    });
+    it('rejects a wrong code and consumes a used one', async () => {
+        const { devCode } = await auth.sendCode('bob@example.com');
+        await expect(auth.verifyCode('bob@example.com', '000000')).rejects.toThrow(AppSdkError);
+        await auth.verifyCode('bob@example.com', devCode);
+        await expect(auth.verifyCode('bob@example.com', devCode)).rejects.toThrow(/验证码/);
+    });
+    it('password register / login / duplicate email', async () => {
+        const reg = await auth.register('carol@example.com', 'secret1', { name: 'Carol' });
+        expect(reg.created).toBe(true);
+        await expect(auth.register('carol@example.com', 'secret1')).rejects.toThrow(/已注册/);
+        await expect(auth.register('dave@example.com', 'x')).rejects.toThrow(/6 位/);
+        await expect(auth.login('carol@example.com', 'wrong')).rejects.toThrow(/不正确/);
+        const login = await auth.login('carol@example.com', 'secret1');
+        expect(login.user.id).toBe(reg.user.id);
+    });
+    it('never exposes the password and revokes sessions when disabled', async () => {
+        const { token, user } = await auth.register('erin@example.com', 'secret1');
+        expect(user.pwd).toBeUndefined();
+        await auth.users.update(user.id, { disabled: true });
+        expect(await auth.getSession(token)).toBeNull();
+        await expect(auth.login('erin@example.com', 'secret1')).rejects.toThrow(/停用/);
+    });
+    it('lists, searches, updates and deletes users', async () => {
+        const a = await auth.register('frank@example.com', 'secret1', { name: 'Frank' });
+        await auth.register('grace@example.com', 'secret1', { name: 'Grace' });
+        const list = await auth.users.list();
+        expect(list.total).toBe(2);
+        expect(list.users[0].email).toBe('grace@example.com'); // 最新注册在前
+        expect((await auth.users.list({ keyword: 'frank' })).total).toBe(1);
+        expect((await auth.users.list({ limit: 1 })).nextSkip).toBe(1);
+        const updated = await auth.users.update(a.user.id, { name: '弗兰克', meta: { role: 'admin' } });
+        expect(updated.name).toBe('弗兰克');
+        expect(updated.meta).toEqual({ role: 'admin' });
+        expect(await auth.users.get(a.user.id)).toMatchObject({ name: '弗兰克' });
+        expect(await auth.users.delete(a.user.id)).toBe(true);
+        expect(await auth.users.get(a.user.id)).toBeNull();
+        expect(await auth.getSession(a.token)).toBeNull();
+    });
+    it('getSession tolerates missing tokens', async () => {
+        expect(await auth.getSession(null)).toBeNull();
+        expect(await auth.getSession(undefined)).toBeNull();
+        expect(await auth.signOut(null)).toBe(false);
+    });
+});
+d('auth platform driver', () => {
+    it('sends app key / env / session headers and unwraps responses', async () => {
+        const calls = [];
+        const user = { id: 'u1', email: 'a@b.com', name: 'A', avatar: null, createdAt: 1, lastLoginAt: 2, disabled: false, meta: {} };
+        const fetchImpl = (async (url, init) => {
+            calls.push({ url, init });
+            if (url.endsWith('/auth/code/send'))
+                return new Response(JSON.stringify({ ok: true, sent: true }), { status: 200 });
+            if (url.endsWith('/auth/code/verify'))
+                return new Response(JSON.stringify({ ok: true, token: 't1', user, created: true }), { status: 200 });
+            if (url.includes('/auth/session'))
+                return new Response(JSON.stringify({ ok: true, user }), { status: 200 });
+            if (url.includes('/auth/users?'))
+                return new Response(JSON.stringify({ ok: true, users: [user], total: 1, nextSkip: null }), { status: 200 });
+            if (url.endsWith('/auth/users/u404'))
+                return new Response(JSON.stringify({ ok: false, error: 'USER_NOT_FOUND' }), { status: 404 });
+            return new Response(JSON.stringify({ ok: false, error: 'CODE_RATE_LIMITED', message: '发送过于频繁' }), { status: 429 });
+        });
+        configure({ driver: 'platform', baseUrl: 'https://api.test/data/v1/', apiKey: 'sk-conv-abc', env: 'prod', fetchImpl });
+        expect(await auth.sendCode('a@b.com')).toEqual({ sent: true, devCode: null });
+        const signed = await auth.verifyCode('a@b.com', '123456');
+        expect(signed.token).toBe('t1');
+        expect(await auth.getSession('t1')).toMatchObject({ id: 'u1' });
+        expect((await auth.users.list({ keyword: 'a' })).total).toBe(1);
+        expect(await auth.users.get('u404')).toBeNull();
+        const headers = calls[0].init.headers;
+        expect(headers['x-api-key']).toBe('sk-conv-abc');
+        expect(headers['x-chatu-env']).toBe('prod');
+        const sessionCall = calls.find(c => c.url.includes('/auth/session'));
+        expect(sessionCall.init.headers['x-app-session']).toBe('t1');
+        await expect(auth.login('a@b.com', 'secret1')).rejects.toMatchObject({ code: 'CODE_RATE_LIMITED', status: 429 });
+    });
+    it('caches getSession to avoid paying for one auth call per request', async () => {
+        let sessionCalls = 0;
+        const user = { id: 'u1', email: 'a@b.com', name: 'A', avatar: null, createdAt: 1, lastLoginAt: 2, disabled: false, meta: {} };
+        const fetchImpl = (async (url) => {
+            if (url.includes('/auth/session'))
+                sessionCalls += 1;
+            if (url.includes('/auth/users/'))
+                return new Response(JSON.stringify({ ok: true, user }), { status: 200 });
+            return new Response(JSON.stringify({ ok: true, user, removed: true }), { status: 200 });
+        });
+        configure({ driver: 'platform', baseUrl: 'https://api.test/data/v1', apiKey: 'sk-conv-abc', env: 'prod', fetchImpl });
+        await auth.getSession('t1');
+        await auth.getSession('t1');
+        await auth.getSession('t1');
+        expect(sessionCalls).toBe(1);
+        await auth.getSession('t2');
+        expect(sessionCalls).toBe(2);
+        // 停用某个用户后缓存必须作废，否则被停用的人还能继续访问
+        await auth.users.update('u1', { disabled: true });
+        await auth.getSession('t1');
+        expect(sessionCalls).toBe(3);
+        // 退出登录只清掉自己那条
+        await auth.signOut('t1');
+        await auth.getSession('t1');
+        expect(sessionCalls).toBe(4);
+        await auth.getSession('t2');
+        expect(sessionCalls).toBe(5);
+        // 显式关闭缓存：每次都回源
+        configure({ driver: 'platform', baseUrl: 'https://api.test/data/v1', apiKey: 'sk-conv-abc', env: 'prod', fetchImpl, authSessionCacheSeconds: 0 });
+        sessionCalls = 0;
+        await auth.getSession('t1');
+        await auth.getSession('t1');
+        expect(sessionCalls).toBe(2);
+    });
+    it('refuses drivers without a platform data service', async () => {
+        configure({ driver: 'edgeone' });
+        await expect(auth.getSession('t')).rejects.toThrow(/不支持应用用户体系/);
+    });
+});

package/dist/config.d.ts

@@ -15,6 +15,12 @@ export interface PlatformConfig {
     aiBaseUrl: string;
     /** 默认模型：CHATU_AI_MODEL → PRIMARY_MODEL（沙箱注入的平台默认模型）；都没有则不传，由服务端决定 */
     aiModel?: string;
+    /**
+     * auth.getSession() 的进程内缓存秒数（默认 30，0 关闭）。
+     * 会话校验每个请求都会发生，缓存能显著减少计费的 auth 调用；代价是"停用用户"最多延迟这么久生效。
+     * 覆盖：configure({ authSessionCacheSeconds }) 或环境变量 CHATU_AUTH_SESSION_CACHE。
+     */
+    authSessionCacheSeconds: number;
 }
 export interface MemoryConfig {
     kind: 'memory';
@@ -59,9 +65,13 @@ export interface ConfigureOptions {
     aiBaseUrl?: string;
     /** LLM 默认模型 */
     model?: string;
+    /** auth.getSession() 进程内缓存秒数（默认 30，0 关闭） */
+    authSessionCacheSeconds?: number;
 }
 /** 显式配置（测试或非 env 场景）；不调用则完全由环境变量决定 */
 export declare function configure(options: ConfigureOptions): void;
+/** configure() 调用次数：带内存状态的模块（如 auth 的 memory 驱动）用它判断是否该重建客户端 */
+export declare function configVersion(): number;
 export declare function resolveConfig(): ResolvedConfig;
 /** `https://api.chatuapi.com/data/v1` → `https://api.chatuapi.com/v1`（Data API 与 LLM 中继同源） */
 export declare function deriveAiBaseUrl(dataBaseUrl: string): string;

package/dist/config.js

@@ -1,7 +1,13 @@
 let override = {};
+let version = 0;
 /** 显式配置（测试或非 env 场景）；不调用则完全由环境变量决定 */
 export function configure(options) {
     override = { ...options };
+    version += 1;
+}
+/** configure() 调用次数：带内存状态的模块（如 auth 的 memory 驱动）用它判断是否该重建客户端 */
+export function configVersion() {
+    return version;
 }
 export function resolveConfig() {
     // 不依赖 @types/node：通过 globalThis 读取 process.env
@@ -57,10 +63,20 @@ export function resolveConfig() {
             fetchImpl: override.fetchImpl ?? fetch,
             aiBaseUrl: (override.aiBaseUrl ?? env.CHATU_AI_URL ?? deriveAiBaseUrl(normalizedBase)).replace(/\/+$/, ''),
             aiModel: override.model ?? env.CHATU_AI_MODEL ?? env.PRIMARY_MODEL,
+            authSessionCacheSeconds: normalizeCacheSeconds(override.authSessionCacheSeconds ?? env.CHATU_AUTH_SESSION_CACHE),
         };
     }
     return { kind: 'memory' };
 }
+/** 会话缓存秒数：非法值回落到默认 30，上限 300（避免停用用户长时间仍可用） */
+function normalizeCacheSeconds(value) {
+    if (value === undefined || value === '')
+        return 30;
+    const n = typeof value === 'number' ? value : Number(value);
+    if (!Number.isFinite(n) || n < 0)
+        return 30;
+    return Math.min(Math.floor(n), 300);
+}
 /** `https://api.chatuapi.com/data/v1` → `https://api.chatuapi.com/v1`（Data API 与 LLM 中继同源） */
 export function deriveAiBaseUrl(dataBaseUrl) {
     const trimmed = dataBaseUrl.replace(/\/+$/, '');
@@ -106,6 +122,7 @@ export function resolveAiConfig() {
         fetchImpl: override.fetchImpl ?? fetch,
         aiBaseUrl: (override.aiBaseUrl ?? env.CHATU_AI_URL ?? deriveAiBaseUrl(normalizedBase)).replace(/\/+$/, ''),
         aiModel: override.model ?? env.CHATU_AI_MODEL ?? env.PRIMARY_MODEL,
+        authSessionCacheSeconds: normalizeCacheSeconds(override.authSessionCacheSeconds ?? env.CHATU_AUTH_SESSION_CACHE),
     };
 }
 /** 动态加载可选依赖（ioredis / @aws-sdk/* / @edgeone/pages-blob），不参与打包静态分析；缺失时给出可操作的错误 */

package/dist/index.d.ts

@@ -7,6 +7,8 @@ export { db, getDb, matchesFilter, applySort, queryDocs, newDocId } from './db.j
 export type { DbClient, Collection, Doc, Filter, FilterOp, Sort, FindOptions, FindResult, UpdateInput } from './db.js';
 export { storage, getStorage } from './storage.js';
 export type { StorageClient, StorageObject, StorageListResult, UploadUrlResult } from './storage.js';
+export { auth, getAuth } from './auth.js';
+export type { AuthClient, AppUser, SignInResult, SendCodeResult, UserListResult, UserPatch } from './auth.js';
 export { ai, getAi } from './ai.js';
 export type { AiClient, AiMessage, AiChatOptions, AiChatResult, AiUsage } from './ai.js';
 export { encodeKvKey, decodeKvKey } from './edgeone.js';

package/dist/index.js

@@ -3,5 +3,6 @@ export { configure, describe, registerOptionalModule } from './config.js';
 export { AppSdkError } from './errors.js';
 export { db, getDb, matchesFilter, applySort, queryDocs, newDocId } from './db.js';
 export { storage, getStorage } from './storage.js';
+export { auth, getAuth } from './auth.js';
 export { ai, getAi } from './ai.js';
 export { encodeKvKey, decodeKvKey } from './edgeone.js';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@chatu-ai/app-sdk",
-  "version": "0.8.7",
-  "description": "Runtime SDK for apps generated by ChatU Builder: kv, storage and ai (OpenAI-compatible LLM relay) with platform / byo / memory drivers selected by environment variables",
+  "version": "0.9.1",
+  "description": "Runtime SDK for apps generated by ChatU Builder: kv, db, storage, auth (app users) and ai (OpenAI-compatible LLM relay) with platform / byo / edgeone / memory drivers selected by environment variables",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
@@ -31,6 +31,7 @@
     "kv",
     "storage",
     "app-sdk",
+    "auth",
     "ai",
     "llm",
     "nextjs"

package/skills/chatu-auth/SKILL.md

@@ -0,0 +1,191 @@
+---
+name: chatu-auth
+description: 应用自己的登录用户体系（@chatu-ai/app-sdk 的 auth）。当应用需要"登录后才能用""每个人只看到自己的数据""会员/后台/多人协作"时使用；提供邮箱验证码登录、邮箱密码登录、会话 Cookie、用户管理。禁止引入 next-auth/clerk/supabase-auth/firebase-auth/bcrypt/jose 等第三方登录库。
+---
+
+# 应用用户体系（auth）
+
+给**生成出来的这个应用**一套自己的终端用户：注册、登录、会话、退出、用户管理。**用量计入应用所有者的 ChatU 点数**（每次调用记 `auth_ops`，实际外发的验证码邮件另按封计价，见下方「计费与省钱写法」）。与 ChatU 平台账号完全无关，数据按"应用 + 环境（预览/线上）"隔离——预览环境注册的测试账号不会出现在线上。
+
+## 什么时候需要它
+
+| 需求 | 是否需要 auth |
+| --- | --- |
+| "我的待办/我的收藏/我的订单"——每人只看自己的数据 | ✅ |
+| 会员中心、后台管理页、只有登录用户能发帖/评论 | ✅ |
+| 多人协作（谁创建的、谁修改的） | ✅ |
+| 纯展示页、工具页、所有人看到同样内容 | ❌ 不要加登录，直接做 |
+
+## API
+
+```ts
+import {
+  currentUser, requireUser, sendLoginCode, signInWithCode,
+  signUpWithPassword, signInWithPassword, endSession, auth,
+} from '@/lib/platform';
+
+const user = await currentUser();          // AppUser | null，Server Component 里可直接用
+const me   = await requireUser();          // 未登录自动 redirect('/login')
+
+// 邮箱验证码（推荐：不用记密码）
+const { devCode } = await sendLoginCode(email);   // 预览环境未配邮件时返回 devCode，方便自测
+const user = await signInWithCode(email, code, { name });  // 首次登录自动注册
+
+// 邮箱 + 密码（可选路线）
+await signUpWithPassword(email, password, { name });       // 密码 ≥ 6 位
+await signInWithPassword(email, password);
+
+await endSession();                        // 退出登录
+
+// 用户管理（后台页用）
+const { users, total, nextSkip } = await auth.users.list({ skip: 0, limit: 50, keyword: '张' });
+await auth.users.update(id, { name: '新名字', disabled: true, meta: { role: 'admin' } });
+await auth.users.delete(id);
+```
+
+`AppUser`：`{ id, email, name, avatar, createdAt, lastLoginAt, disabled, meta }`。密码永远不会回传。
+
+**登录态存在 HttpOnly Cookie 里**，`signIn*` / `endSession` 会写/删 Cookie —— 因此**只能在 Server Action 或 Route Handler 中调用**（Server Component 只能 `currentUser()` 读）。
+
+## 标准登录页（验证码，两步）
+
+```tsx
+// src/app/login/page.tsx
+import { redirect } from 'next/navigation';
+import { sendLoginCode, signInWithCode, currentUser } from '@/lib/platform';
+
+export default async function LoginPage({ searchParams }: { searchParams: Promise<{ email?: string; error?: string }> }) {
+  if (await currentUser()) redirect('/');
+  const { email, error } = await searchParams;
+
+  async function send(formData: FormData) {
+    'use server';
+    const value = String(formData.get('email') ?? '').trim();
+    if (!value) return;
+    await sendLoginCode(value);
+    redirect(`/login?email=${encodeURIComponent(value)}`);
+  }
+
+  async function verify(formData: FormData) {
+    'use server';
+    try {
+      await signInWithCode(String(formData.get('email')), String(formData.get('code')));
+    } catch {
+      redirect(`/login?email=${encodeURIComponent(String(formData.get('email')))}&error=1`);
+    }
+    redirect('/');
+  }
+
+  return (
+    <main className="mx-auto flex min-h-screen max-w-sm flex-col justify-center gap-4 p-6">
+      {!email ? (
+        <form action={send} className="space-y-3">
+          <input name="email" type="email" required placeholder="邮箱" className="w-full rounded-md border px-3 py-2" />
+          <button className="w-full rounded-md bg-primary px-3 py-2 text-primary-foreground">发送验证码</button>
+        </form>
+      ) : (
+        <form action={verify} className="space-y-3">
+          <input type="hidden" name="email" value={email} />
+          <p className="text-sm text-muted-foreground">验证码已发送至 {email}</p>
+          {error ? <p className="text-sm text-destructive">验证码不正确或已过期</p> : null}
+          <input name="code" inputMode="numeric" required placeholder="6 位验证码" className="w-full rounded-md border px-3 py-2" />
+          <button className="w-full rounded-md bg-primary px-3 py-2 text-primary-foreground">登录</button>
+        </form>
+      )}
+    </main>
+  );
+}
+```
+
+退出登录：
+
+```tsx
+import { endSession } from '@/lib/platform';
+import { redirect } from 'next/navigation';
+
+export function SignOutButton() {
+  async function out() {
+    'use server';
+    await endSession();
+    redirect('/login');
+  }
+  return <form action={out}><button className="text-sm underline">退出登录</button></form>;
+}
+```
+
+## 每个用户自己的数据
+
+约定：在 db 文档里存 `userId`，**每次查询都带上它**（见 `chatu-db`）。
+
+```ts
+// src/lib/todos.ts
+import { db, requireUser } from '@/lib/platform';
+
+interface Todo { userId: string; title: string; done: boolean }
+const todos = db.collection<Todo>('todos');
+
+export async function myTodos() {
+  const me = await requireUser();
+  return todos.find({ filter: { userId: me.id }, sort: { _createdAt: -1 }, limit: 100 });
+}
+
+export async function addTodo(title: string) {
+  const me = await requireUser();
+  return todos.insert({ userId: me.id, title, done: false });
+}
+
+export async function toggleTodo(id: string, done: boolean) {
+  const me = await requireUser();
+  const doc = await todos.get(id);
+  if (!doc || doc.userId !== me.id) throw new Error('无权操作');   // 越权检查不能省
+  return todos.update(id, { set: { done } });
+}
+```
+
+管理员：用 `meta.role === 'admin'` 判断（在平台「用户」面板或后台页给某个用户打上），不要硬编码邮箱白名单以外的复杂权限模型。
+
+## 计费与省钱写法
+
+| 计量项 | 何时累加 | 默认折算 |
+| --- | --- | --- |
+| `auth_ops` | 每次 auth 接口调用（发码、校验、登录、`currentUser()`、用户管理…） | 100 次 = 1 点 |
+| `auth_emails` | **真正发出**的验证码邮件（预览环境未配邮件返回 devCode 时不计） | 1 封 = 1 点 |
+
+`currentUser()` / `requireUser()` 每次请求都会打一次会话校验，是最容易放量的一项。SDK 已内置 **30 秒进程内会话缓存**（`CHATU_AUTH_SESSION_CACHE` 秒数可调，0 关闭），但代码写法仍决定实际调用量：
+
+```ts
+// ✅ 一个页面/一次 Server Action 只取一次，往下传
+export default async function Page() {
+  const me = await requireUser();
+  return <><Header user={me} /><TodoList user={me} /></>;   // 不要在每个子组件里再 currentUser()
+}
+
+// ❌ 循环里逐条校验
+for (const item of items) { const me = await currentUser(); /* … */ }
+
+// ✅ 公开页面不要强行登录：能匿名浏览的内容别加 requireUser()
+```
+
+发码按钮务必加 60 秒倒计时（服务端也有 60s 频控），既省邮件钱也避免 `CODE_RATE_LIMITED`。批量导入用户时用 `auth.users.list({ limit: 200 })` 一次多取，别逐个 `users.get()`。
+
+## 边界与禁忌
+
+- **禁止**引入 next-auth / auth.js / clerk / supabase-auth / firebase-auth / passport / bcrypt / jose / jsonwebtoken —— 平台已提供，装了也跑不通（沙箱与函数部署都没有对应后端）。
+- 不要自己生成 JWT、不要把用户信息写进普通 Cookie / localStorage，会话只用 `chatu_session`（HttpOnly）。
+- 不要在客户端组件里 import `@/lib/platform` 的 auth；通过 Server Action 或 Route Handler 拿 `currentUser()` 的结果传下去。
+- 需要登录的页面要么 `await requireUser()`，要么在 Server Action 里再校验一次——只在前端隐藏按钮不算保护。
+- 单应用单环境上限 1 万用户、每日验证码 200 封（超出报 `CODE_QUOTA_EXCEEDED`）；验证码 10 分钟有效、错 5 次作废、同一邮箱 60 秒才能再发一次。
+- 只有邮箱登录；没有短信、没有微信/GitHub 第三方登录。用户要"手机号登录"时，如实说明当前只支持邮箱。
+
+## 常见错误
+
+| 现象 | 原因 | 修法 |
+| --- | --- | --- |
+| `Cookies can only be modified in a Server Action or Route Handler` | 在 Server Component 里调用了 `signIn*` / `endSession` | 挪进 `'use server'` 的 action 或 `route.ts` |
+| 登录后刷新又变未登录 | 页面被静态预渲染 | 保留 layout 里的 `export const dynamic = "force-dynamic"` |
+| `EMAIL_NOT_CONFIGURED`（线上） | 平台未配置邮件通道 | 线上改用邮箱密码登录，或让用户联系平台开通 |
+| `CODE_RATE_LIMITED` | 同一邮箱 60 秒内重复发码 | 前端按钮加倒计时 |
+| `AUTH_UNSUPPORTED` | 应用被部署在没有平台数据服务的驱动上（如 edgeone blob） | 部署时选择带平台数据服务的目标 |
+| `READ_ONLY` / 无法注册新用户 | 应用所有者点数不足，数据已置只读 | 已登录用户仍可访问；充值后自动恢复 |
+| 停用了用户但他还能访问 | 会话缓存最长 30 秒 | 等待缓存过期，或把 `CHATU_AUTH_SESSION_CACHE` 设为 0 |
+| 别人能看到我的数据 | 查询没带 `userId`，或改删时没做归属校验 | 每个 find/update/delete 都带上 `userId` 判断 |