@segmentstream/ontology 0.0.0-stage → 0.92.0

package/dist/service/authentication.js

@@ -0,0 +1,767 @@
+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, decodeProtectedHeader, errors, jwtVerify, } from "jose";
+import { CHANNEL_COOKIE_PATTERN } from "../channel-session.js";
+import { requireDeploymentCapability } from "../deployment.js";
+import { API_KEY_PREFIX } from "../runtime/principals.js";
+import { FEDERATION_TOKEN_PREFIX, federationDigest } from "../runtime/federation.js";
+import { browserRevisionAdmitted, browserRevisionObservation, browserSessionAdmission, federationStatus, } from "./federation-status.js";
+import { RequestId, crossOriginSession, forbidden, internalError, notInvited, toServerResponse, unauthorized, unavailable, } from "./errors.js";
+import { ACCESS_TOKEN_PREFIX, appSessionResource, publicOrigin, callerOfAccessToken, rejectedAccessToken, } from "./oauth/protocol.js";
+import { CurrentCaller } from "./caller-context.js";
+import { OntologyBackend } from "./runtime-contract.js";
+import { ACT_AS_HEADER, AGENT_TASK_HEADER, logRuntimeRejection, runtimeCredential, } from "./runtime-identity.js";
+import { agentTaskCaller } from "./agent/task-caller.js";
+import { ErrorSchemas } from "./schemas.js";
+const CLOCK_TOLERANCE_SECONDS = 5;
+const JWKS_TIMEOUT_MS = 5_000;
+/** The principal the request runs as, provided by {@link Authentication}. */
+export class CurrentPrincipal extends Context.Service()("@segmentstream/ontology/CurrentPrincipal") {
+}
+/**
+ * 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 class Authentication extends HttpApiMiddleware.Service()("@segmentstream/ontology/Authentication", {
+    security: {
+        bearer: HttpApiSecurity.bearer.pipe(HttpApiSecurity.annotate(OpenApi.Description, "The signed-in member's Neon Auth token (a SegmentStream app token during the move to " +
+            "Neon Auth), or an API key (ssk_…) for a service.")),
+    },
+    error: [ErrorSchemas.unauthorized, ErrorSchemas.notInvited, ErrorSchemas.unavailable],
+}) {
+}
+/** The control plane's app-token key set: `GET /api/v1/app-sessions/jwks`. */
+export function remoteKeySet(segmentstreamUrl) {
+    return createRemoteJWKSet(new URL("/api/v1/app-sessions/jwks", segmentstreamUrl), {
+        timeoutDuration: JWKS_TIMEOUT_MS,
+    });
+}
+/** The workspace's Neon Auth key set, at `NEON_AUTH_JWKS_URL`. */
+export function neonAuthKeySet(jwksUrl) {
+    return createRemoteJWKSet(new URL(jwksUrl), { timeoutDuration: JWKS_TIMEOUT_MS });
+}
+/**
+ * The key set could not be read: a timeout, a network failure, a non-200 or malformed response. The
+ * token may be fine, so this is not the caller's fault. Every other jose error is about the token.
+ */
+function keySetUnavailable(error) {
+    if (!(error instanceof errors.JOSEError)) {
+        return true;
+    }
+    return (error instanceof errors.JWKSTimeout ||
+        error instanceof errors.JWKSInvalid ||
+        error.code === errors.JOSEError.code);
+}
+function identityFromClaims(config, payload) {
+    const { sub, org, wsp, email, name, ss_oidc_identity } = payload;
+    if (typeof sub !== "string" || sub === "") {
+        return undefined;
+    }
+    if (org !== config.organizationId || wsp !== config.workspaceId) {
+        return undefined;
+    }
+    let oidcIdentity;
+    if (ss_oidc_identity !== undefined) {
+        const mapping = ss_oidc_identity;
+        if (!mapping ||
+            typeof mapping !== "object" ||
+            mapping.issuer !==
+                (config.oidc?.issuer ?? `${new URL(config.segmentstreamUrl).origin}/oidc`) ||
+            typeof mapping.subject !== "string" ||
+            !mapping.subject) {
+            return undefined;
+        }
+        oidcIdentity = { issuer: mapping.issuer, subject: mapping.subject };
+    }
+    return {
+        ...(oidcIdentity ? { oidcIdentity } : {}),
+        provider: "segmentstream",
+        subject: sub,
+        ...(typeof email === "string" ? { email } : {}),
+        ...(typeof name === "string" ? { name } : {}),
+    };
+}
+/**
+ * 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 function makeTokenVerifier(config, keySet) {
+    const issuer = new URL(config.segmentstreamUrl).origin;
+    const audience = `app:${config.applicationId}`;
+    return async function verifyToken(token) {
+        let payload;
+        try {
+            const verified = await jwtVerify(token, keySet, {
+                algorithms: ["ES256"],
+                typ: "JWT",
+                issuer,
+                audience,
+                clockTolerance: CLOCK_TOLERANCE_SECONDS,
+                requiredClaims: ["sub", "exp", "iat", "org", "wsp"],
+            });
+            payload = verified.payload;
+        }
+        catch (error) {
+            return keySetUnavailable(error) ? { status: "unavailable" } : { status: "invalid" };
+        }
+        const identity = identityFromClaims(config, payload);
+        return identity === undefined ? { status: "invalid" } : { status: "valid", identity };
+    };
+}
+export const WORKLOAD_TOKEN_TYPE = "segmentstream-ontology-workload+jwt";
+/** The workspace's pipeline workers' workload subject: `pipeline-workers:<workspace id>`. */
+export 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 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 function workloadKind(claims, workspaceId) {
+    if (claims.sub === `${PIPELINE_WORKERS_SUBJECT_PREFIX}${workspaceId}`) {
+        return "pipeline";
+    }
+    if (claims.sub === `${PLATFORM_SUBJECT_PREFIX}${workspaceId}`) {
+        return "platform";
+    }
+    return undefined;
+}
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** A separate verifier: a workload token can never resolve as a human or act as an agent. */
+export function makeWorkloadTokenVerifier(config, keySet) {
+    return async (token) => {
+        const preview = config.deployment?.target === "preview" ? config.deployment : undefined;
+        const servingDeploymentId = preview?.deploymentId ?? config.workloadTarget?.deploymentId;
+        if (servingDeploymentId === undefined) {
+            return { status: "invalid" };
+        }
+        if (preview) {
+            requireDeploymentCapability(preview, "workflows");
+        }
+        let payload;
+        try {
+            const verified = await jwtVerify(token, keySet, {
+                algorithms: ["ES256"],
+                typ: WORKLOAD_TOKEN_TYPE,
+                issuer: new URL(config.segmentstreamUrl).origin,
+                audience: `ontology:${config.applicationId}`,
+                clockTolerance: CLOCK_TOLERANCE_SECONDS,
+                requiredClaims: [
+                    "sub",
+                    "exp",
+                    "iat",
+                    "jti",
+                    "org",
+                    "wsp",
+                    "deploymentId",
+                    "ontologyDeploymentId",
+                    "ontologyOrigin",
+                    "environment",
+                    "runId",
+                    "attemptId",
+                    "generation",
+                ],
+            });
+            payload = verified.payload;
+        }
+        catch (error) {
+            return keySetUnavailable(error) ? { status: "unavailable" } : { status: "invalid" };
+        }
+        const kind = workloadKind(payload, config.workspaceId);
+        // The platform's runId and attemptId only correlate its requests; a pipeline's name its run.
+        const strings = kind === "platform" ? ["jti", "runId", "attemptId"] : ["jti"];
+        const ids = kind === "platform"
+            ? ["deploymentId", "ontologyDeploymentId"]
+            : ["deploymentId", "ontologyDeploymentId", "runId", "attemptId"];
+        if (payload.org !== config.organizationId ||
+            payload.wsp !== config.workspaceId ||
+            kind === undefined ||
+            (kind === "pipeline" && !("executionId" in payload)) ||
+            payload.environment !== (preview ? "preview" : "production") ||
+            (preview !== undefined &&
+                (kind !== "platform" ||
+                    payload.deploymentId !== preview.deploymentId ||
+                    payload.ontologyDeploymentId !== preview.deploymentId ||
+                    typeof payload.exp !== "number" ||
+                    payload.exp * 1000 > Date.parse(preview.expiresAt))) ||
+            payload.aud !== `ontology:${config.applicationId}` ||
+            strings.some((name) => typeof payload[name] !== "string" || payload[name].trim() === "") ||
+            (payload.jobName !== undefined &&
+                payload.jobName !== null &&
+                (typeof payload.jobName !== "string" || payload.jobName.trim() === "")) ||
+            ids.some((name) => typeof payload[name] !== "string" || !UUID.test(payload[name])) ||
+            (payload.executionId !== null &&
+                !(kind === "platform" && payload.executionId === undefined) &&
+                (typeof payload.executionId !== "string" || !UUID.test(payload.executionId))) ||
+            !Number.isSafeInteger(payload.generation) ||
+            payload.generation < 1 ||
+            !Number.isSafeInteger(payload.iat) ||
+            !Number.isSafeInteger(payload.exp) ||
+            payload.iat > Math.floor(Date.now() / 1000) + CLOCK_TOLERANCE_SECONDS ||
+            payload.exp <= payload.iat ||
+            payload.exp - payload.iat > 300 ||
+            typeof payload.ontologyOrigin !== "string" ||
+            !URL.canParse(payload.ontologyOrigin)) {
+            return { status: "invalid" };
+        }
+        const origin = new URL(payload.ontologyOrigin);
+        if (origin.protocol !== "https:" || origin.origin !== payload.ontologyOrigin) {
+            return { status: "invalid" };
+        }
+        return {
+            status: "workload",
+            execution: {
+                issuer: payload.iss,
+                audience: payload.aud,
+                organizationId: config.organizationId,
+                workspaceId: config.workspaceId,
+                subject: payload.sub,
+                deploymentId: payload.deploymentId,
+                ontologyDeploymentId: payload.ontologyDeploymentId,
+                servingOntologyDeploymentId: servingDeploymentId,
+                ontologyOrigin: payload.ontologyOrigin,
+                environment: preview ? "preview" : "production",
+                jobName: typeof payload.jobName === "string" ? payload.jobName : null,
+                runId: payload.runId,
+                executionId: (payload.executionId ?? null),
+                attemptId: payload.attemptId,
+                generation: payload.generation,
+                tokenId: payload.jti,
+                issuedAt: payload.iat,
+                expiresAt: payload.exp,
+            },
+        };
+    };
+}
+/**
+ * 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 function neonAuthIssuer(baseUrl) {
+    return new URL(baseUrl).origin;
+}
+/**
+ * The member a Neon Auth token names. Its email counts only once Neon Auth verified it: sign-in links
+ * an invited member by email, and an unverified address (a password sign-up anyone can make) must
+ * never claim someone else's invitation or roles.
+ */
+function neonAuthIdentity(payload) {
+    const { sub, email, emailVerified, name } = payload;
+    if (typeof sub !== "string" || sub === "") {
+        return undefined;
+    }
+    return {
+        provider: "neon-auth",
+        subject: sub,
+        ...(typeof email === "string" && emailVerified === true ? { email } : {}),
+        ...(typeof name === "string" ? { name } : {}),
+    };
+}
+/**
+ * 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 function makeNeonAuthTokenVerifier(config, keySet) {
+    const issuer = neonAuthIssuer(config.baseUrl);
+    return async function verifyNeonAuthToken(token) {
+        let payload;
+        try {
+            const verified = await jwtVerify(token, keySet, {
+                algorithms: ["EdDSA"],
+                issuer,
+                clockTolerance: CLOCK_TOLERANCE_SECONDS,
+                requiredClaims: ["sub", "exp", "iat"],
+            });
+            payload = verified.payload;
+        }
+        catch (error) {
+            return keySetUnavailable(error) ? { status: "unavailable" } : { status: "invalid" };
+        }
+        const identity = neonAuthIdentity(payload);
+        return identity === undefined ? { status: "invalid" } : { status: "valid", identity };
+    };
+}
+/** The `iss` a token claims, before anything about it is verified; `undefined` for a non-JWT. */
+function claimedIssuer(token) {
+    try {
+        const { iss } = decodeJwt(token);
+        return typeof iss === "string" ? iss : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * 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 function verifyByIssuer(verifiers) {
+    return async function verifyToken(token) {
+        const issuer = claimedIssuer(token);
+        const verify = issuer === undefined ? undefined : verifiers.get(issuer);
+        return verify === undefined ? { status: "invalid" } : verify(token);
+    };
+}
+/**
+ * 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 function tokenVerifier(config) {
+    const platformKeys = remoteKeySet(config.segmentstreamUrl);
+    const human = makeTokenVerifier(config, platformKeys);
+    const workload = makeWorkloadTokenVerifier(config, platformKeys);
+    const platform = (token) => {
+        try {
+            return decodeProtectedHeader(token).typ === WORKLOAD_TOKEN_TYPE
+                ? workload(token)
+                : config.deployment?.target === "preview"
+                    ? Promise.resolve({ status: "invalid" })
+                    : human(token);
+        }
+        catch {
+            return Promise.resolve({ status: "invalid" });
+        }
+    };
+    const verifiers = new Map([
+        [new URL(config.segmentstreamUrl).origin, platform],
+    ]);
+    if (config.neonAuth !== undefined &&
+        (!config.browserMethods || config.browserMethods.includes("email"))) {
+        verifiers.set(neonAuthIssuer(config.neonAuth.baseUrl), makeNeonAuthTokenVerifier(config.neonAuth, neonAuthKeySet(config.neonAuth.jwksUrl)));
+    }
+    const verify = verifyByIssuer(verifiers);
+    return Object.assign(async (token) => {
+        if (config.deployment) {
+            requireDeploymentCapability(config.deployment);
+        }
+        return verify(token);
+    }, {
+        deployment: config.deployment,
+        browserRevision: config.browserRevision,
+        browserMethods: config.browserMethods,
+        oidc: config.oidc,
+    });
+}
+/**
+ * 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.
+ */
+export function sessionMayAuthenticate(request) {
+    if (SAFE_METHODS.has(request.method)) {
+        return true;
+    }
+    const origin = request.headers.origin;
+    return origin !== undefined && origin === requestOrigin(request);
+}
+/**
+ * The member a verified runtime caller acts for: the member `X-SegmentStream-Act-As` names, with the
+ * roles they hold now, while they are active and paired with the agent. Without the header, the
+ * runtime may call only the agent's own routes, which authenticate it themselves.
+ */
+function actingMember(actAs, provider) {
+    return Effect.gen(function* () {
+        const backend = yield* OntologyBackend;
+        if (actAs === undefined) {
+            return {
+                status: "forbidden",
+                detail: `The app's agent names the member it acts for in ${ACT_AS_HEADER}.`,
+            };
+        }
+        const member = backend.agents === undefined
+            ? undefined
+            : yield* backend.agents.actingMember(actAs, provider);
+        return member === undefined || member.kind !== "member"
+            ? {
+                status: "forbidden",
+                detail: "The member is inactive or has not paired with the app's agent.",
+            }
+            : {
+                status: "authenticated",
+                principal: { ...member, authenticatedVia: provider ?? "agent" },
+                caller: { kind: "runtime", subjectId: member.id },
+            };
+    });
+}
+/**
+ * The workflow user a verified runtime caller acts as while it runs a task a workflow handed it:
+ * the task's secret names it, never the caller. Refused on a route that does not accept tasks, and
+ * with a member named as well.
+ */
+function agentTaskPrincipal(secret, actAs, accepted) {
+    return Effect.gen(function* () {
+        if (accepted === undefined) {
+            return {
+                status: "forbidden",
+                detail: `This route does not accept ${AGENT_TASK_HEADER}.`,
+            };
+        }
+        if (actAs !== undefined) {
+            return {
+                status: "forbidden",
+                detail: `A request names a member in ${ACT_AS_HEADER} or a task in ${AGENT_TASK_HEADER}, not both.`,
+            };
+        }
+        const resolved = yield* agentTaskCaller(secret, accepted.workspaceId);
+        return resolved.status === "refused"
+            ? { status: "forbidden", detail: resolved.detail }
+            : {
+                status: "authenticated",
+                principal: resolved.principal,
+                caller: { kind: "runtime", subjectId: resolved.principal.id },
+            };
+    });
+}
+/** Resolves a bearer credential to its current principal and verified credential provenance. */
+export function authenticate(credential, verifyToken, options = {}) {
+    return Effect.gen(function* () {
+        const backend = yield* OntologyBackend;
+        const token = Redacted.value(credential);
+        if (verifyToken.deployment) {
+            requireDeploymentCapability(verifyToken.deployment);
+        }
+        if (verifyToken.deployment?.target === "preview" &&
+            ((token.startsWith(FEDERATION_TOKEN_PREFIX) && !verifyToken.browserMethods) ||
+                token.startsWith(ACCESS_TOKEN_PREFIX) ||
+                token.startsWith(API_KEY_PREFIX) ||
+                options.runtime !== undefined)) {
+            return { status: "rejected" };
+        }
+        if (token === "") {
+            return { status: "missing" };
+        }
+        if (token.startsWith(FEDERATION_TOKEN_PREFIX)) {
+            const revision = verifyToken.browserRevision
+                ? yield* Effect.promise(() => browserRevisionObservation(verifyToken.browserRevision))
+                : { active: true };
+            if (!browserRevisionAdmitted(revision)) {
+                return { status: "rejected" };
+            }
+            const store = backend.federation;
+            const session = store ? yield* store.read(federationDigest(token)) : undefined;
+            const admission = !verifyToken.browserMethods
+                ? { active: true }
+                : verifyToken.browserMethods.includes("segmentstream") &&
+                    session !== undefined &&
+                    verifyToken.oidc !== undefined
+                    ? yield* Effect.promise(() => browserSessionAdmission(session, verifyToken.oidc))
+                    : { active: false };
+            const active = browserRevisionAdmitted(admission) &&
+                session?.userId &&
+                (yield* Effect.promise(() => federationStatus(session)));
+            const principal = active && session?.userId ? yield* store.principal(session.userId) : undefined;
+            return principal && browserRevisionAdmitted(revision) && browserRevisionAdmitted(admission)
+                ? {
+                    status: "authenticated",
+                    principal: { ...principal, authenticatedVia: principal.authenticatedVia ?? "oidc" },
+                    caller: { kind: "member", subjectId: principal.id },
+                }
+                : { status: "rejected" };
+        }
+        if (token.startsWith(ACCESS_TOKEN_PREFIX)) {
+            if (options.oauthResource === undefined || backend.oauth === undefined) {
+                yield* rejectedAccessToken(backend.oauth === undefined ? "oauth_unavailable" : "unsupported_route");
+                return { status: "rejected" };
+            }
+            const authenticated = yield* callerOfAccessToken(backend.oauth, token, options.oauthResource);
+            return authenticated === undefined
+                ? { status: "rejected" }
+                : {
+                    status: "authenticated",
+                    ...authenticated,
+                    principal: {
+                        ...authenticated.principal,
+                        authenticatedVia: authenticated.principal.authenticatedVia ?? "oauth",
+                    },
+                };
+        }
+        if (token.startsWith(API_KEY_PREFIX)) {
+            const principal = yield* backend.resolveApiKey(credential);
+            return principal === undefined
+                ? { status: "rejected" }
+                : {
+                    status: "authenticated",
+                    principal: { ...principal, authenticatedVia: "api_key" },
+                    caller: {
+                        kind: principal.kind === "service" ? "service" : "member",
+                        subjectId: principal.id,
+                    },
+                };
+        }
+        if (options.runtime !== undefined) {
+            const { verify, actAs, provider, agentTask } = options.runtime;
+            const runtime = yield* Effect.promise(() => verify(token));
+            switch (runtime.status) {
+                case "valid":
+                    return agentTask === undefined
+                        ? yield* actingMember(actAs, provider)
+                        : yield* agentTaskPrincipal(agentTask, actAs, options.agentTasks);
+                case "invalid":
+                    yield* logRuntimeRejection(runtime.reason);
+                    return { status: "rejected" };
+                case "unavailable":
+                    return { status: "unavailable" };
+                case "other":
+                    if (agentTask !== undefined) {
+                        return {
+                            status: "forbidden",
+                            detail: `${AGENT_TASK_HEADER} authenticates only with the deployment's runtime token.`,
+                        };
+                    }
+                    break;
+            }
+        }
+        const verification = yield* Effect.promise(() => verifyToken(token));
+        if (verification.status === "workload") {
+            // Only the pipeline workers resolve as a principal. The platform's subject is admitted by the
+            // workflow routes alone; here, as everywhere else, it is refused.
+            const { execution } = verification;
+            const principal = workloadKind({ sub: execution.subject }, execution.workspaceId) !== "pipeline" ||
+                backend.resolvePipelineWorker === undefined
+                ? undefined
+                : yield* backend.resolvePipelineWorker(execution);
+            return principal === undefined
+                ? { status: "rejected" }
+                : {
+                    status: "authenticated",
+                    principal: { ...principal, authenticatedVia: "workload" },
+                    caller: { kind: "workload", subjectId: principal.id },
+                };
+        }
+        if (verification.status !== "valid") {
+            return verification.status === "invalid"
+                ? { status: "rejected" }
+                : { status: "unavailable" };
+        }
+        const revision = verification.identity.provider === "neon-auth" && verifyToken.browserRevision
+            ? yield* Effect.promise(() => browserRevisionObservation(verifyToken.browserRevision))
+            : { active: true };
+        if (!browserRevisionAdmitted(revision)) {
+            return { status: "rejected" };
+        }
+        return yield* backend.resolvePrincipal(verification.identity).pipe(Effect.map((member) => member === undefined || !browserRevisionAdmitted(revision)
+            ? { status: "rejected" }
+            : {
+                status: "authenticated",
+                principal: { ...member, authenticatedVia: verification.identity.provider },
+                caller: { kind: "member", subjectId: member.id },
+            }), Effect.catchTag("NotInvited", () => Effect.succeed({ status: "not_invited" })));
+    });
+}
+/**
+ * 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 channelCookies = Object.entries(request.cookies).filter(([name]) => CHANNEL_COOKIE_PATTERN.test(name));
+        if (channelCookies.length > 0) {
+            if (!sessionMayAuthenticate(request)) {
+                return { status: "cross_origin" };
+            }
+            for (const [, token] of channelCookies) {
+                if (!token?.startsWith(ACCESS_TOKEN_PREFIX)) {
+                    continue;
+                }
+                const outcome = yield* authenticate(Redacted.make(token), verifyToken, {
+                    oauthResource: appSessionResource(publicOrigin(request)),
+                });
+                if (outcome.status === "authenticated") {
+                    return outcome;
+                }
+            }
+        }
+        const federationCookies = Object.entries(request.cookies).filter(([name]) => /^(?:__Host-)?ss_oidc_session\.[A-Za-z0-9_-]+$/.test(name));
+        if (federationCookies.length > 0) {
+            if (!sessionMayAuthenticate(request)) {
+                return { status: "cross_origin" };
+            }
+            for (const [, token] of federationCookies) {
+                if (!token?.startsWith(FEDERATION_TOKEN_PREFIX)) {
+                    continue;
+                }
+                const outcome = yield* authenticate(Redacted.make(token ?? ""), verifyToken);
+                if (outcome.status === "authenticated") {
+                    return outcome;
+                }
+            }
+            return { status: "rejected" };
+        }
+        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" };
+        }
+    });
+}
+/**
+ * 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 function withPrincipal(credential, verifyToken, backend, effect, options = {}) {
+    return Effect.gen(function* () {
+        const requestId = yield* RequestId;
+        const outcome = yield* Effect.gen(function* () {
+            const fromSession = Redacted.value(credential) === "" && options.session !== undefined
+                ? yield* authenticateSession(options.session.request, options.session.exchange, verifyToken)
+                : undefined;
+            const ordinaryResource = options.session === undefined
+                ? undefined
+                : appSessionResource(publicOrigin(options.session.request));
+            return (fromSession ??
+                (yield* authenticate(credential, verifyToken, {
+                    ...options,
+                    oauthResource: options.oauthResource ?? ordinaryResource,
+                })));
+        }).pipe(Effect.provideService(OntologyBackend, backend), Effect.annotateLogs({ requestId }), 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) {
+            case "authenticated":
+                return yield* Effect.provideContext(effect, Context.make(CurrentPrincipal, outcome.principal).pipe(Context.add(CurrentCaller, outcome.caller)));
+            case "missing":
+                return toServerResponse(unauthorized(requestId, "A bearer token is required.", options.challenge?.(true)));
+            case "rejected":
+                return toServerResponse(unauthorized(requestId, "The bearer token is invalid, expired or revoked.", options.challenge?.(false)));
+            case "not_invited":
+                return toServerResponse(notInvited(requestId));
+            case "forbidden":
+                return toServerResponse(forbidden(requestId, outcome.detail));
+            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":
+                return toServerResponse(internalError(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 function authenticationLayer(verifyToken, exchangeSession, verifyRuntime) {
+    return Layer.effect(Authentication, Effect.gen(function* () {
+        const backend = yield* OntologyBackend;
+        return Authentication.of({
+            bearer: (httpEffect, { credential }) => Effect.gen(function* () {
+                const request = yield* HttpServerRequest.HttpServerRequest;
+                const runtime = runtimeCredential(verifyRuntime, request);
+                return yield* withPrincipal(credential, verifyToken, backend, httpEffect, {
+                    session: { request, exchange: exchangeSession },
+                    ...(runtime === undefined ? {} : { runtime }),
+                });
+            }),
+        });
+    }));
+}