Справочник Browser и Backend SDK

API браузерного и серверного SDK для интеграции приложений. Подключение.

Browser options и методы

API	Контракт
MixBrowserOptions	issuer, clientId, redirectUri: string; scopes?: string[]
new MixBrowserClient(options)	Нормализует issuer без завершающего slash; нужны browser APIs
signIn(mode = redirect)	redirect уводит со страницы и не возвращает на ней tokens; popup возвращает token-set promise
handleCallback(url = location.href)	Promise MixTokenSet после callback binding и обмена сохранённой транзакции
postPopupCallback(url = location.href)	Отправляет callback opener на настроенный origin и закрывает popup
verifyIdentityToken(token, {issuer, audience, nonce})	Promise проверенного identity JWTPayload; не авторизация access token

MixTokenSet содержит access_token, token_type=Bearer и положительный expires_in; id_token, refresh_token и scope optional по типу/политике. Реализация хранит authorization transaction 10 минут; exchange timeout — 10 секунд. State удаляется до обмена; после неудачного одноразового exchange начинайте новую авторизацию, не повторяйте code. Popup требует same application origin, user activation и разрешённого окна; проверяются origin/source/state. Redirect и popup требуют отдельных integration tests.

SDK хранит pending verifier/nonce binding в sessionStorage, но не реализует общую token persistence API. Не помещайте токены в logs/URL; выберите проверенную memory либо server-session стратегию приложения.

Использование redirect callback

import { MixBrowserClient, type MixTokenSet } from '@zorin/mix-browser';

export function createIdentityClient(clientId: string): MixBrowserClient {
    return new MixBrowserClient({
        issuer: 'https://id.zorin.cloud',
        clientId,
        redirectUri: new URL('/auth/callback', location.origin).href,
        scopes: ['openid', 'profile'],
    });
}

export async function completeRedirect(client: MixBrowserClient): Promise<MixTokenSet> {
    try {
        return await client.handleCallback(location.href);
    } finally {
        const clean = new URL(location.href);
        for (const key of ['code', 'state', 'error', 'error_description']) clean.searchParams.delete(key);
        history.replaceState(null, '', clean.href);
    }
}

Callback path должен точно соответствовать зарегистрированному redirect URI приложения. В login action вызывайте client.signIn(‘redirect’), а completeRedirect(client) — только на callback route. При отказе показывайте безопасное состояние и новый sign-in. Пример убирает authorization query parameters и при ошибке; он не создаёт app session и не реализует account linking.

Backend verification

MixVerifierOptions требует issuer и audience; clockTolerance optional (default 5 секунд), как expectedTrustTier и expectedIdentityMode. verifyAccessToken(token) проверяет ES256/JWKS, issuer/audience, наличие exp/iat/sub/sid/scope, access token_use и допустимые trust/identity modes; настроенные expected modes должны совпасть. Это offline signature/claims verification, не запрос об отзыве сессии. requireScopes(claims, required) отклоняет недостающие scopes. bearer(header) ожидает Bearer prefix; результат всегда пропускайте через verifier.

import { MixTokenVerifier, bearer, type MixAccessClaims } from '@zorin/mix-node';

export function createAccessVerifier(audience: string): MixTokenVerifier {
    return new MixTokenVerifier({
        issuer: 'https://id.zorin.cloud',
        audience,
        expectedIdentityMode: 'MIX_ACCOUNT',
    });
}

export async function verifyRequest(
    verifier: MixTokenVerifier,
    authorization: string | undefined,
    requiredScopes: string[],
): Promise<MixAccessClaims> {
    const claims = await verifier.verifyAccessToken(bearer(authorization));
    verifier.requireScopes(claims, requiredScopes);
    return claims;
}

Audience задаётся регистрацией защищаемого API, не берётся из непроверенного токена. Пример намеренно ожидает MIX_ACCOUNT; организация с directory должна выбрать нужный identity mode. Ошибка verification означает authentication failure; нехватка scope/прав ресурса — authorization failure. Не логируйте raw tokens. Проверка scopes не заменяет владение ресурсом.

Trusted gateway helpers

signTrustedIdentity(identity, secret) возвращает envelope/signature; verifyTrustedIdentity(envelope, signature, secret, options) проверяет HMAC envelope. Identity содержит sub, sid, aud, scope[], trustTier, identityMode, expiresAt/issuedAt в секундах, requestId, method и path. Secret — минимум 32 bytes; verification ограничивает размер envelope, default maxAgeSeconds — 30. Передавайте ожидаемые method/path, проверяйте audience сервиса и replay policy; requestId сам по себе не replay cache. Механизм предназначен для доверенной gateway/service границы, не публичного arbitrary signing service и не реализации RFC 9421.