@segmentstream/ontology 0.0.0-stage → 0.92.0

package/dist/service/name-suggestions.js

@@ -0,0 +1,38 @@
+import { toSnakeCase } from "../names.js";
+/** Levenshtein distance, stopping once a match within two edits is impossible. */
+function distance(left, right) {
+    if (Math.abs(left.length - right.length) > 2) {
+        return 3;
+    }
+    let previous = Array.from({ length: right.length + 1 }, (_, index) => index);
+    for (let row = 1; row <= left.length; row++) {
+        const current = [row];
+        for (let column = 1; column <= right.length; column++) {
+            current[column] = Math.min(previous[column] + 1, current[column - 1] + 1, previous[column - 1] + (left[row - 1] === right[column - 1] ? 0 : 1));
+        }
+        if (Math.min(...current) > 2) {
+            return 3;
+        }
+        previous = current;
+    }
+    return previous[right.length];
+}
+/** Candidates must already be filtered for this authenticated caller's visibility. */
+export function suggestNames(name, candidates) {
+    const canonical = toSnakeCase(name);
+    if (candidates.includes(canonical)) {
+        return [canonical];
+    }
+    return [...new Set(candidates)]
+        .map((candidate) => ({ name: candidate, distance: distance(canonical, candidate) }))
+        .filter((candidate) => candidate.distance <= 2)
+        .sort((left, right) => left.distance - right.distance ||
+        (left.name < right.name ? -1 : left.name > right.name ? 1 : 0))
+        .slice(0, 3)
+        .map((candidate) => candidate.name);
+}
+export function suggestionDetail(detail, suggestions) {
+    return suggestions.length === 0
+        ? detail
+        : `${detail} did you mean ${suggestions.map((name) => JSON.stringify(name)).join(" or ")}?`;
+}

package/dist/service/navigation-schemas.d.ts

@@ -0,0 +1,80 @@
+import { Schema } from "effect";
+export declare const NavigationInput: Schema.Struct<{
+    readonly entity: Schema.optionalKey<Schema.String>;
+    readonly query: Schema.optionalKey<Schema.String>;
+    readonly after: Schema.optionalKey<Schema.String>;
+    readonly limit: Schema.optionalKey<Schema.Int>;
+    readonly expected_revision: Schema.optionalKey<Schema.String>;
+}>;
+export type NavigationInput = typeof NavigationInput.Type;
+export declare const NavigationOutput: Schema.Struct<{
+    readonly revision: Schema.String;
+    readonly pages: Schema.$Array<Schema.Union<readonly [Schema.Struct<{
+        readonly url: Schema.String;
+        readonly ref: Schema.String;
+        readonly route: Schema.String;
+        readonly title: Schema.String;
+        readonly description: Schema.String;
+        readonly entities: Schema.$Array<Schema.String>;
+        readonly parameters: Schema.$Array<Schema.Struct<{
+            readonly name: Schema.String;
+            readonly kind: Schema.Literals<readonly ["segment", "catch_all"]>;
+            readonly required: Schema.Boolean;
+            readonly description: Schema.optionalKey<Schema.String>;
+        }>>;
+        readonly query: Schema.$Record<Schema.String, Schema.String>;
+    }>, Schema.Struct<{
+        readonly url_pattern: Schema.String;
+        readonly ref: Schema.String;
+        readonly route: Schema.String;
+        readonly title: Schema.String;
+        readonly description: Schema.String;
+        readonly entities: Schema.$Array<Schema.String>;
+        readonly parameters: Schema.$Array<Schema.Struct<{
+            readonly name: Schema.String;
+            readonly kind: Schema.Literals<readonly ["segment", "catch_all"]>;
+            readonly required: Schema.Boolean;
+            readonly description: Schema.optionalKey<Schema.String>;
+        }>>;
+        readonly query: Schema.$Record<Schema.String, Schema.String>;
+    }>]>>;
+    readonly next_cursor: Schema.NullOr<Schema.String>;
+}>;
+export declare const NavigationToolOutput: Schema.Union<readonly [Schema.Struct<{
+    readonly revision: Schema.String;
+    readonly pages: Schema.$Array<Schema.Union<readonly [Schema.Struct<{
+        readonly url: Schema.String;
+        readonly ref: Schema.String;
+        readonly route: Schema.String;
+        readonly title: Schema.String;
+        readonly description: Schema.String;
+        readonly entities: Schema.$Array<Schema.String>;
+        readonly parameters: Schema.$Array<Schema.Struct<{
+            readonly name: Schema.String;
+            readonly kind: Schema.Literals<readonly ["segment", "catch_all"]>;
+            readonly required: Schema.Boolean;
+            readonly description: Schema.optionalKey<Schema.String>;
+        }>>;
+        readonly query: Schema.$Record<Schema.String, Schema.String>;
+    }>, Schema.Struct<{
+        readonly url_pattern: Schema.String;
+        readonly ref: Schema.String;
+        readonly route: Schema.String;
+        readonly title: Schema.String;
+        readonly description: Schema.String;
+        readonly entities: Schema.$Array<Schema.String>;
+        readonly parameters: Schema.$Array<Schema.Struct<{
+            readonly name: Schema.String;
+            readonly kind: Schema.Literals<readonly ["segment", "catch_all"]>;
+            readonly required: Schema.Boolean;
+            readonly description: Schema.optionalKey<Schema.String>;
+        }>>;
+        readonly query: Schema.$Record<Schema.String, Schema.String>;
+    }>]>>;
+    readonly next_cursor: Schema.NullOr<Schema.String>;
+}>, Schema.Top, Schema.Top, Schema.Struct<{
+    readonly error: Schema.Literals<readonly ["invalid_cursor", "page_catalog_version_mismatch", "page_catalog_unavailable"]>;
+    readonly detail: Schema.String;
+    readonly request_id: Schema.String;
+    readonly revision: Schema.optionalKey<Schema.String>;
+}>]>;

package/dist/service/navigation-schemas.js

@@ -0,0 +1,49 @@
+import { Schema } from "effect";
+import { ErrorSchemas } from "./schemas.js";
+export const NavigationInput = Schema.Struct({
+    entity: Schema.optionalKey(Schema.String.check(Schema.isPattern(/^[a-z][a-z0-9_]*$/))),
+    query: Schema.optionalKey(Schema.String.check(Schema.makeFilter((value) => value.trim().length > 0 && Array.from(value).length <= 512
+        ? true
+        : "Use a nonblank query of at most 512 Unicode code points.", { toJsonSchema: () => ({ minLength: 1, maxLength: 512, pattern: "\\S" }) }))),
+    after: Schema.optionalKey(Schema.String.check(Schema.isMinLength(1), Schema.isMaxLength(16 * 1024))),
+    limit: Schema.optionalKey(Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: 50 }))),
+    expected_revision: Schema.optionalKey(Schema.String.check(Schema.isPattern(/^sha256:[a-f0-9]{64}$/))),
+});
+const Page = {
+    ref: Schema.String,
+    route: Schema.String,
+    title: Schema.String,
+    description: Schema.String,
+    entities: Schema.Array(Schema.String),
+    parameters: Schema.Array(Schema.Struct({
+        name: Schema.String,
+        kind: Schema.Literals(["segment", "catch_all"]),
+        required: Schema.Boolean,
+        description: Schema.optionalKey(Schema.String),
+    })),
+    query: Schema.Record(Schema.String, Schema.String),
+};
+export const NavigationOutput = Schema.Struct({
+    revision: Schema.String,
+    pages: Schema.Array(Schema.Union([
+        Schema.Struct({ ...Page, url: Schema.String }),
+        Schema.Struct({ ...Page, url_pattern: Schema.String }),
+    ])),
+    next_cursor: Schema.NullOr(Schema.String),
+});
+const NavigationFailureOutput = Schema.Struct({
+    error: Schema.Literals([
+        "invalid_cursor",
+        "page_catalog_version_mismatch",
+        "page_catalog_unavailable",
+    ]),
+    detail: Schema.String,
+    request_id: Schema.String,
+    revision: Schema.optionalKey(Schema.String),
+});
+export const NavigationToolOutput = Schema.Union([
+    NavigationOutput,
+    ErrorSchemas.invalidRequest,
+    ErrorSchemas.internal,
+    NavigationFailureOutput,
+]);

package/dist/service/navigation.d.ts

@@ -0,0 +1,20 @@
+import type { OntologyManifest } from "../manifest.js";
+import { type PageCatalogV1 } from "../navigation-catalog.js";
+import { type PermissionHolder } from "../permissions.js";
+import type { CallerContext } from "./caller-context.js";
+import type { NavigationInput } from "./navigation-schemas.js";
+type JsonObject = Readonly<Record<string, unknown>>;
+declare const NavigationError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "NavigationError";
+} & Readonly<A>;
+export declare class NavigationError extends NavigationError_base<{
+    readonly error: "invalid_cursor" | "page_catalog_version_mismatch" | "page_catalog_unavailable";
+    readonly detail: string;
+    readonly revision?: string;
+    readonly cause?: unknown;
+}> {
+}
+/** Snapshot immutable deployment metadata once; compute caller visibility on every invocation. */
+export declare function createNavigation(value: PageCatalogV1, manifest: OntologyManifest, origins: readonly string[]): (input: NavigationInput, principal: PermissionHolder, caller: CallerContext, origin: string) => JsonObject;
+export type Navigation = ReturnType<typeof createNavigation>;
+export {};

package/dist/service/navigation.js

@@ -0,0 +1,165 @@
+import { createHash } from "node:crypto";
+import { Data } from "effect";
+import { NAVIGATION_CATALOG_LIMITS, parsePageCatalog, } from "../navigation-catalog.js";
+import { effectivePermissions } from "../permissions.js";
+import { catalogFor } from "./catalog.js";
+import { discoveryResultBytes } from "./discovery.js";
+import { compareRefs, normalizeSearch } from "./discovery-search.js";
+export class NavigationError extends Data.TaggedError("NavigationError") {
+}
+function unavailable(cause) {
+    throw new NavigationError({
+        error: "page_catalog_unavailable",
+        detail: "Page discovery is unavailable for this deployment.",
+        cause,
+    });
+}
+function invalidCursor() {
+    throw new NavigationError({
+        error: "invalid_cursor",
+        detail: "Restart page discovery; its cursor is invalid.",
+    });
+}
+function checkRevision(revision, expected) {
+    if (expected !== undefined && expected !== revision) {
+        throw new NavigationError({
+            error: "page_catalog_version_mismatch",
+            detail: "The page catalog changed. Repeat page discovery with the current revision.",
+            revision,
+        });
+    }
+}
+function digest(value) {
+    return createHash("sha256").update(JSON.stringify(value)).digest("hex");
+}
+/** Keyword search inspects only published titles/descriptions and never executes page code. */
+function score(title, description, query) {
+    const normalizedTitle = normalizeSearch(title);
+    const normalizedDescription = normalizeSearch(description);
+    const terms = query.match(/[\p{L}\p{N}]+/gu) ?? [query];
+    if (!terms.every((term) => normalizedTitle.includes(term) || normalizedDescription.includes(term))) {
+        return 0;
+    }
+    return ((normalizedTitle === query ? 100 : normalizedTitle.includes(query) ? 50 : 0) +
+        (normalizedDescription.includes(query) ? 10 : 0) +
+        terms.filter((term) => normalizedTitle.includes(term)).length +
+        1);
+}
+/** The existing app-origin allowlist is the authority; forwarded headers only select an exact member. */
+function trustedOrigin(candidate, origins) {
+    const parsed = URL.parse(candidate);
+    if (parsed === null ||
+        !["https:", "http:"].includes(parsed.protocol) ||
+        parsed.username !== "" ||
+        parsed.password !== "" ||
+        parsed.origin !== candidate ||
+        !origins.includes(candidate)) {
+        return unavailable(new Error("The request has no verified app origin for navigation."));
+    }
+    return parsed.origin;
+}
+/** Snapshot immutable deployment metadata once; compute caller visibility on every invocation. */
+export function createNavigation(value, manifest, origins) {
+    let catalog;
+    let catalogFailure;
+    try {
+        catalog = parsePageCatalog(value);
+        const names = new Set(manifest.entities.map(({ name }) => name));
+        for (const page of catalog.pages) {
+            for (const name of page.entities) {
+                if (!names.has(name)) {
+                    throw new Error(`Page ${page.ref} references unknown ontology entity ${name}.`);
+                }
+            }
+        }
+    }
+    catch (error) {
+        catalog = undefined;
+        catalogFailure = error;
+    }
+    const trustedOrigins = [...origins];
+    return (input, principal, caller, origin) => {
+        if (catalog === undefined) {
+            return unavailable(catalogFailure);
+        }
+        checkRevision(catalog.revision, input.expected_revision);
+        const appOrigin = trustedOrigin(origin, trustedOrigins);
+        const visibleNames = catalogFor(manifest, effectivePermissions(principal)).entities.map(({ name }) => name);
+        const visible = new Set(visibleNames);
+        const scope = digest([caller.kind, visibleNames.sort(compareRefs)]);
+        const query = input.query === undefined ? undefined : normalizeSearch(input.query);
+        const request = digest({
+            entity: input.entity ?? null,
+            query: query ?? null,
+            order: "keywords-v1",
+            origin: appOrigin,
+        });
+        const items = catalog.pages
+            .filter((page) => page.entities.every((name) => visible.has(name)))
+            .filter((page) => input.entity === undefined || page.entities.includes(input.entity))
+            .map((page) => ({
+            page,
+            score: query === undefined ? 1 : score(page.title, page.description, query),
+        }))
+            .filter((item) => item.score > 0)
+            .sort((a, b) => b.score - a.score || compareRefs(a.page.ref, b.page.ref))
+            .map(({ page }) => ({
+            ...page,
+            [page.parameters.length === 0 ? "url" : "url_pattern"]: `${appOrigin}${page.route}`,
+        }));
+        let start = 0;
+        if (input.after !== undefined) {
+            let cursor;
+            try {
+                if (!/^[A-Za-z0-9_-]+$/.test(input.after)) {
+                    return invalidCursor();
+                }
+                const decoded = JSON.parse(Buffer.from(input.after, "base64url").toString("utf8"));
+                if (typeof decoded !== "object" || decoded === null || Array.isArray(decoded)) {
+                    return invalidCursor();
+                }
+                cursor = decoded;
+            }
+            catch {
+                return invalidCursor();
+            }
+            if (typeof cursor.revision !== "string") {
+                return invalidCursor();
+            }
+            checkRevision(catalog.revision, cursor.revision);
+            if (cursor.scope !== scope || cursor.request !== request || typeof cursor.last !== "string") {
+                return invalidCursor();
+            }
+            const position = items.findIndex(({ ref }) => ref === cursor.last);
+            if (position < 0) {
+                return invalidCursor();
+            }
+            start = position + 1;
+        }
+        const cursorAfter = (last) => Buffer.from(JSON.stringify({
+            revision: catalog.revision,
+            scope,
+            request,
+            last,
+        })).toString("base64url");
+        const selected = [];
+        let result = { revision: catalog.revision, pages: selected, next_cursor: null };
+        for (const item of items.slice(start, start + (input.limit ?? 20))) {
+            const candidate = [...selected, item];
+            const next = {
+                revision: catalog.revision,
+                pages: candidate,
+                next_cursor: start + candidate.length < items.length ? cursorAfter(item.ref) : null,
+            };
+            if (discoveryResultBytes(next) > NAVIGATION_CATALOG_LIMITS.responseBytes) {
+                if (selected.length === 0) {
+                    return unavailable(new Error("A complete navigation result exceeds the MCP response budget."));
+                }
+                break;
+            }
+            selected.push(item);
+            result = next;
+        }
+        return result;
+    };
+}

package/dist/service/oauth/protocol.d.ts

@@ -0,0 +1,70 @@
+import { Effect } from "effect";
+import type { HttpServerRequest } from "effect/unstable/http";
+import type { Principal } from "../../runtime.js";
+import type { OAuthStore } from "../runtime-contract.js";
+import type { VerifiedCaller } from "../caller-context.js";
+/** Access tokens: `sso_` and 43 characters of base64url, isolated by their grant's resource. */
+export declare const ACCESS_TOKEN_PREFIX = "sso_";
+/** First-party app sessions have a resource distinct from every MCP grant. */
+export declare const APP_SESSION_RESOURCE_PATH = "/api/ontology/session";
+export declare const REFRESH_TOKEN_PREFIX = "ssr_";
+export declare const CODE_PREFIX = "ssc_";
+export declare const CLIENT_ID_PREFIX = "ssa_";
+export declare const CLIENT_SECRET_PREFIX = "sss_";
+export declare const ACCESS_TOKEN_TTL_MS: number;
+export declare const REFRESH_TOKEN_TTL_MS: number;
+export declare const CODE_TTL_MS: number;
+/** How long a member has to sign in and decide. */
+export declare const REQUEST_TTL_MS: number;
+/** Everything the member may do. */
+export declare const FULL_SCOPE = "ontology";
+/** Only the reads of what the member may do. */
+export declare const READ_SCOPE = "ontology:read";
+export declare const SCOPES: readonly ["ontology", "ontology:read"];
+export type Scope = (typeof SCOPES)[number];
+/** The well-known path of the MCP server's protected resource metadata (RFC 9728). */
+export declare const PROTECTED_RESOURCE_PATH = "/.well-known/oauth-protected-resource";
+/** The well-known path of the authorization server metadata (RFC 8414). */
+export declare const AUTHORIZATION_SERVER_PATH = "/.well-known/oauth-authorization-server";
+/** The app's page where a signed-in member approves or denies a request. */
+export declare const CONSENT_PATH = "/oauth/consent";
+/** 32 random bytes, base64url, after a prefix that says what the value is. */
+export declare function newSecret(prefix?: string): string;
+/** SHA-256 in hex: how codes, tokens and client secrets are stored. */
+export declare function secretHash(value: string): string;
+/** URL serialization preserves the resource boundary while normalizing host case and default ports. */
+export declare function sameResource(left: string, right: string): boolean;
+export declare function appSessionResource(origin: string): string;
+type AccessRejection = "token_not_found" | "token_expired" | "grant_revoked" | "resource_mismatch" | "member_unavailable" | "client_unavailable" | "unsupported_route" | "oauth_unavailable";
+export declare function rejectedAccessToken(reason: AccessRejection, grantId?: string): Effect.Effect<undefined, never, never>;
+export declare function sameSecret(value: string, hash: string): boolean;
+/** Whether a PKCE verifier answers an S256 challenge (RFC 7636). */
+export declare function verifierMatches(verifier: string, challenge: string): boolean;
+/**
+ * The scope a request gets: everything the member may do unless it asks only to read. Scopes this
+ * server does not know are ignored, as clients often ask for the ones they always ask for.
+ */
+export declare function grantedScope(requested: string | undefined): Scope;
+/** The member as a grant of this scope acts: with only their reads under `ontology:read`. */
+export declare function scopedPrincipal(principal: Principal, scope: string): Principal;
+export declare function isLoopback(host: string): boolean;
+/**
+ * The origin the client reached the app on, as Vercel forwards it: the issuer of the authorization
+ * server and the origin of the MCP server's URL. Each domain of the app is its own resource.
+ */
+export declare function publicOrigin(request: HttpServerRequest.HttpServerRequest): string;
+/**
+ * The member an access token acts for, as its grant allows: only for the resource it was issued
+ * for, while the grant stands and the member may still sign in.
+ */
+export declare function callerOfAccessToken(store: OAuthStore, token: string, resource: string): Effect.Effect<{
+    readonly principal: Principal;
+    readonly caller: VerifiedCaller;
+} | undefined>;
+export declare const DEVICE_GRANT = "urn:ietf:params:oauth:grant-type:device_code";
+export declare const DEVICE_TTL_MS: number;
+export declare const DEVICE_INTERVAL = 5;
+/** 32 symbols, five bits per symbol, without ambiguous I/O/0/1. */
+export declare function humanCode(groups?: number): string;
+export declare function normalizedUserCode(value: string): string;
+export {};

package/dist/service/oauth/protocol.js

@@ -0,0 +1,157 @@
+import { createHash, randomBytes, randomInt, timingSafeEqual } from "node:crypto";
+import { Effect } from "effect";
+import { CHANNEL_SESSION_PATH } from "../../channel-session.js";
+import { parsePermission, permissionOf, READ_VERB, WILDCARD } from "../../permissions.js";
+/** Access tokens: `sso_` and 43 characters of base64url, isolated by their grant's resource. */
+export const ACCESS_TOKEN_PREFIX = "sso_";
+/** First-party app sessions have a resource distinct from every MCP grant. */
+export const APP_SESSION_RESOURCE_PATH = CHANNEL_SESSION_PATH;
+export const REFRESH_TOKEN_PREFIX = "ssr_";
+export const CODE_PREFIX = "ssc_";
+export const CLIENT_ID_PREFIX = "ssa_";
+export const CLIENT_SECRET_PREFIX = "sss_";
+export const ACCESS_TOKEN_TTL_MS = 60 * 60 * 1000;
+export const REFRESH_TOKEN_TTL_MS = 30 * 24 * 60 * 60 * 1000;
+export const CODE_TTL_MS = 5 * 60 * 1000;
+/** How long a member has to sign in and decide. */
+export const REQUEST_TTL_MS = 15 * 60 * 1000;
+/** Everything the member may do. */
+export const FULL_SCOPE = "ontology";
+/** Only the reads of what the member may do. */
+export const READ_SCOPE = "ontology:read";
+export const SCOPES = [FULL_SCOPE, READ_SCOPE];
+/** The well-known path of the MCP server's protected resource metadata (RFC 9728). */
+export const PROTECTED_RESOURCE_PATH = "/.well-known/oauth-protected-resource";
+/** The well-known path of the authorization server metadata (RFC 8414). */
+export const AUTHORIZATION_SERVER_PATH = "/.well-known/oauth-authorization-server";
+/** The app's page where a signed-in member approves or denies a request. */
+export const CONSENT_PATH = "/oauth/consent";
+/** 32 random bytes, base64url, after a prefix that says what the value is. */
+export function newSecret(prefix = "") {
+    return `${prefix}${randomBytes(32).toString("base64url")}`;
+}
+/** SHA-256 in hex: how codes, tokens and client secrets are stored. */
+export function secretHash(value) {
+    return createHash("sha256").update(value, "utf8").digest("hex");
+}
+/** URL serialization preserves the resource boundary while normalizing host case and default ports. */
+export function sameResource(left, right) {
+    return URL.canParse(left) && URL.canParse(right) && new URL(left).href === new URL(right).href;
+}
+export function appSessionResource(origin) {
+    return new URL(APP_SESSION_RESOURCE_PATH, origin).href;
+}
+export function rejectedAccessToken(reason, grantId) {
+    return Effect.logWarning("ontology.oauth.access_rejected").pipe(Effect.annotateLogs({ reason, ...(grantId === undefined ? {} : { grantId }) }), Effect.as(undefined));
+}
+export function sameSecret(value, hash) {
+    const left = Buffer.from(secretHash(value), "hex");
+    const right = Buffer.from(hash, "hex");
+    return left.length === right.length && timingSafeEqual(left, right);
+}
+/** Whether a PKCE verifier answers an S256 challenge (RFC 7636). */
+export function verifierMatches(verifier, challenge) {
+    if (!/^[A-Za-z0-9._~-]{43,128}$/.test(verifier)) {
+        return false;
+    }
+    const computed = Buffer.from(createHash("sha256").update(verifier, "ascii").digest("base64url"));
+    const expected = Buffer.from(challenge);
+    return computed.length === expected.length && timingSafeEqual(computed, expected);
+}
+/**
+ * The scope a request gets: everything the member may do unless it asks only to read. Scopes this
+ * server does not know are ignored, as clients often ask for the ones they always ask for.
+ */
+export function grantedScope(requested) {
+    const asked = new Set((requested ?? "").split(" ").filter((scope) => scope !== ""));
+    return asked.has(READ_SCOPE) && !asked.has(FULL_SCOPE) ? READ_SCOPE : FULL_SCOPE;
+}
+/** `lead:*` and `lead:read` keep `lead:read`; `*:*` keeps `*:read`; other verbs go. */
+function readPermissions(permissions) {
+    const reads = permissions.flatMap((permission) => {
+        const parsed = parsePermission(permission);
+        return parsed !== undefined && (parsed.verb === READ_VERB || parsed.verb === WILDCARD)
+            ? [permissionOf(parsed.entity, READ_VERB)]
+            : [];
+    });
+    return [...new Set(reads)];
+}
+/** The member as a grant of this scope acts: with only their reads under `ontology:read`. */
+export function scopedPrincipal(principal, scope) {
+    return scope === READ_SCOPE
+        ? { ...principal, permissions: readPermissions(principal.permissions) }
+        : principal;
+}
+const LOOPBACK_HOSTS = new Set(["localhost", "127.0.0.1", "[::1]"]);
+export function isLoopback(host) {
+    return LOOPBACK_HOSTS.has(host.replace(/:\d+$/, ""));
+}
+/**
+ * The origin the client reached the app on, as Vercel forwards it: the issuer of the authorization
+ * server and the origin of the MCP server's URL. Each domain of the app is its own resource.
+ */
+export function publicOrigin(request) {
+    const forwardedHost = request.headers["x-forwarded-host"] ?? request.headers.host;
+    if (forwardedHost === undefined) {
+        // A web Request without a Host header still carries its absolute URL.
+        return URL.canParse(request.originalUrl)
+            ? new URL(request.originalUrl).origin
+            : "http://localhost";
+    }
+    const host = forwardedHost.split(",")[0].trim();
+    const forwardedProto = request.headers["x-forwarded-proto"]?.split(",")[0]?.trim();
+    const protocol = forwardedProto === "http" || forwardedProto === "https"
+        ? forwardedProto
+        : isLoopback(host)
+            ? "http"
+            : "https";
+    return new URL(`${protocol}://${host}`).origin;
+}
+/**
+ * The member an access token acts for, as its grant allows: only for the resource it was issued
+ * for, while the grant stands and the member may still sign in.
+ */
+export function callerOfAccessToken(store, token, resource) {
+    return Effect.gen(function* () {
+        const grant = yield* store.findAccess(secretHash(token));
+        if (grant === undefined) {
+            return undefined;
+        }
+        if (!sameResource(grant.resource, resource)) {
+            return yield* rejectedAccessToken("resource_mismatch", grant.id);
+        }
+        const member = yield* store.memberPrincipal(grant.userId);
+        const client = yield* store.findClient(grant.clientId);
+        if (member === undefined || member.kind !== "member" || member.id !== grant.userId) {
+            return yield* rejectedAccessToken("member_unavailable", grant.id);
+        }
+        if (client === undefined || client.id !== grant.clientId) {
+            return yield* rejectedAccessToken("client_unavailable", grant.id);
+        }
+        return {
+            principal: {
+                ...scopedPrincipal(member, grant.scope),
+                ...(grant.identityProvider ? { authenticatedVia: grant.identityProvider } : {}),
+            },
+            caller: new URL(grant.resource).pathname === APP_SESSION_RESOURCE_PATH
+                ? { kind: "member", subjectId: member.id }
+                : {
+                    kind: "oauth",
+                    subjectId: member.id,
+                    client: { id: client.id, name: client.name },
+                    scope: grant.scope,
+                },
+        };
+    });
+}
+export const DEVICE_GRANT = "urn:ietf:params:oauth:grant-type:device_code";
+export const DEVICE_TTL_MS = 10 * 60 * 1000;
+export const DEVICE_INTERVAL = 5;
+/** 32 symbols, five bits per symbol, without ambiguous I/O/0/1. */
+export function humanCode(groups = 2) {
+    const alphabet = "ABCDEFGHJKLMNPQRSTUVWXYZ23456789";
+    return Array.from({ length: groups }, () => Array.from({ length: 4 }, () => alphabet[randomInt(alphabet.length)]).join("")).join("-");
+}
+export function normalizedUserCode(value) {
+    return value.toUpperCase().replace(/[\s-]/g, "");
+}

package/dist/service/oauth/refresh-replay.d.ts

@@ -0,0 +1,2 @@
+export declare function encryptReplay(token: string, response: unknown): string;
+export declare function decryptReplay(token: string, encrypted: string): unknown;

package/dist/service/oauth/refresh-replay.js

@@ -0,0 +1,20 @@
+import { createCipheriv, createDecipheriv, createHash, randomBytes } from "node:crypto";
+/** The high-entropy presented token is the key; a database dump cannot recover successors. */
+function key(token) {
+    return createHash("sha256").update("ontology.oauth.refresh-replay.v1\0").update(token).digest();
+}
+export function encryptReplay(token, response) {
+    const nonce = randomBytes(12);
+    const cipher = createCipheriv("aes-256-gcm", key(token), nonce);
+    const ciphertext = Buffer.concat([
+        cipher.update(JSON.stringify(response), "utf8"),
+        cipher.final(),
+    ]);
+    return Buffer.concat([nonce, cipher.getAuthTag(), ciphertext]).toString("base64url");
+}
+export function decryptReplay(token, encrypted) {
+    const bytes = Buffer.from(encrypted, "base64url");
+    const decipher = createDecipheriv("aes-256-gcm", key(token), bytes.subarray(0, 12));
+    decipher.setAuthTag(bytes.subarray(12, 28));
+    return JSON.parse(Buffer.concat([decipher.update(bytes.subarray(28)), decipher.final()]).toString("utf8"));
+}

package/dist/service/oauth/server.d.ts

@@ -0,0 +1,28 @@
+import { Layer } from "effect";
+import { HttpRouter } from "effect/unstable/http";
+import { type TokenVerifier } from "../authentication.js";
+import { RequestId } from "../errors.js";
+import { type RateLimit } from "../rate-limit.js";
+import { OntologyBackend } from "../runtime-contract.js";
+/** The authorization server's endpoints, under the ontology service's path. */
+export declare const OAUTH_PATH = "/api/ontology/oauth";
+/** Registrations one client address may make per minute; each one is a row in the database. */
+export declare const REGISTRATION_LIMIT: RateLimit;
+/** Where the MCP server is, on the origin the client reached. */
+export declare function mcpResource(origin: string): string;
+/**
+ * The `WWW-Authenticate` challenge of the MCP server: it names the protected resource metadata,
+ * which is how a client learns where members authorize it (RFC 9728).
+ */
+export declare function mcpChallenge(origin: string, missing: boolean): string;
+export interface OAuthServerOptions {
+    readonly verifyToken: TokenVerifier;
+    readonly refreshReuseGraceMs?: number;
+}
+/**
+ * The MCP server's OAuth 2.1 authorization server, on the app's own origin: the protected resource
+ * and authorization server metadata, dynamic client registration, the authorization endpoint that
+ * hands the member to the app's consent page, the endpoints the consent page decides with, and the
+ * token and revocation endpoints. Without the OAuth tables, it serves nothing.
+ */
+export declare function oauthLayer(options: OAuthServerOptions): Layer.Layer<never, never, OntologyBackend | HttpRouter.HttpRouter | HttpRouter.Request<"Requires", RequestId>>;