@isomorph.ai/app-sdk 1.21.0 → 1.22.0

package/README.md

@@ -453,3 +453,9 @@ await isomorph.actions.invoke('research', input, { onProgress: (step) => setStep
 Without `onProgress` the call is unchanged and `ctx.progress` does nothing. At
 most 256 steps of up to 1 KiB each reach the page; further steps are dropped.
 The action still has the 300 s action budget. (Unreleased)
+
+## Running on Lambda
+
+On a serverless cell Harbour runs an app's server code as Lambda functions; nothing in the app changes. `ISOMORPH_GATEWAY_IDENTITY=sts-session` replaces `HARBOUR_WORKLOAD_TOKEN_FILE`: the runtime's bearer for the gateway is a one-hour session it gets by posting a presigned STS `GetCallerIdentity`, signed with the function's credentials (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_SESSION_TOKEN`, `AWS_REGION`), to `<gateway>/_harbour/internal/session`. A cluster runtime leaves it unset.
+
+(1.22.0; data plane ADR 0065)

package/dist/aws.d.ts

@@ -0,0 +1,13 @@
+export interface AwsEnvironment {
+    accessKeyId: string;
+    secretAccessKey: string;
+    sessionToken?: string;
+    region: string;
+}
+export declare function awsEnvironment(env?: NodeJS.ProcessEnv): AwsEnvironment;
+/**
+ * A presigned GET of STS GetCallerIdentity on the region's dual-stack
+ * endpoint. Host is the only signed header: the gateway forwards the query
+ * alone (ADR 0068), so a signature over any other header could never verify.
+ */
+export declare function presignCallerIdentity(aws: AwsEnvironment, signingDate?: Date): Promise<string>;

package/dist/aws.js

@@ -0,0 +1,34 @@
+// The AWS calls a serverless runtime makes with its function role, signed
+// here rather than through an AWS SDK client (ADR 0065). Credentials and the
+// region come from the Lambda environment on every call.
+import { Sha256 } from '@aws-crypto/sha256-js';
+import { HttpRequest } from '@smithy/protocol-http';
+import { SignatureV4 } from '@smithy/signature-v4';
+export function awsEnvironment(env = process.env) {
+    const accessKeyId = env.AWS_ACCESS_KEY_ID;
+    const secretAccessKey = env.AWS_SECRET_ACCESS_KEY;
+    const region = env.AWS_REGION || env.AWS_DEFAULT_REGION;
+    if (!accessKeyId || !secretAccessKey)
+        throw new Error('the function has no AWS credentials in its environment (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY)');
+    if (!region)
+        throw new Error('the function has no AWS region in its environment (AWS_REGION)');
+    return { accessKeyId, secretAccessKey, ...(env.AWS_SESSION_TOKEN ? { sessionToken: env.AWS_SESSION_TOKEN } : {}), region };
+}
+function signer(aws, service) {
+    return new SignatureV4({ service, region: aws.region, sha256: Sha256, credentials: { accessKeyId: aws.accessKeyId, secretAccessKey: aws.secretAccessKey, ...(aws.sessionToken ? { sessionToken: aws.sessionToken } : {}) } });
+}
+/**
+ * A presigned GET of STS GetCallerIdentity on the region's dual-stack
+ * endpoint. Host is the only signed header: the gateway forwards the query
+ * alone (ADR 0068), so a signature over any other header could never verify.
+ */
+export async function presignCallerIdentity(aws, signingDate = new Date()) {
+    const hostname = `sts.${aws.region}.api.aws`;
+    const request = new HttpRequest({ method: 'GET', protocol: 'https:', hostname, path: '/', query: { Action: 'GetCallerIdentity', Version: '2011-06-15' }, headers: { host: hostname } });
+    const signed = await signer(aws, 'sts').presign(request, { expiresIn: 300, signingDate });
+    const query = new URLSearchParams();
+    for (const [key, value] of Object.entries(signed.query ?? {}))
+        if (typeof value === 'string')
+            query.set(key, value);
+    return `https://${hostname}/?${query.toString()}`;
+}

package/dist/gateway-session.d.ts

@@ -0,0 +1,22 @@
+export declare const SESSION_PATH = "/_harbour/internal/session";
+export interface GatewaySessionOptions {
+    gatewayUrl: string;
+    env?: NodeJS.ProcessEnv;
+    fetch?: typeof fetch;
+    /** The pauses between attempts the gateway or STS did not answer; the tests shorten them. */
+    retryDelaysMs?: number[];
+    now?: () => number;
+}
+export declare class GatewaySession {
+    private readonly options;
+    private current;
+    private pending;
+    constructor(options: GatewaySessionOptions);
+    /**
+     * The cached token while it stays valid for at least `minValidityMs`, else a
+     * new one. Concurrent callers share one exchange.
+     */
+    token(minValidityMs: number): Promise<string>;
+    private now;
+    private exchange;
+}

package/dist/gateway-session.js

@@ -0,0 +1,65 @@
+// The runtime's gateway identity on a serverless cell, where there is no
+// projected ServiceAccount token to read (ISOMORPH_GATEWAY_IDENTITY=sts-session,
+// ADR 0065). The runtime proves its function role with a presigned STS
+// GetCallerIdentity and the gateway answers with a one-hour bearer for the app
+// whose declaration names that role (the gateway's ADR 0068).
+import { setTimeout as sleep } from 'node:timers/promises';
+import { awsEnvironment, presignCallerIdentity } from './aws.js';
+export const SESSION_PATH = '/_harbour/internal/session';
+// The gateway answers 503 when STS did not, with no Retry-After; an ALB in
+// front answers 502 or 504 while the gateway task restarts.
+const RETRY_STATUSES = new Set([502, 503, 504]);
+const RETRY_DELAYS_MS = [250, 500, 1_000, 2_000, 4_000];
+export class GatewaySession {
+    options;
+    current;
+    pending;
+    constructor(options) {
+        this.options = options;
+    }
+    /**
+     * The cached token while it stays valid for at least `minValidityMs`, else a
+     * new one. Concurrent callers share one exchange.
+     */
+    async token(minValidityMs) {
+        if (this.current && this.current.expiresAt - this.now() >= minValidityMs)
+            return this.current.token;
+        this.pending ??= this.exchange().finally(() => { this.pending = undefined; });
+        return this.pending;
+    }
+    now() { return (this.options.now ?? Date.now)(); }
+    async exchange() {
+        const delays = this.options.retryDelaysMs ?? RETRY_DELAYS_MS;
+        let refusedOnce = false;
+        for (let attempt = 0;; attempt += 1) {
+            // Presigned per attempt: the gateway refuses one signed more than five minutes ago.
+            const presignedUrl = await presignCallerIdentity(awsEnvironment(this.options.env));
+            let response;
+            let failure;
+            try {
+                response = await (this.options.fetch ?? fetch)(`${this.options.gatewayUrl}${SESSION_PATH}`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ presignedUrl }), signal: AbortSignal.timeout(10_000) });
+                failure = `the gateway answered ${response.status}`;
+            }
+            catch (error) {
+                failure = `the gateway did not answer: ${error instanceof Error ? error.message : String(error)}`;
+            }
+            if (response?.ok) {
+                const body = await response.json();
+                const expiresAt = typeof body.data?.expiresAt === 'string' ? Date.parse(body.data.expiresAt) : NaN;
+                if (typeof body.data?.token !== 'string' || !body.data.token || Number.isNaN(expiresAt))
+                    throw new Error('the gateway session answer has no token and expiry');
+                this.current = { token: body.data.token, expiresAt };
+                return this.current.token;
+            }
+            // A refusal gets one more exchange with a new presign; the second is final.
+            if (response?.status === 401 && !refusedOnce) {
+                refusedOnce = true;
+                continue;
+            }
+            const retryable = response === undefined || RETRY_STATUSES.has(response.status);
+            if (!retryable || attempt >= delays.length)
+                throw new Error(`the gateway session was not issued: ${failure}`);
+            await sleep(delays[attempt]);
+        }
+    }
+}

package/dist/index.d.ts

@@ -1126,6 +1126,8 @@ export interface SlackUserLookupResult {
     displayName: string;
 }
 export interface WarehouseViewReadResult {
+    /** True when these are development sample rows, not warehouse data. Use this to label charts and exports. */
+    sample?: boolean;
     rows: Array<Record<string, unknown>>;
     /** True when more rows matched than `limit`: the rows are incomplete, so never total or average them in code. */
     truncated: boolean;

package/dist/runtime.d.ts

@@ -85,6 +85,8 @@ export interface RuntimeOptions {
     queuePollMs?: number;
     /** Set when the runtime itself runs the App Gateway for its trusted actions (the Lambda option). */
     localGateway?: Omit<LocalGatewayOptions, 'log'>;
+    /** 'sts-session' when the workload's bearer is a gateway session for the function role (ISOMORPH_GATEWAY_IDENTITY). */
+    gatewayIdentity?: 'sts-session';
 }
 export declare class Runtime {
     private readonly options;
@@ -97,6 +99,7 @@ export declare class Runtime {
     private queueLive;
     private queueWake;
     private readonly runs;
+    private session;
     private readonly log;
     readonly server: import("http").Server<typeof IncomingMessage, typeof ServerResponse>;
     constructor(options: RuntimeOptions);

package/dist/runtime.js

@@ -49,6 +49,10 @@
 //                                 runs without waiting on the data path. Set by
 //                                 Provision; the table exists otherwise
 //   ISOMORPH_APP_ROOT             the app root (default: the working directory)
+//   ISOMORPH_GATEWAY_IDENTITY=sts-session
+//                                 the workload's bearer is a gateway session the
+//                                 runtime obtains with its function role (a
+//                                 serverless cell, ADR 0065), not a token file
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { createServer } from 'node:http';
 import { readFile, readdir, stat } from 'node:fs/promises';
@@ -77,6 +81,11 @@ const MAX_BODY_BYTES = 1 << 20;
 const LEASE_MS = 5 * 60_000;
 const QUEUE_POLL_MS = 2_000;
 const TOKEN_REFRESH_MS = 60_000;
+// A gateway session lasts an hour. An action runs at most 300 s, so a request
+// takes a new one in the session's last 10 minutes; a scheduled run may take
+// up to 900 s on Lambda and takes one in the last 15.
+const SESSION_MIN_VALIDITY_MS = 10 * 60_000;
+const JOB_SESSION_MIN_VALIDITY_MS = 15 * 60_000;
 const DEFAULT_MAX_ATTEMPTS = 3;
 // A CronJob pod may start while the app's database is still waking: --run-job
 // waits this long for the gateway's data path, probing every retry interval.
@@ -248,6 +257,9 @@ export class Runtime {
     queueLive = false;
     queueWake = false;
     runs;
+    // Built on first use: the AWS signing modules load only on a serverless
+    // cell, so a cluster runtime never imports them.
+    session;
     log;
     server = createServer((request, response) => { void this.serve(request, response); });
     constructor(options) {
@@ -257,7 +269,12 @@ export class Runtime {
     }
     async start() {
         this.inventory = await discover(this.options.root);
-        await this.refreshToken();
+        // A Web Function must listen within 10 s of starting, so the session is
+        // only begun here; the first request that needs it waits for it.
+        if (this.options.gatewayIdentity)
+            void this.refreshToken().catch((error) => this.log(`gateway session: ${error instanceof Error ? error.message : String(error)}`));
+        else
+            await this.refreshToken();
         if (this.options.localGateway && this.inventory.trusted.length > 0) {
             this.localGateway = new LocalGateway({ ...this.options.localGateway, log: this.log });
             await this.localGateway.start();
@@ -328,7 +345,7 @@ export class Runtime {
      */
     async runJobOnce(name, now = new Date()) {
         this.inventory = await discover(this.options.root);
-        await this.refreshToken();
+        await this.refreshToken(JOB_SESSION_MIN_VALIDITY_MS);
         if (!this.inventory.jobs.some((job) => job.name === name)) {
             this.log(`this app has no ${JOBS_DIR}/${name}.ts`);
             return false;
@@ -401,7 +418,12 @@ export class Runtime {
         })().catch(error => { this.aiBinding = undefined; throw error; });
         await this.aiBinding;
     }
-    async refreshToken() {
+    async refreshToken(minValidityMs = SESSION_MIN_VALIDITY_MS) {
+        if (this.options.gatewayIdentity) {
+            this.session ??= import('./gateway-session.js').then(({ GatewaySession }) => new GatewaySession({ gatewayUrl: this.options.gatewayUrl }));
+            process.env.ISOMORPH_WORKLOAD_TOKEN = await (await this.session).token(minValidityMs);
+            return;
+        }
         if (!this.options.tokenFile)
             return;
         const token = (await readFile(this.options.tokenFile, 'utf8')).trim();
@@ -553,6 +575,12 @@ export class Runtime {
                 return refuse(response, 400, 'VALIDATION_FAILED', 'the request body is not JSON', requestId);
             }
         }
+        // Only the runtime's own calls, a trusted action's and the AI binding
+        // send the bearer; an action acting as its caller does not wait for it.
+        // Without a session such a call fails with AUTH_REQUIRED, which the builder reads.
+        const sendsBearer = name.startsWith(RESERVED_PREFIX) ? name !== PING_ACTION : this.inventory.trusted.includes(name) || Boolean(process.env.ISOMORPH_AI_VERSION_ID);
+        if (this.options.gatewayIdentity && sendsBearer)
+            await this.refreshToken().catch((error) => this.log(`gateway session: ${error instanceof Error ? error.message : String(error)}`));
         try {
             if (name.startsWith(RESERVED_PREFIX))
                 return answer(response, 200, { data: await this.reserved(name, input, context) }, requestId);
@@ -663,6 +691,7 @@ export function optionsFromEnvironment(env = process.env) {
         mode: env.ISOMORPH_RUNTIME_MODE === 'gate' ? 'gate' : env.ISOMORPH_JOBS_SCHEDULER === 'platform' ? 'actions' : 'full',
         tokenFile: env.HARBOUR_WORKLOAD_TOKEN_FILE || undefined,
         jobRuns: env.ISOMORPH_JOB_RUNS !== 'none',
+        ...(env.ISOMORPH_GATEWAY_IDENTITY === 'sts-session' ? { gatewayIdentity: 'sts-session' } : {}),
         ...(env.ISOMORPH_LOCAL_GATEWAY_BINARY && env.ISOMORPH_LOCAL_GATEWAY_CONFIG_FILE
             ? { localGateway: { binary: env.ISOMORPH_LOCAL_GATEWAY_BINARY, configFile: env.ISOMORPH_LOCAL_GATEWAY_CONFIG_FILE, url: (env.ISOMORPH_LOCAL_GATEWAY_URL || '').replace(/\/$/, '') } }
             : {}),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@isomorph.ai/app-sdk",
-  "version": "1.21.0",
+  "version": "1.22.0",
   "type": "module",
   "repository": {
     "type": "git",
@@ -38,6 +38,9 @@
     }
   },
   "dependencies": {
+    "@aws-crypto/sha256-js": "5.2.0",
+    "@smithy/protocol-http": "5.6.2",
+    "@smithy/signature-v4": "5.7.4",
     "acorn": "8.18.0"
   }
 }