Zeroword Docs

CLI#

@auth-platform/cli は Management API によるリソース設定と、React Native / Expo アプリの初期設定を行う。各環境の統合概要は 概要、リソースと ID は概念、API キーと権限はManagement APIを参照する。

起動と共通オプション#

実行ファイル名は auth-platform である。インストール方法は配布環境に従う。auth-platform --help と auth-platform <command> --help はそのバージョンのコマンド構文を表示する。

オプション 説明
--json 結果を整形済み JSON で出力する。
--api-key <key> Management API キー。認証の優先順位はこのフラグ、AUTH_PLATFORM_API_KEY、保存済み資格情報の順。シェル履歴やプロセス一覧への露出を避けるため、通常は環境変数を使う。
--base-url <url> Management API のベース URL。優先順位はこのフラグ、AUTH_PLATFORM_BASE_URL、保存済み URL、既定値の順。
-V, --version CLI バージョンを表示する。
-h, --help ヘルプを表示する。

既定のベース URL は実サービスの Management API https://api.zeroword.smartcrab.ai/v1 である。別の URL を使う場合だけ AUTH_PLATFORM_BASE_URL または --base-url で上書きする。

export AUTH_PLATFORM_API_KEY='<Management API key>'
auth-platform login

認証とローカル設定#

login は API キーを Management API で検証して保存する。フラグ、AUTH_PLATFORM_API_KEY、TTY 上の対話プロンプトの順にキーを解決する。キーは表示しない。対話入力もなくキーが解決できない場合は usage error となる。検証後、credentials.json に API キーと既定値以外の base_url を保存する。

環境変数 用途
AUTH_PLATFORM_CONFIG_DIR CLI 設定ディレクトリを直接指定する。
XDG_CONFIG_HOME AUTH_PLATFORM_CONFIG_DIR が空の場合、$XDG_CONFIG_HOME/auth-platform を使う。
HOME 上記がない場合のホームディレクトリ。既定の保存先は ~/.config/auth-platform。
AUTH_PLATFORM_API_KEY Management API キー。
AUTH_PLATFORM_BASE_URL Management API のベース URL。
APPLE_TEAM_ID react-native configure が iOS Team ID を対話なしで解決する。

資格情報は <設定ディレクトリ>/credentials.json に JSON 形式で保存する。設定ディレクトリは新規作成時に mode 0700、資格情報ファイルは mode 0600 にする。形式は {"api_key":"<key>"} で、既定以外の base URL を使った場合だけ "base_url":"<url>" が加わる。CI ではフラグではなく AUTH_PLATFORM_API_KEY を使う。

init は実行したプロジェクトディレクトリに auth-platform.json を書き、workspace / project / environment ID と issuer を保存する。このファイルに資格情報は含まれず、CLI は verify の issuer / environment と react-native configure の issuer / environment を既定値として読む。公開識別子のみを含むため、コミットできる。

コマンド#

グローバルオプション --json、--api-key、--base-url は各サブコマンドでも利用できる。

init#

workspace → project → environment を名前で検索し、見つからないものを作成して auth-platform.json にリンクを書く。

オプション 説明
--workspace-name <name> workspace 名。既定値 Default。
--project-name <name> project 名。既定値 Default。
--environment-name <name> environment 名。既定値 development。
--type <type> test または production。既定値 test。
--force 既存リンクがあっても処理する。既存リソースを削除せず、同名の workspace / project / environment は再利用する。

同名検索は workspace と project が名前、environment が名前と type の一致で行われる。現行 Management API の POST /workspaces は Dashboard セッションを要求し、API キーによる workspace 作成は 401 Unauthorized となる。そのため API キーで使う前に Dashboard で workspace を用意すること。既存 workspace が見つかる場合、init はその workspace 内に project / environment を作成できる。

login#

追加のコマンド固有オプションはない。共通の --api-key、--base-url または AUTH_PLATFORM_API_KEY、AUTH_PLATFORM_BASE_URL を使う。キーを Management API の GET /workspaces?limit=1 で検証してから保存する。403 insufficient_scope はキー自体が有効である証明として扱い保存するが、workspace 読み取り権限がない旨を知らせる。

workspace create#

オプション 説明
--name <name> 必須。workspace 名。
--slug <slug> 省略可能な URL-safe slug。省略時は名前から生成される。

workspace を新規作成する。現行 Management API の作成ルートは Dashboard セッション認証のみを受け付けるため、Management API キーでは 401 Unauthorized になる。CLI に Dashboard ログイン機能はない。API キーで project / environment を設定する場合は、Dashboard で workspace を先に作成する。

project create#

オプション 説明
--workspace-id <id> 必須。workspace ID。
--name <name> 必須。project 名。
--slug <slug> 省略可能な URL-safe slug。省略時は名前から生成される。

env create#

オプション 説明
--project-id <id> 必須。project ID。
--type <type> 必須。test または production。
--name <name> 必須。environment 名。

issuer は API が生成する。

env rp-migration と env disable-legacy-rp#

コマンド オプション 説明
env rp-migration --environment-id <id> 必須。WebAuthn RP ID 移行状況を表示する。
env disable-legacy-rp --environment-id <id> 必須。対象 environment。
env disable-legacy-rp --confirm-rp-id <rp> 必須。legacy RP ID を正確に入力する確認値。

disable-legacy-rp は取り消しできない操作であり、legacy RP ID での passkey 認証を停止する。実行前に移行状況と対象 RP ID を確認する。

client create#

オプション 説明
--environment-id <id> 必須。environment ID。
--type <type> 必須。web_bff、web_spa、react_native のいずれか。
--name <name> 必須。クライアント名。
--redirect-uri <uri> redirect URI。繰り返し指定できる。
--post-logout-redirect-uri <uri> post-logout redirect URI。繰り返し指定できる。
--allowed-origin <origin> allowed origin。繰り返し指定できる。
--scope <scope> allowed scope。繰り返し指定できる。
--resource <url> allowed resource。繰り返し指定できる。
--token-endpoint-auth-method <method> none、client_secret_basic、client_secret_post。web_bff の既定値は client_secret_basic、web_spa / react_native の既定値は none。指定すれば既定値を上書きする。
--no-pkce Client の require_pkce を false で登録する。Authorization Server は require_pkce にかかわらず全 Client に PKCE S256 を要求するため、通常は指定しない。

confidential client の client_secret は作成成功時に一度だけ出力され、CLI は保存しない。--json 出力にも含まれるため、出力先を保護して直ちに秘密管理システムへ保存する。

react-native configure#

Expo アプリ設定を冪等に更新する。--dry-run は存在しない。app.json / app.config.json は読み書きし、app.config.ts / .js / .mjs / .cjs は npx --no-install expo config --json で評価するが、動的設定ファイルは自動編集できない。動的設定では scheme と Config Plugin を手動設定する。

オプション 説明
--project-dir <dir> Expo アプリディレクトリ。既定値は現在のディレクトリ。
--client-id <id> platform client ID。省略時は auth-platform.json の client_id を使う。init はこの値を記録しないため、通常は指定する。Config Plugin 登録に必要。
--environment-id <id> issuer / RP domain 解決用 environment ID。省略時は auth-platform.json を参照する。
--issuer <url> issuer URL を明示して解決値を上書きする。
--rp-domain <host> RP / Universal Link domain を明示して解決値を上書きする。
--scheme <scheme> URL scheme。既定値は既存の scheme、iOS bundle ID、Android package の順で解決する。reverse-DNS 形式を使う。
--ios-team-id <id> Apple Team ID。未指定時は APPLE_TEAM_ID、TTY での入力の順に解決する。
--keystore <path> Android keystore。既定値は <project-dir>/android/app/debug.keystore。
--keystore-alias <alias> カスタム keystore の alias。
--keystore-storepass <pass> カスタム keystore の store password。
--keystore-keypass <pass> カスタム keystore の key password。
--callback-path <path> OAuth callback path。既定値 oauth/callback。

Config Plugin の登録には --client-id と RP domain が必要である。Management API で client の mobile app 情報と不足している callback URI を更新する。AASA / assetlinks.json を確認し、.env に EXPO_PUBLIC_AUTH_ISSUER、EXPO_PUBLIC_AUTH_CLIENT_ID、EXPO_PUBLIC_AUTH_REDIRECT_URI を書き、app/login.tsx がなければサンプルを生成する。一部の初期手順が失敗すると後続手順は skip される。いずれかの手順が失敗すれば終了コード 1 になる。keystore password をコマンドライン引数へ置かない。

domain add と domain update#

コマンド オプション 説明
domain add --environment-id <id> 必須。environment ID。
domain add --hostname <host> 必須。登録する custom hostname。
domain add --rp-enabled 指定時、その domain を WebAuthn RP ID host としても有効化する。省略時は無効。
domain update --domain-id <id> 必須。custom domain ID。
domain update --rp-enabled <true|false> 必須。RP domain として使用するかを明示する。

domain add の後は表示された案内に従って Cloudflare for SaaS 向け DNS を設定する。domain update で有効化しても、domain が active になるまで RP ID / Hosted Login domain は切り替わらない。

provider configure#

オプション 説明
--environment-id <id> 必須。environment ID。
--provider <provider> 必須。google、apple、github、microsoft、generic_oidc のいずれか。
--mode <mode> 必須。managed または byo。
--provider-key <key> 同一 provider の複数接続を区別する値。既定値は provider 名。
--client-id <id> 必須。上流 OAuth provider の client ID。
--client-secret <secret> 上流 OAuth provider の client secret。省略時は TTY で入力を促し、非対話では必須。argv に秘密を渡さず、対話入力を使う。
--issuer <url> Generic OIDC issuer。generic_oidc では必須。
--scope <scope> 上流 OAuth scope。繰り返し指定できる。既定値は空。

成功時、provider に登録する callback URI を表示する。managed は canonical issuer、byo は environment interaction domain を使う。

verify#

environment の事前確認を実行する。--environment-id / --issuer は auth-platform.json の値で補完できる。Management API キーがない場合、API を必要とする確認は skip し、指定された public URL の確認だけを行う。

オプション 説明
--issuer <url> OIDC issuer URL。
--environment-id <id> issuer / RP domain の解決に使う environment ID。
--client-id <id> redirect URI、AASA、assetlinks 確認用 client ID。
--rp-domain <host> AASA / assetlinks 確認用 RP domain。
--custom-domain <host> TLS 証明書確認用 custom domain。
--email-domain <host> Email Sending の MX / SPF / DKIM 確認用 domain。

確認項目は issuer discovery、JWKS、redirect URI、AASA、assetlinks、custom domain TLS、Email Sending DNS、social provider callback / Generic OIDC discovery、MAU billing である。各項目は pass / fail / skip を返し、skip は失敗として数えない。fail が 1 つ以上あれば終了コード 1 となる。

verify の Management API 操作は environment / client / connection / usage の読み取りであり、すべて GET である。issuer、JWKS、AASA、assetlinks、callback の HTTP 確認も GET を使い、redirect は追跡しない。custom domain は TLS 証明書、email domain は DNS を読み取る。verify は Management API のリソースを書き換えない。

出力と終了コード#

通常は結果を人間向けの行として stdout に、失敗を stderr に出力する。--json は成功データを整形済み JSON として stdout に、コマンド実行時の失敗を {"error": ...} として stderr に出力する。引数解析で検出する構文エラーや必須オプション不足は --json の有無にかかわらず通常のテキストで stderr に出る。verify は stdout の checks 配列と failed 数を返し、失敗時はさらに stderr に型付き error を出す。

終了コード 意味
0 成功。--help / --version 表示も含む。
1 API / I/O / process / verify などの実行時失敗。
2 CLI 構文エラー、必須オプション不足などの usage error。

API 失敗は human 出力では error[api_failure] と HTTP status / error code / request ID、JSON 出力では型付き error object として表示される。Management API key と provider secret はエラー表示で redaction される。

プラットフォーム運用者向けコマンド#

以下の操作はプラットフォーム運用者向けであり、アプリの開発者は使う必要がない。dev [--app <name>] は platform repository の pnpm dev を実行し、--app を指定すると対象 package の dev script を実行する。deploy [--env <name>] は各 Worker を順に deploy する。production では各 app の production 用設定を使い、それ以外は指定した環境名を使う。AUTH_PLATFORM_REPO_ROOT は platform repository root を上書きする (既定値: 現在の作業ディレクトリ)。

verify の Cloudflare Queue / DLQ と D1 migration の確認も運用者向けである。Queue / DLQ 確認には CLOUDFLARE_ACCOUNT_ID と CLOUDFLARE_API_TOKEN が必要である。D1 確認では --migrations-dir <dir> (既定値 ./migrations) で migration root を指定し、wrangler d1 migrations list を使う。