@segmentstream/app 0.0.0-stage → 0.38.0

package/dist/navigation-protocol.js

@@ -0,0 +1,298 @@
+// Generated from packages/ontology-sdk/src/navigation-catalog.ts; do not edit.
+import { createHash } from "node:crypto";
+export const NAVIGATION_CATALOG_LIMITS = Object.freeze({
+    pages: 1_000,
+    bytes: 1024 * 1024,
+    title: 120,
+    description: 2_000,
+    hint: 512,
+    associations: 32,
+    hints: 32,
+    responseBytes: 32 * 1024,
+});
+function routeShape(path, source) {
+    if (!path.startsWith("/")) {
+        return undefined;
+    }
+    const result = [];
+    for (const segment of path.split("/").filter(Boolean)) {
+        const parameter = source
+            ? /^:[A-Za-z0-9_]+([?*+]?)$/u.exec(segment)
+            : /^(?:\[\[\.\.\.[^\[\]]+\]\]|\[\.\.\.[^\[\]]+\]|\[[^\[\]]+\])$/u.exec(segment);
+        if (parameter) {
+            result.push({
+                literal: undefined,
+                optional: source ? ["?", "*"].includes(parameter[1]) : segment.startsWith("[["),
+                repeat: source ? ["*", "+"].includes(parameter[1]) : segment.includes("..."),
+            });
+        }
+        else if (/[:()*+?{}\\\[\]%]/u.test(segment)) {
+            return undefined;
+        }
+        else {
+            result.push({ literal: segment.toLowerCase(), optional: false, repeat: false });
+        }
+    }
+    return result;
+}
+/**
+ * Whether a generated page and a routing source can share a path. Compare complete segment
+ * shapes for ordinary parameters, optional parameters and catch-alls; custom regex sources
+ * remain conservative when their static prefixes cannot prove disjointness.
+ */
+export function navigationRoutesMayOverlap(route, source) {
+    const page = routeShape(route, false);
+    const rule = routeShape(source, true);
+    if (page === undefined || rule === undefined) {
+        const pagePrefix = route.split("[")[0].toLowerCase();
+        const rulePrefix = source.split(/[:(*?+{\\]/u)[0].toLowerCase();
+        return (pagePrefix.includes("%") ||
+            rulePrefix.includes("%") ||
+            pagePrefix.startsWith(rulePrefix) ||
+            rulePrefix.startsWith(pagePrefix));
+    }
+    const pending = [[0, 0]];
+    const visited = new Set();
+    while (pending.length > 0) {
+        const [left, right] = pending.pop();
+        const key = `${left}:${right}`;
+        if (visited.has(key)) {
+            continue;
+        }
+        visited.add(key);
+        if (left === page.length && right === rule.length) {
+            return true;
+        }
+        const a = page[left];
+        const b = rule[right];
+        if (a?.optional) {
+            pending.push([left + 1, right]);
+        }
+        if (b?.optional) {
+            pending.push([left, right + 1]);
+        }
+        if (a && b && (a.literal === undefined || b.literal === undefined || a.literal === b.literal)) {
+            pending.push([left + 1, right + 1]);
+            if (a.repeat) {
+                pending.push([left, right + 1]);
+            }
+            if (b.repeat) {
+                pending.push([left + 1, right]);
+            }
+        }
+    }
+    return false;
+}
+export class NavigationCatalogError extends Error {
+    code;
+    name = "NavigationCatalogError";
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+function invalid(message) {
+    throw new NavigationCatalogError("invalid_page_catalog", message);
+}
+function bounded(condition, message) {
+    if (!condition) {
+        throw new NavigationCatalogError("page_catalog_too_large", message);
+    }
+}
+function object(value, fields) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return invalid("Navigation metadata must be a JSON object.");
+    }
+    if (fields !== undefined && Object.keys(value).some((key) => !fields.includes(key))) {
+        return invalid("Navigation metadata contains an unknown field.");
+    }
+    return value;
+}
+function text(value, maximum, field) {
+    if (typeof value !== "string" ||
+        value.trim() === "" ||
+        /[\u0000-\u0008\u000b\u000c\u000e-\u001f]/u.test(value)) {
+        return invalid(`${field} must be nonblank text without control characters.`);
+    }
+    bounded(Array.from(value).length <= maximum, `${field} exceeds ${maximum} Unicode code points.`);
+    return value;
+}
+function hints(value) {
+    const entries = Object.entries(object(value));
+    bounded(entries.length <= NAVIGATION_CATALOG_LIMITS.hints, "A page has more than 32 query hints.");
+    return Object.freeze(Object.fromEntries(entries
+        .sort(([a], [b]) => compare(a, b))
+        .map(([key, hint]) => [
+        text(key, NAVIGATION_CATALOG_LIMITS.responseBytes, "Query name"),
+        text(hint, NAVIGATION_CATALOG_LIMITS.hint, "Query hint"),
+    ])));
+}
+function compare(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+function entry(value) {
+    const page = object(value, [
+        "ref",
+        "route",
+        "title",
+        "description",
+        "entities",
+        "parameters",
+        "query",
+    ]);
+    const route = text(page.route, NAVIGATION_CATALOG_LIMITS.responseBytes, "Page route");
+    if (!route.startsWith("/") || /[?#\\\s\u007f]/u.test(route) || route.includes("//")) {
+        return invalid("A page route must be a normalized absolute path without an origin or query.");
+    }
+    const segments = route.slice(1).split("/").filter(Boolean);
+    const routeParameters = [];
+    for (const [index, segment] of segments.entries()) {
+        const match = /^(?:\[\[\.\.\.([^\[\]/]+)\]\]|\[\.\.\.([^\[\]/]+)\]|\[([^\[\]/]+)\])$/u.exec(segment);
+        if (match) {
+            const name = match[1] ?? match[2] ?? match[3];
+            const kind = match[3] === undefined ? "catch_all" : "segment";
+            text(name, NAVIGATION_CATALOG_LIMITS.responseBytes, "Parameter name");
+            if (routeParameters.some((parameter) => parameter.name === name) ||
+                (kind === "catch_all" && index !== segments.length - 1)) {
+                return invalid("Route parameters must be unique and catch-all parameters must be last.");
+            }
+            routeParameters.push({ name, kind, required: match[1] === undefined });
+        }
+        else {
+            let decoded;
+            try {
+                decoded = decodeURIComponent(segment);
+            }
+            catch {
+                return invalid("Page route has invalid percent encoding.");
+            }
+            if (decoded === "." || decoded === ".." || /[\[\]\/\\\u0000-\u0020\u007f]/u.test(decoded)) {
+                return invalid("Page route has an unsupported or unsafe segment.");
+            }
+        }
+    }
+    if (page.ref !== `page:${route}`) {
+        return invalid("Page references must be page: followed by the normalized route.");
+    }
+    if (!Array.isArray(page.entities) || !Array.isArray(page.parameters)) {
+        return invalid("Page entities and parameters must be arrays.");
+    }
+    bounded(page.entities.length <= NAVIGATION_CATALOG_LIMITS.associations, "A page has more than 32 entities.");
+    const entities = Array.from(page.entities, (name) => {
+        if (typeof name !== "string" || !/^[a-z][a-z0-9_]*$/u.test(name)) {
+            return invalid("Page entity associations must be canonical ontology names.");
+        }
+        return name;
+    });
+    if (new Set(entities).size !== entities.length) {
+        return invalid("A page repeats an entity association.");
+    }
+    if (page.parameters.length !== routeParameters.length) {
+        return invalid("Page parameters must exactly describe their route.");
+    }
+    const declaredParameters = page.parameters;
+    const parameters = routeParameters.map((expected, index) => {
+        const parameter = object(declaredParameters[index], [
+            "name",
+            "kind",
+            "required",
+            "description",
+        ]);
+        if (parameter.name !== expected.name ||
+            parameter.kind !== expected.kind ||
+            parameter.required !== expected.required) {
+            return invalid("Page parameters must match their route in path order.");
+        }
+        return Object.freeze({
+            ...expected,
+            ...(parameter.description === undefined
+                ? {}
+                : {
+                    description: text(parameter.description, NAVIGATION_CATALOG_LIMITS.hint, "Parameter hint"),
+                }),
+        });
+    });
+    bounded(parameters.filter((parameter) => parameter.description !== undefined).length <=
+        NAVIGATION_CATALOG_LIMITS.hints, "A page has more than 32 parameter hints.");
+    const normalized = Object.freeze({
+        ref: `page:${route}`,
+        route,
+        title: text(page.title, NAVIGATION_CATALOG_LIMITS.title, "Page title"),
+        description: text(page.description, NAVIGATION_CATALOG_LIMITS.description, "Page description"),
+        entities: Object.freeze(entities.sort(compare)),
+        parameters: Object.freeze(parameters),
+        query: hints(page.query),
+    });
+    // An entry must fit even when more results follow. Runtime checks the actual origin/envelope too.
+    const revision = `sha256:${"0".repeat(64)}`;
+    const result = {
+        revision,
+        pages: [
+            {
+                ...normalized,
+                [parameters.length === 0 ? "url" : "url_pattern"]: `https://navigation.invalid${route}`,
+            },
+        ],
+        next_cursor: Buffer.from(JSON.stringify({
+            revision,
+            scope: "0".repeat(64),
+            request: "0".repeat(64),
+            last: normalized.ref,
+        })).toString("base64url"),
+    };
+    bounded(Buffer.byteLength(JSON.stringify({
+        content: [{ type: "text", text: JSON.stringify(result) }],
+        structuredContent: result,
+    })) <= NAVIGATION_CATALOG_LIMITS.responseBytes, "A complete page entry exceeds the MCP response budget.");
+    return normalized;
+}
+/** Canonical JSON is independent of insertion order, process locale, and object prototypes. */
+function canonical(value) {
+    if (Array.isArray(value)) {
+        return `[${value.map(canonical).join(",")}]`;
+    }
+    if (typeof value === "object" && value !== null) {
+        return `{${Object.entries(value)
+            .sort(([a], [b]) => compare(a, b))
+            .map(([key, item]) => `${JSON.stringify(key)}:${canonical(item)}`)
+            .join(",")}}`;
+    }
+    return JSON.stringify(value);
+}
+/** Validate and copy an untrusted artifact. Entity existence is checked against the serving ontology. */
+export function parsePageCatalog(value) {
+    const catalog = object(value, ["version", "revision", "pages"]);
+    if (catalog.version !== 1 ||
+        typeof catalog.revision !== "string" ||
+        !/^sha256:[a-f0-9]{64}$/u.test(catalog.revision) ||
+        !Array.isArray(catalog.pages)) {
+        return invalid("Expected a version-1 page catalog with a SHA-256 revision and pages array.");
+    }
+    bounded(catalog.pages.length <= NAVIGATION_CATALOG_LIMITS.pages, "A catalog has more than 1,000 pages.");
+    const pages = Array.from(catalog.pages, entry).sort((a, b) => compare(a.ref, b.ref));
+    if (new Set(pages.map((page) => page.ref)).size !== pages.length) {
+        return invalid("Page catalog contains duplicate routes.");
+    }
+    const normalized = {
+        version: 1,
+        revision: catalog.revision,
+        pages: Object.freeze(pages),
+    };
+    bounded(Buffer.byteLength(canonical(normalized)) <= NAVIGATION_CATALOG_LIMITS.bytes, "Page catalog exceeds 1 MiB.");
+    return Object.freeze(normalized);
+}
+/** Generate an immutable catalog identity from normalized metadata, ontology, and source identity. */
+export function createPageCatalog(pages, context) {
+    text(context.ontologyHash, NAVIGATION_CATALOG_LIMITS.bytes, "Ontology hash");
+    text(context.sourceHash, NAVIGATION_CATALOG_LIMITS.bytes, "Source hash");
+    const normalized = parsePageCatalog({ version: 1, revision: `sha256:${"0".repeat(64)}`, pages });
+    const revision = `sha256:${createHash("sha256")
+        .update(canonical({
+        version: 1,
+        pages: normalized.pages,
+        ontologyHash: context.ontologyHash,
+        sourceHash: context.sourceHash,
+    }))
+        .digest("hex")}`;
+    return Object.freeze({ ...normalized, revision });
+}

package/dist/neon.d.ts

@@ -0,0 +1,101 @@
+import { NextResponse } from "next/server";
+import type { NextRequest } from "next/server";
+import type { NeonAuthEnvironment, ResolvedConfig } from "./config.js";
+import type { OntologyTransport } from "./ontology.js";
+import type { ProxyOptions, SegmentStreamProxy } from "./proxy.js";
+import type { Fetch } from "./sessions.js";
+import type { AppUser } from "./tokens.js";
+/** The app's sign-in page, which renders `<SignIn />` from `@segmentstream/app/ui`. */
+export declare const SIGN_IN_PAGE = "/sign-in";
+/** Where `app/src/app/api/auth/[...path]/route.ts` serves the Neon Auth API. */
+export declare const AUTH_API_PATH = "/api/auth";
+/**
+ * Paths every visitor may open: the Neon Auth API, the sign-in page, the health check, and the
+ * Next.js assets and metadata files the sign-in page needs.
+ */
+export declare const OPEN_PATHS: ReadonlyArray<string>;
+interface NeonError {
+    readonly status?: number;
+    readonly code?: string;
+    readonly message?: string;
+}
+interface NeonResult<T> {
+    readonly data: T | null;
+    readonly error: NeonError | null;
+}
+interface NeonSessionData {
+    readonly session: {
+        readonly id: string;
+    } | null;
+    readonly user: {
+        readonly id: string;
+        readonly email?: string | null;
+        readonly name?: string | null;
+    } | null;
+}
+export type AuthRouteHandler = (request: Request, context: {
+    params: Promise<{
+        path: string[];
+    }>;
+}) => Promise<Response>;
+/** The Neon Auth API for `app/src/app/api/auth/[...path]/route.ts`. */
+export interface AuthRouteHandlers {
+    readonly GET: AuthRouteHandler;
+    readonly POST: AuthRouteHandler;
+    readonly PUT: AuthRouteHandler;
+    readonly DELETE: AuthRouteHandler;
+    readonly PATCH: AuthRouteHandler;
+}
+/** The part of `createNeonAuth(...)` from `@neondatabase/auth/next/server` the SDK uses. */
+export interface NeonAuthServer {
+    getSession(): Promise<NeonResult<NeonSessionData>>;
+    token(): Promise<NeonResult<{
+        readonly token?: string;
+    }>>;
+    signOut(): Promise<NeonResult<unknown>>;
+    handler(): AuthRouteHandlers;
+    middleware(config?: {
+        loginUrl?: string;
+    }): (request: NextRequest) => Promise<NextResponse>;
+}
+export type CreateNeonAuth = (config: {
+    readonly baseUrl: string;
+    readonly cookies: {
+        readonly secret: string;
+        readonly sameSite: "lax";
+    };
+}) => NeonAuthServer;
+/** How `getUser`, `requireUser` and `can` read the signed-in user. */
+export interface UserOptions {
+    /**
+     * Ask `/api/ontology/me` again instead of reusing the answer cached for up to a minute, and cache
+     * the new answer. For checks a role change must take effect on at once.
+     */
+    readonly fresh?: boolean;
+}
+export interface SignOutOptions {
+    /** Where to send the browser afterwards. Defaults to the sign-in page. */
+    readonly redirectTo?: string;
+}
+export interface NeonSessionDependencies {
+    readonly config: ResolvedConfig;
+    readonly settings: NeonAuthEnvironment;
+    readonly createNeonAuth: CreateNeonAuth;
+    readonly fetch: Fetch;
+    readonly now: () => number;
+}
+/**
+ * Neon Auth (Managed Better Auth) for the app's users: sessions in cookies through
+ * `@neondatabase/auth`, and roles and permissions from the ontology's `GET /api/ontology/me`.
+ */
+export declare function createNeonSession(dependencies: NeonSessionDependencies): {
+    proxy: (options?: ProxyOptions) => SegmentStreamProxy;
+    authHandlers: () => AuthRouteHandlers;
+    getUser: (options?: UserOptions) => Promise<AppUser | null>;
+    requireUser: (options?: UserOptions) => Promise<AppUser>;
+    can: (permission: string, options?: UserOptions) => Promise<boolean>;
+    signOut: (options?: SignOutOptions) => Promise<never>;
+    ontologyTransport: OntologyTransport;
+    identityToken: () => Promise<string | null>;
+};
+export {};