AdDroid は localhost-only / outbound-only で動作するセルフホスト OSS です。 このドキュメントは AdDroid OSS のセキュリティ前提と、OSS リリース衛生を維持するための ルールをまとめます。
| 項目 | 既定値 | 補足 |
|---|---|---|
| Web UI バインドアドレス | 127.0.0.1:3000 |
0.0.0.0 でリッスンしてはならない |
| Web UI 認証 | なし (ローカルプロセスを信頼) | 多人数運用では将来 SSO を検討 |
| GitHub Webhook | 使用しない | merged PR 検知は API ポーリング (ETag-aware) |
| Meta Webhook | 使用しない | レポート / 階層同期は AdDroid からの outbound のみ |
| Slack request URL / event URL | 使用しない | Socket Mode (WebSocket outbound) のみ |
| Public IP | 不要 | inbound 接続は受け付けない |
| 専用ドメイン / SSL 証明書 | 不要 | https:// は要求しない |
| トンネリングサービス (ngrok 等) | 不要 | outbound のみ |
すべての外部統合 (GitHub, Meta, Slack, LLM Provider, Image Provider) は AdDroid 側から outbound で起動します。inbound webhook / 公開 URL を要求する変更は コントラクト違反 であり受け入れません。
.env,.env.local,.env.productionなど.env.example以外の.env*secrets.local.yaml,secrets.local.yml- AdDroid の
~/.addroid/配下のファイル一切 - GitHub OAuth トークン / Personal Access Token
- Meta Access Token / OAuth リフレッシュトークン
- Slack Bot トークン (
xoxb-*) / App-level トークン (xapp-*) / User トークン (xoxp-*) - Codex / OpenAI OAuth トークン / API Key
ENCRYPTION_KEY値- 個人 GitHub アカウント名 / 組織名 / リポジトリ名のハードコード
- 個人パス (例:
/Users/<username>/...) - 特定の
act_<id>/ Slackteam_id/channel_idのハードコード
これらは .gitignore に登録済みです。git add -A を避け、コミット前に
git status で意図しないファイルが含まれないことを確認してください。
すべての外部 provider トークン (GitHub / Meta / Codex / Slack) は Prisma の
oauth_tokens テーブルに 暗号化境界越しで 保存します。
- 暗号化アルゴリズム: AES-256-GCM (
packages/configのgetCryptoBoundary()) - 鍵: 環境変数
ENCRYPTION_KEY(32 byte 以上の base64 / hex / raw)- base64 (44 字, padded) → 32 byte に decode
- hex (64 字) → 32 byte に decode
- raw UTF-8 (>=32 byte) → SHA-256 で 32 byte に派生
- ciphertext 形式:
v1.aes256gcm.<iv-b64>.<tag-b64>.<payload-b64>(各 IV はランダム生成) oauth_tokensの主要列:provider—github/meta/openai/anthropic/slackaccountIdentifier— provider 内のテナント識別子 (例: GitHub login、Meta user id、Slack team_id)accessTokenCiphertext/refreshTokenCiphertextscopes/expiresAt/connectedAt/lastRefreshedAt
- 鍵を
.env*に書く場合も.envまたは.env.localのみ。.env.exampleには placeholder のみ。 - DB スナップショットを共有する場合は
oauth_tokens.access_token_ciphertextごと 共有しても、ENCRYPTION_KEYを共有しなければトークン本体は漏れません。
secrets.local.yaml はユーザーがローカルでのみ参照する補助 secrets ファイルで、
AdDroid runtime は ~/.addroid/secrets.local.yaml を読み取り得ます。
このファイルは .gitignore で除外され、コミット対象外です。packages/config の
readLocalSecrets() / getLocalSecret(dottedKey) 経由で参照し、ファイル mode は
addroid init / ensureSecretsFilePermissions() が 0600 を強制します。
| provider | 取得経路 | 保存場所 |
|---|---|---|
| GitHub | CLI addroid connect github の OAuth Device Flow / Web UI /github の OAuth Code Flow |
oauth_tokens (provider="github") |
| Meta | addroid connect meta または Web UI /accounts の OAuth Code Flow |
oauth_tokens (provider="meta") |
| Codex | ローカル Codex CLI / codex app-server のログイン状態を利用 |
AdDroid には保存しない |
| OpenAI / Anthropic | CLI addroid connect ai の API key 登録 |
oauth_tokens (provider="openai" / "anthropic") |
| Slack | addroid connect slack で Bot/App トークンを暗号化保存 (Socket Mode 接続テスト後) |
oauth_tokens (provider="slack") |
トークンはすべて 平文をプロセス内変数のみで保持し、ログ出力や console.log を
行わない契約です。Web UI / CLI / Slack の sanitize-on-render により、表示直前に
access_token / Bearer / xoxb- / xapp- / xoxp- / sk- プレフィックスを
[REDACTED] に置換します。
+------------------+ plaintext +-------------------+
| addroid CLI | --------------> | packages/config |
| addroid Web | | crypto layer |
| addroid Worker | +-------------------+
+------------------+ |
AES-256-GCM
|
v
+----------------+
| PostgreSQL |
| oauth_tokens |
+----------------+
- 平文トークンはプロセス内変数のみで保持し、ログ出力しない。
- DB に書き込む時点で常に暗号化文字列に変換する。
- 暗号化器は
packages/configのcrypto.tsに集約し、他コードは平文を直接 DB に 書く API を持たない。改ざん検知 (GCM auth tag) はdecryptがCiphertextFormatErrorとして例外で報告し、サイレントに復号成功させない。 - 大きめのバイナリ / テキスト (ops repo クローン、生成画像、ai_run の大きな payload) は
LocalDiskStorage経由で~/.addroid/storage/に置く。書き込み時に常に mode0600を 付与し、相対 key の path-traversal をStoragePathErrorで拒否する。
- 広告配信または予算を変える可能性があるすべての操作は、
Pull Request + 監査ログ (
audit_logs) の二重記録を必須とします。 - Apply (PR merge → PAUSED 作成) と Activate (PAUSED → ACTIVE 遷移) は別の承認境界です。
両者は
approval_recordsの polymorphic targetType で区別され、独立に許可 / 却下できます。 - Zod スキーマ (
packages/ops-schemas) と dry-run plan で以下を必ず拒否します:- 不正な GitOps operation manifest / cron 設定の構造
account.keyパスの不整合- 安全でない予算変更 (既定では 2x 以上を警告、5x 以上をブロック)
- 初期 active キャンペーンの作成
- 入稿ガードの設定は ops repo の
workflows/guards.yamlに保存します。 Web UI/guards、CLI chat、ダッシュボード chat、Slack chat から自然言語でも変更できます。
| actor 値 | 用途 |
|---|---|
addroid |
システム自身 (cron / pg-boss / apply executor) |
user:<github_login> |
ops repo 上の merge 操作 (GitHub merge) |
user:web-ui |
Web UI からの merge / Activate / cron 起動 |
user:cli |
addroid CLI からの操作 (activate 等) |
slack:<user_id> |
Slack /adops 経由の操作 |
ai:<model> |
AI workflow による自動操作 (improvement_pr ほか) |
ops_repo.bootstrapped— ops repo を初めて連携したapply.enqueued— merged PR を検知しexecute_applyを queue に投入apply.blocked_unapproved— merge を検知したが承認 / mode / branch protection で遮断activate.requested/activate.executed— Activate 要求と実行- 実装中の追加 action は
apps/worker/src/lib/audit-store.tsを確認
- Meta Access Token / OAuth トークンは
oauth_tokens(provider="meta") に AES-256-GCM で保存。 - 開発・E2E では
ADDROID_META_OAUTH_MOCK=1でMockMetaAdapterを選択。Mock は 外部graph.facebook.comへの通信を一切行わず、in-memoryMockMetaSandboxで campaign / adset / ad / creative / insights を deterministic に再現します。 - 本番運用では mock フラグを必ず外すこと。
addroid doctorおよび/setupの OSS Release Readiness カードで mock 設定の残置を warn として提示します。 - Sandbox 用の Meta App と本番 Meta App はトークン自身の app type で区別され、Web UI の
TopBar /
/setup#meta//accountsでlive/sandbox/mock/unconfiguredを 常時可視化します。Apply / Activate の ConfirmDialog body 先頭に mode を mono で表示し、mock/sandbox中は確認ボタンに対応するサフィックスを付けます。 - Apply は新規オブジェクトを すべて PAUSED で作成するため、誤って本番 token で Apply が走っても予算消費は発生しません。Activate は別経路で人間承認が必要です。
詳細は docs/META.md を参照してください。
- Slack 連携は 任意。トークンを設定しなくても AdDroid OSS は通常通り稼働し、
/setup#slackおよび Dashboard の Slack カードは benign idle を表示します。 - 連携時は
addroid connect slackで Bot Token (xoxb-*) と App-Level Token (xapp-*、connections:writescope) を暗号化保存します。コマンドは Socket Mode 接続テストを 実行し、成功時のみトークンを永続化します。 - Slack は Socket Mode 専用。public な request URL / event URL を要求しません。
templates/slack-app-manifest.yamlをそのまま Slack 管理画面に貼り付けて App を作成できます。 /adopsslash command は 3 秒以内 ack → pg-boss キュー →response_urlで応答する 契約を維持し、長時間実行は worker 側で安全に処理します。
詳細は docs/SLACK.md を参照してください。
- LLM Provider 未設定時は
StubLLMProviderが fail-closed し、AI workflow は GitOps 状態を破壊せずに失敗します。improvement_prは提案を生成できないためskipped扱いで PR は作成されません。 - Codex はローカル Codex CLI /
codex app-serverのログイン状態を利用し、AdDroid DB には Codex token を保存しません。 - OpenAI / Anthropic API key 認証を使う場合、API key は
oauth_tokens.access_token_ciphertextに AES-256-GCM で暗号化保存します。.envに恒久保存する必要はありません。 - Image Provider 未設定時は creative 生成を skip し、improvement_pr は テキストのみで PR
を作成します (UI は
succeeded_text_onlyの benign idle 表示)。 - LLM 入力 / 出力 JSON は ai_runs に保存される前に redactor を通し、token-shape の値や
個人 path / GitHub login を
[REDACTED]/~/<rest>に置換します。
詳細は docs/LLM_PROVIDER.md を参照してください。
リリース前に必ず確認します。リリース手順全体 (バージョニング / CHANGELOG /
npm publish 実発行 / git tag / ロールバック) は docs/RELEASE.md を、
リリースごとの変更点は CHANGELOG.md を参照してください。本節は
衛生 (secret / 個人 path / hardcoded value の不在) に限定したチェックリストです。
-
git ls-filesの出力に.env*が含まれていない (.env.exampleのみ tracked) -
git ls-filesの出力にsecrets.local.yamlが含まれていない -
git ls-files | grep -E '\.png$'で個人 path や個人 GitHub login が含まれる Playwright / Puppeteer 取得画像が混入していない - コードベース内に
/Users/<personal>のような絶対個人パスが残っていない - コードベース内に
/home/<personal>/C:\Users\<personal>が残っていない - 個人 GitHub アカウント名 / 組織名 / リポジトリ名がハードコードされていない
- 特定
act_<id>/ Slackteam_id/channel_idがハードコードされていない -
ENCRYPTION_KEYの実値が.env.example等に書かれていない (placeholder のみ) -
addroid doctorでsecrets.local.yamlのパーミッション (0600) チェックがokになる (apps/cli/src/lib/checks.tsのcheckSecretsLocal) - Web UI
/setupの "Security & Network Posture" パネルで.gitignoreが.env/secrets.local.yamlを除外していることがokになる (apps/web/app/setup/page.tsxで.gitignoreを読み取り検証) - Web UI
/setup#releaseの OSS Release Readiness カードが warn / fail を表示していない - README / docs に inbound webhook / public domain を要求する記述がない
-
ADDROID_*_MOCK/ENABLE_MOCK_*フラグが.env.exampleで commented-out のままで、 実値が書かれていない -
npm run publish:dry-runが成功する (実 publish は人間承認後に手動実行)
セキュリティ脆弱性を発見した場合は、GitHub の Security Advisories 経由で 非公開報告してください。OSS であるためパブリックなチケットには記載しないでください。
contribution 全般のガイドラインは CONTRIBUTING.md を参照してください。