appilot-mcp 0.0.1 → 0.1.0

package/dist/remote/oauth.d.ts

@@ -0,0 +1,74 @@
+/**
+ * OAuth 2.1 authorization server for the remote MCP service.
+ *
+ * ChatGPT and claude.ai offer exactly two ways to reach a remote MCP server:
+ * no authentication, or OAuth. Neither has a field for pasting an API key. So a
+ * remote Appilot MCP endpoint that anyone can safely use has to speak OAuth,
+ * with PKCE and dynamic client registration, and that is what this file is.
+ *
+ * What it does NOT do is own identity. Appilot already has users, orgs, and a
+ * scoped, revocable credential for exactly this purpose: the service token. The
+ * authorization step therefore collects a service token on the consent screen,
+ * verifies it against the instance, and seals it inside the OAuth tokens it
+ * issues. The service holds no user database, no client registry, and no
+ * credential of its own. See remote/tokens.ts for why everything is sealed
+ * rather than stored.
+ *
+ * Spec: docs/architecture/appilot-mcp.md, section "Remote deployment".
+ */
+import type { Response } from 'express';
+import type { OAuthServerProvider, AuthorizationParams } from '@modelcontextprotocol/sdk/server/auth/provider.js';
+import type { OAuthRegisteredClientsStore } from '@modelcontextprotocol/sdk/server/auth/clients.js';
+import type { OAuthClientInformationFull, OAuthTokens } from '@modelcontextprotocol/sdk/shared/auth.js';
+import type { AuthInfo } from '@modelcontextprotocol/sdk/server/auth/types.js';
+/** Scopes this authorization server can grant, mirroring the service-token scopes. */
+export declare const SUPPORTED_SCOPES: readonly ["config:read", "config:write"];
+/** What the instance says a credential reaches. Absent on instances without /config/whoami. */
+export interface TokenIdentity {
+    organizationId: number | null;
+    appId: number | null;
+    scopes: string[];
+}
+export interface AppilotOAuthOptions {
+    /** Public origin of this service, used to build the consent form action. */
+    publicUrl: URL;
+    /** The Appilot backend this deployment serves. */
+    baseUrl: string;
+    /** Secret behind every sealed artifact. */
+    secret: string;
+    /** Swappable for tests; defaults to a real call to GET /config/whoami. */
+    verifyServiceToken?: (pat: string) => Promise<TokenIdentity | null>;
+}
+export declare class AppilotOAuthProvider implements OAuthServerProvider {
+    private readonly options;
+    private readonly sealer;
+    private readonly consentPath;
+    private readonly verifyServiceToken;
+    constructor(options: AppilotOAuthOptions);
+    /**
+     * Client registrations are sealed into the client_id itself, so dynamic
+     * registration works without a registry. A client that presents an id we did
+     * not issue fails to open it, which is the same outcome as an unknown id.
+     */
+    get clientsStore(): OAuthRegisteredClientsStore;
+    authorize(client: OAuthClientInformationFull, params: AuthorizationParams, res: Response): Promise<void>;
+    /** The authorization request travels through the consent form, so it is sealed too. */
+    private sealAuthRequest;
+    /**
+     * Handle the consent form post: verify the pasted service token, then either
+     * redirect back with an authorization code or re-render with the reason it
+     * failed. Returns the HTML to render, or the redirect to follow.
+     */
+    handleConsent(form: Record<string, unknown>): Promise<{
+        redirect: string;
+    } | {
+        html: string;
+        status: number;
+    }>;
+    private openCode;
+    challengeForAuthorizationCode(client: OAuthClientInformationFull, authorizationCode: string): Promise<string>;
+    exchangeAuthorizationCode(client: OAuthClientInformationFull, authorizationCode: string, _codeVerifier?: string, redirectUri?: string): Promise<OAuthTokens>;
+    exchangeRefreshToken(client: OAuthClientInformationFull, refreshToken: string, scopes?: string[]): Promise<OAuthTokens>;
+    private issue;
+    verifyAccessToken(token: string): Promise<AuthInfo>;
+}

package/dist/remote/oauth.js

@@ -0,0 +1,288 @@
+/**
+ * OAuth 2.1 authorization server for the remote MCP service.
+ *
+ * ChatGPT and claude.ai offer exactly two ways to reach a remote MCP server:
+ * no authentication, or OAuth. Neither has a field for pasting an API key. So a
+ * remote Appilot MCP endpoint that anyone can safely use has to speak OAuth,
+ * with PKCE and dynamic client registration, and that is what this file is.
+ *
+ * What it does NOT do is own identity. Appilot already has users, orgs, and a
+ * scoped, revocable credential for exactly this purpose: the service token. The
+ * authorization step therefore collects a service token on the consent screen,
+ * verifies it against the instance, and seals it inside the OAuth tokens it
+ * issues. The service holds no user database, no client registry, and no
+ * credential of its own. See remote/tokens.ts for why everything is sealed
+ * rather than stored.
+ *
+ * Spec: docs/architecture/appilot-mcp.md, section "Remote deployment".
+ */
+import { InvalidGrantError, InvalidTokenError, InvalidClientError, ServerError, } from '@modelcontextprotocol/sdk/server/auth/errors.js';
+import { TokenSealer, SealError } from './tokens.js';
+import { renderConsentPage, renderErrorPage } from './consent.js';
+/** Scopes this authorization server can grant, mirroring the service-token scopes. */
+export const SUPPORTED_SCOPES = ['config:read', 'config:write'];
+const AUTH_REQUEST_TTL = 10 * 60;
+const CODE_TTL = 60;
+const ACCESS_TTL = 60 * 60;
+const REFRESH_TTL = 90 * 24 * 60 * 60;
+const SERVICE_TOKEN_PREFIX = 'appilot_pat_';
+/**
+ * Ask the instance what a pasted service token actually reaches. Returns null
+ * when the instance rejects it. Returns an empty identity when the instance
+ * predates /config/whoami, which is not a rejection: older instances simply
+ * cannot answer, and the first tool call will surface a bad token instead.
+ */
+async function defaultVerifyServiceToken(baseUrl, pat) {
+    let res;
+    try {
+        res = await fetch(`${baseUrl}/config/whoami`, {
+            headers: { Authorization: `Bearer ${pat}`, Accept: 'application/json' },
+        });
+    }
+    catch (err) {
+        throw new ServerError(`Could not reach the Appilot instance at ${baseUrl}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (res.status === 401 || res.status === 403)
+        return null;
+    if (res.status === 404) {
+        // Instance predates the self-check. Accept the token on shape alone.
+        return { organizationId: null, appId: null, scopes: [...SUPPORTED_SCOPES] };
+    }
+    if (!res.ok) {
+        throw new ServerError(`The Appilot instance answered ${res.status} while verifying the service token.`);
+    }
+    const body = (await res.json());
+    return {
+        organizationId: body.organizationId ?? null,
+        appId: body.appId ?? null,
+        scopes: Array.isArray(body.scopes) && body.scopes.length ? body.scopes : ['config:read'],
+    };
+}
+export class AppilotOAuthProvider {
+    options;
+    sealer;
+    consentPath;
+    verifyServiceToken;
+    constructor(options) {
+        this.options = options;
+        this.sealer = new TokenSealer(options.secret);
+        this.consentPath = new URL('/consent', options.publicUrl).toString();
+        this.verifyServiceToken =
+            options.verifyServiceToken ?? (pat => defaultVerifyServiceToken(options.baseUrl, pat));
+    }
+    /**
+     * Client registrations are sealed into the client_id itself, so dynamic
+     * registration works without a registry. A client that presents an id we did
+     * not issue fails to open it, which is the same outcome as an unknown id.
+     */
+    get clientsStore() {
+        return {
+            registerClient: async (client) => {
+                // Every registration is a public client. MCP mandates PKCE, which is
+                // the proof of possession here, and a shared secret would have to be
+                // carried inside the client id we hand back: a secret in the same
+                // string as the identifier it is supposed to protect. Drop the one
+                // the registration handler generated rather than seal it.
+                const { client_secret: _secret, client_secret_expires_at: _expires, ...meta } = client;
+                const publicMeta = { ...meta, token_endpoint_auth_method: 'none' };
+                const client_id = await this.sealer.seal('client', { meta: publicMeta });
+                return {
+                    ...publicMeta,
+                    client_id,
+                    client_id_issued_at: Math.floor(Date.now() / 1000),
+                };
+            },
+            getClient: async (client_id) => {
+                try {
+                    const sealed = await this.sealer.open('client', client_id);
+                    return {
+                        ...sealed.meta,
+                        client_id,
+                        client_id_issued_at: sealed.iat,
+                        token_endpoint_auth_method: 'none',
+                    };
+                }
+                catch {
+                    return undefined;
+                }
+            },
+        };
+    }
+    async authorize(client, params, res) {
+        const requested = (params.scopes?.length ? params.scopes : ['config:read']).filter(s => SUPPORTED_SCOPES.includes(s));
+        const sealedRequest = await this.sealAuthRequest({
+            client_id: client.client_id,
+            redirect_uri: params.redirectUri,
+            code_challenge: params.codeChallenge,
+            state: params.state,
+            scopes: requested.length ? requested : ['config:read'],
+            resource: params.resource?.toString(),
+        });
+        res.set('Content-Type', 'text/html; charset=utf-8').send(renderConsentPage({
+            request: sealedRequest,
+            action: this.consentPath,
+            clientName: client.client_name || 'an MCP client',
+            baseUrl: this.options.baseUrl,
+            scopes: requested.length ? requested : ['config:read'],
+        }));
+    }
+    /** The authorization request travels through the consent form, so it is sealed too. */
+    sealAuthRequest(request) {
+        return this.sealer.seal('code', { ...request, stage: 'request' }, AUTH_REQUEST_TTL);
+    }
+    /**
+     * Handle the consent form post: verify the pasted service token, then either
+     * redirect back with an authorization code or re-render with the reason it
+     * failed. Returns the HTML to render, or the redirect to follow.
+     */
+    async handleConsent(form) {
+        const rawRequest = typeof form.request === 'string' ? form.request : '';
+        let request;
+        try {
+            request = await this.sealer.open('code', rawRequest);
+        }
+        catch {
+            return {
+                status: 400,
+                html: renderErrorPage('This sign-in link expired', 'Start the connection again from the client that sent you here. A consent link is valid for ten minutes.'),
+            };
+        }
+        if (request.stage !== 'request') {
+            return { status: 400, html: renderErrorPage('Invalid request', 'That token is not a consent request.') };
+        }
+        const redirect = new URL(request.redirect_uri);
+        if (form.action === 'deny') {
+            redirect.searchParams.set('error', 'access_denied');
+            redirect.searchParams.set('error_description', 'The person declined the request.');
+            if (request.state)
+                redirect.searchParams.set('state', request.state);
+            return { redirect: redirect.toString() };
+        }
+        const pat = typeof form.pat === 'string' ? form.pat.trim() : '';
+        const reRender = (error) => ({
+            status: 400,
+            html: renderConsentPage({
+                request: rawRequest,
+                action: this.consentPath,
+                clientName: 'an MCP client',
+                baseUrl: this.options.baseUrl,
+                scopes: request.scopes,
+                error,
+            }),
+        });
+        if (!pat.startsWith(SERVICE_TOKEN_PREFIX)) {
+            return reRender(`That does not look like a service token. A service token starts with ${SERVICE_TOKEN_PREFIX} and is created in the Backoffice under Settings, Service Tokens.`);
+        }
+        let identity;
+        try {
+            identity = await this.verifyServiceToken(pat);
+        }
+        catch (err) {
+            return reRender(err instanceof Error ? err.message : String(err));
+        }
+        if (!identity) {
+            return reRender('The instance rejected that service token. It may have been revoked or have expired.');
+        }
+        // Never grant more than the token itself carries.
+        const granted = request.scopes.filter(s => identity.scopes.includes(s));
+        if (granted.length === 0) {
+            return reRender(`That token grants ${identity.scopes.join(', ')}, which does not cover the requested ${request.scopes.join(', ')}. Create a token with the needed scope.`);
+        }
+        // An app-scoped token dictates its own app; a form value cannot widen it.
+        const formAppId = Number(form.app_id);
+        const appId = identity.appId ?? (Number.isInteger(formAppId) && formAppId > 0 ? formAppId : undefined);
+        const code = await this.sealer.seal('code', {
+            ...request,
+            stage: 'code',
+            scopes: granted,
+            pat,
+            app_id: appId,
+            organization_id: identity.organizationId ?? undefined,
+        }, CODE_TTL);
+        redirect.searchParams.set('code', code);
+        if (request.state)
+            redirect.searchParams.set('state', request.state);
+        return { redirect: redirect.toString() };
+    }
+    async openCode(client, authorizationCode) {
+        let code;
+        try {
+            code = await this.sealer.open('code', authorizationCode);
+        }
+        catch (err) {
+            throw new InvalidGrantError(err instanceof SealError ? 'The authorization code is invalid or has expired.' : String(err));
+        }
+        if (code.stage !== 'code')
+            throw new InvalidGrantError('That token is not an authorization code.');
+        if (code.client_id !== client.client_id)
+            throw new InvalidClientError('The authorization code was issued to a different client.');
+        return code;
+    }
+    async challengeForAuthorizationCode(client, authorizationCode) {
+        return (await this.openCode(client, authorizationCode)).code_challenge;
+    }
+    async exchangeAuthorizationCode(client, authorizationCode, _codeVerifier, redirectUri) {
+        const code = await this.openCode(client, authorizationCode);
+        if (redirectUri !== undefined && redirectUri !== code.redirect_uri) {
+            throw new InvalidGrantError('redirect_uri does not match the one the code was issued for.');
+        }
+        return this.issue(code);
+    }
+    async exchangeRefreshToken(client, refreshToken, scopes) {
+        let sealed;
+        try {
+            sealed = await this.sealer.open('refresh', refreshToken);
+        }
+        catch {
+            throw new InvalidGrantError('The refresh token is invalid or has expired.');
+        }
+        if (sealed.client_id !== client.client_id) {
+            throw new InvalidClientError('The refresh token was issued to a different client.');
+        }
+        // A refresh may narrow the grant, never widen it.
+        const narrowed = scopes?.length ? sealed.scopes.filter(s => scopes.includes(s)) : sealed.scopes;
+        if (narrowed.length === 0)
+            throw new InvalidGrantError('The requested scopes are not covered by this grant.');
+        return this.issue({ ...sealed, scopes: narrowed });
+    }
+    async issue(grant) {
+        const payload = {
+            client_id: grant.client_id,
+            scopes: grant.scopes,
+            pat: grant.pat,
+            app_id: grant.app_id,
+            organization_id: grant.organization_id,
+            resource: grant.resource,
+        };
+        const [access_token, refresh_token] = await Promise.all([
+            this.sealer.seal('access', payload, ACCESS_TTL),
+            this.sealer.seal('refresh', payload, REFRESH_TTL),
+        ]);
+        return {
+            access_token,
+            token_type: 'Bearer',
+            expires_in: ACCESS_TTL,
+            scope: grant.scopes.join(' '),
+            refresh_token,
+        };
+    }
+    async verifyAccessToken(token) {
+        let sealed;
+        try {
+            sealed = await this.sealer.open('access', token);
+        }
+        catch {
+            throw new InvalidTokenError('The access token is invalid or has expired.');
+        }
+        return {
+            token,
+            clientId: sealed.client_id,
+            scopes: sealed.scopes,
+            expiresAt: sealed.exp,
+            resource: sealed.resource ? new URL(sealed.resource) : undefined,
+            // The service token never leaves the server: it is read here to build the
+            // per-request Appilot client and is not echoed in any response.
+            extra: { pat: sealed.pat, appId: sealed.app_id, organizationId: sealed.organization_id },
+        };
+    }
+}

package/dist/remote/tokens.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Sealed tokens for the remote MCP service.
+ *
+ * Every artifact the OAuth authorization server hands out (client id,
+ * authorization code, access token, refresh token) is an encrypted JWT carrying
+ * its own state. That is a deliberate choice: it lets the service run with no
+ * database and no shared cache, so a second instance, a cold start, or an
+ * air-gapped copy behaves identically to the first. The cost is that a sealed
+ * artifact cannot be deleted server-side. Codes are short-lived and PKCE-bound,
+ * so replay needs the verifier; access tokens are short-lived; and the credential
+ * that actually reaches Appilot data, the service token sealed inside, is
+ * revoked where it was minted, in the Backoffice.
+ *
+ * The payload holds a live service token, so these are encrypted (JWE, A256GCM),
+ * never merely signed. A client sees an opaque string.
+ */
+/** What a sealed artifact is for. Mixing them up is rejected by the audience check. */
+export type SealKind = 'client' | 'code' | 'access' | 'refresh';
+export declare class SealError extends Error {
+}
+export declare class TokenSealer {
+    private readonly key;
+    constructor(secret: string);
+    /** Seal a payload. `ttlSeconds` omitted means no expiry (client registrations). */
+    seal(kind: SealKind, payload: Record<string, unknown>, ttlSeconds?: number): Promise<string>;
+    /** Open a sealed artifact, or throw SealError. Expiry and audience are enforced. */
+    open<T extends Record<string, unknown>>(kind: SealKind, token: string): Promise<T>;
+}

package/dist/remote/tokens.js

@@ -0,0 +1,50 @@
+/**
+ * Sealed tokens for the remote MCP service.
+ *
+ * Every artifact the OAuth authorization server hands out (client id,
+ * authorization code, access token, refresh token) is an encrypted JWT carrying
+ * its own state. That is a deliberate choice: it lets the service run with no
+ * database and no shared cache, so a second instance, a cold start, or an
+ * air-gapped copy behaves identically to the first. The cost is that a sealed
+ * artifact cannot be deleted server-side. Codes are short-lived and PKCE-bound,
+ * so replay needs the verifier; access tokens are short-lived; and the credential
+ * that actually reaches Appilot data, the service token sealed inside, is
+ * revoked where it was minted, in the Backoffice.
+ *
+ * The payload holds a live service token, so these are encrypted (JWE, A256GCM),
+ * never merely signed. A client sees an opaque string.
+ */
+import { createHash } from 'node:crypto';
+import { EncryptJWT, jwtDecrypt } from 'jose';
+const ISSUER = 'appilot-mcp';
+export class SealError extends Error {
+}
+export class TokenSealer {
+    key;
+    constructor(secret) {
+        // A256GCM needs exactly 32 bytes; the operator's secret is a passphrase of
+        // arbitrary length, so derive rather than require a precise encoding.
+        this.key = new Uint8Array(createHash('sha256').update(secret, 'utf8').digest());
+    }
+    /** Seal a payload. `ttlSeconds` omitted means no expiry (client registrations). */
+    async seal(kind, payload, ttlSeconds) {
+        let jwt = new EncryptJWT({ ...payload })
+            .setProtectedHeader({ alg: 'dir', enc: 'A256GCM' })
+            .setIssuedAt()
+            .setIssuer(ISSUER)
+            .setAudience(kind);
+        if (ttlSeconds !== undefined)
+            jwt = jwt.setExpirationTime(`${ttlSeconds}s`);
+        return jwt.encrypt(this.key);
+    }
+    /** Open a sealed artifact, or throw SealError. Expiry and audience are enforced. */
+    async open(kind, token) {
+        try {
+            const { payload } = await jwtDecrypt(token, this.key, { issuer: ISSUER, audience: kind });
+            return payload;
+        }
+        catch (err) {
+            throw new SealError(`Sealed ${kind} is invalid, expired, or was issued under a different secret: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+}

package/dist/scaffold.d.ts

@@ -0,0 +1,37 @@
+/**
+ * `scaffold_integration`: the source a host application needs, as text.
+ *
+ * The MCP server returns content and never touches the customer's filesystem.
+ * The coding agent calling it already knows where files go in that repository,
+ * has the user's approval to write them, and can reconcile them with what is
+ * there. A server that wrote files itself would be guessing at all three.
+ *
+ * The relay is the piece worth generating. It is the one part of the
+ * integration a developer must write in their own backend, it is
+ * security-critical, and getting it wrong is invisible until an auth edge case
+ * shows up in production.
+ */
+export type Framework = 'next' | 'express' | 'fastify' | 'hono' | 'remix' | 'sveltekit';
+export interface ScaffoldFile {
+    /** Suggested path, relative to the repository root. The agent may move it. */
+    path: string;
+    language: string;
+    contents: string;
+}
+export interface ScaffoldResult {
+    framework: Framework;
+    files: ScaffoldFile[];
+    install: string;
+    env: string;
+    notes: string[];
+}
+interface ScaffoldOptions {
+    framework: Framework;
+    widgetScriptUrl: string;
+    apiUrl?: string | null;
+    widgetKey?: string | null;
+    /** Namespace for externalId, so a host's ids never collide with another's. */
+    idNamespace?: string;
+}
+export declare function scaffoldIntegration(options: ScaffoldOptions): ScaffoldResult;
+export {};

package/dist/scaffold.js

@@ -0,0 +1,203 @@
+/**
+ * `scaffold_integration`: the source a host application needs, as text.
+ *
+ * The MCP server returns content and never touches the customer's filesystem.
+ * The coding agent calling it already knows where files go in that repository,
+ * has the user's approval to write them, and can reconcile them with what is
+ * there. A server that wrote files itself would be guessing at all three.
+ *
+ * The relay is the piece worth generating. It is the one part of the
+ * integration a developer must write in their own backend, it is
+ * security-critical, and getting it wrong is invisible until an auth edge case
+ * shows up in production.
+ */
+function relayFetchHandler(namespace) {
+    return `import { createWidgetTokenHandler } from 'appilot-server';
+
+// resolveUser is the security boundary. Derive the user from a credential you
+// trust (your session cookie, your own JWT). Never from the request body.
+export const POST = createWidgetTokenHandler({
+  apiUrl: process.env.APPILOT_API_URL!,
+  widgetKey: process.env.APPILOT_WIDGET_KEY!,
+  widgetSecret: process.env.APPILOT_WIDGET_SECRET!,   // server-side only
+  resolveUser: async request => {
+    const session = await getSession(request);        // your auth, unchanged
+    if (!session) return null;                        // 401 IDENTITY_REQUIRED
+    return {
+      externalId: \`${namespace}:\${session.userId}\`,
+      displayName: session.name,
+    };
+  },
+});
+`;
+}
+function relayNodeHandler(namespace, framework) {
+    const mount = framework === 'express'
+        ? `app.post('/api/widget/token', relay);`
+        : `fastify.post('/api/widget/token', (request, reply) => relay(request.raw, reply.raw));`;
+    return `import { createNodeWidgetTokenHandler } from 'appilot-server/node';
+
+// resolveUser is the security boundary. Derive the user from a credential you
+// trust (req.session, req.user). Never from the request body.
+const relay = createNodeWidgetTokenHandler({
+  apiUrl: process.env.APPILOT_API_URL,
+  widgetKey: process.env.APPILOT_WIDGET_KEY,
+  widgetSecret: process.env.APPILOT_WIDGET_SECRET,   // server-side only
+  resolveUser: req => {
+    const user = req.session?.user;                  // your auth, unchanged
+    if (!user) return null;                          // 401 IDENTITY_REQUIRED
+    return { externalId: \`${namespace}:\${user.id}\`, displayName: user.name };
+  },
+});
+
+${mount}
+`;
+}
+function bootFile(options) {
+    const lines = [
+        "import { bootAppilotWidget } from 'appilot';",
+        '',
+        '// Call once, after your app knows the user is signed in. The widget',
+        '// requires an identified user; the relay below mints that identity.',
+        'export function startAppilot() {',
+        '  bootAppilotWidget({',
+        `    widgetScriptUrl: '${options.widgetScriptUrl}',`,
+    ];
+    if (options.widgetKey)
+        lines.push(`    widgetKey: '${options.widgetKey}',`);
+    if (options.apiUrl)
+        lines.push(`    appilotApiUrl: '${options.apiUrl}',`);
+    lines.push("    tokenEndpoint: '/api/widget/token',", '  });', '}');
+    return lines.join('\n') + '\n';
+}
+const CLIENT_ACTION_EXAMPLE = `import { registerTool } from 'appilot';
+
+// A client action is an operation your PAGE performs, in the user's own
+// session. Use it for anything UI-coupled or session-bound: navigate the SPA,
+// open a modal, or a mutation your page already knows how to do safely.
+// Backend operations belong in an HTTP-proxy tool instead.
+export function registerBookingActions(navigate: (path: string) => void) {
+  const handle = registerTool({
+    name: 'open_booking',
+    description: 'Open a booking by id so the user can see it.',
+    inputSchema: {
+      type: 'object',
+      properties: { booking_id: { type: 'string' } },
+      required: ['booking_id'],
+    },
+    annotations: { readOnlyHint: true },   // absent or false means mutating,
+                                           // and the agent confirms first
+    async execute({ booking_id }) {
+      navigate(\`/bookings/\${booking_id}\`);
+      return { content: [{ type: 'text', text: \`Opened booking \${booking_id}.\` }] };
+    },
+  });
+
+  return () => handle.unregister();        // unregister on route change
+}
+`;
+export function scaffoldIntegration(options) {
+    const namespace = options.idNamespace ?? 'app';
+    const files = [];
+    switch (options.framework) {
+        case 'next':
+            files.push({
+                path: 'app/api/widget/token/route.ts',
+                language: 'typescript',
+                contents: relayFetchHandler(namespace),
+            });
+            break;
+        case 'remix':
+            files.push({
+                path: 'app/routes/api.widget.token.ts',
+                language: 'typescript',
+                contents: `import { createWidgetTokenHandler } from 'appilot-server';
+
+const handler = createWidgetTokenHandler({
+  apiUrl: process.env.APPILOT_API_URL!,
+  widgetKey: process.env.APPILOT_WIDGET_KEY!,
+  widgetSecret: process.env.APPILOT_WIDGET_SECRET!,
+  resolveUser: async request => {
+    const session = await getSession(request.headers.get('Cookie'));
+    const userId = session.get('userId');
+    return userId ? { externalId: \`${namespace}:\${userId}\` } : null;
+  },
+});
+
+export const action = ({ request }: { request: Request }) => handler(request);
+`,
+            });
+            break;
+        case 'sveltekit':
+            files.push({
+                path: 'src/routes/api/widget/token/+server.ts',
+                language: 'typescript',
+                contents: `import { createWidgetTokenHandler } from 'appilot-server';
+import { env } from '$env/dynamic/private';
+
+const handler = createWidgetTokenHandler({
+  apiUrl: env.APPILOT_API_URL,
+  widgetKey: env.APPILOT_WIDGET_KEY,
+  widgetSecret: env.APPILOT_WIDGET_SECRET,
+  resolveUser: async request => {
+    const user = await getUserFromCookies(request.headers.get('cookie'));
+    return user ? { externalId: \`${namespace}:\${user.id}\`, displayName: user.name } : null;
+  },
+});
+
+export const POST = ({ request }) => handler(request);
+`,
+            });
+            break;
+        case 'hono':
+            files.push({
+                path: 'src/routes/widgetToken.ts',
+                language: 'typescript',
+                contents: `import { Hono } from 'hono';
+import { createWidgetTokenHandler } from 'appilot-server';
+
+const handler = createWidgetTokenHandler({
+  apiUrl: process.env.APPILOT_API_URL!,
+  widgetKey: process.env.APPILOT_WIDGET_KEY!,
+  widgetSecret: process.env.APPILOT_WIDGET_SECRET!,
+  resolveUser: async request => {
+    const user = await getUser(request);
+    return user ? { externalId: \`${namespace}:\${user.id}\` } : null;
+  },
+});
+
+export const widgetToken = new Hono().post('/api/widget/token', c => handler(c.req.raw));
+`,
+            });
+            break;
+        case 'express':
+        case 'fastify':
+            files.push({
+                path: 'src/routes/widgetToken.ts',
+                language: 'typescript',
+                contents: relayNodeHandler(namespace, options.framework),
+            });
+            break;
+    }
+    files.push({ path: 'src/appilot/boot.ts', language: 'typescript', contents: bootFile(options) });
+    files.push({
+        path: 'src/appilot/actions.ts',
+        language: 'typescript',
+        contents: CLIENT_ACTION_EXAMPLE,
+    });
+    return {
+        framework: options.framework,
+        files,
+        install: 'npm install appilot appilot-server',
+        env: [
+            `APPILOT_API_URL=${options.apiUrl ?? 'https://api.appilot.space'}`,
+            `APPILOT_WIDGET_KEY=${options.widgetKey ?? 'wk_live_...'}`,
+            'APPILOT_WIDGET_SECRET=wsk_secret_...   # server-side only, never in a client bundle',
+        ].join('\n'),
+        notes: [
+            'The widget secret must never appear in a client bundle or a public env var. In Next.js that means no NEXT_PUBLIC_ prefix; in Vite, keep it out of VITE_.',
+            'resolveUser is the security boundary: derive the user from a credential you trust, never from the request body.',
+            'Call verify_integration once this is wired to confirm the relay answers and the widget actually boots.',
+        ],
+    };
+}