@segmentstream-cloud/app 0.2.0 → 0.3.1

package/README.md

@@ -1,9 +1,11 @@
 # @segmentstream-cloud/app
 
-Sign-in, sessions, and warehouse data access for SegmentStream workspace apps built with
-Next.js (App Router, version 16 or later). Every visitor signs in with their SegmentStream
-account, only members of the app's workspace get in, and the app reads workspace data as
-that user without holding any warehouse credentials.
+Sign-in, users, permissions, the ontology client and warehouse data access for
+SegmentStream workspace apps built with Next.js (App Router, version 16 or later) and
+React 19. The app's users sign in with an email code through Neon Auth (Managed
+Better Auth) on the workspace's Neon project; the workspace's ontology decides who may
+use the app and what they may do. The SDK wraps `@neondatabase/auth`, so the app never
+configures Neon Auth itself.
 
 ## Install
 
@@ -11,17 +13,18 @@ that user without holding any warehouse credentials.
 npm install @segmentstream-cloud/app
 ```
 
-## Add three files
+## Set up
 
-**`src/segmentstream.ts`** configures the app once:
+**`src/segmentstream.ts`** configures the app once. Pass the type of the app's
+ontology to type `segmentstream.ontology`; the ontology is imported as a type only:
 
 ```ts
 import { createSegmentStreamApp } from "@segmentstream-cloud/app";
 
-export const segmentstream = createSegmentStreamApp({
-  workspaceId: "your-workspace-id",
-  organizationId: "your-organization-id",
-});
+import type ontology from "../../ontology";
+import link from "../segmentstream.json"; // { "workspaceId": "…", "organizationId": "…" }
+
+export const segmentstream = createSegmentStreamApp<typeof ontology>(link);
 ```
 
 **`src/proxy.ts`** keeps every page and API route signed in:
@@ -30,22 +33,55 @@ export const segmentstream = createSegmentStreamApp({
 import { segmentstream } from "./segmentstream";
 
 export const proxy = segmentstream.proxy({
-  // Optional: paths that anyone may open. `/health` also covers `/health/live`.
-  publicPaths: ["/health"],
+  // Optional: paths anyone may open. `/webhooks` also covers `/webhooks/stripe`.
+  publicPaths: ["/webhooks"],
 });
 
 export const config = {
-  matcher: ["/((?!_next/static|_next/image|favicon.ico|robots.txt).*)"],
+  matcher: ["/((?!_next/static|_next/image|favicon.ico).*)"],
 };
 ```
 
-**`src/app/api/segmentstream/[...path]/route.ts`** handles the sign-in callback and
-sign-out:
+Static assets, `/api/auth`, `/sign-in` and `/api/health` are always open.
+
+**`src/app/api/auth/[...path]/route.ts`** serves the Neon Auth API that sign-in and
+sessions use:
 
 ```ts
-import { segmentstream } from "../../../../segmentstream";
+import { segmentstream } from "@/segmentstream";
+
+export const { GET, POST, PUT, DELETE, PATCH } = segmentstream.authHandlers();
+```
+
+The route completes emailed sign-in links (`/api/auth/magic-link/verify`) itself: it
+verifies the token through Neon Auth without a callback, sets the session cookies on
+the app's domain and redirects to the link's `callbackURL` path. An expired, used or
+unknown link redirects to `/sign-in?error=sign_in_link_invalid`, where `<SignIn />`
+offers a new code.
+
+**`src/app/sign-in/page.tsx`** renders the sign-in form, and the root layout imports
+its stylesheet once:
+
+```tsx
+import { SignIn } from "@segmentstream-cloud/app/ui";
+
+type SearchParams = Promise<Record<string, string | string[] | undefined>>;
+
+export default async function SignInPage({ searchParams }: { searchParams: SearchParams }) {
+  const { returnTo, error } = await searchParams;
 
-export const { GET, POST } = segmentstream.handlers();
+  return (
+    <SignIn
+      returnTo={typeof returnTo === "string" ? returnTo : undefined}
+      error={typeof error === "string" ? error : undefined}
+    />
+  );
+}
+```
+
+```tsx
+// src/app/layout.tsx
+import "@segmentstream-cloud/app/ui/styles.css";
 ```
 
 ## Read the signed-in user
@@ -56,28 +92,92 @@ import { segmentstream } from "@/segmentstream";
 export default async function Page() {
   const user = await segmentstream.requireUser();
 
-  return <p>Signed in as {user.email ?? user.id}</p>;
+  return (
+    <p>
+      {user.name ?? user.email}: {user.roles.join(", ")}
+    </p>
+  );
 }
 ```
 
-- `getUser()` returns `{ id, email?, name?, organizationId, workspaceId }` or `null`.
-- `requireUser()` returns the user, or redirects to `/api/segmentstream/sign-in` when
-  there is none. Next.js `unauthorized()` needs the experimental `authInterrupts` flag,
-  so the SDK restarts sign-in instead. The proxy normally signs users in first, so this
-  only happens on paths the proxy matcher excludes.
-- `getAccessToken()` returns the verified app session token for calls to SegmentStream.
-
-Use them in Server Components, Route Handlers, and Server Functions. Always check the
+- `requireUser()` returns `{ id, email?, name?, roles, permissions, kind?, active?,
+authUserId?, organizationId, workspaceId }`. `id` is the person's ontology `user`
+  record. Roles and permissions come from the ontology's `GET /api/ontology/me`,
+  cached per session for a minute. Signed out, it redirects to `/sign-in`. For a
+  person the app has not invited (`403 not_invited`), it redirects to
+  `/sign-in?error=not_invited`, where `<SignIn />` asks them to request an invitation
+  or use another email.
+- `getUser()` returns the same, or `null` when signed out; it throws
+  `SegmentStreamApiError` with `code: "not_invited"` for people without an invitation.
+- `can("lead:changeStatus")` is `true` when the user's permissions cover the
+  permission. Roles may hold wildcards: `lead:*`, `*:read`, `*:*`. `isAllowed` and
+  `grants` apply the same rule to any list of permissions.
+- `signOut()` ends the session, clears its cookies and redirects to `/sign-in` (or
+  `{ redirectTo }`). Call it from a Server Function or Route Handler.
+
+Use them in Server Components, Route Handlers and Server Functions. Always check the
 user in Server Functions and Route Handlers too; do not rely on the proxy alone.
 
-To sign out, post a form to the SDK route:
+## Client components
+
+`@segmentstream-cloud/app/ui` holds React client components with plain, neutral CSS
+(no Tailwind). Every class starts with `ss-`; the `--ss-*` custom properties on
+`:root` set colours, radius and font.
+
+| Export                                 | Does                                                                               |
+| -------------------------------------- | ---------------------------------------------------------------------------------- |
+| `<SignIn />`                           | Email, then the six-digit code; resend after 30 seconds, errors and loading states |
+| `<SignedIn>`, `<SignedOut>`            | Render children by session state                                                   |
+| `<Can permission="lead:changeStatus">` | Renders children when the user holds the permission; `fallback` otherwise          |
+| `<UserMenu />`                         | Name, email, roles and sign-out                                                    |
+| `useUser()`                            | `{ status, user, error }` from `/api/ontology/me`, loaded once per session         |
+| `usePermissions()`                     | `{ isLoading, roles, permissions, can(permission) }`                               |
+| `useSession()`, `signOut()`            | The Neon Auth session in the browser; sign-out from the browser                    |
+
+`<Can>` only hides controls: the ontology service checks every read and action. A
+Server Component may wrap server-rendered children in `<Can>`:
 
 ```tsx
-<form action="/api/segmentstream/sign-out" method="post">
-  <button type="submit">Sign out</button>
-</form>
+<Can permission="lead:changeStatus" fallback={lead.status}>
+  <ChangeStatusForm lead={lead.id} />
+</Can>
 ```
 
+## The ontology
+
+`segmentstream.ontology.<entity>` calls the app's ontology service at `/api/ontology`
+with the signed-in user's Neon Auth JWT, so the service applies their permissions.
+Records, action inputs and action results are typed from the ontology:
+
+```ts
+const { items, nextCursor } = await segmentstream.ontology.lead.find({
+  where: { status: { in: ["new", "contacted"] } },
+  orderBy: [{ field: "createdAt", direction: "desc" }],
+  include: { owner: true },
+  limit: 20,
+});
+const lead = await segmentstream.ontology.lead.get(id);
+const history = await segmentstream.ontology.lead.history(id, { limit: 50 });
+const page = await segmentstream.ontology.lead.query({ where: { email: { startsWith: "ada" } } });
+
+const input = { lead: id, status: "contacted" } as const;
+const check = await segmentstream.ontology.lead.actions.changeStatus(input, { validateOnly: true });
+const { result, validation, edits } = await segmentstream.ontology.lead.actions.changeStatus(input);
+```
+
+- `find` sends the query as URL parameters, `query` as a JSON body; both return
+  `{ items, nextCursor }`. Pass `nextCursor` as `after` for the next page.
+- `actions.<name>(input, { validateOnly })` posts `{ input, options }` and returns
+  `{ result, validation, edits }`. Generated actions are there too
+  (`actions.create`, `update`, `delete`), and `action(name, input)` runs any action by
+  name, such as `upsertByEmail`.
+- Failures throw `SegmentStreamApiError` with the service's `code` (`forbidden`,
+  `not_found`, `invalid_input`, `action_rejected`, `conflict`, `not_invited`), `status`,
+  `detail`, `requestId` and, for invalid input, `issues`.
+- The types are read from the ontology SDK's `Ontology`, entity and action types
+  structurally, so the app needs neither the ontology SDK nor Effect at runtime.
+  Without a type argument, any entity name is accepted and records are untyped.
+
 ## Query the warehouse
 
 ```tsx
@@ -87,6 +187,8 @@ import { segmentstream } from "@/segmentstream";
 type Revenue = { order_date: string; total_revenue: number };
 
 export default async function Page() {
+  await segmentstream.requireUser();
+
   const { rows } = await segmentstream.warehouse.query<Revenue>(
     `SELECT order_date, total_revenue
      FROM gold.revenue_summary
@@ -99,6 +201,10 @@ export default async function Page() {
 }
 ```
 
+- Warehouse calls authenticate with the workspace app credential,
+  `SEGMENTSTREAM_APP_CREDENTIAL`, which SegmentStream sets on deploy and the SDK reads
+  on every call. Without it they use the legacy sign-in's session token. The
+  credential belongs to the app, so check the user before querying for them.
 - Queries are read-only GoogleSQL over the workspace warehouse. `dataset.table` resolves
   to the workspace's project. Anything other than a single `SELECT` is rejected.
 - Pass values as named `@parameters` in `params`; never build SQL from user input.
@@ -112,79 +218,84 @@ export default async function Page() {
   estimated bytes and result columns without running the query.
 - Long queries keep running in the warehouse for up to an hour after `query()` stops
   waiting. It then throws `query_timeout` with a `queryId`. Resume the query from a later
-  request, for example a Route Handler your page polls, with
-  `warehouse.result(queryId)`. Each request carries a fresh session token, so a query can
-  outlive the 5-minute token. Don't hold one request open for minutes.
+  request, for example a Route Handler your page polls, with `warehouse.result(queryId)`.
+  Don't hold one request open for minutes.
 - Values arrive as JSON: safe integers as numbers, larger integers and decimals as strings,
   timestamps as ISO strings, records and arrays as JSON strings.
 
-Semantic models give governed metrics without SQL:
-
-```ts
-const { rows } = await segmentstream.semantic.query("advertising", {
-  dimensions: ["platform"],
-  measures: ["spend", "clicks"],
-  dateRange: { from: "2026-09-01", to: "2026-09-30" },
-  filters: [{ dimension: "currency", operator: "equals", value: "USD" }],
-});
-```
-
-`semantic.list()` and `semantic.get(name)` describe the deployed models.
-
-## Call the SegmentStream API
-
-The session token works on the whole SegmentStream API, with the signed-in member's
-organization role and permissions, exactly like their own login. `fetch` adds it to any
-API path:
-
-```ts
-const response = await segmentstream.fetch(
-  `/api/v1/workspaces/${user.workspaceId}/warehouse/datasets`,
-);
-```
-
-`warehouse` and `semantic` are typed helpers over the same API, for the app's own
-workspace. Every call is server-only: use it from Server Components, Route Handlers, and
-Server Functions behind the proxy, and pass results to Client Components as props or
-through your own Route Handlers. Typed helpers throw `SegmentStreamApiError` with the API
-error `code`, `status`, `detail` and, for timeouts, the `queryId`.
+`segmentstream.semantic` (governed metrics from semantic models) and
+`segmentstream.fetch(path)` (any SegmentStream API path) act as the signed-in
+SegmentStream member, so they need the legacy sign-in; under Neon Auth they throw
+`app_credential_missing`.
 
 ## How requests are handled
 
-- Page navigations without a session are redirected to SegmentStream to sign in, then
-  return to the page they started on.
-- API routes, `fetch` calls, non-GET requests, and Next.js data requests receive
+- Page navigations without a session are redirected to `/sign-in?returnTo=<path>` and
+  return to the page after sign-in.
+- API routes, `fetch` calls, non-GET requests and Next.js data requests receive
   `401 {"error":"unauthenticated"}` instead of a redirect.
-- `/api/segmentstream/*` and your `publicPaths` never require a session.
+- Static assets, `/api/auth/*`, `/sign-in`, `/api/health` and your `publicPaths` never
+  require a session.
 
 ## Environment
 
-| Variable            | Purpose                                                              |
-| ------------------- | -------------------------------------------------------------------- |
-| `SEGMENTSTREAM_URL` | SegmentStream origin. Defaults to `https://cloud.segmentstream.com`. |
+| Variable                               | Purpose                                                                         |
+| -------------------------------------- | ------------------------------------------------------------------------------- |
+| `NEON_AUTH_BASE_URL`                   | The workspace's Neon Auth URL. Set: sign in with Neon Auth. Unset: 0.2 sign-in. |
+| `SEGMENTSTREAM_APP_AUTH_COOKIE_SECRET` | 32 or more characters; signs the session cache cookie. Required with Neon Auth. |
+| `SEGMENTSTREAM_APP_CREDENTIAL`         | The workspace app credential for warehouse queries.                             |
+| `SEGMENTSTREAM_ONTOLOGY_URL`           | Optional: the ontology service when it does not run beside the app.             |
+| `SEGMENTSTREAM_URL`                    | SegmentStream origin. Defaults to `https://cloud.segmentstream.com`.            |
+
+SegmentStream sets the first three in the app's environment on deploy.
 
 ## Local development
 
-`next dev` on `http://localhost` works. SegmentStream accepts loopback redirect URIs,
-and the SDK drops the `__Host-` prefix and `Secure` attribute only for `http://localhost`,
-`127.0.0.1`, and `[::1]`, which browsers otherwise reject over plain HTTP.
+Put the deployed `NEON_AUTH_BASE_URL` and a cookie secret in `app/.env.local`;
+Neon Auth trusts `http://localhost:3000`:
+
+```sh
+NEON_AUTH_BASE_URL=https://ep-….neonauth.….aws.neon.tech/ontology/auth
+SEGMENTSTREAM_APP_AUTH_COOKIE_SECRET=<openssl rand -base64 32>
+SEGMENTSTREAM_ONTOLOGY_URL=http://localhost:3100
+```
+
+With `SEGMENTSTREAM_ONTOLOGY_URL`, server-side ontology calls go there and the proxy
+forwards the browser's `/api/ontology/*` requests to it. Point it at a local
+`npm --prefix ontology run dev` or at the deployed app.
 
 ## Security
 
-- The app never sees SegmentStream's identity-provider tokens. It receives a short-lived
-  (5-minute) ES256 session token scoped to this workspace app and a rotating refresh
-  token, both in `HttpOnly`, `SameSite=Lax` cookies (`__Host-` and `Secure` in production).
-- Session tokens are verified against SegmentStream's published keys: issuer, expiry,
-  workspace, organization, and an `app:` audience.
-- The proxy refreshes expired sessions silently. When access is revoked, the next refresh
-  fails and the user is signed out.
-- Sign-in uses the authorization-code flow with PKCE (S256) and a single-use `state`.
-- API calls carry the session token, which SegmentStream accepts as the member: their
-  WorkOS role and permissions, read at sign-in and every refresh, decide what the call may
-  do. App code therefore acts as whoever is visiting, across their organization, so treat
-  deploying app code like any other code your organization runs with member access.
-  Warehouse queries run with the workspace's own identity; the app never holds warehouse
-  credentials.
+- Sessions are Neon Auth's: `HttpOnly`, `Secure`, `SameSite=Lax` cookies on the app's
+  own domain, set through the app's `/api/auth` route. The session cache cookie is
+  signed with `SEGMENTSTREAM_APP_AUTH_COOKIE_SECRET`.
+- Signing in proves an email address and grants nothing. The ontology links the
+  person to an invited member, and their roles decide what they may read and do. The
+  ontology service verifies the user's JWT (EdDSA, 15 minutes) and checks permissions
+  on every request; `can()` and `<Can>` only decide what to show.
+- The session JWT and the app credential stay on the server, except that the browser
+  components fetch the JWT from the app's own `/api/auth/token` to read
+  `/api/ontology/me`.
+- Warehouse queries run with the workspace's own identity; the app never holds
+  warehouse credentials.
+
+## Without Neon Auth
+
+Without `NEON_AUTH_BASE_URL`, 0.3 behaves exactly as 0.2, so existing apps keep
+working: members of the workspace's organization sign in with their SegmentStream
+account through `/api/segmentstream/[...path]/route.ts`
+(`export const { GET, POST } = segmentstream.handlers();`), the proxy redirects to
+SegmentStream, and `fetch`, `warehouse` and `semantic` act as the member. In that mode
+`roles` and `permissions` are empty, `can()` is `false`, `authHandlers()` answers
+`404 neon_auth_not_configured`, and `segmentstream.ontology` sends the member's app
+token, which the ontology service accepts while workspaces move to Neon Auth. Keep the
+legacy route until every deployment of the app has Neon Auth.
+
+## Upgrading from 0.2
+
+Add the auth route, the sign-in page and the stylesheet import; keep the legacy route.
+`AppUser` gained `roles` and `permissions`. Under Neon Auth, people sign in again with
+an email code, and the ontology must have invited them.
 
 ## License
 

package/dist/app.d.ts

@@ -1,33 +1,60 @@
+import type { Environment, SegmentStreamAppConfig } from "./config.js";
 import type { SemanticClient, WarehouseClient } from "./data.js";
-import type { SegmentStreamAppConfig } from "./config.js";
 import type { SegmentStreamRouteHandlers } from "./handlers.js";
+import type { AuthRouteHandlers, CreateNeonAuth, SignOutOptions } from "./neon.js";
+import type { OntologyClient } from "./ontology.js";
 import type { ProxyOptions, SegmentStreamProxy } from "./proxy.js";
 import type { Fetch } from "./sessions.js";
 import type { AppUser, KeySet } from "./tokens.js";
-export interface SegmentStreamApp {
+/** How the app signs its users in: Neon Auth when `NEON_AUTH_BASE_URL` is set, else SegmentStream. */
+export type AuthenticationMethod = "neon-auth" | "segmentstream";
+/**
+ * The app's SegmentStream integration. `O` is the type of the app's ontology,
+ * `typeof import("../../ontology").default`, which types {@link SegmentStreamApp.ontology}.
+ */
+export interface SegmentStreamApp<O = unknown> {
+    /** `neon-auth` when `NEON_AUTH_BASE_URL` is set; `segmentstream` (the 0.2 sign-in) otherwise. */
+    readonly authentication: AuthenticationMethod;
     /** The Next.js Proxy that keeps every non-public request signed in. */
     readonly proxy: (options?: ProxyOptions) => SegmentStreamProxy;
-    /** Route Handlers for `app/api/segmentstream/[...path]/route.ts`. */
+    /** Route Handlers for `app/src/app/api/auth/[...path]/route.ts`: the Neon Auth API. */
+    readonly authHandlers: () => AuthRouteHandlers;
+    /** Route Handlers for `app/api/segmentstream/[...path]/route.ts`: the legacy sign-in. */
     readonly handlers: () => SegmentStreamRouteHandlers;
     /** The signed-in user for this request, or `null`. */
     readonly getUser: () => Promise<AppUser | null>;
     /** The signed-in user; redirects to sign-in when there is none. */
     readonly requireUser: () => Promise<AppUser>;
-    /** The verified app session token for this request, or `null`. */
+    /** Whether the signed-in user's permissions cover `permission`, wildcards included. */
+    readonly can: (permission: string) => Promise<boolean>;
+    /**
+     * Ends the session and redirects to the sign-in page, or to `redirectTo`. Call it from a Server
+     * Function or Route Handler, which may change cookies.
+     */
+    readonly signOut: (options?: SignOutOptions) => Promise<never>;
+    /** The verified legacy app session token for this request, or `null`; always `null` under Neon Auth. */
     readonly getAccessToken: () => Promise<string | null>;
     /**
      * Calls any SegmentStream API path as the signed-in member, with their organization role
-     * and permissions. Server-only; the session token never reaches the browser.
+     * and permissions. Server-only; the session token never reaches the browser. Legacy sign-in only.
      */
     readonly fetch: (path: string, init?: RequestInit) => Promise<Response>;
-    /** Read-only SQL over the workspace warehouse, as the signed-in member. Server-only. */
+    /**
+     * Read-only SQL over the workspace warehouse. Server-only. Uses the workspace app credential
+     * (`SEGMENTSTREAM_APP_CREDENTIAL`) when it is set, else the signed-in member's session.
+     */
     readonly warehouse: WarehouseClient;
-    /** Governed metrics from the workspace's deployed semantic models. Server-only. */
+    /** Governed metrics from the workspace's deployed semantic models. Server-only. Legacy sign-in only. */
     readonly semantic: SemanticClient;
+    /** The app's ontology service, `/api/ontology`, as the signed-in user. Server-only. */
+    readonly ontology: OntologyClient<O>;
 }
 /** Replaceable capabilities, for tests. */
 export interface AppDependencies {
     readonly fetch: Fetch;
     readonly keySet: KeySet;
+    readonly environment: Environment;
+    readonly createNeonAuth: CreateNeonAuth;
+    readonly now: () => number;
 }
-export declare function createApp(config: SegmentStreamAppConfig, dependencies?: Partial<AppDependencies>): SegmentStreamApp;
+export declare function createApp<O = unknown>(config: SegmentStreamAppConfig, dependencies?: Partial<AppDependencies>): SegmentStreamApp<O>;

package/dist/app.js

@@ -1,12 +1,21 @@
-import { resolveConfig } from "./config.js";
+import { createNeonAuth } from "@neondatabase/auth/next/server";
+import { NextResponse } from "next/server";
+import { environmentValue, processEnvironment, resolveConfig, resolveNeonAuth } from "./config.js";
 import { createDataClient } from "./data.js";
+import { SegmentStreamApiError } from "./errors.js";
 import { createHandlers } from "./handlers.js";
+import { createNeonSession } from "./neon.js";
+import { createOntologyClient } from "./ontology.js";
+import { createOntologyTransport } from "./ontology-transport.js";
 import { createProxy } from "./proxy.js";
 import { createServerSession } from "./server.js";
 import { createSessionClient } from "./sessions.js";
 import { createTokenVerifier, remoteKeySet } from "./tokens.js";
+const NEON_AUTH_NOT_CONFIGURED = "This app signs in with SegmentStream: NEON_AUTH_BASE_URL is not set. SegmentStream sets it on deploy once the workspace has Neon Auth.";
 export function createApp(config, dependencies = {}) {
-    const resolved = resolveConfig(config);
+    const environment = dependencies.environment ?? processEnvironment();
+    const resolved = resolveConfig(config, environment);
+    const neonAuth = resolveNeonAuth(environment);
     const keySet = dependencies.keySet ?? remoteKeySet(resolved.baseUrl);
     const fetchImplementation = dependencies.fetch ?? ((input, init) => fetch(input, init));
     const sessionClient = createSessionClient(resolved, fetchImplementation);
@@ -16,20 +25,76 @@ export function createApp(config, dependencies = {}) {
         requestToken: sessionClient.requestToken,
         revokeSession: sessionClient.revoke,
     };
-    const serverSession = createServerSession(context);
+    const legacy = createServerSession(context);
+    const getAppCredential = () => environmentValue(environment, "SEGMENTSTREAM_APP_CREDENTIAL");
+    if (neonAuth === null) {
+        const data = createDataClient({
+            config: resolved,
+            fetch: fetchImplementation,
+            getAccessToken: legacy.getAccessToken,
+            getAppCredential,
+        });
+        const ontologyUrl = environmentValue(environment, "SEGMENTSTREAM_ONTOLOGY_URL");
+        return {
+            authentication: "segmentstream",
+            proxy: (options) => createProxy(context, options),
+            authHandlers: notConfiguredHandlers,
+            handlers: () => createHandlers(context),
+            getUser: legacy.getUser,
+            requireUser: legacy.requireUser,
+            // Ontology permissions come with Neon Auth; the legacy sign-in grants none.
+            can: async () => false,
+            signOut: legacy.signOut,
+            getAccessToken: legacy.getAccessToken,
+            fetch: data.fetch,
+            warehouse: data.warehouse,
+            semantic: data.semantic,
+            // 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 },
+            })),
+        };
+    }
+    const neon = createNeonSession({
+        config: resolved,
+        settings: neonAuth,
+        createNeonAuth: dependencies.createNeonAuth ?? createNeonAuth,
+        fetch: fetchImplementation,
+        now: dependencies.now ?? Date.now,
+    });
     const data = createDataClient({
         config: resolved,
         fetch: fetchImplementation,
-        getAccessToken: serverSession.getAccessToken,
+        getAccessToken: noSegmentStreamSession,
+        getAppCredential,
     });
     return {
-        proxy: (options) => createProxy(context, options),
+        authentication: "neon-auth",
+        proxy: neon.proxy,
+        authHandlers: neon.authHandlers,
         handlers: () => createHandlers(context),
-        getUser: serverSession.getUser,
-        requireUser: serverSession.requireUser,
-        getAccessToken: serverSession.getAccessToken,
+        getUser: neon.getUser,
+        requireUser: neon.requireUser,
+        can: neon.can,
+        signOut: neon.signOut,
+        getAccessToken: async () => null,
         fetch: data.fetch,
         warehouse: data.warehouse,
         semantic: data.semantic,
+        ontology: createOntologyClient(neon.ontologyTransport),
     };
 }
+/** Under Neon Auth the app has no SegmentStream session to call the API with. */
+async function noSegmentStreamSession() {
+    throw new SegmentStreamApiError({
+        code: "app_credential_missing",
+        status: 401,
+        detail: "Apps that sign in with Neon Auth have no SegmentStream session. Warehouse queries use the workspace app credential, SEGMENTSTREAM_APP_CREDENTIAL, which is not set; SegmentStream sets it on deploy. Other SegmentStream API calls are not available to these apps yet.",
+    });
+}
+function notConfiguredHandlers() {
+    const handler = async () => NextResponse.json({ error: "neon_auth_not_configured", detail: NEON_AUTH_NOT_CONFIGURED }, { status: 404, headers: { "cache-control": "no-store" } });
+    return { GET: handler, POST: handler, PUT: handler, DELETE: handler, PATCH: handler };
+}

package/dist/config.d.ts

@@ -13,6 +13,22 @@ export interface ResolvedConfig {
     readonly baseUrl: string;
     readonly issuer: string;
 }
-export declare function resolveConfig(config: SegmentStreamAppConfig): ResolvedConfig;
+/** Environment variables, `process.env` unless a test supplies its own. */
+export type Environment = Readonly<Record<string, string | undefined>>;
+export declare function processEnvironment(): Environment;
+/** Neon Auth for the app's users, configured when `NEON_AUTH_BASE_URL` is set. */
+export interface NeonAuthEnvironment {
+    /** `NEON_AUTH_BASE_URL`: the branch's Auth URL. */
+    readonly baseUrl: string;
+    /** `SEGMENTSTREAM_APP_AUTH_COOKIE_SECRET`: signs the session cache cookie. */
+    readonly cookieSecret: string | undefined;
+    /** `SEGMENTSTREAM_ONTOLOGY_URL`: the ontology service when it is not beside the app. */
+    readonly ontologyUrl: string | undefined;
+}
+export declare function resolveConfig(config: SegmentStreamAppConfig, environment?: Environment): ResolvedConfig;
+/** `null` without `NEON_AUTH_BASE_URL`: the app then signs in with SegmentStream, as in 0.2. */
+export declare function resolveNeonAuth(environment: Environment): NeonAuthEnvironment | null;
 /** Linear-time trailing slash removal; `/\/+$/` backtracks quadratically on slash runs. */
 export declare function trimTrailingSlashes(value: string): string;
+/** A variable's trimmed value; unset and blank are the same. */
+export declare function environmentValue(environment: Environment, name: string): string | undefined;

package/dist/config.js

@@ -1,11 +1,29 @@
 export const DEFAULT_BASE_URL = "https://cloud.segmentstream.com";
-export function resolveConfig(config) {
+export function processEnvironment() {
+    return typeof process === "undefined" ? {} : process.env;
+}
+export function resolveConfig(config, environment = processEnvironment()) {
     const workspaceId = requireIdentifier("workspaceId", config.workspaceId);
     const organizationId = requireIdentifier("organizationId", config.organizationId);
-    const baseUrl = normalizeBaseUrl(config.baseUrl ?? readEnvironment("SEGMENTSTREAM_URL") ?? DEFAULT_BASE_URL);
-    const issuer = readEnvironment("SEGMENTSTREAM_APP_TOKEN_ISSUER") ?? new URL(baseUrl).origin;
+    const baseUrl = normalizeBaseUrl(config.baseUrl ?? environmentValue(environment, "SEGMENTSTREAM_URL") ?? DEFAULT_BASE_URL);
+    const issuer = environmentValue(environment, "SEGMENTSTREAM_APP_TOKEN_ISSUER") ?? new URL(baseUrl).origin;
     return { workspaceId, organizationId, baseUrl, issuer };
 }
+/** `null` without `NEON_AUTH_BASE_URL`: the app then signs in with SegmentStream, as in 0.2. */
+export function resolveNeonAuth(environment) {
+    const baseUrl = environmentValue(environment, "NEON_AUTH_BASE_URL");
+    if (baseUrl === undefined) {
+        return null;
+    }
+    const ontologyUrl = environmentValue(environment, "SEGMENTSTREAM_ONTOLOGY_URL");
+    return {
+        baseUrl: normalizeUrl("NEON_AUTH_BASE_URL", baseUrl),
+        cookieSecret: environmentValue(environment, "SEGMENTSTREAM_APP_AUTH_COOKIE_SECRET"),
+        ontologyUrl: ontologyUrl === undefined
+            ? undefined
+            : new URL(normalizeUrl("SEGMENTSTREAM_ONTOLOGY_URL", ontologyUrl)).origin,
+    };
+}
 function requireIdentifier(name, value) {
     const trimmed = typeof value === "string" ? value.trim() : "";
     if (trimmed === "") {
@@ -22,20 +40,24 @@ export function trimTrailingSlashes(value) {
     return value.slice(0, end);
 }
 function normalizeBaseUrl(value) {
+    return normalizeUrl("SegmentStream base URL", value);
+}
+function normalizeUrl(name, value) {
     const trimmed = trimTrailingSlashes(value.trim());
     let url;
     try {
         url = new URL(trimmed);
     }
     catch (error) {
-        throw new Error(`SegmentStream base URL is not a valid URL: ${trimmed}`, { cause: error });
+        throw new Error(`${name} is not a valid URL: ${trimmed}`, { cause: error });
     }
     if (url.protocol !== "https:" && url.protocol !== "http:") {
-        throw new Error(`SegmentStream base URL must use http or https: ${trimmed}`);
+        throw new Error(`${name} must use http or https: ${trimmed}`);
     }
     return trimmed;
 }
-function readEnvironment(name) {
-    const value = typeof process === "undefined" ? undefined : process.env[name];
+/** A variable's trimmed value; unset and blank are the same. */
+export function environmentValue(environment, name) {
+    const value = environment[name];
     return value === undefined || value.trim() === "" ? undefined : value.trim();
 }