@segmentstream-cloud/app 0.7.0 → 0.9.0

package/dist/app.d.ts

@@ -1,6 +1,7 @@
 import type { Environment, SegmentStreamAppConfig } from "./config.js";
 import type { WarehouseClient } from "./data.js";
 import type { SegmentStreamRouteHandlers } from "./handlers.js";
+import type { AgentAuthorizations } from "./oauth.js";
 import type { AuthRouteHandlers, CreateNeonAuth, SignOutOptions } from "./neon.js";
 import type { OntologyClient } from "./ontology.js";
 import type { ProxyOptions, SegmentStreamProxy } from "./proxy.js";
@@ -46,6 +47,11 @@ export interface SegmentStreamApp<O = unknown> {
     readonly warehouse: WarehouseClient;
     /** The app's ontology service, `/api/ontology`, as the signed-in user. Server-only. */
     readonly ontology: OntologyClient<O>;
+    /**
+     * Agents connecting to the app's MCP server: the request the consent page shows the signed-in
+     * member, and the Route Handler that carries out their decision. Server-only.
+     */
+    readonly oauth: AgentAuthorizations;
 }
 /** Replaceable capabilities, for tests. */
 export interface AppDependencies {

package/dist/app.js

@@ -5,6 +5,7 @@ import { createDataClient } from "./data.js";
 import { SegmentStreamApiError } from "./errors.js";
 import { createHandlers } from "./handlers.js";
 import { createNeonSession } from "./neon.js";
+import { createAgentAuthorizations, withUnframeableConsent } from "./oauth.js";
 import { createOntologyClient } from "./ontology.js";
 import { createOntologyTransport } from "./ontology-transport.js";
 import { createProxy } from "./proxy.js";
@@ -35,9 +36,15 @@ export function createApp(config, dependencies = {}) {
             getAppCredential,
         });
         const ontologyUrl = environmentValue(environment, "SEGMENTSTREAM_ONTOLOGY_URL");
+        // The ontology service accepts SegmentStream app tokens while workspaces move to Neon Auth.
+        const ontologyTransport = createOntologyTransport({
+            fetch: fetchImplementation,
+            ontologyUrl: ontologyUrl === undefined ? undefined : new URL(ontologyUrl).origin,
+            credentials: { token: legacy.getAccessToken },
+        });
         return {
             authentication: "segmentstream",
-            proxy: (options) => createProxy(context, options),
+            proxy: (options) => withUnframeableConsent(createProxy(context, options)),
             authHandlers: notConfiguredHandlers,
             handlers: () => createHandlers(context),
             getUser: legacy.getUser,
@@ -48,12 +55,8 @@ export function createApp(config, dependencies = {}) {
             getAccessToken: legacy.getAccessToken,
             fetch: data.fetch,
             warehouse: data.warehouse,
-            // The ontology service accepts SegmentStream app tokens while workspaces move to Neon Auth.
-            ontology: createOntologyClient(createOntologyTransport({
-                fetch: fetchImplementation,
-                ontologyUrl: ontologyUrl === undefined ? undefined : new URL(ontologyUrl).origin,
-                credentials: { token: legacy.getAccessToken },
-            }), data.aggregateTransport),
+            ontology: createOntologyClient(ontologyTransport, data.aggregateTransport),
+            oauth: createAgentAuthorizations(ontologyTransport),
         };
     }
     const neon = createNeonSession({
@@ -71,7 +74,7 @@ export function createApp(config, dependencies = {}) {
     });
     return {
         authentication: "neon-auth",
-        proxy: neon.proxy,
+        proxy: (options) => withUnframeableConsent(neon.proxy(options)),
         authHandlers: neon.authHandlers,
         handlers: () => createHandlers(context),
         getUser: neon.getUser,
@@ -82,6 +85,7 @@ export function createApp(config, dependencies = {}) {
         fetch: data.fetch,
         warehouse: data.warehouse,
         ontology: createOntologyClient(neon.ontologyTransport, data.aggregateTransport),
+        oauth: createAgentAuthorizations(neon.ontologyTransport),
     };
 }
 /** Under Neon Auth the app has no SegmentStream session to call the API with. */

package/dist/index.d.ts

@@ -19,6 +19,8 @@ export { NOT_INVITED, SIGN_IN_LINK_INVALID, SegmentStreamApiError } from "./erro
 export { grants, isAllowed } from "./permissions.js";
 export { sql } from "./parameters.js";
 export type { AuthenticationMethod, SegmentStreamApp } from "./app.js";
+export { CONSENT_PAGE } from "./oauth.js";
+export type { AgentAuthorizationRequest, AgentAuthorizations, AgentScope } from "./oauth.js";
 export type { ApiIssue } from "./errors.js";
 export type { CurrentUser } from "./me.js";
 export type { AuthRouteHandler, AuthRouteHandlers, SignOutOptions } from "./neon.js";
@@ -30,3 +32,4 @@ export type { SegmentStreamAppConfig } from "./config.js";
 export type { SegmentStreamRouteHandlers, RouteHandler } from "./handlers.js";
 export type { ProxyOptions, SegmentStreamProxy } from "./proxy.js";
 export type { AppUser } from "./tokens.js";
+export { createBlobStorageClient, type BlobUploadTicket, type FileRevision, type FileTransfer, type FileUploadTarget, type UploadSession, type FileUploadOptions, } from "./storage.js";

package/dist/index.js

@@ -19,3 +19,5 @@ export function createSegmentStreamApp(config) {
 export { NOT_INVITED, SIGN_IN_LINK_INVALID, SegmentStreamApiError } from "./errors.js";
 export { grants, isAllowed } from "./permissions.js";
 export { sql } from "./parameters.js";
+export { CONSENT_PAGE } from "./oauth.js";
+export { createBlobStorageClient, } from "./storage.js";

package/dist/neon.js

@@ -14,6 +14,13 @@ import { isApiRequest, unauthenticatedResponse } from "./sign-in.js";
 export const SIGN_IN_PAGE = "/sign-in";
 /** Where `app/src/app/api/auth/[...path]/route.ts` serves the Neon Auth API. */
 export const AUTH_API_PATH = "/api/auth";
+/** The paths the ontology service answers: its HTTP API, its MCP server and its OAuth metadata. */
+const ONTOLOGY_PATHS = [
+    "/api/ontology",
+    "/mcp",
+    "/.well-known/oauth-protected-resource",
+    "/.well-known/oauth-authorization-server",
+];
 /**
  * Paths every visitor may open: the Neon Auth API, the sign-in page, the health check, and the
  * Next.js assets and metadata files the sign-in page needs.
@@ -303,8 +310,9 @@ export function createNeonSession(dependencies) {
         const publicPaths = [...OPEN_PATHS, ...(options.publicPaths ?? [])].map(normalizePublicPath);
         return async function neonProxy(request) {
             const { pathname, search } = request.nextUrl;
-            if (settings.ontologyUrl !== undefined && matchesPathPrefix(pathname, "/api/ontology")) {
-                // Local development: the service runs elsewhere; deployed, /api/ontology never reaches the app.
+            if (settings.ontologyUrl !== undefined &&
+                ONTOLOGY_PATHS.some((path) => matchesPathPrefix(pathname, path))) {
+                // Local development: the service runs elsewhere; deployed, its paths never reach the app.
                 return NextResponse.rewrite(new URL(`${pathname}${search}`, settings.ontologyUrl));
             }
             if (publicPaths.some((path) => matchesPathPrefix(pathname, path))) {

package/dist/oauth.d.ts

@@ -0,0 +1,44 @@
+import type { OntologyTransport } from "./ontology.js";
+import { type SegmentStreamProxy } from "./proxy.js";
+/** The app's page where a signed-in member decides whether an agent may act for them. */
+export declare const CONSENT_PAGE = "/oauth/consent";
+/**
+ * The proxy, with the consent page unframeable: no other site may show it in a frame and trick a
+ * member into clicking Allow. Every app gets this from the SDK, whatever its Next.js config says.
+ */
+export declare function withUnframeableConsent(proxy: SegmentStreamProxy): SegmentStreamProxy;
+/** Everything the member may do, or only the reads of it. */
+export type AgentScope = "ontology" | "ontology:read";
+/** An agent asking to act for the signed-in member, as the consent page shows it. */
+export interface AgentAuthorizationRequest {
+    readonly id: string;
+    readonly client: {
+        /** The name the agent registered with. Agents choose it themselves, so show the host too. */
+        readonly name: string;
+        readonly uri: string | null;
+        /** Where the member's browser goes after the decision: the agent's own address. */
+        readonly redirectUri: string;
+        readonly redirectHost: string;
+    };
+    readonly scope: AgentScope;
+    /** What the member may do, and so the most the agent may do for them. */
+    readonly permissions: ReadonlyArray<string>;
+    readonly expiresAt: string;
+}
+export interface AgentAuthorizations {
+    /**
+     * The request the consent page at `/oauth/consent?request=<id>` shows, for the signed-in member;
+     * `null` when it expired or was already decided. Server-only.
+     */
+    readonly request: (id: string) => Promise<AgentAuthorizationRequest | null>;
+    /**
+     * The Route Handler the consent page's form posts to, at `app/src/app/api/oauth/consent/route.ts`.
+     * It takes `request`, `decision` (`approve` or `deny`) and, to allow reading only, `scope`
+     * (`ontology:read`), and sends the browser back to the agent.
+     */
+    readonly consentHandler: () => {
+        readonly POST: (request: Request) => Promise<Response>;
+    };
+}
+/** The consent flow, over the ontology service as the signed-in member. */
+export declare function createAgentAuthorizations(transport: OntologyTransport): AgentAuthorizations;

package/dist/oauth.js

@@ -0,0 +1,112 @@
+import { NextResponse } from "next/server";
+import { apiErrorFrom, readJson } from "./errors.js";
+import { matchesPathPrefix } from "./proxy.js";
+/** The app's page where a signed-in member decides whether an agent may act for them. */
+export const CONSENT_PAGE = "/oauth/consent";
+/**
+ * The proxy, with the consent page unframeable: no other site may show it in a frame and trick a
+ * member into clicking Allow. Every app gets this from the SDK, whatever its Next.js config says.
+ */
+export function withUnframeableConsent(proxy) {
+    return async (request) => {
+        const response = await proxy(request);
+        if (matchesPathPrefix(request.nextUrl.pathname, CONSENT_PAGE)) {
+            response.headers.set("x-frame-options", "DENY");
+            response.headers.set("content-security-policy", "frame-ancestors 'none'");
+        }
+        return response;
+    };
+}
+function parseRequest(payload) {
+    if (typeof payload !== "object" || payload === null) {
+        return null;
+    }
+    const body = payload;
+    const client = (body.client ?? {});
+    if (typeof body.id !== "string" ||
+        typeof client.name !== "string" ||
+        typeof client.redirect_uri !== "string" ||
+        typeof client.redirect_host !== "string" ||
+        (body.scope !== "ontology" && body.scope !== "ontology:read") ||
+        !Array.isArray(body.permissions) ||
+        typeof body.expires_at !== "string") {
+        return null;
+    }
+    return {
+        id: body.id,
+        client: {
+            name: client.name,
+            uri: typeof client.uri === "string" ? client.uri : null,
+            redirectUri: client.redirect_uri,
+            redirectHost: client.redirect_host,
+        },
+        scope: body.scope,
+        permissions: body.permissions.filter((permission) => typeof permission === "string"),
+        expiresAt: body.expires_at,
+    };
+}
+/**
+ * Whether a form post came from the app's own pages. A decision must never be made from another
+ * site, which could otherwise approve an agent in the member's name.
+ */
+function sameOrigin(request) {
+    const origin = request.headers.get("origin");
+    if (origin !== null) {
+        return origin === new URL(request.url).origin;
+    }
+    return request.headers.get("sec-fetch-site") === "same-origin";
+}
+function requestPath(id, decision) {
+    const path = `/oauth/requests/${encodeURIComponent(id)}`;
+    return decision === undefined ? path : `${path}/${decision}`;
+}
+/** The consent flow, over the ontology service as the signed-in member. */
+export function createAgentAuthorizations(transport) {
+    return {
+        async request(id) {
+            if (id === "") {
+                return null;
+            }
+            const response = await transport.fetch(requestPath(id), {
+                method: "GET",
+                headers: { accept: "application/json" },
+            });
+            const payload = await readJson(response);
+            if (response.status === 404) {
+                return null;
+            }
+            if (!response.ok) {
+                throw apiErrorFrom(response.status, payload, "The ontology service refused the request.");
+            }
+            return parseRequest(payload);
+        },
+        consentHandler: () => ({
+            async POST(request) {
+                if (!sameOrigin(request)) {
+                    return NextResponse.json({ error: "forbidden", detail: "Decide on an agent from the app's own page." }, { status: 403 });
+                }
+                const form = await request.formData();
+                const id = String(form.get("request") ?? "");
+                const decision = form.get("decision") === "approve" ? "approve" : "deny";
+                const response = await transport.fetch(requestPath(id, decision), {
+                    method: "POST",
+                    headers: { "content-type": "application/json", accept: "application/json" },
+                    body: JSON.stringify(form.get("scope") === "ontology:read" ? { scope: "ontology:read" } : {}),
+                });
+                const payload = await readJson(response);
+                if (response.status === 404) {
+                    return NextResponse.redirect(new URL(`${CONSENT_PAGE}?expired=1`, request.url), 303);
+                }
+                if (!response.ok) {
+                    throw apiErrorFrom(response.status, payload, "The ontology service refused the decision.");
+                }
+                const redirect = payload?.redirect;
+                if (typeof redirect !== "string" || !URL.canParse(redirect)) {
+                    throw apiErrorFrom(502, payload, "The ontology service answered without a redirect.");
+                }
+                // 303: the agent's redirect URI receives a GET, whatever method brought the browser here.
+                return NextResponse.redirect(redirect, 303);
+            },
+        }),
+    };
+}

package/dist/ontology-wire.js

@@ -233,11 +233,13 @@ export function actionInputToWire(input, entity, action, catalog) {
         const property = definition?.properties.find((candidate) => candidate.name === wireField);
         return [
             wireField,
-            (action === "link" || action === "unlink") &&
-                field === "relationship" &&
-                typeof child === "string"
-                ? toSnakeCase(child)
-                : selectToWire(child, property),
+            property?.type === "blob" && isRecord(child)
+                ? Object.fromEntries(Object.entries(child).map(([key, value]) => [toSnakeCase(key), value]))
+                : (action === "link" || action === "unlink") &&
+                    field === "relationship" &&
+                    typeof child === "string"
+                    ? toSnakeCase(child)
+                    : selectToWire(child, property),
         ];
     }));
 }

package/dist/ontology.d.ts

@@ -121,6 +121,8 @@ export interface RequestOptions {
 export interface ActionOptions extends RequestOptions {
     /** Validate the input and report issues in `validation` without a write. */
     readonly validateOnly?: boolean;
+    readonly idempotencyKey?: string;
+    readonly createIntent?: string;
 }
 export interface HistoryOptions extends RequestOptions {
     readonly after?: string;

package/dist/ontology.js

@@ -89,9 +89,21 @@ function entityClient(entity, transport, getCatalog) {
         const catalog = await getCatalog();
         const wireResponse = await send(transport, "POST", `${base}/actions/${encodeURIComponent(action)}`, {
             input: actionInputToWire(input, entity, action, catalog),
-            ...(options.validateOnly === undefined
+            ...([options.validateOnly, options.idempotencyKey, options.createIntent].every((value) => value === undefined)
                 ? {}
-                : { options: { validate_only: options.validateOnly } }),
+                : {
+                    options: {
+                        ...(options.validateOnly === undefined
+                            ? {}
+                            : { validate_only: options.validateOnly }),
+                        ...(options.idempotencyKey === undefined
+                            ? {}
+                            : { idempotency_key: options.idempotencyKey }),
+                        ...(options.createIntent === undefined
+                            ? {}
+                            : { create_intent: options.createIntent }),
+                    },
+                }),
         }, options.signal);
         const response = { ...wireResponse, edits: editsFromWire(wireResponse.edits, catalog) };
         if (action === "create" || action === "update") {

package/dist/storage.d.ts

@@ -0,0 +1,54 @@
+import type { OntologyTransport } from "./ontology.js";
+export interface BlobUploadTicket {
+    readonly uploadId: string;
+}
+export interface FileRevision {
+    readonly id: string;
+    readonly filename: string;
+    readonly contentType: string;
+    readonly size: number;
+    readonly createdAt: string;
+}
+export interface FileTransfer {
+    readonly url: string;
+    readonly method: "GET" | "PUT";
+    readonly headers: Readonly<Record<string, string>>;
+    readonly expiresAt: string;
+}
+export interface FileUploadTarget {
+    readonly entity: string;
+    readonly property: string;
+    readonly action: string;
+    readonly recordId?: string;
+    readonly createIntent?: string;
+}
+export interface UploadSession {
+    readonly id: string;
+    readonly state: string;
+    readonly expiresAt: string;
+    readonly ticket?: BlobUploadTicket;
+}
+export interface FileUploadOptions {
+    readonly signal?: AbortSignal;
+    /** Reuse this UUID when retrying an upload and its entity action. */
+    readonly idempotencyKey?: string;
+    /** Reports transfer start and completion; supply a transfer adapter for granular progress. */
+    readonly onProgress?: (transferred: number, total: number) => void;
+}
+/** Portable client: ontology requests use the member transport; bytes use only a scoped grant. */
+export declare function createBlobStorageClient(transport: OntologyTransport, transfer?: typeof fetch): {
+    status: (id: string, signal?: AbortSignal) => Promise<UploadSession>;
+    cancel: (id: string) => Promise<UploadSession>;
+    uploadForAction(target: FileUploadTarget, file: File, options?: FileUploadOptions): Promise<{
+        ticket: BlobUploadTicket;
+        options: {
+            createIntent?: string | undefined;
+            idempotencyKey: string;
+        };
+    }>;
+    download(entity: string, recordId: string, property: string, options?: {
+        readonly revisionId?: string;
+        readonly inline?: boolean;
+        readonly signal?: AbortSignal;
+    }): Promise<FileTransfer>;
+};

package/dist/storage.js

@@ -0,0 +1,116 @@
+import { apiErrorFrom, readJson } from "./errors.js";
+import { toSnakeCase } from "./ontology-names.js";
+/** Portable client: ontology requests use the member transport; bytes use only a scoped grant. */
+export function createBlobStorageClient(transport, transfer = globalThis.fetch) {
+    const send = async (path, method, body, signal) => {
+        const response = await transport.fetch(path, {
+            method,
+            ...(body === undefined
+                ? {}
+                : { headers: { "content-type": "application/json" }, body: JSON.stringify(body) }),
+            ...(signal ? { signal } : {}),
+        });
+        const data = await readJson(response);
+        if (!response.ok) {
+            throw apiErrorFrom(response.status, data, "The ontology service rejected the file request.");
+        }
+        return data;
+    };
+    const sessionPath = (id) => `/uploads/${encodeURIComponent(id)}`;
+    const readSession = async (path, method, body, signal) => {
+        const { expires_at, ticket, ...session } = await send(path, method, body, signal);
+        return {
+            ...session,
+            expiresAt: expires_at,
+            ...(ticket ? { ticket: { uploadId: ticket.upload_id } } : {}),
+        };
+    };
+    const readTransfer = async (path, body, signal) => {
+        const { expires_at, ...grant } = await send(path, "POST", body, signal);
+        return { ...grant, expiresAt: expires_at };
+    };
+    const cancel = (id) => readSession(`${sessionPath(id)}/cancel`, "POST");
+    return {
+        status: (id, signal) => readSession(sessionPath(id), "GET", undefined, signal),
+        cancel,
+        async uploadForAction(target, file, options = {}) {
+            const idempotencyKey = options.idempotencyKey ?? crypto.randomUUID();
+            const createIntent = target.recordId ? undefined : (target.createIntent ?? idempotencyKey);
+            const session = await readSession("/uploads", "POST", {
+                entity: toSnakeCase(target.entity),
+                property: toSnakeCase(target.property),
+                action: toSnakeCase(target.action),
+                ...(target.recordId ? { record_id: target.recordId } : {}),
+                ...(createIntent ? { create_intent: createIntent } : {}),
+                idempotency_key: idempotencyKey,
+                filename: file.name,
+                content_type: file.type,
+                size: file.size,
+            }, options.signal);
+            if (session.ticket) {
+                return {
+                    ticket: session.ticket,
+                    options: { idempotencyKey, ...(createIntent ? { createIntent } : {}) },
+                };
+            }
+            let completionStarted = false;
+            let transferRejected = false;
+            try {
+                if (session.state !== "completing") {
+                    const grant = await readTransfer(`${sessionPath(session.id)}/parts`, undefined, options.signal);
+                    options.onProgress?.(0, file.size);
+                    const response = await transfer(grant.url, {
+                        method: grant.method,
+                        headers: grant.headers,
+                        body: file,
+                        signal: options.signal,
+                        credentials: "omit",
+                        referrerPolicy: "no-referrer",
+                    });
+                    if (!response.ok) {
+                        transferRejected = true;
+                        throw new Error(`File transfer failed (${response.status}).`);
+                    }
+                    options.onProgress?.(file.size, file.size);
+                }
+                completionStarted = true;
+                const completed = await readSession(`${sessionPath(session.id)}/complete`, "POST", undefined, options.signal);
+                if (!completed.ticket) {
+                    throw new Error("The file upload is not ready.");
+                }
+                return {
+                    ticket: completed.ticket,
+                    options: { idempotencyKey, ...(createIntent ? { createIntent } : {}) },
+                };
+            }
+            catch (error) {
+                if (options.signal?.aborted || transferRejected) {
+                    // Deliberate cancellation uses a fresh request even when the signal was aborted.
+                    await cancel(session.id).catch((cause) => {
+                        console.warn("ontology.upload.cancel_failed", { uploadId: session.id, cause });
+                    });
+                }
+                else if (completionStarted) {
+                    // A lost completion response may already have produced a valid ticket.
+                    const recovered = await readSession(sessionPath(session.id), "GET").catch(() => undefined);
+                    if (recovered?.ticket) {
+                        return {
+                            ticket: recovered.ticket,
+                            options: { idempotencyKey, ...(createIntent ? { createIntent } : {}) },
+                        };
+                    }
+                }
+                // Ambiguous network failures retain the session for an explicit retry or scheduled cleanup.
+                throw error;
+            }
+        },
+        download(entity, recordId, property, options = {}) {
+            const { signal } = options;
+            const input = {
+                ...(options.revisionId ? { revision_id: options.revisionId } : {}),
+                ...(options.inline === undefined ? {} : { inline: options.inline }),
+            };
+            return readTransfer(`/${encodeURIComponent(toSnakeCase(entity))}/${encodeURIComponent(recordId)}/blobs/${encodeURIComponent(toSnakeCase(property))}/download`, input, signal);
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@segmentstream-cloud/app",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "Sign-in, users, permissions, the ontology client and warehouse data access for SegmentStream workspace apps built with Next.js.",
   "license": "Apache-2.0",
   "author": "SegmentStream",
@@ -27,7 +27,11 @@
       "types": "./dist/ui/index.d.ts",
       "import": "./dist/ui/index.js"
     },
-    "./ui/styles.css": "./dist/ui/styles.css"
+    "./ui/styles.css": "./dist/ui/styles.css",
+    "./storage": {
+      "types": "./dist/storage.d.ts",
+      "import": "./dist/storage.js"
+    }
   },
   "files": [
     "dist",