@segmentstream/ontology 0.0.0-stage → 0.92.0

package/dist/service/api.js

@@ -0,0 +1,288 @@
+import { Effect, Layer, Schema } from "effect";
+import { HttpApi, HttpApiEndpoint, HttpApiGroup, HttpApiMiddleware, HttpApiSchema, OpenApi, } from "effect/unstable/httpapi";
+import { EARLIER_QUERY_METRICS_ROUTE } from "../legacy.js";
+import { QUERY_METRICS_ROUTE } from "../names.js";
+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";
+import { actionDescription, requires } from "./descriptions.js";
+import { InvalidRequestBody, RequestId, failureResponse } from "./errors.js";
+import { planApi, } from "./plan.js";
+import { ActionResponse, MetricQueryBody, MetricQueryResult, EntityMetricQueryBody, AsParams, Catalog, ErrorSchemas, Graph, HistoryPage, HistoryParams, IdParam, WarehouseIdParam, Me, SignInCheckRequest, SignInCheckResult, Status, actionRequest, entitySchemas, } from "./schemas.js";
+/** The path every ontology route lives under. */
+export const BASE_PATH = "/api/ontology";
+/** The group of the global routes. Entity names are snake_case, so it cannot clash with one. */
+export const SERVICE_GROUP = "Ontology";
+/**
+ * Maps every failure of a route, including input that fails its schema, to the service's error
+ * responses. It runs inside {@link Authentication}, so unauthenticated requests never reach it.
+ */
+export class ErrorResponses extends HttpApiMiddleware.Service()("@segmentstream/ontology/ErrorResponses", {
+    error: [ErrorSchemas.invalidRequest, ErrorSchemas.internal],
+}) {
+}
+export const ErrorResponsesLive = Layer.succeed(ErrorResponses)((httpEffect) => Effect.gen(function* () {
+    const requestId = yield* RequestId;
+    return yield* httpEffect.pipe(
+    // HttpApi answers a body it cannot decode with a plain-text 415.
+    Effect.flatMap((response) => response.status === 415
+        ? Effect.fail(new InvalidRequestBody({ reason: "unsupported_media_type", issues: [] }))
+        : Effect.succeed(response)), Effect.catchCause((cause) => failureResponse(cause, requestId)));
+}));
+function authenticated(endpoint) {
+    return endpoint.middleware(ErrorResponses).middleware(Authentication);
+}
+function documented(endpoint, summary, description) {
+    return endpoint.annotateMerge(OpenApi.annotations({ summary, ...(description !== undefined ? { description } : {}) }));
+}
+const serviceErrors = [ErrorSchemas.invalidRequest, ErrorSchemas.internal];
+const readErrors = [
+    ErrorSchemas.invalidRequest,
+    ErrorSchemas.forbidden,
+    ErrorSchemas.internal,
+    ErrorSchemas.warehouseReadUnavailable,
+    ErrorSchemas.rateLimited,
+];
+const recordErrors = [
+    ErrorSchemas.invalidRequest,
+    ErrorSchemas.forbidden,
+    ErrorSchemas.notFound,
+    ErrorSchemas.internal,
+    ErrorSchemas.warehouseReadUnavailable,
+    ErrorSchemas.rateLimited,
+];
+const actionErrors = [
+    ErrorSchemas.invalidRequest,
+    ErrorSchemas.forbidden,
+    ErrorSchemas.notFound,
+    ErrorSchemas.conflict,
+    ErrorSchemas.unsupportedMediaType,
+    ErrorSchemas.unprocessable,
+    ErrorSchemas.internal,
+];
+/**
+ * The facade's own refusals. SegmentStream's answers, success and errors alike, pass through as it
+ * sent them: its errors are `{ error, detail, requestId, retryable }`.
+ */
+const metricQueryErrors = [
+    ErrorSchemas.invalidRequest,
+    ErrorSchemas.invalidMetricQuery,
+    ErrorSchemas.readForbidden,
+    ErrorSchemas.unsupportedMediaType,
+    ErrorSchemas.rateLimited,
+    ErrorSchemas.internal,
+    ErrorSchemas.metricQueryUpstreamUnavailable,
+    ErrorSchemas.metricQueriesUnavailable,
+];
+/** An action that calls connections also answers for the connections it could not use. */
+const connectionActionErrors = [
+    ...actionErrors,
+    ErrorSchemas.connectionRequired,
+    ErrorSchemas.connectionResponseInvalid,
+    ErrorSchemas.connectionUnavailable,
+];
+function readPermission(entity) {
+    return permissionOf(entity, READ_VERB);
+}
+/** Whether an entity declares metrics, and so has `POST /api/ontology/<entity>/query_metrics`. */
+export function hasMetrics(planned) {
+    return Object.keys(planned.resolved.entity.definition.metrics ?? {}).length > 0;
+}
+/** The name of the metric query endpoints at their current paths, in the service and entity groups. */
+export const QUERY_METRICS_ENDPOINT = "queryMetrics";
+/**
+ * A metric query route, `<base>/query_metrics`, and the same route at its earlier path,
+ * `<base>/aggregate`, which older app SDKs call: one request and answer, the earlier deprecated.
+ */
+function metricQueryEndpoints(input) {
+    const { base, payload, summary, description } = input;
+    const endpoint = (name, route) => HttpApiEndpoint.post(name, `${base}/${route}`, {
+        payload,
+        success: MetricQueryResult,
+        error: metricQueryErrors,
+    });
+    return [
+        documented(endpoint(QUERY_METRICS_ENDPOINT, QUERY_METRICS_ROUTE), summary, description),
+        documented(
+        // @legacy ontology.metric-earlier-names
+        endpoint(EARLIER_QUERY_METRICS_ROUTE, EARLIER_QUERY_METRICS_ROUTE), summary, `The earlier path of ${base}/${QUERY_METRICS_ROUTE}, which it answers the same way.`).annotateMerge(OpenApi.annotations({ deprecated: true })),
+    ];
+}
+/** The per-entity shorthand, which runs as the caller like the model-level route. */
+function entityMetricQueryEndpoints(planned) {
+    const { plural } = planned.resolved.entity.definition;
+    return metricQueryEndpoints({
+        base: `${BASE_PATH}/${planned.name}`,
+        payload: EntityMetricQueryBody,
+        summary: `Query ${plural.toLowerCase()} metrics`,
+        description: `The entity's metrics, with names relative to it: revenue, product.brand. dateRange bounds a ` +
+            "partitioned entity. Requires reading the entity and every entity along each path it " +
+            `groups, filters or orders by. Answered as POST ${BASE_PATH}/${QUERY_METRICS_ROUTE} is, ` +
+            "and counted against the same limit.",
+    });
+}
+function traversalEndpoint(planned, traversal, target, targetNames) {
+    const label = planned.resolved.entity.definition.label;
+    const reach = traversal.kind === "one" ? `one ${targetNames.label}` : `many ${targetNames.plural}`;
+    // A rel.one reaches one record; every to-many traversal is a paged query on the target.
+    const query = traversal.kind === "one" ? target.includeParams : target.queryParams;
+    const endpoint = HttpApiEndpoint.get(`related.${traversal.name}`, `${BASE_PATH}/${planned.name}/:id/${traversal.name}`, {
+        params: {
+            id: planned.resolved.entity.definition.source === undefined ? IdParam : WarehouseIdParam,
+        },
+        query,
+        success: target.findResult,
+        error: recordErrors,
+    });
+    const permissions = [...new Set([planned.name, traversal.target].map(readPermission))];
+    return documented(endpoint, `${label} ${traversal.phrase} ${reach} (${traversal.name})`, `${traversal.description}\n\n${requires(permissions)} Including a relationship requires ` +
+        "reading its entity too.");
+}
+function actionEndpoint(planned, plannedAction) {
+    const { name, action } = plannedAction;
+    const endpoint = HttpApiEndpoint.post(`actions.${name}`, `${BASE_PATH}/${planned.name}/actions/${name}`, {
+        payload: actionRequest(action.input),
+        success: ActionResponse,
+        error: action.connections.length > 0 ? connectionActionErrors : actionErrors,
+    });
+    return documented(endpoint, `${planned.name}.${name}`, actionDescription(plannedAction));
+}
+function entityGroup(planned, schemas, names) {
+    const own = schemas.get(planned.name);
+    const { definition } = planned.resolved.entity;
+    const base = `${BASE_PATH}/${planned.name}`;
+    const metricQueries = hasMetrics(planned)
+        ? entityMetricQueryEndpoints(planned).map(authenticated)
+        : [];
+    const plural = definition.plural.toLowerCase();
+    const read = requires([readPermission(planned.name)]);
+    const including = `${read} Including a relationship requires reading its entity too.`;
+    const endpoints = [
+        documented(HttpApiEndpoint.get("find", base, {
+            query: own.queryParams,
+            success: own.findResult,
+            error: readErrors,
+        }), `Find ${plural}`, `Filter, sort and page through records. The filter is JSON in the where parameter. ${including}`),
+        documented(HttpApiEndpoint.post("query", `${base}/query`, {
+            payload: own.query,
+            success: own.findResult,
+            error: readErrors,
+        }), `Query ${plural}`, `The same query as find, as a JSON body. ${including}`),
+        documented(HttpApiEndpoint.get("get", `${base}/:id`, {
+            params: { id: definition.source === undefined ? IdParam : WarehouseIdParam },
+            success: own.record,
+            error: recordErrors,
+        }), `Get a ${definition.label.toLowerCase()}`, read),
+        ...(definition.source === undefined
+            ? [
+                documented(HttpApiEndpoint.get("history", `${base}/:id/history`, {
+                    params: { id: IdParam },
+                    query: HistoryParams,
+                    success: HistoryPage,
+                    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), ...metricQueries];
+    return HttpApiGroup.make(planned.name)
+        .add(first, ...rest)
+        .annotateMerge(OpenApi.annotations({ title: definition.plural, description: definition.description }));
+}
+function serviceGroup() {
+    return HttpApiGroup.make(SERVICE_GROUP, { topLevel: true })
+        .add(authenticated(documented(HttpApiEndpoint.get("catalog", BASE_PATH, {
+        query: AsParams,
+        success: Catalog,
+        error: serviceErrors,
+    }), "The catalog", "The manifest: entities, properties, relationships, actions and roles with their " +
+        "permissions. With as=me, only the actions the caller's permissions may run.")), authenticated(documented(HttpApiEndpoint.get("graph", `${BASE_PATH}/graph`, {
+        success: Graph,
+        error: serviceErrors,
+    }), "Entities and their relationships, phrased in both directions")), authenticated(documented(HttpApiEndpoint.get("openapi", `${BASE_PATH}/openapi.json`, {
+        success: Schema.Record(Schema.String, Schema.Unknown),
+        error: serviceErrors,
+    }), "This OpenAPI document")), authenticated(documented(HttpApiEndpoint.get("me", `${BASE_PATH}/me`, {
+        success: Me,
+        error: serviceErrors,
+    }), "The caller", "The signed-in member, or the service an API key belongs to: the user, its roles and " +
+        "the permissions they grant. Needs only authentication; the app reads it once per " +
+        "session to show what the caller may do.")), authenticated(documented(HttpApiEndpoint.get("describe", `${BASE_PATH}/describe`, {
+        query: AsParams,
+        success: Schema.String.pipe(HttpApiSchema.asText()),
+        error: serviceErrors,
+    }), "The catalog as prose", "Written for agents and people. With as=me, only the actions the caller's " +
+        "permissions may run.")), documented(HttpApiEndpoint.get("status", `${BASE_PATH}/status`, {
+        success: Status,
+        error: serviceErrors,
+    }).middleware(ErrorResponses), "The served and the applied manifest hash", "Public: the deploy pipeline compares the hashes before it marks a deployment ready."), documented(HttpApiEndpoint.post("signInCheck", `${BASE_PATH}/sign-in/check`, {
+        payload: SignInCheckRequest,
+        success: SignInCheckResult,
+        error: [ErrorSchemas.invalidRequest, ErrorSchemas.rateLimited, ErrorSchemas.internal],
+    }).middleware(ErrorResponses), "Whether an address may sign in", "Public and rate limited per client address. The app asks before it emails a code or a " +
+        "sign-in link. Under the invited policy, an active member's address is allowed: with " +
+        "code once they have signed in with Neon Auth, with link before; any other address, " +
+        "deactivated members included, is not. Under open, every address is allowed with link."), ...metricQueryEndpoints({
+        base: BASE_PATH,
+        payload: MetricQueryBody,
+        summary: "Query metrics across the ontology",
+        description: "Numbers about the model: metrics from several entities, grouped and filtered by " +
+            "properties of related entities. Look at or change records through find and actions; " +
+            "count, sum or compare through query_metrics. Names are <entity>.<metric> and " +
+            "<entity>.<property>, or a route from a metric's entity: " +
+            "<entity>.<relationship>.<property>. Requires <entity>:read on every entity the " +
+            "request reads: each metric's entity, and every entity on a dimension's or a " +
+            "filter's route, and at most 30 metric queries a minute per caller, MCP included. The " +
+            "service then forwards the request to SegmentStream, which " +
+            "answers from the warehouse and the replica of stored records; its answer, errors " +
+            "included, is returned unchanged. Preview deployments answer aggregate_unavailable.",
+    }).map(authenticated))
+        .annotateMerge(OpenApi.annotations({ title: SERVICE_GROUP, description: "The ontology as a whole." }));
+}
+export function buildApi(plan) {
+    const schemas = entitySchemas(plan);
+    const names = new Map(plan.entities.map(({ name, resolved }) => [
+        name,
+        { label: resolved.entity.definition.label, plural: resolved.entity.definition.plural },
+    ]));
+    const groups = [
+        serviceGroup(),
+        ...(plan.ontology.manifest.entities.some((entity) => entity.properties.some((property) => property.type === "blob"))
+            ? [
+                storageGroup(authenticated, [...actionErrors, ErrorSchemas.storageUnavailable], (endpoint) => endpoint.middleware(ErrorResponses)),
+            ]
+            : []),
+        ...plan.entities.map((planned) => entityGroup(planned, schemas, names)),
+    ];
+    const api = HttpApi.make("ontology")
+        .add(...groups)
+        .annotateMerge(OpenApi.annotations({
+        title: "Ontology",
+        version: plan.ontology.manifest.hash,
+        description: "The workspace app's ontology: read records, run actions and read the catalog. " +
+            "Every change goes through an action.",
+    }));
+    return { plan, api, schemas };
+}
+const runtimeGeneratedActions = (entity, ontology) => generatedActions(ontology, entity.name);
+/**
+ * The HttpApi of an ontology: per entity `find`, `query`, `get`, `history`, a traversal per
+ * relationship and inverse, and a route per generated and authored action; and the catalog, graph,
+ * OpenAPI, status, caller (`me`), sign-in check, prose and metric query routes. There is no PUT, PATCH
+ * or DELETE: every change is an action.
+ */
+export function deriveApi(ontology, options = {}) {
+    return buildApi(planApi(ontology, options.generatedActions ?? runtimeGeneratedActions)).api;
+}

package/dist/service/authentication.d.ts

@@ -0,0 +1,227 @@
+import { Context, Effect, Layer, Redacted } from "effect";
+import { HttpServerRequest, type HttpServerResponse } from "effect/unstable/http";
+import { HttpApiMiddleware, HttpApiSecurity } from "effect/unstable/httpapi";
+import { type JWTVerifyGetKey } from "jose";
+import { type DeploymentObservation } from "../deployment.js";
+import { type BrowserRevision } from "./federation-status.js";
+import type { WorkloadExecution } from "../runtime/workload.js";
+import type { Principal } from "../runtime.js";
+import type { NeonAuthEnvironment } from "./config.js";
+import { RequestId } from "./errors.js";
+import { CurrentCaller, type VerifiedCaller } from "./caller-context.js";
+import { OntologyBackend, type SignInIdentity } from "./runtime-contract.js";
+import { type RuntimeCredential, type RuntimeTokenVerifier } from "./runtime-identity.js";
+declare const CurrentPrincipal_base: Context.ServiceClass<CurrentPrincipal, "@segmentstream/ontology/CurrentPrincipal", Principal>;
+/** The principal the request runs as, provided by {@link Authentication}. */
+export declare class CurrentPrincipal extends CurrentPrincipal_base {
+}
+declare const Authentication_base: HttpApiMiddleware.ServiceClass<Authentication, "@segmentstream/ontology/Authentication", {
+    requires: RequestId;
+    provides: CurrentCaller | CurrentPrincipal;
+    error: readonly [import("effect/Schema").Top, import("effect/Schema").Top, import("effect/Schema").Top];
+    clientError: never;
+    requiredForClient: false;
+    security: {
+        readonly bearer: HttpApiSecurity.Http;
+    };
+}, HttpApiMiddleware.HttpApiMiddlewareSecurity<{
+    readonly bearer: HttpApiSecurity.Http;
+}, CurrentCaller | 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,
+ * an API key or the deployment's runtime token acting as a member, 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 {
+}
+export interface TokenVerifierConfig {
+    readonly browserRevision?: BrowserRevision;
+    readonly browserMethods?: readonly string[];
+    readonly oidc?: {
+        issuer: string;
+        clientId: string;
+        environment?: string;
+        deploymentId?: string;
+        manifestDigest?: string;
+    };
+    readonly deployment?: DeploymentObservation;
+    /** Production workload activation and the deployment actually serving the request. */
+    readonly workloadTarget?: {
+        readonly deploymentId: string;
+    };
+    /** The control plane: the issuer of app tokens and the host of their JWKS. */
+    readonly segmentstreamUrl: string;
+    readonly applicationId: string;
+    readonly workspaceId: string;
+    readonly organizationId: string;
+}
+export type TokenVerification = {
+    readonly status: "workload";
+    readonly execution: WorkloadExecution;
+} | {
+    readonly status: "valid";
+    readonly identity: SignInIdentity;
+} | {
+    readonly status: "invalid";
+} | {
+    readonly status: "unavailable";
+};
+export type TokenVerifier = ((token: string) => Promise<TokenVerification>) & {
+    readonly browserRevision?: BrowserRevision;
+    readonly browserMethods?: readonly string[];
+    readonly oidc?: {
+        issuer: string;
+        clientId: string;
+        environment?: string;
+        deploymentId?: string;
+        manifestDigest?: string;
+    };
+    readonly deployment?: DeploymentObservation;
+};
+/** The control plane's app-token key set: `GET /api/v1/app-sessions/jwks`. */
+export declare function remoteKeySet(segmentstreamUrl: string): JWTVerifyGetKey;
+/** The workspace's Neon Auth key set, at `NEON_AUTH_JWKS_URL`. */
+export declare function neonAuthKeySet(jwksUrl: string): JWTVerifyGetKey;
+/**
+ * Verifies app tokens as the app SDK does: ES256 against the control plane's JWKS, issued by
+ * `SEGMENTSTREAM_URL` for this application (`aud: app:<application id>`), organization and workspace.
+ */
+export declare function makeTokenVerifier(config: TokenVerifierConfig, keySet: JWTVerifyGetKey): TokenVerifier;
+export declare const WORKLOAD_TOKEN_TYPE = "segmentstream-ontology-workload+jwt";
+/** The workspace's pipeline workers' workload subject: `pipeline-workers:<workspace id>`. */
+export declare const PIPELINE_WORKERS_SUBJECT_PREFIX = "pipeline-workers:";
+/**
+ * The platform's workload subject, `platform:<workspace id>`: backend-next acting for the console
+ * and the CLI. It is admitted only to the workflow routes and never resolves as a principal.
+ */
+export declare const PLATFORM_SUBJECT_PREFIX = "platform:";
+/**
+ * Who a workload token's subject names in this workspace: its pipeline workers or the platform.
+ * `undefined` for any other subject.
+ */
+export declare function workloadKind(claims: {
+    readonly sub?: unknown;
+}, workspaceId: string): "pipeline" | "platform" | undefined;
+/** A separate verifier: a workload token can never resolve as a human or act as an agent. */
+export declare function makeWorkloadTokenVerifier(config: TokenVerifierConfig, keySet: JWTVerifyGetKey): TokenVerifier;
+/**
+ * Neon Auth's issuer is the origin of its Auth URL: `https://ep-….neon.tech/ontology/auth` issues
+ * tokens with `iss: https://ep-….neon.tech`.
+ */
+export declare function neonAuthIssuer(baseUrl: string): string;
+/**
+ * Verifies the workspace's Neon Auth tokens (Managed Better Auth): EdDSA against its JWKS, issued by
+ * the origin of `NEON_AUTH_BASE_URL`, with a subject. The tokens carry no roles and no custom claims;
+ * roles come from the ontology.
+ */
+export declare function makeNeonAuthTokenVerifier(config: {
+    readonly baseUrl: string;
+}, keySet: JWTVerifyGetKey): TokenVerifier;
+/**
+ * Verifies a token with the verifier of the issuer it claims, by origin. The claim only picks the
+ * verifier, which checks the issuer again with the signature; a token from any other issuer is
+ * invalid without a key-set fetch.
+ */
+export declare function verifyByIssuer(verifiers: ReadonlyMap<string, TokenVerifier>): TokenVerifier;
+/**
+ * The service's token verification: SegmentStream app tokens, and the workspace's Neon Auth tokens
+ * once it has Neon Auth. Both are accepted while workspaces move to Neon Auth.
+ */
+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;
+/**
+ * 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.
+ */
+export declare function sessionMayAuthenticate(request: HttpServerRequest.HttpServerRequest): boolean;
+type Authenticated = {
+    readonly status: "authenticated";
+    readonly principal: Principal;
+    readonly caller: VerifiedCaller;
+} | {
+    readonly status: "missing";
+} | {
+    readonly status: "rejected";
+} | {
+    readonly status: "not_invited";
+} | {
+    readonly status: "forbidden";
+    readonly detail: string;
+} | {
+    readonly status: "unavailable";
+};
+/** Where a credential is presented. */
+export interface CredentialOptions {
+    /**
+     * The exact resource an opaque access token must name: MCP's URL or the first-party app-session
+     * resource. Ordinary routes derive the app resource from their browser request context.
+     */
+    readonly oauthResource?: string;
+    /**
+     * The deployment's own runtime token may authenticate here, acting as the member it names. Without
+     * it a runtime token is just an invalid token.
+     */
+    readonly runtime?: RuntimeCredential;
+    /**
+     * This route accepts `X-SegmentStream-Agent-Task`: with the runtime token, a live task's secret
+     * authenticates as the task's workflow user in this workspace. Every other route refuses it.
+     */
+    readonly agentTasks?: {
+        readonly workspaceId: string;
+    };
+}
+/** Resolves a bearer credential to its current principal and verified credential provenance. */
+export declare function authenticate(credential: Redacted.Redacted<string>, verifyToken: TokenVerifier, options?: CredentialOptions): Effect.Effect<Authenticated, never, OntologyBackend>;
+/** A browser's request, which may authenticate with the app's Neon Auth session cookie. */
+export interface BrowserSession {
+    readonly request: HttpServerRequest.HttpServerRequest;
+    readonly exchange: SessionExchange | undefined;
+}
+/**
+ * Runs `effect` as the principal a bearer credential names, or answers the request as every route
+ * does: 401 without a valid credential, 403 for a person nobody invited or a session cookie sent
+ * from another origin, 503 while sign-in cannot be verified, and a sanitized 500 when
+ * authentication itself fails.
+ */
+export declare function withPrincipal<E, R>(credential: Redacted.Redacted<string>, verifyToken: TokenVerifier, backend: OntologyBackend["Service"], effect: Effect.Effect<HttpServerResponse.HttpServerResponse, E, R>, options?: CredentialOptions & {
+    /** The `WWW-Authenticate` challenge of a 401, by whether the credential was missing. */
+    readonly challenge?: (missing: boolean) => string;
+    /** Without a bearer token, the app's session cookie may authenticate this browser request. */
+    readonly session?: BrowserSession;
+}): Effect.Effect<HttpServerResponse.HttpServerResponse, E, Exclude<R, CurrentPrincipal | CurrentCaller> | RequestId>;
+/**
+ * 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; with
+ * `verifyRuntime`, the deployment's own runtime token may act as the member it names.
+ */
+export declare function authenticationLayer(verifyToken: TokenVerifier, exchangeSession?: SessionExchange, verifyRuntime?: RuntimeTokenVerifier): Layer.Layer<Authentication, never, OntologyBackend>;
+export {};