@segmentstream-cloud/ontology 0.7.0 → 0.9.0

package/dist/entity.d.ts

@@ -3,7 +3,6 @@ import type { Measures } from "./measure.js";
 import type { WarehouseSource } from "./source.js";
 import type { Actions } from "./action.js";
 import type { Conflict, NotFound } from "./errors.js";
-import type { SystemProperty } from "./names.js";
 import { type AnyProperty } from "./property.js";
 import type { AnyRelationship, ManyRelationship, OneRelationship } from "./relationship.js";
 import { OntologyReads, OntologyWrites, type FindOptions, type GetOptions, type UpsertResult } from "./runtime.js";
@@ -20,11 +19,11 @@ export interface SystemFields {
     /** A UUID. */
     readonly id: string;
     /** ISO 8601 timestamps. */
-    readonly created_at: string;
-    readonly updated_at: string;
+    readonly createdAt: string;
+    readonly updatedAt: string;
     /** The `user` who created or last updated the record; `null` when the platform wrote it. */
-    readonly created_by: string | null;
-    readonly updated_by: string | null;
+    readonly createdBy: string | null;
+    readonly updatedBy: string | null;
 }
 /** A record id, or a record. */
 export type RecordRef = string | {
@@ -58,9 +57,9 @@ type UniqueKeys<P> = {
     } ? K : never;
 }[keyof P] & string;
 type RelationshipIds<R> = {
-    readonly [K in OneKeys<R> as `${K}_id`]: R[K] extends OneRelationship<true> ? string | null : string;
+    readonly [K in OneKeys<R> as `${K}Id`]: R[K] extends OneRelationship<true> ? string | null : string;
 };
-/** A record of the entity: system fields, declared properties, and `<relationship>_id` per `rel.one`. */
+/** A record of the entity: system fields, declared properties, and `<relationship>Id` per `rel.one`. */
 export type EntityRecord<P, R> = Simplify<SystemFields & {
     readonly [K in keyof P]: ValueOf<P[K]>;
 } & RelationshipIds<R>>;
@@ -88,7 +87,7 @@ export type UpdateValues<P, R> = Simplify<{
     readonly [K in ManyKeys<R>]?: ReadonlyArray<string>;
 }>;
 /** Fields an index may cover: declared properties, system properties and `rel.one` relationships. */
-export type IndexField<P, R> = (keyof P & string) | SystemProperty | OneKeys<R>;
+export type IndexField<P, R> = (keyof P & string) | keyof SystemFields | OneKeys<R>;
 /** An index: the covered fields in order, or the fields with options. */
 export type IndexDefinition<Field extends string = string> = ReadonlyArray<Field> | {
     readonly properties: ReadonlyArray<Field>;

package/dist/entity.js

@@ -1,5 +1,7 @@
 import { Effect } from "effect";
 import { p } from "./property.js";
+import { recordFromWire, valuesToWire, findToWire } from "./authoring-records.js";
+import { toSnakeCase } from "./names.js";
 import { OntologyReads, OntologyWrites, } from "./runtime.js";
 export const EntityTypeId = Symbol.for("@segmentstream-cloud/ontology/Entity");
 function idOf(record) {
@@ -25,17 +27,38 @@ export function entity(name, definition) {
         relationships: definition.relationships ?? {},
         ref: p.ref(name),
         get: (record, options) => withReads((runtime) => runtime.get({
-            entity: name,
+            entity: toSnakeCase(name),
             id: idOf(record),
             ...(options?.forUpdate === true ? { forUpdate: true } : {}),
+        })).pipe(Effect.map((record) => recordFromWire(record, definition))),
+        find: (options) => withReads((runtime) => runtime.find({ entity: toSnakeCase(name), options: findToWire(options ?? {}, definition) })).pipe(Effect.map((records) => records.map((record) => recordFromWire(record, definition)))),
+        create: (values) => withWrites((runtime) => runtime.create({ entity: toSnakeCase(name), values: valuesToWire(values, definition) })).pipe(Effect.map((record) => recordFromWire(record, definition))),
+        update: (record, values) => withWrites((runtime) => runtime.update({
+            entity: toSnakeCase(name),
+            id: idOf(record),
+            values: valuesToWire(values, definition),
+        })).pipe(Effect.map((record) => recordFromWire(record, definition))),
+        upsertBy: (property, values) => withWrites((runtime) => runtime.upsertBy({
+            entity: toSnakeCase(name),
+            property: toSnakeCase(property),
+            values: valuesToWire(values, definition),
+        })).pipe(Effect.map((result) => ({
+            ...result,
+            record: recordFromWire(result.record, definition),
+        }))),
+        delete: (record) => withWrites((runtime) => runtime.delete({ entity: toSnakeCase(name), id: idOf(record) })),
+        link: (relationship, record, target) => withWrites((runtime) => runtime.link({
+            entity: toSnakeCase(name),
+            relationship: toSnakeCase(relationship),
+            id: idOf(record),
+            targetId: idOf(target),
+        })),
+        unlink: (relationship, record, target) => withWrites((runtime) => runtime.unlink({
+            entity: toSnakeCase(name),
+            relationship: toSnakeCase(relationship),
+            id: idOf(record),
+            targetId: idOf(target),
         })),
-        find: (options) => withReads((runtime) => runtime.find({ entity: name, options: options ?? {} })),
-        create: (values) => withWrites((runtime) => runtime.create({ entity: name, values })),
-        update: (record, values) => withWrites((runtime) => runtime.update({ entity: name, id: idOf(record), values })),
-        upsertBy: (property, values) => withWrites((runtime) => runtime.upsertBy({ entity: name, property, values })),
-        delete: (record) => withWrites((runtime) => runtime.delete({ entity: name, id: idOf(record) })),
-        link: (relationship, record, target) => withWrites((runtime) => runtime.link({ entity: name, relationship, id: idOf(record), targetId: idOf(target) })),
-        unlink: (relationship, record, target) => withWrites((runtime) => runtime.unlink({ entity: name, relationship, id: idOf(record), targetId: idOf(target) })),
     };
     // Every form of the entity shares `definition`, which is how defineOntology recognises them.
     const self = { ...handle, actions: {} };

package/dist/migrate/plan.js

@@ -1,4 +1,4 @@
-import { SNAKE_CASE_NAME, isSystemProperty } from "../names.js";
+import { SNAKE_CASE_NAME, isSystemProperty, toSnakeCase } from "../names.js";
 import { CATALOG_TABLE_DDL, MAX_IDENTIFIER_LENGTH, USER_TABLE, addConstraintStatement, columnDefinition, constraintDefinition, createEnumStatement, createIndexStatement, createTableStatement, defaultExpression, entityStorage, enumTypeName, fieldColumnName, joinTable, propertyCheck, propertyColumn, propertyEnum, quoteIdentifier, quoteLiteral, relationshipColumn, RUNTIME_TABLES_DDL, relationshipForeignKey, SYSTEM_COLUMNS, tableName, } from "./storage.js";
 const GLOBAL_KINDS = new Set(["table", "type", "index"]);
 function step(input) {
@@ -296,9 +296,10 @@ function matchProperties(current, target) {
     const addedProperties = [];
     for (const property of target.properties) {
         const sameName = byName.get(property.name);
-        const previous = property.renamedFrom !== undefined && !claimed.has(property.renamedFrom)
-            ? byName.get(property.renamedFrom)
-            : undefined;
+        const source = property.renamedFrom === undefined
+            ? undefined
+            : (byName.get(property.renamedFrom) ?? byName.get(toSnakeCase(property.renamedFrom)));
+        const previous = source !== undefined && !claimed.has(source.name) ? source : undefined;
         const match = sameName ?? previous;
         if (match === undefined) {
             addedProperties.push(property);

package/dist/names.d.ts

@@ -1,12 +1,15 @@
 /** Ontology names: lowercase snake_case. */
 export declare const SNAKE_CASE_NAME: RegExp;
+/** Convert each character once, including acronym boundaries such as HTTPClient. */
+export declare function toSnakeCase(name: string): string;
+export declare function toCamelCase(name: string): string;
 /** Historical property names accepted only as explicit rename sources. */
 export declare const LEGACY_MEMBER_NAME: RegExp;
 /** Stable entity identities, for example `ent_01J9Q4M8ZK`. */
 export declare const ENTITY_ID: RegExp;
 /** Properties every entity has. They are never declared and cannot be redeclared. */
 export declare const SYSTEM_PROPERTIES: readonly ["id", "created_at", "updated_at", "created_by", "updated_by"];
-export type SystemProperty = (typeof SYSTEM_PROPERTIES)[number];
+export type SystemProperty = "id" | "createdAt" | "updatedAt" | "createdBy" | "updatedBy";
 /** Actions the platform generates for every entity; authored actions cannot use these names. */
 export declare const GENERATED_ACTIONS: readonly ["create", "update", "delete", "link", "unlink"];
 /** Prefix of the generated `upsert_by_<property>` actions. */
@@ -18,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

@@ -1,5 +1,31 @@
 /** Ontology names: lowercase snake_case. */
 export const SNAKE_CASE_NAME = /^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$/;
+/** TypeScript names are converted only at the ontology's serialization boundary. */
+function isUppercase(letter) {
+    return letter !== undefined && letter >= "A" && letter <= "Z";
+}
+function isLowercase(letter) {
+    return letter !== undefined && letter >= "a" && letter <= "z";
+}
+/** Convert each character once, including acronym boundaries such as HTTPClient. */
+export function toSnakeCase(name) {
+    const characters = [];
+    for (let index = 0; index < name.length; index++) {
+        const current = name[index];
+        const previous = name[index - 1];
+        const next = name[index + 1];
+        const followsWord = isLowercase(previous) || (previous !== undefined && previous >= "0" && previous <= "9");
+        const endsAcronym = isUppercase(previous) && isLowercase(next);
+        if (isUppercase(current) && (followsWord || endsAcronym)) {
+            characters.push("_");
+        }
+        characters.push(current);
+    }
+    return characters.join("").toLowerCase();
+}
+export function toCamelCase(name) {
+    return name.replace(/_([a-z0-9])/g, (_, letter) => letter.toUpperCase());
+}
 /** Historical property names accepted only as explicit rename sources. */
 export const LEGACY_MEMBER_NAME = /^(?:[a-z][a-zA-Z0-9]*|[a-z][a-z0-9]*(?:_[a-z0-9]+)*)$/;
 /** Stable entity identities, for example `ent_01J9Q4M8ZK`. */
@@ -28,6 +54,7 @@ export const RESERVED_ENTITY_NAMES = [
     "status",
     "describe",
     "openapi",
+    "docs",
     "mcp",
     "me",
 ];

package/dist/permissions.js

@@ -1,4 +1,4 @@
-import { GENERATED_UPSERT_PREFIX } from "./names.js";
+import { GENERATED_UPSERT_PREFIX, toSnakeCase } from "./names.js";
 /**
  * Permissions are `<entity>:<verb>` strings. The verbs are `read`, the generated `create`, `update`,
  * `delete`, `link` and `unlink`, and the snake_case name of an authored action. A role may use `*` for
@@ -12,7 +12,7 @@ export const READ_VERB = "read";
 /** What the built-in `member` role holds when `defineOntology` does not say: reading everything. */
 export const DEFAULT_MEMBER_PERMISSIONS = [`${WILDCARD}:${READ_VERB}`];
 /** `<entity>:<verb>` with lowercase snake_case entities and lowercase snake_case verbs, or `*` for either. */
-const PERMISSION = /^(\*|[a-z][a-z0-9]*(?:_[a-z0-9]+)*):(\*|[a-z][a-z0-9]*(?:_[a-z0-9]+)*)$/;
+const PERMISSION = /^(\*|[a-z][a-zA-Z0-9]*(?:_[a-z0-9]+)*):(\*|[a-z][a-zA-Z0-9]*(?:_[a-z0-9]+)*)$/;
 /** The entity and verb of a permission, or `undefined` when the value is not one. */
 export function parsePermission(value) {
     if (typeof value !== "string") {
@@ -32,8 +32,8 @@ export function grants(granted, required) {
     if (held === undefined || wanted === undefined) {
         return false;
     }
-    return ((held.entity === WILDCARD || held.entity === wanted.entity) &&
-        (held.verb === WILDCARD || held.verb === wanted.verb));
+    return ((held.entity === WILDCARD || toSnakeCase(held.entity) === toSnakeCase(wanted.entity)) &&
+        (held.verb === WILDCARD || toSnakeCase(held.verb) === toSnakeCase(wanted.verb)));
 }
 /**
  * Whether the principal may do what `required` names: one of its permissions equals it, or covers it
@@ -51,7 +51,7 @@ export function missingPermission(required, principal) {
  * create or update and so requires both `<entity>:create` and `<entity>:update`.
  */
 export function generatedActionPermissions(entity, action) {
-    return action.startsWith(GENERATED_UPSERT_PREFIX)
+    return toSnakeCase(action).startsWith(GENERATED_UPSERT_PREFIX)
         ? [permissionOf(entity, "create"), permissionOf(entity, "update")]
         : [permissionOf(entity, action)];
 }

package/dist/property.js

@@ -1,5 +1,6 @@
 import { Schema } from "effect";
 import { humanize } from "./names.js";
+import { nameToWire } from "./authoring-names.js";
 /** The closed set of storage types. Each has a known column, JSON Schema, filters and rendering. */
 export const PROPERTY_TYPES = [
     "text",
@@ -171,7 +172,7 @@ function ref(target, options) {
         ...(settings.label !== undefined ? { title: settings.label } : {}),
         description: settings.description ?? `The id of a ${entityName} record.`,
         format: "uuid",
-        [REFERENCE_ANNOTATION]: entityName,
+        [REFERENCE_ANNOTATION]: nameToWire(entityName),
     }).check(Schema.isPattern(UUID));
     return (settings.optional === true ? Schema.optionalKey(schema) : schema);
 }

package/dist/runtime/generated-actions.js

@@ -5,7 +5,6 @@ import { generatedActionPermissions } from "../permissions.js";
 import { p, REFERENCE_ANNOTATION } from "../property.js";
 import { isCalendarDate, isInstant } from "../query.js";
 import { OntologyWrites } from "../runtime.js";
-import { User } from "../user.js";
 import { entityModel, ontologyModel, propertyValueSchema, } from "./model.js";
 /** Generated actions, built once per ontology and entity. */
 const builtActions = new WeakMap();
@@ -98,7 +97,7 @@ export function generatedActions(ontology, entityName) {
 }
 function buildGeneratedActions(ontology, entityName) {
     const entity = entityModel(ontologyModel(ontology), entityName);
-    if (entity.resolved.entity.definition === User.definition) {
+    if (entity.resolved.builtIn) {
         return {};
     }
     const label = entity.label.toLowerCase();

package/dist/runtime/principals.js

@@ -6,7 +6,7 @@ import { SqlClient } from "effect/unstable/sql";
 import { isSqlError } from "effect/unstable/sql/SqlError";
 import { entity, } from "../entity.js";
 import { API_KEYS_TABLE, USER_ROLES_TABLE, USER_TABLE } from "../migrate/storage.js";
-import { MEMBER_ROLE } from "../names.js";
+import { MEMBER_ROLE, toSnakeCase } from "../names.js";
 import { buildOntology } from "../ontology.js";
 import { permissionsOf } from "../permissions.js";
 import { EMAIL_PATTERN } from "../property.js";
@@ -318,7 +318,7 @@ function deployedUser(manifest) {
         return User;
     }
     const names = new Set(deployed.properties.map((property) => property.name));
-    const kept = Object.entries(User.definition.properties).filter(([name, property]) => names.has(name) ||
+    const kept = Object.entries(User.definition.properties).filter(([name, property]) => names.has(toSnakeCase(name)) ||
         (propertyDefinition(property)?.renamedFrom !== undefined &&
             names.has(propertyDefinition(property).renamedFrom)));
     if (kept.length === Object.keys(User.definition.properties).length) {

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/config.d.ts

@@ -48,7 +48,7 @@ export interface ActionCommitted {
     readonly entity: string;
     readonly action: string;
     readonly principal: Principal;
-    /** The input as the caller sent it. */
+    /** The decoded input, using the authored TypeScript schema. */
     readonly input: unknown;
     readonly result: unknown;
     readonly edits: ReadonlyArray<unknown>;

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>;