@segmentstream-cloud/ontology 0.7.0 → 0.9.0

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/handlers.js

@@ -1,6 +1,10 @@
 import { HttpServerResponse } from "effect/unstable/http";
 import { Effect, Layer, Schema } from "effect";
 import { HttpApiBuilder, OpenApi } from "effect/unstable/httpapi";
+import { editsFromWire, generatedResultFromWire, recordFromWire } from "../authoring-records.js";
+import { nameToWire } from "../authoring-names.js";
+import { principalFromWire } from "../authoring.js";
+import { toCamelCase } from "../names.js";
 import { PermissionDenied } from "../errors.js";
 import { missingPermission, permissionOf, READ_VERB } from "../permissions.js";
 import { EMAIL_PATTERN } from "../property.js";
@@ -141,26 +145,31 @@ function readEnvelope(request) {
  * The configured hook as `runAction` runs it after the commit. A failure is logged with the request
  * id here, so the action's caller still gets the committed result.
  */
-function afterCommitOf(hook, request) {
-    return (committed) => Effect.tryPromise(async () => hook({
-        entity: committed.entity,
-        action: committed.action,
-        principal: committed.principal,
-        input: request.input,
-        result: committed.result,
-        edits: committed.edits,
-        requestId: request.requestId,
-    })).pipe(Effect.catchCause((cause) => Effect.logError("ontology.after_commit.failed", cause).pipe(Effect.annotateLogs({
-        requestId: request.requestId,
-        action: `${committed.entity}.${committed.action}`,
-    }))));
+function afterCommitOf(hook, request, ontology) {
+    return (committed) => {
+        const definition = ontology.config.entities.find((entity) => nameToWire(entity.name) === committed.entity)?.definition;
+        return Effect.tryPromise(async () => hook({
+            entity: toCamelCase(committed.entity),
+            action: toCamelCase(committed.action),
+            principal: principalFromWire(committed.principal),
+            input: request.generated ? recordFromWire(committed.input, definition) : committed.input,
+            result: request.generated
+                ? generatedResultFromWire(committed.result, committed.action, definition)
+                : committed.result,
+            edits: editsFromWire(committed.edits, ontology.config.entities),
+            requestId: request.requestId,
+        })).pipe(Effect.catchCause((cause) => Effect.logError("ontology.after_commit.failed", cause).pipe(Effect.annotateLogs({
+            requestId: request.requestId,
+            action: `${committed.entity}.${committed.action}`,
+        }))));
+    };
 }
 /** The deployment's OIDC token: Vercel sets it on each request, and in the environment of builds. */
 function identityToken(request) {
     const header = request.headers[OIDC_TOKEN_HEADER];
     return typeof header === "string" && header !== "" ? header : process.env.VERCEL_OIDC_TOKEN;
 }
-function runAction(planned, { name }, hook, connections) {
+function runAction(planned, { name, generated }, ontology, hook, connections) {
     return ({ request }) => Effect.gen(function* () {
         const backend = yield* OntologyBackend;
         const principal = yield* CurrentPrincipal;
@@ -180,7 +189,7 @@ function runAction(planned, { name }, hook, connections) {
             }),
             ...(hook === undefined
                 ? {}
-                : { afterCommit: afterCommitOf(hook, { input: envelope.input, requestId }) }),
+                : { afterCommit: afterCommitOf(hook, { requestId, generated }, ontology) }),
         });
         const { issues } = outcome.validation;
         if (!outcome.validation.ok && !validateOnly) {
@@ -214,7 +223,7 @@ function entityHandlers(built, planned, hooks, targets, connections) {
             registered = registered.handle(`related.${traversal.name}`, (request) => traverse(planned, traversal, request, targets).pipe(Effect.provideService(OntologyBackend, backend)));
         }
         for (const action of planned.actions) {
-            const handler = runAction(planned, action, hooks.get(`${planned.name}.${action.name}`), connections);
+            const handler = runAction(planned, action, built.plan.ontology, hooks.get(`${planned.name}.${action.name}`), connections);
             registered = registered.handleRaw(`actions.${action.name}`, (request) => handler(request).pipe(Effect.provideService(OntologyBackend, backend)));
         }
         return registered;

package/dist/service/service.js

@@ -1,12 +1,14 @@
 import { Cause, Context, Effect, Layer } from "effect";
 import { HttpRouter, HttpServer, HttpServerError } from "effect/unstable/http";
 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. */
@@ -15,13 +17,19 @@ export const ONTOLOGY_HASH_HEADER = "x-ontology-hash";
 export const REQUEST_ID_HEADER = "x-request-id";
 function afterCommitHooks(plan, hooks = {}) {
     const actions = new Set(plan.entities.flatMap(({ name, actions: planned }) => planned.map((action) => `${name}.${action.name}`)));
-    const unknown = Object.keys(hooks).filter((key) => !actions.has(key));
+    const entries = Object.entries(hooks).map(([key, hook]) => [key.split(".").map(nameToWire).join("."), hook]);
+    const unknown = Object.keys(hooks).filter((key) => !actions.has(key.split(".").map(nameToWire).join(".")));
     if (unknown.length > 0) {
         throw new OntologyServiceConfigError({
             message: `afterCommit names actions the ontology does not have: ${unknown.join(", ")}.`,
         });
     }
-    return new Map(Object.entries(hooks));
+    if (new Set(entries.map(([key]) => key)).size !== entries.length) {
+        throw new OntologyServiceConfigError({
+            message: "afterCommit names collide after snake_case conversion.",
+        });
+    }
+    return new Map(entries);
 }
 /**
  * Requests that match no route, and defects that escape a route's own error handling, still get a
@@ -55,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/dist/user.d.ts

@@ -13,8 +13,8 @@ export declare const User: import("./entity.js").DraftEntity<"user", {
     readonly email: import("effect/Schema").optionalKey<import("./property.js").Property<string, false, true>>;
     readonly kind: import("./property.js").Property<"member" | "service", false, false>;
     readonly active: import("./property.js").Property<boolean, true, false>;
-    readonly identity_provider: import("effect/Schema").optionalKey<import("./property.js").Property<string, false, false>>;
-    readonly identity_subject: import("effect/Schema").optionalKey<import("./property.js").Property<string, false, false>>;
-    readonly last_sign_in_at: import("effect/Schema").optionalKey<import("./property.js").Property<string, false, false>>;
+    readonly identityProvider: import("effect/Schema").optionalKey<import("./property.js").Property<string, false, false>>;
+    readonly identitySubject: import("effect/Schema").optionalKey<import("./property.js").Property<string, false, false>>;
+    readonly lastSignInAt: import("effect/Schema").optionalKey<import("./property.js").Property<string, false, false>>;
 }, import("./entity.js").Relationships>;
 export type User = typeof User.Type;

package/dist/user.js

@@ -41,13 +41,13 @@ export const User = entity("user", {
             managed: true,
             description: "Inactive users cannot sign in or run actions.",
         }),
-        identity_provider: p.text({
+        identityProvider: p.text({
             renamedFrom: "identityProvider",
             optional: true,
             managed: true,
             description: "Who signs the member in, for example neon-auth. Empty for services.",
         }),
-        identity_subject: p.text({
+        identitySubject: p.text({
             renamedFrom: "identitySubject",
             optional: true,
             managed: true,
@@ -55,7 +55,7 @@ export const User = entity("user", {
         }),
         // Optional so that a table created before it gains the column without a backfill: a member
         // who has not signed in since simply has none.
-        last_sign_in_at: p.timestamp({
+        lastSignInAt: p.timestamp({
             renamedFrom: "lastSignInAt",
             optional: true,
             managed: true,
@@ -63,5 +63,5 @@ export const User = entity("user", {
             description: "When the member last signed in to the app. Empty until they do.",
         }),
     },
-    indexes: [{ properties: ["identity_provider", "identity_subject"], unique: true }],
+    indexes: [{ properties: ["identityProvider", "identitySubject"], unique: true }],
 });

package/package.json

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