@growth-labs/cms 0.1.0

package/src/engine/invites.ts

@@ -0,0 +1,271 @@
+// invites.ts — workspace_invites engine (P7 Task 5).
+//
+// Copies inbox-platform src/lib/invites/service.ts, re-keyed onto:
+//   workspace_invites / workspace_memberships / masthead_users
+// Differences from inbox:
+//   - Uses Web Crypto (crypto.subtle.digest) NOT node:crypto — workerd-pure.
+//   - Timestamps are INTEGER unixepoch() (CMS convention, not inbox's TEXT datetime('now')).
+//   - acceptInvite takes the full user object; the identity call (mintOrAttachAccount)
+//     is the route layer's responsibility (routes/rbac-invites.ts), NOT the engine.
+//
+// SCOPE GUARDS (from spec §12):
+//   - Email must match the invite on accept (else invite_email_mismatch).
+//   - Membership is keyed on the REAL OpenAuth subject ('user:<uuid>') — NEVER a placeholder.
+//   - Email send is a Fronts-cutover concern; the engine only writes the row + returns the token.
+
+import type { CmsRole } from '../schema/types.js'
+import type { D1Database } from './d1.js'
+import { upsertMastheadUser } from './members.js'
+
+// ---------------------------------------------------------------------------
+// hashInviteToken — Web Crypto SHA-256 hex (workerd-pure, no node:crypto)
+// ---------------------------------------------------------------------------
+
+export async function hashInviteToken(token: string): Promise<string> {
+	const enc = new TextEncoder()
+	const buf = await crypto.subtle.digest('SHA-256', enc.encode(token))
+	return Array.from(new Uint8Array(buf))
+		.map((b) => b.toString(16).padStart(2, '0'))
+		.join('')
+}
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface InviteRecord {
+	id: string
+	workspaceId: string
+	email: string
+	role: CmsRole
+	invitedBy: string
+	tokenHash: string
+	expiresAt: number
+	acceptedAt: number | null
+	createdAt: number
+}
+
+export interface CreateInviteInput {
+	workspaceId: string
+	email: string
+	role: CmsRole
+	invitedBy: string
+	/** Expiry in seconds from now. Defaults to 7 days. */
+	expiresInSeconds?: number
+}
+
+export interface CreateInviteResult {
+	inviteId: string
+	/** The raw token — show once to the inviter for the accept link. */
+	token: string
+}
+
+export interface AcceptInviteInput {
+	token: string
+	user: {
+		/** Real OpenAuth subject — MUST start with 'user:'. NEVER a placeholder. */
+		id: string
+		email: string
+		name: string | null
+		image: string | null
+	}
+}
+
+// ---------------------------------------------------------------------------
+// createInvite — write the invite row, return the raw token (not stored)
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a workspace invite. Generates a random token, stores only its
+ * SHA-256 hash in the DB (never the raw value), and returns the token + id.
+ *
+ * The invite-email send is a Fronts-cutover concern (injected hook in the route
+ * layer) — the engine only persists the row. Mirror inbox "failure-as-value".
+ */
+export async function createInvite(
+	db: D1Database,
+	input: CreateInviteInput,
+): Promise<CreateInviteResult> {
+	const id = crypto.randomUUID()
+	// Generate a raw token: 32 random bytes as hex
+	const raw = new Uint8Array(32)
+	crypto.getRandomValues(raw)
+	const token = Array.from(raw)
+		.map((b) => b.toString(16).padStart(2, '0'))
+		.join('')
+
+	const tokenHash = await hashInviteToken(token)
+	const expiresIn = input.expiresInSeconds ?? 7 * 24 * 60 * 60 // 7 days
+	const now = Math.floor(Date.now() / 1000)
+	const expiresAt = now + expiresIn
+
+	await db
+		.prepare(
+			`INSERT INTO workspace_invites (id, workspace_id, email, role, invited_by, token_hash, expires_at, accepted_at, created_at)
+			 VALUES (?, ?, ?, ?, ?, ?, ?, NULL, ?)`,
+		)
+		.bind(
+			id,
+			input.workspaceId,
+			input.email,
+			input.role,
+			input.invitedBy,
+			tokenHash,
+			expiresAt,
+			now,
+		)
+		.run()
+
+	return { inviteId: id, token }
+}
+
+// ---------------------------------------------------------------------------
+// loadInviteByToken — hash the token, look up, reject expired/accepted
+// ---------------------------------------------------------------------------
+
+/**
+ * Load a pending invite by its raw token. Returns null if:
+ *   - token hash does not match any row
+ *   - the invite is expired (expires_at <= now)
+ *   - the invite is already accepted (accepted_at IS NOT NULL)
+ *
+ * Mirrors inbox `loadTenantInviteByToken`.
+ */
+export async function loadInviteByToken(
+	db: D1Database,
+	token: string,
+): Promise<InviteRecord | null> {
+	const tokenHash = await hashInviteToken(token)
+	const now = Math.floor(Date.now() / 1000)
+
+	const row = await db
+		.prepare(
+			`SELECT id, workspace_id, email, role, invited_by, token_hash, expires_at, accepted_at, created_at
+			 FROM workspace_invites
+			 WHERE token_hash = ? AND expires_at > ? AND accepted_at IS NULL`,
+		)
+		.bind(tokenHash, now)
+		.first<{
+			id: string
+			workspace_id: string
+			email: string
+			role: CmsRole
+			invited_by: string
+			token_hash: string
+			expires_at: number
+			accepted_at: number | null
+			created_at: number
+		}>()
+
+	if (!row) return null
+	return {
+		id: row.id,
+		workspaceId: row.workspace_id,
+		email: row.email,
+		role: row.role,
+		invitedBy: row.invited_by,
+		tokenHash: row.token_hash,
+		expiresAt: row.expires_at,
+		acceptedAt: row.accepted_at,
+		createdAt: row.created_at,
+	}
+}
+
+// ---------------------------------------------------------------------------
+// upsertMembership — insert or update a workspace_memberships row
+// ---------------------------------------------------------------------------
+
+async function upsertMembership(
+	db: D1Database,
+	{
+		workspaceId,
+		userId,
+		role,
+		invitedBy,
+		acceptedAt,
+	}: {
+		workspaceId: string
+		userId: string
+		role: CmsRole
+		invitedBy: string | null
+		acceptedAt: number
+	},
+): Promise<void> {
+	const now = Math.floor(Date.now() / 1000)
+	await db
+		.prepare(
+			`INSERT INTO workspace_memberships (workspace_id, user_id, role, invited_by, accepted_at, created_at, updated_at)
+			 VALUES (?, ?, ?, ?, ?, ?, ?)
+			 ON CONFLICT(workspace_id, user_id) DO UPDATE SET
+			   role = excluded.role,
+			   accepted_at = excluded.accepted_at,
+			   updated_at = excluded.updated_at`,
+		)
+		.bind(workspaceId, userId, role, invitedBy ?? null, acceptedAt, now, now)
+		.run()
+}
+
+// ---------------------------------------------------------------------------
+// acceptInvite — validate email match, upsert user + membership, mark accepted
+// ---------------------------------------------------------------------------
+
+/**
+ * Accept a workspace invite.
+ *
+ * Validates:
+ *   1. The token resolves to a pending, non-expired invite.
+ *   2. The user's email matches the invite email (prevents invite-link hijacking).
+ *
+ * On success:
+ *   - Upserts masthead_users (with the REAL OpenAuth subject as id).
+ *   - Upserts workspace_memberships keyed on the real subject.
+ *   - Marks the invite accepted.
+ *
+ * Throws:
+ *   - 'invite_not_found' if the token is unknown/expired/accepted.
+ *   - 'invite_email_mismatch' if the user email does not match.
+ *
+ * NOTE: The IdentityProvider.mintOrAttachAccount call is the ROUTE layer's
+ * responsibility — the engine only persists the data.
+ */
+export async function acceptInvite(
+	db: D1Database,
+	input: AcceptInviteInput,
+): Promise<{ workspaceId: string; role: CmsRole }> {
+	const invite = await loadInviteByToken(db, input.token)
+	if (!invite) {
+		throw new Error('invite_not_found')
+	}
+
+	// Email must match (case-insensitive)
+	if (invite.email.toLowerCase() !== input.user.email.toLowerCase()) {
+		throw new Error('invite_email_mismatch')
+	}
+
+	const now = Math.floor(Date.now() / 1000)
+
+	// Upsert the user profile
+	await upsertMastheadUser(db, {
+		id: input.user.id,
+		email: input.user.email,
+		name: input.user.name,
+		image: input.user.image,
+	})
+
+	// Upsert the membership (accepted)
+	await upsertMembership(db, {
+		workspaceId: invite.workspaceId,
+		userId: input.user.id,
+		role: invite.role,
+		invitedBy: invite.invitedBy,
+		acceptedAt: now,
+	})
+
+	// Mark invite accepted
+	await db
+		.prepare(`UPDATE workspace_invites SET accepted_at = ? WHERE id = ?`)
+		.bind(now, invite.id)
+		.run()
+
+	return { workspaceId: invite.workspaceId, role: invite.role }
+}

package/src/engine/members.ts

@@ -0,0 +1,216 @@
+// members.ts — Membership engine over workspace_memberships + masthead_users (P7 Task 1).
+//
+// Mirrors inbox-platform src/lib/data/members.ts (loadMembershipForUser /
+// upsertInboxUser) re-keyed onto workspace_memberships / masthead_users.
+// Differences from inbox:
+//   - Timestamps are INTEGER unixepoch() per CMS convention (inbox uses TEXT datetime('now')).
+//   - Subject format is the real OpenAuth subject 'user:<uuid>' (NEVER a locally-minted id).
+//   - listMembers does a LEFT JOIN to masthead_users for the profile view.
+
+import type { CmsRole } from '../schema/types.js'
+import type { D1Database } from './d1.js'
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** A resolved membership record (workspace_memberships row, flat). */
+export interface MembershipRecord {
+	workspaceId: string
+	userId: string
+	role: CmsRole
+	invitedBy: string | null
+	invitedAt: number | null
+	acceptedAt: number | null
+	createdAt: number
+	updatedAt: number
+}
+
+/** A membership record joined to masthead_users for the member-list view. */
+export interface MemberListEntry extends MembershipRecord {
+	email: string
+	name: string | null
+	image: string | null
+}
+
+// ---------------------------------------------------------------------------
+// masthead_users upsert (mirror upsertInboxUser)
+// ---------------------------------------------------------------------------
+
+export interface UpsertMastheadUserInput {
+	/** Real OpenAuth subject — MUST start with 'user:'. */
+	id: string
+	email: string
+	name: string | null
+	image: string | null
+}
+
+/**
+ * Upsert a masthead_users row. On conflict(id), updates email/name/image and
+ * bumps last_login_at + updated_at. Uses INTEGER unixepoch() timestamps
+ * (diverges from inbox's TEXT datetime('now') — match CMS convention).
+ *
+ * NEVER call with a locally-minted or placeholder id — id must be the real
+ * OpenAuth subject ('user:<uuid>'). A placeholder email on the UNIQUE column
+ * causes a 500 on the real person's first login (inbox-platform §16 risk 10).
+ */
+export async function upsertMastheadUser(
+	db: D1Database,
+	input: UpsertMastheadUserInput,
+): Promise<void> {
+	const now = Math.floor(Date.now() / 1000)
+	await db
+		.prepare(
+			`INSERT INTO masthead_users (id, email, name, image, last_login_at, created_at, updated_at)
+			 VALUES (?, ?, ?, ?, ?, ?, ?)
+			 ON CONFLICT(id) DO UPDATE SET
+			   email = excluded.email,
+			   name = excluded.name,
+			   image = excluded.image,
+			   last_login_at = excluded.last_login_at,
+			   updated_at = excluded.updated_at`,
+		)
+		.bind(input.id, input.email, input.name ?? null, input.image ?? null, now, now, now)
+		.run()
+}
+
+// ---------------------------------------------------------------------------
+// loadMembership (mirror loadMembershipForUser)
+// ---------------------------------------------------------------------------
+
+/**
+ * Load a single workspace membership keyed on (workspaceId, userId).
+ * Returns null when absent — a caller receiving null must 403/401.
+ * The userId MUST be the real OpenAuth subject; a placeholder returns null.
+ */
+export async function loadMembership(
+	db: D1Database,
+	workspaceId: string,
+	userId: string,
+): Promise<MembershipRecord | null> {
+	const row = await db
+		.prepare(
+			`SELECT workspace_id, user_id, role, invited_by, invited_at, accepted_at, created_at, updated_at
+			 FROM workspace_memberships
+			 WHERE workspace_id = ? AND user_id = ?`,
+		)
+		.bind(workspaceId, userId)
+		.first<{
+			workspace_id: string
+			user_id: string
+			role: CmsRole
+			invited_by: string | null
+			invited_at: number | null
+			accepted_at: number | null
+			created_at: number
+			updated_at: number
+		}>()
+
+	if (!row) return null
+	return {
+		workspaceId: row.workspace_id,
+		userId: row.user_id,
+		role: row.role,
+		invitedBy: row.invited_by,
+		invitedAt: row.invited_at,
+		acceptedAt: row.accepted_at,
+		createdAt: row.created_at,
+		updatedAt: row.updated_at,
+	}
+}
+
+// ---------------------------------------------------------------------------
+// listMembers — LEFT JOIN masthead_users for the member list view
+// ---------------------------------------------------------------------------
+
+/**
+ * List all accepted members for a workspace, joined to masthead_users for
+ * profile data. Ordered by membership created_at ASC (deterministic).
+ */
+export async function listMembers(db: D1Database, workspaceId: string): Promise<MemberListEntry[]> {
+	const result = await db
+		.prepare(
+			`SELECT
+			   wm.workspace_id, wm.user_id, wm.role,
+			   wm.invited_by, wm.invited_at, wm.accepted_at,
+			   wm.created_at, wm.updated_at,
+			   mu.email, mu.name, mu.image
+			 FROM workspace_memberships wm
+			 LEFT JOIN masthead_users mu ON mu.id = wm.user_id
+			 WHERE wm.workspace_id = ?
+			 ORDER BY wm.created_at ASC`,
+		)
+		.bind(workspaceId)
+		.all<{
+			workspace_id: string
+			user_id: string
+			role: CmsRole
+			invited_by: string | null
+			invited_at: number | null
+			accepted_at: number | null
+			created_at: number
+			updated_at: number
+			email: string
+			name: string | null
+			image: string | null
+		}>()
+
+	return (result.results ?? []).map((row) => ({
+		workspaceId: row.workspace_id,
+		userId: row.user_id,
+		role: row.role,
+		invitedBy: row.invited_by,
+		invitedAt: row.invited_at,
+		acceptedAt: row.accepted_at,
+		createdAt: row.created_at,
+		updatedAt: row.updated_at,
+		email: row.email,
+		name: row.name,
+		image: row.image,
+	}))
+}
+
+// ---------------------------------------------------------------------------
+// setRole — update a member's role
+// ---------------------------------------------------------------------------
+
+/**
+ * Update the role of an existing workspace member. Does not enforce the
+ * owner-invariant here — callers (route layer) must apply canChangeMemberRole
+ * from membership-rules.ts before calling this.
+ */
+export async function setRole(
+	db: D1Database,
+	workspaceId: string,
+	userId: string,
+	role: CmsRole,
+): Promise<void> {
+	const now = Math.floor(Date.now() / 1000)
+	await db
+		.prepare(
+			`UPDATE workspace_memberships
+			 SET role = ?, updated_at = ?
+			 WHERE workspace_id = ? AND user_id = ?`,
+		)
+		.bind(role, now, workspaceId, userId)
+		.run()
+}
+
+// ---------------------------------------------------------------------------
+// removeMember — delete a membership row
+// ---------------------------------------------------------------------------
+
+/**
+ * Remove a member from a workspace. Does not enforce the owner-invariant
+ * here — callers must apply canRemoveMember from membership-rules.ts first.
+ */
+export async function removeMember(
+	db: D1Database,
+	workspaceId: string,
+	userId: string,
+): Promise<void> {
+	await db
+		.prepare(`DELETE FROM workspace_memberships WHERE workspace_id = ? AND user_id = ?`)
+		.bind(workspaceId, userId)
+		.run()
+}

package/src/engine/membership-rules.ts

@@ -0,0 +1,63 @@
+// membership-rules.ts — Pure membership invariant guards (P7 Task 3).
+//
+// Copied from inbox-platform src/lib/permissions.ts — re-keyed onto the
+// workspace_memberships model. The mailboxScope helpers are stripped; the
+// owner-invariant logic (ownerCount / canRemoveMember / canChangeMemberRole)
+// is preserved verbatim.
+//
+// These are PURE functions — no D1, no crypto, no async.
+//
+// The "always keep ≥1 owner" invariant is non-negotiable:
+//   - canRemoveMember: cannot remove self; cannot remove the sole owner.
+//   - canChangeMemberRole: cannot demote the sole owner to a non-owner role.
+
+export type MembershipSummary = {
+	userId: string
+	role: string
+}
+
+export type MemberActionDecision =
+	| { allowed: true }
+	| { allowed: false; reason: 'cannot-remove-self' | 'last-owner' }
+
+/**
+ * Count the number of members with the 'owner' role.
+ */
+export function ownerCount(members: MembershipSummary[]): number {
+	return members.filter((member) => member.role === 'owner').length
+}
+
+/**
+ * A member cannot remove themselves (avoids accidental lockout) and the sole
+ * owner cannot be removed (the workspace must always keep at least one owner).
+ */
+export function canRemoveMember(
+	members: MembershipSummary[],
+	actorUserId: string,
+	targetUserId: string,
+): MemberActionDecision {
+	if (actorUserId === targetUserId) {
+		return { allowed: false, reason: 'cannot-remove-self' }
+	}
+	const target = members.find((member) => member.userId === targetUserId)
+	if (target?.role === 'owner' && ownerCount(members) <= 1) {
+		return { allowed: false, reason: 'last-owner' }
+	}
+	return { allowed: true }
+}
+
+/**
+ * The sole owner cannot be demoted to a non-owner role — that would leave the
+ * workspace with no owner. Any other role change is allowed.
+ */
+export function canChangeMemberRole(
+	members: MembershipSummary[],
+	targetUserId: string,
+	newRole: string,
+): MemberActionDecision {
+	const target = members.find((member) => member.userId === targetUserId)
+	if (target?.role === 'owner' && newRole !== 'owner' && ownerCount(members) <= 1) {
+		return { allowed: false, reason: 'last-owner' }
+	}
+	return { allowed: true }
+}

package/src/engine/og-render.ts

@@ -0,0 +1,59 @@
+// OG-image renderer interface + pure card-spec builder (P4 Task 5).
+//
+// The package owns the OgImageRenderer *interface* and the OgCardSpec type.
+// The mechanism that produces the PNG (Cloudflare Browser Rendering binding vs.
+// Resvg/satori WASM) is INJECTED by the site and is NOT imported here — it is
+// cutover glue (P8). Tests inject a stub renderer that returns fixed bytes.
+
+/** The deterministic spec the generateOgImage route hands to the renderer. */
+export interface OgCardSpec {
+	/** The article headline / title. */
+	title: string
+	/** Subtitle copy — typically the excerpt/dek. Empty string when absent. */
+	subtitle: string
+	/** Publication brand label (displayed on the card). */
+	brand: string
+	/** Optional hero-image URL to composite into the card background. */
+	heroUrl?: string
+}
+
+/**
+ * The renderer interface. The package defines the contract; the site (cutover
+ * P8) supplies a real implementation backed by a Browser Rendering binding or
+ * a Resvg/satori WASM path. Tests inject a stub that returns fixed bytes.
+ */
+export interface OgImageRenderer {
+	/** Render the card spec to PNG bytes. */
+	render(spec: OgCardSpec): Promise<Uint8Array>
+}
+
+/** Options for buildOgCardSpec. */
+export interface OgCardSpecOpts {
+	/** Override the publication brand label. Defaults to 'The Publication'. */
+	brand?: string
+	/** Pre-resolved hero image URL. If absent, heroUrl is omitted from the spec. */
+	heroUrl?: string
+}
+
+/**
+ * Build a deterministic OgCardSpec from a content row + options.
+ *
+ * - title: from the content item.
+ * - subtitle: from the item's excerpt; empty string when absent/null.
+ * - brand: from opts.brand or a sensible default label.
+ * - heroUrl: from opts.heroUrl when present; omitted otherwise.
+ */
+export function buildOgCardSpec(
+	item: { title: string; excerpt?: string | null },
+	opts: OgCardSpecOpts,
+): OgCardSpec {
+	const spec: OgCardSpec = {
+		title: item.title,
+		subtitle: item.excerpt ?? '',
+		brand: opts.brand ?? 'The Publication',
+	}
+	if (opts.heroUrl !== undefined) {
+		spec.heroUrl = opts.heroUrl
+	}
+	return spec
+}