@tapokjs/core

Изоморфный TypeScript-пакет для протокола Tapok Base и Connect. Работает в браузере, Bun 1.4+, Node.js 22+ и Deno 2+.

Полное руководство по интеграции: tapok.orria.space/docs/core. Сначала выберите режим в обзоре.

Установка

bun add @tapokjs/core

Когда нужен Core

Берите Core, если пишете свой browser или server adapter. Он предоставляет:

• константы TAPOK_ISSUER, TAPOK_API_BASE_URL, tapokEndpoints;
• генерацию state, nonce и PKCE S256;
• builders для Base и Connect authorize URL;
• bodies для Base exchange, Connect token и revoke;
• строгую проверку callback по state и exact iss;
• runtime-парсеры protocol responses.

Core не хранит transaction, не открывает popup, не создаёт client_secret_basic, не проверяет JWT signature и не создаёт сессию. Для готовой интеграции используйте @tapokjs/sdk/browser или @tapokjs/sdk/server.

Base пример

import {
  TAPOK_ISSUER,
  buildBaseAuthorizeUrl,
  createAuthorizationSecrets,
  parseAndValidateAuthorizationCallback,
} from "@tapokjs/core";

const secrets = await createAuthorizationSecrets();
const authorizationUrl = buildBaseAuthorizeUrl({
  redirectUri: "https://app.example/auth/tapok/callback",
  scopes: ["age:18"],
  state: secrets.state,
  nonce: secrets.nonce,
  codeChallenge: secrets.pkce.challenge,
});

// Сохраните state, nonce и secrets.pkce.verifier в transaction приложения.
location.assign(authorizationUrl);

const callback = parseAndValidateAuthorizationCallback({
  callbackUrl: location.href,
  expectedState: transaction.state,
  expectedIssuer: TAPOK_ISSUER,
});

buildBaseAuthorizeUrl() сам вычисляет client_id как origin:<redirect origin>, всегда добавляет session и принимает только optional age:18. parseAndValidateAuthorizationCallback() до возврата code проверяет единственность и совпадение state и iss. При ошибке он бросает TapokCallbackValidationError.

Connect helpers

Для Connect используйте buildConnectAuthorizeUrl(), createConnectTokenBody(), createConnectRevokeBody(), parseConnectTokenResponse() и parseConnectUserInfo(). В список scopes обязательно входит openid.

const authorizationUrl = buildConnectAuthorizeUrl({
  clientId: "tpk_client_example",
  redirectUri: "https://app.example/auth/tapok/callback",
  scopes: ["openid", "email"],
  state: secrets.state,
  nonce: secrets.nonce,
  codeChallenge: secrets.pkce.challenge,
});

В Connect храните state, nonce и pkce.verifier только на backend. Scope email добавляет в ID token и UserInfo короткий технический user-<pairwise-id>@tapok.orria.space с email_verified: true; это не контактный адрес. Проверку ES256 signature, kid, iss, aud, nonce, срока жизни и mode выполняйте через @tapokjs/sdk/server или свой server verifier.

API

• Base: быстрый старт, manifest, API
• Connect: быстрый старт, scopes
• Общие требования: безопасность

Команды разработки

bun install
bun run typecheck
bun test
bun run build
bun run check

bun run check запускает typecheck, contract tests, сборку tsdown и импорт опубликованного ESM в Bun, Node.js и Deno.