OpenWork MCP Gateway

Den API

Hono ベースの Den コントロールプレーン実装（den-api、旧称 den-controller）です。

このパッケージは、現在使用されている Den コントロールプレーン実装です。

Den API のルート一式をフォルダー分けした Hono 構成に移行しており、サービス全体を調べなくても、エージェントが一度に 1 つの領域を確認できます。

クイックスタート

pnpm --filter @openwork-ee/den-api dev:local

ローカルデモ組織のシード

ローカルの Den MySQL データベースが稼働している状態で、デモ組織をシードします。

pnpm --filter @openwork-ee/den-api seed:demo-org

これにより、デモユーザー、チーム、保留中の招待、およびインポート済みの Anthropic Knowledge Work Plugins マーケットプレイスを含む Acme Robotics が作成されます。この機能は OPENWORK_DEV_MODE=1 で保護されており、デフォルトではローカルの Den DB URL を使用します。また、ワーカーや有効な外部インテグレーションは作成しません。

デフォルトのオーナーログイン：[email protected] / OpenWorkDemo123!。

オブザーバビリティ

DEN_OBSERVABILITY_BACKEND でバックエンドを 1 つ選択します：none、otel、または sentry。

• none（デフォルト）：構造化 JSON ログを stdout に出力します。
• otel：Hono／DB のインポート前に OpenTelemetry Node SDK を初期化し、標準の OTEL_* 変数から OTLP HTTP/protobuf 形式でトレース、メトリクス、ログをエクスポートします。また、インバウンド HTTP の自動計装を使わずに、正規化されたリクエストスパン／メトリクスに @hono/otel を使用します。
• sentry：アプリのインポート前に @sentry/hono/node を初期化し、エラー、トレース、Sentry Logs に公式の Hono ミドルウェアを使用します。OTEL バックエンドと併用しないでください。

リクエストアクセスログには、リクエスト ID、メソッド、正規化されたルート、ステータス、所要時間、およびリクエストが発行したデータベースステートメント数（db_queries。件数のみ）が記録されます。ヘルスチェック／レディネスチェックのログは除外されます。ヘルスチェック／レディネスチェックのリクエストでは、den-api の Hono オブザーバビリティミドルウェアもスキップされます。アプリのテレメトリでは、Authorization、Cookie、本文、クエリの値が秘匿されます。OTEL_SERVICE_NAME を設定すると、デフォルトのサービス名 den-api を上書きできます。Daytona 独自の OTEL ブートストラップは無効のままにしてください。den-api から Daytona の OTEL 有効化変数を設定しないでください。

ビルド時にソースマップが生成されます。Sentry のソースマップは、DEN_OBSERVABILITY_BACKEND=sentry で、SENTRY_AUTH_TOKEN、SENTRY_ORG、SENTRY_PROJECT、SENTRY_RELEASE がすべて設定されている場合にのみアップロードされます。SENTRY_DIST が設定されている場合は、その値も引き継がれます。認証トークンはシークレットストレージに保管し、環境変数の例やログには決して書き込まないでください。

承認済み Web オリジン

組織のオーナーと管理者は、Den ダッシュボードの 組織設定 → 承認済み Web オリジン（/v1/org/web-origins）で、セルフホストの OpenWork Web インスタンスを承認します。各エントリは正確な HTTPS オリジンです。スキーム、ホスト、および任意のポートで構成され、パス、クエリ、フラグメント、認証情報、ワイルドカードは使用できません。1 つの組織で最大 20 件まで承認できます。承認済みオリジンは、その組織が有効な間に限り、/signin への Web サインインの引き継ぎ先として使用できます。また、Den API への認証情報付きブラウザーリクエストにも使用できます。引き継ぎの承認はリクエストごとに確認されます。CORS の承認はプロセスごとにキャッシュされ、すべての Den API レプリカで約 30 秒以内に反映されます。DEN_CORS_HANDLED_BY_EDGE=true の場合、エッジ側でも同じ正確なオリジンと Authorization のプリフライトを許可する必要があります。

現在のルート

• GET / -> 302 https://openworklabs.com
• GET /health
• Better Auth のマウント先：/api/auth/*
• デスクトップの引き継ぎルート：/v1/auth/*
• 現在のユーザーのルート：/v1/me*
• 組織のルート：/v1/orgs*
• アクティブな組織の SCIM 管理ルート：/v1/scim*
• 管理者ルート：/v1/admin*
• ワーカーの一覧表示、削除、アクティビティのハートビートルート：/v1/workers*（OpenWork Web インスタンスはワーカーの行として扱われます。そのライフサイクルは /v1/cloud/* で管理されます）

フォルダーマップ

• src/routes/auth/：Better Auth のマウントとデスクトップへの引き継ぎエンドポイント
• src/routes/me/：現在のユーザーと、現在のユーザーの組織を解決するルート
• src/routes/org/：組織の CRUD に関する機能。領域ごとに分割されています
• src/routes/admin/：管理者専用のレポートエンドポイント
• src/routes/workers/：ワーカーの一覧表示、削除、アクティビティのハートビートエンドポイント
• src/middleware/：認証コンテキスト、組織コンテキスト、チーム、バリデーション用の再利用可能な Hono ミドルウェア
• src/cache.ts：Redis を利用した共有の読み取りキャッシュ。負荷の高い読み取りヘルパーはここに追加し、cache:${cacheParent}:${cacheChild}:${id} をキーとして使用します。例：cache.auth.session(token)、cache.org.members(orgId)。Redis は任意のため、すべてのヘルパーで DB ローダーにフォールバックする必要があります。

各主要フォルダーには個別の README.md もあり、今後のエージェントが領域ごとに確認できます。

共有クエリキャッシュ

Den API の読み取りキャッシュには src/cache.ts を使用してください。ルートハンドラーやドメインモジュールに場当たり的な Redis 呼び出しを作成しないでください。

現在公開されているヘルパー：

const session = await cache.auth.session(token)
const members = await cache.org.members(orgId)

キャッシュキーの形式：

cache:${cacheParent}:${cacheChild}:${id}

キーの例：

cache:auth:session:<token>
cache:org:members:org_...

キャッシュヘルパーを追加する際のルール：

• src/cache.ts のエクスポートされた cache 名前空間にヘルパーを追加してください。
• 各ヘルパーは読み取りキャッシュ関数としてください。Redis を確認し、キャッシュミス時に DB ローダーを実行して Redis に書き込み、その後、読み込んだ値を返します。
• Redis は任意です。DATABASE_REDIS_URL が未設定でもヘルパーが動作する必要があります。
• ローカル以外の Redis では rediss:// を使用してください。redis:// エンドポイントがプライベートかつ非公開で、信頼できる内部ネットワークに制限されている場合に限り、DATABASE_REDIS_ALLOW_INSECURE_INTERNAL=1 を設定してください。
• 無効化が明示され、テストされていない限り、TTL は短くしてください。
• 認証セッションの正本は DB とし、キャッシュ期間は最大 1 時間とします。セッションの削除、または ID を変更する更新を行う場合は、cache.auth.deleteSession(token) を無効化する必要があります。
• 明示的な無効化処理とテストなしに、セキュリティ上重要な新しいキャッシュヘルパーを追加しないでください。
• cache.auth.session(token) や cache.org.members(orgId) のように、ドメインの呼び出しとして読める名前を優先してください。

SCIM による既存ユーザーの引き継ぎ

src/auth.ts の SCIM プラグインは、既存アカウントを引き継ぐ前に、コネクターの組織への既存のメンバーシップを必要とします。また、その shouldLinkUser コールバックでは、正規化されたユーザー ID と組織 ID、および removed_at IS NULL を条件とする、キャッシュを介さないメンバーシップの読み取りも行います。Better Auth 1.7.0-beta.10 に組み込まれているメンバーシップ検索は削除済みの行を除外しないため、両方のチェックを有効にしておく必要があります。参加済みユーザーがいない招待、削除済みのメンバーシップ、別の組織に属するアカウント、組織のないトークンでは、引き継ぎを許可できません。メールドメインによる例外はありません。引き継ぎが成功すると、ユーザー ID とメンバーシップのロールが維持されます。新規ユーザーのプロビジョニング経路に変更はありません。

プラグインはアカウント作成トランザクションの前にこのポリシーを評価します。最新の読み取りでは、すでに削除されたメンバーシップを除外しますが、同時に行われる削除とリンク処理は直列化されません。この競合を解消するには、プラグインでトランザクションを考慮したポリシーのサポートが必要です。このコールバックは、アトミックなメンバーシップロックではありません。

インストール済みプラグインの回帰テストスイートは、独立した Node プロセスで実行してください。

pnpm --filter @openwork-ee/den-api test:scim-existing-user-linking

このテストでは Better Auth のメモリーアダプターを使用し、実行はせずにメンバーシップ SQL をコンパイルします。Den の認証関連モジュール全体はインポートせず、MySQL の起動、OAuth の設定、実際の認証情報も必要ありません。

TypeID のバリデーション

• Den 共通の TypeID バリデーションは ee/packages/utils/src/typeid.ts にあります。
• エンドポイントが Den TypeID を受け付ける、または返す場合は、typeId.schema("...") か、normalizeDenTypeId("...", value) のような互換性ヘルパーを使用してください。
• ee/apps/den-api/src/openapi.ts は denTypeIdSchema(...) を公開しており、パスパラメーター、リクエスト本文、レスポンスフィールドで同じバリデーションルールと Swagger の例を共有できます。
• Swagger では、Den ID に必須のプレフィックスと固定長 26 文字の TypeID サフィックスが記載されるようになりました。無効な ID はルートロジックの実行前にリクエストのバリデーションでエラーになります。

OpenAPI コントラクト

• packages/docs/openapi.json は、pnpm den:contract で生成され、pnpm api:lint でリントされる無視対象のビルド成果物です。CI はソースから OpenAPI／SDK を生成し、生成エラーや型エラー、Spectral のエラー、または .spectral-baseline.json を超える警告がある場合に失敗します。ホスト型ドキュメントは、同じ正規化済み公開コントラクトを /openapi.json?public=1 から読み込みます。.github/workflows/refresh-api-docs.yml は、本番環境でコントラクトの変更が反映された後に、ドキュメントを再ビルドします。
• 各ルートの登録には、summary、tags、security、responses を含む describeRoute() が付随します。規約と文書化された例外については、docs/api-style.md を参照してください。

移行方針

1. Den のコントロールプレーンの動作に関する信頼できる唯一の情報源として、den-api（旧 den-controller）を維持します。
2. 一度に 1 つのサーフェスに絞り、Hono のルートグループにエンドポイントを追加します。
3. リクエスト／セッション／組織まわりの処理を重複させず、共有ミドルウェアと Zod バリデーターを再利用します。
4. 構成を変更した場合は、後続のエージェントがすばやく経緯を把握できるよう、各ルート領域に短い README を残します。