@shapio/local 0.5.0 → 0.5.1

package/dist/index.d.ts

@@ -36,6 +36,12 @@ type LocalClientOptions = {
   fallbackUrl?: string;
   /** Where failures are logged (pino). Default: warnings and errors to stdout. */
   logger?: Logger;
+  /**
+   * Drafts mode, for a site's development server: every delivery read asks for drafts instead of published
+   * content (as `@shapio/client`'s `drafts`). Needs a delivery token whose role grants Read drafts; never set
+   * it on a production build.
+   */
+  drafts?: boolean;
 };
 /** The server runs another Shapio release (503 `VERSION_SKEW`); null when the database predates this one. */
 type ShapioVersionSkewError$1 = ShapioApiError & {
@@ -71,12 +77,13 @@ export type LocalClient = ShapioDeliveryClient & {
  * Shapio's delivery API as function calls in this process: the `delivery`, `site` and `snapshots` groups of
  * `@shapio/client`, with the same paths, permissions, response shapes and `ShapioApiError`s, answered from the
  * database without an HTTP hop. Reads as `token` (a delivery API token) or, without one, as an anonymous
- * caller (the site's `public` role). Model changes made in the admin show on the next call.
+ * caller (the site's `public` role). Model changes made in the admin show on the next call. `drafts: true`
+ * reads drafts instead (drafts mode), when the token's role grants Read drafts.
  *
  * Needs PostgreSQL or MySQL, the Node.js runtime, and the same Shapio release as the server (`SHAPIO_VERSION`);
  * see `onVersionSkew`. Nothing is read until the first call.
  */
-export declare const createLocalClient: ({ token, site, ...runtimeOptions }: LocalClientOptions) => LocalClient;
+export declare const createLocalClient: ({ token, site, drafts, ...runtimeOptions }: LocalClientOptions) => LocalClient;
 //#endregion
 export type { LocalClientOptions };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -15,7 +15,7 @@ import { mkdir, rename, rm, rmdir, stat, writeFile } from "node:fs/promises";
 import { pipeline } from "node:stream/promises";
 //#endregion
 //#region ../../apps/api/src/constants/version.ts
-const SHAPIO_VERSION$1 = "0.5.0";
+const SHAPIO_VERSION$1 = "0.5.1";
 //#endregion
 //#region ../../apps/api/src/helpers/errorResponse.ts
 const STATUS_CODES = {
@@ -206,6 +206,14 @@ const CONTENT_ACTIONS = [
 	"schemaManage"
 ];
 /**
+* What a delivery role may grant (plan drafts-mode §1): `read`, and `readDrafts`, which lets a delivery token
+* read draft heads (`?publicationState=draft`, GraphQL `publicationState: DRAFT`) on top of `read`. A
+* `readDrafts` grant always covers every model (no model, condition or field list), so one check per request
+* covers relation targets too. Admin and app roles never hold it; admin principals read drafts without it.
+*/
+const DELIVERY_ACTIONS = ["read", "readDrafts"];
+const READ_DRAFTS_ACTION = "readDrafts";
+/**
 * Content actions about the schema rather than one site's entries: network roles only for a shared
 * definition; for a site's own definition, the roles that apply on that site (when the principal acts there).
 */
@@ -317,7 +325,11 @@ Type.Enum(NETWORK_ACTIONS);
 Type.Enum(SITE_ACTIONS);
 Type.Enum([...SITE_ACTIONS, ...SITE_GRANTABLE_ACTION_LIST]);
 Type.Object({
-	action: Type.Enum([...CONTENT_ACTIONS, ...GLOBAL_ACTIONS]),
+	action: Type.Enum([
+		...CONTENT_ACTIONS,
+		READ_DRAFTS_ACTION,
+		...GLOBAL_ACTIONS
+	]),
 	modelId: Type.Union([Type.String({
 		minLength: 1,
 		maxLength: 100
@@ -427,6 +439,8 @@ const RICH_TEXT_MODES = [
 	"both"
 ];
 /** `?seo=`: SEO fields as stored, or merged with the site's SEO defaults (plan seo-fields). */
+/** Which heads a delivery read serves (`?publicationState=`, GraphQL's `publicationState`). */
+const PUBLICATION_STATES = ["published", "draft"];
 const SEO_MODES = ["raw", "resolved"];
 const ENTRY_LIST_STATUSES = [
 	"draft",
@@ -2201,6 +2215,7 @@ const TOP_LEVEL_KEYS = /* @__PURE__ */ new Set([
 	"snapshot",
 	"richText",
 	"seo",
+	"publicationState",
 	"q",
 	"status",
 	"author"
@@ -2380,6 +2395,18 @@ const parseSeo = (tree, context) => {
 	if (value === "resolved" && !context.model.fields.some((field) => !field.deprecated && isSeoField(field) && context.isReadable(field))) throw queryInvalid(`"${context.model.apiKey}" has no SEO field to resolve`);
 	return { seo: value };
 };
+const PUBLICATION_STATE_SET = new Set(PUBLICATION_STATES);
+/**
+* `?publicationState=published|draft` on delivery reads; whether the caller may read drafts is the service's
+* check.
+*/
+const parsePublicationState = (tree, context) => {
+	const value = single(tree.publicationState, "publicationState");
+	if (value === void 0) return {};
+	if (!context.allowPublicationState) throw queryInvalid("publicationState is only available on the delivery API");
+	if (!PUBLICATION_STATE_SET.has(value)) throw queryInvalid(`"publicationState" must be one of ${PUBLICATION_STATES.join(", ")}`);
+	return { publicationState: value };
+};
 const parseContentQuery = (tree, context) => {
 	for (const key of Object.keys(tree)) if (!TOP_LEVEL_KEYS.has(key)) throw queryInvalid(`Unknown query parameter "${key}"`);
 	const filters = tree.filters;
@@ -2403,6 +2430,7 @@ const parseContentQuery = (tree, context) => {
 		snapshot,
 		...parseRichText(tree, context),
 		...parseSeo(tree, context),
+		...parsePublicationState(tree, context),
 		...parseAdminFilters(tree, context)
 	};
 };
@@ -2443,6 +2471,7 @@ const parseQueryFor = (context, model, policy, rawQuery, options) => parseConten
 	allowAdminFilters: options.allowAdminFilters ?? false,
 	allowRichText: options.allowRichText ?? false,
 	allowSeo: options.allowSeo ?? false,
+	allowPublicationState: options.allowPublicationState ?? false,
 	resolveModel: (modelId) => resolveModelById(context.snapshot, modelId)?.definition
 });
 //#endregion
@@ -2648,6 +2677,26 @@ const readOneEntry = async (unloaded, id, options = {}) => {
 	});
 };
 //#endregion
+//#region ../../apps/api/src/services/draftAccess.ts
+/**
+* Who may read draft heads through the delivery API (plan drafts-mode §1). Admin users, admin-scope tokens
+* and Shapio itself always could (GraphQL previews). A delivery token may when its role grants `readDrafts`,
+* which always covers every model, so this one check per request also covers relation targets. App users and
+* anonymous callers never may, whatever a role says (the evaluator denies them too). The caller has already
+* checked `read` on the model.
+*/
+const isAdminPrincipal = (principal) => principal.kind === "system" || principal.kind === "admin" || principal.kind === "token" && principal.scope === "admin";
+const draftsForbidden = (message) => new AppError(403, "DRAFTS_FORBIDDEN", message);
+const assertMayReadDrafts = async (context, modelId, modelKey) => {
+	const { actor } = context;
+	if (isAdminPrincipal(actor)) return;
+	if (actor.kind !== "token") throw draftsForbidden("Drafts need an admin user or a delivery token granted Read drafts");
+	if (!(await context.permissions.evaluate(actor, {
+		action: "readDrafts",
+		modelId
+	})).allowed) throw draftsForbidden(`This token may not read drafts of "${modelKey}"; grant Read drafts on its delivery role`);
+};
+//#endregion
 //#region ../../apps/api/src/services/contentDelivery.ts
 const readableModel = async (context, modelKey) => {
 	const model = resolveModel(context.snapshot, modelKey);
@@ -2661,10 +2710,19 @@ const readableModel = async (context, modelKey) => {
 		policy
 	};
 };
-/** The heads a read serves: drafts (GraphQL previews), a pinned snapshot, or the published heads. */
-const sourceOf = (query, options) => {
-	if (query.snapshot !== void 0 && options.drafts) throw queryInvalid("snapshot reads published content; it cannot be combined with drafts");
-	return options.drafts ? {
+/** Whether a read asks for drafts: GraphQL's option, or `?publicationState=draft`. */
+const readsDrafts = (query, options) => options.drafts === true || query.publicationState === "draft";
+/**
+* A draft read must be allowed: `read` was checked already; `readDrafts` (or an admin principal) is checked
+* here.
+*/
+const authorizeDrafts = async (context, model, modelKey, drafts) => {
+	if (drafts) await assertMayReadDrafts(context, model.definition.id, modelKey);
+};
+/** The heads a read serves: drafts, a pinned snapshot, or the published heads. */
+const sourceOf = (query, drafts) => {
+	if (query.snapshot !== void 0 && drafts) throw queryInvalid("snapshot reads published content; it cannot be combined with drafts");
+	return drafts ? {
 		kind: "heads",
 		state: "draft"
 	} : query.snapshot !== void 0 ? {
@@ -2685,7 +2743,7 @@ const snapshotCheck = (query) => (current) => {
 */
 const recordUsage = async (context, options, model, policy, query) => {
 	const principalKey = usagePrincipalKey(context.actor);
-	if (!options.usage || options.drafts || principalKey === null) return;
+	if (!options.usage || readsDrafts(query, options) || principalKey === null) return;
 	const reads = await restFieldReads({
 		snapshot: context.snapshot,
 		model,
@@ -2713,8 +2771,24 @@ const ITEM_PARAMETERS = /* @__PURE__ */ new Set([
 	"locale",
 	"snapshot",
 	"richText",
-	"seo"
+	"seo",
+	"publicationState"
 ]);
+const DELIVERY_PARSE = {
+	allowSnapshot: true,
+	allowRichText: true,
+	allowSeo: true,
+	allowPublicationState: true
+};
+/** Meta every delivery response carries; draft reads add `publicationState` (published ones are unchanged). */
+const metaOf = (locale, snapshot, drafts) => drafts ? {
+	locale,
+	snapshot,
+	publicationState: "draft"
+} : {
+	locale,
+	snapshot
+};
 /** Reading one entry takes only these query parameters; anything else is refused, not ignored. */
 const assertItemParameters = (rawQuery, allowed) => {
 	const unsupported = [...new URLSearchParams(rawQuery).keys()].find((key) => !allowed.has(key.split("[")[0] ?? key));
@@ -2723,16 +2797,15 @@ const assertItemParameters = (rawQuery, allowed) => {
 /** `GET /api/content/:modelKey`: a page of a collection, or a singleton's one entry. */
 const listDelivery = async (context, modelKey, rawQuery, options = {}) => {
 	const { model, policy } = await readableModel(context, modelKey);
-	const query = parseQueryFor(context, model, policy, rawQuery, {
-		allowSnapshot: true,
-		allowRichText: true,
-		allowSeo: true
-	});
+	const query = parseQueryFor(context, model, policy, rawQuery, DELIVERY_PARSE);
+	const drafts = readsDrafts(query, options);
+	const source = sourceOf(query, drafts);
+	await authorizeDrafts(context, model, modelKey, drafts);
 	const locale = query.locale ?? context.snapshot.defaultLocale;
 	const singleton = model.definition.kind === "singleton";
 	const { entries, limit, total, seq } = await readEntryPage({
 		context,
-		source: sourceOf(query, options),
+		source,
 		model,
 		policy,
 		query,
@@ -2748,34 +2821,32 @@ const listDelivery = async (context, modelKey, rawQuery, options = {}) => {
 		if (!entry) throw entryNotFound(modelKey);
 		result = {
 			data: entry,
-			meta: {
-				locale,
-				snapshot
-			}
+			meta: metaOf(locale, snapshot, drafts)
 		};
 	} else result = {
 		data: entries,
 		meta: {
-			locale,
-			snapshot,
+			...metaOf(locale, snapshot, drafts),
 			pagination: paginationMeta(query.page, limit, total)
 		}
 	};
 	await afterRead(options, () => recordUsage(context, options, model, policy, query));
 	return result;
 };
-/** `GET /api/content/:modelKey/:id`: one published entry (404 for drafts, unknown or unreadable entries). */
+/**
+* `GET /api/content/:modelKey/:id`: one published entry (404 for unpublished, unknown or unreadable entries);
+* with drafts, the entry's draft.
+*/
 const getDelivery = async (context, modelKey, id, rawQuery, options = {}) => {
 	assertItemParameters(rawQuery, ITEM_PARAMETERS);
 	const { model, policy } = await readableModel(context, modelKey);
-	const query = parseQueryFor(context, model, policy, rawQuery, {
-		allowSnapshot: true,
-		allowRichText: true,
-		allowSeo: true
-	});
+	const query = parseQueryFor(context, model, policy, rawQuery, DELIVERY_PARSE);
+	const drafts = readsDrafts(query, options);
+	const source = sourceOf(query, drafts);
+	await authorizeDrafts(context, model, modelKey, drafts);
 	const { entry, seq } = await readOneEntry({
 		context,
-		source: sourceOf(query, options),
+		source,
 		model,
 		policy,
 		query,
@@ -2785,10 +2856,7 @@ const getDelivery = async (context, modelKey, id, rawQuery, options = {}) => {
 	await afterRead(options, () => recordUsage(context, options, model, policy, query));
 	return {
 		data: entry,
-		meta: {
-			locale: query.locale ?? context.snapshot.defaultLocale,
-			snapshot: query.snapshot ?? seq
-		}
+		meta: metaOf(query.locale ?? context.snapshot.defaultLocale, query.snapshot ?? seq, drafts)
 	};
 };
 //#endregion
@@ -3809,7 +3877,11 @@ const groupBindings = (rows) => {
 	}
 	return bindings;
 };
-const KNOWN_ACTIONS = /* @__PURE__ */ new Set([...CONTENT_ACTIONS, ...GLOBAL_ACTIONS]);
+const KNOWN_ACTIONS = /* @__PURE__ */ new Set([
+	...CONTENT_ACTIONS,
+	...DELIVERY_ACTIONS,
+	...GLOBAL_ACTIONS
+]);
 const KNOWN_CONDITIONS = /* @__PURE__ */ new Set(["ownedByPrincipal"]);
 /**
 * A stored grant as this build understands it. Rows written by a newer Shapio may name an action or a row
@@ -3955,7 +4027,9 @@ const allowsGlobalAction = (grants, action) => grants.some((grant) => grant.acti
 //#endregion
 //#region ../../apps/api/src/permissions/evaluator.ts
 const NETWORK_ACTION_SET = new Set(NETWORK_ACTIONS);
-const READ_ONLY = /* @__PURE__ */ new Set(["read"]);
+/** Delivery tokens read, and read drafts where their role grants `readDrafts`. */
+const DELIVERY_TOKEN_ACTIONS = new Set(DELIVERY_ACTIONS);
+/** App users and anonymous callers: never `readDrafts`, whatever a role says. */
 const APP_ACTIONS = new Set(APP_CONTENT_ACTIONS);
 /**
 * Which roles a principal holds and how its masks are computed. App users hold the custom app roles assigned
@@ -3982,7 +4056,7 @@ const rolesOf = async (principal, grants, executor, versions) => {
 			roleIds: [principal.roleId],
 			networkRoleIds: [],
 			audience: "delivery",
-			actions: READ_ONLY
+			actions: DELIVERY_TOKEN_ACTIONS
 		};
 		case "appUser": return {
 			roleIds: [...await grants.getSiteAppRoleIds(principal.siteId, "authenticated", executor, versions), ...principal.roleIds],
@@ -4457,12 +4531,13 @@ const DeliveryRuntimeError = DeliveryRuntimeError$1;
 * Shapio's delivery API as function calls in this process: the `delivery`, `site` and `snapshots` groups of
 * `@shapio/client`, with the same paths, permissions, response shapes and `ShapioApiError`s, answered from the
 * database without an HTTP hop. Reads as `token` (a delivery API token) or, without one, as an anonymous
-* caller (the site's `public` role). Model changes made in the admin show on the next call.
+* caller (the site's `public` role). Model changes made in the admin show on the next call. `drafts: true`
+* reads drafts instead (drafts mode), when the token's role grants Read drafts.
 *
 * Needs PostgreSQL or MySQL, the Node.js runtime, and the same Shapio release as the server (`SHAPIO_VERSION`);
 * see `onVersionSkew`. Nothing is read until the first call.
 */
-const createLocalClient = ({ token, site, ...runtimeOptions }) => {
+const createLocalClient = ({ token, site, drafts, ...runtimeOptions }) => {
 	assertNodeRuntime();
 	const runtime = createDeliveryRuntime(runtimeOptions);
 	const release = runtime.retain();
@@ -4471,7 +4546,10 @@ const createLocalClient = ({ token, site, ...runtimeOptions }) => {
 		...site !== void 0 ? { site } : {}
 	});
 	return {
-		...createDeliveryClient(request, site !== void 0 ? { site } : {}),
+		...createDeliveryClient(request, {
+			...site !== void 0 ? { site } : {},
+			...drafts !== void 0 ? { drafts } : {}
+		}),
 		close: release
 	};
 };