Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 38 additions & 7 deletions docs/ops/15_Google_Cloud_Launch_Readiness.md
Original file line number Diff line number Diff line change
Expand Up @@ -258,13 +258,44 @@ Production uses the same simplified shape, but every boundary is isolated from
staging:

1. Separate Cloud SQL instance.
2. Separate secrets.
3. Separate Lark routes.
4. Separate Gmail sender.
5. Separate contract addresses.
6. Separate owner and signer wallets.
7. Separate domain.
8. Separate evidence directory.

## Production Admin Entry Boundary

Production `admin-front` and `gateway-admin` now use a public Cloud Run entry
surface, but the security boundary remains application-auth-first.

Required invariants:

1. `https://admin.synapse-network.ai/login` stays publicly reachable so human
operators can open the login page.
2. `https://admin-api.synapse-network.ai/health` may be publicly reachable for
health checks, but business routes must still require app-layer auth.
3. A bootstrap or seeded admin without `password_hash` must not be able to log
in and must not be able to enter a usable MFA enrollment path.
4. `MFA_ENROLLMENT_REQUIRED` is only valid after password verification succeeds
for an active admin who requires MFA but has no usable active Google
Authenticator factor.
5. `POST /api/admin/v1/auth/mfa/enroll/begin` and
`POST /api/admin/v1/auth/mfa/enroll/verify` must continue to require a valid
short-lived enrollment token minted by the password-verified login branch.
6. No admin session cookie may be issued until MFA enrollment verify succeeds
for first-bind flows.

Operational interpretation:

1. Public login page does not mean public admin access.
2. Password remains the first mandatory gate.
3. Google Authenticator TOTP remains the second gate for bound accounts and the
first-bind requirement for unbound `require_mfa=true` accounts.
4. Session cookie, CSRF, RBAC, lockout, audit trail, and high-risk TOTP step-up
remain the main runtime protections after the network edge is made public.
5. Separate secrets.
6. Separate Lark routes.
7. Separate Gmail sender.
8. Separate contract addresses.
9. Separate owner and signer wallets.
10. Separate domain.
11. Separate evidence directory.

Production Cloud SQL minimum:

Expand Down
16 changes: 13 additions & 3 deletions docs/ops/20_Production_GCP_Operator_Checklist.md
Original file line number Diff line number Diff line change
Expand Up @@ -142,9 +142,11 @@ Operators must:

1. keep `admin-front` as the default human operator entrypoint
2. keep `gateway-admin` business routes protected by app-layer auth, CSRF,
TOTP step-up, and RBAC
password-first login, TOTP step-up, and RBAC
3. verify anonymous access reaches the login/API surface instead of Google
Frontend `403`
4. ensure bootstrap admins still require a manually initialized password before
any MFA enrollment can begin

Required production runtime settings:

Expand All @@ -160,8 +162,16 @@ Expected public-entry behavior:
1. `https://admin.synapse-network.ai/login` returns `200`
2. `https://admin.synapse-network.ai/` routes to the app login flow instead of
Cloud Run `Forbidden`
3. `https://admin-api.synapse-network.ai/health` returns `200`
4. anonymous protected admin API calls return application `401/403`
3. accounts without `password_hash` cannot log in and cannot reach a usable MFA
enrollment path
4. password-verified but unbound admins receive
`428 MFA_ENROLLMENT_REQUIRED`
5. `https://admin-api.synapse-network.ai/health` returns `200`
6. anonymous protected admin API calls return application `401/403`
7. MFA enrollment begin/verify only succeeds when the request carries a valid
login-minted enrollment token
8. first-bind accounts do not receive `synapse_admin_session` until Google
Authenticator enrollment verify succeeds

## 5. Private Cloud SQL Network Checks

Expand Down
22 changes: 22 additions & 0 deletions docs/projects/gateway-admin/Gateway_Admin_Operations_Runbook.md
Original file line number Diff line number Diff line change
Expand Up @@ -239,6 +239,16 @@ GATEWAY_INTERNAL_SERVICE_SUBJECTS=service:gateway-admin

Docker bootstrap 只创建管理员账号、角色绑定和占位 MFA 记录,不会初始化密码。`admin_users.password_hash` 为 `NULL` 时,登录会返回通用“邮箱或密码不正确”。

这个安全边界必须明确保持:

1. 没有密码就不可登录。
2. 没有密码就不能进入可用的 MFA enrollment 流程。
3. 只有密码先验证通过,且账号 `require_mfa = true` 但没有可用 active
Google Authenticator 因子时,登录接口才允许返回
`428 MFA_ENROLLMENT_REQUIRED`。
4. Google Authenticator enrollment verify 成功前,不会签发
`synapse_admin_session`。

```bash
cd /Users/cliff/workspace/agent/Synapse-Network/services/gateway-admin
.venv/bin/python scripts/set_bootstrap_password.py \
Expand All @@ -260,6 +270,18 @@ cd /Users/cliff/workspace/agent/Synapse-Network/services/gateway-admin

如果登录 MFA 开启,bootstrap 管理员默认没有可用 TOTP secret,需要先完成 MFA enrollment。Manual Setup Key 由 Gateway-admin 在 enrollment begin 时随机生成,Google Authenticator 只负责读取这个标准 TOTP secret,不会返回 secret 给我们。历史库里如果还存在 `__BOOTSTRAP_TOTP_SECRET__`,它只是不可用的 legacy 哨兵值,必须按未绑定 MFA 处理,不能展示给管理员、不能扫码使用。高危审核动作始终应保留 OTP step-up。

推荐验证步骤:

1. 先执行上面的 `set_bootstrap_password.py`
2. 打开 `https://admin.synapse-network.ai/login`
3. 使用刚设置的密码发起登录;只有密码正确时,才允许进入 MFA enrollment
4. expected result: `428 MFA_ENROLLMENT_REQUIRED`
5. 进入首绑流程,完成 Google Authenticator 扫码或手工录入
6. 提交首个 6 位验证码后,正式获得后台 session

如果第 3 步密码错误,预期结果必须始终是通用 `401 UNAUTHORIZED`,而不是
`MFA_ENROLLMENT_REQUIRED`。

### 2.8 重置未绑定 MFA 的联调测试管理员

```bash
Expand Down
4 changes: 4 additions & 0 deletions docs/reference/Service_Port_Map.md
Original file line number Diff line number Diff line change
Expand Up @@ -43,6 +43,10 @@ Production admin routing note:
owns session, CSRF, MFA, and RBAC enforcement.
4. Anonymous requests to protected `gateway-admin` business routes should fail
with application `401/403`, not Google Frontend `403`.
5. Public reachability does not bypass the bootstrap hardening path: accounts
without a password hash must still fail login before MFA enrollment can
begin, and first-bind Google Authenticator flows must not mint an admin
session until enrollment verify succeeds.

## Env Defaults

Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
# Agent Lessons: codex-admin-password-first-mfa-enrollment

No new lessons.
2 changes: 1 addition & 1 deletion scripts/e2e/prod_public_docs_links_e2e.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -330,7 +330,7 @@ await check(
"public health endpoint"
);
await check("admin_login_page", `${ADMIN_ROOT}/login`, [200], (body) => {
assertContains(body, "System Authorization", "admin login title");
assertContains(body, "Admin Console Login", "admin login title");
});
await check(
"admin_root_entry",
Expand Down
2 changes: 1 addition & 1 deletion scripts/ui/dogfood_admin_front.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -442,7 +442,7 @@ async function closeTopModal(page) {
}

const authPageMatrix = [
{ route: "/login", name: "login", text: ["System Authorization"] },
{ route: "/login", name: "login", text: ["Admin Console Login"] },
{
route: "/login/mfa-enroll",
name: "login-mfa-enroll",
Expand Down
2 changes: 1 addition & 1 deletion scripts/ui/dogfood_admin_login_lockout.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -177,7 +177,7 @@ async function submitLogin(page, password) {
item.request().method() === "POST",
{ timeout: 15000 }
),
page.getByRole("button", { name: /Execute Initialization/i }).click(),
page.getByRole("button", { name: /Continue Secure Sign-In/i }).click(),
]);
const body = await response.json().catch(() => ({}));
apiResponses.push({
Expand Down
2 changes: 1 addition & 1 deletion services/admin-front/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -52,7 +52,7 @@ Recommended prototype lookup order:

- `services/admin-front/stitch/overview/`: console shell, dashboard density, card rhythm, signal surfaces, and global Sentinel tone.
- `services/admin-front/stitch/admin_login/`: admin sign-in composition, security framing, CTA posture, and auth entry hierarchy.
- `services/admin-front/stitch/mfa_setup_registration/`: MFA enrollment, QR/manual key layout, verification cadence, and secure initialization mood.
- `services/admin-front/stitch/mfa_setup_registration/`: password-gated MFA enrollment, QR/manual key layout, verification cadence, and activation-state copy.
- `services/admin-front/stitch/reset_successful/`: success-state composition, post-action confirmation rhythm, and return-entry CTA treatment.
- `services/admin-front/stitch/synapse_sentinel/`: shared Sentinel design language and supporting visual rules.

Expand Down
Loading
Loading