@segmentstream-cloud/ontology 0.9.0 → 0.11.0

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

@@ -0,0 +1,52 @@
+import { Effect } from "effect";
+import type { HttpServerRequest } from "effect/unstable/http";
+import type { Principal } from "../../runtime.js";
+import type { OAuthStore } from "../runtime-contract.js";
+/** Access tokens: `sso_` and 43 characters of base64url. They work only on the MCP server. */
+export declare const ACCESS_TOKEN_PREFIX = "sso_";
+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;
+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 principalOfAccessToken(store: OAuthStore, token: string, resource: string): Effect.Effect<Principal | undefined>;

package/dist/service/oauth/protocol.js

@@ -0,0 +1,110 @@
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+import { Effect } from "effect";
+import { parsePermission, permissionOf, READ_VERB, WILDCARD } from "../../permissions.js";
+/** Access tokens: `sso_` and 43 characters of base64url. They work only on the MCP server. */
+export const ACCESS_TOKEN_PREFIX = "sso_";
+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");
+}
+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 `${protocol}://${host}`;
+}
+/**
+ * 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 principalOfAccessToken(store, token, resource) {
+    return Effect.gen(function* () {
+        const grant = yield* store.findAccess(secretHash(token));
+        if (grant === undefined || grant.resource !== resource) {
+            return undefined;
+        }
+        const member = yield* store.memberPrincipal(grant.userId);
+        return member === undefined ? undefined : scopedPrincipal(member, grant.scope);
+    });
+}

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

@@ -0,0 +1,27 @@
+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;
+}
+/**
+ * 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>>;