@segmentstream/app 0.0.0-stage → 0.38.1

package/dist/channel-session.js

@@ -0,0 +1,89 @@
+import { cookies } from "next/headers";
+import { NextResponse } from "next/server";
+import { CHANNEL_LOGOUT_PATH, channelCookieName, channelCookieAttributes, } from "./channel-protocol.js";
+import { apiErrorFrom, readJson, SegmentStreamApiError } from "./errors.js";
+import { isSameOrigin } from "./decision-pages.js";
+import { parseMe } from "./me.js";
+import { createOntologyTransport, ontologyOrigin } from "./ontology-transport.js";
+export { channelCookieName } from "./channel-protocol.js";
+/** Workspace-owned opaque app sessions; every discovery checks current membership and revocation. */
+export function createChannelSession(options) {
+    const name = channelCookieName(options.workspaceId);
+    const token = async () => {
+        if (!options.enabled) {
+            return null;
+        }
+        const credential = (await cookies()).get(name)?.value;
+        return credential?.startsWith("sso_") ? credential : null;
+    };
+    const transport = createOntologyTransport({
+        ...options,
+        credentials: { token },
+    });
+    const read = async () => {
+        const credential = await token();
+        if (!credential) {
+            return null;
+        }
+        const response = await transport.fetch("/me", { method: "GET" });
+        if (response.status === 401 || response.status === 403) {
+            return null;
+        }
+        const payload = await readJson(response);
+        if (!response.ok) {
+            throw apiErrorFrom(response.status, payload, "session_unavailable");
+        }
+        const user = parseMe(payload);
+        if (!user) {
+            throw new SegmentStreamApiError({
+                code: "ontology_invalid_response",
+                status: 502,
+                detail: "ontology_invalid_response",
+            });
+        }
+        return { token: credential, user };
+    };
+    const signOut = async () => {
+        if (!(await token())) {
+            return;
+        }
+        const origin = await ontologyOrigin(undefined);
+        const response = await transport.fetch(CHANNEL_LOGOUT_PATH.replace("/api/ontology", ""), {
+            method: "POST",
+            headers: { origin },
+        });
+        if (!response.ok) {
+            throw apiErrorFrom(response.status, await readJson(response), "logout_failed");
+        }
+        (await cookies()).set(name, "", { ...channelCookieAttributes, maxAge: 0 });
+    };
+    const proxy = async (request) => {
+        if (!options.enabled) {
+            return undefined;
+        }
+        const credential = request.cookies.get(name)?.value;
+        if (!credential?.startsWith("sso_")) {
+            return undefined;
+        }
+        if (!["GET", "HEAD", "OPTIONS"].includes(request.method) && !isSameOrigin(request)) {
+            return NextResponse.json({ error: "cross_origin_session" }, { status: 403 });
+        }
+        const response = await options.fetch(`${await ontologyOrigin(options.ontologyUrl ?? request.nextUrl.origin)}/api/ontology/me`, {
+            headers: {
+                authorization: `Bearer ${credential}`,
+                "x-forwarded-host": request.nextUrl.host,
+                "x-forwarded-proto": request.nextUrl.protocol.slice(0, -1),
+            },
+            cache: "no-store",
+            redirect: "error",
+        });
+        if (response.ok && parseMe(await readJson(response))) {
+            return NextResponse.next();
+        }
+        if (response.status !== 401 && response.status !== 403) {
+            return NextResponse.json({ error: "session_unavailable" }, { status: 503 });
+        }
+        return undefined;
+    };
+    return { token, transport, read, signOut, proxy };
+}

package/dist/config.d.ts

@@ -0,0 +1,53 @@
+export declare const DEFAULT_BASE_URL = "https://cloud.segmentstream.com";
+export interface SegmentStreamAppConfig {
+    /** The SegmentStream workspace that owns this app. */
+    readonly workspaceId: string;
+    /** The SegmentStream organization that owns the workspace. */
+    readonly organizationId: string;
+    /** SegmentStream origin. Defaults to `SEGMENTSTREAM_URL`, then `https://cloud.segmentstream.com`. */
+    readonly baseUrl?: string;
+    /** Explicit channel app opt-in; omitted providers stay disabled. */
+    readonly channels?: Readonly<Record<string, boolean>>;
+}
+export interface ResolvedConfig {
+    readonly workspaceId: string;
+    readonly organizationId: string;
+    readonly baseUrl: string;
+    readonly issuer: string;
+    readonly channels?: Readonly<Record<string, boolean>>;
+}
+/** Environment variables, `process.env` unless a test supplies its own. */
+export type Environment = Readonly<Record<string, string | undefined>>;
+export declare function processEnvironment(): Environment;
+/** Neon Auth for the app's users, configured when `NEON_AUTH_BASE_URL` is set. */
+export interface NeonAuthEnvironment {
+    /** `NEON_AUTH_BASE_URL`: the branch's Auth URL. */
+    readonly baseUrl: string;
+    /** `SEGMENTSTREAM_APP_AUTH_COOKIE_SECRET`: signs the session cache cookie. */
+    readonly cookieSecret: string | undefined;
+    /** `SEGMENTSTREAM_ONTOLOGY_URL`: the ontology service when it is not beside the app. */
+    readonly ontologyUrl: string | undefined;
+}
+export declare function resolveConfig(config: SegmentStreamAppConfig, environment?: Environment): ResolvedConfig;
+/** `null` without `NEON_AUTH_BASE_URL`: the app then signs in with SegmentStream, as in 0.2. */
+export declare function resolveNeonAuth(environment: Environment): NeonAuthEnvironment | null;
+/** Linear-time trailing slash removal; `/\/+$/` backtracks quadratically on slash runs. */
+export declare function trimTrailingSlashes(value: string): string;
+/** A variable's trimmed value; unset and blank are the same. */
+export declare function environmentValue(environment: Environment, name: string): string | undefined;
+/** Opt-ins are booleans, separate from ontology admission policy. */
+export declare function hasChannelApps(channels: Readonly<Record<string, boolean>> | undefined): boolean;
+/** Derived from the deployed ontology; never authored as an app-side override. */
+export interface BrowserAuthBinding {
+    readonly version: 1;
+    readonly manifest_digest: string;
+    readonly browser: {
+        readonly methods: readonly ("email" | "segmentstream")[];
+        readonly primary: "email" | "segmentstream";
+        readonly auto_redirect: boolean;
+        readonly local?: {
+            readonly port: number;
+        };
+    };
+}
+export declare function resolveBrowserAuth(environment: Environment): BrowserAuthBinding | undefined;

package/dist/config.js

@@ -0,0 +1,112 @@
+export const DEFAULT_BASE_URL = "https://cloud.segmentstream.com";
+export function processEnvironment() {
+    return typeof process === "undefined" ? {} : process.env;
+}
+export function resolveConfig(config, environment = processEnvironment()) {
+    const workspaceId = requireIdentifier("workspaceId", config.workspaceId);
+    const organizationId = requireIdentifier("organizationId", config.organizationId);
+    const baseUrl = normalizeBaseUrl(config.baseUrl ?? environmentValue(environment, "SEGMENTSTREAM_URL") ?? DEFAULT_BASE_URL);
+    const issuer = environmentValue(environment, "SEGMENTSTREAM_APP_TOKEN_ISSUER") ?? new URL(baseUrl).origin;
+    return {
+        workspaceId,
+        organizationId,
+        baseUrl,
+        issuer,
+        ...(config.channels ? { channels: config.channels } : {}),
+    };
+}
+/** `null` without `NEON_AUTH_BASE_URL`: the app then signs in with SegmentStream, as in 0.2. */
+export function resolveNeonAuth(environment) {
+    const baseUrl = environmentValue(environment, "NEON_AUTH_BASE_URL");
+    if (baseUrl === undefined) {
+        return null;
+    }
+    const ontologyUrl = environmentValue(environment, "SEGMENTSTREAM_ONTOLOGY_URL");
+    return {
+        baseUrl: normalizeUrl("NEON_AUTH_BASE_URL", baseUrl),
+        cookieSecret: environmentValue(environment, "SEGMENTSTREAM_APP_AUTH_COOKIE_SECRET"),
+        ontologyUrl: ontologyUrl === undefined
+            ? undefined
+            : new URL(normalizeUrl("SEGMENTSTREAM_ONTOLOGY_URL", ontologyUrl)).origin,
+    };
+}
+function requireIdentifier(name, value) {
+    const trimmed = typeof value === "string" ? value.trim() : "";
+    if (trimmed === "") {
+        throw new Error(`createSegmentStreamApp requires a non-empty ${name}.`);
+    }
+    return trimmed;
+}
+/** Linear-time trailing slash removal; `/\/+$/` backtracks quadratically on slash runs. */
+export function trimTrailingSlashes(value) {
+    let end = value.length;
+    while (end > 0 && value.charCodeAt(end - 1) === 47) {
+        end -= 1;
+    }
+    return value.slice(0, end);
+}
+function normalizeBaseUrl(value) {
+    return normalizeUrl("SegmentStream base URL", value);
+}
+function normalizeUrl(name, value) {
+    const trimmed = trimTrailingSlashes(value.trim());
+    let url;
+    try {
+        url = new URL(trimmed);
+    }
+    catch (error) {
+        throw new Error(`${name} is not a valid URL: ${trimmed}`, { cause: error });
+    }
+    if (url.protocol !== "https:" && url.protocol !== "http:") {
+        throw new Error(`${name} must use http or https: ${trimmed}`);
+    }
+    return trimmed;
+}
+/** A variable's trimmed value; unset and blank are the same. */
+export function environmentValue(environment, name) {
+    const value = environment[name];
+    return value === undefined || value.trim() === "" ? undefined : value.trim();
+}
+/** Opt-ins are booleans, separate from ontology admission policy. */
+export function hasChannelApps(channels) {
+    return Object.values(channels ?? {}).some((enabled) => enabled === true);
+}
+export function resolveBrowserAuth(environment) {
+    const raw = environmentValue(environment, "SEGMENTSTREAM_BROWSER_AUTH");
+    if (!raw)
+        return undefined;
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch (cause) {
+        throw new Error("browser_auth_configuration_invalid", { cause });
+    }
+    if (!value || typeof value !== "object")
+        throw new Error("browser_auth_configuration_invalid");
+    const binding = value;
+    const browser = binding.browser;
+    if (binding.version !== 1 ||
+        typeof binding.manifest_digest !== "string" ||
+        !binding.manifest_digest ||
+        !browser ||
+        !Array.isArray(browser.methods) ||
+        browser.methods.length === 0 ||
+        browser.methods.some((method) => method !== "email" && method !== "segmentstream") ||
+        new Set(browser.methods).size !== browser.methods.length ||
+        !browser.methods.includes(browser.primary) ||
+        typeof browser.auto_redirect !== "boolean" ||
+        (browser.auto_redirect &&
+            (browser.methods.length !== 1 || browser.methods[0] !== "segmentstream")) ||
+        (browser.local !== undefined &&
+            (!browser.methods.includes("segmentstream") ||
+                !browser.local ||
+                typeof browser.local !== "object" ||
+                Array.isArray(browser.local) ||
+                !Number.isInteger(browser.local.port) ||
+                browser.local.port < 1 ||
+                browser.local.port > 65535))) {
+        throw new Error("browser_auth_configuration_invalid");
+    }
+    return binding;
+}

package/dist/context.d.ts

@@ -0,0 +1,10 @@
+import type { ResolvedConfig } from "./config.js";
+import type { TokenExchange, TokenGrant } from "./sessions.js";
+import type { TokenVerification } from "./tokens.js";
+/** The resolved configuration and capabilities shared by the proxy, handlers, and server helpers. */
+export interface AppContext {
+    readonly config: ResolvedConfig;
+    readonly verifyToken: (token: string) => Promise<TokenVerification>;
+    readonly requestToken: (grant: TokenGrant) => Promise<TokenExchange>;
+    readonly revokeSession: (refreshToken: string) => Promise<void>;
+}

package/dist/context.js

@@ -0,0 +1 @@
+export {};

package/dist/cookies.d.ts

@@ -0,0 +1,56 @@
+import type { NextResponse } from "next/server";
+export { safeReturnTo } from "./return-to.js";
+export declare const REFRESH_COOKIE_MAX_AGE_SECONDS: number;
+export declare const AUTH_FLOW_COOKIE_MAX_AGE_SECONDS: number;
+/** Sign-ins one browser can have in progress at once; one more abandons them all. */
+export declare const MAX_PENDING_AUTH_FLOWS = 4;
+export interface CookieNames {
+    readonly session: string;
+    readonly refresh: string;
+    /** Each sign-in in progress has its own cookie: this prefix followed by its `state`. */
+    readonly authFlowPrefix: string;
+}
+/** Cookie names and attributes for one app on one request origin. */
+export interface CookiePolicy {
+    readonly secure: boolean;
+    readonly names: CookieNames;
+}
+/** The PKCE flow state kept between starting sign-in and the callback. */
+export interface AuthFlowState {
+    readonly state: string;
+    readonly codeVerifier: string;
+    readonly redirectUri: string;
+    readonly returnTo: string;
+}
+export interface SessionTokens {
+    readonly accessToken: string;
+    readonly expiresIn: number;
+    readonly refreshToken: string;
+}
+export declare function isLoopbackHostname(hostname: string): boolean;
+/**
+ * Browsers reject `Secure` and `__Host-` cookies on plain-HTTP origins, except that
+ * local development on http://localhost should still work. Every other origin uses
+ * `__Host-` cookies, which cannot be set by sibling subdomains.
+ *
+ * Browsers share cookies between ports, so apps on `localhost:3000` and `localhost:3001`
+ * see one cookie jar. Names carry the workspace id to keep each app's session its own.
+ */
+export declare function cookiePolicyFor(url: URL, workspaceId: string): CookiePolicy;
+/** Candidate cookie names for code that only knows the request host (Server Components). */
+export declare function sessionCookieCandidates(hostname: string, workspaceId: string): readonly string[];
+/** The cookie holding one sign-in's flow, or undefined for a `state` this SDK never issues. */
+export declare function authFlowCookieName(policy: CookiePolicy, state: string): string | undefined;
+/** The sign-in flow cookies a request carries, one per sign-in still in progress. */
+export declare function pendingAuthFlowCookies(policy: CookiePolicy, requestCookieNames: readonly string[]): string[];
+export declare function setSessionCookies(response: NextResponse, policy: CookiePolicy, tokens: SessionTokens): void;
+export declare function clearSessionCookies(response: NextResponse, policy: CookiePolicy): void;
+export declare function setAuthFlowCookie(response: NextResponse, policy: CookiePolicy, flow: AuthFlowState): void;
+export declare function clearCookie(response: NextResponse, policy: CookiePolicy, name: string): void;
+export declare function encodeAuthFlowState(flow: AuthFlowState): string;
+export declare function decodeAuthFlowState(value: string | undefined): AuthFlowState | null;
+/**
+ * Replaces the named cookies in a raw `Cookie` request header while preserving every
+ * other cookie byte for byte.
+ */
+export declare function replaceRequestCookies(cookieHeader: string | null, replacements: Record<string, string>): string;

package/dist/cookies.js

@@ -0,0 +1,131 @@
+import { base64UrlDecode, base64UrlEncode } from "./pkce.js";
+import { safeReturnTo } from "./return-to.js";
+export { safeReturnTo } from "./return-to.js";
+export const REFRESH_COOKIE_MAX_AGE_SECONDS = 30 * 24 * 60 * 60;
+export const AUTH_FLOW_COOKIE_MAX_AGE_SECONDS = 10 * 60;
+/** Sign-ins one browser can have in progress at once; one more abandons them all. */
+export const MAX_PENDING_AUTH_FLOWS = 4;
+const SECURE_PREFIX = "__Host-";
+const AUTH_FLOW_STATE = /^[A-Za-z0-9_-]{1,128}$/;
+export function isLoopbackHostname(hostname) {
+    const normalized = hostname.toLowerCase();
+    return (normalized === "localhost" ||
+        normalized.endsWith(".localhost") ||
+        normalized === "[::1]" ||
+        normalized === "::1" ||
+        /^127(?:\.\d{1,3}){3}$/.test(normalized));
+}
+/**
+ * Browsers reject `Secure` and `__Host-` cookies on plain-HTTP origins, except that
+ * local development on http://localhost should still work. Every other origin uses
+ * `__Host-` cookies, which cannot be set by sibling subdomains.
+ *
+ * Browsers share cookies between ports, so apps on `localhost:3000` and `localhost:3001`
+ * see one cookie jar. Names carry the workspace id to keep each app's session its own.
+ */
+export function cookiePolicyFor(url, workspaceId) {
+    const insecureLoopback = url.protocol === "http:" && isLoopbackHostname(url.hostname);
+    return {
+        secure: !insecureLoopback,
+        names: cookieNames(insecureLoopback ? "" : SECURE_PREFIX, workspaceId),
+    };
+}
+/** Candidate cookie names for code that only knows the request host (Server Components). */
+export function sessionCookieCandidates(hostname, workspaceId) {
+    const secure = cookieNames(SECURE_PREFIX, workspaceId).session;
+    return isLoopbackHostname(hostname) ? [secure, cookieNames("", workspaceId).session] : [secure];
+}
+function cookieNames(prefix, workspaceId) {
+    // Workspace ids are UUIDs; anything else is kept to cookie-name characters.
+    const scope = workspaceId.replace(/[^A-Za-z0-9_-]/g, "_");
+    return {
+        session: `${prefix}ss_app_session.${scope}`,
+        refresh: `${prefix}ss_app_refresh.${scope}`,
+        authFlowPrefix: `${prefix}ss_app_auth.${scope}.`,
+    };
+}
+/** The cookie holding one sign-in's flow, or undefined for a `state` this SDK never issues. */
+export function authFlowCookieName(policy, state) {
+    return AUTH_FLOW_STATE.test(state) ? `${policy.names.authFlowPrefix}${state}` : undefined;
+}
+/** The sign-in flow cookies a request carries, one per sign-in still in progress. */
+export function pendingAuthFlowCookies(policy, requestCookieNames) {
+    return requestCookieNames.filter((name) => name.startsWith(policy.names.authFlowPrefix));
+}
+function cookieAttributes(policy, maxAge) {
+    return {
+        httpOnly: true,
+        secure: policy.secure,
+        sameSite: "lax",
+        path: "/",
+        maxAge,
+    };
+}
+export function setSessionCookies(response, policy, tokens) {
+    const accessMaxAge = Math.max(1, Math.floor(tokens.expiresIn));
+    response.cookies.set(policy.names.session, tokens.accessToken, cookieAttributes(policy, accessMaxAge));
+    response.cookies.set(policy.names.refresh, tokens.refreshToken, cookieAttributes(policy, REFRESH_COOKIE_MAX_AGE_SECONDS));
+}
+export function clearSessionCookies(response, policy) {
+    clearCookie(response, policy, policy.names.session);
+    clearCookie(response, policy, policy.names.refresh);
+}
+export function setAuthFlowCookie(response, policy, flow) {
+    response.cookies.set(`${policy.names.authFlowPrefix}${flow.state}`, encodeAuthFlowState(flow), cookieAttributes(policy, AUTH_FLOW_COOKIE_MAX_AGE_SECONDS));
+}
+// `__Host-` cookies are only replaced when the clearing cookie repeats Secure and Path=/.
+export function clearCookie(response, policy, name) {
+    response.cookies.set(name, "", { ...cookieAttributes(policy, 0), expires: new Date(0) });
+}
+export function encodeAuthFlowState(flow) {
+    return base64UrlEncode(new TextEncoder().encode(JSON.stringify(flow)));
+}
+export function decodeAuthFlowState(value) {
+    if (value === undefined || value === "") {
+        return null;
+    }
+    let candidate;
+    try {
+        candidate = JSON.parse(new TextDecoder().decode(base64UrlDecode(value)));
+    }
+    catch {
+        return null;
+    }
+    if (!isAuthFlowState(candidate)) {
+        return null;
+    }
+    return {
+        state: candidate.state,
+        codeVerifier: candidate.codeVerifier,
+        redirectUri: candidate.redirectUri,
+        returnTo: safeReturnTo(candidate.returnTo),
+    };
+}
+function isAuthFlowState(value) {
+    if (typeof value !== "object" || value === null) {
+        return false;
+    }
+    const record = value;
+    return (typeof record.state === "string" &&
+        typeof record.codeVerifier === "string" &&
+        typeof record.redirectUri === "string" &&
+        typeof record.returnTo === "string");
+}
+/**
+ * Replaces the named cookies in a raw `Cookie` request header while preserving every
+ * other cookie byte for byte.
+ */
+export function replaceRequestCookies(cookieHeader, replacements) {
+    const replacedNames = new Set(Object.keys(replacements));
+    const preserved = (cookieHeader ?? "")
+        .split(";")
+        .map((pair) => pair.trim())
+        .filter((pair) => pair !== "")
+        .filter((pair) => !replacedNames.has(cookiePairName(pair)));
+    const replaced = Object.entries(replacements).map(([name, value]) => `${name}=${value}`);
+    return [...preserved, ...replaced].join("; ");
+}
+function cookiePairName(pair) {
+    const separator = pair.indexOf("=");
+    return (separator === -1 ? pair : pair.slice(0, separator)).trim();
+}