db-tech-uk-server-lib

DB-TECH UK 認証 API 用サーバークライアント。

各サイトサーバーが認証・ユーザー管理・Webhook 受信・Google カレンダー連携を行うためのライブラリです。

インストール

npm install db-tech-uk-server-lib

環境変数

| env | 内容 | | :-- | :-- | | SERVER_SECRET | 管理画面で登録したサーバー秘密鍵の平文 |

使い方

ServerClient（facade）

import { ServerClient } from 'db-tech-uk-server-lib';

const client = new ServerClient({
  isStage: true,
  serverSecret: process.env.SERVER_SECRET!,
});

| プロパティ | 役割 | | :-- | :-- | | client.auth | refresh / logout | | client.users | ユーザー一覧・詳細 / 名前・ロール変更 / 削除 / プロバイダー解除 / アイコン・パスワード・メール変更 | | client.loginLog | ログイン履歴一覧（マスター/管理者） | | client.enroll | 追加認証（enroll）開始 | | client.signup | サインアップ URL 発行 | | client.calendar | Google カレンダー API プロキシ |

refresh / logout

const tokens = await client.auth.refresh(refreshToken);
// 旧refreshTokenは失効する。必ず新しいrefreshTokenを保存する

await client.auth.logout(refreshToken);

ユーザー一覧・詳細・名前変更・ロール変更（マスター/管理者）

// 一覧（page/count はセットで指定。省略時は全件）
const { users, totalCount, lastPage } = await client.users.listUsers(accessToken, {
  page: 1,
  count: 50,
  name: '山田',
  roleType: 3,
  isInactive: false,
});

const { user } = await client.users.getUser(accessToken, userId);

// 名前変更（マスターは管理者・一般、管理者は一般のみ。マスター本人は変更不可）
await client.users.patchUserName(accessToken, userId, { name: '新しい名前' });

// ロール変更（roleType: 2=管理者、3=一般。マスター昇格は不可）
await client.users.patchUserRole(accessToken, userId, { roleType: 2 });

ログイン履歴（マスター/管理者）

const { logs, totalCount, lastPage } = await client.loginLog.listLogs(accessToken, {
  page: 1,
  count: 100,
  provider: 'google',
  isSuccess: true,
  loggedAtFrom: '2026-09-01 00:00:00',
  loggedAtTo: '2026-09-30 23:59:59',
});

表示名変更（本人）

await client.users.patchMeName(accessToken, { name: '新しい名前' });

ユーザー削除 / プロバイダー解除

// 自分自身を削除（204）
await client.users.deleteMe(accessToken);

// 指定ユーザーを削除（マスター/管理者、204）
await client.users.deleteUser(accessToken, userId);

// プロバイダー解除（204）
await client.users.deleteCredential(accessToken, 'google');
await client.users.deleteCredential(accessToken, 'github');
await client.users.deleteCredential(accessToken, 'line');
await client.users.deleteCredential(accessToken, 'mail');

アイコン・パスワード・メール変更

// アイコン登録（JPEG/PNG/WebP/GIF、200×200px以下、5MiB以下）
const { iconUrl } = await client.users.putIcon(accessToken, iconBlob);

// パスワード変更（mail 認証ユーザー）
await client.users.patchPassword(accessToken, {
  oldPassword: '...',
  newPassword: '...',
});

// メール変更（6桁コード送信。token を verify に渡す）
const { token } = await client.users.patchMail(accessToken, { mail: '[email protected]' });
await client.users.verifyMail(accessToken, { token, code: '123456' });

putIcon の iconBlob は Blob / File（Node 18+ の globalThis.Blob 等）を渡してください。フィールド名は API 仕様どおり icon です。

enroll（追加認証）開始

ログイン済みユーザーに別プロバイダーを紐付ける OAuth フローを開始します。返却された redirectUrl へブラウザをリダイレクトしてください。

const result = await client.enroll.startGoogle(accessToken, {
  expiresInSec: 600,
  successUrl: 'https://example.com/enroll/success',
  failureUrl: 'https://example.com/enroll/failure',
});
// result.redirectUrl, result.expiresAt

await client.enroll.startGithub(accessToken, { ... });
await client.enroll.startLine(accessToken, { ... });

サインアップ URL 発行

const result = await client.signup.issueGoogleUrl(accessToken, { expiresInSec: 3600 });
// result.signupUrl, result.expiresAt

await client.signup.issueGithubUrl(accessToken, { expiresInSec: 3600 });
await client.signup.issueLineUrl(accessToken, { expiresInSec: 3600 });
await client.signup.issueMailUrl(accessToken, { expiresInSec: 3600 });

// OAuth signup URL を指定メールへ送る場合（google / github / line）
await client.signup.issueGoogleUrl(accessToken, {
  expiresInSec: 3600,
  mail: '[email protected]',
});

メール signup のレスポンスは signupUrl と expiresAt のみ です（トークン ID の別フィールドは返しません）。signupUrl は共通 API Worker 公開 SPA の /signup/mail?token={UUID} です（JWT ではありません）。登録 UI は公開ページ、API は POST /v1/auth/signup/mail（verificationId）と POST /v1/auth/signup/mail/verify です。サイトサーバー側で URL を組み立てる必要がある場合:

import { buildMailSignupPageUrl } from 'db-tech-uk-server-lib';

const url = buildMailSignupPageUrl({
  origin: 'https://stage.d-b-tech.uk',
  tokenId: '...', // 通常は issueMailUrl の signupUrl から取り出す必要はない
});

メール signup 完了時の Webhook は provider: "mail"、identifier に 小文字正規化後のメールアドレス が入ります。

Webhook 受信

管理画面で設定した Webhook URL へ、signup / enroll / unlink 完了時に JSON POST されます。

import { parseWebhookPayload, WEBHOOK_EVENT_TYPES } from 'db-tech-uk-server-lib';

app.post('/webhook/db-tech', express.json(), (req, res) => {
  const payload = parseWebhookPayload(req.body);
  // payload.event: 'signup' | 'enroll' | 'unlink'
  // payload.domainKey, payload.userId, payload.provider, payload.identifier, payload.occurredAt
  res.sendStatus(204);
});

POST body 例:

{
  "event": "signup",
  "domainKey": "example-com",
  "userId": "01J...",
  "provider": "github",
  "identifier": "12345678",
  "occurredAt": "2026-09-21 23:00:00"
}

Google カレンダー

Google Calendar API v3 のプロキシです。body / query は Google 公式仕様 に準拠し、そのまま渡せます。 ログイン済みユーザーの accessToken が必要です（Bearer）。Google sub 登録時にカレンダー権限を取得済みであること。

const calendars = await client.calendar.listCalendars(accessToken, { maxResults: 250 });

const events = await client.calendar.listEvents(accessToken, 'primary', {
  timeMin: '2026-09-01T00:00:00+09:00',
  timeMax: '2026-09-30T23:59:59+09:00',
  singleEvents: true,
  orderBy: 'startTime',
  pageToken: '...',
});

const event = await client.calendar.createEvent(accessToken, 'primary', {
  summary: '予約',
  start: { dateTime: '2026-09-10T10:00:00+09:00', timeZone: 'Asia/Tokyo' },
  end: { dateTime: '2026-09-10T11:00:00+09:00', timeZone: 'Asia/Tokyo' },
  extendedProperties: { private: { bookingId: '12345' } },
});

await client.calendar.updateEvent(accessToken, 'primary', event.id as string, { summary: '予約（変更）' });
await client.calendar.deleteEvent(accessToken, 'primary', event.id as string);

メールログインコールバック（JSON）

フロントが login_success_url へ POST した body をパースする。

import { parseMailLoginCallback } from 'db-tech-uk-server-lib';

app.post('/auth/mail/callback', express.json(), (req, res) => {
  const result = parseMailLoginCallback(req.body);
  // result.accessToken, result.refreshToken, result.user をセッション等に保存
});

Google / GitHub / LINE ログイン

import {
  buildGoogleLoginUrl,
  buildGithubLoginUrl,
  buildLineLoginUrl,
  decodeAccessTokenPayload,
  parseGoogleLoginSuccessCallback,
  parseGoogleLoginFailureCallback,
  parseGithubLoginSuccessCallback,
  parseGithubLoginFailureCallback,
  parseLineLoginSuccessCallback,
  parseLineLoginFailureCallback,
} from 'db-tech-uk-server-lib';

// ログイン開始URL（ブラウザをここへリダイレクト）
const googleLoginUrl = buildGoogleLoginUrl({ isStage: true, domainKey: 'your-domain-key' });
const githubLoginUrl = buildGithubLoginUrl({ isStage: true, domainKey: 'your-domain-key' });
const lineLoginUrl = buildLineLoginUrl({ isStage: true, domainKey: 'your-domain-key' });

// 成功コールバック（application/x-www-form-urlencoded）
app.post('/auth/google/callback', express.urlencoded({ extended: false }), (req, res) => {
  const result = parseGoogleLoginSuccessCallback(req.body);
  const payload = decodeAccessTokenPayload(result.accessToken);
  // payload.sub, payload.name をセッション等に保存
});

構成

src/clients/v1/
  BaseServerClient.ts   # X-Server-Secret 付き HTTP
  AuthClient.ts         # POST /v1/auth/refresh, /v1/auth/logout
  UsersClient.ts        # users 一覧・詳細・role / users/me（name, icon, password, mail, delete, credentials）
  LoginLogClient.ts     # GET /v1/login-log
  EnrollClient.ts       # POST /v1/auth/enroll/{google,github,line}
  SignupClient.ts       # POST /v1/auth/signup/{provider}/url
  CalendarClient.ts     # GET/POST/PUT/DELETE Google カレンダー API
  ServerClient.ts       # facade
src/callback/           # ログインコールバック body パーサー
src/google/             # buildGoogleLoginUrl
src/github/             # buildGithubLoginUrl
src/line/               # buildLineLoginUrl
src/mail/               # buildMailSignupPageUrl
src/webhook/            # parseWebhookPayload

対象外 API

以下は server-lib の対象外です（ブラウザ向け / DB-TECH 内部処理 / 管理画面専用）。

| 種別 | 例 | | :-- | :-- | | ブラウザ OAuth コールバック | /auth/callback/* | | フロント向け login / signup 実行 | GET/POST /v1/auth/login/*, GET/POST /v1/auth/signup/* | | apiToken 発行 | POST /v1/token | | お問い合わせ | POST /v1/contact | | 管理画面 API | /admin/* |

環境

| isStage | API | | :-- | :-- | | true | https://stage.d-b-tech.uk | | false / 未指定 | https://d-b-tech.uk |

注意

• サーバー（Node.js 等）からの利用を想定しています。X-Server-Secret をフロントに渡さないでください
• refresh / logout 呼び出し時に Origin ヘッダーを付けないでください（付いていると 403）
• refresh 成功後は必ず新しい refreshToken に差し替えて保存してください（ローテーション）