@isomorph.ai/app-sdk 2.3.0 → 2.4.0

package/dist/aws.js

@@ -67,7 +67,11 @@ export async function runtimeCredentials(env = process.env, { fetch: fetcher = f
         throw new Error('the runtime has no AWS credentials (AWS_ACCESS_KEY_ID, or AWS_ROLE_ARN with AWS_WEB_IDENTITY_TOKEN_FILE)');
     if (webIdentity?.roleArn === roleArn && webIdentity.expiresAt - now() > 5 * 60_000)
         return webIdentity.credentials;
-    const region = env.AWS_REGION || env.AWS_DEFAULT_REGION || 'us-east-1';
+    // STS is called in the runtime's own region, which the runtime always has (Lambda and the kit chart set
+    // it). No default: a cell outside us-east-1 under a region-pinning policy must never fall back there.
+    const region = env.AWS_REGION || env.AWS_DEFAULT_REGION;
+    if (!region)
+        throw new Error('the runtime has no AWS region (AWS_REGION) for its STS exchange');
     // The token is read on each exchange: the kubelet rotates the file.
     const body = new URLSearchParams({ Action: 'AssumeRoleWithWebIdentity', Version: '2011-06-15', RoleArn: roleArn, RoleSessionName: env.AWS_ROLE_SESSION_NAME || 'isomorph-runtime', WebIdentityToken: (await readFile(tokenFile, 'utf8')).trim() });
     const response = await fetcher(`https://sts.${region}.amazonaws.com/`, { method: 'POST', headers: { 'content-type': 'application/x-www-form-urlencoded' }, body: body.toString(), signal: AbortSignal.timeout(10_000) });

package/dist/computer-use-api.js

@@ -1,5 +1,9 @@
-// Harbour's computer use API (CUA) as the runtime's own role, signed with
-// SigV4 (ADR 0078): what the computer use tool and the sign-in helpers share.
+// Harbour's computer use API (CUA): what the computer use tool and the sign-in
+// helpers share. A hosted job reaches it through its App Gateway as the app's
+// workload (ADR 0103): the gateway and governance carry the call into
+// Harbour's account, so no customer-account role signs Harbour's API. A
+// runtime with no gateway (older deployments, ISOMORPH_COMPUTER_USE_URL)
+// still signs the API with its own role (ADR 0078).
 import { runtimeCredentials, signedJsonPost } from './aws.js';
 import { IsomorphError } from './index.js';
 export function refused(path, status, body) {
@@ -7,12 +11,24 @@ export function refused(path, status, body) {
     return new Error(`The computer use API refused ${path} (${status}${typeof error === 'string' ? `: ${error}` : ''}).`);
 }
 export function computerUseApi({ env = process.env, fetch } = {}) {
-    const base = env.ISOMORPH_COMPUTER_USE_URL?.replace(/\/+$/, '');
-    if (!base)
-        throw new Error('This app has no computer use API (ISOMORPH_COMPUTER_USE_URL is not set).');
+    const gateway = env.ISOMORPH_GATEWAY_URL?.replace(/\/+$/, '');
+    const direct = env.ISOMORPH_COMPUTER_USE_URL?.replace(/\/+$/, '');
+    if (!gateway && !direct)
+        throw new Error('This app has no computer use API (ISOMORPH_GATEWAY_URL is not set).');
+    // The direct call names Harbour's own API in Harbour's region (ADR 0078); the gateway path has no region.
     const region = env.ISOMORPH_COMPUTER_USE_REGION || 'us-east-1';
     const transport = fetch ? { fetch } : {};
-    const call = async (path, body) => signedJsonPost({ ...await runtimeCredentials(env, transport), region }, 'execute-api', `${base}${path}`, body, transport);
+    const fetcher = fetch ?? globalThis.fetch;
+    const call = gateway
+        ? async (path, body) => {
+            // The workload token is read on every call: the runtime refreshes it in place.
+            const token = env.ISOMORPH_WORKLOAD_TOKEN;
+            if (!token)
+                throw new Error('This job has no workload token for its computer use call.');
+            const response = await fetcher(`${gateway}/_harbour/computer-use${path}`, { method: 'POST', headers: { 'content-type': 'application/json', authorization: `Bearer ${token}` }, body: JSON.stringify(body) });
+            return { status: response.status, body: await response.json().catch(() => undefined) };
+        }
+        : async (path, body) => signedJsonPost({ ...await runtimeCredentials(env, transport), region }, 'execute-api', `${direct}${path}`, body, transport);
     return {
         call,
         /** A call the API must answer with 200; its body. */

package/dist/index.d.ts

@@ -2138,3 +2138,4 @@ export interface FileArrivalInput {
     createdAt: string;
     observedAt: string;
 }
+export type { WebhookReceived, WebhookTrigger, WebhookProvider } from './jobs.js';

package/dist/jobs.d.ts

@@ -20,7 +20,27 @@ export interface FileCreatedTrigger {
     driveId?: string;
     mimeTypes?: string[];
 }
-export type EventTrigger = EmailArrivalTrigger | FileCreatedTrigger;
+export declare const WEBHOOK_PROVIDERS: readonly ["slack", "none"];
+export type WebhookProvider = typeof WEBHOOK_PROVIDERS[number];
+/**
+ * A job a third-party product triggers by posting to the app's hook URL. `provider` names the
+ * runtime's sender-verification adapter; `secret` is the NAME of the app secret (an env var in the
+ * runtime) holding that provider's signing secret, required when the provider signs (`slack`).
+ */
+export interface WebhookTrigger {
+    type: 'webhook';
+    provider: WebhookProvider;
+    secret?: string;
+}
+/** What a webhook job's handler receives as `ctx.input`. */
+export interface WebhookReceived {
+    type: 'webhook.received';
+    provider: WebhookProvider;
+    headers: Record<string, string>;
+    body: unknown;
+    receivedAt: string;
+}
+export type EventTrigger = EmailArrivalTrigger | FileCreatedTrigger | WebhookTrigger;
 export interface JobDefinition {
     name: string;
     schedule?: string;

package/dist/jobs.js

@@ -8,6 +8,7 @@ export const JOBS_DIR = 'jobs';
 const LOGICAL_NAME = /^[a-z0-9][a-z0-9_-]{0,63}$/;
 export const FILE_MIME_TYPES = ['application/pdf', 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet', 'image/png', 'image/jpeg'];
 export const providerFileId = (value) => typeof value === 'string' && /^[A-Za-z0-9!._,=-]{1,256}$/.test(value);
+export const WEBHOOK_PROVIDERS = ['slack', 'none'];
 function literalObject(node, what = 'trigger') {
     const value = node;
     if (value?.type === 'Literal')
@@ -57,7 +58,17 @@ export async function actionExposure(file) {
     }
     return undefined;
 }
+const SECRET_NAME = /^[A-Z][A-Z0-9_]{0,127}$/;
 export function eventTrigger(value) {
+    if (value?.type === 'webhook') {
+        const t = value;
+        if (Object.keys(t).some(k => !['type', 'provider', 'secret'].includes(k)) || !WEBHOOK_PROVIDERS.includes(t.provider)
+            || (t.secret !== undefined && (typeof t.secret !== 'string' || !SECRET_NAME.test(t.secret))))
+            throw new Error("webhook requires provider 'slack' or 'none' and an optional secret: the UPPER_CASE name of an app secret");
+        if (t.provider === 'slack' && !t.secret)
+            throw new Error("webhook provider 'slack' requires secret: the name of the app secret holding the Slack signing secret");
+        return t;
+    }
     if (value?.type === 'file.created') {
         const t = value;
         if (Object.keys(t).some(k => !['type', 'connection', 'resource', 'folderId', 'configurableFolder', 'driveId', 'mimeTypes'].includes(k))
@@ -174,7 +185,7 @@ export async function discoverJobs(root) {
         if (!statements.some(statement => statement.type === 'ExportDefaultDeclaration'))
             fail('export one default job handler.');
         if (schedule && trigger)
-            fail('a job may declare a schedule or an email trigger, not both.');
+            fail('a job may declare a schedule or a trigger, not both.');
         jobs.push({ name, ...(schedule ? { schedule } : {}), ...(trigger ? { trigger } : {}) });
     }
     return jobs.sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);

package/dist/runtime.d.ts

@@ -153,6 +153,19 @@ export declare class Runtime {
      * path never answered, or the handler threw; the log names which.
      */
     acceptEventArrival(value: unknown): Promise<void>;
+    /**
+     * A third-party product's delivery, forwarded by the gateway's hooks route with the job and
+     * provider it verified from the URL token (`X-Harbour-Verified-Hook`, `-Provider`). The provider's
+     * adapter checks the sender over the raw body before anything is written; a verified event becomes
+     * one durable run keyed by the provider's event id, so a repeated delivery finds the existing row
+     * and re-signals the queue (ADR 0107). Answers `{ challenge }` for a handshake, else `{ accepted, runId }`.
+     */
+    acceptWebhookArrival(app: string, jobName: string, provider: string, headers: Record<string, string>, rawBody: Buffer): Promise<{
+        challenge: string;
+    } | {
+        accepted: true;
+        runId: string;
+    }>;
     runJobOnce(name: string, now?: Date): Promise<boolean>;
     private awaitDataPath;
     stop(): Promise<void>;

package/dist/runtime.js

@@ -57,7 +57,7 @@
 //   ISOMORPH_JOBS_QUEUE_URL       an enqueue sends the run to this SQS queue and
 //                                 the queue loop never runs here: the cell's
 //                                 Event Function works it (lambda-events-entry.ts)
-import { createHash } from 'node:crypto';
+import { createHash, randomBytes } from 'node:crypto';
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { createServer } from 'node:http';
 import { readFile, readdir, stat } from 'node:fs/promises';
@@ -69,6 +69,7 @@ import { createClient, gatewayRequest, IsomorphError } from './index.js';
 import { userGroupsFromHeader } from './user-groups.js';
 import { userRole } from './user-role.js';
 import { FILE_MIME_TYPES, providerFileId, actionExposure, discoverJobs, exportsTrue, invokeJob, loadHandler, JOBS_DIR } from './jobs.js';
+import { WEBHOOK_ADAPTERS } from './webhook-adapters.js';
 import { LocalGateway } from './local-gateway.js';
 export { JOBS_DIR } from './jobs.js';
 const actionIdentity = new AsyncLocalStorage();
@@ -210,6 +211,11 @@ function header(request, name) {
     const value = request.headers[name.toLowerCase()];
     return (Array.isArray(value) ? value[0] : value) ?? '';
 }
+const HOP_HEADERS = new Set(['host', 'connection', 'content-length', 'transfer-encoding', 'authorization']);
+/** The sender's own headers, lower-cased: the gateway's verified headers and the hop's are not the sender's. */
+function providerHeaders(request) {
+    return Object.fromEntries(Object.entries(request.headers).flatMap(([name, value]) => value === undefined || HOP_HEADERS.has(name) || name.startsWith('x-harbour-') ? [] : [[name, Array.isArray(value) ? value.join(', ') : value]]));
+}
 // ---- Runs (through the gateway, as the workload) ------------------------------
 export class Runs {
     client;
@@ -439,7 +445,7 @@ export class Runtime {
         this.inventory = await discover(this.options.root);
         const job = this.inventory.jobs.find(job => job.name === delivery.job);
         const input = delivery.input;
-        if (!job?.trigger || job.trigger.connection !== input.sourceId)
+        if (!job?.trigger || job.trigger.type === 'webhook' || job.trigger.connection !== input.sourceId)
             throw new Error('event trigger is not declared by this deployed app');
         if (job.trigger.type === 'file.created') {
             const instant = (v) => typeof v === 'string' && /^\d{4}-\d{2}-\d{2}T/.test(v) && Number.isFinite(Date.parse(v));
@@ -463,6 +469,38 @@ export class Runtime {
         const queued = await this.runs.enqueueEvent(delivery);
         await this.signalQueuedRun(queued.id);
     }
+    /**
+     * A third-party product's delivery, forwarded by the gateway's hooks route with the job and
+     * provider it verified from the URL token (`X-Harbour-Verified-Hook`, `-Provider`). The provider's
+     * adapter checks the sender over the raw body before anything is written; a verified event becomes
+     * one durable run keyed by the provider's event id, so a repeated delivery finds the existing row
+     * and re-signals the queue (ADR 0107). Answers `{ challenge }` for a handshake, else `{ accepted, runId }`.
+     */
+    async acceptWebhookArrival(app, jobName, provider, headers, rawBody) {
+        const fail = (status, category, message) => { throw new IsomorphError(category, message, undefined, undefined, status); };
+        this.inventory = await discover(this.options.root);
+        const job = this.inventory.jobs.find(job => job.name === jobName);
+        if (job?.trigger?.type !== 'webhook')
+            fail(404, 'NOT_FOUND', `this app has no webhook job ${JOBS_DIR}/${jobName}.ts`);
+        const trigger = job.trigger;
+        if (trigger.provider !== provider)
+            fail(404, 'NOT_FOUND', `${JOBS_DIR}/${jobName}.ts expects deliveries from ${trigger.provider}, not ${provider}`);
+        const secret = trigger.secret ? process.env[trigger.secret] : undefined;
+        if (trigger.secret && !secret)
+            fail(500, 'INTERNAL', `the app secret ${trigger.secret} that ${JOBS_DIR}/${jobName}.ts names for ${trigger.provider} is not set; set it on the app's secrets page`);
+        const verdict = WEBHOOK_ADAPTERS[trigger.provider]({ headers, rawBody, secret, now: Date.now() });
+        if (verdict.kind === 'challenge')
+            return { challenge: verdict.challenge };
+        await this.refreshToken(JOB_SESSION_MIN_VALIDITY_MS);
+        if (!this.options.gatewayUrl || this.options.mode === 'gate' || this.options.jobRuns === false || !(await this.awaitDataPath()))
+            fail(503, 'UNAVAILABLE', 'webhook arrival requires durable job runs');
+        const input = { type: 'webhook.received', provider: trigger.provider, headers, body: verdict.body, receivedAt: new Date().toISOString() };
+        // A provider without an event id gets at-least-once with no dedup; its handler must be idempotent.
+        const deliveryId = verdict.eventId ? createHash('sha256').update(`hook:${app}/${jobName}/${verdict.eventId}`).digest('hex') : randomBytes(32).toString('hex');
+        const queued = await this.runs.enqueueEvent({ deliveryId, job: jobName, input, owner: `workload:${app}` });
+        await this.signalQueuedRun(queued.id);
+        return { accepted: true, runId: queued.id };
+    }
     async runJobOnce(name, now = new Date()) {
         this.inventory = await discover(this.options.root);
         await this.refreshToken(JOB_SESSION_MIN_VALIDITY_MS);
@@ -685,8 +723,13 @@ export class Runtime {
         const abort = () => controller.abort();
         response.once('close', abort);
         const directory = header(request, 'X-Harbour-Verified-Directory');
+        const userId = header(request, 'X-Harbour-Verified-User-ID');
         const user = {
-            id: header(request, 'X-Harbour-Verified-User-ID'),
+            id: userId,
+            // A service credential's call arrives with the credential as the verified user
+            // (`service:<clientId>`, ADR 0101); the action sees it as `kind: 'service'`, the
+            // shape `/_harbour/identity/current` already answers. Anything else is a person.
+            ...(userId.startsWith('service:') ? { kind: 'service' } : {}),
             email: header(request, 'X-Harbour-Verified-User-Email'),
             groups: userGroupsFromHeader(header(request, 'X-Harbour-Verified-User-Groups')),
             role: userRole(header(request, 'X-Harbour-Verified-User-Role')),
@@ -721,6 +764,20 @@ export class Runtime {
         const raw = await readBody(request);
         if (raw === undefined)
             return refuse(response, 413, 'VALIDATION_FAILED', 'the request body is larger than 1 MiB', requestId);
+        if (name === 'isomorph-mail-arrival' && header(request, 'X-Harbour-Verified-Hook')) {
+            // The gateway's hooks route: the provider's raw body and headers, the gateway's verified
+            // headers beside them. The answer is what the provider reads, so it is not enveloped.
+            try {
+                return answer(response, 200, await this.acceptWebhookArrival(app, header(request, 'X-Harbour-Verified-Hook'), header(request, 'X-Harbour-Verified-Provider'), providerHeaders(request), raw), requestId);
+            }
+            catch (error) {
+                const refused = refusal(error);
+                if (refused)
+                    return refuse(response, refused.status, refused.category, refused.message, requestId);
+                this.log(`webhook ${header(request, 'X-Harbour-Verified-Hook')}: ${error instanceof Error ? error.stack ?? error.message : String(error)}`);
+                return refuse(response, 500, 'INTERNAL', 'the webhook could not be accepted; the log names the cause', requestId);
+            }
+        }
         let input = undefined;
         if (raw.length > 0) {
             try {

package/dist/webhook-adapters.d.ts

@@ -0,0 +1,33 @@
+import type { WebhookProvider } from './jobs.js';
+export interface WebhookRequest {
+    /** The provider's headers, lower-cased names, as the gateway forwarded them. */
+    headers: Record<string, string>;
+    /** The body exactly as the provider sent it: what the signature covers. */
+    rawBody: Buffer;
+    /** The signing secret the job named, undefined when the provider has none. */
+    secret?: string;
+    /** Milliseconds since the epoch, for freshness. */
+    now: number;
+}
+export type WebhookVerdict = 
+/** Answer the provider's handshake synchronously with `{ challenge }`; nothing is written. */
+{
+    kind: 'challenge';
+    challenge: string;
+}
+/** A verified delivery: the body (parsed JSON when it is JSON, else the text) and the provider's id for it, when it has one. */
+ | {
+    kind: 'event';
+    eventId?: string;
+    body: unknown;
+};
+/** Slack accepts a request timestamp this far from the receiver's clock (Slack's own guidance: five minutes). */
+export declare const SLACK_MAX_AGE_SECONDS: number;
+/** How far ahead of the receiver's clock a Slack timestamp may be: clock skew, not age. */
+export declare const SLACK_MAX_SKEW_SECONDS = 60;
+export declare const parseBody: (rawBody: Buffer) => unknown;
+/** `X-Slack-Signature: v0=<hex HMAC-SHA256(secret, "v0:<X-Slack-Request-Timestamp>:<raw body>")>`. */
+export declare function verifySlack(request: WebhookRequest): WebhookVerdict;
+/** No signature: the hook's URL token is the only check, and no event id means no dedup. */
+export declare const verifyNone: (request: WebhookRequest) => WebhookVerdict;
+export declare const WEBHOOK_ADAPTERS: Record<WebhookProvider, (request: WebhookRequest) => WebhookVerdict>;

package/dist/webhook-adapters.js

@@ -0,0 +1,49 @@
+// Sender verification for webhook arrivals, one adapter per provider: the exact signed bytes,
+// header parsing, timestamp freshness, event-id extraction and any handshake, as pure functions
+// over the raw request. The runtime runs the adapter before it writes anything (ADR 0107).
+import { createHmac, timingSafeEqual } from 'node:crypto';
+import { IsomorphError } from './index.js';
+/** A refusal the runtime answers as it is, with its status, and writes nothing for. */
+function refuse(status, message) { throw new IsomorphError(status === 401 ? 'AUTH_REQUIRED' : 'VALIDATION_FAILED', message, undefined, undefined, status); }
+/** Slack accepts a request timestamp this far from the receiver's clock (Slack's own guidance: five minutes). */
+export const SLACK_MAX_AGE_SECONDS = 5 * 60;
+/** How far ahead of the receiver's clock a Slack timestamp may be: clock skew, not age. */
+export const SLACK_MAX_SKEW_SECONDS = 60;
+export const parseBody = (rawBody) => {
+    const text = rawBody.toString('utf8');
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+};
+/** `X-Slack-Signature: v0=<hex HMAC-SHA256(secret, "v0:<X-Slack-Request-Timestamp>:<raw body>")>`. */
+export function verifySlack(request) {
+    if (!request.secret)
+        refuse(401, 'the Slack signing secret is not set');
+    const timestamp = request.headers['x-slack-request-timestamp'] ?? '';
+    const signature = request.headers['x-slack-signature'] ?? '';
+    if (!/^\d{1,12}$/.test(timestamp) || !/^v0=[0-9a-f]{64}$/.test(signature))
+        refuse(401, 'the request carries no valid X-Slack-Request-Timestamp and X-Slack-Signature');
+    const age = Math.floor(request.now / 1000) - Number(timestamp);
+    if (age > SLACK_MAX_AGE_SECONDS)
+        refuse(401, `the Slack request timestamp is older than ${SLACK_MAX_AGE_SECONDS} seconds`);
+    if (-age > SLACK_MAX_SKEW_SECONDS)
+        refuse(401, 'the Slack request timestamp is in the future');
+    const expected = Buffer.from(`v0=${createHmac('sha256', request.secret).update(`v0:${timestamp}:`).update(request.rawBody).digest('hex')}`);
+    const given = Buffer.from(signature);
+    if (expected.length !== given.length || !timingSafeEqual(expected, given))
+        refuse(401, 'the Slack signature does not match');
+    const body = parseBody(request.rawBody);
+    const record = body && typeof body === 'object' ? body : {};
+    if (record.type === 'url_verification') {
+        if (typeof record.challenge !== 'string' || !record.challenge)
+            refuse(400, 'url_verification carries no challenge');
+        return { kind: 'challenge', challenge: record.challenge };
+    }
+    return { kind: 'event', body, ...(typeof record.event_id === 'string' && record.event_id ? { eventId: record.event_id } : {}) };
+}
+/** No signature: the hook's URL token is the only check, and no event id means no dedup. */
+export const verifyNone = (request) => ({ kind: 'event', body: parseBody(request.rawBody) });
+export const WEBHOOK_ADAPTERS = { slack: verifySlack, none: verifyNone };

package/package.json

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