@assembly-js/app-foundation 0.8.2 → 0.10.0

package/dist/assembly.js

@@ -270,8 +270,10 @@ export function authUnavailableResponse() {
 // from the trusted build-env baseUrl, never a token/bearer claim. When the
 // caller has a verified identity, getTokenPayload() answers with it rather than
 // with the SDK's read of the bearer's claims.
-async function getBearerAssembly(bearer, identity) {
+async function getBearerAssembly(bearer, identity, options) {
     const assembly = await assemblyApi({ bearer, baseUrl: trustedBaseUrl });
+    if (options?.crossAppAsInstaller)
+        routeCrossAppFetchThroughInstaller(assembly);
     if (identity) {
         // Includes the embed-context ids the SDK's bearer-mode payload omits, so
         // payload.notificationId still marks the Notification Center surface.
@@ -325,7 +327,7 @@ export async function getOfflineAssembly() {
         throw new Error('getOfflineAssembly: ASSEMBLY_API_KEY is not set — cannot mint an app-scoped bearer');
     }
     const minted = await mintBearerFromAppKey();
-    if (!minted) {
+    if (!minted.ok) {
         throw new Error('getOfflineAssembly: failed to mint an app-scoped bearer from the app API key');
     }
     return getBearerAssembly(minted.bearer);
@@ -340,7 +342,7 @@ async function mintInstallerBearer() {
         throw new Error('getInstallerAssembly: ASSEMBLY_API_KEY is not set — cannot mint an app-scoped bearer');
     }
     const minted = await mintBearerFromAppKey();
-    if (!minted) {
+    if (!minted.ok) {
         throw new Error('getInstallerAssembly: failed to mint an app-scoped bearer from the app API key');
     }
     return minted.bearer;
@@ -377,11 +379,156 @@ async function getInstallerBearer() {
  * 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.
+ * Does not attach the viewer's bearer to its own calls. Each request mints once;
+ * a second call in the same request reuses that bearer. A call through `fetch` to
+ * another app (`/v1/apps/...`) is the exception: in a client's request it is made
+ * as that client (see getCrossAppBearer), in a staff request as this app.
  */
 export async function getInstallerAssembly() {
-    return getBearerAssembly(await getInstallerBearer());
+    return getBearerAssembly(await getInstallerBearer(), undefined, {
+        crossAppAsInstaller: true,
+    });
+}
+// The platform's cross-app proxy lives under this prefix; nothing else gets a parent.
+const CROSS_APP_PATH_PREFIX = '/v1/apps/';
+// The platform's code for a mint whose parent bearer it refused outright, as
+// opposed to one that merely expired (which a re-exchange fixes).
+const PARENT_INVALID_CODE = 'parent_invalid';
+const PARENT_EXPIRED_CODE = 'parent_expired';
+// One cross-app bearer per request, keyed on the memoized headers object like the
+// installer bearer: a process-wide cache would hand one client's bearer to the next.
+const crossAppBearerByRequest = new WeakMap();
+// Whether `path`, as the SDK will concatenate it onto the base, lands on the
+// cross-app proxy. Resolved with URL first so `/v1/apps/../session` and encoded
+// dot-segments are judged by where they actually go.
+function isCrossAppPath(path) {
+    const base = (trustedBaseUrl ?? OpenAPI.BASE).replace(/\/+$/, '');
+    try {
+        const resolved = new URL(`${base}${path.startsWith('/') ? path : `/${path}`}`);
+        const baseUrl = new URL(base);
+        if (resolved.origin !== baseUrl.origin)
+            return false;
+        const basePath = baseUrl.pathname.replace(/\/+$/, '');
+        return resolved.pathname.slice(basePath.length).startsWith(CROSS_APP_PATH_PREFIX);
+    }
+    catch {
+        return false;
+    }
+}
+// The viewer bearer to present as the mint's parent, or undefined when this
+// request has no person to speak for. The decision rests only on what the
+// platform verifies for the one credential the request carries: the header when
+// present, else the cookie, never the cookie after a rejected header. A viewer
+// that is present but cannot be verified throws instead of quietly becoming app
+// authority.
+async function resolveCrossAppParent(headerStore, cookieStore) {
+    const candidate = headerStore.get(BEARER_HEADER_NAME) ||
+        cookieStore.get(BEARER_COOKIE_NAME)?.value ||
+        undefined;
+    const legacyViewer = Boolean(headerStore.get(LEGACY_TOKEN_HEADER) || headerStore.get(LEGACY_WORKSPACE_HEADER));
+    if (!candidate) {
+        if (legacyViewer)
+            throw new TokenInvalidError('Assembly bearer is required');
+        return undefined;
+    }
+    // Exchange off: a viewer is present and nothing can verify it.
+    if (!isSessionExchangeEnabled()) {
+        throw new TokenInvalidError('Assembly bearer is required');
+    }
+    const result = await verifyBearer(candidate);
+    if (!result.ok) {
+        if (result.reason === 'unavailable')
+            throw new AuthUnavailableError();
+        throw new TokenInvalidError('Assembly bearer is required');
+    }
+    const { identity } = result;
+    // The platform refuses an impersonation or assistant-run bearer as a parent.
+    if (identity.tokenKind !== 'viewer')
+        return undefined;
+    // Staff stay app authority; only a client is forwarded.
+    if (!identity.clientId)
+        return undefined;
+    return candidate;
+}
+async function mintCrossAppBearer(headerStore, cookieStore) {
+    const parent = await resolveCrossAppParent(headerStore, cookieStore);
+    // Without a person this is the plain installer bearer, so a request that also
+    // calls the installer's other endpoints still mints once.
+    if (!parent)
+        return { bearer: await getInstallerBearer() };
+    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({ parent });
+    if (minted.ok)
+        return { bearer: minted.bearer };
+    // Never retried without the parent: that would be the fallback to app authority.
+    if (minted.code === PARENT_EXPIRED_CODE) {
+        throw new TokenInvalidError('Assembly bearer expired');
+    }
+    if (minted.code === PARENT_INVALID_CODE && minted.status !== undefined) {
+        return {
+            refusal: {
+                status: minted.status,
+                body: minted.body ?? JSON.stringify({ code: PARENT_INVALID_CODE }),
+            },
+        };
+    }
+    // A throttled mint says nothing about the parent, so it is an outage, not a refusal.
+    if (minted.status === undefined || minted.status >= 500 || minted.status === 429) {
+        throw new AuthUnavailableError();
+    }
+    throw new Error('getInstallerAssembly: failed to mint a cross-app bearer from the app API key');
+}
+// The bearer for a call to another app: the installer's, carrying the client when
+// this is a client's request. Throws where the request cannot be read (`'use cache'`,
+// prerender, `after()`), because a bearer minted there would be unattributed while
+// the page may still be serving a client.
+async function getCrossAppBearer() {
+    let headerStore;
+    let cookieStore;
+    try {
+        [headerStore, cookieStore] = await Promise.all([headers(), cookies()]);
+    }
+    catch {
+        throw new Error('A call to another app needs the current request, which cannot be read here (a cached component, prerender or after()). Make the call from a page, server action or route handler.');
+    }
+    const existing = crossAppBearerByRequest.get(headerStore);
+    if (existing)
+        return existing;
+    const pending = mintCrossAppBearer(headerStore, cookieStore);
+    crossAppBearerByRequest.set(headerStore, pending);
+    try {
+        return await pending;
+    }
+    catch (err) {
+        // A failed mint must not stick for the rest of the request.
+        crossAppBearerByRequest.delete(headerStore);
+        throw err;
+    }
+}
+function refusalResponse(refusal) {
+    return new Response(refusal.body, {
+        status: refusal.status,
+        headers: { 'Content-Type': 'application/json' },
+    });
+}
+// Wraps `fetch` on an installer SDK object so a raw call to another app uses the
+// cross-app bearer, and every other path is left exactly as the SDK sends it.
+function routeCrossAppFetchThroughInstaller(assembly) {
+    const original = assembly.fetch;
+    if (typeof original !== 'function')
+        return;
+    assembly.fetch = async (path, init) => {
+        if (!isCrossAppPath(path))
+            return original.call(assembly, path, init);
+        const outcome = await getCrossAppBearer();
+        if ('refusal' in outcome)
+            return refusalResponse(outcome.refusal);
+        const headers = new Headers(init?.headers);
+        headers.set('Authorization', `Bearer ${outcome.bearer}`);
+        return original.call(assembly, path, { ...init, headers, cache: 'no-store' });
+    };
 }
 /**
  * Options for calling another app's API through the platform, shaped for an
@@ -389,19 +536,30 @@ export async function getInstallerAssembly() {
  * `createClient`. The bearer is resolved on every call, so a client built at
  * module scope still authenticates as the current request.
  *
- * `installer` calls as this app, with the same per-request mint as
- * getInstallerAssembly. `viewer` forwards the signed-in user's verified bearer,
- * which the platform scopes to that contact and refuses for a team member.
+ * `installer` calls as this app. In a client's request it also carries that
+ * client, so the platform checks the client could open the other app and the
+ * other app sees a client; in a staff request it is this app alone. `viewer`
+ * forwards the signed-in user's verified bearer, which the platform scopes to
+ * that contact and refuses for a team member.
  */
 export function appProxyOptions(appId, caller) {
     const origin = (trustedBaseUrl ?? OpenAPI.BASE).replace(/\/+$/, '');
     return {
         baseUrl: `${origin}/v1/apps/${encodeURIComponent(appId)}/api`,
         fetch: async (input) => {
-            const bearer = caller === 'installer' ? await getInstallerBearer() : await requireViewerBearer();
+            let bearer;
+            if (caller === 'installer') {
+                const outcome = await getCrossAppBearer();
+                if ('refusal' in outcome)
+                    return refusalResponse(outcome.refusal);
+                bearer = outcome.bearer;
+            }
+            else {
+                bearer = await requireViewerBearer();
+            }
             const request = new Request(input);
             request.headers.set('Authorization', `Bearer ${bearer}`);
-            return fetch(request);
+            return fetch(request, { cache: 'no-store' });
         },
     };
 }

package/dist/mint-bearer.d.ts

@@ -22,8 +22,35 @@ export interface MintSessionOptions {
 }
 export declare function mintBearerFromSessionToken(token: string, options?: MintSessionOptions): Promise<MintOutcome>;
 export declare function fetchSessionFlags(bearer: string): Promise<string[] | null>;
+/** The person a minted bearer is attributed to, echoed by the platform. */
+export interface MintedOnBehalfOf {
+    /** "client" or "internal_user". */
+    kind: string;
+    clientId?: string;
+    internalUserId?: string;
+    companyId?: string;
+}
 export interface MintedAppBearer {
     bearer: string;
     bearerExpiresAt: number;
+    /** Present only when the mint carried a parent the platform accepted. */
+    onBehalfOf?: MintedOnBehalfOf;
+}
+export type AppKeyMintOutcome = ({
+    ok: true;
+} & MintedAppBearer) | {
+    ok: false;
+    /** HTTP status of a refusal; absent when no response arrived (no key,
+     *  network failure, timeout) or the 2xx body was unusable. */
+    status?: number;
+    /** The platform's error code, when its body carried one. */
+    code?: string;
+    /** The platform's raw error body, so a refusal can be handed on verbatim. */
+    body?: string;
+};
+export interface MintAppKeyOptions {
+    /** Viewer bearer of the person whose request this app is serving. The platform
+     *  refuses a present-but-invalid parent; it is never silently dropped. */
+    parent?: string;
 }
-export declare function mintBearerFromAppKey(): Promise<MintedAppBearer | null>;
+export declare function mintBearerFromAppKey(options?: MintAppKeyOptions): Promise<AppKeyMintOutcome>;

package/dist/mint-bearer.js

@@ -145,20 +145,38 @@ export async function fetchSessionFlags(bearer) {
         clearTimeout(timeoutId);
     }
 }
+function parseOnBehalfOf(value) {
+    if (!value || typeof value !== 'object')
+        return undefined;
+    const v = value;
+    if (typeof v.kind !== 'string' || v.kind === '')
+        return undefined;
+    const str = (x) => (typeof x === 'string' && x !== '' ? x : undefined);
+    return {
+        kind: v.kind,
+        clientId: str(v.clientId),
+        internalUserId: str(v.internalUserId),
+        companyId: str(v.companyId),
+    };
+}
 // Mints a short-lived, APP-scoped bearer from the app API key ALONE by calling
 // platform-api POST /v1/token (client-credentials). There is NO session token
 // and NO user in the loop: this is the OFFLINE/background path (cron, webhooks)
 // where no iframe ever handed us a session token to exchange. The app key mints
 // the bearer once; every subsequent data call then uses that bearer alone.
 //
+// With `parent`, the mint is attributed to the person that parent names (see
+// MintAppKeyOptions). Callers decide whether a parent exists; this only sends it.
+//
 // Uses a runtime-agnostic fetch (safe in BOTH the Edge middleware and Node route-
 // handler runtimes) with the same abort-based timeout as the session exchange,
-// and fails closed (null) on any error — including a malformed 2xx — so a caller
-// never proceeds with a missing or bad credential.
-export async function mintBearerFromAppKey() {
+// and fails closed on any error — including a malformed 2xx — so a caller
+// never proceeds with a missing or bad credential. The failure carries the
+// platform's status and code so a caller can tell a refused parent from an outage.
+export async function mintBearerFromAppKey(options) {
     const apiKey = process.env.ASSEMBLY_API_KEY;
     if (!apiKey)
-        return null;
+        return { ok: false };
     // Client-credentials mint: POST /v1/token authenticated by the app key sent as
     // X-API-Key. Unlike mintBearerFromSessionToken (which decrypts a session token
     // and lets the SDK derive the header), there is no token here, and the SDK only
@@ -174,16 +192,31 @@ export async function mintBearerFromAppKey() {
         // Present only in the app's sandbox (written to .env.local, never to the deployed
         // env); it lets the platform tell a sandbox call from a deployed one.
         const sandboxGrant = process.env.ASSEMBLY_SANDBOX_GRANT;
+        const body = {
+            ...(sandboxGrant ? { sandboxGrant } : {}),
+            ...(options?.parent ? { parent: options.parent } : {}),
+        };
+        const hasBody = Object.keys(body).length > 0;
         const resp = await fetch(`${base}/v1/token`, {
             method: 'POST',
-            headers: sandboxGrant
+            headers: hasBody
                 ? { 'X-API-Key': apiKey, 'Content-Type': 'application/json' }
                 : { 'X-API-Key': apiKey },
-            ...(sandboxGrant ? { body: JSON.stringify({ sandboxGrant }) } : {}),
+            ...(hasBody ? { body: JSON.stringify(body) } : {}),
             signal: controller.signal,
         });
-        if (!resp.ok)
-            return null;
+        if (!resp.ok) {
+            let text;
+            let code;
+            try {
+                text = await resp.text();
+                const parsed = JSON.parse(text);
+                if (typeof parsed?.code === 'string')
+                    code = parsed.code;
+            }
+            catch { }
+            return { ok: false, status: resp.status, code, body: text };
+        }
         const json = (await resp.json());
         // Fail closed on a malformed or already-expired 2xx: a missing/mistyped token
         // would yield a client that sends `Authorization: Bearer undefined`, a
@@ -195,13 +228,19 @@ export async function mintBearerFromAppKey() {
             typeof json.tokenExpiresAt !== 'number' ||
             !Number.isFinite(json.tokenExpiresAt) ||
             json.tokenExpiresAt * 1_000 <= now) {
-            return null;
+            return { ok: false, status: resp.status };
         }
         const bearerExpiresAt = Math.min(json.tokenExpiresAt * 1_000, now + BEARER_TTL_MS);
-        return { bearer: json.token, bearerExpiresAt };
+        const onBehalfOf = parseOnBehalfOf(json.onBehalfOf);
+        return {
+            ok: true,
+            bearer: json.token,
+            bearerExpiresAt,
+            ...(onBehalfOf ? { onBehalfOf } : {}),
+        };
     }
     catch {
-        return null;
+        return { ok: false };
     }
     finally {
         clearTimeout(timeoutId);

package/dist/proxy.js

@@ -121,7 +121,7 @@ async function fetchWorkspaceThemeForIdentity(workspaceId, bearer) {
     // or future change surfaces an exception.
     try {
         const minted = await mintBearerFromAppKey();
-        if (!minted?.bearer)
+        if (!minted.ok)
             return null;
         return await fetchWorkspaceThemeWithBearer(minted.bearer, workspaceId);
     }

package/dist/scripts.js

@@ -4644,33 +4644,66 @@ var COOKIE_PROBE_TTL_SECONDS = 24 * 60 * 60;
 // src/mint-bearer.ts
 var mintBaseUrl = process.env.ASSEMBLY_API_BASE_URL || void 0;
 var EXCHANGE_TIMEOUT_MS = 15e3;
-async function mintBearerFromAppKey() {
+function parseOnBehalfOf(value) {
+  if (!value || typeof value !== "object") return void 0;
+  const v = value;
+  if (typeof v.kind !== "string" || v.kind === "") return void 0;
+  const str = (x) => typeof x === "string" && x !== "" ? x : void 0;
+  return {
+    kind: v.kind,
+    clientId: str(v.clientId),
+    internalUserId: str(v.internalUserId),
+    companyId: str(v.companyId)
+  };
+}
+async function mintBearerFromAppKey(options) {
   const apiKey = process.env.ASSEMBLY_API_KEY;
-  if (!apiKey) return null;
+  if (!apiKey) return { ok: false };
   const base = (mintBaseUrl ?? OpenAPI2.BASE).replace(/\/$/, "");
   const now = Date.now();
   const controller = new AbortController();
   const timeoutId = setTimeout(() => controller.abort(), EXCHANGE_TIMEOUT_MS);
   try {
     const sandboxGrant = process.env.ASSEMBLY_SANDBOX_GRANT;
+    const body = {
+      ...sandboxGrant ? { sandboxGrant } : {},
+      ...options?.parent ? { parent: options.parent } : {}
+    };
+    const hasBody = Object.keys(body).length > 0;
     const resp = await fetch(`${base}/v1/token`, {
       method: "POST",
-      headers: sandboxGrant ? { "X-API-Key": apiKey, "Content-Type": "application/json" } : { "X-API-Key": apiKey },
-      ...sandboxGrant ? { body: JSON.stringify({ sandboxGrant }) } : {},
+      headers: hasBody ? { "X-API-Key": apiKey, "Content-Type": "application/json" } : { "X-API-Key": apiKey },
+      ...hasBody ? { body: JSON.stringify(body) } : {},
       signal: controller.signal
     });
-    if (!resp.ok) return null;
+    if (!resp.ok) {
+      let text;
+      let code;
+      try {
+        text = await resp.text();
+        const parsed = JSON.parse(text);
+        if (typeof parsed?.code === "string") code = parsed.code;
+      } catch {
+      }
+      return { ok: false, status: resp.status, code, body: text };
+    }
     const json = await resp.json();
     if (typeof json.token !== "string" || json.token.length === 0 || typeof json.tokenExpiresAt !== "number" || !Number.isFinite(json.tokenExpiresAt) || json.tokenExpiresAt * 1e3 <= now) {
-      return null;
+      return { ok: false, status: resp.status };
     }
     const bearerExpiresAt = Math.min(
       json.tokenExpiresAt * 1e3,
       now + BEARER_TTL_MS
     );
-    return { bearer: json.token, bearerExpiresAt };
+    const onBehalfOf = parseOnBehalfOf(json.onBehalfOf);
+    return {
+      ok: true,
+      bearer: json.token,
+      bearerExpiresAt,
+      ...onBehalfOf ? { onBehalfOf } : {}
+    };
   } catch {
-    return null;
+    return { ok: false };
   } finally {
     clearTimeout(timeoutId);
   }
@@ -4689,7 +4722,7 @@ async function getOfflineAssembly() {
     );
   }
   const minted = await mintBearerFromAppKey();
-  if (!minted) {
+  if (!minted.ok) {
     throw new Error(
       "getOfflineAssembly: failed to mint an app-scoped bearer from the app API key"
     );

package/dist/verify-bearer.d.ts

@@ -9,6 +9,11 @@ export interface VerifiedIdentity {
     callerAppId?: string;
     installerUserId?: string;
     tokenKind?: string;
+    /** Apps an app-to-app call passed through to reach this request, read from the
+     *  verified bearer's own claims. Advisory: display and logging only, never a
+     *  decision (the platform's depth cap is the control). */
+    chain?: string[];
+    hops?: number;
     /** Epoch SECONDS at which the verified bearer expires. */
     expiresAt: number;
 }
@@ -24,6 +29,7 @@ export declare const VIEWER_BEARER_HEADER = "X-Assembly-Viewer-Bearer";
 export declare const VERIFY_OUTCOME_EVENT = "assembly.verify_outcome";
 /**
  * Resolves a viewer bearer to the identity the platform vouches for. Identity
- * must come from here, never from the bearer's decoded claims.
+ * must come from here, never from the bearer's decoded claims. The one
+ * exception is the advisory call chain, which only the bearer carries.
  */
 export declare function verifyBearer(bearer: string): Promise<VerifyResult>;

package/dist/verify-bearer.js

@@ -156,11 +156,45 @@ async function verifyUncached(bearer, key, startedAt) {
     logOutcome(result.reason, startedAt);
     return result;
 }
+// Reads the advisory call-chain claims off a bearer the platform has just
+// verified. Never used to decide anything: a bearer that fails to decode simply
+// has no chain.
+function readChainClaims(bearer) {
+    try {
+        const segment = bearer.split('.')[1];
+        const b64 = segment.replace(/-/g, '+').replace(/_/g, '/');
+        const padded = b64 + '='.repeat((4 - (b64.length % 4)) % 4);
+        const claims = JSON.parse(new TextDecoder().decode(Uint8Array.from(atob(padded), (ch) => ch.charCodeAt(0))));
+        const chain = Array.isArray(claims.chain)
+            ? claims.chain.filter((a) => typeof a === 'string' && a !== '')
+            : [];
+        const hops = typeof claims.hops === 'number' && Number.isInteger(claims.hops) && claims.hops > 0
+            ? claims.hops
+            : undefined;
+        return {
+            ...(chain.length ? { chain } : {}),
+            ...(hops ? { hops } : {}),
+        };
+    }
+    catch {
+        return {};
+    }
+}
 /**
  * Resolves a viewer bearer to the identity the platform vouches for. Identity
- * must come from here, never from the bearer's decoded claims.
+ * must come from here, never from the bearer's decoded claims. The one
+ * exception is the advisory call chain, which only the bearer carries.
  */
 export async function verifyBearer(bearer) {
+    const result = await verifyBearerWithPlatform(bearer);
+    if (!result.ok)
+        return result;
+    return {
+        ok: true,
+        identity: Object.freeze({ ...result.identity, ...readChainClaims(bearer) }),
+    };
+}
+async function verifyBearerWithPlatform(bearer) {
     const startedAt = Date.now();
     // The decode is a no-network precheck: shape, expiry and workspace claim.
     if (!decodeBearer(bearer)) {

package/package.json

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