@segmentstream-cloud/ontology 0.8.0 → 0.9.0

package/README.md

@@ -135,7 +135,7 @@ entity, the verb or both: `lead:*`, `*:read`, `*:*`.
   Members hold `member` and their assigned roles; an API key holds exactly the roles it was
   created with. A role the ontology no longer declares grants nothing.
 - The catalog, `describe`, `graph`, `openapi.json` and `me` need only authentication;
-  `status` and `sign-in/check` need none. `?as=me` lists only the actions the caller may run.
+  `status`, `sign-in/check` and the `docs` page need none. `?as=me` lists only the actions the caller may run.
 - `check` fails on a role without permissions, on a permission whose entity or verb does not
   exist, and on `allow`, which version 0.2 replaced. It warns on an action no role may run
   and on `*:*`.
@@ -155,6 +155,12 @@ export function handleOntologyRequest(request: Request): Promise<Response> {
 }
 ```
 
+`GET /api/ontology/docs` serves a Scalar API reference over `openapi.json`. A browser signed
+in to the app authenticates with the app's Neon Auth session cookie
+(`__Secure-neon-auth.session_token`), which the service exchanges at Neon Auth for the
+session's token and verifies like a bearer token. A bearer token always takes precedence. The
+cookie authenticates a `POST` only when its `Origin` is the app's own.
+
 `handler(request)` takes a web `Request` and returns a `Response`. `dispose()` closes the
 database pool. `configFromEnv()` reads these variables (`ENVIRONMENT_VARIABLES`, and the
 optional `NEON_AUTH_ENVIRONMENT_VARIABLES`). It throws `OntologyServiceConfigError` when

package/dist/names.d.ts

@@ -21,7 +21,7 @@ export declare const HISTORY_SUFFIX = "_history";
 /** The combinators of the query language, which take the place of field names in a `where`. */
 export declare const RESERVED_MEMBER_NAMES: readonly ["and", "or", "not"];
 /** Routes of the ontology service under `/api/ontology/`, which an entity's routes would shadow. */
-export declare const RESERVED_ENTITY_NAMES: readonly ["graph", "status", "describe", "openapi", "mcp", "me"];
+export declare const RESERVED_ENTITY_NAMES: readonly ["graph", "status", "describe", "openapi", "docs", "mcp", "me"];
 /** `/api/ontology/<entity>/{id}/history`, which a relationship's traversal would shadow. */
 export declare const RESERVED_RELATIONSHIP_NAMES: readonly ["history"];
 export declare function isSystemProperty(name: string): boolean;

package/dist/names.js

@@ -54,6 +54,7 @@ export const RESERVED_ENTITY_NAMES = [
     "status",
     "describe",
     "openapi",
+    "docs",
     "mcp",
     "me",
 ];

package/dist/service/authentication.d.ts

@@ -23,8 +23,8 @@ declare const Authentication_base: HttpApiMiddleware.ServiceClass<Authentication
 }, CurrentPrincipal, readonly [import("effect/Schema").Top, import("effect/Schema").Top, import("effect/Schema").Top], RequestId>>;
 /**
  * Authenticates every ontology route except `status`: a Neon Auth token, a SegmentStream app token
- * or an API key, all as `Authorization: Bearer …`. Failures answer the request directly, before its
- * input is decoded.
+ * or an API key, all as `Authorization: Bearer …`; without one, the app's Neon Auth session cookie.
+ * Failures answer the request directly, before its input is decoded.
  */
 export declare class Authentication extends Authentication_base {
 }
@@ -79,6 +79,32 @@ export declare function verifyByIssuer(verifiers: ReadonlyMap<string, TokenVerif
 export declare function tokenVerifier(config: TokenVerifierConfig & {
     readonly neonAuth?: NeonAuthEnvironment | undefined;
 }): TokenVerifier;
+/**
+ * The session cookie the app's Neon Auth sets on the app's domain. The ontology service shares the
+ * domain, so a signed-in browser sends it here too: the docs page relies on it.
+ */
+export declare const NEON_AUTH_SESSION_COOKIE = "__Secure-neon-auth.session_token";
+export type SessionExchangeResult = {
+    readonly status: "token";
+    readonly token: string;
+} | {
+    readonly status: "invalid";
+} | {
+    readonly status: "unavailable";
+};
+/** Turns a Neon Auth session cookie into the session's token; `origin` is the app's. */
+export type SessionExchange = (session: Redacted.Redacted<string>, origin: string) => Promise<SessionExchangeResult>;
+/**
+ * Exchanges a session cookie for its token at Neon Auth's `GET <base URL>/token`, as the app's
+ * `@neondatabase/auth` does, and reuses the token until shortly before it expires. The token is then
+ * verified like any bearer token, so the exchange never vouches for a session on its own.
+ */
+export declare function neonAuthSessionExchange(config: {
+    readonly baseUrl: string;
+}, options?: {
+    readonly fetch?: typeof fetch;
+    readonly now?: () => number;
+}): SessionExchange;
 type Authenticated = {
     readonly status: "authenticated";
     readonly principal: Principal;
@@ -93,6 +119,9 @@ type Authenticated = {
 };
 /** Resolves a bearer credential to a principal. */
 export declare function authenticate(credential: Redacted.Redacted<string>, verifyToken: TokenVerifier): Effect.Effect<Authenticated, never, OntologyBackend>;
-/** The {@link Authentication} middleware, verifying tokens with `verifyToken`. */
-export declare function authenticationLayer(verifyToken: TokenVerifier): Layer.Layer<Authentication, never, OntologyBackend>;
+/**
+ * The {@link Authentication} middleware, verifying tokens with `verifyToken`. With `exchangeSession`,
+ * a request without a bearer token may authenticate with the app's Neon Auth session cookie.
+ */
+export declare function authenticationLayer(verifyToken: TokenVerifier, exchangeSession?: SessionExchange): Layer.Layer<Authentication, never, OntologyBackend>;
 export {};

package/dist/service/authentication.js

@@ -1,8 +1,9 @@
 import { Cause, Context, Effect, Layer, Redacted } from "effect";
+import { HttpServerRequest } from "effect/unstable/http";
 import { HttpApiMiddleware, HttpApiSecurity, OpenApi } from "effect/unstable/httpapi";
 import { createRemoteJWKSet, decodeJwt, errors, jwtVerify, } from "jose";
 import { API_KEY_PREFIX } from "../runtime/principals.js";
-import { RequestId, internalError, notInvited, toServerResponse, unauthorized, unavailable, } from "./errors.js";
+import { RequestId, crossOriginSession, internalError, notInvited, toServerResponse, unauthorized, unavailable, } from "./errors.js";
 import { OntologyBackend } from "./runtime-contract.js";
 import { ErrorSchemas } from "./schemas.js";
 const CLOCK_TOLERANCE_SECONDS = 5;
@@ -12,8 +13,8 @@ export class CurrentPrincipal extends Context.Service()("@segmentstream-cloud/on
 }
 /**
  * Authenticates every ontology route except `status`: a Neon Auth token, a SegmentStream app token
- * or an API key, all as `Authorization: Bearer …`. Failures answer the request directly, before its
- * input is decoded.
+ * or an API key, all as `Authorization: Bearer …`; without one, the app's Neon Auth session cookie.
+ * Failures answer the request directly, before its input is decoded.
  */
 export class Authentication extends HttpApiMiddleware.Service()("@segmentstream-cloud/ontology/Authentication", {
     security: {
@@ -173,6 +174,105 @@ export function tokenVerifier(config) {
     }
     return verifyByIssuer(verifiers);
 }
+/**
+ * The session cookie the app's Neon Auth sets on the app's domain. The ontology service shares the
+ * domain, so a signed-in browser sends it here too: the docs page relies on it.
+ */
+export const NEON_AUTH_SESSION_COOKIE = "__Secure-neon-auth.session_token";
+/** Session tokens kept at once; past it the oldest go first. */
+const SESSION_CACHE_SIZE = 1_000;
+/** A session's token is fetched again this long before it expires. */
+const SESSION_TOKEN_MARGIN_MS = 60_000;
+const SESSION_EXCHANGE_TIMEOUT_MS = 5_000;
+/**
+ * Exchanges a session cookie for its token at Neon Auth's `GET <base URL>/token`, as the app's
+ * `@neondatabase/auth` does, and reuses the token until shortly before it expires. The token is then
+ * verified like any bearer token, so the exchange never vouches for a session on its own.
+ */
+export function neonAuthSessionExchange(config, options = {}) {
+    const fetchToken = options.fetch ?? fetch;
+    const now = options.now ?? Date.now;
+    const endpoint = new URL("token", config.baseUrl.endsWith("/") ? config.baseUrl : `${config.baseUrl}/`);
+    const cache = new Map();
+    return async function exchangeSession(session, origin) {
+        const value = Redacted.value(session);
+        const cached = cache.get(value);
+        if (cached !== undefined && cached.refreshAt > now()) {
+            return { status: "token", token: cached.token };
+        }
+        cache.delete(value);
+        let response;
+        try {
+            response = await fetchToken(endpoint, {
+                headers: { cookie: `${NEON_AUTH_SESSION_COOKIE}=${value}`, origin },
+                redirect: "error",
+                signal: AbortSignal.timeout(SESSION_EXCHANGE_TIMEOUT_MS),
+            });
+        }
+        catch {
+            return { status: "unavailable" };
+        }
+        if (response.status === 401 || response.status === 403) {
+            return { status: "invalid" };
+        }
+        if (!response.ok) {
+            return { status: "unavailable" };
+        }
+        const body = (await response.json().catch(() => undefined));
+        const token = body?.token;
+        if (typeof token !== "string" || token === "") {
+            return { status: "unavailable" };
+        }
+        const expiresAt = tokenExpiry(token);
+        if (expiresAt !== undefined) {
+            if (cache.size >= SESSION_CACHE_SIZE) {
+                cache.delete(cache.keys().next().value);
+            }
+            cache.set(value, { token, refreshAt: expiresAt - SESSION_TOKEN_MARGIN_MS });
+        }
+        return { status: "token", token };
+    };
+}
+/** When a token expires, in milliseconds; `undefined` for a token without a readable `exp`. */
+function tokenExpiry(token) {
+    try {
+        const { exp } = decodeJwt(token);
+        return typeof exp === "number" ? exp * 1_000 : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+const SAFE_METHODS = new Set(["GET", "HEAD", "OPTIONS"]);
+/**
+ * The origin the browser addressed. Vercel and the app's development proxy name it in the forwarded
+ * headers; otherwise it is the request URL's, which Nitro passes on whole.
+ */
+function requestOrigin(request) {
+    const first = (value) => value?.split(",")[0]?.trim() || undefined;
+    const url = URL.canParse(request.originalUrl) ? new URL(request.originalUrl) : undefined;
+    const host = first(request.headers["x-forwarded-host"]) ?? url?.host ?? request.headers.host;
+    if (host === undefined || host === "") {
+        return undefined;
+    }
+    const forwardedProto = first(request.headers["x-forwarded-proto"]);
+    const protocol = forwardedProto === "http" || forwardedProto === "https"
+        ? forwardedProto
+        : (url?.protocol.slice(0, -1) ?? "https");
+    return `${protocol}://${host}`;
+}
+/**
+ * A request the session cookie may authenticate: any read, and a change only when the browser says
+ * it comes from the app's own origin. Browsers send `Origin` with every cross-origin request and
+ * with same-origin `POST`s, so a change without one is refused too.
+ */
+function sessionMayAuthenticate(request) {
+    if (SAFE_METHODS.has(request.method)) {
+        return true;
+    }
+    const origin = request.headers.origin;
+    return origin !== undefined && origin === requestOrigin(request);
+}
 /** Resolves a bearer credential to a principal. */
 export function authenticate(credential, verifyToken) {
     return Effect.gen(function* () {
@@ -198,14 +298,48 @@ export function authenticate(credential, verifyToken) {
             : { status: "authenticated", principal: member }), Effect.catchTag("NotInvited", () => Effect.succeed({ status: "not_invited" })));
     });
 }
-/** The {@link Authentication} middleware, verifying tokens with `verifyToken`. */
-export function authenticationLayer(verifyToken) {
+/**
+ * Resolves the Neon Auth session cookie to a principal through the session's token. `undefined`
+ * when the request has no session cookie, or the service no Neon Auth.
+ */
+function authenticateSession(request, exchangeSession, verifyToken) {
+    return Effect.gen(function* () {
+        const session = request.cookies[NEON_AUTH_SESSION_COOKIE];
+        const origin = requestOrigin(request);
+        if (exchangeSession === undefined || session === undefined || session === "") {
+            return undefined;
+        }
+        if (origin === undefined || !sessionMayAuthenticate(request)) {
+            return { status: "cross_origin" };
+        }
+        const exchange = yield* Effect.promise(() => exchangeSession(Redacted.make(session), origin));
+        switch (exchange.status) {
+            case "token":
+                return yield* authenticate(Redacted.make(exchange.token), verifyToken);
+            case "invalid":
+                return { status: "rejected" };
+            case "unavailable":
+                return { status: "unavailable" };
+        }
+    });
+}
+/**
+ * The {@link Authentication} middleware, verifying tokens with `verifyToken`. With `exchangeSession`,
+ * a request without a bearer token may authenticate with the app's Neon Auth session cookie.
+ */
+export function authenticationLayer(verifyToken, exchangeSession) {
     return Layer.effect(Authentication, Effect.gen(function* () {
         const backend = yield* OntologyBackend;
         return Authentication.of({
             bearer: (httpEffect, { credential }) => Effect.gen(function* () {
                 const requestId = yield* RequestId;
-                const outcome = yield* authenticate(credential, verifyToken).pipe(Effect.provideService(OntologyBackend, backend), Effect.catchCause((cause) => Cause.hasInterruptsOnly(cause)
+                const request = yield* HttpServerRequest.HttpServerRequest;
+                const outcome = yield* Effect.gen(function* () {
+                    const fromSession = Redacted.value(credential) === ""
+                        ? yield* authenticateSession(request, exchangeSession, verifyToken)
+                        : undefined;
+                    return fromSession ?? (yield* authenticate(credential, verifyToken));
+                }).pipe(Effect.provideService(OntologyBackend, backend), Effect.catchCause((cause) => Cause.hasInterruptsOnly(cause)
                     ? Effect.failCause(cause)
                     : Effect.logError("ontology.authentication.failed", cause).pipe(Effect.annotateLogs({ requestId }), Effect.as({ status: "failed" }))));
                 switch (outcome.status) {
@@ -217,6 +351,8 @@ export function authenticationLayer(verifyToken) {
                         return toServerResponse(unauthorized(requestId, "The bearer token is invalid, expired or revoked."));
                     case "not_invited":
                         return toServerResponse(notInvited(requestId));
+                    case "cross_origin":
+                        return toServerResponse(crossOriginSession(requestId));
                     case "unavailable":
                         return yield* Effect.logWarning("ontology.authentication.unavailable").pipe(Effect.annotateLogs({ requestId }), Effect.as(toServerResponse(unavailable(requestId))));
                     case "failed":

package/dist/service/docs.d.ts

@@ -0,0 +1,9 @@
+import { HttpRouter } from "effect/unstable/http";
+/** The API reference page: `GET /api/ontology/docs`. */
+export declare const DOCS_PATH = "/api/ontology/docs";
+/**
+ * The API reference at `/api/ontology/docs`: Scalar over the service's own `openapi.json`. The page
+ * is public and holds no part of the ontology: it loads the document as the reader, with the app's
+ * session cookie when they are signed in to the app, or with a token they paste.
+ */
+export declare const DocsRoute: import("effect/Layer").Layer<never, never, HttpRouter.HttpRouter>;

package/dist/service/docs.js

@@ -0,0 +1,197 @@
+import { Effect } from "effect";
+import { HttpRouter, HttpServerResponse } from "effect/unstable/http";
+import { BASE_PATH } from "./api.js";
+/** The API reference page: `GET /api/ontology/docs`. */
+export const DOCS_PATH = `${BASE_PATH}/docs`;
+const OPENAPI_PATH = `${BASE_PATH}/openapi.json`;
+/**
+ * Scalar's API reference, pinned with its integrity hash: a different file never runs. Bump both
+ * together: `curl -sL <url> | openssl dgst -sha384 -binary | openssl base64 -A`.
+ */
+const SCALAR_SCRIPT = {
+    src: "https://cdn.jsdelivr.net/npm/@scalar/api-reference@1.73.1/dist/browser/standalone.js",
+    integrity: "sha384-kYDGzV91Jnn3TbHINV3nt54riK2uMJDfN5Al8dAkz4FssELTBWbD8rgw32sTKfOi",
+};
+/**
+ * Scalar without its hosted extras: no telemetry, AI agent, MCP button, developer tools or fonts
+ * from scalar.com. Requests from the page go to the ontology itself, never through Scalar's proxy.
+ */
+const SCALAR_CONFIGURATION = {
+    telemetry: false,
+    agent: { disabled: true },
+    mcp: { disabled: true },
+    showDeveloperTools: "never",
+    withDefaultFonts: false,
+    hideClientButton: true,
+    documentDownloadType: "json",
+};
+/** The key the page keeps a pasted token under, for this tab only. */
+const TOKEN_STORAGE_KEY = "segmentstream-ontology-docs-token";
+/** JSON inside a `<script>`: nothing in it can close the element. */
+function scriptJson(value) {
+    return JSON.stringify(value).replace(/</g, "\\u003c");
+}
+function contentSecurityPolicy(nonce) {
+    return [
+        "default-src 'none'",
+        `script-src 'nonce-${nonce}' https://cdn.jsdelivr.net`,
+        // Scalar injects its styles at runtime.
+        "style-src 'self' 'unsafe-inline'",
+        "img-src 'self' data: blob: https:",
+        "font-src 'self' data:",
+        "connect-src 'self'",
+        "worker-src 'self' blob:",
+        "base-uri 'none'",
+        "form-action 'none'",
+        "frame-ancestors 'none'",
+    ].join("; ");
+}
+function page(nonce) {
+    const settings = scriptJson({
+        openapi: OPENAPI_PATH,
+        storageKey: TOKEN_STORAGE_KEY,
+        configuration: SCALAR_CONFIGURATION,
+    });
+    return `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <meta name="robots" content="noindex" />
+    <title>Ontology API</title>
+    <style>
+      #sign-in {
+        font: 14px/1.5 system-ui, sans-serif;
+        max-width: 28rem;
+        margin: 15vh auto;
+        padding: 0 1.5rem;
+        color: #18181b;
+      }
+      #sign-in h1 { font-size: 1.25rem; margin: 0 0 .5rem; }
+      #sign-in p { margin: 0 0 1rem; color: #52525b; }
+      #sign-in label { display: block; font-weight: 500; margin-bottom: .25rem; }
+      #sign-in input {
+        box-sizing: border-box;
+        width: 100%;
+        padding: .5rem .625rem;
+        border: 1px solid #d4d4d8;
+        border-radius: .375rem;
+        font: inherit;
+      }
+      #sign-in button {
+        margin-top: .75rem;
+        padding: .5rem .875rem;
+        border: 0;
+        border-radius: .375rem;
+        background: #18181b;
+        color: #fff;
+        font: inherit;
+        cursor: pointer;
+      }
+      #sign-in [role="alert"] { margin-top: .75rem; color: #b91c1c; }
+    </style>
+  </head>
+  <body>
+    <main id="sign-in" hidden>
+      <form>
+        <h1>Ontology API</h1>
+        <p>Sign in to the app in this browser, or paste a bearer token or an API key (ssk_…).</p>
+        <label for="token">Token or API key</label>
+        <input id="token" type="password" autocomplete="off" spellcheck="false" required />
+        <button type="submit">Open the reference</button>
+        <p role="alert"></p>
+      </form>
+    </main>
+    <div id="app"></div>
+    <script
+      nonce="${nonce}"
+      src="${SCALAR_SCRIPT.src}"
+      integrity="${SCALAR_SCRIPT.integrity}"
+      crossorigin="anonymous"
+    ></script>
+    <script nonce="${nonce}">
+      (() => {
+        const settings = ${settings};
+        const signIn = document.getElementById("sign-in");
+        const form = signIn.querySelector("form");
+        const input = document.getElementById("token");
+        const alert = signIn.querySelector("[role=alert]");
+
+        async function load(token) {
+          const response = await fetch(settings.openapi, {
+            credentials: "same-origin",
+            headers: token ? { authorization: "Bearer " + token } : {},
+          });
+
+          if (response.ok) {
+            return { spec: await response.json() };
+          }
+
+          const body = await response.json().catch(() => ({}));
+
+          return { status: response.status, detail: body.detail };
+        }
+
+        function show(spec, token) {
+          signIn.hidden = true;
+          window.Scalar.createApiReference(document.getElementById("app"), {
+            ...settings.configuration,
+            content: spec,
+            authentication: {
+              preferredSecurityScheme: "bearer",
+              ...(token ? { securitySchemes: { bearer: { token } } } : {}),
+            },
+          });
+        }
+
+        async function open(token) {
+          let result;
+
+          try {
+            result = await load(token);
+          } catch {
+            result = { status: 0 };
+          }
+
+          if (result.spec !== undefined) {
+            if (token) {
+              sessionStorage.setItem(settings.storageKey, token);
+            }
+            show(result.spec, token);
+
+            return;
+          }
+
+          sessionStorage.removeItem(settings.storageKey);
+          signIn.hidden = false;
+          alert.textContent =
+            !token && result.status === 401
+              ? ""
+              : (result.detail ?? "The reference could not be loaded. Try again shortly.");
+        }
+
+        form.addEventListener("submit", (event) => {
+          event.preventDefault();
+          open(input.value.trim());
+        });
+
+        open(sessionStorage.getItem(settings.storageKey) ?? "");
+      })();
+    </script>
+  </body>
+</html>
+`;
+}
+/**
+ * The API reference at `/api/ontology/docs`: Scalar over the service's own `openapi.json`. The page
+ * is public and holds no part of the ontology: it loads the document as the reader, with the app's
+ * session cookie when they are signed in to the app, or with a token they paste.
+ */
+export const DocsRoute = HttpRouter.add("GET", DOCS_PATH, Effect.sync(() => {
+    const nonce = crypto.randomUUID().replaceAll("-", "");
+    return HttpServerResponse.html(page(nonce)).pipe(HttpServerResponse.setHeaders({
+        "content-security-policy": contentSecurityPolicy(nonce),
+        "referrer-policy": "no-referrer",
+        "x-content-type-options": "nosniff",
+    }));
+}));

package/dist/service/errors.d.ts

@@ -51,6 +51,11 @@ export declare function unauthorized(requestId: string, detail: string): ErrorRe
  * The detail is written for the person, since the app shows it.
  */
 export declare function notInvited(requestId: string): ErrorResponse;
+/**
+ * A request that changes something came with the session cookie but not from the app's own pages.
+ * The cookie rides along with any request to the app's domain, so only its origin can vouch for it.
+ */
+export declare function crossOriginSession(requestId: string): ErrorResponse;
 export declare function unavailable(requestId: string): ErrorResponse;
 export declare function internalError(requestId: string): ErrorResponse;
 export declare function routeNotFound(requestId: string): ErrorResponse;

package/dist/service/errors.js

@@ -67,6 +67,20 @@ export function notInvited(requestId) {
         body: { error: "not_invited", detail: "Ask your administrator for an invitation.", requestId },
     };
 }
+/**
+ * A request that changes something came with the session cookie but not from the app's own pages.
+ * The cookie rides along with any request to the app's domain, so only its origin can vouch for it.
+ */
+export function crossOriginSession(requestId) {
+    return {
+        status: 403,
+        body: {
+            error: "forbidden",
+            detail: "The session cookie only authenticates requests from the app's own pages; send a bearer token.",
+            requestId,
+        },
+    };
+}
 export function unavailable(requestId) {
     return {
         status: 503,

package/dist/service/service.js

@@ -4,10 +4,11 @@ import { HttpApiBuilder } from "effect/unstable/httpapi";
 import { nameToWire } from "../authoring-names.js";
 import { sqlServiceRuntime } from "../runtime/service-binding.js";
 import { ErrorResponsesLive, buildApi } from "./api.js";
-import { authenticationLayer, tokenVerifier } from "./authentication.js";
+import { authenticationLayer, neonAuthSessionExchange, tokenVerifier } from "./authentication.js";
 import { OntologyServiceConfigError, } from "./config.js";
 import { RequestId, failureResponse, internalError, errorBodyForWire, routeNotFound, toServerResponse, } from "./errors.js";
 import { deployedConnections, localConnections } from "./connections.js";
+import { DocsRoute } from "./docs.js";
 import { handlersLayer } from "./handlers.js";
 import { planApi } from "./plan.js";
 /** The header every response carries: the hash of the manifest the service serves. */
@@ -62,13 +63,14 @@ export function createOntologyService(ontology, config) {
     const built = buildApi(plan);
     const hooks = afterCommitHooks(plan, config.afterCommit);
     const verifyToken = tokenVerifier(config);
+    const exchangeSession = config.neonAuth === undefined ? undefined : neonAuthSessionExchange(config.neonAuth);
     const backend = runtime.connect({ ontology, databaseUrl: config.databaseUrl });
     const connections = config.connections ??
         (config.localConnections === undefined
             ? deployedConnections(config)
             : localConnections(config.localConnections));
-    const routes = HttpApiBuilder.layer(built.api).pipe(Layer.provide(handlersLayer(built, hooks, connections)), Layer.provide([authenticationLayer(verifyToken), ErrorResponsesLive]), Layer.provide(backend));
-    const application = Layer.mergeAll(routes, UnmatchedRoutes).pipe(Layer.provide(HttpServer.layerServices));
+    const routes = HttpApiBuilder.layer(built.api).pipe(Layer.provide(handlersLayer(built, hooks, connections)), Layer.provide([authenticationLayer(verifyToken, exchangeSession), ErrorResponsesLive]), Layer.provide(backend));
+    const application = Layer.mergeAll(routes, DocsRoute, UnmatchedRoutes).pipe(Layer.provide(HttpServer.layerServices));
     const web = HttpRouter.toWebHandler(application, { disableLogger: true });
     const hash = ontology.manifest.hash;
     return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@segmentstream-cloud/ontology",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Define a SegmentStream workspace app's ontology: entities, relationships, roles and actions, written with Effect.",
   "license": "Apache-2.0",
   "author": "SegmentStream",