@puckeditor/cloud-client 0.9.0-canary.d4a0bc62 → 0.9.0-canary.d582a110

package/README.md

@@ -1 +1,105 @@
 # @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 branch.
+
+Each API key belongs to one branch of a project, chosen when you create it under **Settings › Project › API Keys**. Its requests read and write that branch.
+
+Direct `chat()` calls also require authentication and return a promise:
+
+```ts
+const response = await chat(params, {
+  authenticate: () => authenticate({ request }),
+});
+```
+
+### Sign in with Puck
+
+Let members of your Puck Cloud organization sign in to your editor with their Puck account. Sessions edit the branch of your `PUCK_API_KEY`.
+
+```ts
+import { authenticate } from "@puckeditor/cloud-client/auth";
+import { puckHandler } from "@puckeditor/cloud-client/experimental";
+
+export const GET = (request: Request) => puckHandler(request, { authenticate });
+export const POST = GET;
+export const DELETE = GET;
+```
+
+Gate the editor page:
+
+```ts
+import { getSession, loginUrl } from "@puckeditor/cloud-client/auth";
+
+const session = await getSession(await headers());
+if (!session) redirect(loginUrl("/puck"));
+```
+
+Protect custom routes with the same function:
+
+```ts
+const user = await 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               |
+
+Each sign-in asks for the Puck account again and starts a Puck Cloud session of its own, separate from any Puck Cloud dashboard session in the same browser. Accounts outside the organization that owns `PUCK_API_KEY` are turned away with a prompt to sign in with another account. Sessions last up to seven days and end when the user signs out of the app or leaves the organization. Cloud verifies the user on every request, and external-owner filtering does not apply. These functions read `PUCK_API_KEY` and `PUCK_HOST`, which every cloud-client call uses. Use `createPuckAuth(options)` to pass them explicitly.
+
+Before each sign-in, the app registers its callback with its API key, so the editor can run on localhost or any HTTPS origin. Switching to a key for another branch signs the app out.
+
+The pages plugin needs no configuration: outside the Puck Cloud editor frame it relies on the app's session cookie. Add `createAuthPlugin` from `@puckeditor/plugin-auth` to show the signed-in account in the editor's header, with links to Puck Cloud and sign-out. List it after the pages plugin, which replaces the header's actions:
+
+```tsx
+import { createAuthPlugin } from "@puckeditor/plugin-auth";
+import "@puckeditor/plugin-auth/styles.css";
+
+<Puck plugins={[createPagesPlugin(), createAuthPlugin()]} />;
+```
+
+Pass `host` if the auth routes aren't served at `/api/puck/auth`. The menu shows the branch being edited in development, or anywhere with `showBranch: true`.
+
+## 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
+```
+
+The CLI reads `PUCK_API_KEY` and `PUCK_HOST` from the environment, then from `.env.local` and `.env`. Pages go to the API key's branch. 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 pages** does the same for the selected branch.

package/dist/auth.d.mts

@@ -0,0 +1,46 @@
+import { A as AuthenticateFn } from './types-BMWPvaOC.mjs';
+import '@ai-sdk/provider';
+import '@ai-sdk/provider-utils';
+
+type PuckSession = {
+    user: {
+        id: string;
+        name: string;
+        email: string;
+        image?: string | null;
+    };
+    /** 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 = {
+    /** Members sign in to the key's project and edit its branch. Defaults to PUCK_API_KEY. */
+    apiKey?: string;
+    /** Puck Cloud API host. Defaults to PUCK_HOST or https://cloud.puckeditor.com/api. */
+    host?: 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) => string;
+/**
+ * Sign in with Puck. `authenticate` also serves the login, callback, logout
+ * and session routes under /api/puck/auth. Use the exported functions unless you need options.
+ */
+declare function createPuckAuth(options?: PuckAuthOptions): PuckAuth;
+/** Pass to `puckHandler`, or call directly to protect your own routes. */
+declare const authenticate: PuckAuth["authenticate"];
+declare const getSession: PuckAuth["getSession"];
+declare const loginUrl: PuckAuth["loginUrl"];
+
+export { type PuckAuth, type PuckAuthOptions, type PuckSession, authenticate, createPuckAuth, getSession, loginUrl, safeReturnTo };

package/dist/auth.d.ts

@@ -0,0 +1,46 @@
+import { A as AuthenticateFn } from './types-BMWPvaOC.js';
+import '@ai-sdk/provider';
+import '@ai-sdk/provider-utils';
+
+type PuckSession = {
+    user: {
+        id: string;
+        name: string;
+        email: string;
+        image?: string | null;
+    };
+    /** 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 = {
+    /** Members sign in to the key's project and edit its branch. Defaults to PUCK_API_KEY. */
+    apiKey?: string;
+    /** Puck Cloud API host. Defaults to PUCK_HOST or https://cloud.puckeditor.com/api. */
+    host?: 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) => string;
+/**
+ * Sign in with Puck. `authenticate` also serves the login, callback, logout
+ * and session routes under /api/puck/auth. Use the exported functions unless you need options.
+ */
+declare function createPuckAuth(options?: PuckAuthOptions): PuckAuth;
+/** Pass to `puckHandler`, or call directly to protect your own routes. */
+declare const authenticate: PuckAuth["authenticate"];
+declare const getSession: PuckAuth["getSession"];
+declare const loginUrl: PuckAuth["loginUrl"];
+
+export { type PuckAuth, type PuckAuthOptions, type PuckSession, authenticate, createPuckAuth, getSession, loginUrl, safeReturnTo };

package/dist/auth.js

@@ -0,0 +1,311 @@
+"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, {
+  authenticate: () => authenticate,
+  createPuckAuth: () => createPuckAuth,
+  getSession: () => getSession,
+  loginUrl: () => loginUrl,
+  safeReturnTo: () => safeReturnTo
+});
+module.exports = __toCommonJS(auth_exports);
+
+// ../tsup-config/react-import.js
+var import_react = __toESM(require("react"));
+
+// src/lib/get-api-key.ts
+var getApiKey = () => process.env.PUCK_API_KEY;
+
+// src/lib/get-host.ts
+var getDefaultHost = () => (process.env.PUCK_HOST ?? "https://cloud.puckeditor.com/api").replace(
+  /\/+$/,
+  ""
+);
+
+// src/auth.ts
+var BASE_PATH = "/api/puck/auth";
+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 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) => {
+  if (!value || value.length > 512) return "/";
+  try {
+    const url = new URL(value, "https://puck.invalid");
+    if (url.origin === "https://puck.invalid" && !url.pathname.startsWith(BASE_PATH)) {
+      return `${url.pathname}${url.search}`;
+    }
+  } catch {
+  }
+  return "/";
+};
+function createPuckAuth(options = {}) {
+  const apiKey = () => {
+    const key = options.apiKey ?? getApiKey();
+    if (!key) {
+      throw new Error(
+        "Sign in with Puck requires an API key. Set PUCK_API_KEY or pass apiKey."
+      );
+    }
+    return key;
+  };
+  const host = (options.host ?? getDefaultHost()).replace(/\/+$/, "");
+  const cloudUrl = new URL(host).origin;
+  const appOrigin = (request) => new URL(options.appUrl ?? request.url).origin;
+  const isSecure = (request) => appOrigin(request).startsWith("https:");
+  const callbackUrl = (request) => `${appOrigin(request)}${BASE_PATH}/callback`;
+  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, clientId } = decodeCookie(
+      readCookie(headers, `__Host-${SESSION_COOKIE}`) ?? readCookie(headers, SESSION_COOKIE)
+    );
+    return typeof token === "string" && TOKEN_PATTERN.test(token) && typeof clientId === "string" ? { token, clientId } : void 0;
+  };
+  const loginUrl2 = (returnTo = "/") => `${BASE_PATH}/login?returnTo=${encodeURIComponent(safeReturnTo(returnTo))}`;
+  const html = (message, status, action = "Sign in") => new Response(
+    `<!doctype html><html lang="en"><meta charset="utf-8"><title>Puck</title><p>${message} <a href="${loginUrl2()}">${action}</a>.</p></html>`,
+    {
+      status,
+      headers: { ...noStore, "content-type": "text/html; charset=utf-8" }
+    }
+  );
+  const unauthorized = () => Response.json(
+    { error: "unauthorized", loginUrl: loginUrl2() },
+    { status: 401, headers: noStore }
+  );
+  const fetchCloudSession = async (accessToken) => {
+    const response = await fetch(`${host}/oauth/session`, {
+      headers: {
+        authorization: `Bearer ${accessToken}`,
+        "x-api-key": apiKey()
+      },
+      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}).`
+      );
+    }
+    const session = await response.json();
+    return session?.user?.id ? { ...session, cloudUrl } : null;
+  };
+  const resolve = async (headers) => {
+    const stored = readSessionCookie(headers);
+    if (!stored) return null;
+    const session = await fetchCloudSession(stored.token);
+    return session ? { session, accessToken: stored.token } : null;
+  };
+  const revoke = (accessToken, clientId) => fetch(`${host}/auth/oauth2/revoke`, {
+    method: "POST",
+    headers: { "content-type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams({ token: accessToken, client_id: clientId }),
+    signal: AbortSignal.timeout(1e4)
+  }).catch(() => void 0);
+  const registerClient = async (request) => {
+    const response = await fetch(`${host}/oauth/client`, {
+      method: "POST",
+      headers: { "content-type": "application/json", "x-api-key": apiKey() },
+      body: JSON.stringify({ callbackUrl: callbackUrl(request) }),
+      cache: "no-store",
+      signal: AbortSignal.timeout(1e4)
+    });
+    if (!response.ok) {
+      throw new Error(
+        `Puck Cloud couldn't set up Sign in with Puck (HTTP ${response.status}). Check PUCK_API_KEY.`
+      );
+    }
+    return await response.json();
+  };
+  const login = async (request, url) => {
+    const state = randomToken();
+    const verifier = randomToken();
+    const { clientId, redirectUri } = await registerClient(request);
+    const transaction = encodeCookie({
+      state,
+      verifier,
+      clientId,
+      redirectUri,
+      returnTo: safeReturnTo(url.searchParams.get("returnTo"))
+    });
+    const authorize = new URL(`${host}/auth/oauth2/authorize`);
+    authorize.search = new URLSearchParams({
+      client_id: clientId,
+      redirect_uri: redirectUri,
+      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 === "access_denied") {
+      return html(
+        "You don't have access to this project.",
+        403,
+        "Sign in with another account"
+      );
+    }
+    if (error) return html("Sign-in was cancelled or failed.", 400);
+    const { state, verifier, clientId, redirectUri, returnTo } = decodeCookie(readCookie(request.headers, cookieName(LOGIN_COOKIE, secure)));
+    const code = url.searchParams.get("code");
+    if (!code || typeof state !== "string" || typeof verifier !== "string" || typeof clientId !== "string" || typeof redirectUri !== "string" || 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: redirectUri,
+        client_id: clientId,
+        code_verifier: 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 session = await fetchCloudSession(accessToken);
+    const maxAge = Math.floor(
+      (Date.parse(session?.expiresAt ?? "") - Date.now()) / 1e3
+    );
+    if (!session || !(maxAge > 0)) {
+      await revoke(accessToken, clientId);
+      return html("Sign-in expired or was cancelled.", 400);
+    }
+    const headers = new Headers({
+      ...noStore,
+      location: new URL(safeReturnTo(returnTo), appOrigin(request)).toString()
+    });
+    headers.append("set-cookie", cookie(LOGIN_COOKIE, "", 0, secure));
+    headers.append(
+      "set-cookie",
+      cookie(
+        SESSION_COOKIE,
+        encodeCookie({ token: accessToken, clientId }),
+        maxAge,
+        secure
+      )
+    );
+    return new Response(null, { status: 303, headers });
+  };
+  const logout = async (request) => {
+    const stored = readSessionCookie(request.headers);
+    if (stored) await revoke(stored.token, stored.clientId);
+    return new Response(null, {
+      status: 303,
+      headers: {
+        ...noStore,
+        location: "/",
+        "set-cookie": cookie(SESSION_COOKIE, "", 0, isSecure(request))
+      }
+    });
+  };
+  const authenticate2 = async ({ request }) => {
+    const url = new URL(request.url);
+    if (url.pathname.startsWith(`${BASE_PATH}/`)) {
+      const route = `${request.method} ${url.pathname.slice(BASE_PATH.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: authenticate2,
+    getSession: async (headers) => (await resolve(headers))?.session ?? null,
+    loginUrl: loginUrl2
+  };
+}
+var defaultAuth;
+var getDefaultAuth = () => defaultAuth ??= createPuckAuth();
+var authenticate = (context) => getDefaultAuth().authenticate(context);
+var getSession = (headers) => getDefaultAuth().getSession(headers);
+var loginUrl = (returnTo) => getDefaultAuth().loginUrl(returnTo);
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  authenticate,
+  createPuckAuth,
+  getSession,
+  loginUrl,
+  safeReturnTo
+});