@commonpub/layer 0.60.0 → 0.61.0

package/composables/useFeatures.ts

@@ -44,6 +44,8 @@ export interface FeatureFlags {
   actAsRegistry: boolean;
   /** Announce this instance to a registry (Phase 4). Default ON (discoverable). */
   announceToRegistry: boolean;
+  /** Expose federation reach metrics on the public API. Default OFF (server-gated). */
+  publicApiMetricsFederation: boolean;
   /**
    * Cross-instance delegated authorization. All sub-flags default false.
    * Mirrors `@commonpub/config`'s `IdentityFeatures`. Phase 1b+ — see
@@ -68,6 +70,7 @@ export const DEFAULT_FLAGS: FeatureFlags = {
   rbac: false,
   actAsRegistry: false,
   announceToRegistry: true,
+  publicApiMetricsFederation: false,
   identity: {
     linkRemoteAccounts: false,
     signInWithRemote: false,

package/nuxt.config.ts

@@ -112,6 +112,7 @@ export default defineNuxtConfig({
         rbac: false,
         actAsRegistry: false,
         announceToRegistry: true,
+        publicApiMetricsFederation: false,
       },
       contentTypes: 'project,blog,explainer',
       contestCreation: 'admin',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@commonpub/layer",
-  "version": "0.60.0",
+  "version": "0.61.0",
   "type": "module",
   "main": "./nuxt.config.ts",
   "files": [
@@ -54,15 +54,15 @@
     "vue-router": "^4.3.0",
     "zod": "^4.3.6",
     "@commonpub/auth": "0.8.0",
-    "@commonpub/config": "0.18.0",
     "@commonpub/editor": "0.7.11",
-    "@commonpub/docs": "0.6.3",
+    "@commonpub/config": "0.19.0",
     "@commonpub/protocol": "0.13.0",
-    "@commonpub/server": "2.80.0",
+    "@commonpub/learning": "0.5.2",
+    "@commonpub/server": "2.81.0",
     "@commonpub/ui": "0.9.2",
     "@commonpub/explainer": "0.7.15",
-    "@commonpub/schema": "0.33.0",
-    "@commonpub/learning": "0.5.2"
+    "@commonpub/schema": "0.34.0",
+    "@commonpub/docs": "0.6.3"
   },
   "devDependencies": {
     "@testing-library/jest-dom": "^6.9.1",

package/pages/admin/api-keys.vue

@@ -1,6 +1,6 @@
 <script setup lang="ts">
 import type { AdminApiKeyView, ApiKeyUsageStats } from '@commonpub/server';
-import { PUBLIC_API_SCOPES } from '@commonpub/schema';
+import { PUBLIC_API_SCOPES, originPatternSchema } from '@commonpub/schema';
 
 definePageMeta({ layout: 'admin', middleware: 'auth' });
 
@@ -30,6 +30,12 @@ const form = reactive({
   rateLimitPerMinute: 60,
   allowedOrigins: '',
 });
+// CORS preset: 'none' (server-to-server, default), 'any' (*), 'localhost', or
+// 'custom' (free-text origin patterns). Keeps the common cases one click away
+// while still allowing wildcard/subdomain/port patterns via Custom.
+type CorsPreset = 'none' | 'any' | 'localhost' | 'custom';
+const corsPreset = ref<CorsPreset>('none');
+
 const creating = ref(false);
 const createError = ref('');
 const createdKey = ref<CreateResponse | null>(null);
@@ -50,9 +56,31 @@ function resetForm(): void {
   form.expiresAt = '';
   form.rateLimitPerMinute = 60;
   form.allowedOrigins = '';
+  corsPreset.value = 'none';
   createError.value = '';
 }
 
+/**
+ * Resolve the CORS preset into the origin list the API expects. Returns null
+ * (and sets createError) when a custom pattern is invalid, so the caller can
+ * abort before submitting. Mirrors the server-side `originPatternSchema`.
+ */
+function resolveOrigins(): string[] | null {
+  if (corsPreset.value === 'none') return [];
+  if (corsPreset.value === 'any') return ['*'];
+  if (corsPreset.value === 'localhost') return ['localhost'];
+  const list = form.allowedOrigins
+    .split(/[\s,]+/)
+    .map((o) => o.trim())
+    .filter(Boolean);
+  const bad = list.find((o) => !originPatternSchema.safeParse(o).success);
+  if (bad) {
+    createError.value = `Invalid CORS origin: ${bad}`;
+    return null;
+  }
+  return list;
+}
+
 async function submitCreate(): Promise<void> {
   createError.value = '';
   if (!form.name.trim()) {
@@ -63,12 +91,11 @@ async function submitCreate(): Promise<void> {
     createError.value = 'Select at least one scope';
     return;
   }
+  const origins = resolveOrigins();
+  if (origins === null) return; // invalid custom pattern; error already set
+
   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,
@@ -227,9 +254,38 @@ function fmtErrorRate(rate: number): string {
         </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>
+        <label id="key-cors-label">CORS access</label>
+        <div class="cpub-scope-grid" role="radiogroup" aria-labelledby="key-cors-label">
+          <label class="cpub-scope-chip">
+            <input type="radio" name="cors-preset" value="none" v-model="corsPreset" />
+            <span>Server-to-server only</span>
+          </label>
+          <label class="cpub-scope-chip">
+            <input type="radio" name="cors-preset" value="any" v-model="corsPreset" />
+            <span>Allow any origin (*)</span>
+          </label>
+          <label class="cpub-scope-chip">
+            <input type="radio" name="cors-preset" value="localhost" v-model="corsPreset" />
+            <span>Localhost (dev)</span>
+          </label>
+          <label class="cpub-scope-chip">
+            <input type="radio" name="cors-preset" value="custom" v-model="corsPreset" />
+            <span>Custom origins</span>
+          </label>
+        </div>
+        <div v-if="corsPreset === 'custom'" class="cpub-cors-custom">
+          <label for="key-origins">Allowed origins (comma or whitespace separated)</label>
+          <input
+            id="key-origins"
+            v-model="form.allowedOrigins"
+            class="cpub-input"
+            placeholder="https://app.example.com, https://*.example.com, http://localhost:*"
+          />
+        </div>
+        <small v-if="corsPreset === 'none'">Default. Browser cross-origin calls are blocked. Use this key from a server.</small>
+        <small v-else-if="corsPreset === 'any'">Any website can call this key from a browser. The Bearer token still controls access.</small>
+        <small v-else-if="corsPreset === 'localhost'">Allows http and https on localhost at any port, for local development.</small>
+        <small v-else>Patterns: *, localhost, https://app.example.com, https://*.example.com, http://localhost:*</small>
       </div>
       <p v-if="createError" class="cpub-form-error" role="alert">{{ createError }}</p>
       <div class="cpub-form-actions">
@@ -393,6 +449,8 @@ function fmtErrorRate(rate: number): string {
   font-size: 12px; cursor: pointer;
 }
 .cpub-scope-chip code { font-family: var(--font-mono); font-size: 11px; color: var(--text); }
+.cpub-scope-chip span { font-size: 12px; color: var(--text); }
+.cpub-cors-custom { margin-top: 8px; }
 
 .cpub-btn {
   padding: 6px 14px; font-size: 12px; font-weight: 500;

package/server/api/public/v1/metrics/content/top.get.ts

@@ -0,0 +1,30 @@
+import { getTopContent } from '@commonpub/server';
+import { z } from 'zod';
+
+const querySchema = z.object({
+  metric: z.enum(['views', 'likes', 'comments']).default('views'),
+  type: z.enum(['project', 'blog', 'explainer']).optional(),
+  limit: z.coerce.number().int().min(1).max(100).default(20),
+});
+
+/**
+ * GET /api/public/v1/metrics/content/top
+ *
+ * Scope: read:analytics. Leaderboard of published, public content by the chosen
+ * engagement metric. Author attribution is intentional (the content is public).
+ */
+export default defineEventHandler(async (event) => {
+  requireApiScope(event, 'read:analytics');
+  const parsed = querySchema.safeParse(getQuery(event));
+  if (!parsed.success) {
+    throw createError({ statusCode: 400, statusMessage: 'Invalid query parameters', data: parsed.error.flatten() });
+  }
+  const db = useDB();
+  const config = useConfig();
+  const items = await getTopContent(db, config.instance.domain, {
+    metric: parsed.data.metric,
+    type: parsed.data.type,
+    limit: parsed.data.limit,
+  });
+  return { items, metric: parsed.data.metric, limit: parsed.data.limit };
+});

package/server/api/public/v1/metrics/contributors/top.get.ts

@@ -0,0 +1,25 @@
+import { getTopContributors } from '@commonpub/server';
+import { z } from 'zod';
+
+const querySchema = z.object({
+  limit: z.coerce.number().int().min(1).max(100).default(20),
+});
+
+/**
+ * GET /api/public/v1/metrics/contributors/top
+ *
+ * Scope: read:analytics. Ranks public-profile, active users by their published,
+ * public content (with engagement received). Private/suspended/deleted profiles
+ * are excluded; this aggregates already-public attribution.
+ */
+export default defineEventHandler(async (event) => {
+  requireApiScope(event, 'read:analytics');
+  const parsed = querySchema.safeParse(getQuery(event));
+  if (!parsed.success) {
+    throw createError({ statusCode: 400, statusMessage: 'Invalid query parameters', data: parsed.error.flatten() });
+  }
+  const db = useDB();
+  const config = useConfig();
+  const items = await getTopContributors(db, config.instance.domain, parsed.data.limit);
+  return { items, limit: parsed.data.limit };
+});

package/server/api/public/v1/metrics/engagement.get.ts

@@ -0,0 +1,19 @@
+import { getEngagementMetrics } from '@commonpub/server';
+
+/**
+ * GET /api/public/v1/metrics/engagement
+ *
+ * Scope: read:analytics. Aggregate engagement ratios and funnels: content
+ * likes/comments-per-view, learning enroll->complete, event capacity->attendance,
+ * contest entries. Feature-gated sections are omitted when the feature is off.
+ */
+export default defineEventHandler(async (event) => {
+  requireApiScope(event, 'read:analytics');
+  const db = useDB();
+  const config = useConfig();
+  return await getEngagementMetrics(db, {
+    learning: config.features.learning,
+    events: config.features.events,
+    contests: config.features.contests,
+  });
+});

package/server/api/public/v1/metrics/federation.get.ts

@@ -0,0 +1,30 @@
+import { getFederationReach } from '@commonpub/server';
+import { z } from 'zod';
+
+const querySchema = z.object({
+  limit: z.coerce.number().int().min(1).max(100).default(20),
+});
+
+/**
+ * GET /api/public/v1/metrics/federation
+ *
+ * Scope: read:federation. Federation reach: known instances, active mirrors,
+ * accepted followers, and inbound content by origin domain (domain-level only,
+ * never per-user).
+ *
+ * Double-gated: requires `features.federation` AND the opt-in
+ * `features.publicApiMetricsFederation` (default OFF), because this exposes
+ * network-topology data about third-party instances. 404 (not 403) when either
+ * is off, so the surface stays invisible.
+ */
+export default defineEventHandler(async (event) => {
+  requireFeature('federation');
+  requireFeature('publicApiMetricsFederation');
+  requireApiScope(event, 'read:federation');
+  const parsed = querySchema.safeParse(getQuery(event));
+  if (!parsed.success) {
+    throw createError({ statusCode: 400, statusMessage: 'Invalid query parameters', data: parsed.error.flatten() });
+  }
+  const db = useDB();
+  return await getFederationReach(db, parsed.data.limit);
+});

package/server/api/public/v1/metrics/overview.get.ts

@@ -0,0 +1,15 @@
+import { getMetricsOverview } from '@commonpub/server';
+
+/**
+ * GET /api/public/v1/metrics/overview
+ *
+ * Scope: read:analytics. Instance-wide DevRel scorecard: totals (users,
+ * contributors, content by type, hubs, tags, engagement) plus 7d/30d growth
+ * deltas derived from timestamps. Aggregates only — no per-user data.
+ */
+export default defineEventHandler(async (event) => {
+  requireApiScope(event, 'read:analytics');
+  const db = useDB();
+  const config = useConfig();
+  return await getMetricsOverview(db, config.instance.domain);
+});

package/server/api/public/v1/metrics/tags/trending.get.ts

@@ -0,0 +1,24 @@
+import { getTrendingTags } from '@commonpub/server';
+import { z } from 'zod';
+
+const querySchema = z.object({
+  limit: z.coerce.number().int().min(1).max(100).default(20),
+});
+
+/**
+ * GET /api/public/v1/metrics/tags/trending
+ *
+ * Scope: read:analytics. Tags ranked by lifetime usage count (unused tags
+ * excluded). Time-windowed trending arrives with Phase 3 rollups.
+ */
+export default defineEventHandler(async (event) => {
+  requireApiScope(event, 'read:analytics');
+  const parsed = querySchema.safeParse(getQuery(event));
+  if (!parsed.success) {
+    throw createError({ statusCode: 400, statusMessage: 'Invalid query parameters', data: parsed.error.flatten() });
+  }
+  const db = useDB();
+  const config = useConfig();
+  const items = await getTrendingTags(db, config.instance.domain, parsed.data.limit);
+  return { items, limit: parsed.data.limit };
+});

package/server/api/public/v1/openapi.json.get.ts

@@ -364,6 +364,24 @@ export default defineEventHandler((event) => {
       '/search': {
         get: { summary: 'Search content', security: [{ bearer: ['read:search'] }], parameters: [{ name: 'q', in: 'query', required: true, schema: { type: 'string' } }, { name: 'type', in: 'query', schema: { type: 'string' } }], responses: { '200': { description: 'OK', content: { 'application/json': { schema: paginated('#/components/schemas/PublicContentSummary') } } } } },
       },
+      '/metrics/overview': {
+        get: { summary: 'Instance analytics scorecard (totals + 7d/30d deltas)', security: [{ bearer: ['read:analytics'] }], responses: { '200': { description: 'OK', content: { 'application/json': { schema: { type: 'object' } } } }, '403': { description: 'Missing scope', content: { 'application/json': { schema: { $ref: '#/components/schemas/Error' } } } } } },
+      },
+      '/metrics/content/top': {
+        get: { summary: 'Top content by engagement metric', security: [{ bearer: ['read:analytics'] }], parameters: [{ name: 'metric', in: 'query', schema: { type: 'string', enum: ['views', 'likes', 'comments'] } }, { name: 'type', in: 'query', schema: { type: 'string', enum: ['project', 'blog', 'explainer'] } }, { name: 'limit', in: 'query', schema: { type: 'integer' } }], responses: { '200': { description: 'OK', content: { 'application/json': { schema: { type: 'object', properties: { items: { type: 'array', items: { $ref: '#/components/schemas/PublicContentSummary' } } } } } } } } },
+      },
+      '/metrics/tags/trending': {
+        get: { summary: 'Tags ranked by usage', security: [{ bearer: ['read:analytics'] }], parameters: [{ name: 'limit', in: 'query', schema: { type: 'integer' } }], responses: { '200': { description: 'OK', content: { 'application/json': { schema: { type: 'object', properties: { items: { type: 'array', items: { $ref: '#/components/schemas/PublicTag' } } } } } } } } },
+      },
+      '/metrics/contributors/top': {
+        get: { summary: 'Top public-profile contributors', security: [{ bearer: ['read:analytics'] }], parameters: [{ name: 'limit', in: 'query', schema: { type: 'integer' } }], responses: { '200': { description: 'OK', content: { 'application/json': { schema: { type: 'object' } } } } } },
+      },
+      '/metrics/engagement': {
+        get: { summary: 'Aggregate engagement ratios and funnels', security: [{ bearer: ['read:analytics'] }], responses: { '200': { description: 'OK', content: { 'application/json': { schema: { type: 'object' } } } } } },
+      },
+      '/metrics/federation': {
+        get: { summary: 'Federation reach (opt-in; read:federation)', security: [{ bearer: ['read:federation'] }], parameters: [{ name: 'limit', in: 'query', schema: { type: 'integer' } }], responses: { '200': { description: 'OK', content: { 'application/json': { schema: { type: 'object' } } } }, '404': { description: 'Federation reach metrics not enabled', content: { 'application/json': { schema: { $ref: '#/components/schemas/Error' } } } } } },
+      },
       '/openapi.json': {
         get: { summary: 'This OpenAPI spec', responses: { '200': { description: 'OK' } } },
       },

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

@@ -1,7 +1,9 @@
 import {
   apiKeyRateLimit,
   authenticateApiKey,
+  isWellFormedOrigin,
   logApiKeyUsage,
+  matchOrigin,
   touchLastUsed,
   type ApiKey,
 } from '@commonpub/server';
@@ -45,10 +47,12 @@ export default defineEventHandler(async (event) => {
     setResponseHeader(event, 'Access-Control-Allow-Headers', 'Authorization, Content-Type');
     setResponseHeader(event, 'Access-Control-Max-Age', 600);
     const origin = getRequestHeader(event, 'origin');
-    if (origin) {
-      // Echo origin only on preflight — real requests get the per-key
-      // allow-list check below. Browsers that don't trust this echo because
-      // credentials aren't involved will simply fall back to the no-CORS path.
+    // Echo origin only on preflight — real requests get the per-key allow-list
+    // check below. Preflight is UNAUTHENTICATED, so the raw header is only
+    // reflected after `isWellFormedOrigin` rejects CRLF / control characters
+    // (reflecting an unvalidated header is a response-splitting sink). Browsers
+    // that don't trust this echo (no credentials) fall back to the no-CORS path.
+    if (origin && isWellFormedOrigin(origin)) {
       setResponseHeader(event, 'Access-Control-Allow-Origin', origin);
       appendResponseHeader(event, 'Vary', 'Origin');
     }
@@ -85,16 +89,18 @@ export default defineEventHandler(async (event) => {
     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');
-    }
+  // Per-key CORS allow-list, wildcard-aware (see `matchOrigin`). An empty/null
+  // list means server-to-server only (no CORS headers, so the browser blocks
+  // cross-origin calls). Patterns support `*` (any origin), `localhost`, and
+  // scheme/subdomain/port wildcards. `*` is safe here because auth is a Bearer
+  // token, not a cookie, and we never send Access-Control-Allow-Credentials.
+  const cors = matchOrigin(key.allowedOrigins, getRequestHeader(event, 'origin'));
+  if (cors.allowed && cors.headerValue) {
+    setResponseHeader(event, 'Access-Control-Allow-Origin', cors.headerValue);
+    setResponseHeader(event, 'Access-Control-Allow-Methods', 'GET, OPTIONS');
+    setResponseHeader(event, 'Access-Control-Allow-Headers', 'Authorization, Content-Type');
+    // Reflected origins vary by request; the literal `*` does not.
+    if (!cors.wildcard) appendResponseHeader(event, 'Vary', 'Origin');
   }
 
   event.context.apiKey = key;