@tokenoftrust/storefront-runner 2.0.3 → 2.0.5

package/apps/storefront/src/lib/shared/developerInvites.ts

@@ -0,0 +1,1250 @@
+/**
+ * DeveloperInviteClient — the storefront's seam to tot20's operator-auth
+ * developer-invite endpoint (#8425): a keyless, self-serve invite path.
+ *
+ * An authenticated OPERATOR — storefront, presenting its OWN per-tier ToT
+ * credentials — invites a developer EMAIL onto a tenant it OPERATES (not owns).
+ * tot20 authorizes via its own operator-grant check (`hasOperatorGrant`), writes
+ * the `developer` eligibility role onto the TARGET tenant tenant-internally (no
+ * owner keys, no leaf-token dance), then sends the branded sign-in email.
+ *
+ *   POST /api/clients/developerInvites  { tenant, email, sendEmail? }
+ *     → 200 { code:'developerInvites:created', inviteId, tenant, developer,
+ *             roles:['developer'], changed, emailed, signInEligible, capability }
+ *     → 403 developerInvites:notGranted   (storefront holds no operator grant here)
+ *     → 422 developerInvites:{tenantRequired|invalidEmail|tenantNotFound}
+ *
+ * AUTH WIRE (mirrors `@/lib/auth/totAccessClient`): tot20's swagger
+ * `normalizeSecureUserRequest` extracts machine creds
+ * from the request BODY fields `totApiKey`/`totSecretKey`, NOT custom `x-tot-*`
+ * headers. That is the ONLY integration-sensitive spot ({@link credentialFields}).
+ * tot20 wraps every response in a `{ content, metadata }` envelope.
+ *
+ * TIER: the host + operator credential are per-DEPLOY env (`TOT_CORE_URL` +
+ * `TOT_API_KEY`/`TOT_SECRET_KEY`) — each tier's deploy is configured with its
+ * tier-matching values (test/qa → https://qa.tokenoftrust.com, prod →
+ * https://app.tokenoftrust.com). This is the SAME env the sibling forge + access
+ * clients read; there are no hardcoded hosts and no secrets in code.
+ *
+ * Built like `@/lib/forge` and `@/lib/auth/totAccessClient` (interface + Http impl
+ * + Mock + env factory) so the route develops/tests against `MockDeveloperInviteClient`
+ * and swaps in the Http client with no call-site change. The tiny HTTP transport
+ * seam is duplicated locally rather than imported from `@/lib/auth` so the grants
+ * control-plane cluster stays self-contained (see `.dependency-cruiser.cjs`).
+ */
+import { readEnv } from "@/lib/env";
+import { diagEmail } from "@/lib/diag/redact";
+import { checkStorePreviewReady, type PreflightDecision } from "@/lib/shared/invitePreflight";
+
+/**
+ * The header carrying the storefront-signed staff BROKER ASSERTION to tot20
+ * (#8453). The literal is duplicated locally (rather than
+ * imported from `@/lib/auth/brokerAssertion`) so the grants control-plane cluster
+ * stays self-contained (see `.dependency-cruiser.cjs`); the MINTER lives in
+ * `@/lib/auth` and the ROUTE mints + passes the compact JWT down as a string.
+ */
+const BROKER_ASSERTION_HEADER = "X-ToT-Broker-Assertion";
+
+/** Narrow tot20's `signInToken` payload to the expected shape (fail-closed). */
+function isSignInToken(v: unknown): v is { token: string; expiresAt: string; audience: string } {
+  if (!v || typeof v !== "object") return false;
+  const o = v as Record<string, unknown>;
+  return typeof o.token === "string" && typeof o.expiresAt === "string" && typeof o.audience === "string";
+}
+
+/** Host of a URL, or null — for diagnostics (never throws). */
+function safeHost(url?: string): string | null {
+  if (!url) return null;
+  try {
+    return new URL(url).host;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Secret-safe diagnostic for the storefront→tot20 invite interaction — the
+ * storefront half of the cross-repo email-send trace. Logs the request shape +
+ * tot20's decision (esp. `emailed`) so email-send outcomes are observable on both
+ * sides. NEVER logs creds/assertions.
+ * Emitted at info level → lands in `logs/dev.log` (pnpm dev:log) and worker logs.
+ */
+function logInviteDiag(phase: "request" | "response", fields: Record<string, unknown>): void {
+  try {
+    console.info(`[diag:invite:${phase}]`, JSON.stringify(fields));
+  } catch {
+    /* diagnostics must never break the call */
+  }
+}
+
+/**
+ * tot20's team-role vocabulary (mirrors `ASSIGNABLE_ROLES` in tot20's
+ * `DeveloperInviteManager`). `contributor` is the ONE role a plain, non-staff
+ * operator/member invite may request directly — a strictly-weaker self-downgrade
+ * from `developer`, never an escalation; `appAdmin`/`appOwner` still require a
+ * VERIFIED staff broker assertion (#8453). Exported so UI role pickers (e.g. the
+ * dashboard Team page) stay in sync with what tot20 actually honors.
+ */
+export const DEVELOPER_INVITE_ROLES = [
+  "developer",
+  "appAdmin",
+  "appOwner",
+  "contributor",
+] as const;
+export type DeveloperInviteRole = (typeof DEVELOPER_INVITE_ROLES)[number];
+
+/** The one team role a plain (non-staff) operator/member may self-request. */
+export const CONTRIBUTOR_ROLE: DeveloperInviteRole = "contributor";
+
+/** Operator input to a developer invite. `tenant` is resolved from the session. */
+export interface DeveloperInviteInput {
+  /** Target tenant appDomain the developer is invited onto (session-derived). */
+  tenant: string;
+  /** The developer's email (lowercased on the wire; tot20 keys eligibility on it). */
+  email: string;
+  /** Send the branded sign-in email (tot20 default: true). */
+  sendEmail?: boolean;
+  /**
+   * A fresh storefront-signed BROKER ASSERTION (compact RS256 JWT) PROVING the
+   * signed-in staff actor (#8453). Minted
+   * server-side by `@/lib/auth/brokerAssertion` from the verified `session.email`
+   * and presented to tot20 in the `X-ToT-Broker-Assertion` header. tot20 verifies
+   * signature + replay and derives the staff actor from the VERIFIED `sub`, then
+   * permits invite/list on ANY tenant (bypassing the operator-grant). Omitted →
+   * the operator-grant-only path applies. NEVER a plaintext staff email (which
+   * would be spoofable).
+   */
+  brokerAssertion?: string;
+  /**
+   * The team-member role to write. tot20's vocabulary: `developer` (default) |
+   * `appAdmin` | `appOwner` | `contributor`.
+   *
+   * `appAdmin`/`appOwner` are HONORED only for a VERIFIED STAFF actor (a
+   * `brokerAssertion` that verifies to ToT staff, #8453);
+   * for a plain operator they are IGNORED and the role stays hard-pinned to
+   * `developer`.
+   *
+   * `contributor` is the ONE exception: tot20 honors it for a plain (non-staff)
+   * operator too — it is a strictly-weaker self-downgrade from `developer`, never an
+   * escalation (`DeveloperInviteManager._resolveInviteRole` in tot20). So a normal,
+   * non-staff invite call MAY request `contributor` directly — no broker assertion
+   * needed. Omitted → developer.
+   */
+  role?: string;
+  /**
+   * Optional personal note from the inviter, shown to the developer in the branded
+   * invite email. Free-text — tot20 HTML-escapes it on render (injection guard).
+   * Omitted → the email has no note block.
+   */
+  note?: string;
+  /**
+   * Absolute sign-in URL on the INVITING storefront (its own origin + a post-login
+   * `next`), so tot20 can render a "Sign in to <store>" call-to-action button in the
+   * invite email — without it the email is code-only and the developer has nowhere to
+   * enter the code (#8425). tot20 must allowlist/validate the
+   * URL before rendering it. Omitted → tot20 falls back to the code-only copy.
+   */
+  signInUrl?: string;
+  /**
+   * MAGIC-LINK mint (storefront-owns-the-email model). When true, tot20 does NOT send
+   * its own template — instead it returns a high-entropy single-use `signInToken` (see
+   * {@link DeveloperInviteCreated.signInToken}) for the storefront to embed in its OWN
+   * branded email. Pair with `sendEmail:false`. The token is returned only over this
+   * server-to-server operator channel, never to the browser.
+   */
+  issueSignInToken?: boolean;
+  /**
+   * MAGIC-LINK lifetime (seconds) — the storefront owns the link's TTL. tot20 clamps to
+   * [60, 604800] (1 min .. 7 days); absent → tot20's 30-min default. The effective value
+   * comes back as `signInToken.ttlSeconds`.
+   */
+  signInTokenTtlSeconds?: number;
+}
+
+/** A successful invite — tot20 wrote the `developer` eligibility on the tenant. */
+export interface DeveloperInviteCreated {
+  ok: true;
+  /** Opaque handle encoding (tenant, appSpec-user-id) for GET-one / DELETE. */
+  inviteId: string;
+  tenant: string;
+  /** The invited developer email, echoed back. */
+  developer: string;
+  /** Roles written — hard-pinned to `['developer']` by tot20. */
+  roles: string[];
+  /** `false` when the email already held the developer role (idempotent no-op). */
+  changed: boolean;
+  /** Whether the branded sign-in email was actually sent. */
+  emailed: boolean;
+  /** Whether tot20 now resolves the email as access-code eligible. */
+  signInEligible: boolean;
+  /** Effective capability tot20 resolved for the email (usually `developer`). */
+  capability?: string;
+  /**
+   * Why the email did (or didn't) send — tot20's structured reason:
+   * `sent | rateLimited | notEligible | mailError | sendError | skipped`. Makes an
+   * `emailed:false` self-explaining instead of a silent false.
+   */
+  emailReason?: string;
+  /** Human detail when not sent (rate-limit window, transport/Mandrill error, …). */
+  emailDetail?: string;
+  /**
+   * MAGIC-LINK token — present only when the request set `issueSignInToken:true`. A
+   * high-entropy, single-use, short-TTL secret bound to `(email, audience)`, for the
+   * storefront to embed in its own branded email's CTA (`/auth/magic?token=…`).
+   * Exchanged (POST-only, never GET) via {@link TotAccessClient.exchangeSignInToken}.
+   */
+  signInToken?: { token: string; expiresAt: string; audience: string; ttlSeconds?: number };
+}
+
+/** Typed failure reasons mapped from tot20's error codes / HTTP status. */
+export type DeveloperInviteFailureReason =
+  | "notGranted" // 403 developerInvites:notGranted — no operator grant on tenant
+  | "notAuthenticated" // 403 operatorGrants:notAuthenticated — bad/absent operator cred
+  | "tenantRequired" // 422
+  | "invalidEmail" // 422
+  | "tenantNotFound" // 422
+  | "storeNotProvisioned" // 409 — LOCAL preflight block: the store repo isn't provisioned here
+  | "error"; // transport / unexpected upstream fault
+
+export interface DeveloperInviteFailed {
+  ok: false;
+  /** Upstream HTTP status (0 for a transport failure before any response). */
+  status: number;
+  reason: DeveloperInviteFailureReason;
+  message: string;
+  /** tot20's machine-readable `code`, when present. */
+  code?: string;
+}
+
+export type DeveloperInviteResult = DeveloperInviteCreated | DeveloperInviteFailed;
+
+/** One developer invite in a tenant's listing (the team member list). */
+export interface DeveloperInviteSummary {
+  inviteId: string;
+  tenant: string;
+  developer: string;
+  roles: string[];
+}
+
+/** Result of listing a tenant's developer invites (typed failure, fail-closed). */
+export type DeveloperInviteListResult =
+  | { ok: true; tenant: string; invites: DeveloperInviteSummary[] }
+  | {
+      ok: false;
+      status: number;
+      reason: DeveloperInviteFailureReason;
+      message: string;
+      code?: string;
+    };
+
+/** Result of revoking a developer invite (typed failure, fail-closed). */
+export type DeveloperInviteRevokeResult =
+  | { ok: true; tenant: string; inviteId: string }
+  | {
+      ok: false;
+      status: number;
+      reason: DeveloperInviteFailureReason;
+      message: string;
+      code?: string;
+    };
+
+export interface DeveloperInviteClient {
+  /** Invite a developer email onto a tenant storefront operates. */
+  createInvite(input: DeveloperInviteInput): Promise<DeveloperInviteResult>;
+  /**
+   * List the developer invites (team members) on a tenant storefront operates.
+   * `brokerAssertion` (a storefront-signed staff proof) is presented to tot20 in
+   * the `X-ToT-Broker-Assertion` header; when it verifies to ToT staff server-side,
+   * the list is permitted on ANY tenant (#8453).
+   */
+  listInvites(
+    tenant: string,
+    brokerAssertion?: string,
+  ): Promise<DeveloperInviteListResult>;
+  /**
+   * Revoke one developer invite by its opaque `inviteId` (as returned by
+   * `createInvite`/`listInvites`). Idempotent on tot20's side (revoking an already-
+   * gone invite is a success no-op). Same `brokerAssertion` staff carve-out as
+   * `listInvites`.
+   */
+  revokeInvite(
+    inviteId: string,
+    brokerAssertion?: string,
+  ): Promise<DeveloperInviteRevokeResult>;
+}
+
+// --- HTTP transport seam (injected by tests) --------------------------------
+
+export interface HttpResponseLike {
+  status: number;
+  json(): Promise<unknown>;
+}
+export interface HttpTransport {
+  post(
+    url: string,
+    headers: Record<string, string>,
+    body: unknown,
+  ): Promise<HttpResponseLike>;
+  /** Optional GET (used by listInvites). Optional so post-only test stubs still satisfy the seam. */
+  get?(url: string, headers: Record<string, string>): Promise<HttpResponseLike>;
+  /** Optional DELETE (used by revokeInvite). Optional so existing test stubs still satisfy the seam. */
+  delete?(url: string, headers: Record<string, string>): Promise<HttpResponseLike>;
+}
+
+/** Default transport: JSON `fetch` POST/GET/DELETE. */
+export class FetchHttpTransport implements HttpTransport {
+  async post(url: string, headers: Record<string, string>, body: unknown) {
+    return fetch(url, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        accept: "application/json",
+        ...headers,
+      },
+      body: JSON.stringify(body),
+    });
+  }
+  async get(url: string, headers: Record<string, string>) {
+    return fetch(url, {
+      method: "GET",
+      headers: { accept: "application/json", ...headers },
+    });
+  }
+  async delete(url: string, headers: Record<string, string>) {
+    return fetch(url, {
+      method: "DELETE",
+      headers: { accept: "application/json", ...headers },
+    });
+  }
+}
+
+export interface HttpDeveloperInviteClientConfig {
+  /** tot20 core API base (no trailing slash), e.g. https://qa.tokenoftrust.com */
+  baseUrl: string;
+  /** Storefront's OWN per-tier ToT credentials (machine auth to the operator API). */
+  apiKey: string;
+  secretKey?: string;
+  transport?: HttpTransport;
+}
+
+export class DeveloperInviteClientError extends Error {}
+
+// --- HTTP impl --------------------------------------------------------------
+
+export class HttpDeveloperInviteClient implements DeveloperInviteClient {
+  private readonly baseUrl: string;
+  private readonly apiKey: string;
+  private readonly secretKey?: string;
+  private readonly transport: HttpTransport;
+
+  constructor(config: HttpDeveloperInviteClientConfig) {
+    if (!config.baseUrl) {
+      throw new DeveloperInviteClientError(
+        "developerInvites: TOT_CORE_URL is not configured",
+      );
+    }
+    if (!config.apiKey) {
+      throw new DeveloperInviteClientError(
+        "developerInvites: storefront ToT credentials are not configured",
+      );
+    }
+    this.baseUrl = config.baseUrl.replace(/\/+$/, "");
+    this.apiKey = config.apiKey;
+    this.secretKey = config.secretKey;
+    this.transport = config.transport ?? new FetchHttpTransport();
+  }
+
+  /**
+   * The one integration-sensitive spot: tot20 reads `totApiKey`/`totSecretKey`
+   * from the request body (`normalizeSecureUserRequest`), so storefront's own
+   * credentials are merged into the POST body. Swap for a machine-JWT
+   * `Authorization: Bearer` here if tot20 ever requires it — the ONLY place to change.
+   */
+  private credentialFields(): Record<string, string> {
+    const f: Record<string, string> = { totApiKey: this.apiKey };
+    if (this.secretKey) f.totSecretKey = this.secretKey;
+    return f;
+  }
+
+  async createInvite(
+    input: DeveloperInviteInput,
+  ): Promise<DeveloperInviteResult> {
+    const body: Record<string, unknown> = {
+      tenant: input.tenant,
+      email: input.email.toLowerCase(),
+      ...this.credentialFields(),
+    };
+    if (input.sendEmail !== undefined) body.sendEmail = input.sendEmail;
+    // #8453: the requested role (tot20 honors it only for a VERIFIED staff actor;
+    // ignored for a plain operator, which stays developer-only).
+    if (input.role) body.role = input.role;
+    // Optional inviter note → shown in the branded invite email (tot20 HTML-escapes it).
+    if (input.note) body.note = input.note;
+    // Optional storefront sign-in URL → tot20 renders it as the email's CTA button
+    // (#8425). Harmless if tot20 doesn't yet consume it.
+    if (input.signInUrl) body.signInUrl = input.signInUrl;
+    // MAGIC-LINK mint: ask tot20 to return a single-use signInToken instead of sending
+    // its own template (the storefront sends its own branded email). Pair with sendEmail:false.
+    if (input.issueSignInToken) body.issueSignInToken = true;
+    if (input.signInTokenTtlSeconds != null) body.signInTokenTtlSeconds = input.signInTokenTtlSeconds;
+
+    // #8453: the staff actor is proven by the
+    // storefront-signed assertion in the header — NEVER a plaintext email field.
+    const headers: Record<string, string> = {};
+    if (input.brokerAssertion) headers[BROKER_ASSERTION_HEADER] = input.brokerAssertion;
+
+    // DIAGNOSTIC: what the storefront is about to send to tot20 (the request half of
+    // the email-send trace). `signInUrlHost` is the top allowlist suspect.
+    logInviteDiag("request", {
+      endpoint: `${this.baseUrl}/api/clients/developerInvites`,
+      tenant: input.tenant,
+      email: diagEmail(input.email.toLowerCase()),
+      sendEmail: input.sendEmail ?? "(unset → tot20 default)",
+      hasSignInUrl: !!input.signInUrl,
+      signInUrlHost: safeHost(input.signInUrl),
+      hasBrokerAssertion: !!input.brokerAssertion,
+      role: input.role ?? "(unset → developer)",
+    });
+
+    let res: HttpResponseLike;
+    try {
+      res = await this.transport.post(
+        `${this.baseUrl}/api/clients/developerInvites`,
+        headers,
+        body,
+      );
+    } catch (cause) {
+      return {
+        ok: false,
+        status: 0,
+        reason: "error",
+        message:
+          "developerInvites: transport failure calling tot20 " +
+          (cause instanceof Error ? cause.message : String(cause)),
+      };
+    }
+
+    let parsed: unknown;
+    try {
+      parsed = await res.json();
+    } catch {
+      return {
+        ok: false,
+        status: res.status,
+        reason: "error",
+        message: `developerInvites: tot20 returned a non-JSON body (status ${res.status})`,
+      };
+    }
+    const result = normalizeInviteResponse(res.status, parsed);
+    // DIAGNOSTIC: tot20's decision — the crux is `emailed`. `changed:false, emailed:false`
+    // means tot20 authorized + already had the role but did NOT send (the gate we're hunting).
+    logInviteDiag("response", {
+      tenant: input.tenant,
+      email: diagEmail(input.email.toLowerCase()),
+      httpStatus: res.status,
+      ok: result.ok,
+      ...(result.ok
+        ? {
+            changed: result.changed,
+            emailed: result.emailed,
+            emailReason: result.emailReason ?? "(none)",
+            emailDetail: result.emailDetail,
+            signInEligible: result.signInEligible,
+          }
+        : { reason: result.reason, code: result.code }),
+    });
+    return result;
+  }
+
+  async listInvites(
+    tenant: string,
+    brokerAssertion?: string,
+  ): Promise<DeveloperInviteListResult> {
+    if (!this.transport.get) {
+      return {
+        ok: false,
+        status: 0,
+        reason: "error",
+        message: "developerInvites: transport does not support GET",
+      };
+    }
+    // GET → creds go in the query string (tot20 reads totApiKey/totSecretKey from
+    // body OR query; a GET has no body). tenant is a normal query param.
+    const q = new URLSearchParams({ tenant, ...this.credentialFields() });
+    // #8453: the staff actor is proven by the signed
+    // assertion header — NEVER a plaintext email query param.
+    const headers: Record<string, string> = {};
+    if (brokerAssertion) headers[BROKER_ASSERTION_HEADER] = brokerAssertion;
+    let res: HttpResponseLike;
+    try {
+      res = await this.transport.get(
+        `${this.baseUrl}/api/clients/developerInvites?${q.toString()}`,
+        headers,
+      );
+    } catch (cause) {
+      return {
+        ok: false,
+        status: 0,
+        reason: "error",
+        message:
+          "developerInvites: transport failure listing invites " +
+          (cause instanceof Error ? cause.message : String(cause)),
+      };
+    }
+    let parsed: unknown;
+    try {
+      parsed = await res.json();
+    } catch {
+      return {
+        ok: false,
+        status: res.status,
+        reason: "error",
+        message: `developerInvites: tot20 returned a non-JSON body (status ${res.status})`,
+      };
+    }
+    return normalizeInvitesListResponse(res.status, tenant, parsed);
+  }
+
+  async revokeInvite(
+    inviteId: string,
+    brokerAssertion?: string,
+  ): Promise<DeveloperInviteRevokeResult> {
+    if (!this.transport.delete) {
+      return {
+        ok: false,
+        status: 0,
+        reason: "error",
+        message: "developerInvites: transport does not support DELETE",
+      };
+    }
+    // DELETE has no body — creds ride the query string, matching listInvites.
+    const q = new URLSearchParams(this.credentialFields());
+    const headers: Record<string, string> = {};
+    if (brokerAssertion) headers[BROKER_ASSERTION_HEADER] = brokerAssertion;
+    let res: HttpResponseLike;
+    try {
+      res = await this.transport.delete(
+        `${this.baseUrl}/api/clients/developerInvites/${encodeURIComponent(inviteId)}?${q.toString()}`,
+        headers,
+      );
+    } catch (cause) {
+      return {
+        ok: false,
+        status: 0,
+        reason: "error",
+        message:
+          "developerInvites: transport failure revoking invite " +
+          (cause instanceof Error ? cause.message : String(cause)),
+      };
+    }
+    let parsed: unknown;
+    try {
+      parsed = await res.json();
+    } catch {
+      return {
+        ok: false,
+        status: res.status,
+        reason: "error",
+        message: `developerInvites: tot20 returned a non-JSON body (status ${res.status})`,
+      };
+    }
+    return normalizeInviteRevokeResponse(res.status, parsed);
+  }
+}
+
+/**
+ * Parse tot20's `{ content, metadata }` REVOKE response (`developerInvites:revokeOk`)
+ * into a typed result (fail closed). Same envelope-unwrap + error-mapping as
+ * {@link normalizeInviteResponse}.
+ */
+export function normalizeInviteRevokeResponse(
+  status: number,
+  body: unknown,
+): DeveloperInviteRevokeResult {
+  const raw = (body ?? {}) as Record<string, unknown>;
+  const c = (
+    raw.content && typeof raw.content === "object" ? raw.content : raw
+  ) as Record<string, unknown>;
+
+  const code = typeof c.code === "string" ? c.code : undefined;
+  const isOk =
+    code === "developerInvites:revokeOk" || (status >= 200 && status < 300);
+
+  if (isOk) {
+    return {
+      ok: true,
+      tenant: String(c.tenant ?? ""),
+      inviteId: String(c.inviteId ?? ""),
+    };
+  }
+
+  const message =
+    typeof c.message === "string"
+      ? c.message
+      : typeof raw.message === "string"
+        ? raw.message
+        : undefined;
+  const reason = reasonFor(code, status);
+  return {
+    ok: false,
+    status,
+    reason,
+    message: message ?? defaultMessage(reason, status),
+    ...(code ? { code } : {}),
+  };
+}
+
+/**
+ * Parse tot20's `{ content, metadata }` invite response into a typed result
+ * (fail closed). Success is `code === 'developerInvites:created'` (or an
+ * `inviteId` on a 2xx); every other shape maps to a typed failure by `code`,
+ * falling back to the HTTP status.
+ */
+export function normalizeInviteResponse(
+  status: number,
+  body: unknown,
+): DeveloperInviteResult {
+  const raw = (body ?? {}) as Record<string, unknown>;
+  // Unwrap the swagger `{ content, metadata }` envelope when present; fall back
+  // to the raw body (the Mock + tests return the un-enveloped shape).
+  const c = (
+    raw.content && typeof raw.content === "object" ? raw.content : raw
+  ) as Record<string, unknown>;
+
+  const code = typeof c.code === "string" ? c.code : undefined;
+  const message =
+    typeof c.message === "string"
+      ? c.message
+      : typeof raw.message === "string"
+        ? raw.message
+        : undefined;
+
+  const isCreated =
+    code === "developerInvites:created" ||
+    (status >= 200 && status < 300 && typeof c.inviteId === "string");
+
+  if (isCreated) {
+    return {
+      ok: true,
+      inviteId: String(c.inviteId ?? ""),
+      tenant: String(c.tenant ?? ""),
+      developer: String(c.developer ?? ""),
+      roles: Array.isArray(c.roles)
+        ? c.roles.filter((r): r is string => typeof r === "string")
+        : ["developer"],
+      changed: c.changed === true,
+      emailed: c.emailed === true,
+      signInEligible: c.signInEligible === true,
+      ...(typeof c.capability === "string" ? { capability: c.capability } : {}),
+      ...(typeof c.emailReason === "string" ? { emailReason: c.emailReason } : {}),
+      ...(typeof c.emailDetail === "string" ? { emailDetail: c.emailDetail } : {}),
+      ...(isSignInToken(c.signInToken) ? { signInToken: c.signInToken } : {}),
+    };
+  }
+
+  const reason = reasonFor(code, status);
+  return {
+    ok: false,
+    status,
+    reason,
+    message: message ?? defaultMessage(reason, status),
+    ...(code ? { code } : {}),
+  };
+}
+
+/**
+ * Parse tot20's `{ content, metadata }` LIST response (`developerInvites:listOk`)
+ * into a typed result (fail closed). Same envelope-unwrap + error-mapping as
+ * {@link normalizeInviteResponse}.
+ */
+export function normalizeInvitesListResponse(
+  status: number,
+  tenant: string,
+  body: unknown,
+): DeveloperInviteListResult {
+  const raw = (body ?? {}) as Record<string, unknown>;
+  const c = (
+    raw.content && typeof raw.content === "object" ? raw.content : raw
+  ) as Record<string, unknown>;
+
+  const code = typeof c.code === "string" ? c.code : undefined;
+  const isOk =
+    code === "developerInvites:listOk" ||
+    (status >= 200 && status < 300 && Array.isArray(c.invites));
+
+  if (isOk) {
+    const invites: DeveloperInviteSummary[] = (
+      Array.isArray(c.invites) ? c.invites : []
+    ).map((raw2) => {
+      const r = (raw2 ?? {}) as Record<string, unknown>;
+      return {
+        inviteId: String(r.inviteId ?? ""),
+        tenant: String(r.tenant ?? tenant),
+        developer: String(r.developer ?? ""),
+        roles: Array.isArray(r.roles)
+          ? r.roles.filter((x): x is string => typeof x === "string")
+          : [],
+      };
+    });
+    return { ok: true, tenant, invites };
+  }
+
+  const message =
+    typeof c.message === "string"
+      ? c.message
+      : typeof raw.message === "string"
+        ? raw.message
+        : undefined;
+  const reason = reasonFor(code, status);
+  return {
+    ok: false,
+    status,
+    reason,
+    message: message ?? defaultMessage(reason, status),
+    ...(code ? { code } : {}),
+  };
+}
+
+/** Map tot20's error `code` (authoritative) then the HTTP status onto a reason. */
+function reasonFor(
+  code: string | undefined,
+  status: number,
+): DeveloperInviteFailureReason {
+  switch (code) {
+    case "developerInvites:notGranted":
+      return "notGranted";
+    case "operatorGrants:notAuthenticated":
+      return "notAuthenticated";
+    case "developerInvites:tenantRequired":
+      return "tenantRequired";
+    case "developerInvites:invalidEmail":
+      return "invalidEmail";
+    case "developerInvites:tenantNotFound":
+      return "tenantNotFound";
+    default:
+      // No recognised code — infer from status so a 403/422 still fails typed.
+      if (status === 403 || status === 401) return "notGranted";
+      return "error";
+  }
+}
+
+/**
+ * Map a typed invite/list failure onto the HTTP status a storefront endpoint
+ * should return: notGranted/notAuthenticated → 403; the 422 validation reasons →
+ * 422; a transport/unexpected fault → the upstream status if it's an error, else
+ * 502 (bad gateway to tot20). Shared by every route that surfaces the client.
+ */
+export function developerInviteHttpStatus(
+  reason: DeveloperInviteFailureReason,
+  upstreamStatus: number,
+): number {
+  switch (reason) {
+    case "notGranted":
+    case "notAuthenticated":
+      return 403;
+    case "tenantRequired":
+    case "invalidEmail":
+    case "tenantNotFound":
+      return 422;
+    default:
+      return upstreamStatus >= 400 ? upstreamStatus : 502;
+  }
+}
+
+function defaultMessage(
+  reason: DeveloperInviteFailureReason,
+  status: number,
+): string {
+  switch (reason) {
+    case "notGranted":
+      return "storefront isn't authorized to invite on this tenant";
+    case "notAuthenticated":
+      return "storefront's operator credential was rejected";
+    case "tenantRequired":
+      return "a target tenant is required";
+    case "invalidEmail":
+      return "a valid developer email is required";
+    case "tenantNotFound":
+      return "the target tenant is not a resolvable Token of Trust app";
+    default:
+      return `developerInvites: tot20 returned status ${status}`;
+  }
+}
+
+// --- Mock (tests + local dev) -----------------------------------------------
+
+/**
+ * In-memory DeveloperInviteClient. Seeded with the set of tenants storefront is
+ * authorized to operate, it drives route + client tests deterministically and
+ * lets local dev exercise the flow before/without the live tot20 endpoint.
+ */
+export class MockDeveloperInviteClient implements DeveloperInviteClient {
+  /** Tenants this operator holds a grant on (anything else → notGranted). */
+  private readonly granted: Set<string>;
+  /** Emails already holding the developer role per tenant (idempotency). */
+  private readonly existing = new Set<string>();
+  /** Recorded invites, for assertions. */
+  invited: DeveloperInviteInput[] = [];
+
+  constructor(grantedTenants: string[] = []) {
+    this.granted = new Set(grantedTenants.map((t) => t.toLowerCase()));
+  }
+
+  async createInvite(
+    input: DeveloperInviteInput,
+  ): Promise<DeveloperInviteResult> {
+    const tenant = (input.tenant ?? "").trim().toLowerCase();
+    const email = (input.email ?? "").trim().toLowerCase();
+    if (!tenant) {
+      return {
+        ok: false,
+        status: 422,
+        reason: "tenantRequired",
+        message: "a target tenant is required",
+      };
+    }
+    if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) {
+      return {
+        ok: false,
+        status: 422,
+        reason: "invalidEmail",
+        message: "a valid developer email is required",
+      };
+    }
+    // #8453: a broker assertion stands in for a
+    // VERIFIED ToT-STAFF actor (tot20 verifies + derives staff server-side); staff
+    // bypass the operator-grant check on ANY tenant. Without an assertion the legacy
+    // granted-set behavior applies. (The Mock treats presence as proof; the real
+    // tot20 verifies the signature.)
+    const staffActor = !!(input.brokerAssertion && input.brokerAssertion.trim());
+    if (!staffActor && !this.granted.has(tenant)) {
+      return {
+        ok: false,
+        status: 403,
+        reason: "notGranted",
+        message: "storefront isn't authorized to invite on this tenant",
+        code: "developerInvites:notGranted",
+      };
+    }
+    this.invited.push({
+      tenant,
+      email,
+      sendEmail: input.sendEmail,
+      ...(input.brokerAssertion ? { brokerAssertion: input.brokerAssertion } : {}),
+      ...(input.role ? { role: input.role } : {}),
+      ...(input.signInUrl ? { signInUrl: input.signInUrl } : {}),
+    });
+    const key = `${tenant} ${email}`;
+    const changed = !this.existing.has(key);
+    this.existing.add(key);
+    // A staff actor may write any role (tot20 honors it). A plain operator is
+    // developer-only, with ONE carve-out: it may deliberately request `contributor`
+    // (a strictly-weaker self-downgrade, honored directly — mirrors tot20's
+    // `DeveloperInviteManager._resolveInviteRole`). Every other non-staff role
+    // request is ignored (stays developer).
+    const effectiveRole = staffActor
+      ? input.role || "developer"
+      : input.role === CONTRIBUTOR_ROLE
+        ? CONTRIBUTOR_ROLE
+        : "developer";
+    return {
+      ok: true,
+      inviteId: Buffer.from(`${tenant}|${email}`, "utf8").toString("base64url"),
+      tenant,
+      developer: email,
+      roles: [effectiveRole],
+      changed,
+      // Magic-link mint: no tot20 email when a token was requested (storefront sends its own).
+      emailed: input.issueSignInToken ? false : input.sendEmail !== false,
+      ...(input.issueSignInToken ? { emailReason: "tokenIssued" as const } : {}),
+      signInEligible: true,
+      capability: "developer",
+      ...(input.issueSignInToken
+        ? {
+            signInToken: {
+              token: Buffer.from(`mock|${tenant}|${email}`, "utf8").toString("base64url"),
+              expiresAt: "2099-01-01T00:00:00.000Z",
+              audience: tenant,
+              ttlSeconds: input.signInTokenTtlSeconds ?? 1800,
+            },
+          }
+        : {}),
+    };
+  }
+
+  async listInvites(
+    tenant: string,
+    brokerAssertion?: string,
+  ): Promise<DeveloperInviteListResult> {
+    const t = (tenant ?? "").trim().toLowerCase();
+    if (!t) {
+      return { ok: false, status: 422, reason: "tenantRequired", message: "a target tenant is required" };
+    }
+    // #8453: a staff broker assertion bypasses the operator-grant on ANY tenant.
+    const staffActor = !!(brokerAssertion && brokerAssertion.trim());
+    if (!staffActor && !this.granted.has(t)) {
+      return {
+        ok: false,
+        status: 403,
+        reason: "notGranted",
+        message: "storefront isn't authorized to list invites on this tenant",
+        code: "developerInvites:notGranted",
+      };
+    }
+    const invites: DeveloperInviteSummary[] = [...this.existing]
+      .filter((k) => k.startsWith(`${t} `))
+      .map((k) => {
+        const email = k.slice(t.length + 1);
+        return {
+          inviteId: Buffer.from(`${t}|${email}`, "utf8").toString("base64url"),
+          tenant: t,
+          developer: email,
+          roles: ["developer"],
+        };
+      });
+    return { ok: true, tenant: t, invites };
+  }
+
+  async revokeInvite(
+    inviteId: string,
+    brokerAssertion?: string,
+  ): Promise<DeveloperInviteRevokeResult> {
+    let decoded: { tenant: string; email: string } | null = null;
+    try {
+      const raw = Buffer.from(inviteId.replace(/-/g, "+").replace(/_/g, "/"), "base64url").toString("utf8");
+      const idx = raw.indexOf("|");
+      if (idx > 0) decoded = { tenant: raw.slice(0, idx), email: raw.slice(idx + 1) };
+    } catch {
+      decoded = null;
+    }
+    if (!decoded) {
+      return { ok: false, status: 400, reason: "error", message: "malformed inviteId" };
+    }
+    const staffActor = !!(brokerAssertion && brokerAssertion.trim());
+    if (!staffActor && !this.granted.has(decoded.tenant)) {
+      return {
+        ok: false,
+        status: 403,
+        reason: "notGranted",
+        message: "storefront isn't authorized to revoke on this tenant",
+        code: "developerInvites:notGranted",
+      };
+    }
+    this.existing.delete(`${decoded.tenant} ${decoded.email}`);
+    return { ok: true, tenant: decoded.tenant, inviteId };
+  }
+}
+
+// --- Factory ----------------------------------------------------------------
+
+/**
+ * Build the env-configured client:
+ *   - `TOT_CORE_URL`  — tot20 core API base (tier-matching per deploy).
+ *   - `TOT_API_KEY` (+ optional `TOT_SECRET_KEY`) — storefront's own operator creds.
+ * Throws {@link DeveloperInviteClientError} when unconfigured (the route maps that to 503).
+ */
+export async function createDeveloperInviteClient(
+  overrides: Partial<HttpDeveloperInviteClientConfig> = {},
+): Promise<HttpDeveloperInviteClient> {
+  const baseUrl = overrides.baseUrl ?? (await readEnv("TOT_CORE_URL")) ?? "";
+  const apiKey = overrides.apiKey ?? (await readEnv("TOT_API_KEY")) ?? "";
+  const secretKey = overrides.secretKey ?? (await readEnv("TOT_SECRET_KEY"));
+  return new HttpDeveloperInviteClient({
+    ...overrides,
+    baseUrl,
+    apiKey,
+    secretKey,
+  });
+}
+
+// --- Option B app-binding seam (#8425) --------------------------------------
+
+/** What to record: the developer's subject-capability app-binding in the MCP. */
+export interface DeveloperAppBinding {
+  /** Subject — the developer email (the MCP subject-capability store key). */
+  email: string;
+  /** Tenant the capability is scoped to. */
+  tenant: string;
+  /**
+   * The capability literal to write. Omitted → `"preview-access"` (today's default
+   * for every plain developer invite). A `contributor` team-role invite writes
+   * `"blog-contribute"` here (see {@link inviteDeveloperToTenant}) so
+   * `resolveViewerContributeCapability` (`@/lib/change/route/viewer-ship-grant`) sees a real,
+   * live, owner-revocable grant over the SAME subject-capability store it reads.
+   */
+  capability?: "preview-access" | "blog-contribute" | "ship-on-behalf";
+}
+
+/** Best-effort outcome of the app-binding write (never fails the invite). */
+export type AppBindingResult =
+  | { recorded: true }
+  // Skipped fail-closed: the write was not attempted/counted because the seam is
+  // unconfigured OR the MCP route isn't mounted yet (401). Not an error.
+  | { recorded: false; skipped: true; reason: string }
+  // Attempted but failed for a real reason (bad body / store fault / transport).
+  | { recorded: false; skipped: false; reason: string };
+
+/**
+ * Record the developer's Option-B subject-capability app-binding in the MCP: the
+ * MCP store is the app-binding source of truth; the writer is this keyless flow.
+ *
+ * WIRED (confirmed contract):
+ *   POST `${MCP_APP_BINDING_URL}`  — the keyless subject-capability writer,
+ *     e.g. https://mcp.qa.tokenoftrust.com/api/internal/dev-access/subject-capability
+ *   Auth: header `x-mcp-service-secret: <MCP_SERVICE_SHARED_SECRET>` (compared
+ *     constant-time to the MCP's shared secret) — NOT an Authorization bearer.
+ *   Body: { subject:<email>, tenant, capability:'preview-access', app:'storefront' }
+ *     (capability/app are optional MCP defaults but sent explicitly). Idempotent.
+ *   → 200 { status:'recorded', ... } | 401 bad/missing secret | 400 bad body | 502 store.
+ *
+ * FAIL-CLOSED: the MCP route is only mounted once the shared secret is set on the
+ * MCP deploy, so an unconfigured seam (no URL/secret) OR a 401 is treated as
+ * `{ skipped: true }`, not a hard failure. A 400/502/transport fault is a real
+ * (non-skipped) failure the caller surfaces as partial success.
+ *
+ * BEST-EFFORT by contract: this NEVER throws and NEVER blocks the invite. The
+ * developer's tenant eligibility (the invite) is already written by tot20 regardless.
+ */
+export async function recordDeveloperAppBinding(
+  binding: DeveloperAppBinding,
+  deps: { transport?: HttpTransport } = {},
+): Promise<AppBindingResult> {
+  const url = await readEnv("MCP_APP_BINDING_URL");
+  const secret = await readEnv("MCP_SERVICE_SHARED_SECRET");
+  if (!url || !secret) {
+    // Seam not fully configured (the MCP route isn't mounted until the shared
+    // secret exists). Skip cleanly rather than fail the invite.
+    return { recorded: false, skipped: true, reason: "not-configured" };
+  }
+  const transport = deps.transport ?? new FetchHttpTransport();
+  try {
+    const res = await transport.post(
+      url,
+      { "x-mcp-service-secret": secret },
+      {
+        // Option B fixed fields — the subject-capability binding for storefront.
+        subject: binding.email.toLowerCase(),
+        tenant: binding.tenant,
+        capability: binding.capability ?? "preview-access",
+        app: "storefront",
+      },
+    );
+    if (res.status >= 200 && res.status < 300) return { recorded: true };
+    if (res.status === 401) {
+      // Bad/missing secret or the MCP route isn't mounted yet — fail-closed as skipped.
+      return {
+        recorded: false,
+        skipped: true,
+        reason: "unauthorized (mcp service secret rejected or route unmounted)",
+      };
+    }
+    return {
+      recorded: false,
+      skipped: false,
+      reason: `mcp app-binding write returned status ${res.status}`,
+    };
+  } catch (cause) {
+    return {
+      recorded: false,
+      skipped: false,
+      reason:
+        "mcp app-binding write failed: " +
+        (cause instanceof Error ? cause.message : String(cause)),
+    };
+  }
+}
+
+// --- Accept-before-sign-in seam (#8425) -------------------------------------
+
+/** Best-effort outcome of marking a developer invite accepted (never fails sign-in). */
+export type AcceptInviteResult =
+  | { accepted: true; changed: boolean }
+  // Not attempted (seam unconfigured) or no invite to accept — not a hard failure.
+  | { accepted: false; skipped: true; reason: string }
+  // Attempted but failed for a real reason (auth / store fault / transport).
+  | { accepted: false; skipped: false; reason: string };
+
+/**
+ * Mark a developer invite ACCEPTED at the magic-link confirm (#8425 accept-before-
+ * sign-in). Called server-to-server from the magic-exchange handler the moment the
+ * invitee affirmatively confirms — so the tot20 invite roster advances pending →
+ * accepted as the developer signs in. This confers NO grant (tot20's createInvite
+ * already wrote the role); it only advances the visible status, so it is authed by
+ * the storefront's OWN operator creds (mirrors {@link HttpDeveloperInviteClient})
+ * and tot20 scopes it to an invite THIS app issued.
+ *
+ * BEST-EFFORT by contract: NEVER throws, NEVER blocks sign-in. A non-invitee magic
+ * sign-in (no pending invite) simply comes back skipped/404; an already-accepted
+ * invite is an idempotent no-op (changed:false).
+ */
+export async function acceptDeveloperInvite(
+  tenant: string,
+  email: string,
+  deps: { transport?: HttpTransport } = {},
+): Promise<AcceptInviteResult> {
+  const t = (tenant ?? "").trim().toLowerCase();
+  const e = (email ?? "").trim().toLowerCase();
+  if (!t || !e) {
+    return { accepted: false, skipped: true, reason: "no-tenant-or-email" };
+  }
+  const baseUrl = ((await readEnv("TOT_CORE_URL")) ?? "").replace(/\/+$/, "");
+  const apiKey = (await readEnv("TOT_API_KEY")) ?? "";
+  if (!baseUrl || !apiKey) {
+    return { accepted: false, skipped: true, reason: "not-configured" };
+  }
+  const secretKey = await readEnv("TOT_SECRET_KEY");
+  const body: Record<string, string> = { tenant: t, email: e, totApiKey: apiKey };
+  if (secretKey) body.totSecretKey = secretKey;
+  const transport = deps.transport ?? new FetchHttpTransport();
+  try {
+    const res = await transport.post(
+      `${baseUrl}/api/clients/developerInvites/accept`,
+      {},
+      body,
+    );
+    if (res.status >= 200 && res.status < 300) {
+      let changed = false;
+      try {
+        const parsed = (await res.json()) as Record<string, unknown>;
+        const c = (parsed?.content && typeof parsed.content === "object"
+          ? parsed.content
+          : parsed) as Record<string, unknown>;
+        changed = c.changed === true;
+      } catch {
+        /* a 2xx with an unparseable body is still an accept success */
+      }
+      return { accepted: true, changed };
+    }
+    // 404 = no pending invite for this email (a non-invitee magic sign-in) — skip cleanly.
+    if (res.status === 404) {
+      return { accepted: false, skipped: true, reason: "no-invite-for-email" };
+    }
+    return {
+      accepted: false,
+      skipped: false,
+      reason: `tot20 accept returned status ${res.status}`,
+    };
+  } catch (cause) {
+    return {
+      accepted: false,
+      skipped: false,
+      reason:
+        "developerInvites accept transport failure: " +
+        (cause instanceof Error ? cause.message : String(cause)),
+    };
+  }
+}
+
+// --- Canonical "grant a developer access to a tenant" method -----------------
+
+/** Outcome of the canonical invite: the tot20 result + the best-effort binding. */
+export interface InviteDeveloperOutcome {
+  /** The tot20 developer-invite result (ok or a typed failure). */
+  invite: DeveloperInviteResult;
+  /**
+   * The Option-B app-binding outcome. Only attempted when the invite SUCCEEDED
+   * (a failed invite has nothing to bind); undefined otherwise.
+   */
+  appBinding?: AppBindingResult;
+}
+
+/** Injectable collaborators (tests); both default to the env-configured impls. */
+export interface InviteDeveloperDeps {
+  /** The tot20 invite client. Defaults to {@link createDeveloperInviteClient}. */
+  client?: DeveloperInviteClient;
+  /** The Option-B recorder. Defaults to {@link recordDeveloperAppBinding}. */
+  recordAppBinding?: (
+    binding: DeveloperAppBinding,
+  ) => Promise<AppBindingResult>;
+  /**
+   * The store-provisioned preflight. Defaults to {@link checkStorePreviewReady}.
+   * Runs BEFORE the invite: a definitive not-provisioned answer BLOCKS the send;
+   * any inconclusive answer fails open (see invitePreflight).
+   */
+  preflight?: (tenant: string) => Promise<PreflightDecision>;
+}
+
+/**
+ * THE canonical, single-source-of-truth method for "grant a developer (email)
+ * access to a tenant" (#8425). Every storefront surface that gives a developer
+ * EMAIL access/eligibility on a tenant routes through here: it invites via tot20's
+ * operator endpoint AND records the Option-B app-binding (best-effort), so the two
+ * halves of "developer has access" never drift between call sites.
+ *
+ * Keyed on EMAIL — the identifier tot20 eligibility joins on. A caller holding a
+ * different identifier (e.g. a forge `principal`/appDomain) must resolve the email
+ * before calling; see the DEV-ACCESS note below for why the repo-grant
+ * fan-out is a SEPARATE axis and does NOT route through here.
+ *
+ * The app-binding is attempted only on a successful invite and NEVER changes the
+ * invite's own success/failure — partial success is reported via the returned
+ * `appBinding`, not by throwing.
+ *
+ * DEV-ACCESS (fan-out) — why the team/repo fan-out does not call this:
+ * `TeamGrantService.grantTeam`'s tenant-tier step (`forge.grantDeveloperAccess`)
+ * is the FORGE repo-collaboration PREREQUISITE (`grantRepoAccess` is refused
+ * without it — enforced by MockForgeClient and, per its comment, the real MCP).
+ * That grant lives on the MCP/forge backend and is keyed on `principal`/appDomain;
+ * this invite writes tenant ELIGIBILITY on the tot20-core backend keyed on email.
+ * Routing the fan-out through here would leave the forge precondition unmet (repo
+ * grants would fail) AND has no email to supply — a genuinely different axis.
+ */
+export async function inviteDeveloperToTenant(
+  input: DeveloperInviteInput,
+  deps: InviteDeveloperDeps = {},
+): Promise<InviteDeveloperOutcome> {
+  // Preflight: BLOCK the send when the target store's repo isn't provisioned on this
+  // environment, so the error surfaces to the INVITER now instead of dead-ending in
+  // the invitee's terminal later. Every role that leads to a `tot start`/checkout
+  // (developer | appAdmin | appOwner) routes through here, so gating here covers all
+  // of them. Fail-open (see invitePreflight): only a definitive not-provisioned
+  // answer blocks; an unconfigured/errored/timed-out seam allows.
+  const preflight = deps.preflight ?? checkStorePreviewReady;
+  const ready = await preflight(input.tenant);
+  if (ready.block) {
+    console.warn(
+      `[developerInvites] invite BLOCKED by preflight for ${input.tenant}: ${ready.reason}`,
+    );
+    return {
+      invite: {
+        ok: false,
+        status: 409,
+        reason: "storeNotProvisioned",
+        message: ready.message,
+        code: "store-not-provisioned",
+      },
+    };
+  }
+
+  const client = deps.client ?? (await createDeveloperInviteClient());
+  const invite = await client.createInvite({
+    tenant: input.tenant,
+    email: input.email,
+    sendEmail: input.sendEmail,
+    ...(input.brokerAssertion ? { brokerAssertion: input.brokerAssertion } : {}),
+    ...(input.role ? { role: input.role } : {}),
+    ...(input.note ? { note: input.note } : {}),
+    ...(input.signInUrl ? { signInUrl: input.signInUrl } : {}),
+    ...(input.issueSignInToken ? { issueSignInToken: true } : {}),
+    ...(input.signInTokenTtlSeconds != null ? { signInTokenTtlSeconds: input.signInTokenTtlSeconds } : {}),
+  });
+  if (!invite.ok) return { invite };
+
+  // A `contributor` team-role invite ALSO writes the `blog-contribute` capability
+  // into the SAME MCP subject-capability store `resolveViewerContributeCapability`
+  // reads. Every other role keeps
+  // today's default (`preview-access`). tot20's own role write (above) already
+  // happened regardless — this is the best-effort second half of "the developer has
+  // contributor access", exactly like the existing preview-access binding.
+  const capability = invite.roles.includes(CONTRIBUTOR_ROLE)
+    ? "blog-contribute"
+    : "preview-access";
+
+  const record = deps.recordAppBinding ?? recordDeveloperAppBinding;
+  const appBinding = await record({
+    email: invite.developer,
+    tenant: invite.tenant,
+    capability,
+  });
+  return { invite, appBinding };
+}