@segmentstream-cloud/app 0.0.0-stage → 0.1.0

package/dist/handlers.js

@@ -0,0 +1,133 @@
+import { NextResponse } from "next/server";
+import { clearAuthFlowCookie, clearSessionCookies, cookiePolicyFor, decodeAuthFlowState, safeReturnTo, setSessionCookies, } from "./cookies.js";
+import { constantTimeEqual } from "./pkce.js";
+import { CALLBACK_PATH, SIGNED_OUT_PATH, SIGN_IN_PATH, SDK_ROUTE_PREFIX, signInRedirect, } from "./sign-in.js";
+export function createHandlers(context) {
+    async function GET(request) {
+        switch (request.nextUrl.pathname) {
+            case CALLBACK_PATH:
+                return handleCallback(context, request);
+            case SIGN_IN_PATH:
+                return signInRedirect({
+                    config: context.config,
+                    request,
+                    returnTo: safeReturnTo(request.nextUrl.searchParams.get("returnTo")),
+                    clearSession: false,
+                });
+            case SIGNED_OUT_PATH:
+                return htmlResponse(200, "You're signed out", "You have signed out of this app.", "Sign in again");
+            default:
+                return notFound();
+        }
+    }
+    async function POST(request) {
+        if (request.nextUrl.pathname === `${SDK_ROUTE_PREFIX}/sign-out`) {
+            return handleSignOut(context, request);
+        }
+        return notFound();
+    }
+    return { GET, POST };
+}
+async function handleCallback(context, request) {
+    const policy = cookiePolicyFor(request.nextUrl);
+    const flow = decodeAuthFlowState(request.cookies.get(policy.names.authFlow)?.value);
+    const code = request.nextUrl.searchParams.get("code");
+    const state = request.nextUrl.searchParams.get("state");
+    if (request.nextUrl.searchParams.get("error") === "access_denied") {
+        return callbackFailure(policy, 403, "You don't have access to this app.");
+    }
+    if (flow === null ||
+        code === null ||
+        code === "" ||
+        state === null ||
+        !constantTimeEqual(state, flow.state)) {
+        return callbackFailure(policy, 400, "This sign-in link is invalid or has expired.");
+    }
+    const exchange = await context.requestToken({
+        grantType: "authorization_code",
+        code,
+        codeVerifier: flow.codeVerifier,
+        redirectUri: flow.redirectUri,
+    });
+    if (exchange.status === "unavailable") {
+        return callbackFailure(policy, 503, "Sign-in is temporarily unavailable. Try again in a moment.");
+    }
+    if (exchange.status === "rejected") {
+        const accessRevoked = exchange.httpStatus === 403 || exchange.code === "access_revoked";
+        return accessRevoked
+            ? callbackFailure(policy, 403, "You don't have access to this app.")
+            : callbackFailure(policy, 400, "Sign-in could not be completed. Try again.");
+    }
+    // A token this app would reject must not become a session, or sign-in would loop.
+    const verification = await context.verifyToken(exchange.tokens.accessToken);
+    if (verification.status === "unavailable") {
+        return callbackFailure(policy, 503, "Sign-in is temporarily unavailable. Try again in a moment.");
+    }
+    if (verification.status !== "valid") {
+        return callbackFailure(policy, 400, "Sign-in returned a session for a different app.");
+    }
+    const response = NextResponse.redirect(new URL(flow.returnTo, request.nextUrl.origin), 303);
+    response.headers.set("cache-control", "no-store");
+    clearAuthFlowCookie(response, policy);
+    setSessionCookies(response, policy, exchange.tokens);
+    return response;
+}
+async function handleSignOut(context, request) {
+    const origin = request.headers.get("origin");
+    if (origin !== null && origin !== request.nextUrl.origin) {
+        return htmlResponse(403, "Sign-out refused", "Sign out from this app's own pages.", "Return to the app");
+    }
+    const policy = cookiePolicyFor(request.nextUrl);
+    const refreshToken = request.cookies.get(policy.names.refresh)?.value;
+    if (refreshToken !== undefined && refreshToken !== "") {
+        await context.revokeSession(refreshToken);
+    }
+    const response = NextResponse.redirect(new URL(SIGNED_OUT_PATH, request.nextUrl.origin), 303);
+    response.headers.set("cache-control", "no-store");
+    clearSessionCookies(response, policy);
+    clearAuthFlowCookie(response, policy);
+    return response;
+}
+function callbackFailure(policy, status, message) {
+    const response = htmlResponse(status, "Sign-in failed", message, "Try again");
+    clearAuthFlowCookie(response, policy);
+    return response;
+}
+function notFound() {
+    return NextResponse.json({ error: "not_found" }, { status: 404, headers: { "cache-control": "no-store" } });
+}
+function htmlResponse(status, title, message, linkLabel) {
+    const body = [
+        "<!doctype html>",
+        '<html lang="en">',
+        "<head>",
+        '<meta charset="utf-8">',
+        '<meta name="viewport" content="width=device-width, initial-scale=1">',
+        '<meta name="robots" content="noindex">',
+        `<title>${escapeHtml(title)}</title>`,
+        "<style>body{font-family:system-ui,sans-serif;max-width:32rem;margin:15vh auto;padding:0 1rem;}</style>",
+        "</head>",
+        "<body>",
+        `<h1>${escapeHtml(title)}</h1>`,
+        `<p>${escapeHtml(message)}</p>`,
+        `<p><a href="/">${escapeHtml(linkLabel)}</a></p>`,
+        "</body>",
+        "</html>",
+    ].join("\n");
+    return new NextResponse(body, {
+        status,
+        headers: {
+            "content-type": "text/html; charset=utf-8",
+            "cache-control": "no-store",
+            "x-content-type-options": "nosniff",
+        },
+    });
+}
+function escapeHtml(value) {
+    return value
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&#39;");
+}

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+import type { SegmentStreamApp } from "./app.js";
+import type { SegmentStreamAppConfig } from "./config.js";
+/**
+ * Creates the SegmentStream sign-in integration for a Next.js workspace app.
+ *
+ * ```ts
+ * export const segmentstream = createSegmentStreamApp({
+ *   workspaceId: "wsp_...",
+ *   organizationId: "org_...",
+ * });
+ * ```
+ */
+export declare function createSegmentStreamApp(config: SegmentStreamAppConfig): SegmentStreamApp;
+export type { SegmentStreamApp } from "./app.js";
+export type { SegmentStreamAppConfig } from "./config.js";
+export type { SegmentStreamRouteHandlers, RouteHandler } from "./handlers.js";
+export type { ProxyOptions, SegmentStreamProxy } from "./proxy.js";
+export type { AppUser } from "./tokens.js";

package/dist/index.js

@@ -0,0 +1,14 @@
+import { createApp } from "./app.js";
+/**
+ * Creates the SegmentStream sign-in integration for a Next.js workspace app.
+ *
+ * ```ts
+ * export const segmentstream = createSegmentStreamApp({
+ *   workspaceId: "wsp_...",
+ *   organizationId: "org_...",
+ * });
+ * ```
+ */
+export function createSegmentStreamApp(config) {
+    return createApp(config);
+}

package/dist/pkce.d.ts

@@ -0,0 +1,8 @@
+export declare function base64UrlEncode(bytes: Uint8Array): string;
+export declare function base64UrlDecode(value: string): Uint8Array;
+/** A URL-safe random value carrying `byteLength` bytes of entropy. */
+export declare function randomToken(byteLength?: number): string;
+/** The RFC 7636 S256 code challenge for a code verifier. */
+export declare function createCodeChallenge(codeVerifier: string): Promise<string>;
+/** Compares two strings without short-circuiting on the first differing character. */
+export declare function constantTimeEqual(left: string, right: string): boolean;

package/dist/pkce.js

@@ -0,0 +1,40 @@
+// Web Crypto only, so the same code runs in the Node.js and Edge runtimes.
+export function base64UrlEncode(bytes) {
+    let binary = "";
+    for (const byte of bytes) {
+        binary += String.fromCharCode(byte);
+    }
+    return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+export function base64UrlDecode(value) {
+    const base64 = value.replace(/-/g, "+").replace(/_/g, "/");
+    const padded = base64 + "=".repeat((4 - (base64.length % 4)) % 4);
+    const binary = atob(padded);
+    const bytes = new Uint8Array(binary.length);
+    for (let index = 0; index < binary.length; index += 1) {
+        bytes[index] = binary.charCodeAt(index);
+    }
+    return bytes;
+}
+/** A URL-safe random value carrying `byteLength` bytes of entropy. */
+export function randomToken(byteLength = 32) {
+    const bytes = new Uint8Array(byteLength);
+    crypto.getRandomValues(bytes);
+    return base64UrlEncode(bytes);
+}
+/** The RFC 7636 S256 code challenge for a code verifier. */
+export async function createCodeChallenge(codeVerifier) {
+    const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(codeVerifier));
+    return base64UrlEncode(new Uint8Array(digest));
+}
+/** Compares two strings without short-circuiting on the first differing character. */
+export function constantTimeEqual(left, right) {
+    if (left.length !== right.length) {
+        return false;
+    }
+    let difference = 0;
+    for (let index = 0; index < left.length; index += 1) {
+        difference |= left.charCodeAt(index) ^ right.charCodeAt(index);
+    }
+    return difference === 0;
+}

package/dist/proxy.d.ts

@@ -0,0 +1,13 @@
+import { NextResponse } from "next/server";
+import type { NextRequest } from "next/server";
+import type { AppContext } from "./context.js";
+export interface ProxyOptions {
+    /**
+     * Paths that do not require a signed-in user. Each entry matches itself and everything
+     * below it on path-segment boundaries: `/health` matches `/health` and `/health/db`,
+     * not `/healthy`.
+     */
+    readonly publicPaths?: readonly string[];
+}
+export type SegmentStreamProxy = (request: NextRequest) => Promise<NextResponse>;
+export declare function createProxy(context: AppContext, options?: ProxyOptions): SegmentStreamProxy;

package/dist/proxy.js

@@ -0,0 +1,91 @@
+import { NextResponse } from "next/server";
+import { trimTrailingSlashes } from "./config.js";
+import { clearSessionCookies, cookiePolicyFor, replaceRequestCookies, safeReturnTo, setSessionCookies, } from "./cookies.js";
+import { SDK_ROUTE_PREFIX, isApiRequest, signInRedirect, unauthenticatedResponse, } from "./sign-in.js";
+export function createProxy(context, options = {}) {
+    const publicPaths = (options.publicPaths ?? []).map(normalizePublicPath);
+    return async function proxy(request) {
+        const pathname = request.nextUrl.pathname;
+        if (matchesPathPrefix(pathname, SDK_ROUTE_PREFIX) ||
+            publicPaths.some((path) => matchesPathPrefix(pathname, path))) {
+            return NextResponse.next();
+        }
+        const policy = cookiePolicyFor(request.nextUrl);
+        const accessToken = request.cookies.get(policy.names.session)?.value;
+        if (accessToken !== undefined && accessToken !== "") {
+            const verification = await context.verifyToken(accessToken);
+            if (verification.status === "valid") {
+                return NextResponse.next();
+            }
+        }
+        const refreshToken = request.cookies.get(policy.names.refresh)?.value;
+        if (refreshToken === undefined || refreshToken === "") {
+            return startSignIn(context, request, accessToken !== undefined);
+        }
+        const exchange = await context.requestToken({ grantType: "refresh_token", refreshToken });
+        if (exchange.status === "rejected") {
+            return startSignIn(context, request, true);
+        }
+        if (exchange.status === "unavailable") {
+            return sessionUnavailable(context, request);
+        }
+        const verification = await context.verifyToken(exchange.tokens.accessToken);
+        if (verification.status === "valid") {
+            return continueWithSession(request, policy, exchange.tokens);
+        }
+        if (verification.status === "unavailable") {
+            // The refresh token was rotated; keep the new one even though this request cannot proceed.
+            const response = await sessionUnavailable(context, request);
+            setSessionCookies(response, policy, exchange.tokens);
+            return response;
+        }
+        return startSignIn(context, request, true);
+    };
+}
+/**
+ * SegmentStream is unreachable. API requests get a retryable 503; pages restart sign-in,
+ * which ends on the callback's error page rather than looping. Session cookies are kept.
+ */
+async function sessionUnavailable(context, request) {
+    if (isApiRequest(request)) {
+        return NextResponse.json({ error: "session_refresh_unavailable" }, { status: 503, headers: { "cache-control": "no-store", "retry-after": "5" } });
+    }
+    return startSignIn(context, request, false);
+}
+async function startSignIn(context, request, clearSession) {
+    if (isApiRequest(request)) {
+        const response = unauthenticatedResponse();
+        if (clearSession) {
+            clearSessionCookies(response, cookiePolicyFor(request.nextUrl));
+        }
+        return response;
+    }
+    const returnTo = safeReturnTo(`${request.nextUrl.pathname}${request.nextUrl.search}`);
+    return signInRedirect({ config: context.config, request, returnTo, clearSession });
+}
+/**
+ * Lets the current request render with the refreshed session. Response cookies set
+ * through `NextResponse.cookies` are merged into `cookies()` by Next.js, and the
+ * rewritten `Cookie` request header covers Route Handlers that read `request.cookies`.
+ */
+function continueWithSession(request, policy, tokens) {
+    const requestHeaders = new Headers(request.headers);
+    requestHeaders.set("cookie", replaceRequestCookies(request.headers.get("cookie"), {
+        [policy.names.session]: tokens.accessToken,
+        [policy.names.refresh]: tokens.refreshToken,
+    }));
+    const response = NextResponse.next({ request: { headers: requestHeaders } });
+    setSessionCookies(response, policy, tokens);
+    return response;
+}
+function normalizePublicPath(path) {
+    const withLeadingSlash = path.startsWith("/") ? path : `/${path}`;
+    const trimmed = trimTrailingSlashes(withLeadingSlash);
+    return trimmed === "" ? "/" : trimmed;
+}
+function matchesPathPrefix(pathname, prefix) {
+    if (prefix === "/") {
+        return true;
+    }
+    return pathname === prefix || pathname.startsWith(`${prefix}/`);
+}

package/dist/server.d.ts

@@ -0,0 +1,8 @@
+import type { AppContext } from "./context.js";
+import type { AppUser } from "./tokens.js";
+export interface ServerSession {
+    readonly getUser: () => Promise<AppUser | null>;
+    readonly requireUser: () => Promise<AppUser>;
+    readonly getAccessToken: () => Promise<string | null>;
+}
+export declare function createServerSession(context: AppContext): ServerSession;

package/dist/server.js

@@ -0,0 +1,50 @@
+import { cookies, headers } from "next/headers";
+import { redirect } from "next/navigation";
+import { sessionCookieCandidates } from "./cookies.js";
+import { SIGN_IN_PATH } from "./sign-in.js";
+export function createServerSession(context) {
+    async function verifiedSession() {
+        const cookieStore = await cookies();
+        const headerStore = await headers();
+        const hostname = hostnameOf(headerStore.get("host"));
+        for (const name of sessionCookieCandidates(hostname)) {
+            const token = cookieStore.get(name)?.value;
+            if (token === undefined || token === "") {
+                continue;
+            }
+            const verification = await context.verifyToken(token);
+            if (verification.status === "valid") {
+                return verification;
+            }
+        }
+        return null;
+    }
+    async function getUser() {
+        const session = await verifiedSession();
+        return session?.user ?? null;
+    }
+    async function requireUser() {
+        const user = await getUser();
+        if (user === null) {
+            // `unauthorized()` needs the experimental `authInterrupts` flag, so restart sign-in instead.
+            redirect(SIGN_IN_PATH);
+        }
+        return user;
+    }
+    async function getAccessToken() {
+        const session = await verifiedSession();
+        return session?.token ?? null;
+    }
+    return { getUser, requireUser, getAccessToken };
+}
+function hostnameOf(host) {
+    if (host === null || host === "") {
+        return "";
+    }
+    try {
+        return new URL(`http://${host}`).hostname;
+    }
+    catch {
+        return "";
+    }
+}

package/dist/sessions.d.ts

@@ -0,0 +1,27 @@
+import type { ResolvedConfig } from "./config.js";
+import type { SessionTokens } from "./cookies.js";
+export type Fetch = typeof fetch;
+export type TokenGrant = {
+    readonly grantType: "authorization_code";
+    readonly code: string;
+    readonly codeVerifier: string;
+    readonly redirectUri: string;
+} | {
+    readonly grantType: "refresh_token";
+    readonly refreshToken: string;
+};
+export type TokenExchange = {
+    readonly status: "issued";
+    readonly tokens: SessionTokens;
+} | {
+    readonly status: "rejected";
+    readonly httpStatus: number;
+    readonly code: string | null;
+} | {
+    readonly status: "unavailable";
+};
+/** Calls the SegmentStream app-session endpoints from the app's server. */
+export declare function createSessionClient(config: ResolvedConfig, fetchImplementation: Fetch): {
+    requestToken: (grant: TokenGrant) => Promise<TokenExchange>;
+    revoke: (refreshToken: string) => Promise<void>;
+};

package/dist/sessions.js

@@ -0,0 +1,72 @@
+const REQUEST_TIMEOUT_MS = 10_000;
+/** Calls the SegmentStream app-session endpoints from the app's server. */
+export function createSessionClient(config, fetchImplementation) {
+    async function post(path, body) {
+        return fetchImplementation(`${config.baseUrl}${path}`, {
+            method: "POST",
+            headers: { "content-type": "application/json", accept: "application/json" },
+            body: JSON.stringify(body),
+            cache: "no-store",
+            redirect: "error",
+            signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        });
+    }
+    async function requestToken(grant) {
+        let response;
+        try {
+            response = await post("/api/v1/app-sessions/token", grant);
+        }
+        catch {
+            return { status: "unavailable" };
+        }
+        const body = await readJson(response);
+        if (response.ok) {
+            const tokens = sessionTokensFrom(body);
+            return tokens === null ? { status: "unavailable" } : { status: "issued", tokens };
+        }
+        if (response.status >= 500 || response.status === 429) {
+            return { status: "unavailable" };
+        }
+        return { status: "rejected", httpStatus: response.status, code: errorCodeFrom(body) };
+    }
+    async function revoke(refreshToken) {
+        try {
+            const response = await post("/api/v1/app-sessions/revoke", { refreshToken });
+            await response.body?.cancel();
+        }
+        catch {
+            // Sign-out is best effort: the local cookies are cleared either way.
+        }
+    }
+    return { requestToken, revoke };
+}
+async function readJson(response) {
+    try {
+        return await response.json();
+    }
+    catch {
+        return null;
+    }
+}
+function sessionTokensFrom(body) {
+    if (typeof body !== "object" || body === null) {
+        return null;
+    }
+    const { accessToken, expiresIn, refreshToken } = body;
+    if (typeof accessToken !== "string" ||
+        typeof refreshToken !== "string" ||
+        typeof expiresIn !== "number") {
+        return null;
+    }
+    if (accessToken === "" || refreshToken === "" || !Number.isFinite(expiresIn) || expiresIn <= 0) {
+        return null;
+    }
+    return { accessToken, expiresIn, refreshToken };
+}
+function errorCodeFrom(body) {
+    if (typeof body !== "object" || body === null) {
+        return null;
+    }
+    const { error } = body;
+    return typeof error === "string" ? error : null;
+}

package/dist/sign-in.d.ts

@@ -0,0 +1,28 @@
+import { NextResponse } from "next/server";
+import type { NextRequest } from "next/server";
+import type { ResolvedConfig } from "./config.js";
+export declare const SDK_ROUTE_PREFIX = "/api/segmentstream";
+export declare const CALLBACK_PATH = "/api/segmentstream/callback";
+export declare const SIGN_IN_PATH = "/api/segmentstream/sign-in";
+export declare const SIGNED_OUT_PATH = "/api/segmentstream/signed-out";
+/**
+ * Requests that cannot follow a cross-origin sign-in redirect: anything other than a
+ * top-level page navigation. They receive a 401 instead of a redirect.
+ */
+export declare function isApiRequest(request: NextRequest): boolean;
+export declare function unauthenticatedResponse(): NextResponse;
+export interface SignInRedirectInput {
+    readonly config: ResolvedConfig;
+    readonly request: NextRequest;
+    readonly returnTo: string;
+    readonly clearSession: boolean;
+}
+/** Starts the authorization-code flow with PKCE by redirecting to SegmentStream. */
+export declare function signInRedirect(input: SignInRedirectInput): Promise<NextResponse>;
+export interface AuthorizationUrlInput {
+    readonly config: ResolvedConfig;
+    readonly redirectUri: string;
+    readonly state: string;
+    readonly codeChallenge: string;
+}
+export declare function authorizationUrl(input: AuthorizationUrlInput): URL;

package/dist/sign-in.js

@@ -0,0 +1,56 @@
+import { NextResponse } from "next/server";
+import { clearSessionCookies, cookiePolicyFor, setAuthFlowCookie } from "./cookies.js";
+import { createCodeChallenge, randomToken } from "./pkce.js";
+export const SDK_ROUTE_PREFIX = "/api/segmentstream";
+export const CALLBACK_PATH = `${SDK_ROUTE_PREFIX}/callback`;
+export const SIGN_IN_PATH = `${SDK_ROUTE_PREFIX}/sign-in`;
+export const SIGNED_OUT_PATH = `${SDK_ROUTE_PREFIX}/signed-out`;
+/**
+ * Requests that cannot follow a cross-origin sign-in redirect: anything other than a
+ * top-level page navigation. They receive a 401 instead of a redirect.
+ */
+export function isApiRequest(request) {
+    if (request.method !== "GET" && request.method !== "HEAD") {
+        return true;
+    }
+    if (request.nextUrl.pathname === "/api" || request.nextUrl.pathname.startsWith("/api/")) {
+        return true;
+    }
+    // Next.js strips some Flight headers before Proxy runs; `_rsc` and Accept still identify those requests.
+    const flightHeaders = ["rsc", "next-router-prefetch", "next-router-state-tree", "next-action"];
+    if (flightHeaders.some((header) => request.headers.has(header)) ||
+        request.nextUrl.searchParams.has("_rsc")) {
+        return true;
+    }
+    return !(request.headers.get("accept") ?? "").includes("text/html");
+}
+export function unauthenticatedResponse() {
+    return NextResponse.json({ error: "unauthenticated" }, { status: 401, headers: { "cache-control": "no-store" } });
+}
+/** Starts the authorization-code flow with PKCE by redirecting to SegmentStream. */
+export async function signInRedirect(input) {
+    const { config, request, returnTo, clearSession } = input;
+    const policy = cookiePolicyFor(request.nextUrl);
+    const state = randomToken();
+    const codeVerifier = randomToken();
+    const codeChallenge = await createCodeChallenge(codeVerifier);
+    const redirectUri = `${request.nextUrl.origin}${CALLBACK_PATH}`;
+    const authorizeUrl = authorizationUrl({ config, redirectUri, state, codeChallenge });
+    const response = NextResponse.redirect(authorizeUrl, 307);
+    response.headers.set("cache-control", "no-store");
+    setAuthFlowCookie(response, policy, { state, codeVerifier, redirectUri, returnTo });
+    if (clearSession) {
+        clearSessionCookies(response, policy);
+    }
+    return response;
+}
+export function authorizationUrl(input) {
+    const url = new URL(`${input.config.baseUrl}/auth/apps/authorize`);
+    url.searchParams.set("workspace_id", input.config.workspaceId);
+    url.searchParams.set("organization_id", input.config.organizationId);
+    url.searchParams.set("redirect_uri", input.redirectUri);
+    url.searchParams.set("state", input.state);
+    url.searchParams.set("code_challenge", input.codeChallenge);
+    url.searchParams.set("code_challenge_method", "S256");
+    return url;
+}

package/dist/tokens.d.ts

@@ -0,0 +1,26 @@
+import type { JWTVerifyGetKey } from "jose";
+import type { ResolvedConfig } from "./config.js";
+/** The signed-in SegmentStream user, as asserted by the app session token. */
+export interface AppUser {
+    readonly id: string;
+    readonly email?: string;
+    readonly name?: string;
+    readonly organizationId: string;
+    readonly workspaceId: string;
+}
+export type KeySet = JWTVerifyGetKey;
+export interface VerifiedToken {
+    readonly status: "valid";
+    readonly user: AppUser;
+    readonly token: string;
+}
+export type TokenVerification = VerifiedToken | {
+    readonly status: "expired";
+} | {
+    readonly status: "invalid";
+} | {
+    readonly status: "unavailable";
+};
+/** One remote JWKS per SegmentStream origin, shared by every app instance in the process. */
+export declare function remoteKeySet(baseUrl: string): KeySet;
+export declare function createTokenVerifier(config: ResolvedConfig, keySet: KeySet): (token: string) => Promise<TokenVerification>;

package/dist/tokens.js

@@ -0,0 +1,70 @@
+import { createRemoteJWKSet, errors, jwtVerify } from "jose";
+const CLOCK_TOLERANCE_SECONDS = 5;
+const remoteKeySets = new Map();
+/** One remote JWKS per SegmentStream origin, shared by every app instance in the process. */
+export function remoteKeySet(baseUrl) {
+    const existing = remoteKeySets.get(baseUrl);
+    if (existing !== undefined) {
+        return existing;
+    }
+    const keySet = createRemoteJWKSet(new URL(`${baseUrl}/api/v1/app-sessions/jwks`), {
+        timeoutDuration: 5_000,
+    });
+    remoteKeySets.set(baseUrl, keySet);
+    return keySet;
+}
+export function createTokenVerifier(config, keySet) {
+    return async function verifyToken(token) {
+        let payload;
+        try {
+            const verified = await jwtVerify(token, keySet, {
+                algorithms: ["ES256"],
+                issuer: config.issuer,
+                clockTolerance: CLOCK_TOLERANCE_SECONDS,
+                requiredClaims: ["sub", "exp", "iat", "org", "wsp"],
+            });
+            payload = verified.payload;
+        }
+        catch (error) {
+            return classifyVerificationFailure(error);
+        }
+        const user = appUserFromClaims(config, payload);
+        return user === null ? { status: "invalid" } : { status: "valid", user, token };
+    };
+}
+function classifyVerificationFailure(error) {
+    if (error instanceof errors.JWTExpired) {
+        return { status: "expired" };
+    }
+    if (error instanceof errors.JWKSTimeout) {
+        return { status: "unavailable" };
+    }
+    if (error instanceof errors.JOSEError) {
+        return { status: "invalid" };
+    }
+    // Network failures while fetching the key set are not token defects.
+    return { status: "unavailable" };
+}
+function appUserFromClaims(config, payload) {
+    const { sub, org, wsp, email, name } = payload;
+    if (typeof sub !== "string" ||
+        sub === "" ||
+        org !== config.organizationId ||
+        wsp !== config.workspaceId) {
+        return null;
+    }
+    if (!hasAppAudience(payload.aud)) {
+        return null;
+    }
+    return {
+        id: sub,
+        ...(typeof email === "string" ? { email } : {}),
+        ...(typeof name === "string" ? { name } : {}),
+        organizationId: org,
+        workspaceId: wsp,
+    };
+}
+function hasAppAudience(audience) {
+    const audiences = typeof audience === "string" ? [audience] : (audience ?? []);
+    return audiences.some((candidate) => candidate.startsWith("app:"));
+}