@isomorph.ai/app-sdk 2.7.0 → 2.8.0

package/README.md

@@ -392,6 +392,30 @@ await isomorph.actions.invokePublic('signup', { email });
 
 (2.6.0)
 
+## Calling another app as the signed-in person
+
+An action calls another app of the company as the person who started it, with no credential:
+
+```ts
+// actions/my-account.ts in the Candidate Portal
+export default async function myAccount(_input: unknown) {
+  return isomorph.apps.invoke('shadowfax-ats', 'portal-account', { version: 2, operation: 'me' });
+}
+```
+
+The other app (named by its address, as `appApiUrl` takes it) lists this one in its `.isomorph/app.json`:
+`"callers": [{ "app": "candidate-portal", "actions": ["portal-account", "portal-*"] }]`. A pattern never reaches a
+trusted action; name a trusted action exactly. Its action sees the person in `ctx.user` (role `member`) and this app
+in `ctx.caller = { app, environment }` (`app` is the calling app's id; `local` under `isomorph dev` and
+`isomorph check`, where `app` is the calling address). `ctx.caller` is absent on its own pages, service and MCP calls.
+The call goes through this app's own gateway with the workload token and the person's context; a refusal is an
+`IsomorphError` with the gateway's category (`AUTH_REQUIRED`, `FORBIDDEN` when not listed, `NOT_FOUND`,
+`RATE_LIMITED`). It works only from an action a signed-in person started: a job keeps using a service credential.
+A journey of the called app plays the caller with a POST to `/_harbour/api/<action>` carrying
+`X-Harbour-Call-Host: <caller address>` and one of the check's identity tokens as the bearer.
+
+(2.8.0; data plane ADR 2026-11-07)
+
 ## Browser read tools
 
 Install optional peers `ai` and `playwright-core@1.58.2`. Locally run `npx playwright-core install chromium --only-shell`; V2 packages Chromium in the existing app image. An existing system executable can be supplied as executablePath.
@@ -588,6 +612,14 @@ 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)
 
+When the renewal cannot restore the sign-in — the refresh failed, or the
+resend was refused again — the session has ended (a platform operator's
+session never renews; any session ends at its lifetime). That refusal's
+message is `Your sign-in has ended. Reload the page to sign in again.`, which
+you can show as is; its `category` (`AUTH_REQUIRED`), `status` (401),
+`requestId` and `details` are unchanged, so branch on `category`. A 401 your
+own action or a connected service gave keeps its own message. (2.7.1)
+
 ## External OTP users
 
 Use `user.id` for ownership and database row rules. External users can sign in with a phone number and have no email. `user.name`, `user.phone`, `user.email` and the `emailVerified`/`phoneVerified` flags describe their profile; an optional contact is not verified automatically. `user.directory` identifies `company` or `external`. Database transactions also expose `current_setting('harbour.directory', true)` when a row rule needs that distinction.

package/dist/index.d.ts

@@ -1953,6 +1953,10 @@ export interface ActionIdentity {
     trusted: boolean;
     transactionId?: string;
     baseUrl?: string;
+    /** The request id the action runs under, which a call to another app carries on. */
+    requestId?: string;
+    /** Brings ISOMORPH_WORKLOAD_TOKEN up to date (a serverless runtime's session is renewed on demand). */
+    workloadToken?: () => Promise<void>;
 }
 interface IdentityRenewal {
     renewals(): number;
@@ -2084,6 +2088,19 @@ export declare function createClient(options?: ClientOptions): {
          */
         invokePublic: <T = unknown>(name: string, input: unknown) => Promise<T>;
     };
+    apps: {
+        /**
+         * Call another app's action as the person who started this one: from an
+         * action's server code only, with no credential. The other app is named
+         * by its address name (what `appApiUrl` takes) and must list this app
+         * among its `callers` for the action in `.isomorph/app.json`; its action
+         * sees that person in `ctx.user` and this app in `ctx.caller`. A job has
+         * no signed-in person and calls with a service credential instead.
+         */
+        invoke: <T = unknown, P = string>(address: string, action: string, input: unknown, options?: {
+            onProgress?: (step: P) => void;
+        }) => Promise<T>;
+    };
     jobs: {
         /** Select the owner's folder for a declared configurable file trigger. */
         configureTrigger: (name: string, configuration: {

package/dist/index.js

@@ -183,6 +183,18 @@ function renewableOnUnauthorized(path) {
         return false;
     return path.startsWith('/_harbour/') && path !== IDENTITY_PATH;
 }
+// A browser call still refused after the renewal could not restore the
+// identity (the API-host refresh failed, or the resend was refused again)
+// means the person's sign-in has ended: a platform operator's session never
+// renews (governance ADR 0178), and any session ends at its lifetime. The
+// gateway's wire message is for engineers, and apps showed it verbatim to
+// people mid-task (escplan, 2026-11-07), so that refusal reads as a plain
+// instruction instead; category, status, requestId and details are kept.
+// Only the identity refusal is reworded — the gateway's own sentence, or a
+// 401 with no Isomorph error at all (an edge refusal). A 401 an action or a
+// connected service gave keeps its own words.
+const IDENTITY_REFUSAL = 'signed Isomorph identity is required';
+const SIGN_IN_ENDED = 'Your sign-in has ended. Reload the page to sign in again.';
 class Transport {
     onUnauthorized;
     baseUrl;
@@ -207,7 +219,7 @@ class Transport {
     json(path, init = {}, onProgress) {
         return this.request(path, init, renewableOnUnauthorized(path) || (this.separateApiHost && path === IDENTITY_PATH), onProgress);
     }
-    async request(path, init, renewOnUnauthorized, onProgress) {
+    async request(path, init, renewOnUnauthorized, onProgress, renewalTried = false) {
         const sentAt = this.renewal?.renewals() ?? 0;
         const action = currentAction();
         // (headers with an undefined value are removed so a multipart body can
@@ -245,13 +257,17 @@ class Transport {
                     if (renewed && path === IDENTITY_PATH)
                         return renewed;
                     if (renewed !== false)
-                        return this.request(path, init, false, onProgress);
+                        return this.request(path, init, false, onProgress, true);
+                    renewalTried = true;
                 }
                 // Not before the resend: a page listening to identity.onChange would
                 // otherwise see the user flicker to null while the edge was healing.
                 this.onUnauthorized?.();
             }
-            throw new IsomorphError(body?.error?.category ?? (response.status === 401 ? 'AUTH_REQUIRED' : response.status === 403 ? 'FORBIDDEN' : 'INTERNAL'), body?.error?.message ?? `Isomorph request failed with ${response.status}`, body?.requestId ?? response.headers.get('x-request-id') ?? undefined, body?.error?.details, response.status);
+            const category = body?.error?.category ?? (response.status === 401 ? 'AUTH_REQUIRED' : response.status === 403 ? 'FORBIDDEN' : 'INTERNAL');
+            const signInEnded = renewalTried && response.status === 401 && category === 'AUTH_REQUIRED'
+                && (body?.error?.message === undefined || body.error.message === IDENTITY_REFUSAL);
+            throw new IsomorphError(category, signInEnded ? SIGN_IN_ENDED : body?.error?.message ?? `Isomorph request failed with ${response.status}`, body?.requestId ?? response.headers.get('x-request-id') ?? undefined, body?.error?.details, response.status);
         }
         return (body && Object.prototype.hasOwnProperty.call(body, 'data') ? body.data : body);
     }
@@ -856,6 +872,41 @@ export function createClient(options = {}) {
                 return body.data;
             },
         },
+        apps: {
+            /**
+             * Call another app's action as the person who started this one: from an
+             * action's server code only, with no credential. The other app is named
+             * by its address name (what `appApiUrl` takes) and must list this app
+             * among its `callers` for the action in `.isomorph/app.json`; its action
+             * sees that person in `ctx.user` and this app in `ctx.caller`. A job has
+             * no signed-in person and calls with a service credential instead.
+             */
+            invoke: async (address, action, input, options = {}) => {
+                if (typeof location !== 'undefined')
+                    throw new IsomorphError('VALIDATION_FAILED', 'isomorph.apps.invoke runs in an action\'s server code, not in the browser.', undefined, undefined, 400);
+                const current = currentAction();
+                if (!current?.context)
+                    throw new IsomorphError('AUTH_REQUIRED', 'isomorph.apps.invoke needs an action a signed-in person started; a job uses a service credential.', undefined, undefined, 401);
+                const environment = process.env;
+                const gateway = environment.ISOMORPH_GATEWAY_URL || environment.HARBOUR_GATEWAY_URL;
+                if (!gateway)
+                    throw new IsomorphError('UNAVAILABLE', 'This app has no gateway to call another app through (ISOMORPH_GATEWAY_URL is not set).', undefined, undefined, 503);
+                const host = new URL(appApiUrl(address)).host;
+                await current.workloadToken?.();
+                if (!environment.ISOMORPH_WORKLOAD_TOKEN)
+                    throw new IsomorphError('AUTH_REQUIRED', 'The action has no workload token to call another app with.', undefined, undefined, 401);
+                return new Transport({ baseUrl: gateway, fetch: transport.fetch }).json(`/_harbour/api/${encodeURIComponent(action)}`, {
+                    method: 'POST',
+                    body: JSON.stringify(input ?? {}),
+                    headers: {
+                        authorization: `Bearer ${environment.ISOMORPH_WORKLOAD_TOKEN}`,
+                        'x-harbour-call-host': host,
+                        'x-harbour-tx': undefined,
+                        ...(current.requestId ? { 'x-request-id': current.requestId } : {}),
+                    },
+                }, options.onProgress);
+            },
+        },
         jobs: {
             /** Select the owner's folder for a declared configurable file trigger. */
             configureTrigger: (name, configuration) => transport.json('/_harbour/integrations/trigger-config', { method: 'POST', body: JSON.stringify({ name, configuration }) }),

package/dist/runtime.d.ts

@@ -32,6 +32,18 @@ export interface ActionContext {
      * the outer one.
      */
     transaction<T>(fn: () => Promise<T>): Promise<T>;
+    /**
+     * Set when another app of the company called this action as the person
+     * signed into it (`isomorph.apps.invoke`), as the gateway verified: that
+     * app's id and the environment the call came from (`local` under
+     * `isomorph dev` and `isomorph check`, where `app` is the calling app's
+     * address name). Absent on this app's own pages, service and MCP calls.
+     */
+    caller?: ActionCaller;
+}
+export interface ActionCaller {
+    app: string;
+    environment: 'preview' | 'production' | 'local';
 }
 export interface RuntimeInventory {
     actions: string[];

package/dist/runtime.js

@@ -122,6 +122,23 @@ const DATA_PATH_RETRY_MS = 3_000;
 const PROGRESS_MEDIA_TYPE = 'application/x-ndjson';
 const MAX_PROGRESS_EVENTS = 256;
 const MAX_PROGRESS_LINE_BYTES = 1 << 10;
+const CALLER_ENVIRONMENTS = ['preview', 'production', 'local'];
+/** The calling app the gateway verified (`X-Harbour-Verified-Caller-*`), when another app called. */
+function verifiedCaller(request) {
+    const app = header(request, 'X-Harbour-Verified-Caller-App');
+    const environment = header(request, 'X-Harbour-Verified-Caller-Environment');
+    return app && CALLER_ENVIRONMENTS.includes(environment) ? { app, environment: environment } : undefined;
+}
+/** `.isomorph/app.json` `callers` as written, for the local gateway to expand (`isomorph dev`); [] when there are none. */
+async function declaredCallers(root) {
+    try {
+        const callers = JSON.parse(await readFile(join(root, '.isomorph', 'app.json'), 'utf8')).callers;
+        return Array.isArray(callers) ? callers : [];
+    }
+    catch {
+        return [];
+    }
+}
 /** Every `actions/<name>.ts` and `jobs/<name>.ts` the app carries, by logical name. */
 export async function discover(root) {
     const list = async (dir) => {
@@ -795,7 +812,8 @@ export class Runtime {
                 response.writeHead(200, { 'content-type': PROGRESS_MEDIA_TYPE, ...(requestId ? { 'x-request-id': requestId } : {}) });
             response.write(line);
         };
-        const context = { computerView: header(request, 'X-Harbour-Computer-View') === '1', signal: controller.signal, user, tenant, app, requestId: requestId ?? '', progress, transaction: (fn) => this.transaction(name, fn) };
+        const caller = verifiedCaller(request);
+        const context = { computerView: header(request, 'X-Harbour-Computer-View') === '1', signal: controller.signal, user, tenant, app, requestId: requestId ?? '', progress, transaction: (fn) => this.transaction(name, fn), ...(caller ? { caller } : {}) };
         const raw = await readBody(request);
         if (raw === undefined)
             return refuse(response, 413, 'VALIDATION_FAILED', 'the request body is larger than 1 MiB', requestId);
@@ -849,7 +867,7 @@ export class Runtime {
             await this.prepareAI();
             const handler = await loadHandler(this.options.root, ACTIONS_DIR, name);
             const trusted = this.inventory.trusted.includes(name);
-            const identity = { context: header(request, 'X-Harbour-Identity-Context'), trusted, baseUrl: trusted ? process.env.ISOMORPH_TRUSTED_GATEWAY_URL || undefined : undefined };
+            const identity = { context: header(request, 'X-Harbour-Identity-Context'), trusted, baseUrl: trusted ? process.env.ISOMORPH_TRUSTED_GATEWAY_URL || undefined : undefined, requestId, workloadToken: () => this.refreshToken() };
             const result = await actionIdentity.run(identity, () => handler(input, context));
             return answer(response, 200, { data: result === undefined ? null : result }, requestId);
         }
@@ -922,7 +940,9 @@ export class Runtime {
             case PING_ACTION: {
                 // `hooks` is what the local gateway's hooks entrance serves under `isomorph dev` (data plane ADR 0112).
                 const hooks = this.inventory.jobs.flatMap((job) => job.trigger?.type === 'webhook' ? [{ job: job.name, provider: job.trigger.provider }] : []);
-                const answer = { ok: true, mode: this.options.mode, actions: this.inventory.actions, trusted: this.inventory.trusted, exposed: this.inventory.exposed, public: this.inventory.public, jobs: this.inventory.jobs.map((job) => job.name), hooks };
+                // `callers` is what the local gateway admits another app's call by under `isomorph dev` (data plane ADR 2026-11-07).
+                const callers = await declaredCallers(this.options.root);
+                const answer = { ok: true, mode: this.options.mode, actions: this.inventory.actions, trusted: this.inventory.trusted, exposed: this.inventory.exposed, public: this.inventory.public, jobs: this.inventory.jobs.map((job) => job.name), hooks, ...(callers.length ? { callers } : {}) };
                 return this.options.mode === 'gate' ? { ...answer, loadFailures: await this.loadFailures() } : answer;
             }
             case ENQUEUE_ACTION: {

package/package.json

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