@isomorph.ai/app-sdk 2.4.0 → 2.6.0

package/README.md

@@ -365,6 +365,33 @@ The calls go to the local App Gateway beside the runtime (`ISOMORPH_TRUSTED_GATE
 
 (1.17.0; data plane ADR 0057)
 
+## Public actions
+
+One door with nobody signed in: a sign-up form, a feedback box, an inbound lead. An action that
+exports `access = "public"` beside `expose = { description, input }` runs for a caller with no
+sign-in as `public:<app>` (`ctx.user.kind === 'public'`, no email, no groups). It may only insert
+rows: a select, update, delete, file, integration, AI call, realtime, another action or a job
+enqueue inside it is refused with `PUBLIC_DENIED`. A public action cannot be trusted. The page
+calls it with `isomorph.actions.invokePublic(name, input)`: a plain POST with no cookie and no
+sign-in, answering the result or an `IsomorphError` with the gateway's category. The table it
+writes says so in its row rule (`WITH CHECK (current_setting('harbour.user_id', true) = 'public:<app>')`).
+
+```ts
+// actions/signup.ts
+export const access = "public";
+export const expose = { description: 'Sign a visitor up for the launch list', input: { type: 'object', properties: { email: { type: 'string' } }, required: ['email'] } };
+
+export default async function signup(input: { email: string }) {
+  await isomorph.data.from('launch_signups').insert({ email: input.email });
+  return { ok: true };
+}
+
+// page
+await isomorph.actions.invokePublic('signup', { email });
+```
+
+(2.6.0)
+
 ## Browser read tools
 
 Install optional peers `ai` and `playwright-core@1.58.2`. Locally run `npx playwright-core install chromium --only-shell`; V2 packages Chromium in the existing app image. An existing system executable can be supplied as executablePath.
@@ -396,7 +423,7 @@ const computerUse = createComputerUseTool({ runKey: ctx.runId ?? `my-job/${ctx.s
 // Add { computerUse } to generateText's tools. It returns { status: 'done' | 'failed', summary, finalUrl, downloads }.
 ```
 
-- The tool calls the task API at `ISOMORPH_COMPUTER_USE_URL` (region `ISOMORPH_COMPUTER_USE_REGION`, default `us-east-1`); Provision sets both when the cell has the API. Each request is signed with SigV4 (`execute-api`) as the runtime's own role: the Lambda environment's credentials, or on a cluster pod its ServiceAccount role through STS `AssumeRoleWithWebIdentity`.
+- Hosted, the tool posts to its App Gateway (`ISOMORPH_GATEWAY_URL`, `/_harbour/computer-use/...`) with the workload token; the gateway and governance carry the call into Harbour's account (data plane ADR 0103). Only a runtime with no gateway URL calls the task API at `ISOMORPH_COMPUTER_USE_URL` directly (region `ISOMORPH_COMPUTER_USE_REGION`, default `us-east-1`), signed with SigV4 as its own role; Provision no longer sets those (ADR 0110).
 - It starts the task with `POST /tasks`, then checks `POST /tasks/check` every 5 s until the task is `done`, `failed` or `waiting_for_input`. Waiting returns immediately; end the app job rather than holding a worker while a person signs in.
 - It calls `progress(step count, note)` on every new step and at least once a minute, so the job's lease does not run out.
 - When `cancelled()` turns true it sends `POST /tasks/cancel` once and keeps checking until the task has `failed`.

package/dist/index.d.ts

@@ -38,10 +38,12 @@ export interface IsomorphUser {
     appUser?: unknown;
     /**
      * Who is calling: a `'person'` signed in through the browser or an MCP
-     * client, or a `'service'` holding a credential the company's IT issued,
-     * whose `id` and `name` are the credential's. Absent means a person.
+     * client, a `'service'` holding a credential the company's IT issued,
+     * whose `id` and `name` are the credential's, or `'public'`: nobody signed
+     * in, calling an action that exports `access = "public"` (`id` is
+     * `public:<app>`, no email, no groups). Absent means a person.
      */
-    kind?: 'person' | 'service';
+    kind?: 'person' | 'service' | 'public';
 }
 /**
  * `export const expose = { description, input }` on an action, beside
@@ -2066,6 +2068,13 @@ export declare function createClient(options?: ClientOptions): {
         invoke: <T = unknown, P = string>(name: string, input: unknown, options?: {
             onProgress?: (step: P) => void;
         }) => Promise<T>;
+        /**
+         * Call an action that exports `access = "public"` with no sign-in: a
+         * plain POST to `/_harbour/api/<name>` on the API host, no cookie, no
+         * credential, no sign-in redirect. The result is the action's, the
+         * error an `IsomorphError` with the gateway's category.
+         */
+        invokePublic: <T = unknown>(name: string, input: unknown) => Promise<T>;
     };
     jobs: {
         /** Select the owner's folder for a declared configurable file trigger. */

package/dist/index.js

@@ -819,6 +819,26 @@ export function createClient(options = {}) {
                 }
                 return transport.json(path, { method: 'POST', body: JSON.stringify(input) }, options.onProgress);
             },
+            /**
+             * Call an action that exports `access = "public"` with no sign-in: a
+             * plain POST to `/_harbour/api/<name>` on the API host, no cookie, no
+             * credential, no sign-in redirect. The result is the action's, the
+             * error an `IsomorphError` with the gateway's category.
+             */
+            invokePublic: async (name, input) => {
+                const response = await transport.fetch(`${transport.baseUrl}/_harbour/api/${encodeURIComponent(name)}`, {
+                    method: 'POST', credentials: 'omit', headers: { 'content-type': 'application/json' }, body: JSON.stringify(input ?? {}),
+                });
+                let body = {};
+                try {
+                    body = await response.json();
+                }
+                catch { /* not JSON: the status says what happened */ }
+                if (!response.ok || body.error) {
+                    throw new IsomorphError(body.error?.category ?? 'INTERNAL', body.error?.message ?? `the public action answered ${response.status}`, body.requestId, undefined, response.status);
+                }
+                return body.data;
+            },
         },
         jobs: {
             /** Select the owner's folder for a declared configurable file trigger. */

package/dist/jobs.d.ts

@@ -58,6 +58,8 @@ export interface JobContext {
 }
 /** Whether the module says `export const <name> = true`, read without importing it; a module that does not parse does not. */
 export declare function exportsTrue(file: string, name: string): Promise<boolean>;
+/** Whether the module says `export const <name> = <value>` with that one literal, read statically; nothing computed counts. */
+export declare function exportsLiteral(file: string, name: string, value: string | boolean): Promise<boolean>;
 export declare function discoverJobs(root: string): Promise<JobDefinition[]>;
 type Handler = (...args: unknown[]) => unknown;
 export declare function loadHandler(root: string, dir: string, name: string): Promise<Handler>;

package/dist/jobs.js

@@ -103,7 +103,11 @@ function parseModule(source) {
     return parse(stripTypeScriptTypes(source), { ecmaVersion: 'latest', sourceType: 'module' }).body;
 }
 /** Whether the module says `export const <name> = true`, read without importing it; a module that does not parse does not. */
-export async function exportsTrue(file, name) {
+export function exportsTrue(file, name) {
+    return exportsLiteral(file, name, true);
+}
+/** Whether the module says `export const <name> = <value>` with that one literal, read statically; nothing computed counts. */
+export async function exportsLiteral(file, name, value) {
     let statements;
     try {
         statements = parseModule(await readFile(file, 'utf8'));
@@ -114,7 +118,7 @@ export async function exportsTrue(file, name) {
     return statements.some(statement => statement.type === 'ExportNamedDeclaration'
         && statement.declaration?.type === 'VariableDeclaration' && statement.declaration.kind === 'const'
         && statement.declaration.declarations.some(declaration => declaration.id.type === 'Identifier' && declaration.id.name === name
-            && declaration.init?.type === 'Literal' && declaration.init.value === true));
+            && declaration.init?.type === 'Literal' && declaration.init.value === value));
 }
 export async function discoverJobs(root) {
     const directory = join(root, JOBS_DIR);

package/dist/runtime.d.ts

@@ -39,6 +39,8 @@ export interface RuntimeInventory {
     trusted: string[];
     /** The actions whose module says `export const expose = { description, input }`, by name: what the kit gate records as exposed (ADR 0100). */
     exposed: Record<string, ActionExposure>;
+    /** The actions whose module says `export const access = "public"`: the gateway runs them for callers with no sign-in (data plane ADR 0114). */
+    public: string[];
     jobs: JobDefinition[];
 }
 /** Every `actions/<name>.ts` and `jobs/<name>.ts` the app carries, by logical name. */

package/dist/runtime.js

@@ -68,7 +68,7 @@ import { pathToFileURL } from 'node:url';
 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 { FILE_MIME_TYPES, providerFileId, actionExposure, discoverJobs, exportsLiteral, 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';
@@ -121,8 +121,9 @@ export async function discover(root) {
     const trusted = await Promise.all(actions.map((name) => exportsTrue(join(root, ACTIONS_DIR, `${name}.ts`), 'trusted')));
     const exposures = await Promise.all(actions.map((name) => actionExposure(join(root, ACTIONS_DIR, `${name}.ts`))));
     const exposed = Object.fromEntries(actions.flatMap((name, index) => exposures[index] ? [[name, exposures[index]]] : []));
+    const publicAccess = await Promise.all(actions.map((name) => exportsLiteral(join(root, ACTIONS_DIR, `${name}.ts`), 'access', 'public')));
     const jobs = await discoverJobs(root);
-    return { actions, trusted: actions.filter((_, index) => trusted[index]), exposed, jobs };
+    return { actions, trusted: actions.filter((_, index) => trusted[index]), exposed, public: actions.filter((_, index) => publicAccess[index]), jobs };
 }
 // ---- Cron ------------------------------------------------------------------
 /** One field of a five-field cron expression: numbers, `*`, lists, ranges and steps, no names. */
@@ -321,7 +322,7 @@ export class Runs {
 }
 export class Runtime {
     options;
-    inventory = { actions: [], trusted: [], exposed: {}, jobs: [] };
+    inventory = { actions: [], trusted: [], exposed: {}, public: [], jobs: [] };
     localGateway;
     running = new Set();
     timers = [];
@@ -728,8 +729,10 @@ export class Runtime {
             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' } : {}),
+            // shape `/_harbour/identity/current` already answers. A public action's caller
+            // arrives as `public:<app>` with no email and no groups (data plane ADR 0114).
+            // Anything else is a person.
+            ...(userId.startsWith('service:') ? { kind: 'service' } : userId.startsWith('public:') ? { kind: 'public' } : {}),
             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')),
@@ -885,7 +888,9 @@ export class Runtime {
         const owner = context.user.id;
         switch (name) {
             case PING_ACTION: {
-                const answer = { ok: true, mode: this.options.mode, actions: this.inventory.actions, trusted: this.inventory.trusted, exposed: this.inventory.exposed, jobs: this.inventory.jobs.map((job) => job.name) };
+                // `hooks` is what the local gateway's hooks entrance serves under `isomorph dev` (data plane ADR 0112).
+                const hooks = this.inventory.jobs.flatMap((job) => job.trigger?.type === 'webhook' ? [{ job: job.name, provider: job.trigger.provider }] : []);
+                const answer = { ok: true, mode: this.options.mode, actions: this.inventory.actions, trusted: this.inventory.trusted, exposed: this.inventory.exposed, public: this.inventory.public, jobs: this.inventory.jobs.map((job) => job.name), hooks };
                 return this.options.mode === 'gate' ? { ...answer, loadFailures: await this.loadFailures() } : answer;
             }
             case ENQUEUE_ACTION: {

package/package.json

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