@domino-sdk/relay 1.61.0 → 1.63.0

package/dist/{participant-activity-DHL8QYks.d.ts → participant-activity-D-Drp24G.d.ts}

@@ -92,14 +92,23 @@ declare function sessionMember(session: {
 declare const memberSummarySchema: z.ZodObject<{
     member: z.ZodString;
     avatarSeed: z.ZodString;
-    email: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-    emails: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    email: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    emails: z.ZodDefault<z.ZodArray<z.ZodString>>;
     clock: z.ZodOptional<z.ZodObject<{
         now: z.ZodNumber;
         offsetMs: z.ZodNumber;
     }, z.core.$strip>>;
 }, z.core.$strip>;
-type MemberSummary = z.infer<typeof memberSummarySchema>;
+type MemberSummaryResponse = z.infer<typeof memberSummarySchema>;
+/** @compat output */
+type MemberSummary = Omit<MemberSummaryResponse, "clock"> & {
+    clock: NonNullable<MemberSummaryResponse["clock"]>;
+};
+/**
+ * @deprecated `POST /v1/auth/exchange` refuses this body with 400: it takes `{ subject, accounts?,
+ * previousToken? }` with an identity integration server key as the bearer. Use
+ * `exchangeParticipant` from `@domino-sdk/relay/portal-proxy`. Removed in 2.0.0.
+ */
 declare const exchangeSchema: z.ZodObject<{
     organization: z.ZodString;
     project: z.ZodString;
@@ -117,6 +126,10 @@ declare const exchangeSchema: z.ZodObject<{
         operator: "operator";
     }>;
 }, z.core.$strict>;
+/**
+ * @deprecated `POST /v1/auth/exchange` refuses this body with 400. Use `exchangeParticipant` from
+ * `@domino-sdk/relay/portal-proxy`. Removed in 2.0.0.
+ */
 type ExchangeInput = z.infer<typeof exchangeSchema>;
 declare const exchangeResultSchema: z.ZodObject<{
     token: z.ZodString;

package/dist/portal-proxy.d.ts

@@ -1,3 +1,8 @@
+import { M as MemberImportVouchedAccount, P as ParticipantExchangeAccountResult, a as ParticipantExchangeResult, I as IdentityIntegrationKey } from './identity-integration-DOeNZaxF.js';
+import { R as RequestError } from './request-error-D_dUPLwo.js';
+import './tracker-data-esm3WG8R.js';
+import 'zod';
+
 /**
  * Server-only proxy: browser cookies stay on the participant origin.
  * The shared API resolves the app's origin to its registered preview or staging
@@ -14,14 +19,82 @@ declare function proxyParticipant(request: Request, upstream: {
      */
     hosted?: boolean;
 }): Promise<Response>;
-/** Use only in an app server route. authenticate must verify the app's own session. */
+declare const participantExchangeErrorBrand: unique symbol;
+/**
+ * Whether `value` is a `ParticipantExchangeError` from any copy of the SDK. Prefer it to
+ * `instanceof`.
+ */
+declare function isParticipantExchangeError(value: unknown): value is ParticipantExchangeError;
+/**
+ * An exchange Domino refused: a `RequestError` of kind `http`, with `status` and `code` as the
+ * exchange answered them, and `retryAfter` the milliseconds its `Retry-After` asked to wait, such
+ * as on a rate-limited exchange.
+ *
+ * @compat sealed
+ */
+declare class ParticipantExchangeError extends RequestError {
+    readonly name: string;
+    readonly [participantExchangeErrorBrand] = true;
+    readonly status: number;
+    readonly code: string;
+    constructor(message: string, details: {
+        status: number;
+        code: string;
+        retryAfter?: number;
+    });
+}
+/**
+ * Signs a member in from your server, without a browser: trades your identity integration key and
+ * the stable ID of a user your server verified for a participant session. Use it when no browser
+ * reaches Domino through `createParticipantBackend`, such as a backend that calls Domino for its
+ * users. `accounts` vouches for the user's accounts as `createParticipantBackend`'s does, and the
+ * answer's `accounts` gives each one's outcome. Pass the previous answer's `token` as
+ * `previousToken` to keep using that session while it lasts. Throws ParticipantExchangeError when
+ * Domino refuses the exchange.
+ */
+declare function exchangeParticipant(options: {
+    baseUrl: string;
+    integrationKey: string;
+    subject: string;
+    previousToken?: string;
+    accounts?: MemberImportVouchedAccount[];
+    fetch?: typeof fetch;
+}): Promise<ParticipantExchangeResult>;
+/**
+ * Which integration an app login key (`di_…`) belongs to: its organization, project, environment,
+ * origin and the expiry of this key, never a secret. Checking a key does not count as using it.
+ * `baseUrl` is the participant API origin: HTTPS, or a loopback HTTP origin for a local stack.
+ * Throws ParticipantExchangeError when Domino refuses the key: 401 `invalid-credential` for a key
+ * that is unknown, expired or revoked, or whose project was deleted.
+ */
+declare function inspectIntegrationKey(options: {
+    baseUrl: string;
+    integrationKey: string;
+    fetch?: typeof fetch;
+}): Promise<IdentityIntegrationKey>;
+/**
+ * Use only in an app server route. authenticate must verify the app's own session.
+ * `origin` is the app's exact HTTPS origin, or a loopback HTTP origin
+ * (`http://localhost`, `http://127.0.0.1`, `http://[::1]`, any port) for a
+ * local browser test. Relay registers only HTTPS origins, so a loopback origin
+ * works only against an injected `fetch`, such as `createFakeRelay`'s.
+ * `authenticate` may also return `accounts` the app vouches belong to the user, which needs the
+ * key's **Vouches accounts** setting; `onAccounts` receives each one's outcome, such as an account
+ * another member holds.
+ * `onExchangeError` receives each refused exchange as Domino answered it (status, code, message and
+ * `retryAfter`) before the browser gets its answer, so the server can log why sign-in failed. The
+ * browser's answer does not change, and a callback that throws does not change it either.
+ */
 declare function createParticipantBackend(options: {
     baseUrl: string;
     integrationKey: string;
     origin: string;
     authenticate: (request: Request) => Promise<{
         subject: string;
+        accounts?: MemberImportVouchedAccount[];
     } | null>;
+    onAccounts?: (results: ParticipantExchangeAccountResult[], request: Request) => void | Promise<void>;
+    onExchangeError?: (error: ParticipantExchangeError, request: Request) => void | Promise<void>;
     fetch?: typeof fetch;
 }): (request: Request) => Promise<Response>;
 /**
@@ -60,4 +133,4 @@ declare function signedInMember(request: Request, env: HostedAppEnv, options: {
     fetch?: typeof fetch;
 }): Promise<string | null>;
 
-export { type HostedAppEnv, createParticipantBackend, handleHostedApp, hostedAppRequest, proxyParticipant, signedInMember };
+export { type HostedAppEnv, ParticipantExchangeError, createParticipantBackend, exchangeParticipant, handleHostedApp, hostedAppRequest, inspectIntegrationKey, isParticipantExchangeError, proxyParticipant, signedInMember };

package/dist/portal-proxy.js

@@ -1,15 +1,27 @@
+import {
+  secureOrLoopbackOrigin
+} from "./chunk-UZ765UGH.js";
+import {
+  identityIntegrationKeySchema,
+  participantExchangeAccountsSchema,
+  participantExchangeResultSchema
+} from "./chunk-KP2MCX3R.js";
 import {
   isParticipantRoute
-} from "./chunk-MHPKEVEW.js";
+} from "./chunk-U66GUVSG.js";
 import {
-  clientIdentity
-} from "./chunk-EN3M5Z4J.js";
+  clientIdentity,
+  retryAfter
+} from "./chunk-3RFP6GT5.js";
 import {
-  exchangeResultSchema,
   participantPrincipalSchema,
   sessionMember
-} from "./chunk-PPB7HALD.js";
-import "./chunk-ZDJLPN4L.js";
+} from "./chunk-N4BDKS6Y.js";
+import "./chunk-ID3BZXFZ.js";
+import {
+  RequestError,
+  isRequestError
+} from "./chunk-GLH6MEI2.js";
 
 // src/portal-proxy.ts
 import * as z from "zod";
@@ -86,10 +98,98 @@ async function proxyParticipant(request, upstream) {
     headers: resultHeaders
   });
 }
+function requestExchange(options, body) {
+  return (options.fetch ?? fetch)(options.baseUrl + "/v1/auth/exchange", {
+    method: "POST",
+    redirect: "manual",
+    headers: {
+      Authorization: "Bearer " + options.integrationKey,
+      "X-Domino-Client": clientIdentity(),
+      "Content-Type": "application/json"
+    },
+    body: JSON.stringify({
+      subject: body.subject,
+      previousToken: body.previousToken,
+      accounts: body.accounts?.length ? participantExchangeAccountsSchema.parse(body.accounts) : void 0
+    })
+  });
+}
+var participantExchangeErrorBrand = /* @__PURE__ */ (() => /* @__PURE__ */ Symbol.for(
+  "@domino-sdk/relay.ParticipantExchangeError"
+))();
+function isParticipantExchangeError(value) {
+  return isRequestError(value) && value[participantExchangeErrorBrand] === true;
+}
+var ParticipantExchangeError = class extends RequestError {
+  name = "ParticipantExchangeError";
+  [participantExchangeErrorBrand] = true;
+  constructor(message, details) {
+    super(message, { ...details, kind: "http" });
+  }
+};
+async function exchangeParticipant(options) {
+  const base = new URL(options.baseUrl);
+  if (base.protocol !== "https:" || base.origin !== options.baseUrl) {
+    throw new Error("Configure the exact HTTPS participant API origin");
+  }
+  if (!options.integrationKey.startsWith("di_")) {
+    throw new Error(
+      "Use an identity integration server key from Console Settings"
+    );
+  }
+  const exchanged = await requestExchange(options, {
+    subject: options.subject,
+    previousToken: options.previousToken,
+    accounts: options.accounts
+  });
+  if (!exchanged.ok) {
+    throw await refusal(exchanged, "Domino identity exchange");
+  }
+  return participantExchangeResultSchema.parse(await exchanged.json());
+}
+async function refusal(response, what) {
+  return refusalError(response, await response.json().catch(() => null), what);
+}
+function refusalError(response, body, what) {
+  return new ParticipantExchangeError(
+    typeof body?.error === "string" ? body.error : `${what} failed with status ${response.status}`,
+    {
+      status: response.status,
+      code: typeof body?.code === "string" ? body.code : statusCode(response.status),
+      retryAfter: retryAfter(response.headers)
+    }
+  );
+}
+async function inspectIntegrationKey(options) {
+  const base = new URL(options.baseUrl);
+  if (!secureOrLoopbackOrigin(base) || base.origin !== options.baseUrl) {
+    throw new Error("Configure the exact participant API origin");
+  }
+  if (!options.integrationKey.startsWith("di_")) {
+    throw new Error(
+      "Use an identity integration server key from Console Settings"
+    );
+  }
+  const answered = await (options.fetch ?? fetch)(
+    options.baseUrl + "/v1/auth/integration",
+    {
+      method: "GET",
+      redirect: "manual",
+      headers: {
+        Authorization: "Bearer " + options.integrationKey,
+        "X-Domino-Client": clientIdentity()
+      }
+    }
+  );
+  if (!answered.ok) {
+    throw await refusal(answered, "Domino app login key check");
+  }
+  return identityIntegrationKeySchema.parse(await answered.json());
+}
 function createParticipantBackend(options) {
   const origin = new URL(options.origin);
   const base = new URL(options.baseUrl);
-  if (origin.protocol !== "https:" || origin.origin !== options.origin || base.protocol !== "https:" || base.origin !== options.baseUrl) {
+  if (!secureOrLoopbackOrigin(origin) || origin.origin !== options.origin || base.protocol !== "https:" || base.origin !== options.baseUrl) {
     throw new Error(
       "Configure exact HTTPS application and participant API origins"
     );
@@ -100,7 +200,11 @@ function createParticipantBackend(options) {
     );
   }
   const send = options.fetch ?? fetch;
-  const cookie = (token) => `domino_app_session=${token}; Path=/relay; HttpOnly; Secure; SameSite=Lax; Max-Age=${token ? 28800 : 0}`;
+  const loopback = origin.protocol === "http:";
+  const cookie = (token) => (
+    // WebKit drops a Secure cookie on http://localhost, so a loopback origin sets it without.
+    `domino_app_session=${token}; Path=/relay; HttpOnly;${loopback ? "" : " Secure;"} SameSite=Lax; Max-Age=${token ? 28800 : 0}`
+  );
   return async (request) => {
     const url = new URL(request.url);
     const reject = (error, status, code) => Response.json(
@@ -126,24 +230,26 @@ function createParticipantBackend(options) {
         }
       );
     }
-    const previousToken = request.headers.get("Cookie")?.split(";").map((value) => value.trim()).find((value) => value.startsWith("domino_app_session="))?.slice("domino_app_session=".length);
-    const exchanged = await send(options.baseUrl + "/v1/auth/exchange", {
-      method: "POST",
-      redirect: "manual",
-      headers: {
-        Authorization: "Bearer " + options.integrationKey,
-        "X-Domino-Client": clientIdentity(),
-        "Content-Type": "application/json"
-      },
-      body: JSON.stringify({ subject: identity.subject, previousToken })
+    const previousToken = onlyCookie(request.headers.get("Cookie"), "domino_app_session") ?? void 0;
+    const exchanged = await requestExchange(options, {
+      subject: identity.subject,
+      previousToken,
+      accounts: identity.accounts
     });
     if (!exchanged.ok) {
       const body = await exchanged.json().catch(() => null);
-      const code = typeof body?.code === "string" ? body.code : statusCode(exchanged.status);
-      const retryAfter = exchanged.headers.get("Retry-After");
+      const failure = refusalError(exchanged, body, "Domino identity exchange");
+      const { code } = failure;
+      const wait = exchanged.headers.get("Retry-After");
+      if (options.onExchangeError) {
+        try {
+          await options.onExchangeError(failure, request);
+        } catch {
+        }
+      }
       return Response.json(
         {
-          error: exchanged.status === 409 && typeof body?.error === "string" ? body.error : exchanged.status === 409 ? "Domino refused this account. Ask an organizer." : "Domino identity exchange failed. Check the server integration key and its expiry in Console Settings.",
+          error: (exchanged.status === 409 || code === "ACCOUNT_VOUCHING_OFF") && typeof body?.error === "string" ? body.error : exchanged.status === 409 ? "Domino refused this account. Ask an organizer." : "Domino identity exchange failed. Check the server integration key and its expiry in Console Settings.",
           code
         },
         {
@@ -151,18 +257,23 @@ function createParticipantBackend(options) {
           headers: {
             "Set-Cookie": cookie(""),
             "Cache-Control": "no-store",
-            ...retryAfter ? { "Retry-After": retryAfter } : {}
+            ...wait ? { "Retry-After": wait } : {}
           }
         }
       );
     }
-    const { token } = exchangeResultSchema.parse(await exchanged.json());
+    const { token, accounts } = participantExchangeResultSchema.parse(
+      await exchanged.json()
+    );
+    if (accounts?.length && options.onAccounts) {
+      await options.onAccounts(accounts, request);
+    }
     const response = await proxyParticipant(request, {
       baseUrl: options.baseUrl,
       fetch: async (target, init) => {
         const headers2 = new Headers(init?.headers);
         headers2.delete("Cookie");
-        const returnBinding = request.headers.get("Cookie")?.split(";").map((value) => value.trim()).find((value) => value.startsWith("relay_auth_return="));
+        const returnBinding = oauthReturnBinding(request.headers.get("Cookie"));
         if (returnBinding) {
           headers2.set("Cookie", returnBinding);
         }
@@ -180,6 +291,19 @@ function createParticipantBackend(options) {
     return new Response(response.body, { status: response.status, headers });
   };
 }
+function onlyCookie(header, name) {
+  const values = (header ?? "").split(";").map((value) => value.trim()).filter((value) => value.startsWith(name + "="));
+  return values.length === 1 ? values[0].slice(name.length + 1) : null;
+}
+function oauthReturnBinding(header) {
+  for (const name of ["__Host-relay_auth_return", "relay_auth_return"]) {
+    if (header?.split(";").some((value) => value.trim().startsWith(name + "="))) {
+      const value = onlyCookie(header, name);
+      return value === null ? null : `${name}=${value}`;
+    }
+  }
+  return null;
+}
 function hostedAppRequest(request, env) {
   if (!env.DOMINO_PREVIEW_ORIGIN) {
     return request;
@@ -237,11 +361,15 @@ async function signedInMember(request, env, options) {
   );
   return session.success ? sessionMember(session.data) : null;
 }
-var signedInSessionSchema = z.object({ principal: participantPrincipalSchema }).nullable();
+var signedInSessionSchema = /* @__PURE__ */ (() => z.object({ principal: participantPrincipalSchema }).nullable())();
 export {
+  ParticipantExchangeError,
   createParticipantBackend,
+  exchangeParticipant,
   handleHostedApp,
   hostedAppRequest,
+  inspectIntegrationKey,
+  isParticipantExchangeError,
   proxyParticipant,
   signedInMember
 };