@isomorph.ai/app-sdk 1.5.3 → 1.6.1

package/README.md

@@ -95,3 +95,21 @@ same way: its refresh ends at the identity GET, so that answer is the identity
 and no second GET is sent. When the refresh fails, `identity.current()`
 answers `null` and listeners hear `null`, as before. On the page's own origin
 the identity GET is never renewed (it is the renewal). (1.5.3)
+
+## The signed-in user's groups
+
+`user.groups` — the company groups your identity provider sent at sign-in; use
+for in-app roles. App access itself is enforced before your code runs.
+
+It is on `identity.current()`, `identity.onChange` and an action's `ctx.user`,
+and it is always an array (`[]` when the identity provider sent none):
+
+```ts
+// actions/approve.ts
+export default async function approve(input: { id: string }, ctx: { user: { groups: string[] } }) {
+  if (!ctx.user.groups.includes('Finance')) throw new Error('Only Finance can approve.');
+  // ...
+}
+```
+
+(1.6.0)

package/dist/index.d.ts

@@ -12,6 +12,12 @@ export declare class IsomorphError extends Error {
 export interface IsomorphUser {
     id: string;
     email: string;
+    /**
+     * The company groups your identity provider sent at sign-in, `[]` when it
+     * sent none. Use them for in-app roles: who may open the app at all is
+     * enforced before your code runs.
+     */
+    groups: string[];
     appUser?: unknown;
 }
 export interface IsomorphResult<T> {

package/dist/index.js

@@ -1,4 +1,5 @@
 import { validateIntegrationExecuteInput } from './integration-execute-input-rules.js';
+import { userGroups } from './user-groups.js';
 export class IsomorphError extends Error {
     category;
     requestId;
@@ -354,6 +355,12 @@ export function createClient(options = {}) {
             for (const listener of authListeners)
                 listener(user);
     };
+    // The gateway's answer becomes an IsomorphUser in place: the same object
+    // must reach every caller (the API-host refresh below relies on it).
+    const withGroups = (user) => {
+        user.groups = userGroups(user.groups);
+        return user;
+    };
     const transport = new Transport(options, () => notifyIdentity(null));
     const socketFactory = options.websocket ?? ((url) => defaultSocketFactory(url, options.identity));
     const refreshIdentity = () => {
@@ -361,7 +368,8 @@ export function createClient(options = {}) {
             return refreshInFlight;
         refreshesStarted += 1;
         refreshInFlight = transport.json(IDENTITY_PATH)
-            .then((user) => {
+            .then((answer) => {
+            const user = answer === null ? null : withGroups(answer);
             // A user answered by the API host's context refresh was announced by
             // that refresh already (it is the same object): once is enough.
             if (user === null || user !== currentUser)
@@ -412,7 +420,7 @@ export function createClient(options = {}) {
                 const user = (await response.json())?.data;
                 if (typeof user?.id !== 'string')
                     return false;
-                notifyIdentity(user, true);
+                notifyIdentity(withGroups(user), true);
                 return user;
             })
                 .catch(() => false)
@@ -665,8 +673,11 @@ export function createClient(options = {}) {
                     method: 'POST', body: JSON.stringify({ connection, operation, resource, ...(input !== undefined ? { input } : {}), ...(idempotencyKey !== undefined ? { idempotencyKey } : {}), ...(operation === 'slack.message.post' && mode !== undefined ? { mode } : {}) }),
                 });
             },
+            // In a browser the consent returns the person to this page (without its
+            // fragment); governance accepts it only as a registered page of this app
+            // (ADR 0030). Outside a browser there is no page, and none is sent.
             connect: (connection) => transport.json('/_harbour/integrations/connect', {
-                method: 'POST', body: JSON.stringify({ connection }),
+                method: 'POST', body: JSON.stringify({ connection, ...(typeof location !== 'undefined' && typeof location.href === 'string' ? { returnUrl: location.href.split('#')[0] } : {}) }),
             }),
             disconnect: (connection) => transport.json('/_harbour/integrations/connect', {
                 method: 'DELETE', body: JSON.stringify({ connection }),

package/dist/runtime.d.ts

@@ -1,5 +1,5 @@
 import { type IncomingMessage, type ServerResponse } from 'node:http';
-import { type IsomorphClient, type JobRun } from './index.js';
+import { type IsomorphClient, type IsomorphUser, type JobRun } from './index.js';
 export declare const ACTIONS_DIR = "actions";
 export declare const JOBS_DIR = "jobs";
 export declare const RUNS_TABLE = "isomorph_job_runs";
@@ -10,10 +10,7 @@ export declare const GET_RUN_ACTION = "isomorph-jobs-get";
 export declare const CANCEL_RUN_ACTION = "isomorph-jobs-cancel";
 export interface ActionContext {
     signal: AbortSignal;
-    user: {
-        id: string;
-        email: string;
-    };
+    user: Pick<IsomorphUser, 'id' | 'email' | 'groups'>;
     tenant: string;
     app: string;
     requestId: string;

package/dist/runtime.js

@@ -56,6 +56,7 @@ import { register } from 'node:module';
 import { join, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { createClient, IsomorphError } from './index.js';
+import { userGroupsFromHeader } from './user-groups.js';
 const actionIdentity = new AsyncLocalStorage();
 const identityKey = Symbol.for('isomorph.actionIdentity');
 globalThis[identityKey] = () => actionIdentity.getStore();
@@ -495,7 +496,12 @@ export class Runtime {
         const controller = new AbortController();
         const abort = () => controller.abort();
         response.once('close', abort);
-        const context = { signal: controller.signal, user: { id: header(request, 'X-Harbour-Verified-User-ID'), email: header(request, 'X-Harbour-Verified-User-Email') }, tenant, app, requestId: requestId ?? '' };
+        const user = {
+            id: header(request, 'X-Harbour-Verified-User-ID'),
+            email: header(request, 'X-Harbour-Verified-User-Email'),
+            groups: userGroupsFromHeader(header(request, 'X-Harbour-Verified-User-Groups')),
+        };
+        const context = { signal: controller.signal, user, tenant, app, requestId: requestId ?? '' };
         const raw = await readBody(request);
         if (raw === undefined)
             return refuse(response, 413, 'VALIDATION_FAILED', 'the request body is larger than 1 MiB', requestId);

package/dist/user-groups.d.ts

@@ -0,0 +1,2 @@
+export declare function userGroups(value: unknown): string[];
+export declare function userGroupsFromHeader(raw: string): string[];

package/dist/user-groups.js

@@ -0,0 +1,16 @@
+// The signed-in user's company groups, as the platform hands them over: a
+// JSON array in the gateway's current-user answer (`groups`) and in the
+// X-Harbour-Verified-User-Groups header on an action. Anything else — a
+// missing or malformed value, a non-string or empty entry — reads as no
+// group, so `user.groups` is always an array of names.
+export function userGroups(value) {
+    return Array.isArray(value) ? value.filter((group) => typeof group === 'string' && group !== '') : [];
+}
+export function userGroupsFromHeader(raw) {
+    try {
+        return userGroups(JSON.parse(raw));
+    }
+    catch {
+        return [];
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@isomorph.ai/app-sdk",
-  "version": "1.5.3",
+  "version": "1.6.1",
   "type": "module",
   "repository": {
     "type": "git",