@user-center/next-better-auth 0.0.0-stage → 0.1.10

package/dist/next-better-auth/src/server.d.ts

@@ -0,0 +1,142 @@
+import "server-only";
+import { type BetterAuthOptions } from "better-auth";
+import type { OAuthProvider } from "better-auth/oauth2";
+import { type EnvironmentSelection } from "../../integration-contracts/src/environment.js";
+import { type ErrorCode, type PublicConfig } from "../../integration-contracts/src/public.js";
+export interface Identity {
+    issuer: string;
+    subject: string;
+    authUserId: string;
+    profile: {
+        name: string;
+        email: string;
+        emailVerified: boolean;
+    };
+}
+export type { SafeSession } from "../../integration-contracts/src/public.js";
+export type Principal<T> = {
+    status: "anonymous";
+} | {
+    status: "mapping-required";
+    identity: Identity;
+} | {
+    status: "authenticated";
+    identity: Identity;
+    user: T;
+};
+export type ResolutionContext = Readonly<{
+    requestId: string;
+    signal: AbortSignal;
+}>;
+export type Event = Readonly<{
+    code: ErrorCode | "OK";
+    phase: "ready" | "identity" | "business" | "login" | "callback" | "logout";
+    at: string;
+    requestId: string;
+    version: string;
+}>;
+export interface AuthOptions<T extends {
+    id: string;
+}> {
+    manifest: unknown;
+    database: NonNullable<BetterAuthOptions["database"]>;
+    clientSecret: string;
+    sessionSecret: string;
+    environment?: EnvironmentSelection;
+    authUserPolicy: "allow-new" | "existing-only";
+    sessionTtlSeconds?: number;
+    resolveBusinessUser: (identity: Identity, context: ResolutionContext) => Promise<{
+        status: "ready";
+        user: T;
+    } | {
+        status: "unmapped";
+    }>;
+    onEvent?: (event: Event) => unknown;
+}
+export declare function createUserCenterAuth<T extends {
+    id: string;
+}>(options: AuthOptions<T>): {
+    publicConfig: PublicConfig;
+    ready: () => Promise<void>;
+    getAuth: () => Promise<import("better-auth").Auth<{
+        baseURL: string;
+        basePath: string;
+        secret: string;
+        database: any;
+        trustedOrigins: string[];
+        emailAndPassword: {
+            enabled: false;
+        };
+        user: {
+            deleteUser: {
+                enabled: false;
+            };
+        };
+        session: {
+            expiresIn: number;
+            disableSessionRefresh: true;
+            cookieCache: {
+                enabled: false;
+            };
+        };
+        account: {
+            accountLinking: {
+                enabled: false;
+            };
+            encryptOAuthTokens: true;
+        };
+        advanced: {
+            cookiePrefix: string;
+            useSecureCookies: true;
+            crossSubDomainCookies: {
+                enabled: false;
+            };
+            defaultCookieAttributes: {
+                secure: true;
+                httpOnly: true;
+                sameSite: "lax";
+                path: string;
+            };
+        };
+        onAPIError: {
+            errorURL: string;
+        };
+        logger: {
+            disabled: true;
+        };
+        rateLimit: {
+            enabled: true;
+            storage: "memory";
+        };
+        plugins: [{
+            init: (ctx: import("better-auth").AuthContext) => Promise<{
+                context: {
+                    socialProviders: OAuthProvider<object, Partial<import("better-auth").ProviderOptions<object>>>[];
+                    genericOAuthPendingDiscovery: Map<string, {
+                        config: import("better-auth/plugins/generic-oauth").GenericOAuthConfig;
+                        attempt?: Promise<void> | undefined;
+                    }>;
+                };
+            }>;
+            hooks: {
+                before: {
+                    matcher: (context: import("better-auth").HookEndpointContext) => boolean;
+                    handler: import("better-auth").Middleware<import("better-auth").MiddlewareOptions, (inputContext: import("better-auth").MiddlewareInputContext<import("better-auth").MiddlewareOptions>) => Promise<void>>;
+                }[];
+            };
+            id: "generic-oauth";
+            version: string;
+            options: import("better-auth/plugins/generic-oauth").GenericOAuthOptions<string>;
+            $ERROR_CODES: {
+                INVALID_OAUTH_CONFIGURATION: import("better-auth").RawError<"INVALID_OAUTH_CONFIGURATION">;
+                TOKEN_URL_NOT_FOUND: import("better-auth").RawError<"TOKEN_URL_NOT_FOUND">;
+            };
+        }];
+    }>>;
+    getIdentity: (headers: Headers) => Promise<Identity | null>;
+    getPrincipal: (headers: Headers) => Promise<Principal<T>>;
+    handlers: {
+        GET: (request: Request) => Promise<Response>;
+        POST: (request: Request) => Promise<Response>;
+    };
+};

package/dist/next-better-auth/src/server.js

@@ -0,0 +1,298 @@
+import "server-only";
+import { randomUUID } from "node:crypto";
+import { betterAuth } from "better-auth";
+import { genericOAuth } from "better-auth/plugins/generic-oauth";
+import { createAuthMiddleware } from "better-auth/api";
+import { createRemoteJWKSet, customFetch } from "jose";
+import { describeIntegration } from "../../integration-contracts/src/config.js";
+import { validateEnvironmentSelection } from "../../integration-contracts/src/environment.js";
+import { IntegrationError, TOOL_VERSION, parseLoginRequest, validateReturnTo } from "../../integration-contracts/src/public.js";
+import { readPublicJson, validateDiscovery, validateJwks } from "../../integration-contracts/src/metadata.js";
+const safeHeaders = { "Cache-Control": "no-store", "Referrer-Policy": "no-referrer" };
+const json = (data, status = 200, extra = {}) => Response.json(data, { status, headers: { ...safeHeaders, ...extra } });
+function bounded(work, ms, code, onTimeout) {
+    let timer;
+    return Promise.race([work, new Promise((_, reject) => { timer = setTimeout(() => { onTimeout?.(); reject(new IntegrationError(code)); }, ms); })]).finally(() => clearTimeout(timer));
+}
+function claims(idToken, c) {
+    try {
+        const data = JSON.parse(Buffer.from(idToken.split(".")[1], "base64url").toString("utf8"));
+        if (data.iss !== c.canonicalIssuer || typeof data.sub !== "string" || !data.sub.trim())
+            return null;
+        return data;
+    }
+    catch {
+        return null;
+    }
+}
+export function createUserCenterAuth(options) {
+    const c = describeIntegration(options.manifest);
+    const environment = options.environment === undefined ? undefined : validateEnvironmentSelection(options.environment);
+    if (!options.database || typeof options.clientSecret !== "string" || !options.clientSecret.trim() || typeof options.sessionSecret !== "string" || !options.sessionSecret.trim() || options.sessionSecret.length < 32 || options.sessionSecret === options.clientSecret || !["allow-new", "existing-only"].includes(options.authUserPolicy) || typeof options.resolveBusinessUser !== "function")
+        throw new IntegrationError("INVALID_CONFIG");
+    const ttl = options.sessionTtlSeconds ?? 86400;
+    if (!Number.isInteger(ttl) || ttl < 300 || ttl > 86400)
+        throw new IntegrationError("INVALID_CONFIG");
+    // Capture explicit server values. Mutating the caller's object cannot change policy later.
+    const { database, clientSecret, sessionSecret, resolveBusinessUser, onEvent } = options;
+    const existingOnly = options.authUserPolicy === "existing-only";
+    function emit(phase, code, requestId = randomUUID()) {
+        try {
+            void Promise.resolve(onEvent?.(Object.freeze({ phase, code, requestId, at: new Date().toISOString(), version: TOOL_VERSION }))).catch(() => { });
+        }
+        catch { /* Observation must not change authentication. */ }
+    }
+    function buildAuth(metadata, state) {
+        const algorithms = metadata.id_token_signing_alg_values_supported;
+        const jwksUrl = c.canonicalIssuer + "/jwks";
+        const jwks = createRemoteJWKSet(new URL(jwksUrl), { timeoutDuration: 5000, [customFetch]: async (url) => {
+                if (url !== jwksUrl)
+                    throw new IntegrationError("UNTRUSTED_METADATA");
+                const data = await readPublicJson(jwksUrl, 1048576);
+                validateJwks(data);
+                return Response.json(data);
+            } });
+        function guardProviders(providers) {
+            if (state.failure)
+                throw state.failure;
+            function reject(code) {
+                const error = new IntegrationError(code);
+                state.invalidate(error);
+                throw error;
+            }
+            const matching = providers.filter(p => p.id === c.providerId);
+            // A partial official initialization must never become a reusable instance.
+            if (!matching.length)
+                reject("CENTER_UNAVAILABLE");
+            if (matching.length !== 1)
+                reject("UNTRUSTED_METADATA");
+            for (const provider of matching) {
+                if (provider.issuer !== c.canonicalIssuer || !provider.idToken || !("jwks" in provider.idToken) || provider.requiresIdTokenNonce !== true || !provider.idToken.algorithms || provider.idToken.algorithms.length !== algorithms.length || provider.idToken.algorithms.some(a => !algorithms.includes(a)))
+                    reject("UNTRUSTED_METADATA");
+                // Mutate the public provider object in place: its official verifier closes over it.
+                provider.idToken.jwks = jwks;
+            }
+        }
+        const plugin = genericOAuth({ config: [{
+                    providerId: c.providerId, name: "User Center", clientId: c.clientId, clientSecret,
+                    discoveryUrl: c.discoveryUrl, authorizationUrl: c.canonicalIssuer + "/oauth2/authorize", tokenUrl: c.canonicalIssuer + "/oauth2/token", userInfoUrl: c.canonicalIssuer + "/oauth2/userinfo",
+                    scopes: ["openid", "profile", "email"], responseType: "code", responseMode: "query", pkce: true, requireIdTokenVerification: true, disableIdTokenNonceBinding: false,
+                    tokenEndpointAuth: { method: "client_secret_basic" }, allowIdpInitiated: false, disableProviderLogout: true, disableSignUp: existingOnly, disableImplicitSignUp: existingOnly,
+                    async getUserInfo(tokens) {
+                        // This official extension runs only after the provider verifies signature and nonce.
+                        const verified = claims(tokens.idToken, c);
+                        if (!verified || !tokens.accessToken)
+                            return null;
+                        try {
+                            const data = await readPublicJson(c.canonicalIssuer + "/oauth2/userinfo", 65536, "CENTER_UNAVAILABLE", { Authorization: `Bearer ${tokens.accessToken}` });
+                            if (data.sub !== verified.sub || data.email_verified !== true || typeof data.email !== "string" || !data.email.trim() || typeof data.name !== "string")
+                                return null;
+                            return { sub: verified.sub, id: verified.sub, email: data.email, emailVerified: true, name: data.name };
+                        }
+                        catch {
+                            return null;
+                        }
+                    },
+                    accountSubject({ tokens, profile }) { const verified = claims(tokens.idToken, c); return verified && verified.sub === profile.sub ? verified.sub : ""; },
+                }] });
+        // Guard every API call, including retained auth objects, before and after official hooks.
+        const providerGuard = { matcher: () => true, handler: createAuthMiddleware(async (ctx) => { guardProviders(ctx.context.socialProviders); }) };
+        const guardedPlugin = { ...plugin, init: async (...args) => {
+                const result = await plugin.init(...args);
+                guardProviders(result.context.socialProviders);
+                return result;
+            }, hooks: { ...plugin.hooks, before: [providerGuard, ...plugin.hooks.before, providerGuard] } };
+        const auth = betterAuth({
+            baseURL: c.platformOrigin, basePath: c.authBasePath, secret: sessionSecret, database, trustedOrigins: [c.platformOrigin],
+            emailAndPassword: { enabled: false }, user: { deleteUser: { enabled: false } },
+            session: { expiresIn: ttl, disableSessionRefresh: true, cookieCache: { enabled: false } },
+            account: { accountLinking: { enabled: false }, encryptOAuthTokens: true },
+            advanced: { cookiePrefix: c.cookiePrefix, useSecureCookies: true, crossSubDomainCookies: { enabled: false }, defaultCookieAttributes: { secure: true, httpOnly: true, sameSite: "lax", path: "/" } },
+            onAPIError: { errorURL: c.platformOrigin + c.errorPath }, logger: { disabled: true }, rateLimit: { enabled: true, storage: "memory" }, plugins: [guardedPlugin],
+        });
+        return { auth, assertTrusted: async () => { guardProviders((await auth.$context).socialProviders); } };
+    }
+    let preparation;
+    async function loadAuth() {
+        if (!preparation) {
+            const state = { invalidate(error) {
+                    state.failure ??= error;
+                    if (preparation === attempt)
+                        preparation = undefined;
+                } };
+            const work = (async () => {
+                const metadata = validateDiscovery(await readPublicJson(c.discoveryUrl, 1048576), c, environment?.targetEnvironment);
+                if (state.failure)
+                    throw state.failure;
+                const prepared = buildAuth(metadata, state);
+                await prepared.assertTrusted();
+                return prepared;
+            })();
+            // All callers share one deadline; an expired generation cannot poison a later one.
+            const attempt = bounded(work, 10000, "CENTER_UNAVAILABLE", () => state.invalidate(new IntegrationError("CENTER_UNAVAILABLE")));
+            preparation = attempt;
+            void attempt.catch(error => state.invalidate(error instanceof IntegrationError ? error : new IntegrationError("CENTER_UNAVAILABLE")));
+        }
+        try {
+            const prepared = await preparation;
+            await prepared.assertTrusted();
+            return prepared.auth;
+        }
+        catch (e) {
+            const error = e instanceof IntegrationError ? e : new IntegrationError("CENTER_UNAVAILABLE");
+            emit("ready", error.code);
+            throw error;
+        }
+    }
+    async function getAuth() {
+        return loadAuth();
+    }
+    async function getIdentity(headers) {
+        try {
+            const auth = await getAuth();
+            const session = await auth.api.getSession({ headers });
+            if (!session)
+                return null;
+            const accounts = await auth.api.listUserAccounts({ headers });
+            const matches = accounts.filter(a => a.providerId === c.providerId);
+            if (!matches.length)
+                return null;
+            if (matches.length !== 1 || matches[0].userId !== session.user.id || typeof matches[0].accountId !== "string" || !matches[0].accountId.trim())
+                throw new IntegrationError("IDENTITY_CONFLICT");
+            return { issuer: c.canonicalIssuer, subject: matches[0].accountId, authUserId: session.user.id, profile: { name: session.user.name, email: session.user.email, emailVerified: session.user.emailVerified } };
+        }
+        catch (e) {
+            throw e instanceof IntegrationError ? e : new IntegrationError("CENTER_UNAVAILABLE");
+        }
+    }
+    async function getPrincipal(headers) {
+        const identity = await getIdentity(headers);
+        if (!identity)
+            return { status: "anonymous" };
+        const requestId = randomUUID();
+        const controller = new AbortController();
+        try {
+            const result = await bounded(Promise.resolve().then(() => resolveBusinessUser(identity, Object.freeze({ requestId, signal: controller.signal }))), 5000, "BUSINESS_RESOLUTION_FAILED", () => controller.abort());
+            if (result?.status === "unmapped")
+                return { status: "mapping-required", identity };
+            if (result?.status !== "ready" || typeof result.user?.id !== "string" || !result.user.id.trim())
+                throw new IntegrationError("BUSINESS_RESOLUTION_FAILED");
+            emit("business", "OK", requestId);
+            return { status: "authenticated", identity, user: result.user };
+        }
+        catch {
+            emit("business", "BUSINESS_RESOLUTION_FAILED", requestId);
+            throw new IntegrationError("BUSINESS_RESOLUTION_FAILED");
+        }
+    }
+    async function safeSession(headers) {
+        const auth = await getAuth();
+        const session = await auth.api.getSession({ headers });
+        return session ? { user: { id: session.user.id, name: session.user.name, email: session.user.email, emailVerified: session.user.emailVerified }, expiresAt: session.session.expiresAt.toISOString() } : null;
+    }
+    function redirectError(code, response) {
+        const headers = new Headers(safeHeaders);
+        headers.set("Location", c.platformOrigin + c.errorPath + "?code=" + code);
+        // Preserve state cleanup, but never deliver a session on a rejected redirect.
+        if (response)
+            for (const cookie of response.headers.getSetCookie())
+                if (!cookie.includes("session_token="))
+                    headers.append("Set-Cookie", cookie);
+        return new Response(null, { status: 302, headers });
+    }
+    async function handle(request) {
+        const url = new URL(request.url);
+        const path = url.pathname.slice(c.authBasePath.length);
+        if (url.origin !== c.platformOrigin || !url.pathname.startsWith(c.authBasePath + "/"))
+            return json({ code: "NOT_FOUND" }, 404);
+        const methods = { "/sign-in/social": "POST", "/get-session": "GET", "/sign-out": "POST", ["/callback/" + c.providerId]: "GET" };
+        if (!methods[path])
+            return json({ code: "NOT_FOUND" }, 404);
+        if (request.method !== methods[path])
+            return json({ code: "METHOD_NOT_ALLOWED" }, 405, { Allow: methods[path] });
+        if (request.method === "POST" && (request.headers.get("Origin") !== c.platformOrigin || request.headers.get("Sec-Fetch-Site") === "cross-site"))
+            return json({ code: "FORBIDDEN" }, 403);
+        try {
+            if (path === "/sign-in/social") {
+                if (url.search || !/^application\/json(?:;|$)/i.test(request.headers.get("Content-Type") ?? ""))
+                    return json({ code: "INVALID_LOGIN_REQUEST" }, 400);
+                const text = await request.text();
+                if (text.length > 4096)
+                    return json({ code: "INVALID_LOGIN_REQUEST" }, 400);
+                let body;
+                try {
+                    body = JSON.parse(text);
+                }
+                catch {
+                    return json({ code: "INVALID_LOGIN_REQUEST" }, 400);
+                }
+                const { returnTo } = parseLoginRequest(body, c);
+                const rebuilt = JSON.stringify({ provider: c.providerId, callbackURL: c.platformOrigin + returnTo, newUserCallbackURL: c.platformOrigin + returnTo, errorCallbackURL: c.platformOrigin + c.errorPath, disableRedirect: true });
+                const headers = new Headers(request.headers);
+                headers.delete("Content-Length");
+                headers.delete("Transfer-Encoding");
+                headers.set("Content-Type", "application/json");
+                const response = await (await loadAuth()).handler(new Request(request.url, { method: "POST", headers, body: rebuilt }));
+                if (!response.ok)
+                    return json({ code: "LOGIN_UNAVAILABLE" }, response.status >= 500 ? 503 : 400);
+                const data = await response.json();
+                const target = new URL(data.url);
+                if (target.origin !== c.centerOrigin || target.pathname !== new URL(c.canonicalIssuer + "/oauth2/authorize").pathname || target.username || target.password || target.hash)
+                    throw new IntegrationError("LOGIN_UNAVAILABLE");
+                const out = json({ url: target.href });
+                for (const cookie of response.headers.getSetCookie())
+                    out.headers.append("Set-Cookie", cookie);
+                emit("login", "OK");
+                return out;
+            }
+            if (path === "/get-session")
+                return json(await safeSession(request.headers));
+            if (path.startsWith("/callback/")) {
+                if (["code", "state", "error"].some(k => url.searchParams.getAll(k).length > 1))
+                    return redirectError("LOGIN_UNAVAILABLE");
+                const response = await (await loadAuth()).handler(request);
+                const location = response.headers.get("Location");
+                if (!location)
+                    return redirectError("LOGIN_UNAVAILABLE", response);
+                const target = new URL(location, c.platformOrigin);
+                if (target.origin !== c.platformOrigin || target.username || target.password || target.hash)
+                    return redirectError("LOGIN_UNAVAILABLE", response);
+                if (target.pathname === c.errorPath)
+                    return redirectError(target.searchParams.get("error") === "account_not_linked" ? "ACCOUNT_CONFLICT" : "LOGIN_UNAVAILABLE", response);
+                try {
+                    validateReturnTo(target.pathname + target.search, c);
+                    if (target.hash)
+                        throw new Error();
+                }
+                catch {
+                    return redirectError("INVALID_RETURN_TO", response);
+                }
+                const headers = new Headers(response.headers);
+                for (const [k, v] of Object.entries(safeHeaders))
+                    headers.set(k, v);
+                emit("callback", "OK");
+                return new Response(null, { status: response.status, headers });
+            }
+            const auth = await getAuth();
+            const response = await auth.handler(request);
+            let confirmed = false;
+            if (response.ok)
+                try {
+                    confirmed = await auth.api.getSession({ headers: request.headers, query: { disableCookieCache: true, disableRefresh: true } }) === null;
+                }
+                catch { /* A failed confirmation read must not declare revocation. */ }
+            const out = confirmed ? json({ success: true }) : json({ code: "SIGN_OUT_UNCONFIRMED" }, 503);
+            for (const cookie of response.headers.getSetCookie())
+                out.headers.append("Set-Cookie", cookie);
+            emit("logout", confirmed ? "OK" : "SIGN_OUT_UNCONFIRMED");
+            return out;
+        }
+        catch (e) {
+            const code = e instanceof IntegrationError ? e.code : "CENTER_UNAVAILABLE";
+            if (path.startsWith("/callback/"))
+                return redirectError(code);
+            return json({ code }, ["INVALID_LOGIN_REQUEST", "INVALID_RETURN_TO"].includes(code) ? 400 : code === "IDENTITY_CONFLICT" ? 409 : 503);
+        }
+    }
+    return { publicConfig: describeIntegration(options.manifest), ready: async () => { await getAuth(); emit("ready", "OK"); }, getAuth, getIdentity, getPrincipal, handlers: { GET: handle, POST: handle } };
+}

package/dist/reference/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 User Center contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/reference/README.md

@@ -0,0 +1,10 @@
+# User Center 0.1.10 接入资料
+
+本目录随 SDK 和 CLI 两个 npm 包完整交付，可安装后阅读，也可从精确版本 tgz 解包获得。无需访问中心源码仓库。许可见 [LICENSE](LICENSE)，本发行内容使用 MIT；中心工程、原独立样例及第三方依赖的许可仍分别处理。
+
+1. 从零接入先读[完整指南](guide/index.md)。
+2. 三环境选择见[环境说明](guide/environments.md)，只读检查见[doctor](guide/doctor.md)，正式支持状态见[支持范围](guide/support.md)。
+3. 给目标工程 Agent 使用[接入 Prompt](guide/agent-prompt.md)。
+4. 新工程可手动复制[完整 Next 参考样例](example-next/README.md)，已有工程按指南复用其接线，不覆盖已有用户和业务数据。
+
+版本 0.1.10 是公开试用定位。候选 tgz 与已实际发布的 registry 版本应分别确认；dry-run 不上传。生产认证、真实邮件、宿主存储和正式兼容组合继续待验，blog 接入保持用户确认已完成。

package/dist/reference/example-next/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 User Center contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/reference/example-next/README.md

@@ -0,0 +1,27 @@
+# 可复制 Next 参考样例 0.1.10
+
+这是随 SDK/CLI npm 包交付的宿主示例。手动复制本目录的内容到一个新的空目录，保留 LICENSE。把 gitignore.txt 复制为 .gitignore，把 environment.example.txt 复制为你自己的 .env.local，再填写秘密。原包完整指南在 dist/reference/guide/index.md，Agent Prompt 在 dist/reference/guide/agent-prompt.md；安装 SDK 后也可在 node_modules/@user-center/next-better-auth/dist/reference/ 中读取。无需中心仓库权限。
+
+## 安装
+
+本项目 package.json 已固定 SDK/CLI 0.1.10 和 Better Auth 1.7.12，不依赖 workspace 或仓库相对路径。版本已发布时在复制后的目录运行 pnpm install --ignore-scripts。
+
+候选交付尚未上传 npm 时，先由操作者提供原 tgz 和摘要。将 package.json 中两个 @user-center 依赖改为已核验 tgz 的 file: 绝对路径，再运行 pnpm install --ignore-scripts 并保存自己的锁文件。不要仅凭本文猜装 registry 同名版本，也不要把别人的锁文件当作你的环境验收。
+
+本地工具可先 pnpm typecheck。它只验证样例类型与路由，不完成认证。SDK 和 doctor 不执行复制、安装或迁移，所有宿主操作由你明确运行。
+
+## 配置与数据库
+
+旧单配置使用 integration.json，填写实际 issuer、HTTPS origin、专用 Client ID 及派生回调，保持模板中的三个可选选择器为注释。profiles 模式可把 profiles.example.json 复制为 integration.environments.json，再取消 USER_CENTER_CONFIG_FILE 与 USER_CENTER_RUNTIME_ENVIRONMENT 两行的注释并填写实际值，以及选中 profile 引用的秘密。未设置 USER_CENTER_TARGET_ENVIRONMENT 时默认与 runtime 相同，需要指定 target 才取消该行注释并填写有效值；不要启用空赋值。只有 development 可跨中心；切 target 不切平台库和会话密钥。
+
+DATABASE_URL 指向样例自己的认证数据库，PLATFORM_SESSION_SECRET 至少 32 字符且独立于 Client Secret。仅准备且已授权的宿主数据库可以迁移：先 pnpm schema:plan，人工审查，再 pnpm schema:apply。两者使用 --conditions=react-server 并加载同一宿主环境；SDK/doctor 不代为执行。现有库不能直接套用干净样例迁移，须先核对旧表、外键、重复身份及 Account(providerId,accountId) 全局唯一约束。
+
+本样例不生成证书、改 hosts 或创建中心 Client。你需准备可信 HTTPS 本地域名或受控反向代理，保证登记的 origin 与实际回调一致；localhost/回环 IP 不属于首期平台 origin 范围。可按自己的 HTTPS 入口运行 pnpm dev。
+
+## 验收入口
+
+从 /projects/example?tab=activity 发起，完成中心注册和真实邮件验证后主动登录、必要授权、派生回调和身份验证，回到同一业务目标；页面/API principal 一致，刷新保持会话，本地退出后拒绝访问。若原授权请求已过期，从平台重新发起，不延长或重放旧请求。
+
+干净样例明确以 authUserId 作为业务 ID。已有工程应保留原用户归属并自行实现稳定 issuer/subject 映射，不按相同邮箱自动认领。受保护页面和 /api/me 都检查 principal；映射未完成、匿名和依赖故障分别拒绝访问。
+
+pnpm exec user-center doctor --config integration.json --project . --env-file .env.local --json 仅是静态诊断。profiles 先由宿主导出单 Manifest。未配置样例的 FAIL 是预期结果；生产认证、真实邮件、宿主约束和正式兼容仍待验。blog 已由用户确认接入完成，本样例不据此推定其 SDK 版本。

package/dist/reference/example-next/environment.example.txt

@@ -0,0 +1,8 @@
+USER_CENTER_CLIENT_SECRET=
+PLATFORM_SESSION_SECRET=
+DATABASE_URL=
+# Optional profiles selectors. Keep commented for the legacy manifest.
+# Enable CONFIG_FILE and RUNTIME together for profiles; omit TARGET to use runtime.
+# USER_CENTER_CONFIG_FILE=
+# USER_CENTER_RUNTIME_ENVIRONMENT=
+# USER_CENTER_TARGET_ENVIRONMENT=

package/dist/reference/example-next/gitignore.txt

@@ -0,0 +1,5 @@
+node_modules/
+.next/
+.env*
+*.tsbuildinfo
+next-env.d.ts

package/dist/reference/example-next/integration.json

@@ -0,0 +1,10 @@
+{
+  "schemaVersion": 1,
+  "issuer": "https://auth.example.com/api/auth",
+  "platformOrigin": "https://platform.example.test:3443",
+  "clientId": "replace-with-registered-client-id",
+  "clientSecretEnv": "USER_CENTER_CLIENT_SECRET",
+  "sessionSecretEnv": "PLATFORM_SESSION_SECRET",
+  "returnTo": {"fallback": "/dashboard", "allowedPaths": ["/dashboard"], "allowedPathPrefixes": ["/projects"], "allowedQueryKeys": ["tab"]},
+  "errorPath": "/auth-error"
+}

package/dist/reference/example-next/next.config.ts

@@ -0,0 +1,3 @@
+import type { NextConfig } from "next";
+const config: NextConfig = { poweredByHeader: false };
+export default config;

package/dist/reference/example-next/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "user-center-sdk-consumer",
+  "version": "0.1.10",
+  "private": true,
+  "type": "module",
+  "packageManager": "pnpm@12.9.1",
+  "scripts": {
+    "dev": "next dev --hostname 0.0.0.0",
+    "build": "next build",
+    "start": "next start",
+    "typecheck": "next typegen && tsc --noEmit",
+    "schema:plan": "node --conditions=react-server --import tsx scripts/schema.mts",
+    "schema:apply": "node --conditions=react-server --import tsx scripts/schema.mts --apply"
+  },
+  "dependencies": {
+    "@next/env": "16.4.3",
+    "@user-center/next-better-auth": "0.1.10",
+    "better-auth": "1.7.12",
+    "next": "16.4.3",
+    "pg": "8.23.1",
+    "react": "19.3.0",
+    "react-dom": "19.3.0",
+    "server-only": "0.0.1"
+  },
+  "devDependencies": {
+    "@types/node": "^24",
+    "@types/pg": "8.23.1",
+    "@types/react": "^19",
+    "@types/react-dom": "^19",
+    "@user-center/cli": "0.1.10",
+    "tsx": "4.23.15",
+    "typescript": "5.9.3"
+  },
+  "engines": {
+    "node": ">=22.21.1"
+  }
+}

package/dist/reference/example-next/pnpm-workspace.yaml

@@ -0,0 +1,4 @@
+packages:
+  - .
+allowBuilds:
+  esbuild: true

package/dist/reference/example-next/profiles.example.json

@@ -0,0 +1,34 @@
+{
+  "schemaVersion": 1,
+  "centers": {
+    "development": "https://auth.user-center.test:3000/api/auth",
+    "staging": "https://auth-staging.example.com/api/auth",
+    "production": "https://auth.example.com/api/auth"
+  },
+  "runtimes": {
+    "development": {
+      "platformOrigin": "https://platform.user-center.test:3443",
+      "sessionSecretEnv": "PLATFORM_DEVELOPMENT_SESSION_SECRET",
+      "database": {"urlEnv": "PLATFORM_DEVELOPMENT_DATABASE_URL", "hostname": "127.0.0.1", "port": 54330, "database": "platform_dev", "username": "platform_dev"},
+      "clients": {
+        "development": {"clientId": "register-local-client-in-local-center", "clientSecretEnv": "LOCAL_TO_DEVELOPMENT_CLIENT_SECRET"},
+        "staging": {"clientId": "register-local-callback-client-in-staging-center", "clientSecretEnv": "LOCAL_TO_STAGING_CLIENT_SECRET"},
+        "production": {"clientId": "register-local-callback-client-in-production-center", "clientSecretEnv": "LOCAL_TO_PRODUCTION_CLIENT_SECRET"}
+      }
+    },
+    "staging": {
+      "platformOrigin": "https://platform-staging.example.com",
+      "sessionSecretEnv": "PLATFORM_STAGING_SESSION_SECRET",
+      "database": {"urlEnv": "PLATFORM_STAGING_DATABASE_URL", "hostname": "staging-db.example.com", "port": 5432, "database": "platform_staging", "username": "platform_staging"},
+      "clients": {"staging": {"clientId": "register-staging-platform-client", "clientSecretEnv": "STAGING_TO_STAGING_CLIENT_SECRET"}}
+    },
+    "production": {
+      "platformOrigin": "https://platform.example.com",
+      "sessionSecretEnv": "PLATFORM_PRODUCTION_SESSION_SECRET",
+      "database": {"urlEnv": "PLATFORM_PRODUCTION_DATABASE_URL", "hostname": "production-db.example.com", "port": 5432, "database": "platform_production", "username": "platform_production"},
+      "clients": {"production": {"clientId": "register-production-platform-client", "clientSecretEnv": "PRODUCTION_TO_PRODUCTION_CLIENT_SECRET"}}
+    }
+  },
+  "returnTo": {"fallback": "/dashboard", "allowedPaths": ["/dashboard"], "allowedPathPrefixes": ["/projects"], "allowedQueryKeys": ["tab"]},
+  "errorPath": "/auth-error"
+}