@segmentstream-cloud/app 0.8.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";

package/dist/index.js

@@ -19,4 +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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@segmentstream-cloud/app",
-  "version": "0.8.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",