P0: Hub Inbox Ownership & Consumer Lease

[vansin]

Summary

CommHub inbox delivery authorization is currently alias-based at the Hub boundary. A network-bound node token can supply another same-network alias to inbox read/ack/reply paths. Codex and Grok production runtimes both require the same server-owned fix.

This issue creates one shared Hub primitive. Do not duplicate this identity boundary inside either gateway.

Related: #428 (RFC-030 Codex productionization).

Security invariant

For a network-bound node token, the Hub derives an immutable consumer principal from the authenticated server context. Client-supplied alias is display-only and never authorizes claim, ack, reply, or dead-letter.

The first acceptance test is the existing real-entry negative case:

A node token bound to node A supplies node B's same-network alias to get_inbox, ack_inbox, reply, or dead-letter. Every operation must fail closed and leave node B's rows/tasks unchanged.

The test must fail on the current baseline before the fix.

Two distinct leases — never combine them

1. Hub delivery consumer lease: who may claim/ack/reply one Hub inbox delivery. Implemented in server/src; shared by Codex and Grok.
2. Gateway local reservation / TUI owner lease: who owns a local runtime turn. Implemented inside each gateway.

These are different tokens, lifecycles and trust boundaries. One must never be accepted in place of the other.

Required Hub design

Authenticated consumer principal

• Resolve from the authenticated token record and effective network, never from a token prefix, alias, body, metadata or query parameter.
• Use stable server identity (node id + network binding); record token id for authentication/audit, not as the sole long-lived node identity.
• A network token used outside its bound network resolves to no consumer principal.
• Human/admin inspection is a separate explicit privileged API. It must not reuse the node self-inbox path with a caller-selected alias.

Atomic database primitive

Implement one shared adapter-level operation for self-inbox claim. Handler code must not reimplement the authorization SQL.

The primitive atomically:

• selects only rows addressed to the server-resolved consumer principal/network;
• writes a server-minted lease id, monotonic epoch/version, claim time and expiry;
• returns the claimed rows plus lease metadata;
• makes concurrent claimers mutually exclusive.

Ack, reply and dead-letter must run through shared adapter primitives and atomically verify:

• message id and canonical task id;
• consumer principal;
• network;
• active, unexpired lease id and epoch.

Retry, reassign and cancel invalidate all older delivery leases/epochs. Late acknowledgements from an older delivery must not mutate the current attempt.

Surfaces

• MCP, REST and SSE/push-related consumers use the same server primitives.
• SQLite and PostgreSQL adapters have identical semantics and conformance tests.
• If PgAdapter cannot guarantee the transaction/lease semantics, PostgreSQL fails closed for these operations. Do not emulate the transaction with separate per-statement connections.
• Legacy method names may remain for compatibility, but the node-token path must ignore/reject a mismatched alias and require the server-issued lease. A versioned claim_self_inbox / ack_claimed_inbox API is acceptable if that makes compatibility explicit.

Required tests

Real auth-entry negatives

• same-network node A token + node B alias: cannot read, claim, ack, reply or dead-letter B;
• cross-network node token: cannot act;
• forged from_session / display alias has no effect;
• expired/stale/wrong lease and wrong epoch cannot mutate;
• retry/reassign/cancel invalidate the prior lease;
• concurrent claim: exactly one active consumer lease;
• mismatched canonical task claim cannot affect a healthy task.

Positive/backward compatibility

• node token claims and completes its own row;
• token rotation for the same stable node identity follows the explicit lease policy;
• authorized human/admin inspection works only through the privileged path;
• ordinary sender-principal stamping remains unchanged;
• Codex and Grok thin adapters each pass one integration test without implementing their own auth SQL.

Adapter matrix

Run the same contract suite against SQLite and PostgreSQL. Any adapter without real atomicity is rejected at preflight.

Delivery rules

• Clean worktree and isolated DB.
• Additive migration with an explicit compatibility/rollback analysis.
• Author does not self-review or merge.
• No production deployment or latest switch from this issue.
• Independent security review is required before merge because this changes a live authorization boundary.

Out of scope

• Gateway local human-vs-agent reservation.
• Codex/Grok scheduler policy.
• Production deployment or runtime promotion.

[vansin]

Execution assignment (2026-07-13):

• H0 owner: 通信SDK马
• Base: fresh origin/main clean worktree; separate branch/PR from RFC-030 PR RFC-030 Wave 1B: gateway scheduler/policy/ledger/adapter + upstream mux + principal stamp (draft) #432
• H0 scope only (ETA 3–4h): real auth-entry RED tests, complete surface/adapter inventory, schema/API/lease/epoch/recovery design, PostgreSQL atomicity audit and H1–H4 estimate
• Production schema/handler/adapter implementation remains locked until the H0 contract and RED evidence are independently reviewed
• A's PR RFC-030 Wave 1A — Codex Policy Gateway (DRAFT — do not merge) #431 corrective continues in parallel under 通信工程马
• Grok Phase 0 capture continues; its production adapter waits for this Hub primitive and must remain thin

No merge/deploy/latest authorization.

[vansin]

Implementation kickoff (2026-07-14)

This issue is now an active prerequisite for RFC-030 §8 Stage 2 and the shared Grok runtime boundary.

Owner: 通信SDK马

Delivery gates:

• 30m: clean worktree/branch/base SHA and a running real-entry negative case
• 3h: H0 candidate (API/schema + real-entry RED)
• 8h: H1 implementation candidate, unless a reproducible blocker is reported earlier

The acceptance case must exercise the current authenticated entry path: a same-network node token must not read, acknowledge, reply to, or dead-letter another consumer alias. Handler-only/helper-only tests are insufficient.

The Hub delivery consumer lease remains separate from any gateway-local human/TUI reservation lease. Codex and Grok may add thin adapters, but must not duplicate the Hub authorization boundary or handler-specific SQL.

No merge/deploy/production/latest authorization is implied.

[vansin]

2026-08-18 16:16 CST · 在 origin/main 上逐条复核:仍然成立,而且三处都对得上

一、get_inbox —— 客户端传的 alias 直接当查询键

server/src/tools.ts:874:

server.tool(
  "get_inbox",
  "Get pending commands for your session.",
  {
    alias: z.string().min(1).max(200).describe("Session alias"),   // ← 客户端传
    limit: z.number()…
  },
  async ({ alias, limit }) => {
    const readScope = resolveReadScope(null);                       // ← 传 null
    …
    "SELECT COUNT(*) as cnt FROM inbox WHERE session_name = ?1 AND acked = 0"   // ?1 = alias

二、ack_inbox —— 同形

alias: z.string().min(1).max(200).describe("Session alias"),
…
const inboxTaskParams: any[] = [message_id, alias];
   WHERE session_name = ?2 AND acked = 0

三、resolveReadScope 的粒度是网络级,永远不收窄到 session

server/src/tools.ts:326:

const resolveReadScope = (clientNetId?: string | null): ReadScope => {
  if (!enforceUserId) return { networkId: clientNetId ?? null, networkIds: null };
  if (enforceNetworkId) { … return role ? { networkId: enforceNetworkId, … } : { denied: … }; }
  if (clientNetId)      { … return role ? { networkId: clientNetId, … }     : { denied: … }; }
  return { networkId: null, networkIds: getReadableNetworkIds() };
};

它回答的是「这个 token 能读哪些网络」,从来没回答过「这个 token 是谁」。

⇒ 同一网络内,持有效 token 的任何一方都能读/ack 任意 alias 的收件箱。alias 是一个客户端提供的键,不是从凭据派生的身份。

🔴 我没有直接修,理由是这个

这台机上有 100+ 个节点每分钟在调 get_inbox。 把 alias 从「查询键」改成「必须等于 token 派生的身份」是一个会立刻改变所有在跑节点行为的改动 —— 而我此刻无法回答一个前置问题:

今天有多少调用的 client alias ≠ token 派生 alias?

如果那个数不是 0,一次性强制会把它们全部打死。而这个数现在没有任何地方在记。

建议的落地顺序(先量,再改)

Phase 1 —— 只观测,零行为变化(可以马上做)

在 get_inbox / ack_inbox 里派生 caller principal,只做比对并记一条结构化日志,不改任何返回:

consumer_mismatch  tool=get_inbox  client_alias=<A>  derived=<B>  token_kind=ntok|utok  network=<N>

⇒ 跑一两天就能拿到真实的爆炸半径。这一步不会打死任何节点,而它回答的正是「能不能直接强制」。

Phase 2 —— 按 token 类型分档强制

ntok_（节点 token）  →  alias 必须等于该 token 绑定的 session。不匹配 = 拒绝。
utok_（用户 token）  →  保留跨 alias 读的能力（Dashboard/运维要用），
                        但要求显式作用域，并写审计行。

Phase 3 —— alias 降为 display-only,四处(get_inbox / ack_inbox / reply / dead-letter)统一。

为什么建议按这个顺序,而不是直接上 Phase 2

这个仓今天已经有一条现成的教训:一个新加的检查如果比产品既有立场更严,会当场打红一整片(#961 那条:垫片拿 engines 下限做硬退,5 个 e2e suite 全灭)。

这里的赌注比 CI 大 —— 赌的是在跑的 100+ 个节点。 Phase 1 的成本是一条日志,收益是把「会不会打死人」从猜测变成一个数。