Neutral responses for grant creation by identifier

[IAM-marco]

Part of #1022. Builds on PR #1192.

Goal

Make "grant access by email" reveal nothing about who exists in the system, and reject self-invites.

Current state

PR #1192 lets POST /grants create a grant from a user.identifier (email in the default schema; the lookup key is whatever the user schema designates via x-identifier, ADR 058). Its contract says: "Exactly one active match is required; zero or several resolve as not found", returning grant.principal_not_found. So the response tells the caller whether the address belongs to an active user. A duplicate grant returns grant.already_exists (409), which is also distinguishable.

The Console journey built on top of this shows the inviter a fixed message: "If the user exists in our system, they have been granted access to your project." That message is only honest if the API itself does not leak the difference.

Separately, internal/api/security.go:110-116 allowlists QueryUsers for sessions. Its only Console consumer is the add-admin picker that the email flow replaces, and it hands any operator a page of up to 100 users, which defeats the neutral message from the other side.

Decisions that shape this work

• On the identifier path, zero matches returns the same success-shaped response as a created grant. The server does nothing and says nothing; reasons stay in the server logs, as PR feat(api): accept user and team locators on grants #1192 already does for ambiguity.
• On the identifier path, an existing identical grant also returns the success shape instead of grant.already_exists. Nothing is created twice.
• The explicit user_id path keeps its current errors; ids are not secrets the way identifiers are.
• Granting to yourself (the resolved user equals the caller) is rejected with a visible error. Your own address tells you nothing new, so this leaks nothing.
• Worth noting for the implementation: a neutral response does not stop volume or timing probes, so this endpoint is a rate-limiting candidate.
• QueryUsers is removed from the session allowlist once the Console picker is gone.
• Known limitation, on purpose: until authz: gate GrantService with grant.create after catalog has grant relations #1024 and Define System Permission Catalog & Default Bundles #420 land, any access level passes the admin check, so "only admins can create grants" is not yet enforced server-side.

Dependencies

• PR feat(api): accept user and team locators on grants #1192. This changes the semantics that PR introduces; if the PR absorbs these changes before merging, this ticket shrinks to the allowlist cleanup.

Test first (TDD)

Write API tests first: create-by-identifier with a matching user returns success and writes the grant; with an unknown identifier it returns the same response shape and writes nothing; repeated with the same identifier it returns the same shape and writes nothing new; the caller's own identifier is rejected with a distinct error; create-by-user_id keeps today's grant.principal_not_found and grant.already_exists behavior; a session calling POST /users/query is refused after the allowlist change. Then implement.

Tasks

• Change the identifier-path responses in the grant create flow (internal/service/grant.go) as decided above, and update the contract text in api/openapi/endpoints/grants/.
• Add the self-grant check where the identifier resolves (compare against the session's user id).
• Drop QueryUsers from the session allowlist in internal/api/security.go, coordinated with the Console ticket that removes the picker.

Reference

PR #1192 (user-locator.yaml, resolveUserByIdentifier); internal/domain/grant.go:19 (ErrGrantPrincipalNotFound); ADR 058 (identifier designation); ADR 054 (collaboration grants).

[IAM-marco]

PR #1192 now implements the neutral contract on the identifier path (commit ce615c7): a miss or an ambiguous match returns 201 with a synthetic grant and writes nothing (the reason goes to the server logs), a duplicate returns 201 with the existing grant, and a session caller granting their own resolved user gets a visible grant.invalid. The user_id and team paths keep their 404/409.

One leak remains, and it belongs to this ticket: the response body still answers the question the status no longer does.

A real identifier create hydrates the user reference, so its 201 body carries user.identifier (and usually display). The synthetic miss body is a bare user_id with no identifier (the integration test asserts the field is absent). A caller who can only create grants can therefore still tell "address matched" from "address unknown" by checking whether the body echoes the identifier. Callers with read access can enumerate through the grant list regardless, which the recorded rationale accepts, but create-only callers are exactly the surface this ticket wants closed.

Suggested direction: return the bare user_id ref on every identifier-path create response, hit or miss. The two outcomes then differ only in random ids, and the Console flow does not need the echoed identifier, since it already knows what it sent.

With PR #1192 absorbing the contract change, what is left here: the QueryUsers allowlist cleanup from the issue body, plus this body-shape alignment.

[IAM-marco]

Update after the grilling session and PR #1265.

What the PR does. Creating a grant now returns only the user id (or team id) in the 201 body, on every create path. Before, a create by email address filled in the user's email and display name when the address matched and left them out when it did not, so anyone who could create grants could still tell the two apart. Now a hit, a duplicate and a miss all come back with the same shape. Reading a grant back (GET or list) still returns the email and display name, as before. Granting yourself is now rejected when you pass your own user id, not only when you pass your own address.

The third task in this ticket is dropped on purpose. Three reasons, in plain terms:

Why "drop QueryUsers from the session allowlist" is not done

1. The list in internal/api/security.go that this ticket points at does not grant anything. It marks calls that need a logged-in user rather than any cookie. Removing the users query from it would let an anonymous cookie through, which is the opposite of what we want. The switch that decides whether a browser session may call the users query is the security block on POST /users/query in the OpenAPI, where the session cookie is listed as an accepted credential.
2. The add-admin picker is not the only caller. The Console users page (apps/console/src/routes/_authed/users/index.tsx) lists users through the same session call, and the CLI calls it too (with a project secret, so it would not be affected).
3. The users query already checks whether the caller may list users of the session's project. What is missing is a permission system that says only admins pass that check, and that is authz: gate GrantService with grant.create after catalog has grant relations #1024's job, not an allowlist edit. Until it lands, anyone with any access to the Console project sees the list. That is a known limitation already recorded in this ticket.

So this ticket closes with PR #1265. Who may list users is decided in #1024. Rate limiting for the by-email path is filed separately as #1266.