@commonpub/layer 0.15.8 → 0.16.1

package/composables/useFeatures.ts

@@ -16,6 +16,7 @@ export interface FeatureFlags {
   federation: boolean;
   admin: boolean;
   emailNotifications: boolean;
+  publicApi: boolean;
 }
 
 let hydrated = false;
@@ -29,6 +30,7 @@ export const DEFAULT_FLAGS: FeatureFlags = {
   content: true, social: true, hubs: true, docs: true, video: true,
   contests: false, events: false, learning: true, explainers: true,
   editorial: true, federation: false, admin: false, emailNotifications: false,
+  publicApi: false,
 };
 
 /** Build the initial flags by merging the layer's runtime config over defaults. */
@@ -77,5 +79,6 @@ export function useFeatures() {
     federation: computed(() => flags.value.federation),
     admin: computed(() => flags.value.admin),
     emailNotifications: computed(() => flags.value.emailNotifications),
+    publicApi: computed(() => flags.value.publicApi),
   };
 }

package/layouts/admin.vue

@@ -37,6 +37,7 @@ const sidebarOpen = ref(false);
           <NuxtLink to="/admin/navigation" class="admin-nav-link" @click="sidebarOpen = false"><i class="fa-solid fa-bars"></i> Navigation</NuxtLink>
           <NuxtLink to="/admin/features" class="admin-nav-link" @click="sidebarOpen = false"><i class="fa-solid fa-toggle-on"></i> Features</NuxtLink>
           <NuxtLink to="/admin/federation" class="admin-nav-link" @click="sidebarOpen = false"><i class="fa-solid fa-globe"></i> Federation</NuxtLink>
+          <NuxtLink to="/admin/api-keys" class="admin-nav-link" @click="sidebarOpen = false"><i class="fa-solid fa-key"></i> API Keys</NuxtLink>
           <NuxtLink to="/admin/settings" class="admin-nav-link" @click="sidebarOpen = false"><i class="fa-solid fa-gear"></i> Settings</NuxtLink>
         </nav>
       </aside>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@commonpub/layer",
-  "version": "0.15.8",
+  "version": "0.16.1",
   "type": "module",
   "main": "./nuxt.config.ts",
   "files": [
@@ -29,8 +29,8 @@
   "dependencies": {
     "@aws-sdk/client-s3": "^3.1010.0",
     "@commonpub/explainer": "^0.7.12",
-    "@commonpub/schema": "^0.13.0",
-    "@commonpub/server": "^2.43.0",
+    "@commonpub/schema": "^0.14.1",
+    "@commonpub/server": "^2.44.2",
     "@tiptap/core": "^2.11.0",
     "@tiptap/extension-bold": "^2.11.0",
     "@tiptap/extension-bullet-list": "^2.11.0",
@@ -53,12 +53,12 @@
     "vue": "^3.4.0",
     "vue-router": "^4.3.0",
     "zod": "^4.3.6",
-    "@commonpub/config": "0.10.0",
     "@commonpub/auth": "0.5.1",
+    "@commonpub/config": "0.11.0",
     "@commonpub/editor": "0.7.9",
     "@commonpub/learning": "0.5.0",
-    "@commonpub/protocol": "0.9.9",
     "@commonpub/docs": "0.6.2",
+    "@commonpub/protocol": "0.9.9",
     "@commonpub/ui": "0.8.5"
   },
   "devDependencies": {

package/pages/admin/api-keys.vue

@@ -0,0 +1,363 @@
+<script setup lang="ts">
+import type { AdminApiKeyView } from '@commonpub/server';
+import { PUBLIC_API_SCOPES } from '@commonpub/schema';
+
+definePageMeta({ layout: 'admin', middleware: 'auth' });
+
+useSeoMeta({ title: `API Keys — Admin — ${useSiteName()}` });
+
+interface KeyListResponse {
+  items: AdminApiKeyView[];
+  total: number;
+}
+
+interface CreateResponse {
+  key: AdminApiKeyView;
+  token: string;
+}
+
+const includeRevoked = ref(false);
+const listUrl = computed(() => `/api/admin/api-keys${includeRevoked.value ? '?includeRevoked=true' : ''}`);
+const { data, pending, refresh, error: listError } = await useFetch<KeyListResponse>(listUrl);
+
+// Create-form state
+const showCreate = ref(false);
+const form = reactive({
+  name: '',
+  description: '',
+  scopes: [] as string[],
+  expiresAt: '',
+  rateLimitPerMinute: 60,
+  allowedOrigins: '',
+});
+const creating = ref(false);
+const createError = ref('');
+const createdKey = ref<CreateResponse | null>(null);
+const copied = ref(false);
+
+const availableScopes = PUBLIC_API_SCOPES.filter((s) => s !== 'read:*');
+
+function toggleScope(scope: string): void {
+  const i = form.scopes.indexOf(scope);
+  if (i >= 0) form.scopes.splice(i, 1);
+  else form.scopes.push(scope);
+}
+
+function resetForm(): void {
+  form.name = '';
+  form.description = '';
+  form.scopes = [];
+  form.expiresAt = '';
+  form.rateLimitPerMinute = 60;
+  form.allowedOrigins = '';
+  createError.value = '';
+}
+
+async function submitCreate(): Promise<void> {
+  createError.value = '';
+  if (!form.name.trim()) {
+    createError.value = 'Name is required';
+    return;
+  }
+  if (form.scopes.length === 0) {
+    createError.value = 'Select at least one scope';
+    return;
+  }
+  creating.value = true;
+  try {
+    const origins = form.allowedOrigins
+      .split(/[\s,]+/)
+      .map((o) => o.trim())
+      .filter(Boolean);
+    const body = {
+      name: form.name.trim(),
+      description: form.description.trim() || null,
+      scopes: form.scopes,
+      expiresAt: form.expiresAt || null,
+      rateLimitPerMinute: form.rateLimitPerMinute,
+      allowedOrigins: origins.length ? origins : null,
+    };
+    const result = await $fetch<CreateResponse>('/api/admin/api-keys', { method: 'POST', body });
+    createdKey.value = result;
+    showCreate.value = false;
+    resetForm();
+    await refresh();
+  } catch (err) {
+    const e = err as { statusMessage?: string; data?: { message?: string } };
+    createError.value = e.data?.message || e.statusMessage || 'Failed to create key';
+  } finally {
+    creating.value = false;
+  }
+}
+
+async function revoke(id: string, name: string): Promise<void> {
+  if (!confirm(`Revoke API key "${name}"? This cannot be undone.`)) return;
+  try {
+    await $fetch(`/api/admin/api-keys/${id}`, { method: 'DELETE' });
+    await refresh();
+  } catch {
+    // toast would go here
+  }
+}
+
+async function copyToken(): Promise<void> {
+  if (!createdKey.value) return;
+  try {
+    await navigator.clipboard.writeText(createdKey.value.token);
+    copied.value = true;
+    setTimeout(() => { copied.value = false; }, 2000);
+  } catch {
+    // clipboard may be blocked; user can still select the text
+  }
+}
+
+function dismissCreated(): void {
+  createdKey.value = null;
+}
+
+function fmtDate(iso: string | null): string {
+  if (!iso) return '—';
+  return new Date(iso).toLocaleString();
+}
+</script>
+
+<template>
+  <div class="cpub-admin-keys">
+    <header class="cpub-admin-head">
+      <div>
+        <h1 class="cpub-admin-title">API Keys</h1>
+        <p class="cpub-admin-sub">
+          Bearer tokens for <code>/api/public/v1/*</code>. Each key is scoped and rate-limited;
+          the raw token is shown once at creation.
+        </p>
+      </div>
+      <div class="cpub-admin-actions">
+        <label class="cpub-checkbox-label">
+          <input type="checkbox" v-model="includeRevoked" @change="refresh()" />
+          Show revoked
+        </label>
+        <button class="cpub-btn cpub-btn-primary" @click="showCreate = true">
+          <i class="fa-solid fa-plus"></i> New key
+        </button>
+      </div>
+    </header>
+
+    <!-- One-time token reveal -->
+    <div v-if="createdKey" class="cpub-key-reveal" role="alert">
+      <div class="cpub-key-reveal-head">
+        <strong>Key created — copy it now.</strong>
+        <button class="cpub-btn-link" aria-label="Close" @click="dismissCreated">
+          <i class="fa-solid fa-xmark"></i>
+        </button>
+      </div>
+      <p class="cpub-key-reveal-warn">
+        This is the only time the full token will be displayed. Store it somewhere safe before
+        leaving this page — the server only keeps a hash.
+      </p>
+      <div class="cpub-key-reveal-value">
+        <code>{{ createdKey.token }}</code>
+        <button class="cpub-btn" @click="copyToken" :aria-label="copied ? 'Copied' : 'Copy to clipboard'">
+          <i :class="copied ? 'fa-solid fa-check' : 'fa-regular fa-copy'"></i>
+          {{ copied ? 'Copied' : 'Copy' }}
+        </button>
+      </div>
+      <div class="cpub-key-reveal-meta">
+        <span>Name: <strong>{{ createdKey.key.name }}</strong></span>
+        <span>Prefix: <code>{{ createdKey.key.prefix }}</code></span>
+        <span>Scopes: <code>{{ createdKey.key.scopes.join(', ') }}</code></span>
+      </div>
+    </div>
+
+    <!-- Create form -->
+    <div v-if="showCreate" class="cpub-key-form" role="dialog" aria-label="Create API key">
+      <div class="cpub-key-form-head">
+        <h2>New API Key</h2>
+        <button class="cpub-btn-link" aria-label="Cancel" @click="showCreate = false; resetForm()">
+          <i class="fa-solid fa-xmark"></i>
+        </button>
+      </div>
+      <div class="cpub-form-row">
+        <label for="key-name">Name</label>
+        <input id="key-name" v-model="form.name" class="cpub-input" placeholder="e.g. Analytics dashboard" required />
+      </div>
+      <div class="cpub-form-row">
+        <label for="key-desc">Description (optional)</label>
+        <textarea id="key-desc" v-model="form.description" class="cpub-input" rows="2"
+                  placeholder="What is this key used for?" />
+      </div>
+      <div class="cpub-form-row">
+        <label>Scopes</label>
+        <div class="cpub-scope-grid">
+          <label v-for="scope in availableScopes" :key="scope" class="cpub-scope-chip">
+            <input type="checkbox" :checked="form.scopes.includes(scope)" @change="toggleScope(scope)" />
+            <code>{{ scope }}</code>
+          </label>
+        </div>
+      </div>
+      <div class="cpub-form-row cpub-form-grid">
+        <div>
+          <label for="key-expires">Expires (optional)</label>
+          <input id="key-expires" v-model="form.expiresAt" type="datetime-local" class="cpub-input" />
+        </div>
+        <div>
+          <label for="key-rate">Rate limit (req/min)</label>
+          <input id="key-rate" v-model.number="form.rateLimitPerMinute" type="number" min="1" max="10000" class="cpub-input" />
+        </div>
+      </div>
+      <div class="cpub-form-row">
+        <label for="key-origins">Allowed CORS origins (comma or whitespace separated, optional)</label>
+        <input id="key-origins" v-model="form.allowedOrigins" class="cpub-input" placeholder="https://app.example.com" />
+        <small>Leave blank for server-to-server only (default, recommended).</small>
+      </div>
+      <p v-if="createError" class="cpub-form-error" role="alert">{{ createError }}</p>
+      <div class="cpub-form-actions">
+        <button class="cpub-btn" @click="showCreate = false; resetForm()" :disabled="creating">Cancel</button>
+        <button class="cpub-btn cpub-btn-primary" @click="submitCreate" :disabled="creating">
+          {{ creating ? 'Creating...' : 'Create key' }}
+        </button>
+      </div>
+    </div>
+
+    <!-- List -->
+    <div v-if="pending" class="cpub-loading">Loading keys...</div>
+    <p v-else-if="listError" class="cpub-form-error">Failed to load keys.</p>
+    <p v-else-if="!data?.items?.length" class="cpub-empty">
+      No API keys yet. Create one to start consuming <code>/api/public/v1/*</code>.
+    </p>
+    <table v-else class="cpub-key-table" aria-label="API keys">
+      <thead>
+        <tr>
+          <th scope="col">Name</th>
+          <th scope="col">Prefix</th>
+          <th scope="col">Scopes</th>
+          <th scope="col">Last used</th>
+          <th scope="col">Created</th>
+          <th scope="col">Status</th>
+          <th scope="col"><span class="cpub-sr-only">Actions</span></th>
+        </tr>
+      </thead>
+      <tbody>
+        <tr v-for="k in data.items" :key="k.id" :class="{ 'cpub-key-revoked': !!k.revokedAt }">
+          <td>
+            <strong>{{ k.name }}</strong>
+            <div v-if="k.description" class="cpub-key-desc">{{ k.description }}</div>
+          </td>
+          <td><code>{{ k.prefix }}...</code></td>
+          <td>
+            <span v-for="s in k.scopes" :key="s" class="cpub-scope-tag">{{ s }}</span>
+          </td>
+          <td>{{ fmtDate(k.lastUsedAt) }}</td>
+          <td>{{ fmtDate(k.createdAt) }}</td>
+          <td>
+            <span v-if="k.revokedAt" class="cpub-key-badge cpub-key-badge-red">Revoked</span>
+            <span v-else-if="k.expiresAt && new Date(k.expiresAt) < new Date()" class="cpub-key-badge cpub-key-badge-yellow">Expired</span>
+            <span v-else class="cpub-key-badge cpub-key-badge-green">Active</span>
+          </td>
+          <td>
+            <button
+              v-if="!k.revokedAt"
+              class="cpub-btn-link cpub-btn-danger"
+              @click="revoke(k.id, k.name)"
+              :aria-label="`Revoke ${k.name}`"
+            >
+              Revoke
+            </button>
+          </td>
+        </tr>
+      </tbody>
+    </table>
+  </div>
+</template>
+
+<style scoped>
+.cpub-admin-keys { padding: 24px; max-width: 1200px; margin: 0 auto; }
+
+.cpub-admin-head { display: flex; justify-content: space-between; align-items: flex-start; gap: 16px; margin-bottom: 24px; }
+.cpub-admin-title { font-size: 22px; font-weight: 700; color: var(--text); margin-bottom: 4px; }
+.cpub-admin-sub { font-size: 13px; color: var(--text-dim); max-width: 620px; }
+.cpub-admin-sub code { font-family: var(--font-mono); font-size: 12px; background: var(--surface2); padding: 1px 6px; }
+
+.cpub-admin-actions { display: flex; gap: 10px; align-items: center; }
+.cpub-checkbox-label { display: flex; gap: 6px; align-items: center; font-size: 12px; color: var(--text-dim); cursor: pointer; }
+
+.cpub-key-reveal {
+  background: var(--accent-bg); border: var(--border-width-default) solid var(--accent-border);
+  padding: 16px 18px; margin-bottom: 20px;
+}
+.cpub-key-reveal-head { display: flex; justify-content: space-between; align-items: center; margin-bottom: 6px; }
+.cpub-key-reveal-warn { font-size: 12px; color: var(--text-dim); margin-bottom: 10px; }
+.cpub-key-reveal-value {
+  display: flex; gap: 10px; align-items: center;
+  background: var(--surface); border: var(--border-width-default) solid var(--border);
+  padding: 10px; font-family: var(--font-mono); font-size: 13px;
+}
+.cpub-key-reveal-value code { flex: 1; overflow-wrap: break-word; word-break: break-all; }
+.cpub-key-reveal-meta { display: flex; gap: 18px; flex-wrap: wrap; margin-top: 12px; font-size: 12px; color: var(--text-dim); }
+.cpub-key-reveal-meta code { font-family: var(--font-mono); }
+
+.cpub-key-form {
+  background: var(--surface); border: var(--border-width-default) solid var(--border);
+  padding: 20px; margin-bottom: 24px; box-shadow: var(--shadow-md);
+}
+.cpub-key-form-head { display: flex; justify-content: space-between; align-items: center; margin-bottom: 16px; }
+.cpub-key-form-head h2 { font-size: 16px; font-weight: 600; color: var(--text); }
+.cpub-form-row { margin-bottom: 14px; }
+.cpub-form-row label { display: block; font-size: 12px; font-weight: 600; color: var(--text); margin-bottom: 4px; }
+.cpub-form-row small { font-size: 11px; color: var(--text-faint); display: block; margin-top: 2px; }
+.cpub-input {
+  width: 100%; padding: 8px 10px; font-size: 13px;
+  background: var(--surface); color: var(--text);
+  border: var(--border-width-default) solid var(--border); font-family: inherit;
+}
+.cpub-form-grid { display: grid; grid-template-columns: 1fr 1fr; gap: 12px; }
+.cpub-form-error { color: var(--red); font-size: 12px; margin: 8px 0; }
+.cpub-form-actions { display: flex; justify-content: flex-end; gap: 10px; }
+
+.cpub-scope-grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(180px, 1fr)); gap: 6px; }
+.cpub-scope-chip {
+  display: flex; align-items: center; gap: 6px; padding: 6px 10px;
+  background: var(--surface2); border: var(--border-width-default) solid var(--border);
+  font-size: 12px; cursor: pointer;
+}
+.cpub-scope-chip code { font-family: var(--font-mono); font-size: 11px; color: var(--text); }
+
+.cpub-btn {
+  padding: 6px 14px; font-size: 12px; font-weight: 500;
+  background: var(--surface); color: var(--text);
+  border: var(--border-width-default) solid var(--border);
+  cursor: pointer; font-family: inherit;
+}
+.cpub-btn:hover { box-shadow: var(--shadow-sm); }
+.cpub-btn-primary { background: var(--accent); color: var(--color-text-inverse); border-color: var(--accent); }
+.cpub-btn-link { background: none; border: none; color: var(--text-dim); cursor: pointer; padding: 4px 8px; font-size: 12px; }
+.cpub-btn-link:hover { color: var(--text); }
+.cpub-btn-danger { color: var(--red); }
+
+.cpub-key-table {
+  width: 100%; border-collapse: collapse;
+  background: var(--surface); border: var(--border-width-default) solid var(--border);
+}
+.cpub-key-table th, .cpub-key-table td {
+  padding: 10px 12px; text-align: left; font-size: 12px;
+  border-bottom: var(--border-width-default) solid var(--border2);
+}
+.cpub-key-table th { font-family: var(--font-mono); font-size: 10px; text-transform: uppercase; letter-spacing: 0.08em; color: var(--text-faint); background: var(--surface2); }
+.cpub-key-desc { font-size: 11px; color: var(--text-dim); margin-top: 2px; }
+.cpub-key-revoked { opacity: 0.5; }
+
+.cpub-scope-tag {
+  display: inline-block; padding: 2px 6px; margin: 1px;
+  background: var(--surface2); border: var(--border-width-default) solid var(--border);
+  font-family: var(--font-mono); font-size: 10px;
+}
+
+.cpub-key-badge { font-family: var(--font-mono); font-size: 10px; padding: 2px 8px; font-weight: 600; text-transform: uppercase; letter-spacing: 0.04em; }
+.cpub-key-badge-green { background: var(--green-bg); color: var(--green); border: var(--border-width-default) solid var(--green); }
+.cpub-key-badge-yellow { background: var(--yellow-bg); color: var(--yellow); border: var(--border-width-default) solid var(--yellow); }
+.cpub-key-badge-red { background: var(--red-bg); color: var(--red); border: var(--border-width-default) solid var(--red); }
+
+.cpub-loading { padding: 40px; text-align: center; color: var(--text-dim); }
+.cpub-empty { padding: 40px; text-align: center; color: var(--text-dim); background: var(--surface); border: var(--border-width-default) solid var(--border); }
+.cpub-empty code { font-family: var(--font-mono); background: var(--surface2); padding: 1px 6px; }
+.cpub-sr-only { position: absolute; width: 1px; height: 1px; padding: 0; margin: -1px; overflow: hidden; clip: rect(0,0,0,0); white-space: nowrap; border: 0; }
+</style>

package/server/api/admin/api-keys/[id].delete.ts

@@ -0,0 +1,11 @@
+import { revokeApiKey } from '@commonpub/server';
+
+export default defineEventHandler(async (event) => {
+  const user = requireAdmin(event);
+  const id = getRouterParam(event, 'id');
+  if (!id) throw createError({ statusCode: 400, statusMessage: 'Missing id' });
+  const db = useDB();
+  const result = await revokeApiKey(db, id, user.id);
+  if (!result) throw createError({ statusCode: 404, statusMessage: 'Key not found or already revoked' });
+  return result;
+});

package/server/api/admin/api-keys/index.get.ts

@@ -0,0 +1,10 @@
+import { listApiKeys } from '@commonpub/server';
+
+export default defineEventHandler(async (event) => {
+  requireAdmin(event);
+  const query = getQuery(event);
+  const includeRevoked = query.includeRevoked === 'true' || query.includeRevoked === '1';
+  const db = useDB();
+  const items = await listApiKeys(db, { includeRevoked });
+  return { items, total: items.length };
+});

package/server/api/admin/api-keys/index.post.ts

@@ -0,0 +1,22 @@
+import { createApiKey } from '@commonpub/server';
+import { createApiKeySchema } from '@commonpub/schema';
+
+/**
+ * POST /api/admin/api-keys
+ *
+ * Creates a new public API key. The full token is returned ONCE in the
+ * response body — the UI displays it with a "copy now, you won't see it
+ * again" warning. Server-side we only keep the SHA-256 hash.
+ */
+export default defineEventHandler(async (event) => {
+  const user = requireAdmin(event);
+  const body = await readBody(event);
+  const parsed = createApiKeySchema.safeParse(body);
+  if (!parsed.success) {
+    throw createError({ statusCode: 400, statusMessage: 'Invalid input', data: parsed.error.flatten() });
+  }
+
+  const db = useDB();
+  const result = await createApiKey(db, user.id, parsed.data);
+  return result;
+});

package/server/api/public/v1/content/[slug].get.ts

@@ -0,0 +1,35 @@
+import { getContentBySlug, toPublicContentDetail, type PublicContentRow } from '@commonpub/server';
+import { z } from 'zod';
+
+const querySchema = z.object({
+  author: z.string().max(128).optional(),
+});
+
+export default defineEventHandler(async (event) => {
+  requireApiScope(event, 'read:content');
+  const slug = getRouterParam(event, 'slug');
+  if (!slug) throw createError({ statusCode: 400, statusMessage: 'Missing slug' });
+
+  const parsed = querySchema.safeParse(getQuery(event));
+  if (!parsed.success) {
+    throw createError({ statusCode: 400, statusMessage: 'Invalid query parameters' });
+  }
+
+  const db = useDB();
+  const config = useConfig();
+
+  // Pass undefined requester — getContentBySlug returns null for any row where
+  // status !== 'published' and authorId !== requesterId, and it already
+  // excludes deleted rows via its own WHERE clause. So the only thing left
+  // to guard is visibility: public API only returns public-visibility content.
+  const content = await getContentBySlug(db, slug, undefined, parsed.data.author);
+  if (!content || content.status !== 'published') {
+    throw createError({ statusCode: 404, statusMessage: 'Content not found' });
+  }
+  const visibility = (content as { visibility?: string | null }).visibility;
+  if (visibility && visibility !== 'public') {
+    throw createError({ statusCode: 404, statusMessage: 'Content not found' });
+  }
+
+  return toPublicContentDetail(content as unknown as PublicContentRow, config.instance.domain);
+});

package/server/api/public/v1/content/index.get.ts

@@ -0,0 +1,58 @@
+import { listContent, toPublicContentSummary, type PublicContentRow } from '@commonpub/server';
+import { z } from 'zod';
+
+const querySchema = z.object({
+  type: z.enum(['project', 'blog', 'explainer']).optional(),
+  tag: z.string().max(80).optional(),
+  authorId: z.string().uuid().optional(),
+  categoryId: z.string().uuid().optional(),
+  difficulty: z.enum(['beginner', 'intermediate', 'advanced']).optional(),
+  limit: z.coerce.number().int().min(1).max(100).default(20),
+  offset: z.coerce.number().int().min(0).default(0),
+  sort: z.enum(['recent', 'popular', 'featured']).default('recent'),
+});
+
+export default defineEventHandler(async (event) => {
+  requireApiScope(event, 'read:content');
+  const db = useDB();
+  const config = useConfig();
+  const rawQuery = getQuery(event);
+  const parsed = querySchema.safeParse(rawQuery);
+  if (!parsed.success) {
+    throw createError({ statusCode: 400, statusMessage: 'Invalid query parameters', data: parsed.error.flatten() });
+  }
+  const filters = parsed.data;
+
+  // Hard-forced: only published + public + non-deleted content.
+  // These overrides mirror the internal /api/content hardening (session 127)
+  // but live here too so a future internal-API change can't accidentally
+  // relax the public-surface guarantees.
+  const result = await listContent(db, {
+    status: 'published',
+    visibility: 'public',
+    type: filters.type,
+    tag: filters.tag,
+    authorId: filters.authorId,
+    categoryId: filters.categoryId,
+    difficulty: filters.difficulty,
+    limit: filters.limit,
+    offset: filters.offset,
+    sort: filters.sort,
+  }, {
+    includeFederated: config.features.seamlessFederation,
+    allowedContentTypes: config.instance.contentTypes,
+  });
+
+  // listContent already filters out deletedAt / non-published; the forced
+  // status+visibility above belt-and-suspenders that. Serialize via
+  // allow-list so any new internal column stays internal.
+  const domain = config.instance.domain;
+  const items = result.items.map((row) => toPublicContentSummary(row as unknown as PublicContentRow, domain));
+
+  return {
+    items,
+    total: result.total,
+    limit: filters.limit,
+    offset: filters.offset,
+  };
+});

package/server/api/public/v1/hubs/[slug].get.ts

@@ -0,0 +1,16 @@
+import { getHubBySlug, toPublicHub, type PublicHubRow } from '@commonpub/server';
+
+export default defineEventHandler(async (event) => {
+  requireApiScope(event, 'read:hubs');
+  const slug = getRouterParam(event, 'slug');
+  if (!slug) throw createError({ statusCode: 400, statusMessage: 'Missing slug' });
+
+  const db = useDB();
+  const config = useConfig();
+  const hub = await getHubBySlug(db, slug);
+  if (!hub || (hub as { deletedAt?: Date | null }).deletedAt) {
+    throw createError({ statusCode: 404, statusMessage: 'Hub not found' });
+  }
+
+  return toPublicHub(hub as unknown as PublicHubRow, config.instance.domain);
+});

package/server/api/public/v1/hubs/index.get.ts

@@ -0,0 +1,45 @@
+import { listHubs, toPublicHub, type PublicHubRow } from '@commonpub/server';
+import { z } from 'zod';
+
+const querySchema = z.object({
+  type: z.enum(['community', 'product', 'company']).optional(),
+  search: z.string().max(80).optional(),
+  limit: z.coerce.number().int().min(1).max(100).default(20),
+  offset: z.coerce.number().int().min(0).default(0),
+});
+
+export default defineEventHandler(async (event) => {
+  requireApiScope(event, 'read:hubs');
+  const db = useDB();
+  const config = useConfig();
+
+  const parsed = querySchema.safeParse(getQuery(event));
+  if (!parsed.success) {
+    throw createError({ statusCode: 400, statusMessage: 'Invalid query parameters', data: parsed.error.flatten() });
+  }
+  const filters = parsed.data;
+
+  // listHubs doesn't accept hubType as a filter today, so we over-fetch and
+  // narrow here. At current hub volume this is fine; if it grows the
+  // internal filter signature should be widened.
+  const result = await listHubs(db, {
+    search: filters.search,
+    limit: filters.limit,
+    offset: filters.offset,
+  });
+
+  const domain = config.instance.domain;
+  let items = (result.items as unknown as PublicHubRow[])
+    .filter((row) => row.deletedAt === null)
+    .map((row) => toPublicHub(row, domain));
+  if (filters.type) {
+    items = items.filter((h) => h.hubType === filters.type);
+  }
+
+  return {
+    items,
+    total: result.total,
+    limit: filters.limit,
+    offset: filters.offset,
+  };
+});

package/server/api/public/v1/instance.get.ts

@@ -0,0 +1,62 @@
+import type { PublicInstance } from '@commonpub/server';
+import { contentItems, hubs, users } from '@commonpub/schema';
+import { and, eq, isNull, sql } from 'drizzle-orm';
+
+export default defineEventHandler(async (event) => {
+  requireApiScope(event, 'read:instance');
+  const db = useDB();
+  const config = useConfig();
+
+  // Cheap aggregate counts. If these become hot we can swap to a cached
+  // materialized view — but at commonpub/deveco volume a per-request count
+  // is fine.
+  const [[userStats], [contentStats], [hubStats]] = await Promise.all([
+    db.select({
+      total: sql<number>`count(*)::int`,
+      activeMonth: sql<number>`count(*) FILTER (WHERE ${users.createdAt} > NOW() - INTERVAL '30 days')::int`,
+    }).from(users).where(and(isNull(users.deletedAt), eq(users.status, 'active'))),
+    db.select({ total: sql<number>`count(*)::int` })
+      .from(contentItems)
+      .where(and(eq(contentItems.status, 'published'), isNull(contentItems.deletedAt))),
+    db.select({ total: sql<number>`count(*)::int` })
+      .from(hubs)
+      .where(isNull(hubs.deletedAt)),
+  ]);
+
+  const domain = config.instance.domain;
+  const features = config.features as unknown as Record<string, boolean>;
+
+  const response: PublicInstance = {
+    name: config.instance.name,
+    description: config.instance.description ?? null,
+    domain,
+    software: {
+      name: 'commonpub',
+      version: '1.0.0',
+    },
+    users: {
+      total: userStats?.total ?? 0,
+      activeMonth: userStats?.activeMonth ?? 0,
+    },
+    content: { total: contentStats?.total ?? 0 },
+    hubs: { total: hubStats?.total ?? 0 },
+    features: {
+      content: !!features.content,
+      hubs: !!features.hubs,
+      docs: !!features.docs,
+      video: !!features.video,
+      contests: !!features.contests,
+      events: !!features.events,
+      learning: !!features.learning,
+      explainers: !!features.explainers,
+      federation: !!features.federation,
+    },
+    openRegistrations: !!config.auth?.emailPassword,
+    links: {
+      nodeinfo: `https://${domain}/nodeinfo/2.1`,
+      webfinger: `https://${domain}/.well-known/webfinger`,
+      api: `https://${domain}/api/public/v1`,
+    },
+  };
+  return response;
+});

package/server/api/public/v1/users/[username].get.ts

@@ -0,0 +1,38 @@
+import { isPublicUser, toPublicUser, type PublicUserRow } from '@commonpub/server';
+import { users } from '@commonpub/schema';
+import { and, eq, isNull } from 'drizzle-orm';
+
+export default defineEventHandler(async (event) => {
+  requireApiScope(event, 'read:users');
+  const username = getRouterParam(event, 'username');
+  if (!username) throw createError({ statusCode: 400, statusMessage: 'Missing username' });
+
+  const db = useDB();
+  const [row] = await db
+    .select({
+      id: users.id,
+      username: users.username,
+      displayName: users.displayName,
+      headline: users.headline,
+      bio: users.bio,
+      avatarUrl: users.avatarUrl,
+      bannerUrl: users.bannerUrl,
+      pronouns: users.pronouns,
+      location: users.location,
+      website: users.website,
+      skills: users.skills,
+      socialLinks: users.socialLinks,
+      profileVisibility: users.profileVisibility,
+      createdAt: users.createdAt,
+      deletedAt: users.deletedAt,
+    })
+    .from(users)
+    .where(and(eq(users.username, username), isNull(users.deletedAt), eq(users.status, 'active')))
+    .limit(1);
+
+  if (!row || !isPublicUser(row as PublicUserRow)) {
+    throw createError({ statusCode: 404, statusMessage: 'User not found' });
+  }
+
+  return toPublicUser(row as PublicUserRow);
+});

package/server/api/public/v1/users/index.get.ts

@@ -0,0 +1,60 @@
+import { isPublicUser, toPublicUser, type PublicUserRow } from '@commonpub/server';
+import { users } from '@commonpub/schema';
+import { and, desc, eq, ilike, isNull, or, sql } from 'drizzle-orm';
+import { z } from 'zod';
+
+const querySchema = z.object({
+  q: z.string().max(80).optional(),
+  limit: z.coerce.number().int().min(1).max(100).default(20),
+  offset: z.coerce.number().int().min(0).default(0),
+});
+
+const PUBLIC_FIELDS = {
+  id: users.id,
+  username: users.username,
+  displayName: users.displayName,
+  headline: users.headline,
+  bio: users.bio,
+  avatarUrl: users.avatarUrl,
+  bannerUrl: users.bannerUrl,
+  pronouns: users.pronouns,
+  location: users.location,
+  website: users.website,
+  skills: users.skills,
+  socialLinks: users.socialLinks,
+  profileVisibility: users.profileVisibility,
+  createdAt: users.createdAt,
+  deletedAt: users.deletedAt,
+};
+
+export default defineEventHandler(async (event) => {
+  requireApiScope(event, 'read:users');
+  const parsed = querySchema.safeParse(getQuery(event));
+  if (!parsed.success) {
+    throw createError({ statusCode: 400, statusMessage: 'Invalid query parameters', data: parsed.error.flatten() });
+  }
+  const { q, limit, offset } = parsed.data;
+
+  const db = useDB();
+  const conds = [
+    isNull(users.deletedAt),
+    eq(users.profileVisibility, 'public'),
+    eq(users.status, 'active'),
+  ];
+  if (q) {
+    const pattern = `%${q.replace(/[%_]/g, (c) => `\\${c}`)}%`;
+    conds.push(or(ilike(users.username, pattern), ilike(users.displayName, pattern))!);
+  }
+
+  const [rows, totalRow] = await Promise.all([
+    db.select(PUBLIC_FIELDS).from(users).where(and(...conds)).orderBy(desc(users.createdAt)).limit(limit).offset(offset),
+    db.select({ count: sql<number>`count(*)::int` }).from(users).where(and(...conds)),
+  ]);
+
+  const items = rows
+    .filter((r) => isPublicUser(r as PublicUserRow))
+    .map((r) => toPublicUser(r as PublicUserRow));
+  const total = totalRow[0]?.count ?? 0;
+
+  return { items, total, limit, offset };
+});

package/server/middleware/public-api-auth.ts

@@ -0,0 +1,93 @@
+import {
+  apiKeyRateLimit,
+  authenticateApiKey,
+  logApiKeyUsage,
+  touchLastUsed,
+  type ApiKey,
+} from '@commonpub/server';
+
+declare module 'h3' {
+  interface H3EventContext {
+    apiKey?: ApiKey;
+    apiScopes?: string[];
+  }
+}
+
+/**
+ * Authenticate Bearer-token requests to `/api/public/v1/*`.
+ *
+ * Returns 404 (not 401) when the feature flag is off — we don't want to leak
+ * even the existence of the API surface on instances that haven't opted in.
+ *
+ * All lookup-failure reasons (missing, malformed, not_found) map to a single
+ * 401 response with a generic `Invalid API key` message. Expired keys get
+ * their own response so a legitimate consumer knows to rotate — that
+ * distinction is safe because the key clearly existed.
+ */
+export default defineEventHandler(async (event) => {
+  const path = getRequestURL(event).pathname;
+  if (!path.startsWith('/api/public/')) return;
+
+  const config = useConfig();
+  if (!config.features.publicApi) {
+    throw createError({ statusCode: 404, statusMessage: 'Not Found' });
+  }
+
+  const authHeader = getRequestHeader(event, 'authorization');
+  const token = authHeader?.startsWith('Bearer ')
+    ? authHeader.slice(7).trim()
+    : undefined;
+
+  const db = useDB();
+  const result = await authenticateApiKey(db, token);
+
+  if (!result.ok) {
+    if (result.reason === 'expired') {
+      throw createError({ statusCode: 401, statusMessage: 'API key expired' });
+    }
+    throw createError({
+      statusCode: 401,
+      statusMessage: 'Invalid API key. Use Authorization: Bearer <key>.',
+    });
+  }
+
+  const { key } = result;
+
+  // Per-key rate limit (separate store from IP-based rate limit so a noisy
+  // public-API consumer can't DoS the web UI for their own home IP).
+  const rl = apiKeyRateLimit.check(key.id, key.rateLimitPerMinute);
+  setResponseHeader(event, 'X-RateLimit-Limit', String(rl.limit));
+  setResponseHeader(event, 'X-RateLimit-Remaining', String(rl.remaining));
+  setResponseHeader(event, 'X-RateLimit-Reset', String(rl.resetAt));
+  if (!rl.allowed) {
+    throw createError({ statusCode: 429, statusMessage: 'Rate limit exceeded' });
+  }
+
+  // Per-key CORS allow-list. `null` means server-to-server only (no CORS
+  // headers, so browser cross-origin calls are blocked by the browser).
+  if (key.allowedOrigins && key.allowedOrigins.length > 0) {
+    const origin = getRequestHeader(event, 'origin');
+    if (origin && key.allowedOrigins.includes(origin)) {
+      setResponseHeader(event, 'Access-Control-Allow-Origin', origin);
+      setResponseHeader(event, 'Access-Control-Allow-Methods', 'GET, OPTIONS');
+      setResponseHeader(event, 'Access-Control-Allow-Headers', 'Authorization, Content-Type');
+      appendResponseHeader(event, 'Vary', 'Origin');
+    }
+  }
+
+  event.context.apiKey = key;
+  event.context.apiScopes = key.scopes;
+
+  // Fire-and-forget debounced touch. Any DB error is swallowed — logging is
+  // best-effort and must never fail a request.
+  touchLastUsed(db, key.id).catch(() => {});
+
+  // Log on response finish (statusCode + latency known only then).
+  const start = Date.now();
+  event.node.res.on('finish', () => {
+    const statusCode = event.node.res.statusCode;
+    const latencyMs = Date.now() - start;
+    logApiKeyUsage(db, { keyId: key.id, endpoint: path, method: event.method, statusCode, latencyMs })
+      .catch(() => {});
+  });
+});

package/server/utils/requireScope.ts

@@ -0,0 +1,19 @@
+import { hasScope } from '@commonpub/server';
+import type { PublicApiScope } from '@commonpub/schema';
+import type { H3Event } from 'h3';
+
+/**
+ * Enforce a single scope on a public-API endpoint. Throws 403 if the key
+ * doesn't hold it (or the wildcard). Throws 401 if the event isn't an
+ * API-key request at all — that shouldn't happen because the middleware
+ * runs first, but defending against misconfiguration is cheap.
+ */
+export function requireApiScope(event: H3Event, needed: PublicApiScope): void {
+  const scopes = event.context.apiScopes;
+  if (!scopes) {
+    throw createError({ statusCode: 401, statusMessage: 'Missing API key' });
+  }
+  if (!hasScope(scopes, needed)) {
+    throw createError({ statusCode: 403, statusMessage: `Missing scope: ${needed}` });
+  }
+}