@puckeditor/cloud-client 0.9.0-canary.9a2a27cf → 0.9.0-canary.9ff9b8a5

package/README.md

@@ -1 +1,93 @@
 # @puckeditor/cloud-client
+
+## Authentication
+
+`puckHandler` requires an `authenticate` function that resolves the current user from each request. Return `{ id }` to continue, `{ id: null }` to use unowned resources, `null` to respond 401, or a `Response` to short-circuit.
+
+```ts
+import { puckHandler } from "@puckeditor/cloud-client/experimental";
+
+export const GET = (request: Request) =>
+  puckHandler(request, {
+    authenticate: async ({ request }) => {
+      const user = await getUser(request); // your own auth
+      return user ? { id: user.id } : null;
+    },
+  });
+export const POST = GET;
+export const DELETE = GET;
+```
+
+Requests to Puck Cloud use your `PUCK_API_KEY` and carry the returned `id` as `x-puck-authenticated-id`. Cloud records it as the external owner of pages, chats and attachments, and only returns rows owned by that id. Returning `{ id: null }` limits API-key requests to unowned resources. Page paths stay unique per site.
+
+Direct `chat()` calls also require authentication and return a promise:
+
+```ts
+const response = await chat(params, {
+  authenticate: () => puckAuth.authenticate({ request }),
+});
+```
+
+### Sign in with Puck
+
+Let members of your Puck Cloud organization sign in to your editor with their Puck account. Create a project in Puck Cloud, set its branches' deployment URLs under **Settings › Branches**, serve the editor at `/puck` on those origins, and set `PUCK_PROJECT_ID` from **Settings › Project**. Every cloud-client call uses this project, and `PUCK_BRANCH` picks the branch whose pages it reads and writes.
+
+```ts
+import { puckAuth } from "@puckeditor/cloud-client/auth";
+import { puckHandler } from "@puckeditor/cloud-client/experimental";
+
+export const GET = (request: Request) =>
+  puckHandler(request, { authenticate: puckAuth });
+export const POST = GET;
+export const DELETE = GET;
+```
+
+Gate the editor page:
+
+```ts
+const session = await puckAuth.getSession(await headers());
+if (!session) redirect(puckAuth.loginUrl("/puck"));
+```
+
+Protect custom routes with the same function:
+
+```ts
+const user = await puckAuth.authenticate({ request });
+if (user instanceof Response) return user;
+await generate({ prompt, user });
+```
+
+The helper serves these routes through `puckHandler`:
+
+| Route                         | Behavior                                              |
+| ----------------------------- | ----------------------------------------------------- |
+| `GET /api/puck/auth/login`    | Redirect to Puck Cloud (authorization code with PKCE) |
+| `GET /api/puck/auth/callback` | Exchange the code and set an HttpOnly session cookie  |
+| `GET /api/puck/auth/session`  | Current user, project, branch and expiry, or 401      |
+| `POST /api/puck/auth/logout`  | Revoke the session and clear the cookie               |
+
+Sessions last up to seven days and end when the user signs out of Puck Cloud or leaves the organization. Cloud verifies the user on every request, so no API key is needed for the editor, and external-owner filtering does not apply. `puckAuth` reads `PUCK_PROJECT_ID`, `PUCK_BRANCH` and `PUCK_HOST` (default `https://cloud.puckeditor.com/api`, shared by every cloud-client call). `createPuckAuth({ projectId, branch, host, basePath, appUrl })` builds an instance with explicit options; `basePath` defaults to `/api/puck/auth` and `appUrl` is the public origin when behind a proxy. HTTPS is required except on localhost.
+
+Each session edits one branch. A deployment URL signs in to the branch deployed there, so a preview deployment can't edit production. Localhost needs no deployment URL and edits `PUCK_BRANCH`, or the project's default branch.
+
+The pages plugin needs no configuration: outside the Puck Cloud editor frame it relies on the app's session cookie and shows an account menu with links to Puck Cloud and sign-out. Pass `authHost` to `createPagesPlugin` if the auth routes live somewhere other than the `/auth` sibling of the pages host.
+
+## Creating pages in bulk
+
+Create pages from a JSON file of `{ "/route": data }`, the shape of a Puck recipe's `database.json`. Routes the branch already has, including pages it inherits, are skipped, so it's safe to run again.
+
+```sh
+npx @puckeditor/cloud-client import database.json [--branch <name>]
+```
+
+The CLI reads `PUCK_API_KEY`, `PUCK_PROJECT_ID`, `PUCK_BRANCH` and `PUCK_HOST` from the environment, then from `.env.local` and `.env`. Use `createPages` from scripts:
+
+```ts
+import { createPages } from "@puckeditor/cloud-client/experimental";
+import pages from "./database.json";
+
+// Pages are published unless status is "unpublished"
+const { created, skipped } = await createPages({ pages });
+```
+
+In Puck Cloud, **Pages › Import JSON** does the same for the selected branch.

package/dist/auth.d.mts

@@ -0,0 +1,52 @@
+import { A as AuthenticateFn } from './types-DRxmCSVs.mjs';
+import '@ai-sdk/provider';
+import '@ai-sdk/provider-utils';
+
+type PuckSession = {
+    user: {
+        id: string;
+        name: string;
+        email: string;
+        image?: string | null;
+    };
+    projectId: string;
+    /** The branch this session reads and writes. */
+    branch: string;
+    organizationId: string;
+    /** ISO timestamp. */
+    expiresAt: string;
+    /** Puck Cloud dashboard origin, for linking back. */
+    cloudUrl: string;
+};
+type PuckAuthOptions = {
+    /** Project registered in Puck Cloud; also the OAuth client id. Defaults to PUCK_PROJECT_ID. */
+    projectId?: string;
+    /**
+     * Branch this app edits. Defaults to PUCK_BRANCH. Cloud signs a deployed URL
+     * in to the branch deployed there; on localhost this picks the branch.
+     */
+    branch?: string;
+    /** Puck Cloud API host. Defaults to PUCK_HOST or https://cloud.puckeditor.com/api. */
+    host?: string;
+    /** Prefix for the auth routes served through puckHandler. Defaults to /api/puck/auth. */
+    basePath?: string;
+    /** Public origin of this app when it cannot be derived from the request, e.g. behind a proxy. */
+    appUrl?: string;
+};
+type PuckAuth = {
+    /** Pass to `puckHandler`, or call directly to protect your own routes. */
+    authenticate: AuthenticateFn;
+    getSession: (headers: Headers) => Promise<PuckSession | null>;
+    loginUrl: (returnTo?: string) => string;
+};
+/** Only same-origin paths, and never back into the auth routes. */
+declare const safeReturnTo: (value: string | null | undefined, basePath: string) => string;
+/**
+ * Sign in with Puck. `authenticate` also serves the login, callback, logout
+ * and session routes under `basePath`. Use `puckAuth` unless you need options.
+ */
+declare function createPuckAuth(options?: PuckAuthOptions): PuckAuth;
+/** Sign in with Puck configured from PUCK_PROJECT_ID, PUCK_BRANCH and PUCK_HOST. */
+declare const puckAuth: PuckAuth;
+
+export { type PuckAuth, type PuckAuthOptions, type PuckSession, createPuckAuth, puckAuth, safeReturnTo };

package/dist/auth.d.ts

@@ -0,0 +1,52 @@
+import { A as AuthenticateFn } from './types-DRxmCSVs.js';
+import '@ai-sdk/provider';
+import '@ai-sdk/provider-utils';
+
+type PuckSession = {
+    user: {
+        id: string;
+        name: string;
+        email: string;
+        image?: string | null;
+    };
+    projectId: string;
+    /** The branch this session reads and writes. */
+    branch: string;
+    organizationId: string;
+    /** ISO timestamp. */
+    expiresAt: string;
+    /** Puck Cloud dashboard origin, for linking back. */
+    cloudUrl: string;
+};
+type PuckAuthOptions = {
+    /** Project registered in Puck Cloud; also the OAuth client id. Defaults to PUCK_PROJECT_ID. */
+    projectId?: string;
+    /**
+     * Branch this app edits. Defaults to PUCK_BRANCH. Cloud signs a deployed URL
+     * in to the branch deployed there; on localhost this picks the branch.
+     */
+    branch?: string;
+    /** Puck Cloud API host. Defaults to PUCK_HOST or https://cloud.puckeditor.com/api. */
+    host?: string;
+    /** Prefix for the auth routes served through puckHandler. Defaults to /api/puck/auth. */
+    basePath?: string;
+    /** Public origin of this app when it cannot be derived from the request, e.g. behind a proxy. */
+    appUrl?: string;
+};
+type PuckAuth = {
+    /** Pass to `puckHandler`, or call directly to protect your own routes. */
+    authenticate: AuthenticateFn;
+    getSession: (headers: Headers) => Promise<PuckSession | null>;
+    loginUrl: (returnTo?: string) => string;
+};
+/** Only same-origin paths, and never back into the auth routes. */
+declare const safeReturnTo: (value: string | null | undefined, basePath: string) => string;
+/**
+ * Sign in with Puck. `authenticate` also serves the login, callback, logout
+ * and session routes under `basePath`. Use `puckAuth` unless you need options.
+ */
+declare function createPuckAuth(options?: PuckAuthOptions): PuckAuth;
+/** Sign in with Puck configured from PUCK_PROJECT_ID, PUCK_BRANCH and PUCK_HOST. */
+declare const puckAuth: PuckAuth;
+
+export { type PuckAuth, type PuckAuthOptions, type PuckSession, createPuckAuth, puckAuth, safeReturnTo };

package/dist/auth.js

@@ -0,0 +1,307 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/auth.ts
+var auth_exports = {};
+__export(auth_exports, {
+  createPuckAuth: () => createPuckAuth,
+  puckAuth: () => puckAuth,
+  safeReturnTo: () => safeReturnTo
+});
+module.exports = __toCommonJS(auth_exports);
+
+// ../tsup-config/react-import.js
+var import_react = __toESM(require("react"));
+
+// src/lib/get-host.ts
+var getDefaultHost = () => (process.env.PUCK_HOST ?? "https://cloud.puckeditor.com/api").replace(
+  /\/+$/,
+  ""
+);
+
+// src/auth.ts
+var SESSION_COOKIE = "puck-session";
+var LOGIN_COOKIE = "puck-login";
+var LOGIN_TTL_SECONDS = 600;
+var TOKEN_PATTERN = /^[A-Za-z0-9_.~-]{16,512}$/;
+var noStore = { "cache-control": "no-store" };
+var base64url = (bytes) => btoa(String.fromCharCode(...bytes)).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+var randomToken = () => base64url(crypto.getRandomValues(new Uint8Array(32)));
+var sha256 = async (value) => base64url(
+  new Uint8Array(
+    await crypto.subtle.digest("SHA-256", new TextEncoder().encode(value))
+  )
+);
+var isLoopback = (hostname) => hostname === "localhost" || hostname.endsWith(".localhost") || hostname === "[::1]" || /^127\.\d+\.\d+\.\d+$/.test(hostname);
+var encodeCookie = (value) => base64url(new TextEncoder().encode(JSON.stringify(value)));
+var decodeCookie = (value) => {
+  try {
+    const binary = atob((value ?? "").replace(/-/g, "+").replace(/_/g, "/"));
+    return JSON.parse(
+      new TextDecoder().decode(Uint8Array.from(binary, (c) => c.charCodeAt(0)))
+    );
+  } catch {
+    return {};
+  }
+};
+var readCookie = (headers, name) => headers.get("cookie")?.split(";").map((part) => part.trim()).find((part) => part.startsWith(`${name}=`))?.slice(name.length + 1);
+var safeReturnTo = (value, basePath) => {
+  if (!value || value.length > 512) return "/";
+  try {
+    const url = new URL(value, "https://puck.invalid");
+    if (url.origin === "https://puck.invalid" && !url.pathname.startsWith(basePath)) {
+      return `${url.pathname}${url.search}`;
+    }
+  } catch {
+  }
+  return "/";
+};
+function createPuckAuth(options = {}) {
+  const projectId = options.projectId ?? process.env.PUCK_PROJECT_ID;
+  const configuredBranch = () => (options.branch ?? process.env.PUCK_BRANCH)?.trim() || null;
+  if (!projectId) {
+    throw new Error(
+      "Sign in with Puck requires a project id. Set PUCK_PROJECT_ID or pass projectId."
+    );
+  }
+  const host = (options.host ?? getDefaultHost()).replace(/\/+$/, "");
+  const cloudUrl = new URL(host).origin;
+  const basePath = (options.basePath ?? "/api/puck/auth").replace(/\/+$/, "");
+  const appOrigin = (request) => new URL(options.appUrl ?? request.url).origin;
+  const isSecure = (request) => appOrigin(request).startsWith("https:");
+  const callbackUrl = (request, branch) => {
+    const url = new URL(`${appOrigin(request)}${basePath}/callback`);
+    if (branch && isLoopback(url.hostname)) {
+      url.searchParams.set("branch", branch);
+    }
+    return url.toString();
+  };
+  const cookieName = (name, secure) => secure ? `__Host-${name}` : name;
+  const cookie = (name, value, maxAge, secure) => `${cookieName(
+    name,
+    secure
+  )}=${value}; Path=/; HttpOnly; SameSite=Lax; Max-Age=${maxAge}${secure ? "; Secure" : ""}`;
+  const readSessionCookie = (headers) => {
+    const { token, branch } = decodeCookie(
+      readCookie(headers, `__Host-${SESSION_COOKIE}`) ?? readCookie(headers, SESSION_COOKIE)
+    );
+    return typeof token === "string" && TOKEN_PATTERN.test(token) ? { token, branch: typeof branch === "string" ? branch : null } : void 0;
+  };
+  const loginUrl = (returnTo = "/") => `${basePath}/login?returnTo=${encodeURIComponent(
+    safeReturnTo(returnTo, basePath)
+  )}`;
+  const html = (message, status) => new Response(
+    `<!doctype html><html lang="en"><meta charset="utf-8"><title>Puck</title><p>${message} <a href="${loginUrl()}">Sign in</a>.</p></html>`,
+    {
+      status,
+      headers: { ...noStore, "content-type": "text/html; charset=utf-8" }
+    }
+  );
+  const unauthorized = () => Response.json(
+    { error: "unauthorized", loginUrl: loginUrl() },
+    { status: 401, headers: noStore }
+  );
+  const fetchCloudSession = async (accessToken) => {
+    const response = await fetch(`${host}/oauth/session`, {
+      headers: { authorization: `Bearer ${accessToken}` },
+      cache: "no-store",
+      signal: AbortSignal.timeout(1e4)
+    });
+    if (response.status === 401) return null;
+    if (!response.ok) {
+      throw new Error(
+        `Puck Cloud session check failed (HTTP ${response.status}).`
+      );
+    }
+    return await response.json();
+  };
+  const isOtherBranch = (session, branch) => !!branch && session.branch !== branch;
+  const toSession = (session, branch) => session?.projectId === projectId && !isOtherBranch(session, branch) && session.user?.id ? { ...session, cloudUrl } : null;
+  const resolve = async (headers) => {
+    const stored = readSessionCookie(headers);
+    if (!stored || stored.branch !== configuredBranch()) return null;
+    const session = toSession(
+      await fetchCloudSession(stored.token),
+      stored.branch
+    );
+    return session ? { session, accessToken: stored.token } : null;
+  };
+  const revoke = (accessToken) => fetch(`${host}/auth/oauth2/revoke`, {
+    method: "POST",
+    headers: { "content-type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams({ token: accessToken, client_id: projectId }),
+    signal: AbortSignal.timeout(1e4)
+  }).catch(() => void 0);
+  const login = async (request, url) => {
+    const state = randomToken();
+    const verifier = randomToken();
+    const branch = configuredBranch();
+    const transaction = encodeCookie({
+      state,
+      verifier,
+      branch,
+      returnTo: safeReturnTo(url.searchParams.get("returnTo"), basePath)
+    });
+    const authorize = new URL(`${host}/auth/oauth2/authorize`);
+    authorize.search = new URLSearchParams({
+      client_id: projectId,
+      redirect_uri: callbackUrl(request, branch),
+      response_type: "code",
+      scope: "profile email",
+      state,
+      code_challenge: await sha256(verifier),
+      code_challenge_method: "S256"
+    }).toString();
+    return new Response(null, {
+      status: 302,
+      headers: {
+        ...noStore,
+        location: authorize.toString(),
+        "set-cookie": cookie(
+          LOGIN_COOKIE,
+          transaction,
+          LOGIN_TTL_SECONDS,
+          isSecure(request)
+        )
+      }
+    });
+  };
+  const callback = async (request, url) => {
+    const secure = isSecure(request);
+    const error = url.searchParams.get("error");
+    if (error) {
+      return html(
+        error === "access_denied" ? "Your Puck account does not have access to this project. Sign out of Puck Cloud to switch accounts." : "Sign-in was cancelled or failed.",
+        400
+      );
+    }
+    const transaction = decodeCookie(readCookie(request.headers, cookieName(LOGIN_COOKIE, secure)));
+    const branch = transaction.branch ?? null;
+    const code = url.searchParams.get("code");
+    if (!code || !transaction.state || !transaction.verifier || transaction.state !== url.searchParams.get("state")) {
+      return html("Sign-in expired or was cancelled.", 400);
+    }
+    const tokenResponse = await fetch(`${host}/auth/oauth2/token`, {
+      method: "POST",
+      headers: { "content-type": "application/x-www-form-urlencoded" },
+      body: new URLSearchParams({
+        grant_type: "authorization_code",
+        code,
+        redirect_uri: callbackUrl(request, branch),
+        client_id: projectId,
+        code_verifier: transaction.verifier
+      }),
+      signal: AbortSignal.timeout(1e4)
+    });
+    const tokens = tokenResponse.ok ? await tokenResponse.json() : null;
+    const accessToken = tokens?.access_token;
+    if (typeof accessToken !== "string" || !TOKEN_PATTERN.test(accessToken)) {
+      return html("Sign-in expired or was cancelled.", 400);
+    }
+    const cloudSession = await fetchCloudSession(accessToken);
+    if (cloudSession && isOtherBranch(cloudSession, branch)) {
+      await revoke(accessToken);
+      return html(
+        `Puck Cloud signs this URL in to the ${cloudSession.branch} branch, but this app is set up for ${branch}. Update PUCK_BRANCH or the branch's deployment URL.`,
+        400
+      );
+    }
+    const session = toSession(cloudSession, branch);
+    const maxAge = Math.floor(
+      (Date.parse(session?.expiresAt ?? "") - Date.now()) / 1e3
+    );
+    if (!session || !(maxAge > 0)) {
+      return html("Sign-in expired or was cancelled.", 400);
+    }
+    const headers = new Headers({
+      ...noStore,
+      location: new URL(
+        safeReturnTo(transaction.returnTo, basePath),
+        appOrigin(request)
+      ).toString()
+    });
+    headers.append("set-cookie", cookie(LOGIN_COOKIE, "", 0, secure));
+    headers.append(
+      "set-cookie",
+      cookie(
+        SESSION_COOKIE,
+        encodeCookie({ token: accessToken, branch }),
+        maxAge,
+        secure
+      )
+    );
+    return new Response(null, { status: 303, headers });
+  };
+  const logout = async (request) => {
+    const stored = readSessionCookie(request.headers);
+    if (stored) await revoke(stored.token);
+    return new Response(null, {
+      status: 303,
+      headers: {
+        ...noStore,
+        location: "/",
+        "set-cookie": cookie(SESSION_COOKIE, "", 0, isSecure(request))
+      }
+    });
+  };
+  const authenticate = async ({ request }) => {
+    const url = new URL(request.url);
+    if (url.pathname.startsWith(`${basePath}/`)) {
+      const route = `${request.method} ${url.pathname.slice(basePath.length)}`;
+      if (route === "GET /login") return login(request, url);
+      if (route === "GET /callback") return callback(request, url);
+      if (route === "POST /logout") return logout(request);
+      if (route === "GET /session") {
+        const resolved2 = await resolve(request.headers);
+        return resolved2 ? Response.json(resolved2.session, { headers: noStore }) : unauthorized();
+      }
+      return Response.json({ error: "Not found" }, { status: 404 });
+    }
+    const resolved = await resolve(request.headers);
+    return resolved ? { ...resolved.session.user, accessToken: resolved.accessToken } : unauthorized();
+  };
+  return {
+    authenticate,
+    getSession: async (headers) => (await resolve(headers))?.session ?? null,
+    loginUrl
+  };
+}
+var defaultAuth;
+var getDefaultAuth = () => defaultAuth ??= createPuckAuth();
+var puckAuth = {
+  authenticate: (context) => getDefaultAuth().authenticate(context),
+  getSession: (headers) => getDefaultAuth().getSession(headers),
+  loginUrl: (returnTo) => getDefaultAuth().loginUrl(returnTo)
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createPuckAuth,
+  puckAuth,
+  safeReturnTo
+});