ZTXBAS Node.js / TypeScript SDK

TypeScript に適したクライアントです。Node 組み込みの fetch と node:crypto を使用し、外部ランタイム依存はありません。

インストール

Node.js 18 以降が必要です。

npm install @corezt/ztxbas

インポート

以下のパッケージからクライアントを読み込みます。

import { Client, ChallengeDeniedError } from '@corezt/ztxbas';

最小構成のエンドツーエンド例

ユーザー、オリジンを登録し、チャレンジを作成・ポーリングして認証済み claims を取得します。

const c = new Client(
  'https://ztxbas.example.com',
  'app_YOUR_APPLICATION_ID',
  'YOUR_HMAC_SECRET_HEX',
);

await c.registerUser({ email: 'alice@example.com' });
await c.registerOrigin({
  origin: 'https://app.example.com',
  display_name: 'Example App',
});

const ch = await c.createChallenge({
  user_email: 'alice@example.com',
  origin: 'https://app.example.com',
});

const claims = await c.pollChallenge(ch.challenge_id);
console.log(claims.email, claims.origin);

型付きエラーの扱い

SDK エラーは ZtxbasError を継承します。instanceof で ChallengeDeniedError、ChallengeExpiredError、UnregisteredOriginError などを判定します。

import {
  ChallengeDeniedError,
  ChallengeExpiredError,
  UnregisteredOriginError,
} from '@corezt/ztxbas';

try {
  await c.pollChallenge(ch.challenge_id);
} catch (e) {
  if (e instanceof ChallengeDeniedError) { /* user Denied */ }
  else if (e instanceof ChallengeExpiredError) { /* TTL elapsed */ }
  else if (e instanceof UnregisteredOriginError) { /* programmer error */ }
  else throw e;
}

JWT 検証のみのモード

JWT の検証だけが必要な場合は Verifier を作成し、expectedIssuer を設定して verify() を呼び出します。

import { Verifier } from '@corezt/ztxbas';

const v = new Verifier(
  'https://ztxbas.example.com/.well-known/jwks.json',
  { expectedIssuer: 'https://ztxbas.example.com' },
);
const claims = await v.verify(jwtFromMobile);

リポジトリとリファレンス

• SDK ソース
• npm パッケージ
• クイックスタート