@domino-sdk/relay-cli 0.2.0 → 0.3.0

package/cli/capabilities.json

@@ -14,6 +14,17 @@
       ],
       "evidence": ["tests/auth.test.mjs", "tests/email-auth.test.mjs"]
     },
+    {
+      "id": "identity-exchange",
+      "support": "native",
+      "description": "Keep an existing application login using createParticipantBackend on its server. A Console administrator creates a project/environment identity integration key. The adapter verifies the application session, exchanges its stable subject for a member-only Domino session, and routes participant requests with trusted scope. Keys expire after 90 days and support rotation and revocation.",
+      "entrypoints": [],
+      "reference": "participant-api",
+      "evidence": [
+        "tests/identity-integration.test.mjs",
+        "apps/api/src/identity-integration.ts"
+      ]
+    },
     {
       "id": "quests",
       "support": "native",

package/cli/doctor.mjs

@@ -182,12 +182,13 @@ export async function diagnose({ project, connection, options }) {
         id: "remote-access",
         status: "ok",
         message:
-          "Management API verified project access. This does not verify participant sign-in or publication permission.",
+          "Management API verified project access. This does not verify participant sign-in or publication permission. Management credentials cannot issue participant sessions. Existing-login integration requires a dedicated server key and createParticipantBackend; run domino capabilities identity-exchange.",
       });
       const preflight = await request(connection, "/preflight");
       readiness = {
         development: preflight.development,
         staging: preflight.staging,
+        identity: preflight.identity ?? { exchange: "unknown" },
       };
       if (project.config.app)
         checks.push({

package/cli/skills/domino/references/existing-app.md

@@ -12,8 +12,10 @@ Add the SDK to the package that owns the authored modules using the app's packag
 
 For participant UI, inspect the installed `@domino-sdk/relay` and `@domino-sdk/relay/browser` exports. Use the supplied quest controllers for submissions, recovery, and changed rules. Keep stable quest IDs and collection slots. Participants explicitly review changed rules before resubmitting.
 
-Keep the application's existing login. Map its authenticated user through a supported trusted backend identity integration. Determine the server credential and allowed project scope before implementing that exchange. Browser-provided user IDs are not verified identities. Management tokens belong only on trusted servers or in CLI credentials, never browser bundles.
+Keep the application's existing login using `createParticipantBackend` on its server. Read [participant authentication and routing](participant-api.md) for the complete route example. Implement `authenticate(request)` using the app's existing server session verifier and return its stable user ID. Never accept a user ID from browser input as proof of identity.
 
-For same-origin participant routing, inspect `@domino-sdk/relay/portal-proxy` and the app's server route conventions. Its proxy allowlist excludes management routes. Verify session transport, sign-in callbacks where relevant, and a participant action through that boundary. If production identity provisioning is unavailable, report that dependency explicitly and keep the demonstration scoped to test.
+An organization administrator creates an identity integration in Console Settings, under "Use your app's login", for the selected project and environment. The user saves the shown key directly in the application's server secret settings as DOMINO_IDENTITY_KEY. The key is shown once; keep it out of agent chat, source control and browser bundles. CLI and personal management credentials cannot create these keys or substitute for them. Readiness requires the deployed API and SDK versions supporting `identity-exchange`; a legacy 404 is an upgrade issue.
+
+Mount the adapter at `/relay/*` and use `createBrowserRelayClient({ baseUrl: "/relay" })`. Verify a signed-in session, one participant action, and that logging out of the application removes access. The adapter checks application authentication on every request and derives project scope from the integration key. No custom fetch wrapper or browser project headers are needed.
 
 Read [authoring](authoring.md) when adding quests or collection slots. Run the app's normal checks and development server. Use its existing preview deployment process when available. `domino deploy` publishes Domino behavior; it does not deploy the app. `domino stage` requires a supported Domino-hosted static repository, so it is not a general deployment command for existing apps.

package/cli/skills/domino/references/participant-api.md

@@ -1,11 +1,47 @@
 # Participant API
 
-Create `createBrowserRelayClient({ baseUrl: "/relay" })` from `@domino-sdk/relay/browser`. The browser client uses cookies and durable submission recovery. The app's server must route `/relay` through the supported participant proxy. Keep management tokens on the server.
+Create `createBrowserRelayClient({ baseUrl: "/relay" })` from `@domino-sdk/relay/browser`. The browser client uses cookies and durable submission recovery. The app's server must route `/relay` through the supported participant proxy. Management tokens are not participant credentials.
 
 ## Sign in
 
 Call `relay.auth.providers()` to discover configured providers and email availability. For OAuth, call `relay.auth.start(provider, "sign-in")` and navigate to its returned `url`. For email, call `emailStart(email)`, then `emailVerify(challenge, code)` using the returned challenge. `auth.session()` returns the current session or null. `auth.signOut()` clears the session.
 
+Email codes and OAuth consent belong to the participant. Let the user complete sign-in in their browser, then verify the resulting session and action. When that has not happened, report sign-in as unverified.
+
+## Existing application login
+
+Mount this handler on the application's **server** at `/relay/*`. Use the app's existing session verifier. Its subject must be a stable, non-recycled account ID, not an email or browser-submitted value.
+
+```ts
+import { createParticipantBackend } from "@domino-sdk/relay/portal-proxy";
+import { verifyAppSession } from "./your-existing-server-auth";
+
+export const participant = createParticipantBackend({
+  baseUrl: "https://relay.domino.run",
+  origin: "https://app.example.com",
+  integrationKey: process.env.DOMINO_IDENTITY_KEY!,
+  authenticate: async (request) => {
+    const user = await verifyAppSession(request);
+    return user ? { subject: user.id } : null;
+  },
+});
+// Wire your framework's GET and POST /relay/* handlers to participant(request).
+```
+
+A Console organization administrator selects the project and environment, opens Settings → Use your app's login, and registers the exact HTTPS application origin. Save the key directly in server secret settings. It is shown once and expires in 90 days. "Replace key" immediately disables the old key while preserving participant identities. "Disconnect" invalidates its sessions too. Recreating an integration creates a new identity namespace; rotate the existing integration to preserve identity continuity.
+
+The adapter authenticates the app's session on every request. It exchanges the verified subject using the dedicated integration key, reuses a matching participant session, and keeps its token in a Secure, HttpOnly cookie. Account switching cannot reuse another user's participant session. Application logout removes access on the next request. Use the application's login/logout UI; this adapter does not expose Domino email or OAuth login flows or account linking.
+
+The browser still uses `createBrowserRelayClient({ baseUrl: "/relay" })`. Requests must reach the server with the configured HTTPS origin. Mutation requests require the matching Origin and X-Relay-CSRF headers, supplied by the browser client. Never cache these responses.
+
+`doctor --remote` checks management and hosting configuration, not the app's session verifier or integration key. Verify `auth.session()`, a participant action, and access after application logout. CLI credentials and personal management tokens are not identity integration keys.
+
+## Server routing and scope
+
+The adapter uses `POST /v1/auth/exchange` with `{ subject, previousToken? }` and the integration key as a server bearer credential. Scope and the member role come from the registered integration, never from request input. It adds a server-only integration header when proxying participant requests. A plain exchange result is not a substitute for configuring that routing; use the adapter.
+
+`https://console.domino.run/relay` proxies management requests only. Use the participant API origin for the adapter. The lower-level `proxyParticipant` remains available for deployments with preconfigured participant routing; it deliberately excludes browser Authorization and organization/project/environment selectors.
+
 ## Display and complete quests
 
 Use `relay.quests.observe(listener)` for the participant's experience. Render the observation's state; dispose the observer when the view unmounts. Read `relay.quests.experience()` for a single snapshot. Open a returned QuestView with `await relay.quests.open(view)`.

package/cli/skills/domino/references/troubleshooting.md

@@ -9,3 +9,5 @@ Start with `domino doctor --json`. Add `--remote` to verify project access, publ
 For compatibility reports, include `domino --version`, `.domino/release.json`, the lockfile, the command and its error. Exclude credentials and private participant data. Install the starter with its frozen lockfile. `release.json` records package versions and archive hashes; matching version strings alone do not establish that locally modified packages match.
 
 If development reports unknown catalog fields at `/releases/batch`, the CLI is using an obsolete startup contract. Upgrade to the corrected CLI. Complete deployment bundles belong at `/deployments/preview`, followed by `/deployments/publish` using the returned ID. Do not strip fields from a user's bundle as a permanent workaround.
+
+For existing-login failures, read `domino capabilities identity-exchange` and `domino reference participant-api`. Use a dedicated `di_` identity integration key from Console Settings. A 401 means the key or participant session is invalid, expired, revoked, or belongs to another integration. A 400 rejects malformed input, including attempted scope or role overrides. A 429 asks the server to retry later. Older APIs return 404; upgrade the deployment. The Console `/relay` URL remains management-only. The user's application must use the participant API origin through `createParticipantBackend`.

package/dist/index.d.ts

@@ -90,6 +90,10 @@ declare const developmentPreflightSchema: z.ZodObject<{
         test: "test";
         live: "live";
     }>;
+    identity: z.ZodOptional<z.ZodObject<{
+        exchange: z.ZodLiteral<"supported">;
+        activeIntegrations: z.ZodNumber;
+    }, z.core.$strip>>;
     staging: z.ZodEnum<{
         blocked: "blocked";
         configured: "configured";

package/dist/index.js

@@ -120,6 +120,10 @@ var developmentPreflightSchema = z2.object({
   organization: z2.string(),
   project: z2.string(),
   environment: z2.enum(["test", "live"]),
+  identity: z2.object({
+    exchange: z2.literal("supported"),
+    activeIntegrations: z2.number().int().nonnegative()
+  }).optional(),
   staging: z2.enum(["configured", "blocked"]),
   development: z2.object({
     status: z2.enum(["configured", "blocked"]),

package/package.json

@@ -10,9 +10,9 @@
   "dependencies": {
     "commander": "15.0.0",
     "zod": "4.3.6",
-    "@domino-sdk/relay": "0.2.0"
+    "@domino-sdk/relay": "0.3.0"
   },
-  "version": "0.2.0",
+  "version": "0.3.0",
   "bin": {
     "domino": "./cli.mjs"
   },