[pournasserian]

Closes #2572

What

The next F-API (#2425) slice, on the read endpoints of #2563 and the Markdown views of #2571: a preview token lets a frontend read a change set's content resolved as it would be published, before approval (API-04).

• Core (FluentCMS.Core.Delivery):
  • IPreviewTokens:
    • IssueAsync(changeSetId) returns the token once.
    • RevokeAsync(tokenId) revokes it.
    • ListAsync(changeSetId) lists the set's tokens, newest first, without secrets.
    • Only a UserInitiator may issue or revoke. Agents, the system and anonymous callers get preview_by_people_only.
    • A set that is published, rejected or reverted gets change_set_not_previewable.
  • IPreviewContent:
    • GetAsync(token, entryId) returns the version the set proposes. An entry the set unpublishes is not found, and an entry the set leaves alone reads at its published version.
    • ChangesAsync(token) returns the entries the set creates or updates, in operation order.
    • References to entity fields resolve to the versions the set proposes. An entity the set unpublishes resolves as NotPublished.
  • PreviewTokenKeys: 32 random bytes with an fcmsp_ prefix. Only the SHA-256 is stored, as for agent keys (SEC-01).
• A token stops working when it is revoked or expires, or when its set is published, rejected or reverted. Unknown and malformed tokens are refused the same way. All of these give one preview_token_invalid. Reads write nothing.
• Audit: preview_token.issued and preview_token.revoked, with the token as subject and the change set id, appended in the same unit of work as the write.
• Infrastructure:
  • PreviewTokens table with a unique token hash and foreign keys to the change set and the site, with migrations for SQLite and PostgreSQL.
  • EntryResolution takes the entity versions a set proposes.
  • PublishedContentReader serves both the published and the preview reads.
  • Delivery__PreviewTokenLifetime defaults to 7 days. A value outside zero to 365 days stops the host at startup. It is documented in CONTRIBUTING.
• Api: GET /api/v1/preview/entries/{id} and GET /api/v1/preview/changes.
  • The token goes in Authorization: Bearer, never in the URL.
  • Responses carry Cache-Control: no-store.
  • A missing or failing token gets a 401 problem.
• Docs: docs/api/delivery.md has a Preview section.

Why

API-04 and S1: a frontend shows reviewers the pages with the new prices before anyone approves the price change. One resolution code path serves both views, so a preview is what publishing would show.

Choices worth a look:

• People only. A token shows unapproved content to whoever holds it, so no agent can mint one. The desk lane can add the issue and revoke screen on these services.
• One error for every failing token, so a holder cannot probe which tokens exist or why one stopped working.
• Expiry is compared in memory after the hash lookup, because SQLite cannot compare stored offsets in a query.
• Entries the set does not touch read as published, so a preview of one page links to the rest of the site as it is live.

Tests

Integration, each on SQLite and PostgreSQL:

• S1: with the product at 24.99 and a new page title in an open set, the token reads the page at version 2 with the title and 24.99, while the published read still shows 19.99. ChangesAsync lists the product and the page in operation order. After the set publishes, the token is refused.

• The token stops working in each of these cases, with the same code:

  • after it is revoked;
  • after seven days;
  • when its set is rejected;
  • when it is well formed but unknown;
  • when it is malformed.

  ListAsync shows the set's three tokens newest first, the revoked one with its time. The audit has four preview_token.issued events and one preview_token.revoked, with the token and the set.

• Refused, each with its own code:

  • an agent issuing or revoking;
  • a published set;
  • an unknown set;
  • an unknown token to revoke.

  Only the hash is stored.

• A set that unpublishes the product shows the page with a NotPublished price and the product as not found. A draft outside the set stays hidden.

HTTP, with stubs:

• A preview with the bearer token returns the entry and the changes with Cache-Control: no-store.
• Without a token, or with a refused one, the response is a 401 problem.

The full suite ran locally against a postgres:17 container as well as SQLite. One known load-sensitive job queue test (#2536) failed once and passed on rerun. Both migrations apply, revert and apply again. markdownlint is clean, and no new package was added.

Review

An independent review blocked this PR on one Medium finding. Revoking a token that was already revoked was only refused inside the unit of work, which broke a caller's own unit of work. It is now refused before the unit of work with preview_token_already_revoked, and a test revokes twice inside a caller's unit of work that still commits.

Its Low findings are fixed too:

• a 401 now names the Bearer scheme in WWW-Authenticate;
• previews are tested against a soft-deleted and an archived page outside the set;
• a token lifetime that is not positive or exceeds a year is tested to stop the host.

Checklist

• Linked to an issue a maintainer has confirmed
• Targets v2
• Tests or docs updated where behaviour changed
• No tool-generated co-author trailers or footers