make-app-auth

make-app-auth

禁止されたページや 403 ハンドラーを変更する前に、references/access-help.md を読んでください。拒否ペイロードとスコープを保持してください。現在の App 管理者向けヘルプを独立して提供しても、業務アクセスが許可されるわけではありません。React のフィードバックでは、makeui/references/permission-feedback.md に記載された検証済みパッケージを使用してください。認証処理で拒否ページをレンダリングしたり、スタイルを設定したりすることはありません。

管理者の検索は、段階的なリリースにおける任意の拡張機能です。SDK メソッドが存在しない場合やエンドポイントがデプロイされていない場合は、ログインや App の準備状態に関するエラーではなく、一般的な認可ガイダンスを維持してください。既存の認証／IAM 要件は引き続き適用されます。

起動時の拒否判定と業務リクエストの拒否判定は分離してください。auth.init() が status: 'forbidden' を返した場合、payload.reason がなくても App エントリーのフィードバックをレンダリングします。request-adapter.md の業務リクエスト判定器を、追加のブートストラップゲートとして再利用してはいけません。references/sdk-integration.md#startup-shape を参照してください。

Make App の認証と、認証済み Make API へのアクセスには、このスキルを使用してください。

スコープ

このスキルでは、以下を扱います。

• @qfeius/make-app-auth SDK の統合
• 生成／公開された Make App のデフォルト認証モードとしての統合ログイン
• 統合ログイン、OAuth、SSO、ngrok、Cookie、ログアウト、コールバックのテスト
• Make ゲートウェイ /api/make/** への認証済み直接リクエスト
• デプロイされた App Service プレフィックス配下での、Service 経由の公開済み App 認証（通常は /api/make/auth/**）
• 401、403、ログアウトの動作
• アカウント画面に必要な、現在のコンテキストの ID 正規化とホストランタイムシグナル
• Cookie、セッション、リダイレクト、コールバックのトラブルシューティング

このスキルでは、以下を扱いません。

• UI レイアウト、コンポーネント設計、Make App のページ構成。makeui を使用してください。
• Service のビルド出力、パッケージング、イメージのエントリーポイント、公開時のランタイム準備状態。make-app-runtime を使用してください。
• ランタイムスキーマの正規化、オブジェクトフィールドのマッピング、テーブルのレンダリング、空白ページの診断、業務データの正確性。makeui とホストアプリのテストを使用してください。
• DSL のモデリングや Make リソースの定義。makedsl を使用してください。
• makecli コマンドの実行。makecli を使用してください。
• make-gateway または Org サーバーの実装変更。
• 単一 App の権限適用。make-app-permission を使用してください。

デフォルトの動作

生成および公開される Make App では、unifiedLogin: true、apiAuthRedirect: true、auth.init({ redirect: true }) を使用した統合ログインをデフォルトとします。

このスキルでサポートするのは、生成およびレビュー対象の Make App における統合ログインのみです。統合ログインの前提条件が満たされていない場合はブロッカーとして扱い、別のモードに切り替える理由にしてはいけません。このスキルから、ブラウザートークンモード、モックモード、ログインを回避する方法を生成してはいけません。

ローカルプレビューの例外：Service 経由の App では、MAKE_APP_LOCAL_PREVIEW=true で保護された、Service 専用のローカルプレビューアダプターを提供できます。このフラグは、MAKE_APP_LOCAL_PREVIEW=true corepack pnpm run dev やプロジェクト管理の dev:preview スクリプトなど、ローカル開発コマンドから一時的なプロセス環境変数として設定する場合に限り有効にしてください。新しい Make App と明示的なランタイム移行では、make-app-runtime のベースライン（Node.js 22.20.0、Corepack 0.34.0、および Corepack 経由の [email protected]）を使用してください。既存の App では、認証作業中も宣言済みのランタイムを維持してください。このフラグを .env、.env.local、.env.example、生成される README のセットアップ手順、デプロイ環境に保存してはいけません。アダプターは makecli configure resolve --target local-preview --output=json を使用して実効的な公開 Make オリジンを解決し、make_api_origin を取得して、ブラウザー向けの /api/make スコープを追加し、Service から Make へのリクエストにのみトークンを付与してください。UI にトークンを公開してはいけません。公開時の統合ログインの契約を変更してはいけません。また、本番環境ではフェイルクローズにしてください。

厳守事項

• 必ず @qfeius/make-app-auth を使用し、認証実装を別途フォークしないでください。
• Make バックエンドへのゲートウェイ直通のビジネスリクエストは、/api/make/** 配下で auth.api を経由する必要があります。
• 通常のフロントエンドからの Make バックエンドリクエストは、スキーマ／メタデータ、レコードの CRUD、通常のファイル／ルックアップ／ユーザー／部署のリクエストを含め、auth.api を経由します。固定された Make App AI v1 の /client コントラクトは限定的な例外です。この AuthenticatedTransport には、202／204、SSE、ファイルのバイトデータに対応する HTTP ステータス、ヘッダー、未加工の AsyncIterable<Uint8Array> が必要ですが、auth.api ではこれらを公開していません。このブリッジは共有認証アダプター内の同一オリジン /api/make/app/ai/v1/** に限って実装し、統合ログインの Cookie 処理を維持したうえで、正確な適用範囲とライフサイクルについては make-ai-assistant に従ってください。これは、他の /api/make/** 呼び出しに汎用の raw fetch を使うことを許可するものではありません。
• 生成する App では、Make バックエンドへのアクセスを auth.api でラップする共有 API アダプターまたはデータソース層に集約する必要があります。
• 新しい Make App の共有認証ビジネスリクエストアダプターでは、make-app-observability の Trace ID コントラクトを適用する必要があります。トークンを公開したり、統合ログインの動作を変更したりせずに、traceparent と対応する X-Log-Id を送信してください。認証の管理はここが担い、Trace の生成、伝播、エラー表示は make-app-observability が担います。
• Service 経由の App では、UI -> Service -> make-gateway のコントラクトを維持してください。UI からメタデータ／データ呼び出しを迂回してはいけません。
• Service 経由の App では、既定の権限呼び出しについてもこのコントラクトを維持してください。UI は auth.api("/app/principal/permission") を使用し、シングル App の権限動作は make-app-permission が担います。
• Service 経由で公開する App の UI では、gatewayBaseUrl: "/api/make" を使用します。UI が auth.api("/app/**") を呼び出すと、ブラウザーからのリクエストは /api/make/app/** になります。認証の初期化と OAuth コールバックは /api/make/auth/** および /api/make/oauth/** 配下に維持してください。このモードで /api/auth/**、/api/oauth/**、または gatewayBaseUrl: "/api" を生成してはいけません。
• UI コンポーネントや通常の Make ビジネス API で、window.fetch('/api/make/...') を直接あちこちに記述しないでください。上記の AI v1 AuthenticatedTransport ブリッジだけが、レスポンスを直接扱う唯一の例外です。任意のオリジン／スコープは拒否し、App コードからブラウザーのトークンや Cookie を読み取ってはいけません。
• Authorization を手動で記述しないでください。
• <img src>、<object data>、通常の <a href> などのブラウザーリソースリクエストでは、カスタムの Authorization ヘッダーを付加できません。Make ファイルのダウンロードにベアラートークンが必要な場合、UI は同一オリジンの Service ダウンロードプロキシ URL を使用し、Service はデプロイ時に注入されたダウンロードトークンを使用する前に、現在の App セッションを検証する必要があります。
• gatewayBaseUrl は Make バックエンド API のベース URL を指定する SDK オプションです。同じ URL について別の環境概念を作成するのではなく、まずホストの Make バックエンド設定を再利用してください。ローカルプレビューでは、makecli configure resolve --target local-preview --output=json とその make_api_origin フィールドの使用を優先してください。
• gatewayBaseUrl は統合ログインやアカウントセンターの URL ではありません。同一オリジンのゲートウェイ直通 App と、Service 経由で公開する App のどちらにも /api/make を優先して使用してください。両者の違いは、UI のビジネス呼び出しが /data/** などの Make バックエンド直通パスを使うか、/app/** などの Service 管理パスを使うかです。
• 生成する App コードで、統合ログイン、Org、アカウントセンターの URL を設定またはハードコードしないでください。これらの URL は make-gateway が返します。
• App コードで zs_session または make_app_session を読み取り、書き込み、永続化、削除してはいけません。
• 生成する App コードで、Org OAuth URL、redirect_uri、state、code_challenge、トークン交換、Org ログアウト URL を組み立ててはいけません。
• ブラウザーコードから ~/.make/credentials を読み取ることはできません。
• ブラウザー側で unifiedLogin: false、accessToken、token、tokenProvider、ローカル認証情報の読み込み、VITE_MAKE_AUTH_MODE=token、またはそれに相当するトークンモード切り替えを生成してはいけません。
• Service 専用のローカルプレビューでは、一時的なプロセスレベルの MAKE_APP_LOCAL_PREVIEW=true が設定されている場合に限り、makecli の認証情報を使用できます。このフラグを env ファイルや生成するドキュメントに永続化しないでください。ローカルプレビューでは makecli configure resolve --target local-preview --output=json を使用して make_api_origin + /api/make を呼び出し、公開ランタイムでは k8s 内部ゲートウェイを /make 付きで呼び出す必要があります。current-context／runtime-view は明示的なプレビュー応答にし、ルート照合では return_url などのクエリ文字列を無視し、ビジネスリクエストにトークンを付加するのは Service 内に限ってください。
• ローカルプレビューの認証ルートで、公開時の認証プロキシルートを覆い隠してはいけません。公開ランタイムでは、/api/make/auth/current-context と /api/make/auth/runtime-view は認証名前空間プロキシ経由で make-gateway に到達する必要があり、localPreview、local-preview-user、authMode: "token"、その他のプレビューコンテキストを返してはいけません。
• 認証の current-context を利用する Service は、Meta／Data エンベロープパーサーではなく、references/service-fronted-mode.md#current-context-consumption に従ってください。認証名前空間プロキシは透過的なままにしてください。
• ローカル OAuth の前提条件が欠けていることを理由に、生成する App の認証方式を統合ログインから黙って切り替えてはいけません。阻害要因を報告してください。
• 公開／ログインの準備完了を報告する前に、エージェントまたはプラットフォームのチェックで認証経路を検証してください。ドメインアクセス、DevTools、k8s のログ、Cookie の確認を、ユーザーだけが実行する検証手順として残してはいけません。
• Service 経由の App では、/api/make/auth/** と /api/make/oauth/** は、公開 App の Service プレフィックス配下に必要な名前空間レベルの Service プロキシコントラクトです。任意の便利なルートや、エンドポイントごとの許可リストではありません。
• Service 経由の Make App ではすべて、既定の /api/make/app/principal/permission ルートが確立済みのブラウザーセッションコンテキストを受け取るようにする必要があります。
• 認証準備を整えるために、広範な /api/make/** のパススルーを追加してはいけません。既定で透過的な名前空間は auth／oauth のみです。Service が管理するビジネスリクエストは明示的な /api/make/app/** ルート配下に置き、不明な /api/make/** パスはデフォルトで拒否してください。
• Service 経由の App では、Service がすべての make-gateway 呼び出しで App のホストコンテキストを維持する必要があります。受信した Host から X-Forwarded-Host を導出し、クライアントが指定した X-Forwarded-Host を信頼せず、X-Forwarded-Proto を追加し、認証とビジネスプロキシのリクエストで同じヘルパーを共有してください。
• 認証済みの current-context 応答から、name、avatar、tenantName を含む表示用 ID 情報を維持してください。ただし、サーバー側の認可では信頼できない情報として扱ってください。モバイルのアカウントドロワーは、この正規化された ID 情報を makeui 経由で使用します。デスクトップ UI に tenantName が表示されないことだけを理由に破棄してはいけません。
• 生成する認証 App のシェルでは、現在のユーザーメニューまたはホスト既定のアカウント領域に、auth.logout() を呼び出すログアウト操作を用意する必要があります。表示 UI は makeui が担い、この Skill は認証ハンドラーとログアウト動作を担います。標準の例外は、検出された Feishu コンテナです。この場合、モバイルのアカウント UI ではログアウトの項目を非表示にしますが、認証ハンドラーを削除または置き換えてはいけません。Cookie の消去、Org URL の書き換え、無関係なページ上の操作によってログアウトを非表示にする動作を実現してはいけません。
• Feishu コンテナの検出は、純粋関数でテスト済みのホストヘルパーに集約してください。既存のホスト／ランタイムシグナルを優先し、それがない場合は window.lark、window.feishu、window.LarkJSBridge を確認してください。その後のフォールバックとしてのみ、大文字小文字を区別しない Lark|Feishu のユーザーエージェント照合を使用してください。tenantName、デプロイ環境、画面幅、モバイルパッケージからコンテナを推測してはいけません。判定結果の真偽値を makeui のアカウント UI に渡してください。
• 生成する App では、回復可能な統合ログインの有効期限切れに対応する必要があります。SDK の初期化が reason: "state_expired" または reason: "challenge_expired" を返した場合、再ログインを促すメッセージを表示し、ユーザー操作から auth.login({ redirect: true }) を呼び出してください。

公開前ワークフロー

1. 統合ログインを使用します。統合ログインの前提条件が不足している場合は、モードを切り替えるのではなく、阻害要因を報告します。
2. 認証コードを生成または変更する前に、references/sdk-integration.md を読みます。
3. トラブルシューティングでさらに読む必要がある場合を除き、該当するモードのリファレンスを読みます。
   • 既定の統合ログイン：references/unified-login-mode.md
   • 401、403、ログアウト：references/logout-and-401.md
   • インシデント／デバッグ：references/troubleshooting.md
4. アプリで UI と make-gateway の間に Service レイヤーを設けている場合は、references/service-fronted-mode.md を読みます。
5. Make バックエンドリクエストを生成またはレビューする場合は、必ず references/request-adapter.md を読みます。
6. 認証のブートストラップは薄く保ちます。ビジネス機能では、認証の内部実装ではなく、プロジェクトの Make API アダプターと認証状態を使用します。
7. 公開／ログインの準備ができたと主張する前に、認証経路を検証します。現在のコンテキストのルート、統合ログインへのリダイレクト、セッションコールバック、Cookie を保持するビジネスリクエスト、および該当する場合は Service を介した認証プロキシを確認します。
8. プロジェクトツリーを利用できる場合は、生成されたアプリで scripts/audit-auth-contract.mjs <project-root> --published を実行します。アプリに Service レイヤーがある場合は、--mode service-fronted を使用します。
9. 生成コードを変更するときは、変更した認証経路に関するテストを追加または更新します。対象は、未認証のセッション、期限切れのセッション、403、ログアウト、統合ログインへのリダイレクト、コールバックプロキシ、ビジネスリクエストの 401 処理、現在のコンテキストの ID 正規化、通常のブラウザー／Feishu でのアカウント表示です。

リファレンスの選択

• SDK の契約とリクエストラッパー：references/sdk-integration.md
• 共通リクエストアダプターと 401／403 処理：references/request-adapter.md
• 既定の統合ログインモード：references/unified-login-mode.md
• Service を介した統合ログインモード：references/service-fronted-mode.md
• 401、403、ログアウトの動作：references/logout-and-401.md
• 認証インシデントの診断：references/troubleshooting.md
• Service を介したルート形状の最小例：references/service-fronted-node-example.md。references/service-fronted-mode.md を読んだ後にのみ読みます。

決定論的チェック

生成されたアプリのプロジェクトで scripts/audit-auth-contract.mjs を使用し、公開前に契約の不整合を検出します。

node skills/make-app-auth/scripts/audit-auth-contract.mjs <project-root> --published
node skills/make-app-auth/scripts/audit-auth-contract.mjs <project-root> --mode service-fronted --published

この監査の対象は認証です。統合ログインの準備状況、/api/make の直接的な fetch の使用、Service を介した /api/make/auth/** および /api/make/oauth/** の名前空間プロキシの有無、ローカルプレビューでの認証のシャドーイング、広範な /api/make/** パススルーのリスク、明らかな直接ルートと Service ルートの不一致をチェックします。スキーマのレンダリングや UI の空白ページの動作は検証しません。

現在のコンテキストをすでに使用している主要ルートについては、scripts/current-context-conformance-suite.mjs <host-adapter-module> を本番ハンドラーに対して実行します。詳しくは references/service-fronted-mode.md#current-context-consumption を参照してください。他のルートに認証リクエストを追加する必要はありません。

監査の要件：

• token という名前の UI デザインシステムのテーマフィールドは、認証トークンモードではありません。認証設定内のトークンモードのオプション、認証環境の切り替え、ブラウザーの認証情報へのアクセス、または明示的な authMode: "token" の経路のみを指摘します。
• Service の名前空間プロキシは、直接の文字列ルート、定数、.startsWith(...)、または同等の正規表現によるルートマウントとして表現できます。ただし、/api/make/auth/** と /api/make/oauth/** が内部の /make/auth/** と /make/oauth/** にマッピングされている必要があります。
• Cookie の転送には、req.headers.cookie、req.header("cookie")、Fetch の headers.get("cookie")、または同等の受信ヘッダーアダプターを使用できます。
• 監査のヒューリスティクスを変更する場合は、生成されたアプリで見つかった誤検出および見逃しのケースを特に考慮し、scripts/test-audit-auth-contract.mjs のテストを最新の状態に保ちます。

makeui との連携

makeui が Make App のフロントエンドコードを生成または編集する際、認証に関する判断はすべてこのスキルが担当します。makeui は認証結果に応じた UI 状態を設計できますが、OAuth、Cookie、トークン、ログアウト、または /api/make/** リクエストのロジックを独自に作り出してはいけません。

make-app-auth は、ユーザーが認証済みか、未認証か、アクセスを禁止されているか、認証の有効期限が切れているか、または認証プロキシ／コールバックの問題によってブロックされているかを報告します。認証済みの Make リクエストがすでにバックエンドに到達している場合、スキーマ形状の不一致、フィールドの欠落、レンダリングのクラッシュ、画面が真っ白になる問題、またはレコードテーブルの動作を診断してはいけません。