@cosmoops/connect-sdk 0.9.0 → 0.16.0

package/dist/esm/server/handler.js

@@ -164,34 +164,143 @@ export function createConnectHandler(options) {
     async function whoami(request) {
         return client.identity.getUser(await requireToken(request));
     }
+    /**
+     * The caller's identity, plus the workspace every tenant-scoped route below
+     * needs - refusing the one session kind that has no workspace.
+     *
+     * A Connect **platform staff** session (`staff === true`) carries
+     * `workspaceId === null` by design: those accounts belong to no
+     * workspace, so entitlements, add-on balances, integrations, the AI context
+     * index and the data store have no tenant to read. Before this existed the
+     * type said `string` and the question never came up; now that it can, the
+     * only two answers are "refuse" and "let the request name a tenant" - and
+     * the second is precisely what this bridge exists to prevent.
+     *
+     * So: staff sign in, `/session` answers, and every workspace-scoped route
+     * refuses. An operator console reads `staff`/`role`/`permissions` and talks
+     * to your own backend for anything tenant-shaped.
+     */
+    async function requireWorkspace(request) {
+        const session = await whoami(request);
+        const workspaceId = session.user.workspaceId;
+        if (workspaceId === null) {
+            throw new ConnectError({
+                status: 403,
+                code: "no_workspace",
+                message: "This session has no workspace - platform staff sessions cannot read workspace data",
+                endpoint: new URL(request.url).pathname,
+            });
+        }
+        return { ...session, workspaceId };
+    }
+    /**
+     * The store paths a browser may reach through the bridge.
+     *
+     * Documents, the key/value store, aggregations and atomic commits.
+     * **`/data-scan/` is deliberately absent**: a scan crosses every tenant, and
+     * Connect refuses one made on behalf of a user - but a browser should not be
+     * able to *ask*, so the refusal happens here rather than a round trip away.
+     * `storePassthrough` enforces the same set at the other end.
+     */
+    function isStoreRoute(route) {
+        return (route.startsWith("/data/") ||
+            route.startsWith("/kv/") ||
+            route.startsWith("/data-aggregate/") ||
+            route === "/data-commit");
+    }
+    /**
+     * Forwards one store call to Connect on behalf of the caller.
+     *
+     * Deliberately a thin relay of *path and body*, with the two things that
+     * decide access supplied here and never taken from the request: the session
+     * token, read from the partner's own session store, and the workspace, read
+     * from that session's identity. Connect re-derives both from the token
+     * anyway - this bridge is not trusted - but sending a client-supplied
+     * workspace even as an ignored field is the kind of thing that stops being
+     * ignored after a refactor.
+     *
+     * Paths are matched by prefix upstream and passed through unparsed; Connect
+     * validates every segment against the application's declared schema, so
+     * there is nothing useful for this layer to check and nothing it could check
+     * more strictly.
+     */
+    async function storeRoute(request) {
+        const token = await requireToken(request);
+        // Same refusal as every other tenant-scoped route - the store is a
+        // workspace's own data, and a staff session names no workspace. Note the
+        // token is still read first: this must fail as "no workspace", not as
+        // "no session".
+        const { workspaceId } = await requireWorkspace(request);
+        const url = new URL(request.url);
+        const route = (url.pathname.startsWith(basePath)
+            ? url.pathname.slice(basePath.length)
+            : url.pathname).replace(/\/+$/, "");
+        const query = new URLSearchParams(url.search);
+        query.set("workspaceId", workspaceId);
+        const body = request.method === "GET" || request.method === "DELETE"
+            ? undefined
+            : { ...(await request.json().catch(() => ({}))), workspaceId };
+        return client.storeRelay({
+            method: request.method,
+            path: `${route}?${query.toString()}`,
+            json: body,
+            headers: {
+                "x-connect-session-token": token,
+                // Forwarded because it is the one request header that changes what the
+                // write means, and dropping it would silently turn every merge into a
+                // replace.
+                ...(request.headers.get("x-store-write-mode")
+                    ? { "x-store-write-mode": request.headers.get("x-store-write-mode") }
+                    : {}),
+            },
+        });
+    }
     const routes = {
         "GET /session": async (request) => {
             const token = await session.read(request);
             // Signed out is a normal state for a page rendering a Login button, not
             // an error - `user: null` rather than a 401 the client must catch.
-            if (!token)
-                return json({ user: null, subscription: null, applicationRole: null });
+            // Signed out carries the same three access fields as a live session, so
+            // the client never has to tell "signed out" from "signed in with no
+            // role" by which keys happen to be present.
+            if (!token) {
+                return json({ user: null, subscription: null, role: null, permissions: [], staff: false });
+            }
             return json(await client.identity.getUser(token));
         },
         "GET /entitlements": async (request) => {
-            const { user } = await whoami(request);
+            const { workspaceId } = await requireWorkspace(request);
             const [readiness, subscription] = await Promise.all([
-                client.entitlements.getReadiness(user.workspaceId),
-                client.entitlements.getSubscription(user.workspaceId),
+                client.entitlements.getReadiness(workspaceId),
+                client.entitlements.getSubscription(workspaceId),
             ]);
             return json({ readiness, subscription });
         },
         "GET /plans": async () => json(await client.billing.listPlans()),
+        /**
+         * The platform's legal identity and grievance channel.
+         *
+         * The only route here that takes neither a session nor a workspace, and
+         * the only one where that is correct rather than a hole: the answer is a
+         * fact about the platform operator, identical for every caller, and
+         * already published on the public web. There is nothing to scope it to.
+         *
+         * Left unauthenticated on purpose. Requiring a session would mean a
+         * signed-out visitor reading your privacy page could not be shown the
+         * grievance officer to complain to - which is the one moment the notice
+         * most needs to be legible.
+         */
+        "GET /company-profile": async () => json({ companyProfile: await client.platform.getCompanyProfile() }),
         // Workspace comes from the caller's own session, same as every other
         // route here - a browser must not be able to ask what another workspace
         // has left.
         "GET /addons": async (request) => {
-            const { user } = await whoami(request);
-            return json(await client.billing.getAddonUsage(user.workspaceId));
+            const { workspaceId } = await requireWorkspace(request);
+            return json(await client.billing.getAddonUsage(workspaceId));
         },
         "GET /apps": async (request) => {
-            const { user } = await whoami(request);
-            return json({ apps: await client.apps.list(user.workspaceId) });
+            const { workspaceId } = await requireWorkspace(request);
+            return json({ apps: await client.apps.list(workspaceId) });
         },
         /**
          * Ask AI. The one streaming route here, and the only one that does not
@@ -209,7 +318,7 @@ export function createConnectHandler(options) {
          * validates it again on arrival.
          */
         "POST /ai/chat": async (request) => {
-            const { user } = await whoami(request);
+            const { workspaceId } = await requireWorkspace(request);
             const body = (await request.json().catch(() => null));
             if (!Array.isArray(body?.messages)) {
                 throw new ConnectError({
@@ -220,8 +329,19 @@ export function createConnectHandler(options) {
                 });
             }
             const upstream = await client.ai.chat({
-                workspaceId: user.workspaceId,
+                workspaceId: workspaceId,
                 messages: body.messages,
+                // Forwarded unvalidated on purpose. These are your application's own
+                // description of itself and of where the user is - Connect bounds and
+                // sanitises them on arrival, and uses them only to write the answer and
+                // to validate action links. Nothing here reaches an authorization
+                // decision, so there is nothing for this layer to check more strictly.
+                screenContext: body.screenContext,
+                screens: body.screens,
+                // Connect re-derives the workspace from this token, so the line above
+                // is belt to its braces - the browser cannot reach another tenant's
+                // Context Index even if this route were changed to trust the request.
+                asUser: await requireToken(request),
             });
             // `upstream.body` is piped, never buffered - awaiting it would collect
             // the whole answer server-side and deliver it in one lump, which is the
@@ -236,12 +356,68 @@ export function createConnectHandler(options) {
                 },
             });
         },
+        /**
+         * The store, forwarded.
+         *
+         * These are the only bridge routes with a *dynamic* path, and the only
+         * ones that forward a browser-supplied body to Connect. Both are safe for
+         * the same reason the rest of the bridge is: the caller's session token
+         * goes with the request as `asUser`, and Connect derives the user, their
+         * workspace and their permissions from it - so a browser cannot name
+         * another tenant, cannot claim a permission it does not hold, and cannot
+         * reach a collection this application never declared.
+         *
+         * `workspaceId` is still sent because the wire contract requires one, but
+         * Connect ignores it whenever a session token is present. It is filled
+         * from `whoami()` rather than the request either way, so this route never
+         * relays a client-supplied workspace even to be discarded.
+         */
+        "STORE": async (request) => storeRoute(request),
+        /**
+         * The workspace switcher's three reads, forwarded with the caller's own
+         * session token.
+         *
+         * `POST /workspaces/switch` is the only bridge route that *changes the
+         * caller's session*, so it writes the new token back through the same
+         * `session.write` the OAuth callback uses. Handing the raw token to the
+         * browser instead would put a credential in JavaScript's hands, which is
+         * exactly what this bridge exists to avoid - the browser gets the new
+         * workspace's name and a `Set-Cookie`, never the token itself.
+         *
+         * A partner with no `session.write` cannot re-persist a rotated token, so
+         * switching is simply absent for them rather than half-working - the same
+         * treatment `/signin` and `/callback` already get.
+         */
+        "GET /workspaces": async (request) => json({ workspaces: await client.workspaces.list({ asUser: await requireToken(request) }) }),
+        "GET /workspaces/members": async (request) => json({ members: await client.workspaces.members({ asUser: await requireToken(request) }) }),
+        "POST /workspaces/switch": async (request) => {
+            const token = await requireToken(request);
+            const body = (await request.json().catch(() => null));
+            if (typeof body?.workspaceId !== "string") {
+                throw new ConnectError({
+                    status: 400,
+                    code: "validation_error",
+                    message: "workspaceId is required",
+                    endpoint: "POST /workspaces/switch",
+                });
+            }
+            const result = await client.workspaces.switch({ workspaceId: body.workspaceId }, { asUser: token });
+            // The response is built first so `session.write` has something to set
+            // cookies on, matching how `/callback` does it.
+            const response = json({
+                workspaceId: result.workspaceId,
+                workspaceName: result.workspaceName,
+                workspaceType: result.workspaceType,
+            });
+            await session.write?.(request, response, result.sessionToken);
+            return response;
+        },
         "GET /integrations": async (request) => {
-            const { user } = await whoami(request);
-            return json({ toolkits: await client.integrations.list(user.workspaceId) });
+            const { workspaceId } = await requireWorkspace(request);
+            return json({ toolkits: await client.integrations.list(workspaceId) });
         },
         "POST /integrations/connect": async (request) => {
-            const { user } = await whoami(request);
+            const { workspaceId } = await requireWorkspace(request);
             const body = (await request.json().catch(() => null));
             if (!body?.toolkitSlug || !body?.returnUrl) {
                 throw new ConnectError({
@@ -251,10 +427,10 @@ export function createConnectHandler(options) {
                     endpoint: "POST /integrations/connect",
                 });
             }
-            return json(await client.integrations.initiateConnect(user.workspaceId, body.toolkitSlug, body.returnUrl));
+            return json(await client.integrations.initiateConnect(workspaceId, body.toolkitSlug, body.returnUrl));
         },
         "POST /integrations/disconnect": async (request) => {
-            const { user } = await whoami(request);
+            const { workspaceId } = await requireWorkspace(request);
             const body = (await request.json().catch(() => null));
             if (!body?.toolkitSlug) {
                 throw new ConnectError({
@@ -264,7 +440,7 @@ export function createConnectHandler(options) {
                     endpoint: "POST /integrations/disconnect",
                 });
             }
-            await client.integrations.disconnect(user.workspaceId, body.toolkitSlug);
+            await client.integrations.disconnect(workspaceId, body.toolkitSlug);
             return json({ ok: true });
         },
         // Account-wide, not scoped to this application - see `SessionsResource`'s
@@ -407,11 +583,20 @@ export function createConnectHandler(options) {
     if (!session.write) {
         delete routes["GET /signin"];
         delete routes["GET /callback"];
+        // A switch rotates the session token. Without somewhere to persist the new
+        // one, the old one would be revoked and the user silently signed out - so
+        // the route does not exist rather than working once and breaking.
+        delete routes["POST /workspaces/switch"];
     }
     return async function handle(request) {
         const path = new URL(request.url).pathname;
         const route = (path.startsWith(basePath) ? path.slice(basePath.length) : path).replace(/\/+$/, "") || "/";
-        const handler = routes[`${request.method} ${route}`];
+        const handler = routes[`${request.method} ${route}`] ??
+            // Store routes carry ids in the path, so they cannot be keyed by an
+            // exact string. Matched by prefix, and only this closed set - the bridge
+            // is deliberately not a generic proxy, and a broader fallback here is
+            // exactly how it would become one.
+            (isStoreRoute(route) ? routes.STORE : undefined);
         if (!handler) {
             return json({ error: { code: "not_found", message: `No Connect bridge route for ${route}` } }, 404);
         }

package/dist/esm/server/http.js

@@ -76,7 +76,8 @@ const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
  * `ConnectError`.
  *
  * **On retries.** Only idempotent requests are retried without a caller
- * opt-in: every `GET`, plus any `POST` carrying an `Idempotency-Key` (the
+ * opt-in: every `GET`, `PUT` and `DELETE`, plus any `POST` carrying an
+ * `Idempotency-Key` (the
  * resources that mutate - `billing.consumeAddon`, `otp.send` - always set
  * one). A bare `POST` is attempted exactly once, because a 429 or a 504 says
  * nothing about whether the server already did the work.
@@ -114,7 +115,10 @@ export async function request(options, spec) {
         headers["content-type"] = "application/json";
         body = JSON.stringify(spec.json);
     }
-    const idempotent = spec.method === "GET" || headers["idempotency-key"] !== undefined;
+    // `PUT` and `DELETE` are idempotent by definition - replaying one lands the
+    // same end state - so they retry like `GET`. `POST` still needs an
+    // `Idempotency-Key` to earn it, because a replayed create is a second row.
+    const idempotent = spec.method !== "POST" || headers["idempotency-key"] !== undefined;
     const attempts = idempotent ? options.maxRetries + 1 : 1;
     let lastError;
     for (let attempt = 0; attempt < attempts; attempt++) {

package/dist/esm/server/resources/acting-as.js

@@ -0,0 +1,13 @@
+/**
+ * The header that turns a server-to-server store call into one made *on behalf
+ * of* a signed-in user.
+ *
+ * Connect resolves the token to a user and a workspace itself and checks the
+ * collection's declared permission against that member's live roles - so a
+ * caller supplying this is asking for a *narrower* check than an application
+ * call, never a wider one. An unresolvable token is refused rather than
+ * quietly downgraded, precisely because the downgrade would be an escalation.
+ */
+export function actingAs(sessionToken) {
+    return sessionToken ? { "x-connect-session-token": sessionToken } : {};
+}

package/dist/esm/server/resources/ai.js

@@ -1,5 +1,13 @@
+import { actingAs } from "./acting-as.js";
 import { request } from "../http.js";
-/** RAG chat and structured extraction against a workspace's data. */
+/**
+ * RAG chat and structured extraction against a workspace's data.
+ *
+ * `asUser` on `chat` behaves as it does on the store resources: pass a
+ * signed-in user's `sessionToken` and Connect resolves the workspace from it,
+ * ignoring `workspaceId`. Without it you are the application, naming the
+ * workspace yourself.
+ */
 export class AiResource {
     transport;
     constructor(transport) {
@@ -15,7 +23,19 @@ export class AiResource {
         return request(this.transport, {
             method: "POST",
             path: "/ai/chat",
-            json: input,
+            // `asUser` never reaches the body - it is a credential, and Connect reads
+            // it from the header. Passing a signed-in user's session token makes
+            // Connect derive the workspace from *that* rather than from
+            // `workspaceId`, which is what the bridge relies on.
+            json: {
+                workspaceId: input.workspaceId,
+                messages: input.messages,
+                // Omitted entirely when absent, rather than sent as `undefined` - an
+                // application that describes no screens should send no field.
+                ...(input.screens ? { screens: input.screens } : {}),
+                ...(input.screenContext ? { screenContext: input.screenContext } : {}),
+            },
+            headers: actingAs(input.asUser),
             raw: true,
             signal: options.signal,
         });