@segmentstream-cloud/ontology 0.8.0 → 0.10.0

package/dist/property.js

@@ -1,5 +1,6 @@
 import { Schema } from "effect";
 import { humanize } from "./names.js";
+import { BlobValue, MAX_BLOB_BYTES } from "./blob.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 = [
@@ -13,6 +14,7 @@ export const PROPERTY_TYPES = [
     "timestamp",
     "select",
     "json",
+    "blob",
 ];
 /** Schema annotation that carries a property's storage metadata. */
 export const PROPERTY_ANNOTATION = "segmentstream/ontology/property";
@@ -47,6 +49,8 @@ function construct({ type, base, options, checks = [], format, selectOptions, })
         ...(options.min !== undefined ? { min: options.min } : {}),
         ...(options.max !== undefined ? { max: options.max } : {}),
         ...(options.maxLength !== undefined ? { maxLength: options.maxLength } : {}),
+        ...(options.accept !== undefined ? { accept: options.accept } : {}),
+        ...(options.maxBytes !== undefined ? { maxBytes: options.maxBytes } : {}),
         ...(selectOptions !== undefined ? { options: selectOptions } : {}),
     };
     // Annotations go on the base node, before the checks, so that the JSON Schema keeps them at the top
@@ -176,7 +180,13 @@ function ref(target, options) {
     }).check(Schema.isPattern(UUID));
     return (settings.optional === true ? Schema.optionalKey(schema) : schema);
 }
-/** Property constructors. */
+function blob(options) {
+    return construct({
+        type: "blob",
+        base: BlobValue,
+        options: { ...options, maxBytes: options.maxBytes ?? MAX_BLOB_BYTES },
+    });
+}
 export const p = {
     text,
     email,
@@ -188,6 +198,7 @@ export const p = {
     timestamp,
     select,
     json,
+    blob,
     ref,
 };
 function findAnnotation(ast, key) {

package/dist/query.js

@@ -1,5 +1,6 @@
 import { Schema } from "effect";
 import { wireStruct } from "./wire.js";
+import { BlobValue } from "./blob.js";
 /**
  * The query language of `find` and of the HTTP API's list and query endpoints.
  *
@@ -194,12 +195,13 @@ export function fieldValueSchema(field) {
         case "json":
             return JsonValue;
         case "uuid":
+        case "blob":
             return UuidValue;
     }
 }
 /** Fields a query can sort on: every field but `json` properties. */
 export function isOrderable(field) {
-    return field.storage !== "json";
+    return field.storage !== "json" && field.storage !== "blob";
 }
 const FILTER_IDENTIFIERS = {
     text: "TextFilter",
@@ -212,6 +214,7 @@ const FILTER_IDENTIFIERS = {
     timestamp: "TimestampFilter",
     json: "JsonFilter",
     uuid: "IdFilter",
+    blob: "IdFilter",
 };
 const FILTER_DESCRIPTIONS = {
     TextFilter: "contains and startsWith ignore case.",
@@ -413,6 +416,8 @@ function recordValueSchema(field) {
                 return Schema.Literals(field.options ?? []);
             case "json":
                 return Schema.Json;
+            case "blob":
+                return BlobValue;
             default:
                 return Schema.String;
         }

package/dist/runtime/generated-actions.js

@@ -1,4 +1,5 @@
 import { Effect, Schema } from "effect";
+import { uploadInput, BLOB_UPLOAD_ANNOTATION } from "../blob.js";
 import { action } from "../action.js";
 import { GENERATED_UPSERT_PREFIX } from "../names.js";
 import { generatedActionPermissions } from "../permissions.js";
@@ -16,7 +17,10 @@ export function upsertActionName(property) {
     return `${GENERATED_UPSERT_PREFIX}${property}`;
 }
 /** A property's value schema, refusing days that do not exist, which PostgreSQL would reject. */
-function propertyInput(field) {
+function propertyInput(field, entity) {
+    if (field.storage === "blob") {
+        return uploadInput(entity.name, field.name);
+    }
     const schema = propertyValueSchema(field.property);
     if (field.storage === "date") {
         return schema.check(Schema.makeFilter((value) => isCalendarDate(value) || "Expected a date that exists"));
@@ -44,7 +48,7 @@ function valueFields(entity, { mode }) {
         if (mode === "update" && definition?.managed === true) {
             continue;
         }
-        const value = propertyInput(field);
+        const value = propertyInput(field, entity);
         const required = mode === "create" &&
             !field.nullable &&
             !(definition !== undefined && "default" in definition);
@@ -164,7 +168,7 @@ function buildGeneratedActions(ontology, entityName) {
 }
 function inputJsonSchema(input) {
     const document = Schema.toJsonSchemaDocument(input, {
-        includeAnnotationKey: (key) => key === REFERENCE_ANNOTATION,
+        includeAnnotationKey: (key) => key === REFERENCE_ANNOTATION || key === BLOB_UPLOAD_ANNOTATION,
         onExcessProperty: "error",
     });
     const schema = document.schema;

package/dist/runtime/history.d.ts

@@ -57,6 +57,9 @@ export interface HistoryScope {
     readonly action: string;
     readonly actionId: string;
     readonly principalId: string | null;
+    readonly branchId?: string;
+    readonly blobActionKey?: string;
+    readonly createIntent?: string;
 }
 /** `INSERT` of one history row; `at` is the transaction's time, shared by the whole action. */
 export declare function insertHistory(scope: HistoryScope, write: HistoryWrite, params: Params): string;

package/dist/runtime/pipeline.d.ts

@@ -32,7 +32,10 @@ export interface ActionRequest<R = never> {
     readonly options?: {
         /** Decode the input and check the permission, without running `prepare` or the handler. */
         readonly validateOnly?: boolean;
+        readonly idempotencyKey?: string;
+        readonly createIntent?: string;
     };
+    readonly branchId?: string;
     readonly afterCommit?: ReadonlyArray<AfterCommit<R>>;
     /** The request's id, which `prepare` and the handler receive for logs; the action id by default. */
     readonly requestId?: string;
@@ -96,7 +99,8 @@ export declare function findAction(ontology: Ontology, entityName: string, actio
  * 1. decode the input with the action's schema; issues are returned, not raised;
  * 2. check that the principal's permissions cover the action's (PermissionDenied);
  * 3. with `validateOnly`, stop;
- * 4. run `prepare`, when the action has one, without a transaction: reads and the declared
+ * 4. reauthorize and replay a committed blob action, if its idempotency key matches;
+ *    otherwise run `prepare`, when the action has one, without a transaction: reads and the declared
  *    connections only, under {@link PREPARE_TIMEOUT};
  * 5. without a handler, answer with what `prepare` returned;
  * 6. open one transaction and run the handler with what `prepare` returned and the runtime, which

package/dist/runtime/pipeline.js

@@ -1,7 +1,10 @@
-import { randomUUID } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { Cause, Duration, Effect, Option, Schema } from "effect";
 import { SqlClient } from "effect/unstable/sql";
 import { isSqlError } from "effect/unstable/sql/SqlError";
+import { canonicalJson } from "../manifest.js";
+import { Conflict } from "../errors.js";
+import { authorizeBlobOperation } from "../storage/authorization.js";
 import { ConnectionError, ConnectionTransport, connectionContext } from "../connection.js";
 import { PermissionDenied } from "../errors.js";
 import { generatedActionPermissions, missingPermission } from "../permissions.js";
@@ -61,7 +64,8 @@ const NO_CONNECTIONS = {
  * 1. decode the input with the action's schema; issues are returned, not raised;
  * 2. check that the principal's permissions cover the action's (PermissionDenied);
  * 3. with `validateOnly`, stop;
- * 4. run `prepare`, when the action has one, without a transaction: reads and the declared
+ * 4. reauthorize and replay a committed blob action, if its idempotency key matches;
+ *    otherwise run `prepare`, when the action has one, without a transaction: reads and the declared
  *    connections only, under {@link PREPARE_TIMEOUT};
  * 5. without a handler, answer with what `prepare` returned;
  * 6. open one transaction and run the handler with what `prepare` returned and the runtime, which
@@ -107,6 +111,50 @@ export function runAction(ontology, request) {
         const actionId = randomUUID();
         const requestId = request.requestId ?? actionId;
         const context = { input: decoded.value, principal: request.principal, requestId };
+        const hasUploads = (value) => typeof value === "object" &&
+            value !== null &&
+            ("uploadId" in value || Object.values(value).some(hasUploads));
+        const key = request.options?.idempotencyKey;
+        const hasBlobProperties = ontology.manifest.entities.some((entity) => entity.properties.some((property) => property.type === "blob"));
+        const consumesUpload = action.transactional && hasBlobProperties && (hasUploads(decoded.value) || key !== undefined);
+        if (consumesUpload && (!key || key.length > 128 || !request.branchId)) {
+            return yield* new Conflict({
+                entity: request.entity,
+                message: "Upload actions require an idempotency key.",
+            });
+        }
+        const fingerprint = consumesUpload
+            ? createHash("sha256")
+                .update(canonicalJson({
+                qualified,
+                manifestHash: ontology.manifest.hash,
+                branchId: request.branchId ?? null,
+                input: request.input,
+                createIntent: request.options?.createIntent ?? null,
+            }))
+                .digest("hex")
+            : undefined;
+        // A committed retry must not depend on preparation's external services being available.
+        // The handler transaction below still locks and rechecks the key for concurrent requests.
+        if (consumesUpload) {
+            const saved = yield* sql
+                .withTransaction(Effect.gen(function* () {
+                yield* authorizeBlobOperation(ontology, sql, request.principal.id, found.permissions);
+                const [saved] = yield* sql.unsafe(`SELECT fingerprint, outcome FROM "_blob_action_results"
+               WHERE principal_id = $1::uuid AND key = $2`, [request.principal.id, key]);
+                if (saved && saved.fingerprint !== fingerprint) {
+                    return yield* new Conflict({
+                        entity: request.entity,
+                        message: "Idempotency key was used for another action.",
+                    });
+                }
+                return saved?.outcome;
+            }))
+                .pipe(Effect.catchIf(isSqlError, (error) => Effect.die(error)));
+            if (saved) {
+                return saved;
+            }
+        }
         const prepared = action.prepare === undefined
             ? undefined
             : yield* prepare(ontology, sql, action, context, request.connections, qualified);
@@ -118,13 +166,49 @@ export function runAction(ontology, request) {
             action: qualified,
             actionId,
             principalId: request.principal.id,
+            ...(key ? { blobActionKey: key } : {}),
+            ...(request.branchId ? { branchId: request.branchId } : {}),
+            ...(request.options?.createIntent ? { createIntent: request.options.createIntent } : {}),
             onEdit: (edit) => edits.push(edit),
         });
         const handle = action.handler;
         const handler = Effect.suspend(() => handle({ ...context, prepared }));
+        let replay;
+        const transactionalHandler = Effect.gen(function* () {
+            if (consumesUpload) {
+                yield* authorizeBlobOperation(ontology, sql, request.principal.id, found.permissions);
+                yield* sql.unsafe(`INSERT INTO "_blob_action_results" (principal_id, key, fingerprint)
+          VALUES ($1::uuid, $2, $3) ON CONFLICT DO NOTHING`, [request.principal.id, key, fingerprint]);
+                const [saved] = yield* sql.unsafe(`SELECT fingerprint, outcome FROM "_blob_action_results" WHERE principal_id = $1::uuid AND key = $2
+           FOR UPDATE`, [request.principal.id, key]);
+                if (saved.fingerprint !== fingerprint) {
+                    return yield* new Conflict({
+                        entity: request.entity,
+                        message: "Idempotency key was used for another action.",
+                    });
+                }
+                if (saved.outcome) {
+                    replay = saved.outcome;
+                    return replay.result;
+                }
+            }
+            const result = yield* handler.pipe(OntologyRuntime.provide(runtime));
+            if (consumesUpload) {
+                yield* sql.unsafe(`UPDATE "_blob_action_results" SET outcome = $1::jsonb
+          WHERE principal_id = $2::uuid AND key = $3`, [
+                    JSON.stringify({ result: result ?? null, validation: VALID, edits }),
+                    request.principal.id,
+                    key,
+                ]);
+            }
+            return result;
+        });
         const result = yield* sql
-            .withTransaction(handler.pipe(OntologyRuntime.provide(runtime)))
+            .withTransaction(transactionalHandler)
             .pipe(Effect.catchIf(isSqlError, (error) => Effect.die(error)));
+        if (replay) {
+            return replay;
+        }
         const committed = {
             entity: request.entity,
             action: request.action,

package/dist/runtime/records.js

@@ -12,6 +12,11 @@ import { validate } from "./validation.js";
  */
 function readExpression(field, column) {
     switch (field.storage) {
+        case "blob":
+            return (`(SELECT json_build_object('id', b.id::text, 'filename', b.filename, ` +
+                `'contentType', b.content_type, 'size', b.size, 'createdAt', ` +
+                `to_char(b.created_at AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"'))::text ` +
+                `FROM "_blobs" b WHERE b.id = ${column})`);
         case "timestamp":
             return `to_char(${column} AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS.US"Z"')`;
         case "date":
@@ -42,6 +47,7 @@ function readValue(field, value) {
     switch (field.storage) {
         case "integer":
             return Number(value);
+        case "blob":
         case "json":
             return typeof value === "string" ? JSON.parse(value) : value;
         case "timestamp":
@@ -76,6 +82,9 @@ export function bindValue(field, value) {
     if (value === null) {
         return null;
     }
+    if (field.storage === "blob") {
+        return typeof value === "string" ? value : value.id;
+    }
     return field.storage === "json" ? JSON.stringify(value) : value;
 }
 function propertyIssue(field, value) {

package/dist/runtime/service-binding.d.ts

@@ -1,10 +1,11 @@
 import { Layer, Redacted } from "effect";
 import { SqlClient } from "effect/unstable/sql";
 import type { SqlError } from "effect/unstable/sql/SqlError";
+import type { BlobStorageBinding } from "../storage/provider.js";
 import type { Ontology } from "../ontology.js";
 import { OntologyBackend, type OntologyServiceRuntime } from "../service/runtime-contract.js";
 /** The service's backend on the runtime, over the SQL client in context. */
-export declare function backendLayer(ontology: Ontology): Layer.Layer<OntologyBackend, never, SqlClient.SqlClient>;
+export declare function backendLayer(ontology: Ontology, blobStorage?: Redacted.Redacted<BlobStorageBinding>): Layer.Layer<OntologyBackend, never, SqlClient.SqlClient>;
 /**
  * `@effect/sql-pg` on the pooled `ontology_app` connection string, with the TLS server name a
  * Neon endpoint needs.

package/dist/runtime/service-binding.js

@@ -1,6 +1,9 @@
 import * as PgClient from "@effect/sql-pg/PgClient";
 import { Effect, Layer, Redacted } from "effect";
 import { SqlClient } from "effect/unstable/sql";
+import { neonBlobProvider } from "../storage/neon.js";
+import { maintainBlobStorage } from "../storage/maintenance.js";
+import { blobRuntime } from "../storage/sessions.js";
 import { readCatalog } from "../migrate/apply.js";
 import { NotInvited, OntologyBackend, } from "../service/runtime-contract.js";
 import { generatedActions } from "./generated-actions.js";
@@ -18,18 +21,26 @@ function rejectedAs(operation) {
     return (rejection) => Effect.logWarning("ontology.principal.rejected").pipe(Effect.annotateLogs({ operation, reason: rejection.reason }), Effect.as(undefined));
 }
 /** The service's backend on the runtime, over the SQL client in context. */
-export function backendLayer(ontology) {
+export function backendLayer(ontology, blobStorage) {
     return Layer.effect(OntologyBackend, Effect.gen(function* () {
         const sql = yield* SqlClient.SqlClient;
         const runtime = makeOntologyRuntime(ontology, sql);
         const withSql = (effect) => Effect.provideService(effect, SqlClient.SqlClient, sql);
+        const binding = blobStorage ? Redacted.value(blobStorage) : undefined;
+        const provider = binding
+            ? yield* Effect.acquireRelease(Effect.sync(() => neonBlobProvider(binding)), (provider) => Effect.sync(() => provider.close?.()))
+            : undefined;
+        const blobs = provider ? blobRuntime(ontology, sql, provider) : undefined;
         return OntologyBackend.of({
+            ...(blobs ? { blobs } : {}),
+            ...(provider ? { maintainBlobs: maintainBlobStorage(sql, provider) } : {}),
             runAction: (input) => withSql(runAction(ontology, {
                 entity: input.entity,
                 action: input.action,
                 input: input.input,
                 principal: input.principal,
                 options: input.options,
+                ...(binding ? { branchId: binding.branchId } : {}),
                 afterCommit: input.afterCommit === undefined ? [] : [input.afterCommit],
                 ...(input.requestId === undefined ? {} : { requestId: input.requestId }),
                 ...(input.connections === undefined ? {} : { connections: input.connections }),
@@ -66,5 +77,5 @@ export function postgresLayer(databaseUrl) {
 /** The default runtime of `createOntologyService`: the SQL runtime on the workspace database. */
 export const sqlServiceRuntime = {
     generatedActions: (entity, ontology) => generatedActions(ontology, entity.name),
-    connect: ({ ontology, databaseUrl }) => backendLayer(ontology).pipe(Layer.provide(postgresLayer(databaseUrl))),
+    connect: ({ ontology, databaseUrl, blobStorage }) => backendLayer(ontology, blobStorage).pipe(Layer.provide(postgresLayer(databaseUrl))),
 };

package/dist/runtime/writes.js

@@ -1,4 +1,5 @@
 import { Effect } from "effect";
+import { resolveBlobWrites } from "../storage/writes.js";
 import { Conflict } from "../errors.js";
 import { quoteIdentifier } from "../migrate/storage.js";
 import { InvalidValues } from "./errors.js";
@@ -21,7 +22,9 @@ function requireReferences(context, references) {
 }
 function insertRecord(context, entity, values, onConflict) {
     return Effect.gen(function* () {
-        const write = yield* prepareWrite(entity, values, "create");
+        const recordId = uuidv7();
+        const resolved = yield* resolveBlobWrites(context, entity, recordId, values, true);
+        const write = yield* prepareWrite(entity, resolved, "create");
         yield* requireReferences(context, write.references);
         const params = new Params();
         const principal = params.add(context.scope.principalId, "uuid");
@@ -34,7 +37,7 @@ function insertRecord(context, entity, values, onConflict) {
             ...write.columns.map(({ field }) => quoteIdentifier(field.column)),
         ];
         const placeholders = [
-            params.add(uuidv7(), "uuid"),
+            params.add(recordId, "uuid"),
             "now()",
             "now()",
             principal,
@@ -64,11 +67,12 @@ export function createRecord(context, entity, values) {
 }
 export function updateRecord(context, entity, id, values) {
     return Effect.gen(function* () {
-        const write = yield* prepareWrite(entity, values, "update");
         const before = yield* loadRecord(context, entity, id, "update");
         if (before === undefined) {
             return yield* notFound(entity, id);
         }
+        const resolved = yield* resolveBlobWrites(context, entity, id, values, false);
+        const write = yield* prepareWrite(entity, resolved, "update");
         yield* requireReferences(context, write.references);
         let after = before;
         if (write.columns.length > 0) {
@@ -121,6 +125,16 @@ export function upsertRecord(context, entity, property, values) {
                 issues: [{ path: [property], message: `${property} is required` }],
             }));
         }
+        // A file ticket for an existing record must not be consumed by a speculative INSERT.
+        if (entity.fields.some((candidate) => candidate.storage === "blob" && values[candidate.name] != null)) {
+            const lookup = new Params();
+            const [existing] = yield* context.run(`SELECT id::text AS id FROM ${quoteIdentifier(entity.table)}
+        WHERE ${quoteIdentifier(field.column)} = ${lookup.add(bindValue(field, key), field.sqlType)} FOR UPDATE`, lookup);
+            if (existing) {
+                const record = yield* updateRecord(context, entity, existing.id, values);
+                return { record, created: false };
+            }
+        }
         const created = yield* insertRecord(context, entity, values, ` ON CONFLICT (${quoteIdentifier(field.column)}) DO NOTHING`);
         if (created !== undefined) {
             return { record: created, created: true };

package/dist/service/api.js

@@ -1,5 +1,7 @@
 import { Effect, Layer, Schema } from "effect";
 import { HttpApi, HttpApiEndpoint, HttpApiGroup, HttpApiMiddleware, HttpApiSchema, OpenApi, } from "effect/unstable/httpapi";
+import { storageGroup } from "../storage/api.js";
+import { DownloadRequest, TransferGrant } from "../storage/sessions.js";
 import { permissionOf, READ_VERB } from "../permissions.js";
 import { generatedActions } from "../runtime/generated-actions.js";
 import { Authentication } from "./authentication.js";
@@ -121,6 +123,14 @@ function entityGroup(planned, schemas, names) {
             error: recordErrors,
         }), `History of a ${definition.label.toLowerCase()}`, `What each action changed on the record, newest first. ${read}`),
         ...planned.traversals.map((traversal) => traversalEndpoint(planned, traversal, schemas.get(traversal.target), names.get(traversal.target) ?? { label: traversal.target, plural: traversal.target })),
+        ...planned.resolved.properties
+            .filter((property) => property.definition.type === "blob")
+            .map((property) => documented(HttpApiEndpoint.post(`blobs.${property.name}`, `${base}/:id/blobs/${property.name}/download`, {
+            params: { id: IdParam },
+            payload: DownloadRequest,
+            success: TransferGrant,
+            error: recordErrors,
+        }), `Download ${property.name}`, `Requires ${planned.name}:read. Historical revisions must belong to this record and field.`)),
         ...planned.actions.map((action) => actionEndpoint(planned, action)),
     ];
     const [first, ...rest] = endpoints.map(authenticated);
@@ -172,6 +182,11 @@ export function buildApi(plan) {
     ]));
     const groups = [
         serviceGroup(),
+        ...(plan.ontology.manifest.entities.some((entity) => entity.properties.some((property) => property.type === "blob"))
+            ? [
+                storageGroup(authenticated, actionErrors, (endpoint) => endpoint.middleware(ErrorResponses)),
+            ]
+            : []),
         ...plan.entities.map((planned) => entityGroup(planned, schemas, names)),
     ];
     const api = HttpApi.make("ontology")

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