app/lib/preview-token.mjs

Functions

Imports

It imports app/lib/bytes.mjs. Imported by app/lib/editor/preview-link-action.server.ts, app/lib/preview-links.server.ts, app/routes/admin.posts.$slug.edit.tsx, app/routes/preview.$token.tsx.

Source

1/**
2 * PURE on purpose: the rules that decide whether a stranger sees an unpublished post must be
3 * testable by `node --test`, which cannot import `.ts`. The token is an unsigned lookup key, so
4 * revocation is a delete and there is nothing in it to read, edit or forge.
5 */
6
7import { bytesToBase64 } from "./bytes.mjs";
8
9export const TOKEN_BYTES = 32;
10
11/** Derived rather than a typed 43, so it cannot go quietly wrong if the byte count changes. */
12export const TOKEN_LENGTH = Math.ceil((TOKEN_BYTES * 4) / 3);
13
14export const PREVIEW_TTL_SECONDS = 7 * 24 * 60 * 60;
15
16const TOKEN_PREFIX = "preview:token:";
17
18const POST_PREFIX = "preview:post:";
19
20/**
21 * Anchored and length-exact, because the read path uses it to decide whether to spend a KV read.
22 * A prefix match would let `<43 valid chars><anything>` through to the store.
23 */
24const TOKEN_PATTERN = new RegExp(`^[A-Za-z0-9_-]{${TOKEN_LENGTH}}$`);
25
26/**
27 * @returns {string} 43 base64url characters
28 */
29export function mintToken() {
30  const bytes = new Uint8Array(TOKEN_BYTES);
31  crypto.getRandomValues(bytes);
32  return base64url(bytes);
33}
34
35/**
36 * Without Buffer: it does not exist in the Worker runtime unless nodejs_compat is on.
37 *
38 * @param {Uint8Array} bytes
39 * @returns {string}
40 */
41export function base64url(bytes) {
42  return bytesToBase64(bytes).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
43}
44
45/**
46 * SHAPE ONLY. A true here says nothing about whether the token exists and is not permission.
47 *
48 * @param {unknown} token
49 * @returns {boolean}
50 */
51export function isWellFormedToken(token) {
52  return typeof token === "string" && TOKEN_PATTERN.test(token);
53}
54
55/**
56 * @param {string} token
57 * @returns {string}
58 */
59export function tokenKey(token) {
60  return `${TOKEN_PREFIX}${token}`;
61}
62
63/**
64 * @param {string} slug
65 * @returns {string}
66 */
67export function postIndexPrefix(slug) {
68  return `${POST_PREFIX}${slug}:`;
69}
70
71/**
72 * @param {string} slug
73 * @param {string} token
74 * @returns {string}
75 */
76export function postIndexKey(slug, token) {
77  return `${postIndexPrefix(slug)}${token}`;
78}
79
80/**
81 * Reads the token off the END rather than splitting on `:`, so it does not depend on
82 * `SLUG_PATTERN` continuing to forbid a colon.
83 *
84 * @param {string} key
85 * @param {string} slug
86 * @returns {string | null}
87 */
88export function tokenFromIndexKey(key, slug) {
89  const prefix = postIndexPrefix(slug);
90  if (!key.startsWith(prefix)) return null;
91  const token = key.slice(prefix.length);
92  return isWellFormedToken(token) ? token : null;
93}
94
95/**
96 * @typedef {object} PreviewRecord
97 * @property {string} slug
98 * @property {string} createdAt
99 * @property {string} createdBy
100 * @property {string} note
101 */
102
103/**
104 * @param {{ slug: string, createdAt: string, createdBy: string, note?: string }} input
105 * @returns {PreviewRecord}
106 */
107export function makeRecord(input) {
108  return {
109    slug: input.slug,
110    createdAt: input.createdAt,
111    createdBy: input.createdBy,
112    note: input.note ?? "",
113  };
114}
115
116/**
117 * FAILS CLOSED: a half-read record must never become a partially trusted one.
118 *
119 * @param {unknown} raw
120 * @returns {PreviewRecord | null}
121 */
122export function parseRecord(raw) {
123  if (typeof raw !== "string" || raw === "") return null;
124  let parsed;
125  try {
126    parsed = JSON.parse(raw);
127  } catch {
128    return null;
129  }
130  if (!parsed || typeof parsed !== "object") return null;
131  const slug = /** @type {any} */ (parsed).slug;
132  if (typeof slug !== "string" || slug.trim() === "") return null;
133  return makeRecord({
134    slug,
135    createdAt: String(/** @type {any} */ (parsed).createdAt ?? ""),
136    createdBy: String(/** @type {any} */ (parsed).createdBy ?? ""),
137    note: String(/** @type {any} */ (parsed).note ?? ""),
138  });
139}
140
141/**
142 * ADVISORY: KV's `expirationTtl` is what actually expires the key. If they disagree, KV wins.
143 *
144 * @param {string} createdAt
145 * @returns {string} ISO 8601, or "" when createdAt is unreadable
146 */
147export function expiresAt(createdAt) {
148  const at = Date.parse(createdAt);
149  if (Number.isNaN(at)) return "";
150  return new Date(at + PREVIEW_TTL_SECONDS * 1000).toISOString();
151}
152
153/**
154 * The full token is a CAPABILITY: anyone who reads it off a screen holds the link. Six
155 * characters is enough to recognize and revoke.
156 *
157 * @param {string} token
158 * @returns {string}
159 */
160export function truncateToken(token) {
161  return token.slice(0, 6);
162}
163
164/**
165 * @param {string} origin
166 * @param {string} token
167 * @returns {string}
168 */
169export function previewUrl(origin, token) {
170  return `${origin.replace(/\/+$/, "")}/preview/${token}`;
171}
172
173/**
174 * The reasons are for server logs and tests only. The route turns every failure into one
175 * response, so a stranger cannot learn whether a token or a slug exists.
176 *
177 * @param {object} input
178 * @param {unknown} input.token
179 * @param {PreviewRecord | null} input.record
180 * @param {{ slug: string, status: string } | null} input.post
181 * @returns {{ ok: boolean, reason: "ok" | "malformed" | "unknown" | "mismatch" | "missing-post" | "not-draft" }}
182 */
183export function resolvePreview({ token, record, post }) {
184  if (!isWellFormedToken(token)) return { ok: false, reason: "malformed" };
185
186  // Unknown, expired and revoked are all a KV delete, so they cannot be told apart.
187  if (!record) return { ok: false, reason: "unknown" };
188
189  // A deleted draft's tokens outlive it by up to seven days.
190  if (!post) return { ok: false, reason: "missing-post" };
191
192  if (record.slug !== post.slug) return { ok: false, reason: "mismatch" };
193
194  // Publishing revokes tokens, but that write can fail and KV is eventually consistent, so the
195  // read path re-checks draft status every time.
196  if (post.status !== "draft") return { ok: false, reason: "not-draft" };
197
198  return { ok: true, reason: "ok" };
199}