@segmentstream-cloud/app 0.2.0 → 0.3.1

package/dist/me.js

@@ -0,0 +1,33 @@
+/** The ontology service's account of the caller: `GET /api/ontology/me`. */
+export const ME_PATH = "/api/ontology/me";
+/**
+ * Reads `{ user: { id, name, email, kind, active }, roles, permissions }` tolerantly: unknown
+ * fields are ignored and only what the SDK presents is checked. `null` when it is not that shape.
+ */
+export function parseMe(payload) {
+    if (typeof payload !== "object" || payload === null) {
+        return null;
+    }
+    const { user, roles, permissions } = payload;
+    if (typeof user !== "object" || user === null) {
+        return null;
+    }
+    const { id, name, email, kind, active } = user;
+    if (typeof id !== "string" || id === "") {
+        return null;
+    }
+    return {
+        id,
+        name: typeof name === "string" ? name : null,
+        email: typeof email === "string" ? email : null,
+        kind: typeof kind === "string" ? kind : "member",
+        active: typeof active === "boolean" ? active : true,
+        roles: strings(roles),
+        permissions: strings(permissions),
+    };
+}
+function strings(value) {
+    return Array.isArray(value)
+        ? value.filter((item) => typeof item === "string")
+        : [];
+}

package/dist/neon.d.ts

@@ -0,0 +1,92 @@
+import { NextResponse } from "next/server";
+import type { NextRequest } from "next/server";
+import type { NeonAuthEnvironment, ResolvedConfig } from "./config.js";
+import type { OntologyTransport } from "./ontology.js";
+import type { ProxyOptions, SegmentStreamProxy } from "./proxy.js";
+import type { Fetch } from "./sessions.js";
+import type { AppUser } from "./tokens.js";
+/** The app's sign-in page, which renders `<SignIn />` from `@segmentstream-cloud/app/ui`. */
+export declare const SIGN_IN_PAGE = "/sign-in";
+/** Where `app/src/app/api/auth/[...path]/route.ts` serves the Neon Auth API. */
+export declare const AUTH_API_PATH = "/api/auth";
+/**
+ * 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.
+ */
+export declare const OPEN_PATHS: ReadonlyArray<string>;
+interface NeonError {
+    readonly status?: number;
+    readonly code?: string;
+    readonly message?: string;
+}
+interface NeonResult<T> {
+    readonly data: T | null;
+    readonly error: NeonError | null;
+}
+interface NeonSessionData {
+    readonly session: {
+        readonly id: string;
+    } | null;
+    readonly user: {
+        readonly id: string;
+        readonly email?: string | null;
+        readonly name?: string | null;
+    } | null;
+}
+export type AuthRouteHandler = (request: Request, context: {
+    params: Promise<{
+        path: string[];
+    }>;
+}) => Promise<Response>;
+/** The Neon Auth API for `app/src/app/api/auth/[...path]/route.ts`. */
+export interface AuthRouteHandlers {
+    readonly GET: AuthRouteHandler;
+    readonly POST: AuthRouteHandler;
+    readonly PUT: AuthRouteHandler;
+    readonly DELETE: AuthRouteHandler;
+    readonly PATCH: AuthRouteHandler;
+}
+/** The part of `createNeonAuth(...)` from `@neondatabase/auth/next/server` the SDK uses. */
+export interface NeonAuthServer {
+    getSession(): Promise<NeonResult<NeonSessionData>>;
+    token(): Promise<NeonResult<{
+        readonly token?: string;
+    }>>;
+    signOut(): Promise<NeonResult<unknown>>;
+    handler(): AuthRouteHandlers;
+    middleware(config?: {
+        loginUrl?: string;
+    }): (request: NextRequest) => Promise<NextResponse>;
+}
+export type CreateNeonAuth = (config: {
+    readonly baseUrl: string;
+    readonly cookies: {
+        readonly secret: string;
+        readonly sameSite: "lax";
+    };
+}) => NeonAuthServer;
+export interface SignOutOptions {
+    /** Where to send the browser afterwards. Defaults to the sign-in page. */
+    readonly redirectTo?: string;
+}
+export interface NeonSessionDependencies {
+    readonly config: ResolvedConfig;
+    readonly settings: NeonAuthEnvironment;
+    readonly createNeonAuth: CreateNeonAuth;
+    readonly fetch: Fetch;
+    readonly now: () => number;
+}
+/**
+ * Neon Auth (Managed Better Auth) for the app's users: sessions in cookies through
+ * `@neondatabase/auth`, and roles and permissions from the ontology's `GET /api/ontology/me`.
+ */
+export declare function createNeonSession(dependencies: NeonSessionDependencies): {
+    proxy: (options?: ProxyOptions) => SegmentStreamProxy;
+    authHandlers: () => AuthRouteHandlers;
+    getUser: () => Promise<AppUser | null>;
+    requireUser: () => Promise<AppUser>;
+    can: (permission: string) => Promise<boolean>;
+    signOut: (options?: SignOutOptions) => Promise<never>;
+    ontologyTransport: OntologyTransport;
+};
+export {};

package/dist/neon.js

@@ -0,0 +1,471 @@
+import { NEON_AUTH_SESSION_COOKIE_NAME, NEON_AUTH_SESSION_DATA_COOKIE_NAME, parseSetCookies, } from "@neondatabase/auth/server";
+import { decodeJwt } from "jose";
+import { cookies } from "next/headers";
+import { redirect } from "next/navigation";
+import { NextResponse } from "next/server";
+import { replaceRequestCookies, safeReturnTo } from "./cookies.js";
+import { NOT_INVITED, SIGN_IN_LINK_INVALID, SegmentStreamApiError, apiErrorFrom, readJson, } from "./errors.js";
+import { parseMe } from "./me.js";
+import { createOntologyTransport } from "./ontology-transport.js";
+import { isAllowed } from "./permissions.js";
+import { matchesPathPrefix, normalizePublicPath } from "./proxy.js";
+import { isApiRequest, unauthenticatedResponse } from "./sign-in.js";
+/** The app's sign-in page, which renders `<SignIn />` from `@segmentstream-cloud/app/ui`. */
+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";
+/**
+ * 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.
+ */
+export const OPEN_PATHS = [
+    AUTH_API_PATH,
+    SIGN_IN_PAGE,
+    "/api/health",
+    "/_next",
+    "/favicon.ico",
+    "/robots.txt",
+    "/sitemap.xml",
+    "/manifest.webmanifest",
+];
+/**
+ * Better Auth answers a magic link that names a callback with a redirect to that path on Neon
+ * Auth's own origin; Neon's proxy follows it and loses the session cookie. Without them it answers
+ * JSON with the cookies, and the app's auth route redirects itself.
+ */
+const MAGIC_LINK_CALLBACK_PARAMETERS = ["callbackURL", "errorCallbackURL", "newUserCallbackURL"];
+/** How long a user's roles and permissions are reused before `/api/ontology/me` is asked again. */
+const USER_TTL_MS = 60_000;
+/** Neon Auth JWTs live 15 minutes; a cached one is replaced a minute before it expires. */
+const TOKEN_EARLY_REFRESH_MS = 60_000;
+const CACHE_LIMIT = 1000;
+/** Entries that expire, at most {@link CACHE_LIMIT} of them; the oldest go first. */
+class ExpiringCache {
+    now;
+    #entries = new Map();
+    constructor(now) {
+        this.now = now;
+    }
+    get(key) {
+        const entry = this.#entries.get(key);
+        if (entry === undefined) {
+            return undefined;
+        }
+        if (entry.expiresAt <= this.now()) {
+            this.#entries.delete(key);
+            return undefined;
+        }
+        return entry.value;
+    }
+    set(key, value, expiresAt) {
+        this.#entries.delete(key);
+        this.#entries.set(key, { value, expiresAt });
+        for (const oldest of this.#entries.keys()) {
+            if (this.#entries.size <= CACHE_LIMIT) {
+                break;
+            }
+            this.#entries.delete(oldest);
+        }
+    }
+    delete(key) {
+        this.#entries.delete(key);
+    }
+}
+/**
+ * Neon Auth (Managed Better Auth) for the app's users: sessions in cookies through
+ * `@neondatabase/auth`, and roles and permissions from the ontology's `GET /api/ontology/me`.
+ */
+export function createNeonSession(dependencies) {
+    const { config, settings, now } = dependencies;
+    const tokens = new ExpiringCache(now);
+    const users = new ExpiringCache(now);
+    const loadingUsers = new Map();
+    let server;
+    let routeHandlers;
+    let middleware;
+    /** Created on first use, so that builds without the cookie secret still succeed. */
+    function neonAuth() {
+        if (server !== undefined) {
+            return server;
+        }
+        const secret = settings.cookieSecret;
+        if (secret === undefined || secret.length < 32) {
+            throw new Error("SEGMENTSTREAM_APP_AUTH_COOKIE_SECRET must hold at least 32 characters when NEON_AUTH_BASE_URL is set. " +
+                "SegmentStream sets both on deploy; for local development copy them into app/.env.local.");
+        }
+        server = dependencies.createNeonAuth({
+            baseUrl: settings.baseUrl,
+            // Lax keeps the session on links followed from email and other sites.
+            cookies: { secret, sameSite: "lax" },
+        });
+        return server;
+    }
+    async function identity() {
+        // Reading cookies first marks the page dynamic, so prerendering at build time stops here
+        // before any configuration is needed. Thrown errors pass through untouched: Next.js signals
+        // dynamic rendering with them.
+        await cookies();
+        const result = await neonAuth().getSession();
+        if (result.error !== null) {
+            if (result.error.status === 401) {
+                return null;
+            }
+            throw authUnavailable(result.error);
+        }
+        const session = result.data?.session;
+        const user = result.data?.user;
+        if (session === null || session === undefined || user === null || user === undefined) {
+            return null;
+        }
+        return {
+            sessionId: session.id,
+            userId: user.id,
+            email: user.email ?? undefined,
+            name: user.name ?? undefined,
+        };
+    }
+    /** The session's JWT for the ontology service, reused until shortly before it expires. */
+    async function sessionToken(session) {
+        const cached = tokens.get(session.sessionId);
+        if (cached !== undefined) {
+            return cached;
+        }
+        const result = await neonAuth().token();
+        if (result.error !== null) {
+            if (result.error.status === 401) {
+                return null;
+            }
+            throw authUnavailable(result.error);
+        }
+        const token = result.data?.token;
+        if (typeof token !== "string" || token === "") {
+            throw authUnavailable(new Error("Neon Auth returned no token."));
+        }
+        tokens.set(session.sessionId, token, tokenRefreshAt(token, now()));
+        return token;
+    }
+    function transportFor(session) {
+        return createOntologyTransport({
+            fetch: dependencies.fetch,
+            ontologyUrl: settings.ontologyUrl,
+            credentials: {
+                token: () => sessionToken(session),
+                rejected: () => tokens.delete(session.sessionId),
+            },
+        });
+    }
+    /** Ontology requests as the signed-in user. */
+    const ontologyTransport = {
+        async fetch(path, init) {
+            const session = await identity();
+            if (session === null) {
+                throw new SegmentStreamApiError({
+                    code: "app_session_missing",
+                    status: 401,
+                    detail: "No signed-in user for this request; call the ontology from Server Components, Route Handlers, or Server Functions behind the SegmentStream proxy.",
+                });
+            }
+            return transportFor(session).fetch(path, init);
+        },
+    };
+    async function currentUser(session) {
+        const cached = users.get(session.sessionId);
+        if (cached !== undefined) {
+            return cached;
+        }
+        const pending = loadingUsers.get(session.sessionId);
+        if (pending !== undefined) {
+            return pending;
+        }
+        const loading = (async () => {
+            const response = await transportFor(session).fetch("/me", {
+                method: "GET",
+                headers: { accept: "application/json" },
+            });
+            const payload = await readJson(response);
+            if (!response.ok) {
+                throw apiErrorFrom(response.status, payload, "The ontology service rejected the user.");
+            }
+            const user = parseMe(payload);
+            if (user === null) {
+                throw new SegmentStreamApiError({
+                    code: "ontology_invalid_response",
+                    status: 502,
+                    detail: "GET /api/ontology/me did not answer { user, roles, permissions }.",
+                    retryable: true,
+                });
+            }
+            users.set(session.sessionId, user, now() + USER_TTL_MS);
+            return user;
+        })().finally(() => loadingUsers.delete(session.sessionId));
+        loadingUsers.set(session.sessionId, loading);
+        return loading;
+    }
+    function appUser(session, user) {
+        const email = user.email ?? session.email;
+        const name = user.name ?? session.name;
+        return {
+            id: user.id,
+            ...(email === undefined ? {} : { email }),
+            ...(name === undefined ? {} : { name }),
+            organizationId: config.organizationId,
+            workspaceId: config.workspaceId,
+            roles: user.roles,
+            permissions: user.permissions,
+            kind: user.kind,
+            active: user.active,
+            authUserId: session.userId,
+        };
+    }
+    async function getUser() {
+        const session = await identity();
+        if (session === null) {
+            return null;
+        }
+        return appUser(session, await currentUser(session));
+    }
+    async function requireUser() {
+        const session = await identity();
+        if (session === null) {
+            redirect(SIGN_IN_PAGE);
+        }
+        let user;
+        let notInvited = false;
+        try {
+            user = await currentUser(session);
+        }
+        catch (error) {
+            if (!(error instanceof SegmentStreamApiError) || error.code !== NOT_INVITED) {
+                throw error;
+            }
+            notInvited = true;
+        }
+        if (notInvited || user === undefined) {
+            // The sign-in page explains it and offers to sign out; redirect() must not run inside try.
+            redirect(`${SIGN_IN_PAGE}?error=${NOT_INVITED}`);
+        }
+        return appUser(session, user);
+    }
+    async function can(permission) {
+        let user;
+        try {
+            user = await getUser();
+        }
+        catch (error) {
+            if (error instanceof SegmentStreamApiError && error.code === NOT_INVITED) {
+                return false;
+            }
+            throw error;
+        }
+        return user !== null && isAllowed(permission, user);
+    }
+    async function signOut(options = {}) {
+        const session = await identity().catch(() => null);
+        if (session !== null) {
+            tokens.delete(session.sessionId);
+            users.delete(session.sessionId);
+        }
+        try {
+            await neonAuth().signOut();
+        }
+        catch {
+            // Ending the session upstream is best effort; the cookies below end it in this browser.
+        }
+        const cookieStore = await cookies();
+        for (const name of [NEON_AUTH_SESSION_COOKIE_NAME, NEON_AUTH_SESSION_DATA_COOKIE_NAME]) {
+            cookieStore.set(name, "", {
+                httpOnly: true,
+                secure: true,
+                sameSite: "lax",
+                path: "/",
+                maxAge: 0,
+                expires: new Date(0),
+            });
+        }
+        redirect(safeReturnTo(options.redirectTo ?? SIGN_IN_PAGE));
+    }
+    function authHandlers() {
+        const handlers = () => (routeHandlers ??= neonAuth().handler());
+        return {
+            GET: async (request, context) => {
+                const { path } = await context.params;
+                return path.length === 2 && path[0] === "magic-link" && path[1] === "verify"
+                    ? completeMagicLink(request, context, () => handlers().GET)
+                    : handlers().GET(request, context);
+            },
+            POST: (request, context) => handlers().POST(request, context),
+            PUT: (request, context) => handlers().PUT(request, context),
+            DELETE: (request, context) => handlers().DELETE(request, context),
+            PATCH: (request, context) => handlers().PATCH(request, context),
+        };
+    }
+    function proxy(options = {}) {
+        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.
+                return NextResponse.rewrite(new URL(`${pathname}${search}`, settings.ontologyUrl));
+            }
+            if (publicPaths.some((path) => matchesPathPrefix(pathname, path))) {
+                return NextResponse.next();
+            }
+            middleware ??= neonAuth().middleware({ loginUrl: SIGN_IN_PAGE });
+            const response = await middleware(request);
+            if (!isSignInRedirect(request, response)) {
+                return forwardSessionCookies(request, response);
+            }
+            const replacement = isApiRequest(request)
+                ? unauthenticatedResponse()
+                : signInPageRedirect(request);
+            // Neon Auth clears a stale session cache cookie on the way to sign-in.
+            for (const cookie of response.headers.getSetCookie()) {
+                replacement.headers.append("set-cookie", cookie);
+            }
+            return replacement;
+        };
+    }
+    return {
+        proxy,
+        authHandlers,
+        getUser,
+        requireUser,
+        can,
+        signOut,
+        ontologyTransport,
+    };
+}
+/** Neon Auth's middleware sends visitors without a session to the configured sign-in page. */
+function isSignInRedirect(request, response) {
+    const location = response.headers.get("location");
+    if (response.status < 300 || response.status >= 400 || location === null) {
+        return false;
+    }
+    try {
+        const target = new URL(location, request.nextUrl.origin);
+        return target.origin === request.nextUrl.origin && target.pathname === SIGN_IN_PAGE;
+    }
+    catch {
+        return false;
+    }
+}
+const MIDDLEWARE_REQUEST_HEADER = "x-middleware-request-";
+/**
+ * Neon Auth's middleware refreshes the session cookies on its response only, so the page this
+ * request renders would still read the old ones and ask Neon Auth again, which cannot set cookies
+ * from a Server Component. The refreshed cookies go into the request too: through
+ * `NextResponse.cookies`, which Next.js merges into `cookies()`, and the `Cookie` header, which
+ * Route Handlers read.
+ */
+function forwardSessionCookies(request, response) {
+    const setCookies = response.headers.getSetCookie();
+    if (response.headers.get("x-middleware-next") !== "1" || setCookies.length === 0) {
+        return response;
+    }
+    const refreshed = setCookies.flatMap((header) => parseSetCookies(header));
+    const expired = (cookie) => cookie.value === "" ||
+        (cookie.maxAge !== undefined && cookie.maxAge <= 0) ||
+        (cookie.expires !== undefined && cookie.expires.getTime() <= Date.now());
+    const requestHeaders = new Headers(request.headers);
+    // Keep the request headers Neon Auth's middleware added.
+    for (const [name, value] of response.headers) {
+        if (name.startsWith(MIDDLEWARE_REQUEST_HEADER)) {
+            requestHeaders.set(name.slice(MIDDLEWARE_REQUEST_HEADER.length), value);
+        }
+    }
+    const removed = new Set(refreshed.filter(expired).map((cookie) => cookie.name));
+    const live = refreshed.filter((cookie) => !expired(cookie));
+    const cookieHeader = replaceRequestCookies(request.headers.get("cookie"), Object.fromEntries(live.map((cookie) => [cookie.name, cookie.value])))
+        .split("; ")
+        .filter((pair) => pair !== "" && !removed.has(pair.split("=", 1)[0] ?? ""))
+        .join("; ");
+    requestHeaders.set("cookie", cookieHeader);
+    const forwarded = NextResponse.next({ request: { headers: requestHeaders } });
+    for (const { name, value, ...options } of refreshed) {
+        forwarded.cookies.set(name, value, options);
+    }
+    return forwarded;
+}
+/**
+ * Signs in with an emailed magic link on the app's own domain: Neon Auth verifies the token
+ * without a callback and sets the session cookies, which go to the browser with a redirect to the
+ * link's `callbackURL` path. A link Neon Auth rejects leads to the sign-in page instead.
+ */
+async function completeMagicLink(request, context, verify) {
+    const url = new URL(request.url);
+    const destination = safeReturnTo(url.searchParams.get("callbackURL"));
+    const token = url.searchParams.get("token");
+    if (token === null || token === "") {
+        return invalidSignInLink(url.origin, destination);
+    }
+    for (const name of MAGIC_LINK_CALLBACK_PARAMETERS) {
+        url.searchParams.delete(name);
+    }
+    const handler = verify();
+    let response;
+    try {
+        response = await handler(new Request(url, request), context);
+    }
+    catch {
+        return invalidSignInLink(url.origin, destination);
+    }
+    // The body holds the session token; only the cookies go on to the browser.
+    void response.body?.cancel().catch(() => undefined);
+    if (!response.ok) {
+        return invalidSignInLink(url.origin, destination);
+    }
+    const redirect = NextResponse.redirect(new URL(destination, url.origin), 303);
+    for (const cookie of response.headers.getSetCookie()) {
+        redirect.headers.append("set-cookie", cookie);
+    }
+    redirect.headers.set("cache-control", "no-store");
+    return redirect;
+}
+/** An expired, used or unknown sign-in link: the sign-in page explains it and sends a code. */
+function invalidSignInLink(origin, destination) {
+    const url = new URL(SIGN_IN_PAGE, origin);
+    url.searchParams.set("error", SIGN_IN_LINK_INVALID);
+    if (destination !== "/") {
+        url.searchParams.set("returnTo", destination);
+    }
+    const response = NextResponse.redirect(url, 303);
+    response.headers.set("cache-control", "no-store");
+    return response;
+}
+/** Page navigations go to the sign-in page and come back to where they started. */
+function signInPageRedirect(request) {
+    const url = new URL(SIGN_IN_PAGE, request.nextUrl.origin);
+    const returnTo = safeReturnTo(`${request.nextUrl.pathname}${request.nextUrl.search}`);
+    if (returnTo !== "/" && returnTo.length <= 1024) {
+        url.searchParams.set("returnTo", returnTo);
+    }
+    const response = NextResponse.redirect(url, 307);
+    response.headers.set("cache-control", "no-store");
+    return response;
+}
+function tokenRefreshAt(token, now) {
+    try {
+        const { exp } = decodeJwt(token);
+        if (typeof exp === "number") {
+            return Math.max(now, exp * 1000 - TOKEN_EARLY_REFRESH_MS);
+        }
+    }
+    catch {
+        // Not a JWT the SDK can read; the service decides whether it is valid.
+    }
+    return now;
+}
+function authUnavailable(cause) {
+    const code = typeof cause === "object" && cause !== null && "code" in cause && typeof cause.code === "string"
+        ? cause.code
+        : undefined;
+    return new SegmentStreamApiError({
+        code: "auth_unavailable",
+        status: 503,
+        detail: code === undefined
+            ? "Neon Auth could not be reached. Try again in a moment."
+            : `Neon Auth could not be reached (${code}). Try again in a moment.`,
+        retryable: true,
+        cause,
+    });
+}

package/dist/ontology-transport.d.ts

@@ -0,0 +1,23 @@
+import type { OntologyTransport } from "./ontology.js";
+import type { Fetch } from "./sessions.js";
+/** Every ontology route lives under this path, beside the app on the same origin. */
+export declare const ONTOLOGY_BASE_PATH = "/api/ontology";
+/** The caller's bearer token for the ontology service. */
+export interface OntologyCredentials {
+    /** The token for this request, or `null` when nobody is signed in. */
+    readonly token: () => Promise<string | null>;
+    /** Forgets a token the service rejected, so `token` returns a fresh one. */
+    readonly rejected?: (token: string) => void;
+}
+export interface OntologyTransportOptions {
+    readonly fetch: Fetch;
+    /** `SEGMENTSTREAM_ONTOLOGY_URL`: where the service runs when it is not beside the app. */
+    readonly ontologyUrl: string | undefined;
+    readonly credentials: OntologyCredentials;
+}
+/**
+ * Server-side requests to the ontology service with the signed-in user's token. Deployed, the
+ * service shares the app's origin; `SEGMENTSTREAM_ONTOLOGY_URL` points elsewhere, for example at
+ * `http://localhost:3100` or the deployed app during local development.
+ */
+export declare function createOntologyTransport(options: OntologyTransportOptions): OntologyTransport;