astroidjs 0.1.2 → 0.3.0

package/dist/map/style.js

@@ -0,0 +1,154 @@
+// Copyright (c) 2026 BowenLabs. Astroid is MIT licensed.
+//
+// A MapLibre style, built from brand colours.
+//
+// Deliberately dependency-free: a style is JSON, so this returns a plain object
+// rather than importing `maplibre-gl` (a megabyte) or `protomaps-themes-base`
+// for its types. astroidjs stays installable by a project that will never draw
+// a map, and a project that wants Protomaps' full maintained theme can swap
+// this out — the only contract is "an object MapLibre accepts".
+//
+// The layer set is the quiet-basemap subset: land, water, green space, a road
+// ramp with casings, buildings, and admin boundaries. Labels are opt-in and
+// need `glyphs`, because self-hosted SDF glyph ranges are a provisioning step
+// (and the reason the reference site could keep `font-src 'self'`).
+//
+// Source layer names follow the Protomaps v3 schema, which is what a `pmtiles`
+// archive built with `pmtiles extract` / planetiler contains.
+const DEFAULTS = {
+    land: "#faf7ef",
+    water: "#9fdad8",
+    green: "#e9efdc",
+    road: "#fffdf7",
+    arterial: "#f3eee0",
+    casing: "#ece5d2",
+    building: "#f0e9d9",
+    boundary: "#cfc6b0",
+    label: "#2a2a2a",
+    labelHalo: "#fffdf7",
+};
+/**
+ * Build a brand-recoloured basemap style over a self-hosted PMTiles archive.
+ *
+ * ```ts
+ * const style = astroidMapStyle({
+ *   pmtilesUrl: `${location.origin}/map/basemap.pmtiles`,
+ *   colors: { water: theme.colors.brand },
+ * });
+ * ```
+ */
+export function astroidMapStyle(options) {
+    const c = { ...DEFAULTS, ...options.colors };
+    const { pmtilesUrl, glyphs, fontstack = "Noto Sans Regular", attribution = '<a href="https://openstreetmap.org">OpenStreetMap</a> · <a href="https://protomaps.com">Protomaps</a>', } = options;
+    const layers = [
+        { id: "background", type: "background", paint: { "background-color": c.land } },
+        {
+            id: "earth",
+            type: "fill",
+            source: "protomaps",
+            "source-layer": "earth",
+            paint: { "fill-color": c.land },
+        },
+        {
+            id: "landuse",
+            type: "fill",
+            source: "protomaps",
+            "source-layer": "landuse",
+            // Only the green classes; leaving the rest unpainted keeps the map quiet
+            // rather than blotchy.
+            filter: ["in", "pmap:kind", "park", "forest", "wood", "grass", "scrub", "farmland"],
+            paint: { "fill-color": c.green },
+        },
+        {
+            id: "water",
+            type: "fill",
+            source: "protomaps",
+            "source-layer": "water",
+            paint: { "fill-color": c.water },
+        },
+        {
+            id: "buildings",
+            type: "fill",
+            source: "protomaps",
+            "source-layer": "buildings",
+            // Buildings only resolve once you're zoomed in; drawing them earlier is
+            // noise at city scale.
+            minzoom: 14,
+            paint: { "fill-color": c.building },
+        },
+        // Casings sit UNDER the road fills, so a road reads as a stroked ribbon
+        // rather than a flat band. Order matters more than colour here.
+        {
+            id: "roads-casing",
+            type: "line",
+            source: "protomaps",
+            "source-layer": "roads",
+            paint: {
+                "line-color": c.casing,
+                "line-width": ["interpolate", ["exponential", 1.6], ["zoom"], 10, 1.5, 16, 10],
+            },
+        },
+        {
+            id: "roads",
+            type: "line",
+            source: "protomaps",
+            "source-layer": "roads",
+            paint: {
+                "line-color": [
+                    "match",
+                    ["get", "pmap:kind"],
+                    "highway",
+                    c.arterial,
+                    "major_road",
+                    c.arterial,
+                    c.road,
+                ],
+                "line-width": ["interpolate", ["exponential", 1.6], ["zoom"], 10, 0.8, 16, 7],
+            },
+        },
+        {
+            id: "boundaries",
+            type: "line",
+            source: "protomaps",
+            "source-layer": "boundaries",
+            paint: { "line-color": c.boundary, "line-width": 0.8, "line-dasharray": [3, 2] },
+        },
+    ];
+    if (glyphs) {
+        layers.push({
+            id: "roads-labels",
+            type: "symbol",
+            source: "protomaps",
+            "source-layer": "roads",
+            minzoom: 14,
+            layout: {
+                "text-field": ["get", "name"],
+                "text-font": [fontstack],
+                "text-size": 11,
+                "symbol-placement": "line",
+            },
+            paint: { "text-color": c.label, "text-halo-color": c.labelHalo, "text-halo-width": 1.5 },
+        }, {
+            id: "places-labels",
+            type: "symbol",
+            source: "protomaps",
+            "source-layer": "places",
+            layout: { "text-field": ["get", "name"], "text-font": [fontstack], "text-size": 13 },
+            paint: { "text-color": c.label, "text-halo-color": c.labelHalo, "text-halo-width": 1.5 },
+        });
+    }
+    return {
+        version: 8,
+        ...(glyphs ? { glyphs } : {}),
+        sources: {
+            protomaps: {
+                type: "vector",
+                // The `pmtiles://` prefix is what routes reads through the protocol
+                // handler the page registers, instead of MapLibre fetching tile URLs.
+                url: `pmtiles://${pmtilesUrl}`,
+                attribution,
+            },
+        },
+        layers,
+    };
+}

package/dist/portal/config.d.ts

@@ -0,0 +1,26 @@
+import type { AstroidConfig } from "../config.js";
+import type { PortalGuardConfig, PortalRoute } from "./guard.js";
+/** Cookie prefix for the portal instance. Distinct from the studio's default
+ *  (`better-auth`) so the two sessions can coexist on one origin. */
+export declare const ASTROID_PORTAL_COOKIE_PREFIX = "portal";
+/** Table-name prefix for the portal's Better Auth tables — `portal_user`,
+ *  `portal_session`, … The studio owns the unprefixed names. */
+export declare const ASTROID_PORTAL_TABLE_PREFIX = "portal_";
+/** Everything the generated portal wiring needs, defaults applied. */
+export interface ResolvedPortal {
+    enabled: boolean;
+    basePath: string;
+    cookiePrefix: string;
+    tablePrefix: string;
+    roles: string[];
+    /** First role in `roles` — what a newly created account gets. */
+    defaultRole: string;
+    routes: PortalRoute[];
+    home: Record<string, string>;
+    signUp: boolean;
+    gated: boolean;
+}
+/** Resolve the portal block, or null when the project has no portal. */
+export declare function astroidPortal(config: AstroidConfig): ResolvedPortal | null;
+/** The guard config for a project, ready to hand to `portalGuard`. */
+export declare function astroidPortalGuardConfig(config: AstroidConfig): PortalGuardConfig | null;

package/dist/portal/config.js

@@ -0,0 +1,56 @@
+// Copyright (c) 2026 BowenLabs. Astroid is MIT licensed.
+//
+// Portal defaults derived from the project config — the single place that knows
+// the portal's mount, cookie prefix, table prefix, and guard table.
+//
+// The isolation constants are fixed rather than configurable, and that's the
+// point: the studio instance MUST keep Better Auth's defaults (`/api/auth`, the
+// unprefixed tables) because the Louise editor client hardcodes them, so the
+// portal is the one that moves. Leaving that to a project invites the one
+// mistake that matters — two instances sharing a cookie prefix, where signing
+// into one silently signs you out of the other, intermittently, in production.
+import { ASTROID_PORTAL_BASE_PATH } from "../security/rate-rules.js";
+/** Cookie prefix for the portal instance. Distinct from the studio's default
+ *  (`better-auth`) so the two sessions can coexist on one origin. */
+export const ASTROID_PORTAL_COOKIE_PREFIX = "portal";
+/** Table-name prefix for the portal's Better Auth tables — `portal_user`,
+ *  `portal_session`, … The studio owns the unprefixed names. */
+export const ASTROID_PORTAL_TABLE_PREFIX = "portal_";
+/** Default guard table: the account area, for any signed-in portal user. */
+const DEFAULT_ROUTES = [{ prefix: "/portal" }, { prefix: "/api/portal" }];
+/** Resolve the portal block, or null when the project has no portal. */
+export function astroidPortal(config) {
+    const portal = config.portal;
+    if (!portal?.enabled)
+        return null;
+    const roles = portal.roles?.length ? portal.roles : ["customer"];
+    return {
+        enabled: true,
+        // Isolation is configurable so a site with an existing second instance
+        // (coracle's shop account at /api/shop-auth, cookie `coracle_shop`, the
+        // unprefixed `user` tables) keeps its live mount + cookies unchanged. The
+        // defaults stay the safe distinct-from-editor values; `defineAstroid`'s
+        // `assertAuthIsolation` rejects a resolved value that collides with the
+        // editor. `?? ""` is respected for tablePrefix (empty = unprefixed tables).
+        basePath: portal.basePath ?? ASTROID_PORTAL_BASE_PATH,
+        cookiePrefix: portal.cookiePrefix ?? ASTROID_PORTAL_COOKIE_PREFIX,
+        tablePrefix: portal.tablePrefix ?? ASTROID_PORTAL_TABLE_PREFIX,
+        roles,
+        defaultRole: roles[0],
+        routes: portal.routes?.length ? portal.routes : DEFAULT_ROUTES,
+        home: portal.home ?? {},
+        signUp: portal.signUp ?? false,
+        gated: portal.gated ?? false,
+    };
+}
+/** The guard config for a project, ready to hand to `portalGuard`. */
+export function astroidPortalGuardConfig(config) {
+    const portal = astroidPortal(config);
+    if (!portal)
+        return null;
+    return {
+        routes: portal.routes,
+        loginPath: "/login",
+        home: (role) => portal.home[role] ?? "/portal",
+    };
+}

package/dist/portal/guard.d.ts

@@ -0,0 +1,54 @@
+/** A signed-in portal user. The guard only reads `role`; `id` + `email` are the
+ *  universal identity fields every instance resolves, typed so consumers
+ *  (`locals.portalUser`) read them without a cast. Anything else a project's
+ *  resolver returns (name, phone, a linked commerce id) is reachable via the
+ *  index signature. */
+export interface PortalUser {
+    id: string;
+    email: string;
+    role: string;
+    [key: string]: unknown;
+}
+/** One rule: everything under `prefix` requires one of `roles`. */
+export interface PortalRoute {
+    /** Path prefix, e.g. `/portal` — matches the prefix itself and everything
+     *  beneath it, but NOT `/portalling`. */
+    prefix: string;
+    /** Roles allowed through. Empty means "any signed-in user". */
+    roles?: string[];
+}
+export interface PortalGuardConfig {
+    /** The rule table, in order. The first matching prefix decides. */
+    routes: PortalRoute[];
+    /** Where to send a signed-out visitor. Default `/login`. */
+    loginPath?: string;
+    /** Landing page for a signed-in user, by role — used to bounce someone who
+     *  reached an area they don't belong in. Default `/portal` for everyone. */
+    home?: (role: string) => string;
+}
+/** What the guard decided. `null` means "carry on". */
+export type GuardDecision = null | {
+    kind: "redirect";
+    location: string;
+} | {
+    kind: "json";
+    status: 401 | 403;
+    body: {
+        ok: false;
+        error: string;
+    };
+};
+/** Prefix match on a path SEGMENT boundary — `/portal` covers `/portal` and
+ *  `/portal/orders`, but never `/portalling`. */
+export declare function matchesPrefix(path: string, prefix: string): boolean;
+/**
+ * Decide whether a request may proceed.
+ *
+ * Pure — it returns a decision rather than a `Response`, so it's testable
+ * without an Astro context and the middleware stays responsible for turning a
+ * decision into a redirect or a body.
+ */
+export declare function portalGuard(path: string, user: PortalUser | null, config: PortalGuardConfig): GuardDecision;
+/** Turn a decision into a `Response`. `redirect` is left to the caller, since
+ *  Astro's context builds those with its own base-path handling. */
+export declare function guardResponse(decision: Exclude<GuardDecision, null>): Response | null;

package/dist/portal/guard.js

@@ -0,0 +1,64 @@
+// Copyright (c) 2026 BowenLabs. Astroid is MIT licensed.
+//
+// Role-gated routing for the portal.
+//
+// coracle and ghostfire independently built the same thing: a declarative table
+// of `prefix → roles`, walked once per request. Declarative rather than a guard
+// call inside each page, because a guard you have to remember to write is a
+// guard someone eventually forgets — and the page that forgets it is the one
+// that leaks.
+//
+// Three answers, and which one you give matters:
+//
+//   not signed in, HTML   → redirect to the login page, carrying `next`
+//   not signed in, API    → 401 JSON (a redirect to an HTML login page is
+//                           useless to fetch(); it looks like success)
+//   signed in, wrong role → 403 for API, and for HTML a redirect to the area
+//                           this user DOES have — not back to login, which
+//                           reads as "your password failed" when it didn't
+/** Prefix match on a path SEGMENT boundary — `/portal` covers `/portal` and
+ *  `/portal/orders`, but never `/portalling`. */
+export function matchesPrefix(path, prefix) {
+    return path === prefix || path.startsWith(`${prefix}/`);
+}
+/**
+ * Decide whether a request may proceed.
+ *
+ * Pure — it returns a decision rather than a `Response`, so it's testable
+ * without an Astro context and the middleware stays responsible for turning a
+ * decision into a redirect or a body.
+ */
+export function portalGuard(path, user, config) {
+    const rule = config.routes.find((r) => matchesPrefix(path, r.prefix));
+    if (!rule)
+        return null;
+    // An API route answers in JSON whatever happens: redirecting `fetch()` to an
+    // HTML login page returns 200 and a page of markup, which client code reads
+    // as success and then fails on somewhere far less obvious.
+    const isApi = path.startsWith("/api/");
+    if (!user) {
+        if (isApi)
+            return { kind: "json", status: 401, body: { ok: false, error: "Unauthorized" } };
+        const login = config.loginPath ?? "/login";
+        return { kind: "redirect", location: `${login}?next=${encodeURIComponent(path)}` };
+    }
+    const allowed = !rule.roles?.length || rule.roles.includes(user.role);
+    if (!allowed) {
+        if (isApi)
+            return { kind: "json", status: 403, body: { ok: false, error: "Forbidden" } };
+        // Signed in, wrong door. Sending them back to /login would say "your
+        // credentials failed" about credentials that worked fine.
+        return { kind: "redirect", location: config.home?.(user.role) ?? "/portal" };
+    }
+    return null;
+}
+/** Turn a decision into a `Response`. `redirect` is left to the caller, since
+ *  Astro's context builds those with its own base-path handling. */
+export function guardResponse(decision) {
+    if (decision.kind === "redirect")
+        return null;
+    return new Response(JSON.stringify(decision.body), {
+        status: decision.status,
+        headers: { "content-type": "application/json" },
+    });
+}

package/dist/portal/index.d.ts

@@ -0,0 +1,5 @@
+export { ASTROID_PORTAL_COOKIE_PREFIX, ASTROID_PORTAL_TABLE_PREFIX, astroidPortal, astroidPortalGuardConfig, type ResolvedPortal, } from "./config.js";
+export { type GuardDecision, guardResponse, matchesPrefix, portalGuard, type PortalGuardConfig, type PortalRoute, type PortalUser, } from "./guard.js";
+export { definePortalNav, type PortalNav, type PortalNavItem } from "./nav.js";
+export { generateAstroidPortalAuth, generateAstroidPortalAuthRoute, generateAstroidPortalLocals, } from "./scaffold.js";
+export { type CustomerGuardResult, isSameOrigin, json, type PortalSessionResolver, requireCustomer, resolvePortalSession, } from "./session.js";

package/dist/portal/index.js

@@ -0,0 +1,6 @@
+// Copyright (c) 2026 BowenLabs. Astroid is MIT licensed.
+export { ASTROID_PORTAL_COOKIE_PREFIX, ASTROID_PORTAL_TABLE_PREFIX, astroidPortal, astroidPortalGuardConfig, } from "./config.js";
+export { guardResponse, matchesPrefix, portalGuard, } from "./guard.js";
+export { definePortalNav } from "./nav.js";
+export { generateAstroidPortalAuth, generateAstroidPortalAuthRoute, generateAstroidPortalLocals, } from "./scaffold.js";
+export { isSameOrigin, json, requireCustomer, resolvePortalSession, } from "./session.js";

package/dist/portal/nav.d.ts

@@ -0,0 +1,26 @@
+export interface PortalNavItem {
+    label: string;
+    href: string;
+    /** Roles that may see this item. Omit for "everyone signed in". */
+    roles?: string[];
+    /** Optional icon name, passed through to the shell's slot. */
+    icon?: string;
+}
+export interface PortalNav {
+    items: PortalNavItem[];
+    /** The items this role may see. */
+    forRole(role: string | null | undefined): PortalNavItem[];
+    /** The item matching a path, by the same prefix rule the guard uses. */
+    activeFor(path: string): PortalNavItem | null;
+}
+/**
+ * Declare the portal navigation.
+ *
+ * ```ts
+ * export const nav = definePortalNav([
+ *   { label: "Orders", href: "/portal/orders" },
+ *   { label: "Team", href: "/admin/team", roles: ["manager"] },
+ * ]);
+ * ```
+ */
+export declare function definePortalNav(items: PortalNavItem[]): PortalNav;

package/dist/portal/nav.js

@@ -0,0 +1,35 @@
+// Copyright (c) 2026 BowenLabs. Astroid is MIT licensed.
+//
+// The portal's navigation, as data.
+//
+// Two things fall out of declaring it rather than writing markup per page.
+// Items can be filtered by the viewer's role in one place — so an item a user
+// can't reach is never rendered, instead of rendered-then-403'd, which reads as
+// a broken link. And "which item is active" is computed the same way the guard
+// matches prefixes, so the highlight can't disagree with the routing.
+import { matchesPrefix } from "./guard.js";
+/**
+ * Declare the portal navigation.
+ *
+ * ```ts
+ * export const nav = definePortalNav([
+ *   { label: "Orders", href: "/portal/orders" },
+ *   { label: "Team", href: "/admin/team", roles: ["manager"] },
+ * ]);
+ * ```
+ */
+export function definePortalNav(items) {
+    return {
+        items,
+        forRole(role) {
+            return items.filter((item) => !item.roles?.length || (role ? item.roles.includes(role) : false));
+        },
+        activeFor(path) {
+            // Longest href first, so `/portal/orders` wins over `/portal` on a page
+            // both would match — otherwise the parent item is always the active one.
+            return ([...items]
+                .sort((a, b) => b.href.length - a.href.length)
+                .find((item) => matchesPrefix(path, item.href)) ?? null);
+        },
+    };
+}

package/dist/portal/scaffold.d.ts

@@ -0,0 +1,28 @@
+import type { AstroidConfig } from "../config.js";
+/**
+ * `src/portal-auth.ts` — the portal Better Auth instance and its session
+ * resolver.
+ *
+ * Returns null when the project has no portal.
+ */
+export declare function generateAstroidPortalAuth(config: AstroidConfig): string | null;
+/**
+ * `src/pages/api/portal-auth/[...all].ts` — the portal's Better Auth catch-all,
+ * mounted at its own basePath so it never collides with the studio's
+ * `/api/auth`.
+ *
+ * Lives here rather than as a literal in `create-astroid` for the same reason
+ * the archetype sections moved (#277): the scaffolder is plain JS, so a drifted
+ * import path there is invisible until a user's build fails. It is also the half
+ * `generateAstroidPortalAuth` is useless without — `src/portal-auth.ts` exports
+ * `handlePortalAuth`, and nothing calls it unless this route exists.
+ *
+ * Returns null when the project has no portal.
+ */
+export declare function generateAstroidPortalAuthRoute(config: AstroidConfig): string | null;
+/**
+ * The `App.Locals` member the portal adds, as a block `create-astroid`
+ * substitutes into `src/env.d.ts`. Empty without a portal — a project that
+ * types `portalUser` it never sets is inviting a null-check nobody needs.
+ */
+export declare function generateAstroidPortalLocals(config: AstroidConfig): string;

package/dist/portal/scaffold.js

@@ -0,0 +1,140 @@
+// Copyright (c) 2026 BowenLabs. Astroid is MIT licensed.
+//
+// The portal's SCAFFOLD-ONCE pieces: the second Better Auth instance, and the
+// `App.Locals` / `CloudflareEnv` additions that come with it.
+//
+// The auth instance is scaffolded rather than generated because a site edits it
+// — the reset email, the role a new account gets, extra user columns. What
+// Astroid fixes are the three things that must not drift: the mount, the cookie
+// prefix, and the table prefix. Get any of those wrong and the two instances
+// fight over one origin's cookies, which fails intermittently and looks like a
+// session bug rather than a configuration one.
+import { astroidPortal } from "./config.js";
+/**
+ * `src/portal-auth.ts` — the portal Better Auth instance and its session
+ * resolver.
+ *
+ * Returns null when the project has no portal.
+ */
+export function generateAstroidPortalAuth(config) {
+    const portal = astroidPortal(config);
+    if (!portal)
+        return null;
+    return [
+        "// The PORTAL auth instance — customers/members, separate from the editor.",
+        "//",
+        "// Scaffolded once; yours to edit (the reset email, extra user columns, what",
+        "// role a new account gets). Three things should NOT change: the basePath,",
+        "// the cookiePrefix, and the tablePrefix. The studio instance keeps Better",
+        "// Auth's defaults because the Louise editor client hardcodes them, so this",
+        "// one moves — and if the two ever share a cookie prefix, signing into one",
+        "// silently signs you out of the other.",
+        'import { astroidMailTheme, magicLinkEmail, passwordResetEmail, resolveMailer, sendTransactional } from "astroidjs";',
+        'import { env } from "cloudflare:workers";',
+        'import { getLouiseAuth } from "louise-toolkit/auth";',
+        'import astroidConfig from "../astroid.config.js";',
+        "",
+        "const MAIL_THEME = astroidMailTheme(astroidConfig);",
+        "",
+        "/** The request-scoped portal auth instance. */",
+        "function getPortalAuth(request: Request) {",
+        "  return getLouiseAuth(env, new URL(request.url).origin, {",
+        "    rpName: astroidConfig.theme.name,",
+        "    mailFrom: { email: env.MAIL_FROM, name: astroidConfig.theme.name },",
+        "    // The portal never sends magic links — it's email + password — but the",
+        "    // toolkit's config asks for a renderer, so give it the real one.",
+        "    renderMagicLinkEmail: ({ url, toEmail }) => magicLinkEmail(MAIL_THEME, { url, toEmail }),",
+        `    basePath: ${JSON.stringify(portal.basePath)},`,
+        `    cookiePrefix: ${JSON.stringify(portal.cookiePrefix)},`,
+        `    tablePrefix: ${JSON.stringify(portal.tablePrefix)},`,
+        "    customers: {",
+        "      minPasswordLength: 8,",
+        portal.signUp
+            ? "      // Public sign-up is ON for this project."
+            : "      // Accounts are provisioned by staff — no public sign-up.",
+        `      disableSignUp: ${!portal.signUp},`,
+        "      sendResetPassword: async ({ user, url }) => {",
+        "        // Through `resolveMailer`, NOT a hand-built options object: it is the",
+        "        // only thing that applies the DUMMY_REPLACE_ME sentinel check. Built by",
+        "        // hand, a fresh deploy with a real EMAIL binding but a placeholder",
+        "        // MAIL_FROM read as configured and called the Email API with an envelope",
+        "        // sender of literally \"DUMMY_REPLACE_ME\" — rejected upstream, swallowed",
+        "        // here, and reported to the user as a reset email that was sent.",
+        "        const mailer = await resolveMailer(env);",
+        "        await sendTransactional(mailer, [",
+        "          { to: user.email, content: passwordResetEmail(MAIL_THEME, { url, toEmail: user.email }) },",
+        "        ]);",
+        "      },",
+        "    },",
+        "    // The portal has its own users — never the editor allowlist.",
+        "    resolveAdmins: () => [],",
+        "  });",
+        "}",
+        "",
+        "/** Better Auth catch-all for the portal, mounted at its own basePath. */",
+        "export async function handlePortalAuth(request: Request): Promise<Response> {",
+        "  const auth = await getPortalAuth(request);",
+        "  return auth.handler(request);",
+        "}",
+        "",
+        "/**",
+        " * Resolve the signed-in portal user, or null. The generated middleware passes",
+        " * this to `resolvePortalSession`, which shares the lookup for the request.",
+        " */",
+        "export async function resolvePortalUser(request: Request) {",
+        "  try {",
+        "    const auth = await getPortalAuth(request);",
+        "    const session = await auth.api.getSession({ headers: request.headers });",
+        "    const user = session?.user;",
+        "    if (!user) return null;",
+        `    return { id: user.id, email: user.email ?? "", role: user.role ?? ${JSON.stringify(portal.defaultRole)} };`,
+        "  } catch {",
+        "    // No bindings (plain `astro preview`) → treat as signed out.",
+        "    return null;",
+        "  }",
+        "}",
+        "",
+    ].join("\n");
+}
+/**
+ * `src/pages/api/portal-auth/[...all].ts` — the portal's Better Auth catch-all,
+ * mounted at its own basePath so it never collides with the studio's
+ * `/api/auth`.
+ *
+ * Lives here rather than as a literal in `create-astroid` for the same reason
+ * the archetype sections moved (#277): the scaffolder is plain JS, so a drifted
+ * import path there is invisible until a user's build fails. It is also the half
+ * `generateAstroidPortalAuth` is useless without — `src/portal-auth.ts` exports
+ * `handlePortalAuth`, and nothing calls it unless this route exists.
+ *
+ * Returns null when the project has no portal.
+ */
+export function generateAstroidPortalAuthRoute(config) {
+    if (!astroidPortal(config))
+        return null;
+    return [
+        "// The portal Better Auth catch-all, mounted at its own basePath so it",
+        "// never collides with the studio's /api/auth.",
+        'import type { APIRoute } from "astro";',
+        'import { handlePortalAuth } from "../../../portal-auth.js";',
+        "",
+        "export const prerender = false;",
+        "",
+        "export const ALL: APIRoute = ({ request }) => handlePortalAuth(request);",
+        "",
+    ].join("\n");
+}
+/**
+ * The `App.Locals` member the portal adds, as a block `create-astroid`
+ * substitutes into `src/env.d.ts`. Empty without a portal — a project that
+ * types `portalUser` it never sets is inviting a null-check nobody needs.
+ */
+export function generateAstroidPortalLocals(config) {
+    if (!astroidPortal(config))
+        return "";
+    return [
+        "    /** The signed-in PORTAL user (customers/members) — distinct from",
+        "     *  `editor`, which is the studio session. Null when signed out. */",
+        '    portalUser: import("astroidjs").PortalUser | null;',
+    ].join("\n");
+}

package/dist/portal/session.d.ts

@@ -0,0 +1,36 @@
+import type { PortalUser } from "./guard.js";
+/** Resolves the portal user for a request, or null when signed out. */
+export type PortalSessionResolver = (request: Request) => Promise<PortalUser | null>;
+/**
+ * Resolve the portal session at most once per request.
+ *
+ * Shares the *promise*, not the result, so two callers racing during the same
+ * request both await one lookup rather than starting a second.
+ */
+export declare function resolvePortalSession(request: Request, resolve: PortalSessionResolver): Promise<PortalUser | null>;
+/** JSON response helper — the shape every portal API route returns. */
+export declare function json(body: unknown, status?: number, headers?: Record<string, string>): Response;
+/** True when the request came from this same origin. */
+export declare function isSameOrigin(request: Request): boolean;
+export type CustomerGuardResult = {
+    ok: true;
+    user: PortalUser;
+} | {
+    ok: false;
+    response: Response;
+};
+/**
+ * Guard a portal API handler: a signed-in user, and — on mutations — a
+ * same-origin request.
+ *
+ * ```ts
+ * const guard = await requireCustomer(request, (req) => portalUser(req));
+ * if (!guard.ok) return guard.response;
+ * // guard.user is signed in and this is a same-origin call
+ * ```
+ *
+ * `roles` narrows further, for a route only some portal users may reach.
+ */
+export declare function requireCustomer(request: Request, resolve: PortalSessionResolver, options?: {
+    roles?: string[];
+}): Promise<CustomerGuardResult>;