Simplify page expiration to be consumer-driven (#19)

Page expiration was over-built: it included an operator-side, server-read
namespace policy (PUB_NAMESPACE_CONFIG) that made enabling expiration a
deployment concern. That decision belongs to the publisher, not the operator.

- Remove src/core/namespace-config.ts, PUB_NAMESPACE_CONFIG, and the
  resolveNamespaceExpiration option. The server now simply honors the
  expiration it is sent.
- Let a consumer set a default in their own CLI config
  (~/.config/pub/config.json): top-level `defaultExpires` and/or per-namespace
  `expires`. The CLI sends the explicit --expires flag as `expires` and the
  config default as a separate, lower-priority `defaultExpires`.
- Precedence (most specific wins): --expires flag → document frontmatter/
  <meta> → namespace config → global default. This keeps a page's own
  `expires: never` able to pin it even under a namespace default.

Per-page expiration needs no server configuration at all.


Claude-Session: https://claude.ai/code/session_01YNt2ZWLzXwnH6zonhVSQ41

Co-authored-by: Claude <noreply@anthropic.com>

Author: Restuta

README.md

@@ -245,15 +245,19 @@ disappears from `pubmd list`.
 A TTL can be set at three levels — **most specific wins**:
 
 1. **Per page** — a CLI flag, frontmatter, or an HTML `<meta>` tag.
-2. **Per namespace** — server-side policy, so sensitive namespaces can expire
-   everything by default.
-3. **Global default** — server-side fallback (off unless configured).
+2. **Per namespace (your config)** — a default in your CLI config for a given
+   namespace, so all your publishes to a sensitive namespace expire.
+3. **Your global default** — a default in your CLI config applied to every
+   publish.
+
+It's all consumer-driven: the publisher chooses the TTL, the server just honors
+it. There is no server-side configuration to enable expiration.
 
 When expiration is turned on but no duration is given, the default is **14 days**.
 
 Durations accept `m` (minutes), `h` (hours), `d` (days), and `w` (weeks); a bare
 number means days. `true` means "use the default", and `never` / `false` opts a
-page out (even of a namespace policy).
+publish out (even of a config default).
 
 ### Per page
 
@@ -282,24 +286,30 @@ includes an `expiresAt` timestamp (or `null` when the page never expires).
 Re-publishing identical content keeps the original deadline; changing the
 content (or the TTL) resets the clock.
 
-### Per namespace (server config)
+### Default for your publishes (CLI config)
 
-The server reads a per-namespace policy from `PUB_NAMESPACE_CONFIG`, which is
-either a path to a JSON file or inline JSON:
+To avoid passing `--expires` every time, set a default in your own config file
+(`~/.config/pub/config.json`). Use a top-level `defaultExpires` for all your
+publishes, and/or an `expires` under a specific namespace so everything you
+publish there expires:
 
 ```json
 {
-  "default": { "expires": false },
+  "apiBaseUrl": "https://bul.sh",
+  "defaultNamespace": "me",
+  "defaultExpires": false,
   "namespaces": {
-    "secret":  { "expires": true },
-    "scratch": { "expires": "7d" }
+    "me":     { "token": "…" },
+    "secret": { "token": "…", "expires": "14d" },
+    "scratch":{ "token": "…", "expires": "7d" }
   }
 }
 ```
 
-With this config, every page published to `secret` expires after the default
-14 days and everything in `scratch` after 7 days — unless the page sets its own
-`expires` (including `expires: never` to pin it).
+Precedence is most-specific-wins: `--expires` flag → the page's own
+frontmatter / `<meta>` → the namespace's `expires` → `defaultExpires`. So a
+document with `expires: never` still pins itself even when its namespace
+defaults to expiring, and `--expires never` overrides everything for one publish.
 
 Expired pages are hidden lazily — they return `404` and drop out of `list`
 immediately, but the underlying record stays in storage until the slug is

docs/progress.md

@@ -19,4 +19,5 @@
 - 2026-04-03: Added Obsidian-style callout rendering with aliases, collapsible `+`/`-` support, and type-specific styling. Verified with `npm run verify` and local browser QA screenshots.
 - 2026-06-25: Added opt-in review annotations for published markdown/HTML pages. `--review`, markdown `review: true`, or HTML `<meta name="pubmd:review" content="true">` injects inline comments, hover targeting, per-comment deletion, and a copyable feedback prompt while preserving raw source.
 - 2026-06-25: Refined review annotations into comment-mode sharing. `--comments`, markdown `comments: true`, and HTML `<meta name="pubmd:comments" content="true">` are now the preferred opt-ins. The CLI prints `?comments=1` for commentable pages, and removing the query string keeps the same page readable without comment UI.
-- 2026-06-29: Added expiring pages (TTL). Pages never expire by default; a TTL can be set per page (`--expires`, frontmatter `expires:`, or `<meta name="pubmd:expires">`), per namespace (server `PUB_NAMESPACE_CONFIG` policy so sensitive namespaces expire by default), or via a global default, with most-specific-wins precedence and a 14-day default when no duration is given. Expired pages return 404 and drop out of `list`; the CDN cache is capped at the deadline. Verified with `npm run verify`.
+- 2026-06-29: Added expiring pages (TTL). Pages never expire by default; a TTL can be set per page (`--expires`, frontmatter `expires:`, or `<meta name="pubmd:expires">`), with a 14-day default when expiration is enabled without a duration. Expired pages return 404 and drop out of `list`; the CDN cache is capped at the deadline. Verified with `npm run verify`.
+- 2026-06-29: Simplified expiration to be fully consumer-driven. Removed the operator-side `PUB_NAMESPACE_CONFIG` server policy (and the `namespace-config` module) — the server now just honors the `expires` it is sent. Consumers set a default in their own CLI config (`~/.config/pub/config.json`): top-level `defaultExpires` and/or per-namespace `expires`, with precedence flag → namespace → global. No server configuration is required to use expiration.

docs/project-plan.md

@@ -165,7 +165,7 @@ Local .pub mapping:
 - [ ] Page renames with redirects — data model already supports this
 - [ ] View count analytics
 - [ ] Page collections with auto-generated index
-- [x] Expiring pages (TTL) — per-page (flag/frontmatter/meta), per-namespace policy, 14-day default
+- [x] Expiring pages (TTL) — per-page (flag/frontmatter/meta) + consumer config default, 14-day default
 - [ ] Custom domains (namespace.pub.domain)
 - [ ] Web editor (CodeMirror with markdown + live preview)
 - [ ] Batch publish API

src/cli/config.ts

@@ -4,13 +4,21 @@ import path from "node:path";
 
 import { z } from "zod";
 
+import { ExpirationSettingSchema } from "../core/contract.js";
+
 const NamespaceConfigSchema = z.object({
   token: z.string().min(1),
+  // Optional per-namespace default expiration for this consumer's publishes.
+  // A duration ("7d"), a number of days, true (14-day default), or never.
+  expires: ExpirationSettingSchema.optional(),
 });
 
 const ConfigSchema = z.object({
   apiBaseUrl: z.string().url().optional(),
   defaultNamespace: z.string().optional(),
+  // Optional default expiration applied to every publish unless the namespace
+  // or the publish itself overrides it.
+  defaultExpires: ExpirationSettingSchema.optional(),
   namespaces: z.record(z.string(), NamespaceConfigSchema),
 });
 

src/cli/main.ts

@@ -9,6 +9,7 @@ import {
   ListPagesResponseSchema,
   PublishedPageSchema,
 } from "../core/contract.js";
+import type { ExpirationSetting } from "../core/expiration.js";
 import { inlineHtmlAssets } from "../core/inline-html.js";
 import { parseMarkdownDocument } from "../core/markdown.js";
 import { prepareMarkdownBodyForPublish } from "../core/publish-markdown.js";
@@ -165,7 +166,12 @@ async function runPublish(context: CommandContext): Promise<void> {
     existingPage?.pageId === undefined ? {} : { pageId: existingPage.pageId };
   const reviewAnnotations =
     options.review === true || options.comments === true;
+  // The --expires flag is the explicit per-publish override; the consumer's
+  // config (per-namespace, then global) is a lower-priority default that the
+  // server ranks below the document's own frontmatter/<meta>.
   const expires = options.expires;
+  const defaultExpires =
+    config.namespaces[namespace]?.expires ?? config.defaultExpires;
   const requestBody =
     absoluteFilePath !== undefined && /\.html?$/i.test(absoluteFilePath)
       ? await buildHtmlRequestBody(
@@ -174,13 +180,15 @@ async function runPublish(context: CommandContext): Promise<void> {
           pageIdPart,
           reviewAnnotations,
           expires,
+          defaultExpires,
         )
       : await buildMarkdownRequestBody(
           absoluteFilePath,
           slug,
           pageIdPart,
           reviewAnnotations,
           expires,
+          defaultExpires,
         );
 
   const response = await fetch(
@@ -255,7 +263,8 @@ async function buildMarkdownRequestBody(
   slug: string | undefined,
   pageIdPart: { pageId?: string },
   reviewAnnotations: boolean,
-  expires: string | undefined,
+  expires: ExpirationSetting,
+  defaultExpires: ExpirationSetting,
 ): Promise<Record<string, unknown>> {
   const markdown =
     absoluteFilePath === undefined
@@ -274,6 +283,7 @@ async function buildMarkdownRequestBody(
     ...(renderMarkdown === undefined ? {} : { renderMarkdown }),
     ...(shouldInjectReview ? { reviewAnnotations: true } : {}),
     ...(expires === undefined ? {} : { expires }),
+    ...(defaultExpires === undefined ? {} : { defaultExpires }),
     ...(slug === undefined ? {} : { slug }),
     ...pageIdPart,
   };
@@ -284,7 +294,8 @@ async function buildHtmlRequestBody(
   slug: string | undefined,
   pageIdPart: { pageId?: string },
   reviewAnnotations: boolean,
-  expires: string | undefined,
+  expires: ExpirationSetting,
+  defaultExpires: ExpirationSetting,
 ): Promise<Record<string, unknown>> {
   const source = await readFile(absoluteFilePath, "utf8");
   const inlined = await inlineHtmlAssets(source, {
@@ -312,6 +323,7 @@ async function buildHtmlRequestBody(
     document,
     ...(shouldInjectReview ? { reviewAnnotations: true } : {}),
     ...(expires === undefined ? {} : { expires }),
+    ...(defaultExpires === undefined ? {} : { defaultExpires }),
     slug: slug ?? fallbackSlug,
     ...pageIdPart,
   };
@@ -539,7 +551,9 @@ function printHelp(): void {
 
   --expires <when> sets a time-to-live: a duration like 7d, 12h, 30m or 2w,
   or "true" for the default 14 days, or "never". Pages never expire unless a
-  TTL is set here, in frontmatter (expires:), or by namespace policy.`);
+  TTL is set here, in frontmatter (expires:), or as a default in your config
+  (~/.config/pub/config.json: top-level "defaultExpires", or "expires" under a
+  namespace).`);
 }
 
 main().catch((error: unknown) => {

src/core/contract.ts

@@ -45,6 +45,8 @@ export const PublishPageRequestSchema = z.object({
   renderMarkdown: z.string().min(1).optional(),
   reviewAnnotations: z.boolean().optional(),
   expires: ExpirationSettingSchema.optional(),
+  /** Lower-priority fallback than `expires`/frontmatter (the publisher's config default). */
+  defaultExpires: ExpirationSettingSchema.optional(),
   slug: NameSchema.optional(),
   pageId: z.string().uuid().optional(),
 });
@@ -57,6 +59,8 @@ export const PublishHtmlRequestSchema = z.object({
   document: z.string().min(1).optional(),
   reviewAnnotations: z.boolean().optional(),
   expires: ExpirationSettingSchema.optional(),
+  /** Lower-priority fallback than `expires`/`<meta>` (the publisher's config default). */
+  defaultExpires: ExpirationSettingSchema.optional(),
   title: z.string().trim().min(1).max(200).optional(),
   description: z.string().trim().min(1).max(300).optional(),
   noindex: z.boolean().optional(),

src/core/namespace-config.ts

@@ -19,7 +19,6 @@ import {
   parseMarkdownDocument,
   renderMarkdownToHtml,
 } from "./markdown.js";
-import type { NamespaceExpirationResolver } from "./namespace-config.js";
 import {
   AuthenticationError,
   NamespaceExistsError,
@@ -47,6 +46,8 @@ export interface PublishPageInput {
   description?: string;
   noindex?: boolean;
   expires?: ExpirationSetting;
+  /** Lower-priority fallback than `expires` and the document's own setting. */
+  defaultExpires?: ExpirationSetting;
   // common
   namespace: string;
   pageId?: string;
@@ -90,26 +91,13 @@ export interface PublishService {
 export interface PublishServiceOptions {
   /** Clock injection for testability; defaults to `Date.now`. */
   now?: () => number;
-  /** Per-namespace expiration policy; defaults to "no policy". */
-  resolveNamespaceExpiration?: NamespaceExpirationResolver;
 }
 
 export function createPublishService(
   repository: PublishRepository,
   options: PublishServiceOptions = {},
 ): PublishService {
   const now = options.now ?? (() => Date.now());
-  const resolveNamespaceExpiration =
-    options.resolveNamespaceExpiration ?? (() => undefined);
-
-  function resolvePageExpirationMs(
-    namespace: string,
-    pageSetting: ExpirationSetting,
-  ): number | null {
-    return resolveExpirationMs(
-      coalesceExpiration(pageSetting, resolveNamespaceExpiration(namespace)),
-    );
-  }
 
   async function claimNamespace(
     namespace: string,
@@ -153,9 +141,14 @@ export function createPublishService(
     const slug = safeSlug;
     const nowMs = now();
     const nowIso = new Date(nowMs).toISOString();
-    const expirationMs = resolvePageExpirationMs(
-      safeNamespace,
-      coalesceExpiration(input.expires, parsed.frontmatter.expires),
+    // Precedence: explicit per-publish `expires` → document frontmatter →
+    // the publisher's config default. Most specific wins.
+    const expirationMs = resolveExpirationMs(
+      coalesceExpiration(
+        input.expires,
+        parsed.frontmatter.expires,
+        input.defaultExpires,
+      ),
     );
     const markdownBlobKey = `${pageId}.md`;
     const htmlBlobKey = `${pageId}.html`;
@@ -271,11 +264,13 @@ export function createPublishService(
     const pageId = existingPage?.pageId ?? randomUUID();
     const nowMs = now();
     const nowIso = new Date(nowMs).toISOString();
-    const expirationMs = resolvePageExpirationMs(
-      safeNamespace,
+    // Precedence: explicit per-publish `expires` → document `<meta>` → the
+    // publisher's config default. Most specific wins.
+    const expirationMs = resolveExpirationMs(
       coalesceExpiration(
         input.expires,
         meta.expires === null ? undefined : meta.expires,
+        input.defaultExpires,
       ),
     );
     const sourceBlobKey = `${pageId}.html.src`;