@assembly-js/app-foundation 0.0.45 → 0.0.46

package/CHANGELOG.md

@@ -14,6 +14,12 @@ A foundation update reads the sections between an app's version and the target:
 from every bullet except `[guidance]`, agent work from the `fixes.json` entries those `[action]`
 bullets name. Write `[fix]`, `[behavior]` and `[action]` bullets for the app's owner.
 
+## 0.0.46
+- [new] Pages, server actions, and routes can use an installer client that acts as the installing admin while a person is in the app.
+- [behavior] The action wrapper takes the actor from the verified bearer and ignores a userId query parameter.
+- [behavior] A session the platform verifies as coming from another app is admitted as an app; a human on the same session stays a human. A route can list the kinds of caller it accepts.
+- [guidance] Teach the build agent when to use the installer client and how to declare which callers a route accepts.
+
 ## 0.0.45
 - [guidance] The generated SDK method tables no longer list the session and token methods the foundation calls itself, and the module notes name each module's SDK groups.
 

package/CLAUDE.md

@@ -443,6 +443,10 @@ Relationships:
 **Listing companies for users.** `listCompanies` excludes **placeholder** companies (nameless solo-client stand-ins) by default for app-builder apps, so company dropdowns, tables, and filters won't show blank "ghost" rows — you don't need to filter them yourself. To *include* placeholders (e.g. to surface solo clients), pass `listCompanies({ isPlaceholder: true })` explicitly. See `assembly-companies` skill.
 
 **App isolation.** `listAppInstalls`/`retrieveAppInstall` tell you which apps are installed (id, appId, type, icon, and other install metadata), and `listAppConnections`/`createAppConnection` manage manual embed and link connections between installed apps — that's real, supported SDK surface, and requests to inspect an install or set up one of those connections are not out of bounds. None of it reaches another app's own data, though: you have no access to another installed app's database, tables, or any other internal data, and there is no SDK call that reads or writes another app's data store. If a request needs another app's private data, say only that it isn't possible and stop — no alternatives and no follow-up question. In user-facing chat, call them apps, not custom apps. Do not propose a bridge: no endpoint or API on the other app, no webhook, push, or sync, and nothing the user has to paste between chats. Do not volunteer automations, clients, companies, custom fields, or an Assembly module as a substitute. If the user explicitly asks to call an existing registered API exposed by another app, that is supported API access rather than database access; never suggest it unprompted. Likewise, if the request itself explicitly asks for automations, CRM data, or an installed module's supported data (for example invoices), that is a separate supported request. Never reach another app's database directly.
+<!-- feature:api-resources -->
+
+If the user names another app, read its file in `.assembly/docs/apps/` and follow the call recipe at the top of that file. If that folder is absent, the app is not callable (it may still need the Security update). Cross-app calls from pages, server actions and routes use `getInstallerAssembly()`; cron and webhooks use `getOfflineAssembly()`. Never return another app's response to a client unfiltered — scope any client data you forward. While a person is using the app, those calls use the installer client, because the platform does not yet prove which person the call is for. Once it can, use the viewer client for that person's data and keep the installer client for staff-wide reads.
+<!-- /feature:api-resources -->
 
 ---
 
@@ -880,9 +884,10 @@ Internalize these consequences — they are exactly what generated apps get wron
 - **Never pass a token to any function.** `getAssembly()`, server actions, and route handlers all take **no** token argument.
 - **Never call `assemblyApi` yourself, and never authenticate on the client.** Every API call is server-side through `getAssembly()` / `getAssemblyForRequest()`.
 
-Every authenticated call your app makes is one of exactly two kinds:
-1. **User bearer** — the default; everything below. Acts as the current viewer.
-2. **Offline bearer** — for background work with no user in the loop (cron, webhooks). Call `getOfflineAssembly()` (see "Offline bearer" below); it mints an app-scoped bearer from your API key server-side. Only needed outside a request; ignore it for normal UI work.
+Every authenticated call your app makes is one of exactly three kinds:
+1. **User bearer** — the default. `getAssembly()` acts as the current viewer. Use it for anything shown to or done for the person using the app.
+2. **Installer client** — `getInstallerAssembly()`, allowed inside a user request. Use it for staff-wide reads and writes the app is entitled to on its own, including notification helpers, app storage and connectors. It acts as the installing admin, so filter anything from it before showing it to a client. A viewer cookie does not make it refuse; `getOfflineAssembly()` does.
+3. **Offline bearer** — for background work with no user in the loop (cron, webhooks). Call `getOfflineAssembly()` (see "Offline bearer" below); it mints an app-scoped bearer from your API key server-side. Only needed outside a request; it refuses when a viewer is present.
 
 #### `getAssembly()` — the only auth helper you need
 

package/dist/action-route.d.ts

@@ -0,0 +1,46 @@
+import { type AssemblyAPI } from '@assembly-js/node-sdk';
+import { NextRequest, NextResponse } from 'next/server';
+declare const SURFACED_STATUSES: readonly [400, 401, 404, 422, 429, 500];
+export type ActionErrorStatus = (typeof SURFACED_STATUSES)[number];
+export declare class ActionError extends Error {
+    readonly status: ActionErrorStatus;
+    constructor(message: string, status?: ActionErrorStatus);
+}
+export type Viewer = {
+    kind: 'internal';
+    internalUserId: string;
+} | {
+    kind: 'client';
+    clientId: string;
+    companyId?: string;
+} | {
+    kind: 'app';
+};
+export type RequestSource = 'automation' | 'user' | 'app';
+export interface Caller {
+    appId: string;
+    chain: string[];
+    hops: number;
+}
+export interface ActionContext {
+    workspaceId: string;
+    viewer: Viewer;
+    caller?: Caller;
+    request: {
+        source: RequestSource;
+        sandbox?: boolean;
+    };
+    assembly: AssemblyAPI;
+    readonly installer: Promise<AssemblyAPI>;
+    /** @deprecated read viewer.internalUserId */
+    internalUserId?: string;
+}
+/**
+ * Who is calling a page, server action, or route handler, from the identity
+ * the platform verified for this request's bearer.
+ */
+export declare function getRequestContext(): Promise<ActionContext>;
+export declare function automationActionRoute<TInput>(handler: (input: TInput, context: ActionContext) => Promise<unknown>): (request: NextRequest) => Promise<NextResponse>;
+/** Builds an ActionContext for tests. Production code uses the producers. */
+export declare function makeTestActionContext(overrides: Partial<ActionContext> & Pick<ActionContext, 'assembly' | 'workspaceId'>): ActionContext;
+export {};

package/dist/action-route.js

@@ -0,0 +1,206 @@
+import { assemblyApi } from '@assembly-js/node-sdk';
+import { NextResponse } from 'next/server';
+import { principalKind } from './auth.js';
+import { AuthUnavailableError, TokenInvalidError, authUnavailableResponse, getAssembly, getInstallerAssembly, getVerifiedIdentity, } from './assembly.js';
+import { BEARER_HEADER_NAME } from './session-exchange.js';
+import { verifyBearer } from './verify-bearer.js';
+// The only statuses whose response body the platform reads back.
+const SURFACED_STATUSES = [400, 401, 404, 422, 429, 500];
+export class ActionError extends Error {
+    status;
+    constructor(message, status = 400) {
+        super(message);
+        this.name = 'ActionError';
+        this.status = status;
+    }
+}
+// One hop until the bearer carries a real chain. Not a measured depth.
+const PLACEHOLDER_HOPS = 1;
+const trustedBaseUrl = process.env.ASSEMBLY_API_BASE_URL || undefined;
+function callerFrom(callerAppId) {
+    if (!callerAppId)
+        return undefined;
+    return { appId: callerAppId, chain: [callerAppId], hops: PLACEHOLDER_HOPS };
+}
+// A calling app is the viewer only when the bearer names no person. A human
+// id wins so a staff or client session that also carries a caller stays human.
+function viewerFrom(identity) {
+    // Same precedence as route admission, so a request and its guard agree.
+    const kind = principalKind(identity);
+    if (kind === 'client' && identity.clientId) {
+        return {
+            kind: 'client',
+            clientId: identity.clientId,
+            ...(identity.companyId ? { companyId: identity.companyId } : {}),
+        };
+    }
+    if (kind === 'internal' && identity.internalUserId) {
+        return { kind: 'internal', internalUserId: identity.internalUserId };
+    }
+    if (kind === 'app')
+        return { kind: 'app' };
+    return undefined;
+}
+function installerSlot() {
+    return getInstallerAssembly();
+}
+function contextFrom(args) {
+    return {
+        workspaceId: args.workspaceId,
+        viewer: args.viewer,
+        ...(args.caller ? { caller: args.caller } : {}),
+        request: { source: args.source },
+        assembly: args.assembly,
+        get installer() {
+            return installerSlot();
+        },
+        // Hidden once a caller is present: the deprecated alias is the human actor
+        // of a request that has no calling app, not a second identity channel.
+        ...(args.viewer.kind === 'internal' && !args.caller && args.internalUserId
+            ? { internalUserId: args.internalUserId }
+            : {}),
+    };
+}
+/**
+ * Who is calling a page, server action, or route handler, from the identity
+ * the platform verified for this request's bearer.
+ */
+export async function getRequestContext() {
+    let identity;
+    try {
+        identity = await getVerifiedIdentity();
+    }
+    catch (err) {
+        if (err instanceof AuthUnavailableError)
+            throw err;
+        throw err;
+    }
+    if (!identity?.workspaceId) {
+        throw new TokenInvalidError('Assembly bearer is required');
+    }
+    const caller = callerFrom(identity.callerAppId);
+    const viewer = viewerFrom(identity);
+    if (!viewer) {
+        throw new TokenInvalidError('Assembly bearer is required');
+    }
+    const assembly = viewer.kind === 'app' ? await getInstallerAssembly() : await getAssembly();
+    return contextFrom({
+        workspaceId: identity.workspaceId,
+        viewer,
+        caller,
+        source: viewer.kind === 'app' ? 'app' : 'user',
+        assembly,
+        internalUserId: identity.internalUserId,
+    });
+}
+function tokenExpired() {
+    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
+}
+// Bearer path: the platform already exchanged the single-use token and the
+// middleware forwarded the result. Identity is the verify response, never a
+// query parameter — the platform still sends userId, and so can anyone else.
+async function assemblyFromAutomationRequest(request) {
+    const token = request.nextUrl.searchParams.get('token') ??
+        request.headers.get('x-assembly-token');
+    const bearer = request.headers.get(BEARER_HEADER_NAME);
+    if (!token && !bearer)
+        return tokenExpired();
+    try {
+        if (bearer) {
+            const result = await verifyBearer(bearer);
+            if (!result.ok) {
+                return result.reason === 'rejected'
+                    ? tokenExpired()
+                    : authUnavailableResponse();
+            }
+            const assembly = await assemblyApi({ bearer, baseUrl: trustedBaseUrl });
+            const { identity } = result;
+            assembly.getTokenPayload = () => Promise.resolve({
+                workspaceId: identity.workspaceId,
+                clientId: identity.clientId,
+                companyId: identity.companyId,
+                internalUserId: identity.internalUserId,
+                ...(identity.callerAppId ? { callerAppId: identity.callerAppId } : {}),
+            });
+            return {
+                assembly,
+                workspaceId: identity.workspaceId,
+                internalUserId: identity.internalUserId,
+            };
+        }
+        const assembly = await assemblyApi({
+            apiKey: process.env.ASSEMBLY_API_KEY ?? '',
+            token: token ?? undefined,
+            baseUrl: trustedBaseUrl,
+        });
+        const payload = await assembly.getTokenPayload?.();
+        if (!payload?.workspaceId)
+            return tokenExpired();
+        return {
+            assembly,
+            workspaceId: payload.workspaceId,
+            internalUserId: payload.internalUserId,
+        };
+    }
+    catch {
+        return tokenExpired();
+    }
+}
+export function automationActionRoute(handler) {
+    return async (request) => {
+        const resolved = await assemblyFromAutomationRequest(request);
+        if (resolved instanceof NextResponse)
+            return resolved;
+        let input;
+        try {
+            const raw = await request.text();
+            input = (raw.trim() === '' ? {} : JSON.parse(raw));
+        }
+        catch {
+            return NextResponse.json({ error: 'Request body is not valid JSON' }, { status: 400 });
+        }
+        const context = contextFrom({
+            workspaceId: resolved.workspaceId,
+            viewer: { kind: 'app' },
+            source: 'automation',
+            assembly: resolved.assembly,
+            // Automation has no calling app. The actor, when the platform minted
+            // one onto the bearer, stays on the deprecated alias.
+            internalUserId: resolved.internalUserId,
+        });
+        // contextFrom only copies internalUserId for an internal viewer. An
+        // automation's viewer is the app, and handlers still attribute writes to
+        // the staff user the platform named on the bearer.
+        if (resolved.internalUserId) {
+            context.internalUserId = resolved.internalUserId;
+        }
+        try {
+            const result = await handler(input, context);
+            if (result instanceof NextResponse)
+                return result;
+            return NextResponse.json(result ?? {});
+        }
+        catch (err) {
+            if (err instanceof ActionError) {
+                return NextResponse.json({ error: err.message }, { status: err.status });
+            }
+            console.error(err);
+            return NextResponse.json({ error: 'Something went wrong' }, { status: 500 });
+        }
+    };
+}
+/** Builds an ActionContext for tests. Production code uses the producers. */
+export function makeTestActionContext(overrides) {
+    // Not a spread of a live context: that would invoke the installer getter.
+    return {
+        workspaceId: overrides.workspaceId,
+        viewer: overrides.viewer ?? { kind: 'app' },
+        ...(overrides.caller ? { caller: overrides.caller } : {}),
+        request: overrides.request ?? { source: 'user' },
+        assembly: overrides.assembly,
+        installer: overrides.installer ?? Promise.resolve(overrides.assembly),
+        ...(overrides.internalUserId
+            ? { internalUserId: overrides.internalUserId }
+            : {}),
+    };
+}

package/dist/app-storage.js

@@ -1,4 +1,4 @@
-import { getAssembly } from './assembly.js';
+import { getInstallerAssemblyForCaller } from './installer-caller.js';
 // A bearer token is a JWT: three base64url segments separated by dots, the
 // first always decoding to a JSON header (so it starts with 'eyJ'). Matching
 // the whole-string shape — not just the 'eyJ' prefix — avoids rejecting a
@@ -16,7 +16,8 @@ export async function getUploadUrl(fileName) {
         throw new Error('getUploadUrl: first argument looks like a session token. ' +
             'The token argument was removed — call getUploadUrl(fileName) with the file name only.');
     }
-    const assembly = await getAssembly();
+    // App-owned storage uses the app's authority, but only once a caller is verified.
+    const assembly = await getInstallerAssemblyForCaller();
     const res = await assembly.fetch('/v1/app-storage/upload-url', {
         method: 'POST',
         body: JSON.stringify({ fileName }),
@@ -33,7 +34,7 @@ export async function getDownloadUrl(key) {
         throw new Error('getDownloadUrl: first argument looks like a session token. ' +
             'The token argument was removed — call getDownloadUrl(key) with the storage key only.');
     }
-    const assembly = await getAssembly();
+    const assembly = await getInstallerAssemblyForCaller();
     const res = await assembly.fetch('/v1/app-storage/download-url?key=' + encodeURIComponent(key));
     if (!res.ok)
         throw new Error('Download URL request failed: ' + res.status);

package/dist/assembly.d.ts

@@ -1,10 +1,12 @@
 import { type AssemblyAPI } from '@assembly-js/node-sdk';
 import { NextRequest, NextResponse } from 'next/server';
 import { type ExchangedSession } from './session-exchange.js';
+import { type VerifiedIdentity } from './verify-bearer.js';
 type AssemblyInput = {
     token?: string;
 } | string | undefined;
 export declare function getSessionIdentity(): Promise<ExchangedSession | null>;
+export declare function getVerifiedIdentity(): Promise<VerifiedIdentity | null>;
 /**
  * Thrown when a session token is required but missing, or was supplied but
  * could not be decoded (almost always expiry or truncation). Enforced here in
@@ -90,5 +92,15 @@ export declare function authUnavailableResponse(): NextResponse;
  *   }
  */
 export declare function getOfflineAssembly(): Promise<AssemblyAPI>;
+/**
+ * App-scoped client for use inside a user request (pages, server actions,
+ * route handlers). Acts as the installing admin: anything it returns that is
+ * shown to a client must be filtered by the caller. Unlike getOfflineAssembly,
+ * a viewer cookie does not make this throw — that is the point of it.
+ *
+ * Does not attach the viewer's bearer. Each request mints once; a second call
+ * in the same request reuses that bearer.
+ */
+export declare function getInstallerAssembly(): Promise<AssemblyAPI>;
 export declare function getAssemblyForRequest(req: NextRequest): Promise<AssemblyAPI | NextResponse>;
 export {};

package/dist/assembly.js

@@ -100,8 +100,24 @@ export async function getSessionIdentity() {
         return null;
     // Project to the documented shape so layouts that pass the whole object to a
     // client provider don't serialize server-side fields to the browser.
-    const { workspaceId, clientId, internalUserId, companyId, notificationId, instanceId, sessionId } = viewer.identity;
-    return { workspaceId, clientId, internalUserId, companyId, notificationId, instanceId, sessionId };
+    const { workspaceId, clientId, internalUserId, companyId, notificationId, instanceId, sessionId, callerAppId, } = viewer.identity;
+    return {
+        workspaceId,
+        clientId,
+        internalUserId,
+        companyId,
+        notificationId,
+        instanceId,
+        sessionId,
+        ...(callerAppId ? { callerAppId } : {}),
+    };
+}
+// The platform-verified identity for the current request, or null when there
+// is no bearer. Throws AuthUnavailableError when the platform could not be
+// reached. Identity for authorization comes from here, never from decoded claims.
+export async function getVerifiedIdentity() {
+    const viewer = await resolveRequestViewer();
+    return viewer?.identity ?? null;
 }
 /**
  * Thrown when a session token is required but missing, or was supplied but
@@ -264,6 +280,7 @@ async function getBearerAssembly(bearer, identity) {
             internalUserId: identity.internalUserId,
             notificationId: identity.notificationId,
             instanceId: identity.instanceId,
+            ...(identity.callerAppId ? { callerAppId: identity.callerAppId } : {}),
         };
         assembly.getTokenPayload = () => Promise.resolve(payload);
     }
@@ -311,6 +328,54 @@ export async function getOfflineAssembly() {
     }
     return getBearerAssembly(minted.bearer);
 }
+// One minted installer bearer per request. Next memoizes the headers() object
+// for the request, so keying on it shares a mint across the page without
+// keeping the bearer after the request ends. A process-wide cache would hand
+// one viewer's app bearer to the next request.
+const installerByRequest = new WeakMap();
+async function mintInstallerAssembly() {
+    if (!process.env.ASSEMBLY_API_KEY) {
+        throw new Error('getInstallerAssembly: ASSEMBLY_API_KEY is not set — cannot mint an app-scoped bearer');
+    }
+    const minted = await mintBearerFromAppKey();
+    if (!minted) {
+        throw new Error('getInstallerAssembly: failed to mint an app-scoped bearer from the app API key');
+    }
+    return getBearerAssembly(minted.bearer);
+}
+/**
+ * App-scoped client for use inside a user request (pages, server actions,
+ * route handlers). Acts as the installing admin: anything it returns that is
+ * shown to a client must be filtered by the caller. Unlike getOfflineAssembly,
+ * a viewer cookie does not make this throw — that is the point of it.
+ *
+ * Does not attach the viewer's bearer. Each request mints once; a second call
+ * in the same request reuses that bearer.
+ */
+export async function getInstallerAssembly() {
+    let headerStore;
+    try {
+        headerStore = await headers();
+    }
+    catch {
+        headerStore = undefined;
+    }
+    if (!headerStore)
+        return mintInstallerAssembly();
+    const existing = installerByRequest.get(headerStore);
+    if (existing)
+        return existing;
+    const pending = mintInstallerAssembly();
+    installerByRequest.set(headerStore, pending);
+    try {
+        return await pending;
+    }
+    catch (err) {
+        // A failed mint must not stick for the rest of the request.
+        installerByRequest.delete(headerStore);
+        throw err;
+    }
+}
 // Returns a request-scoped SDK client authenticated for the current user.
 //
 // Exchange enabled: bearer-only. A bearer the platform verifies (proxy header or

package/dist/auth.d.ts

@@ -1,5 +1,14 @@
 import type { AssemblyAPI } from '@assembly-js/node-sdk';
 import { NextRequest, NextResponse } from 'next/server';
+export type PrincipalKind = 'internal' | 'client' | 'app';
+export interface PrincipalAllow {
+    allow?: readonly PrincipalKind[];
+}
+export declare function principalKind(payload: {
+    clientId?: string;
+    internalUserId?: string;
+    callerAppId?: string;
+}): PrincipalKind | undefined;
 export interface TokenPayload {
     workspaceId: string;
     internalUserId?: string;
@@ -7,11 +16,13 @@ export interface TokenPayload {
     companyId?: string;
     notificationId?: string;
     instanceId?: string;
+    /** Calling app, when this session was opened by another app. */
+    callerAppId?: string;
     baseUrl?: string;
     tokenId?: string;
 }
-export declare function requireAuth(req: NextRequest): Promise<TokenPayload | NextResponse>;
+export declare function requireAuth(req: NextRequest, options?: PrincipalAllow): Promise<TokenPayload | NextResponse>;
 export declare function requireCompanyScope(payload: TokenPayload, resource: {
     companyId: string | null;
     clientId?: string | null;
-}, tokenOrAssembly?: string | AssemblyAPI): Promise<NextResponse | null>;
+}, tokenOrAssembly?: string | AssemblyAPI, options?: PrincipalAllow): Promise<NextResponse | null>;

package/dist/auth.js

@@ -11,6 +11,25 @@ function isTokenInvalid(err) {
     const e = err;
     return e.name === 'TokenInvalidError' || e.code === 'TOKEN_INVALID';
 }
+// A person wins over a calling app. A caller with no human id is an app.
+// Undefined is an unauthenticated shape, not a fourth kind.
+export function principalKind(payload) {
+    if (payload.clientId)
+        return 'client';
+    if (payload.internalUserId)
+        return 'internal';
+    if (payload.callerAppId)
+        return 'app';
+    return undefined;
+}
+function principalRefused(payload, allow) {
+    if (!allow)
+        return null;
+    const kind = principalKind(payload);
+    if (kind && allow.includes(kind))
+        return null;
+    return NextResponse.json({ error: 'Forbidden' }, { status: 403 });
+}
 function tokenExpiredResponse() {
     return NextResponse.json({ error: 'Unauthorized', code: 'token_expired' }, { status: 401, headers: { [TOKEN_EXPIRED_HEADER]: '1' } });
 }
@@ -23,7 +42,7 @@ function tokenExpiredResponse() {
 // without the marker, so nothing re-exchanges. There is no session-token
 // fallback for a bearer-capable app.
 // Exchange off (legacy): reads and decodes the x-assembly-token header.
-export async function requireAuth(req) {
+export async function requireAuth(req, options) {
     if (isSessionExchangeEnabled()) {
         const bearer = req.headers.get(BEARER_HEADER_NAME) ??
             req.cookies.get(BEARER_COOKIE_NAME)?.value;
@@ -37,14 +56,21 @@ export async function requireAuth(req) {
                 : authUnavailableResponse();
         }
         const { identity } = result;
-        return {
+        const payload = {
             workspaceId: identity.workspaceId,
             clientId: identity.clientId,
             internalUserId: identity.internalUserId,
             companyId: identity.companyId,
             notificationId: identity.notificationId,
             instanceId: identity.instanceId,
+            // Only the platform's verify response. The proxy copies a warm cookie
+            // onto the bearer header, so the header is not a separate trust path.
+            ...(identity.callerAppId ? { callerAppId: identity.callerAppId } : {}),
         };
+        const refused = principalRefused(payload, options?.allow);
+        if (refused)
+            return refused;
+        return payload;
     }
     const token = req.headers.get('x-assembly-token');
     if (!token) {
@@ -61,7 +87,11 @@ export async function requireAuth(req) {
         if (!payload.workspaceId) {
             return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
         }
-        return payload;
+        const tokenPayload = payload;
+        const refused = principalRefused(tokenPayload, options?.allow);
+        if (refused)
+            return refused;
+        return tokenPayload;
     }
     catch (err) {
         if (isTokenInvalid(err)) {
@@ -82,9 +112,17 @@ export async function requireAuth(req) {
 // Pass a session token string (legacy path) or a bearer-authenticated AssemblyAPI
 // instance from getAssemblyForRequest (bearer path) to enable the membership lookup.
 // Returns null on success, or a 403/404 NextResponse on mismatch.
-export async function requireCompanyScope(payload, resource, tokenOrAssembly) {
+export async function requireCompanyScope(payload, resource, tokenOrAssembly, options) {
+    const refused = principalRefused(payload, options?.allow);
+    if (refused)
+        return refused;
     if (payload.internalUserId)
         return null;
+    // Workspace-wide, same as cron. A caller id only counts when verify put it
+    // on the payload: the proxy mirrors a warm cookie onto the bearer header,
+    // so the header cannot prove where the bearer came from.
+    if (payload.callerAppId && !payload.clientId)
+        return null;
     if (!payload.clientId) {
         return NextResponse.json({ error: 'Forbidden' }, { status: 403 });
     }
@@ -133,6 +171,11 @@ export async function requireCompanyScope(payload, resource, tokenOrAssembly) {
         const status = typeof err === 'object' && err !== null ? err.status : undefined;
         if (status === 401)
             return tokenExpiredResponse();
+        // The client's own record can 403. That is an authorization answer, not a
+        // broken server — mapping it to 500 makes the client retry a refusal.
+        if (status === 403) {
+            return NextResponse.json({ error: 'Forbidden' }, { status: 403 });
+        }
         return NextResponse.json({ error: status === 404 ? 'Not found' : 'Internal server error' }, { status: status === 404 ? 404 : 500 });
     }
 }

package/dist/installer-caller.d.ts

@@ -0,0 +1,14 @@
+import type { AssemblyAPI } from '@assembly-js/node-sdk';
+interface InstallerCallerDeps {
+    getAssembly: () => Promise<unknown>;
+    getInstallerAssembly: () => Promise<AssemblyAPI>;
+}
+/**
+ * Installer client for app-owned resources (storage, connectors), handed out
+ * only once the platform has verified a caller. Routes and actions that reach
+ * these helpers without their own auth check would otherwise expose the
+ * installer's workspace-wide authority to anyone. getAssembly() throws when
+ * there is no verified viewer, so the gate runs before any installer mint.
+ */
+export declare function getInstallerAssemblyForCaller(deps?: InstallerCallerDeps): Promise<AssemblyAPI>;
+export {};

package/dist/installer-caller.js

@@ -0,0 +1,12 @@
+import { getAssembly, getInstallerAssembly } from './assembly.js';
+/**
+ * Installer client for app-owned resources (storage, connectors), handed out
+ * only once the platform has verified a caller. Routes and actions that reach
+ * these helpers without their own auth check would otherwise expose the
+ * installer's workspace-wide authority to anyone. getAssembly() throws when
+ * there is no verified viewer, so the gate runs before any installer mint.
+ */
+export async function getInstallerAssemblyForCaller(deps = { getAssembly, getInstallerAssembly }) {
+    await deps.getAssembly();
+    return deps.getInstallerAssembly();
+}

package/dist/mint-bearer.js

@@ -95,6 +95,9 @@ export async function mintBearerFromSessionToken(token, options) {
                 companyId: json.session?.companyId || undefined,
                 notificationId: json.session?.notificationId || undefined,
                 instanceId: json.session?.instanceId || undefined,
+                ...(json.session?.callerAppId
+                    ? { callerAppId: json.session.callerAppId }
+                    : {}),
                 sessionId: payload.tokenId,
                 flags: json.flags?.length ? json.flags : undefined,
             },

package/dist/nango.d.ts

@@ -34,14 +34,14 @@ export interface ProxyOpts {
 /**
  * Returns a thin, server-side-only client for a connected provider. Every method
  * POSTs to the Assembly connector broker (`/v1/connectors/:provider/...`) via
- * getAssembly().fetch — there is no Nango client and no provider credentials in
+ * getInstallerAssemblyForCaller().fetch — there is no Nango client and no provider credentials in
  * the app. The broker resolves the workspace's connection server-side and
  * relays the provider response transparently.
  *
  * MUST be called from server-side code only (API routes, server components,
- * server actions) within an authenticated request scope. `getAssembly()` reads
- * the viewer bearer from the request cookie (same as every other data call);
- * there is no `x-assembly-token` header and no token argument. Background/cron
+ * server actions). The connection belongs to the app, so the call uses the
+ * installer client rather than the viewer's bearer. There is no
+ * `x-assembly-token` header and no token argument. Background/cron
  * calls with no viewer are out of scope for v1 — see connector Phase-2.
  */
 export declare function getIntegration(provider: Provider): Promise<{

package/dist/nango.js

@@ -1,4 +1,4 @@
-import { getAssembly } from './assembly.js';
+import { getInstallerAssemblyForCaller } from './installer-caller.js';
 import { findResource, normalizeResourcePage, TtlCache, } from './resource-resolution.js';
 // Thrown when the broker returns a structured `{ error, provider }` fail-closed
 // response. Catch it server-side and branch on `code` to render the right empty
@@ -67,18 +67,18 @@ async function throwIfBrokerError(res, provider) {
 /**
  * Returns a thin, server-side-only client for a connected provider. Every method
  * POSTs to the Assembly connector broker (`/v1/connectors/:provider/...`) via
- * getAssembly().fetch — there is no Nango client and no provider credentials in
+ * getInstallerAssemblyForCaller().fetch — there is no Nango client and no provider credentials in
  * the app. The broker resolves the workspace's connection server-side and
  * relays the provider response transparently.
  *
  * MUST be called from server-side code only (API routes, server components,
- * server actions) within an authenticated request scope. `getAssembly()` reads
- * the viewer bearer from the request cookie (same as every other data call);
- * there is no `x-assembly-token` header and no token argument. Background/cron
+ * server actions). The connection belongs to the app, so the call uses the
+ * installer client rather than the viewer's bearer. There is no
+ * `x-assembly-token` header and no token argument. Background/cron
  * calls with no viewer are out of scope for v1 — see connector Phase-2.
  */
 export async function getIntegration(provider) {
-    const assembly = await getAssembly();
+    const assembly = await getInstallerAssemblyForCaller();
     // Relays a provider HTTP call through the broker's universal proxy. The broker
     // endpoint is always POST-ed (so a body carries through); the real provider
     // verb travels in X-Connector-Method (default GET). The provider response is

package/dist/server.d.ts

@@ -1,5 +1,6 @@
 import 'server-only';
 export * from './assembly.js';
+export * from './action-route.js';
 export * from './auth.js';
 export * from './client-access.js';
 export * from './mint-bearer.js';

package/dist/server.js

@@ -4,6 +4,7 @@
 // instead of silently shipping ASSEMBLY_API_KEY to the browser.
 import 'server-only';
 export * from './assembly.js';
+export * from './action-route.js';
 export * from './auth.js';
 export * from './client-access.js';
 export * from './mint-bearer.js';

package/dist/session-exchange.d.ts

@@ -40,6 +40,8 @@ export interface ExchangedSession {
     companyId?: string;
     notificationId?: string;
     instanceId?: string;
+    /** Set when another app called this one. Absent on a human session. */
+    callerAppId?: string;
     /** Session token this bearer was exchanged from — lets the proxy tell a
      *  reload of an already-exchanged token apart from a new open. */
     sessionId?: string;

package/dist/session-exchange.js

@@ -202,5 +202,6 @@ export function decodeBearer(bearer) {
         notificationId: claims.notification_id || undefined,
         instanceId: claims.instance_id || undefined,
         sessionId: claims.session_id || undefined,
+        ...(claims.caller_app_id ? { callerAppId: claims.caller_app_id } : {}),
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@assembly-js/app-foundation",
-  "version": "0.0.45",
+  "version": "0.0.46",
   "description": "Versioned foundation helpers and build context for Assembly generated apps",
   "type": "module",
   "files": [

package/skills/assembly-automations/SKILL.md

@@ -269,116 +269,18 @@ Every event also lands in the workspace's audit log, where a workspace admin rea
 
 **Every api with `exposeToAutomations: true` requires two things in the app: `lib/assembly-actions.ts` exactly as written below, and a route serving it at exactly that record's `baseUrl`.** This is not optional infrastructure. Skipping the wrapper and hand-rolling the route is the single most damaging mistake in this file: the platform's call carries no cookie and no viewer bearer, so nothing about it *looks* unauthenticated, and a route that forgets to verify the token becomes a public endpoint that mutates workspace data under the app's own privileges. Serving it at the wrong path is silent too — the automation just fails with an opaque error and the handler never runs.
 
-The platform runs the action by calling the record's `baseUrl`, and `requireAuth` cannot authenticate that call. Copy this file in verbatim, then reuse it for every action route in the app:
+The platform runs the action by calling the record's `baseUrl`, and `requireAuth` cannot authenticate that call. `lib/assembly-actions.ts` re-exports the wrapper from the foundation package — write that re-export, don't paste a second copy of the handler.
+
+Use `getAssembly()` for anything shown to or done for the person using the app, and `getInstallerAssembly()` for staff-wide reads and writes the app is entitled to on its own, including notification helpers.
 
 ```ts
 // lib/assembly-actions.ts
-import { assemblyApi, type AssemblyAPI } from '@assembly-js/node-sdk';
-import { NextRequest, NextResponse } from 'next/server';
-
-// The only statuses whose response body the platform reads back.
-const SURFACED_STATUSES = [400, 401, 404, 422, 429, 500] as const;
-export type ActionErrorStatus = (typeof SURFACED_STATUSES)[number];
-
-export class ActionError extends Error {
-  readonly status: ActionErrorStatus;
-  constructor(message: string, status: ActionErrorStatus = 400) {
-    super(message);
-    this.name = 'ActionError';
-    this.status = status;
-  }
-}
-
-export interface ActionContext {
-  workspaceId: string;
-  internalUserId?: string;
-  assembly: AssemblyAPI;
-}
-
-export function automationActionRoute<TInput>(
-  handler: (input: TInput, context: ActionContext) => Promise<unknown>,
-): (request: NextRequest) => Promise<NextResponse> {
-  return async (request) => {
-    // The platform sends the app token as a query param; the header is the
-    // transport the public API moves to. Never a cookie or a viewer bearer.
-    const token =
-      request.nextUrl.searchParams.get('token') ??
-      request.headers.get('x-assembly-token');
-    // The proxy middleware exchanges that single-use token before this handler
-    // runs and forwards the minted bearer on this header (inbound copies are
-    // stripped, so it is always the middleware's own). By handler time the raw
-    // token is spent — platform calls must ride the bearer whenever one is
-    // present; the token path below serves exchange-disabled apps.
-    const bearer = request.headers.get('x-assembly-request-bearer');
-    if (!token && !bearer) {
-      return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
-    }
-
-    let assembly: AssemblyAPI;
-    let workspaceId: string | undefined;
-    let internalUserId: string | undefined;
-    try {
-      // With a bearer, identity comes from its platform-verified claims. On
-      // the token path, the app API key derives the key the token was
-      // encrypted with; the SDK swallows a decrypt failure and leaves the
-      // payload unset — an absent workspaceId is how a forged or stale
-      // credential surfaces either way.
-      assembly = await assemblyApi({
-        apiKey: process.env.ASSEMBLY_API_KEY ?? '',
-        ...(bearer ? { bearer } : { token: token ?? undefined }),
-        baseUrl: process.env.ASSEMBLY_API_BASE_URL || undefined,
-      });
-      const payload = await assembly.getTokenPayload?.();
-      workspaceId = payload?.workspaceId;
-      internalUserId = payload?.internalUserId;
-    } catch {
-      return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
-    }
-    if (!workspaceId) {
-      return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
-    }
-
-    let input: TInput;
-    try {
-      const raw = await request.text();
-      input = (raw.trim() === '' ? {} : JSON.parse(raw)) as TInput;
-    } catch {
-      return NextResponse.json(
-        { error: 'Request body is not valid JSON' },
-        { status: 400 },
-      );
-    }
-
-    try {
-      const result = await handler(input, {
-        workspaceId,
-        // The token names the actor only when the platform minted it with one;
-        // an automation always names them on the query string.
-        internalUserId:
-          internalUserId ||
-          request.nextUrl.searchParams.get('userId') ||
-          undefined,
-        assembly,
-      });
-      // A handler that returns a NextResponse (anything out of
-      // lib/api-errors.ts) already carries its own status — pass it straight
-      // through, or JSON-wrapping it would serialize the response object into
-      // a 200 body and the automation would record a success.
-      if (result instanceof NextResponse) return result;
-      // Otherwise always a JSON body: the platform parses the response even
-      // for a void operation, so a 204 or an empty body fails the run step.
-      return NextResponse.json(result ?? {});
-    } catch (err) {
-      if (err instanceof ActionError) {
-        return NextResponse.json({ error: err.message }, { status: err.status });
-      }
-      // Never return err.message from a catch — driver and Postgres strings
-      // leak to the caller. Same rule as lib/api-errors.ts.
-      console.error(err);
-      return NextResponse.json({ error: 'Something went wrong' }, { status: 500 });
-    }
-  };
-}
+export {
+  automationActionRoute,
+  ActionError,
+  type ActionContext,
+  type ActionErrorStatus,
+} from '@assembly-js/app-foundation/server';
 ```
 
 Each action route is then just the handler, served at the record's `baseUrl`:
@@ -481,6 +383,10 @@ export const GET = automationActionRoute(async (_input, { workspaceId }) => {
 - **`trigger.icon`, when set, must be one of the names in the icon list above.** Unknown names fail the publish; an omitted icon renders a generic default.
 - **Renaming breaks saved automations.** An action's identity derives from the api's `name` and a trigger's from `eventName` — including the `~<appId>.` prefix, which is part of that identity. Renaming either, or adding/removing the prefix on one you already shipped, orphans every automation a workspace built on it. Pick names as if they're permanent.
 
+## Calling another app
+
+If the user names another app, read its file in `.assembly/docs/apps/` and follow the call recipe at the top of that file. If that folder is absent, the app is not callable (it may still need the Security update). Cross-app calls from pages, server actions and routes use `getInstallerAssembly()`; cron and webhooks use `getOfflineAssembly()`. Never return another app's response to a client unfiltered — scope any client data you forward. While a person is using the app, those calls use the installer client, because the platform does not yet prove which person the call is for. Once it can, use the viewer client for that person's data and keep the installer client for staff-wide reads.
+
 ## Telling the user
 
 **Call it an automation, not a webhook.** In the product this feature is Automations; "webhook" is the wire format underneath it. `sendWebhook` and the `webhooks` manifest key keep their names in code — this is about what you say in chat. "I added a *Time entry logged* trigger you can build automations on" lands; "I set up a webhook" reads as plumbing nobody asked for.

package/skills/assembly-internal-users/SKILL.md

@@ -18,6 +18,8 @@ Never call `assembly.getTokenPayload()` for this — see `assembly-session-token
 
 If `internalUserId` is set, the current viewer is staff. (`clientId` is set for client viewers — see `assembly-client-users` skill.)
 
+Use `getAssembly()` for anything shown to or done for the person using the app, and `getInstallerAssembly()` for staff-wide reads and writes the app is entitled to on its own, including notification helpers.
+
 ## SDK methods
 
 - `listInternalUsers({ nextToken, limit })` — paged list of all staff in the workspace

package/skills/assembly-notifications/SKILL.md

@@ -16,6 +16,8 @@ For a required condition alert (a retainer reaching 90%, going over its allowanc
 
 Every notification is three decisions: **audience** (internal users and/or clients), **channel** (in-product, email, or both), and **context on arrival** (what the recipient sees and can do). Get those right; the rest is mechanics.
 
+Use `getAssembly()` for anything shown to or done for the person using the app, and `getInstallerAssembly()` for staff-wide reads and writes the app is entitled to on its own, including notification helpers.
+
 ### Internal vs client experience
 
 The audience changes the experience and the code:

package/skills/assembly-route-auth/SKILL.md

@@ -7,6 +7,10 @@ Every `app/api/.../[id]/route.ts` handler — **GET included** — must call `re
 
 Routes listed in the `privateRoutes` array of `.assembly/app.json` (globs such as `/internal/**`, matched against the route template, not the file path; `*` stays within a segment, `**` crosses segments) are not offered to other apps.
 
+Use `getAssembly()` for anything shown to or done for the person using the app, and `getInstallerAssembly()` for staff-wide reads and writes the app is entitled to on its own, including notification helpers.
+
+A route that must stay human-only passes `{ allow: ['internal', 'client'] }` to `requireAuth` and `requireCompanyScope`. With no option, an app caller is allowed too; an app caller on a route that does not list `'app'` gets 403. When you branch on `viewer.kind`, keep a default branch — the set of kinds can grow.
+
 ```ts
 import { requireAuth, requireCompanyScope, handleRouteError } from '@assembly-js/app-foundation/server';
 ```

package/skills/assembly-storage/SKILL.md

@@ -18,7 +18,7 @@ Use app-storage for files that belong to YOUR app. For files the user expects to
 
 Store the `key` it returns; never construct an S3 key yourself, and never parse the original file name back out of the key — the platform normalizes the name when forming the key, so the stored `key` is not guaranteed to contain your exact `fileName`. Keep the display name as your own metadata (see "Storing and downloading"). `fileName` must be a bare file name (`invoice.pdf`), never a path — the platform rejects any fileName containing `/` or `..`. Don't prefix folders or namespaces onto it; the platform already scopes the key to the workspace and makes it unique. If you need grouping, store that in your own database alongside the key.
 
-The helpers call `getAssembly()` internally, which reads the bearer from the request cookie server-side — they take no token. `assembly.fetch()` prepends the base URL and injects auth headers — you only pass the path and body. Wrap these in a server API route (e.g. `app/api/app-storage/upload-url/route.ts`); never call `getAssembly` from a client component.
+The helpers verify the caller (as `getAssembly()` does) and then use the installer client — app storage is the app's own resource, so it does not ride the viewer's bearer. They take no token. `assembly.fetch()` prepends the base URL and injects auth headers — you only pass the path and body. Wrap these in a server API route (e.g. `app/api/app-storage/upload-url/route.ts`); never call `getAssembly` from a client component.
 
 ## Client uploader — PUT directly to S3