app/lib/editor/publish-policy.mjs

Functions

Imports

It imports no other module of this repo. Imported by app/kb/editor.server.ts, app/kb/form.server.ts, app/kb/procedures/save.server.ts, app/kb/registry/save.server.ts, app/lib/admin/posts-actions.server.ts, app/lib/carrel/site-adapter.server.ts, app/lib/cv/save.server.ts, app/lib/dictionary/save.server.ts, app/lib/editor/action.server.ts, app/lib/editor/feedback.ts, app/lib/editor/publish.server.ts, app/lib/llms/save.server.ts, app/lib/operator/api.server.ts, app/lib/pages/save.server.ts, app/lib/phages/save.server.ts, app/lib/publications/save.server.ts, app/lib/roster/save.server.ts, app/lib/webmention/decide.server.ts, app/routes/admin.mentions.tsx, app/routes/admin.tsx.

Source

1import matter from "gray-matter";
2
3/**
4 * @typedef {{ kind: "admin" } | { kind: "operator", id: string } | { kind: "smoke", id: string } | { kind: "carrel", changeId: string }} Actor
5 */
6
7export const SMOKE_READ_ONLY_POLICY = "smoke-is-read-only";
8
9/**
10 * Keyed by kind, so a new actor kind is a typecheck failure rather than a silent permission (a
11 * switch with a missing case compiles and falls through).
12 *
13 * @type {Readonly<Record<Actor["kind"], Readonly<{ write: boolean, firstPublish: boolean, destroy: boolean }>>>}
14 */
15export const WRITE_CAPABILITIES = {
16  admin: { write: true, firstPublish: true, destroy: true },
17  operator: { write: true, firstPublish: false, destroy: false },
18  /**
19   * Carrel's key, through /api/carrel/v1 only. It may publish for the first time (Carrel design
20   * decision 2: Carrel decides who triggers it) and may delete a post since site-api v0.3.0, which asks for
21   * it (DELETE /content/:id). Carrel's own rules decide who may ask; the site still checks the version.
22   */
23  carrel: { write: true, firstPublish: true, destroy: true },
24  /**
25   * Every capability false; check:policy asserts it. Read-only is not safe: it still sees drafts and
26   * the operator email (not stubbed, since the topbar's narrow-width measurement depends on it).
27   */
28  smoke: { write: false, firstPublish: false, destroy: false },
29};
30
31export class PolicyError extends Error {
32  /**
33   * @param {string} message
34   * @param {string} policy
35   */
36  constructor(message, policy) {
37    super(message);
38    this.name = "PolicyError";
39    /** @type {string} */
40    this.policy = policy;
41  }
42}
43
44/** @returns {string} */
45function today() {
46  return new Date().toISOString().slice(0, 10);
47}
48
49/**
50 * @param {string} raw
51 * @returns {{ draft: boolean, firstPublished: string | null }}
52 */
53export function readState(raw) {
54  const data = /** @type {Record<string, unknown>} */ (matter(raw).data);
55  const value = data.first_published;
56  const firstPublished =
57    value instanceof Date
58      ? value.toISOString().slice(0, 10)
59      : typeof value === "string" && value.trim()
60        ? value.trim()
61        : null;
62  return { draft: data.draft === true, firstPublished };
63}
64
65/**
66 * gray-matter turns an unquoted 2026-07-30 into a Date while the stamp writes a string, so both sides
67 * reduce a date to its ISO day before comparing.
68 *
69 * @param {Record<string, unknown>} data
70 * @returns {string}
71 */
72function comparableFrontmatter(data) {
73  /** @type {Record<string, unknown>} */
74  const flat = {};
75  for (const key of Object.keys(data).sort()) {
76    const value = data[key];
77    flat[key] = value instanceof Date ? value.toISOString().slice(0, 10) : value;
78  }
79  return JSON.stringify(flat);
80}
81
82/**
83 * Overwrites, and that is the security part: the value must come from the committed file, or an agent
84 * could publish a draft by submitting first_published itself. The line edit keeps the diff to one
85 * field; it is parsed back and kept only if exact, since a quoted key or a list value defeats it.
86 *
87 * @param {string} raw
88 * @param {string | null} value
89 * @returns {string}
90 */
91export function forceFirstPublished(raw, value) {
92  const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/.exec(raw);
93  if (!match) return raw;
94
95  const block = match[1];
96  if (block === undefined) return raw;
97  const rest = raw.slice(match[0].length);
98  const kept = block
99    .split("\n")
100    .filter((line) => !/^first_published\s*:/.test(line));
101
102  if (value) kept.push(`first_published: ${value}`);
103
104  const edited = `---\n${kept.join("\n")}\n---\n${rest}`;
105
106  const before = matter(raw);
107  const want = { .../** @type {Record<string, unknown>} */ (before.data) };
108  if (value) want.first_published = value;
109  else delete want.first_published;
110
111  try {
112    const after = matter(edited);
113    if (
114      after.content === before.content &&
115      comparableFrontmatter(/** @type {Record<string, unknown>} */ (after.data)) ===
116        comparableFrontmatter(want)
117    ) {
118      return edited;
119    }
120  } catch {
121    // YAML cannot read the edit. Fall through.
122  }
123
124  return matter.stringify(before.content, want);
125}
126
127/**
128 * Computed here because only the prior file can tell a first publication from a republication.
129 *
130 * @typedef {"saved" | "published-first" | "republished" | "unpublished"} SaveOutcome
131 */
132
133/**
134 * @param {{ wantsPublished: boolean, everPublished: boolean, priorDraft: boolean | null }} state
135 * @returns {SaveOutcome}
136 */
137function classify(state) {
138  if (state.wantsPublished) {
139    if (!state.everPublished) return "published-first";
140    return state.priorDraft === true ? "republished" : "saved";
141  }
142  return state.priorDraft === false ? "unpublished" : "saved";
143}
144
145/**
146 * Operators may not delete: the destructive verb needs more authority than publishing, not less.
147 * Throws rather than returning a boolean, so a caller that forgets to check cannot proceed.
148 *
149 * @param {{ actor: Actor }} options
150 * @returns {void}
151 * @throws {PolicyError} when the actor may not delete
152 */
153export function decideDelete(options) {
154  const may = WRITE_CAPABILITIES[options.actor.kind];
155
156  if (!may.write) {
157    throw new PolicyError(
158      "Refused: this credential is READ ONLY. It may render admin pages and it " +
159        "may not change anything, delete included.",
160      SMOKE_READ_ONLY_POLICY,
161    );
162  }
163
164  if (!may.destroy) {
165    throw new PolicyError(
166      "Refused: deleting a post is reserved to the human admin. An operator " +
167        "may create, edit, unpublish and republish a post, but not destroy it. " +
168        "Unpublish it instead (draft: true), which is reversible, and ask " +
169        "Dustin to delete it from /admin/posts if it should go for good.",
170      "delete-requires-admin",
171    );
172  }
173}
174
175/**
176 * @param {{ actor: Actor, incomingRaw: string, priorRaw: string | null }} options
177 * @returns {{ raw: string, firstPublished: string | null, published: boolean, outcome: SaveOutcome }}
178 */
179export function decide(options) {
180  const incoming = readState(options.incomingRaw);
181  const prior = options.priorRaw ? readState(options.priorRaw) : null;
182
183  // The prior FILE is the only authority, and the check is on the resulting state, not a diff.
184  const priorFirstPublished = prior?.firstPublished ?? null;
185  const wantsPublished = !incoming.draft;
186  const everPublished = priorFirstPublished !== null;
187
188  const may = WRITE_CAPABILITIES[options.actor.kind];
189
190  if (!may.write) {
191    throw new PolicyError(
192      "Refused: this credential is READ ONLY. It may render admin pages and it " +
193        "may not save a post, in any state, new or existing.",
194      SMOKE_READ_ONLY_POLICY,
195    );
196  }
197
198  if (!may.firstPublish && wantsPublished && !everPublished) {
199    throw new PolicyError(
200      "Refused: publishing a post for the first time is reserved to the human " +
201        "admin. This post has never been public, so an operator cannot set " +
202        "draft to false on it. Save it as a draft (draft: true) and ask Dustin " +
203        "to publish it from /admin/posts. Once it has been published once, an " +
204        "operator may unpublish and republish it freely.",
205      "first-publish-requires-admin",
206    );
207  }
208
209  const firstPublished =
210    priorFirstPublished ?? (wantsPublished ? today() : null);
211
212  return {
213    raw: forceFirstPublished(options.incomingRaw, firstPublished),
214    firstPublished,
215    published: wantsPublished,
216    outcome: classify({
217      wantsPublished,
218      everPublished,
219      priorDraft: prior ? prior.draft : null,
220    }),
221  };
222}
223
224/**
225 * The rule for a file kind whose only status is its own `draft` flag (procedures, publications): the
226 * same policy as a post, read from the prior FILE. An actor without the write capability is refused, and
227 * one without first-publish may unpublish and republish but never make something public that never was.
228 *
229 * @param {{ actor: Actor, noun: string, incomingDraft: boolean, priorRaw: string | null, isDraft: (raw: string) => boolean }} options
230 *   `noun` is the thing saved ("procedure"), named in the refusal.
231 */
232export function decideFileWrite({ actor, noun, incomingDraft, priorRaw, isDraft }) {
233  const may = WRITE_CAPABILITIES[actor.kind];
234  if (!may.write) {
235    throw new PolicyError(`Refused: this credential is READ ONLY and may not save a ${noun}.`, SMOKE_READ_ONLY_POLICY);
236  }
237  const everPublished = priorRaw !== null && !isDraft(priorRaw);
238  if (!may.firstPublish && !incomingDraft && !everPublished) {
239    throw new PolicyError(
240      `Refused: publishing a ${noun} for the first time is reserved to the human admin. Save it with ` +
241        "draft: true, and ask Dustin to publish it.",
242      "first-publish-requires-admin",
243    );
244  }
245}