Authentication SDK and UI
Authentication is separate from the business SDK and follows the project’s published configuration.
Discover and begin sign-in
Read published Realm methods with getConfig, then begin using the selected connectionKey. Render form, redirect or locally registered custom-ui according to mode. Do not hard-code an entire flow by provider name.
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.Use the React sign-in panel
AuthProvider/AuthPanel handle configuration, method selection, form/redirect and verified session handoff. Real configuration and publication determine provider availability. Extension protocols do not imply all cloud authorizations are tested.
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>
);
}Create server clients per request
Platform sessions use HttpOnly Cookies. Servers forward only the current request’s Cookie, and browser code must not read or persist tokens. The read-only server client does not write Cookies; refresh belongs in the host’s writable response boundary.
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.Handle state correctly
getUser verifies the platform session. Network failures mean unavailable, not a confirmed sign-out. Account linking, identifier replacement and delivery require the relevant proof and real channels; a refresh token is not recent authentication.