认证 SDK 与登录 UI
认证独立于业务SDK，以项目已发布配置决定实际登录方式。
发现与发起登录
先用getConfig读取Realm已发布方式，再按connectionKey调用begin。依据返回mode渲染form、跳转redirect或使用本地注册的custom-ui。不要按供应商名称硬编码完整流程。
TypeScript
import type { Shell } from '@mosaic-base/shell';
import type { ArticleSDK, SiteSDK, I18nSDK } from '@mosaic-base/client-sdk';
import type { AuthClient, ServerAuthClient } from '@mosaic-base/auth-sdk';
// Declare once in your application's type contract, never import SDK implementations.
declare module '@mosaic-base/shell/contracts' {
interface SdkRegistry {
'site.config': Pick<SiteSDK, 'getConfig'>;
'content.articles': Pick<ArticleSDK, 'list' | 'getBySlug' | 'getPreview' | 'search'>;
'i18n.messages': Pick<I18nSDK, 'load' | 't' | 'clearCache' | 'refresh'>;
'auth.client': AuthClient | ServerAuthClient;
}
}
export async function beginPublishedMethod(shell: Shell, connectionKey: string) {
const auth = await shell.getSdk('auth.client') as AuthClient; // browser mapping
const result = await auth.begin({ connectionKey });
if (result.error) throw new Error(result.error.message);
return result.data;
}
export async function signOut(shell: Shell) {
return (await shell.getSdk('auth.client') as AuthClient).signOut();
}
// The Auth MF's createAuthShellHost owns verified identity transitions and disposal.
// Set auth.client's HTTP credentials policy explicitly; never replay a business write.使用 React 登录面板
AuthProvider/AuthPanel负责配置、方式选择、表单/跳转及可信会话交接。上游供应商是否可用由真实配置和发布决定；展示扩展协议不等于已完成所有真实云授权。
TypeScript / React
import { AuthProvider, AuthPanel } from '@mosaic-base/auth-ui';
import type { AuthClient } from '@mosaic-base/auth-sdk';
// Pass the selected instance; the application owns its lifecycle.
export function Login({ client }: { client: AuthClient }) {
return (
<AuthProvider realmKey="default-client" client={client}>
<AuthPanel appearance={{ theme: 'system', variant: 'card' }} />
</AuthProvider>
);
}服务端按请求创建
平台会话保存在HttpOnly Cookie。服务器只转发本次请求Cookie，客户端不能自行读取或持久化令牌。SDK的只读服务端客户端不负责写Cookie，续期由宿主可写响应边界完成。
TypeScript
import type { Shell } from '@mosaic-base/shell';
import type { ArticleSDK, SiteSDK, I18nSDK } from '@mosaic-base/client-sdk';
import type { AuthClient, ServerAuthClient } from '@mosaic-base/auth-sdk';
// Declare once in your application's type contract, never import SDK implementations.
declare module '@mosaic-base/shell/contracts' {
interface SdkRegistry {
'site.config': Pick<SiteSDK, 'getConfig'>;
'content.articles': Pick<ArticleSDK, 'list' | 'getBySlug' | 'getPreview' | 'search'>;
'i18n.messages': Pick<I18nSDK, 'load' | 't' | 'clearCache' | 'refresh'>;
'auth.client': AuthClient | ServerAuthClient;
}
}
export async function readRequestUser(shell: Shell) {
const auth = await shell.getSdk('auth.client');
return auth.getUser();
}
// Create the request Shell with only auth.client's Cookie policy and realmKey option.
// Dispose in the request owner. Node SDK is read-only; renewal is a writable boundary.正确处理状态
getUser验证平台会话；网络失败使用unavailable，不能当作退出成功。关联账号、换绑和投递需要相应证明及真实渠道，不以刷新令牌代替近期认证。