@segmentstream-cloud/app 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,2 @@
+SegmentStream App SDK
+Copyright 2026 SegmentStream

package/README.md

@@ -1,3 +1,113 @@
-# Temporary Holding Version
+# @segmentstream-cloud/app
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Sign-in and sessions for SegmentStream workspace apps built with Next.js (App Router,
+version 16 or later). Every visitor signs in with their SegmentStream account, and only
+members of the app's workspace get in.
+
+## Install
+
+```sh
+npm install @segmentstream-cloud/app
+```
+
+## Add three files
+
+**`src/segmentstream.ts`** configures the app once:
+
+```ts
+import { createSegmentStreamApp } from "@segmentstream-cloud/app";
+
+export const segmentstream = createSegmentStreamApp({
+  workspaceId: "your-workspace-id",
+  organizationId: "your-organization-id",
+});
+```
+
+**`src/proxy.ts`** keeps every page and API route signed in:
+
+```ts
+import { segmentstream } from "./segmentstream";
+
+export const proxy = segmentstream.proxy({
+  // Optional: paths that anyone may open. `/health` also covers `/health/live`.
+  publicPaths: ["/health"],
+});
+
+export const config = {
+  matcher: ["/((?!_next/static|_next/image|favicon.ico|robots.txt).*)"],
+};
+```
+
+**`src/app/api/segmentstream/[...path]/route.ts`** handles the sign-in callback and
+sign-out:
+
+```ts
+import { segmentstream } from "../../../../segmentstream";
+
+export const { GET, POST } = segmentstream.handlers();
+```
+
+## Read the signed-in user
+
+```tsx
+import { segmentstream } from "@/segmentstream";
+
+export default async function Page() {
+  const user = await segmentstream.requireUser();
+
+  return <p>Signed in as {user.email ?? user.id}</p>;
+}
+```
+
+- `getUser()` returns `{ id, email?, name?, organizationId, workspaceId }` or `null`.
+- `requireUser()` returns the user, or redirects to `/api/segmentstream/sign-in` when
+  there is none. Next.js `unauthorized()` needs the experimental `authInterrupts` flag,
+  so the SDK restarts sign-in instead. The proxy normally signs users in first, so this
+  only happens on paths the proxy matcher excludes.
+- `getAccessToken()` returns the verified app session token for calls to SegmentStream.
+
+Use them in Server Components, Route Handlers, and Server Functions. Always check the
+user in Server Functions and Route Handlers too; do not rely on the proxy alone.
+
+To sign out, post a form to the SDK route:
+
+```tsx
+<form action="/api/segmentstream/sign-out" method="post">
+  <button type="submit">Sign out</button>
+</form>
+```
+
+## How requests are handled
+
+- Page navigations without a session are redirected to SegmentStream to sign in, then
+  return to the page they started on.
+- API routes, `fetch` calls, non-GET requests, and Next.js data requests receive
+  `401 {"error":"unauthenticated"}` instead of a redirect.
+- `/api/segmentstream/*` and your `publicPaths` never require a session.
+
+## Environment
+
+| Variable            | Purpose                                                              |
+| ------------------- | -------------------------------------------------------------------- |
+| `SEGMENTSTREAM_URL` | SegmentStream origin. Defaults to `https://cloud.segmentstream.com`. |
+
+## Local development
+
+`next dev` on `http://localhost` works. SegmentStream accepts loopback redirect URIs,
+and the SDK drops the `__Host-` prefix and `Secure` attribute only for `http://localhost`,
+`127.0.0.1`, and `[::1]`, which browsers otherwise reject over plain HTTP.
+
+## Security
+
+- The app never sees SegmentStream's identity-provider tokens. It receives a short-lived
+  (5-minute) ES256 session token scoped to this workspace app and a rotating refresh
+  token, both in `HttpOnly`, `SameSite=Lax` cookies (`__Host-` and `Secure` in production).
+- Session tokens are verified locally against SegmentStream's published keys: issuer,
+  expiry, workspace, organization, and an `app:` audience.
+- The proxy refreshes expired sessions silently. When access is revoked, the next refresh
+  fails and the user is signed out.
+- Sign-in uses the authorization-code flow with PKCE (S256) and a single-use `state`.
+
+## License
+
+Apache-2.0

package/dist/app.d.ts

@@ -0,0 +1,23 @@
+import type { SegmentStreamAppConfig } from "./config.js";
+import type { SegmentStreamRouteHandlers } from "./handlers.js";
+import type { ProxyOptions, SegmentStreamProxy } from "./proxy.js";
+import type { Fetch } from "./sessions.js";
+import type { AppUser, KeySet } from "./tokens.js";
+export interface SegmentStreamApp {
+    /** The Next.js Proxy that keeps every non-public request signed in. */
+    readonly proxy: (options?: ProxyOptions) => SegmentStreamProxy;
+    /** Route Handlers for `app/api/segmentstream/[...path]/route.ts`. */
+    readonly handlers: () => SegmentStreamRouteHandlers;
+    /** The signed-in user for this request, or `null`. */
+    readonly getUser: () => Promise<AppUser | null>;
+    /** The signed-in user; redirects to sign-in when there is none. */
+    readonly requireUser: () => Promise<AppUser>;
+    /** The verified app session token for this request, or `null`. */
+    readonly getAccessToken: () => Promise<string | null>;
+}
+/** Replaceable capabilities, for tests. */
+export interface AppDependencies {
+    readonly fetch: Fetch;
+    readonly keySet: KeySet;
+}
+export declare function createApp(config: SegmentStreamAppConfig, dependencies?: Partial<AppDependencies>): SegmentStreamApp;

package/dist/app.js

@@ -0,0 +1,26 @@
+import { resolveConfig } from "./config.js";
+import { createHandlers } from "./handlers.js";
+import { createProxy } from "./proxy.js";
+import { createServerSession } from "./server.js";
+import { createSessionClient } from "./sessions.js";
+import { createTokenVerifier, remoteKeySet } from "./tokens.js";
+export function createApp(config, dependencies = {}) {
+    const resolved = resolveConfig(config);
+    const keySet = dependencies.keySet ?? remoteKeySet(resolved.baseUrl);
+    const fetchImplementation = dependencies.fetch ?? ((input, init) => fetch(input, init));
+    const sessionClient = createSessionClient(resolved, fetchImplementation);
+    const context = {
+        config: resolved,
+        verifyToken: createTokenVerifier(resolved, keySet),
+        requestToken: sessionClient.requestToken,
+        revokeSession: sessionClient.revoke,
+    };
+    const serverSession = createServerSession(context);
+    return {
+        proxy: (options) => createProxy(context, options),
+        handlers: () => createHandlers(context),
+        getUser: serverSession.getUser,
+        requireUser: serverSession.requireUser,
+        getAccessToken: serverSession.getAccessToken,
+    };
+}

package/dist/config.d.ts

@@ -0,0 +1,18 @@
+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;
+}
+export interface ResolvedConfig {
+    readonly workspaceId: string;
+    readonly organizationId: string;
+    readonly baseUrl: string;
+    readonly issuer: string;
+}
+export declare function resolveConfig(config: SegmentStreamAppConfig): ResolvedConfig;
+/** Linear-time trailing slash removal; `/\/+$/` backtracks quadratically on slash runs. */
+export declare function trimTrailingSlashes(value: string): string;

package/dist/config.js

@@ -0,0 +1,41 @@
+export const DEFAULT_BASE_URL = "https://cloud.segmentstream.com";
+export function resolveConfig(config) {
+    const workspaceId = requireIdentifier("workspaceId", config.workspaceId);
+    const organizationId = requireIdentifier("organizationId", config.organizationId);
+    const baseUrl = normalizeBaseUrl(config.baseUrl ?? readEnvironment("SEGMENTSTREAM_URL") ?? DEFAULT_BASE_URL);
+    const issuer = readEnvironment("SEGMENTSTREAM_APP_TOKEN_ISSUER") ?? new URL(baseUrl).origin;
+    return { workspaceId, organizationId, baseUrl, issuer };
+}
+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) {
+    const trimmed = trimTrailingSlashes(value.trim());
+    let url;
+    try {
+        url = new URL(trimmed);
+    }
+    catch (error) {
+        throw new Error(`SegmentStream base URL is not a valid URL: ${trimmed}`, { cause: error });
+    }
+    if (url.protocol !== "https:" && url.protocol !== "http:") {
+        throw new Error(`SegmentStream base URL must use http or https: ${trimmed}`);
+    }
+    return trimmed;
+}
+function readEnvironment(name) {
+    const value = typeof process === "undefined" ? undefined : process.env[name];
+    return value === undefined || value.trim() === "" ? undefined : value.trim();
+}

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,47 @@
+import type { NextResponse } from "next/server";
+export declare const REFRESH_COOKIE_MAX_AGE_SECONDS: number;
+export declare const AUTH_FLOW_COOKIE_MAX_AGE_SECONDS: number;
+export interface CookieNames {
+    readonly session: string;
+    readonly refresh: string;
+    readonly authFlow: string;
+}
+/** Cookie names and attributes for 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.
+ */
+export declare function cookiePolicyFor(url: URL): CookiePolicy;
+/** Candidate cookie names for code that only knows the request host (Server Components). */
+export declare function sessionCookieCandidates(hostname: string): readonly 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 clearAuthFlowCookie(response: NextResponse, policy: CookiePolicy): void;
+export declare function encodeAuthFlowState(flow: AuthFlowState): string;
+export declare function decodeAuthFlowState(value: string | undefined): AuthFlowState | null;
+/** Reduces a return path to a same-origin relative path, falling back to `/`. */
+export declare function safeReturnTo(value: string | null | undefined): string;
+/**
+ * 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,142 @@
+import { base64UrlDecode, base64UrlEncode } from "./pkce.js";
+export const REFRESH_COOKIE_MAX_AGE_SECONDS = 30 * 24 * 60 * 60;
+export const AUTH_FLOW_COOKIE_MAX_AGE_SECONDS = 10 * 60;
+const SECURE_NAMES = {
+    session: "__Host-ss_app_session",
+    refresh: "__Host-ss_app_refresh",
+    authFlow: "__Host-ss_app_auth",
+};
+const LOOPBACK_NAMES = {
+    session: "ss_app_session",
+    refresh: "ss_app_refresh",
+    authFlow: "ss_app_auth",
+};
+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.
+ */
+export function cookiePolicyFor(url) {
+    const insecureLoopback = url.protocol === "http:" && isLoopbackHostname(url.hostname);
+    return insecureLoopback
+        ? { secure: false, names: LOOPBACK_NAMES }
+        : { secure: true, names: SECURE_NAMES };
+}
+/** Candidate cookie names for code that only knows the request host (Server Components). */
+export function sessionCookieCandidates(hostname) {
+    return isLoopbackHostname(hostname)
+        ? [SECURE_NAMES.session, LOOPBACK_NAMES.session]
+        : [SECURE_NAMES.session];
+}
+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.authFlow, encodeAuthFlowState(flow), cookieAttributes(policy, AUTH_FLOW_COOKIE_MAX_AGE_SECONDS));
+}
+export function clearAuthFlowCookie(response, policy) {
+    clearCookie(response, policy, policy.names.authFlow);
+}
+// `__Host-` cookies are only replaced when the clearing cookie repeats Secure and Path=/.
+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");
+}
+/** Reduces a return path to a same-origin relative path, falling back to `/`. */
+export function safeReturnTo(value) {
+    if (typeof value !== "string" ||
+        !value.startsWith("/") ||
+        value.startsWith("//") ||
+        value.startsWith("/\\")) {
+        return "/";
+    }
+    if (/[\u0000-\u001f\u007f]/.test(value)) {
+        return "/";
+    }
+    const placeholderOrigin = "https://return-to.invalid";
+    let url;
+    try {
+        url = new URL(value, placeholderOrigin);
+    }
+    catch {
+        return "/";
+    }
+    if (url.origin !== placeholderOrigin) {
+        return "/";
+    }
+    return `${url.pathname}${url.search}${url.hash}`;
+}
+/**
+ * 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();
+}

package/dist/handlers.d.ts

@@ -0,0 +1,8 @@
+import type { NextRequest } from "next/server";
+import type { AppContext } from "./context.js";
+export type RouteHandler = (request: NextRequest) => Promise<Response>;
+export interface SegmentStreamRouteHandlers {
+    readonly GET: RouteHandler;
+    readonly POST: RouteHandler;
+}
+export declare function createHandlers(context: AppContext): SegmentStreamRouteHandlers;