@segmentstream-cloud/app 0.1.0 → 0.3.0

package/README.md

@@ -1,8 +1,11 @@
 # @segmentstream-cloud/app
 
-Sign-in and sessions for SegmentStream workspace apps built with Next.js (App Router,
-version 16 or later). Every visitor signs in with their SegmentStream account, and only
-members of the app's workspace get in.
+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
 
@@ -10,17 +13,18 @@ members of the app's workspace get in.
 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:
@@ -29,22 +33,49 @@ 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();
+```
+
+**`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
@@ -55,58 +86,210 @@ 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
+import { sql } from "@segmentstream-cloud/app";
+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
+     WHERE order_date >= @from
+     ORDER BY order_date`,
+    { params: { from: sql.date("2026-09-01") } },
+  );
+
+  return <pre>{JSON.stringify(rows, null, 2)}</pre>;
+}
+```
+
+- 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.
+  Strings, booleans, `bigint`, safe integers (`INT64`), other numbers (`FLOAT64`), `Date`
+  (`TIMESTAMP`) and arrays of these are typed automatically. Use `sql.date()`,
+  `sql.datetime()`, `sql.timestamp()`, `sql.numeric()`, `sql.bignumeric()`, `sql.int64()`
+  and `sql.array(type, values)` for anything else.
+- `query()` waits for running queries (`timeoutMs`, default 60 s) and follows result
+  pages up to `maxRows` (default 10,000); `truncated` reports whether more rows exist.
+  `maximumBytesBilled` lowers the per-query byte ceiling; `warehouse.dryRun()` returns the
+  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)`.
+  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.
+
+`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 locally 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`.
+- 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,23 +1,60 @@
-import type { SegmentStreamAppConfig } from "./config.js";
+import type { Environment, SegmentStreamAppConfig } from "./config.js";
+import type { SemanticClient, WarehouseClient } from "./data.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. Legacy sign-in only.
+     */
+    readonly fetch: (path: string, init?: RequestInit) => Promise<Response>;
+    /**
+     * 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. 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,11 +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);
@@ -15,12 +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: 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();
 }

package/dist/cookies.d.ts

@@ -1,12 +1,16 @@
 import type { NextResponse } from "next/server";
+export { safeReturnTo } from "./return-to.js";
 export declare const REFRESH_COOKIE_MAX_AGE_SECONDS: number;
 export declare const AUTH_FLOW_COOKIE_MAX_AGE_SECONDS: number;
+/** Sign-ins one browser can have in progress at once; one more abandons them all. */
+export declare const MAX_PENDING_AUTH_FLOWS = 4;
 export interface CookieNames {
     readonly session: string;
     readonly refresh: string;
-    readonly authFlow: string;
+    /** Each sign-in in progress has its own cookie: this prefix followed by its `state`. */
+    readonly authFlowPrefix: string;
 }
-/** Cookie names and attributes for one request origin. */
+/** Cookie names and attributes for one app on one request origin. */
 export interface CookiePolicy {
     readonly secure: boolean;
     readonly names: CookieNames;
@@ -28,18 +32,23 @@ export declare function isLoopbackHostname(hostname: string): boolean;
  * Browsers reject `Secure` and `__Host-` cookies on plain-HTTP origins, except that
  * local development on http://localhost should still work. Every other origin uses
  * `__Host-` cookies, which cannot be set by sibling subdomains.
+ *
+ * Browsers share cookies between ports, so apps on `localhost:3000` and `localhost:3001`
+ * see one cookie jar. Names carry the workspace id to keep each app's session its own.
  */
-export declare function cookiePolicyFor(url: URL): CookiePolicy;
+export declare function cookiePolicyFor(url: URL, workspaceId: string): CookiePolicy;
 /** Candidate cookie names for code that only knows the request host (Server Components). */
-export declare function sessionCookieCandidates(hostname: string): readonly string[];
+export declare function sessionCookieCandidates(hostname: string, workspaceId: string): readonly string[];
+/** The cookie holding one sign-in's flow, or undefined for a `state` this SDK never issues. */
+export declare function authFlowCookieName(policy: CookiePolicy, state: string): string | undefined;
+/** The sign-in flow cookies a request carries, one per sign-in still in progress. */
+export declare function pendingAuthFlowCookies(policy: CookiePolicy, requestCookieNames: readonly string[]): string[];
 export declare function setSessionCookies(response: NextResponse, policy: CookiePolicy, tokens: SessionTokens): void;
 export declare function clearSessionCookies(response: NextResponse, policy: CookiePolicy): void;
 export declare function setAuthFlowCookie(response: NextResponse, policy: CookiePolicy, flow: AuthFlowState): void;
-export declare function clearAuthFlowCookie(response: NextResponse, policy: CookiePolicy): void;
+export declare function clearCookie(response: NextResponse, policy: CookiePolicy, name: string): void;
 export declare function encodeAuthFlowState(flow: AuthFlowState): string;
 export declare function decodeAuthFlowState(value: string | undefined): AuthFlowState | null;
-/** Reduces a return path to a same-origin relative path, falling back to `/`. */
-export declare function safeReturnTo(value: string | null | undefined): string;
 /**
  * Replaces the named cookies in a raw `Cookie` request header while preserving every
  * other cookie byte for byte.