@commonpub/layer 0.19.2 → 0.21.0

package/composables/useFeatures.ts

@@ -2,6 +2,14 @@
 // Initializes from build-time runtime config, then hydrates from /api/features
 // to pick up runtime DB overrides set via admin panel.
 
+export interface IdentityFeatures {
+  linkRemoteAccounts: boolean;
+  signInWithRemote: boolean;
+  actingAs: boolean;
+  remoteInteract: boolean;
+  remotePublish: boolean;
+}
+
 export interface FeatureFlags {
   content: boolean;
   social: boolean;
@@ -17,6 +25,12 @@ export interface FeatureFlags {
   admin: boolean;
   emailNotifications: boolean;
   publicApi: boolean;
+  /**
+   * Cross-instance delegated authorization. All sub-flags default false.
+   * Mirrors `@commonpub/config`'s `IdentityFeatures`. Phase 1b+ — see
+   * docs/sessions/136-cross-instance-identity-plan.md.
+   */
+  identity: IdentityFeatures;
 }
 
 let hydrated = false;
@@ -31,13 +45,28 @@ export const DEFAULT_FLAGS: FeatureFlags = {
   contests: false, events: false, learning: true, explainers: true,
   editorial: true, federation: false, admin: false, emailNotifications: false,
   publicApi: false,
+  identity: {
+    linkRemoteAccounts: false,
+    signInWithRemote: false,
+    actingAs: false,
+    remoteInteract: false,
+    remotePublish: false,
+  },
 };
 
 /** Build the initial flags by merging the layer's runtime config over defaults. */
 export function getInitialFlags(): FeatureFlags {
   const config = useRuntimeConfig();
   const buildFlags = (config.public.features as unknown as Partial<FeatureFlags> | undefined) ?? {};
-  return { ...DEFAULT_FLAGS, ...buildFlags };
+  // Merge top-level booleans, but deep-merge `identity` so a partial
+  // runtime override (e.g., `{ identity: { actingAs: true } }`) lands on
+  // top of the defaulted sub-flags rather than replacing the whole
+  // nested object.
+  return {
+    ...DEFAULT_FLAGS,
+    ...buildFlags,
+    identity: { ...DEFAULT_FLAGS.identity, ...(buildFlags.identity ?? {}) },
+  };
 }
 
 export function useFeatures() {
@@ -56,9 +85,18 @@ export function useFeatures() {
   if (import.meta.client && !hydrated) {
     hydrated = true;
     ($fetch as Function)('/api/features')
-      .then((dynamic: FeatureFlags) => {
+      .then((dynamic: Partial<FeatureFlags>) => {
         if (dynamic && typeof dynamic === 'object') {
-          flags.value = { ...flags.value, ...dynamic };
+          // Deep-merge `identity` so a server response that omits some
+          // sub-flag doesn't blank it out at the client.
+          flags.value = {
+            ...flags.value,
+            ...dynamic,
+            identity: {
+              ...flags.value.identity,
+              ...(dynamic.identity ?? {}),
+            },
+          };
         }
       })
       .catch(() => { /* use build-time defaults on failure */ });
@@ -80,5 +118,6 @@ export function useFeatures() {
     admin: computed(() => flags.value.admin),
     emailNotifications: computed(() => flags.value.emailNotifications),
     publicApi: computed(() => flags.value.publicApi),
+    identity: computed(() => flags.value.identity),
   };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@commonpub/layer",
-  "version": "0.19.2",
+  "version": "0.21.0",
   "type": "module",
   "main": "./nuxt.config.ts",
   "files": [
@@ -50,16 +50,16 @@
     "vue": "^3.4.0",
     "vue-router": "^4.3.0",
     "zod": "^4.3.6",
-    "@commonpub/editor": "0.7.9",
-    "@commonpub/config": "0.12.0",
-    "@commonpub/docs": "0.6.2",
     "@commonpub/auth": "0.6.0",
+    "@commonpub/docs": "0.6.2",
+    "@commonpub/editor": "0.7.9",
     "@commonpub/learning": "0.5.2",
-    "@commonpub/protocol": "0.9.9",
+    "@commonpub/explainer": "0.7.12",
     "@commonpub/schema": "0.16.0",
+    "@commonpub/config": "0.12.0",
+    "@commonpub/server": "2.51.0",
     "@commonpub/ui": "0.8.5",
-    "@commonpub/server": "2.49.0",
-    "@commonpub/explainer": "0.7.12"
+    "@commonpub/protocol": "0.9.9"
   },
   "devDependencies": {
     "@testing-library/jest-dom": "^6.9.1",

package/server/api/auth/federated/callback.get.ts

@@ -66,11 +66,30 @@ export default defineEventHandler(async (event) => {
   // Check if the current user is logged in — if so, link to their account
   const auth = event.context.auth;
   if (auth?.user) {
-    await linkFederatedAccount(db, auth.user.id, tokenResult.user.actorUri, oauthState.instanceDomain, {
-      preferredUsername: tokenResult.user.username,
-      displayName: tokenResult.user.displayName ?? undefined,
-      avatarUrl: tokenResult.user.avatarUrl ?? undefined,
-    });
+    await linkFederatedAccount(
+      db,
+      auth.user.id,
+      tokenResult.user.actorUri,
+      oauthState.instanceDomain,
+      {
+        preferredUsername: tokenResult.user.username,
+        displayName: tokenResult.user.displayName ?? undefined,
+        avatarUrl: tokenResult.user.avatarUrl ?? undefined,
+      },
+      // Phase 1b: persist the access token so future delegated actions
+      // (Phase 4) can call the remote on this user's behalf. Encrypted
+      // at rest via @commonpub/infra/tokenCrypto. Scopes default to
+      // 'read write follow' for CommonPub↔CommonPub trust (the existing
+      // SSO model assumes mutual trustedInstances). Software-kind is
+      // 'cpub' here because this callback handles CommonPub→CommonPub;
+      // a Mastodon-login flow (Phase 2) will use a separate callback
+      // that detects software via WebFinger / megalodon.
+      {
+        accessToken: tokenResult.accessToken,
+        scopes: ['read', 'write', 'follow'],
+        softwareKind: 'cpub',
+      },
+    );
 
     return sendRedirect(event, '/settings/account?federated=linked', 302);
   }

package/server/api/auth/mastodon/callback.get.ts

@@ -0,0 +1,144 @@
+/**
+ * GET /api/auth/mastodon/callback?code=<auth_code>&state=<state>
+ *
+ * Phase 2a — server side of the Mastodon-login flow. Exchanges the
+ * auth code for an access token, verifies the remote account, then
+ * routes to one of three outcomes:
+ *
+ *   1. **Already linked** — `findUserByFederatedAccount` finds a local
+ *      user. Mint a Better Auth session, redirect to dashboard. (Or
+ *      to `returnTo` if the start request specified it.)
+ *
+ *   2. **Currently logged-in user adding a link** — `event.context.auth`
+ *      has a user. Call `linkFederatedAccount` with the grant; redirect
+ *      to settings.
+ *
+ *   3. **Anonymous + first-time** — call `storePendingLink` (existing
+ *      v1 SSO machinery). Redirect to login form with the link token;
+ *      Phase 2b's UI will consume the token to auto-provision a fresh
+ *      local account or link to an existing user the visitor signs in
+ *      as.
+ *
+ * Gated by `features.identity.signInWithRemote`.
+ */
+import { z } from 'zod';
+import type { H3Event } from 'h3';
+import {
+  consumeMastodonLoginState,
+  createFederatedSession,
+  exchangeCodeAndVerify,
+  findUserByFederatedAccount,
+  getOrRegisterRemoteClient,
+  linkFederatedAccount,
+  storePendingLink,
+} from '@commonpub/server';
+
+const callbackSchema = z.object({
+  code: z.string().min(1),
+  state: z.string().min(1),
+  // OAuth error responses come back as ?error=...&error_description=...
+  // We surface a friendly message rather than crashing.
+  error: z.string().optional(),
+  error_description: z.string().optional(),
+});
+
+function setSessionCookie(event: H3Event, token: string, expiresAt: Date): void {
+  setCookie(event, 'better-auth.session_token', token, {
+    httpOnly: true,
+    secure: process.env.NODE_ENV === 'production',
+    sameSite: 'lax',
+    path: '/',
+    expires: expiresAt,
+  });
+}
+
+export default defineEventHandler(async (event) => {
+  const config = useConfig();
+  if (!config.features.identity.signInWithRemote) {
+    throw createError({ statusCode: 404, statusMessage: 'Not found' });
+  }
+
+  const db = useDB();
+  const params = parseQueryParams(event, callbackSchema);
+
+  if (params.error) {
+    // Remote denied / errored. Surface back to the login page with the
+    // OAuth error message so the UI can render it cleanly.
+    const msg = encodeURIComponent(params.error_description || params.error);
+    return sendRedirect(event, `/auth/login?mastodon_error=${msg}`, 302);
+  }
+
+  // Single-use, atomic. Returns null if expired / already consumed.
+  const loginState = await consumeMastodonLoginState(db, params.state);
+  if (!loginState) {
+    throw createError({
+      statusCode: 400,
+      statusMessage: 'Invalid or expired login state. Please try again.',
+    });
+  }
+
+  // Re-read the cached client credentials for this host; they were
+  // stored by the start route during `getOrRegisterRemoteClient`.
+  // Pass the same redirectUri so we don't mistakenly re-register.
+  const creds = await getOrRegisterRemoteClient(db, loginState.host, loginState.redirectUri);
+
+  // Exchange + verify in one atomic-ish step. Throws on token-exchange
+  // failure or 4xx on verifyCredentials.
+  let verified: Awaited<ReturnType<typeof exchangeCodeAndVerify>>;
+  try {
+    verified = await exchangeCodeAndVerify(loginState.host, creds, params.code);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : 'Unknown error';
+    throw createError({
+      statusCode: 502,
+      statusMessage: `Sign-in via ${loginState.host} failed: ${msg}`,
+    });
+  }
+
+  const ipAddress =
+    getRequestHeader(event, 'x-forwarded-for')?.split(',')[0]?.trim()
+    ?? getRequestHeader(event, 'x-real-ip')
+    ?? undefined;
+  const userAgent = getRequestHeader(event, 'user-agent') ?? undefined;
+
+  // Outcome 1: identity already linked → log them in, redirect.
+  const existingLink = await findUserByFederatedAccount(db, verified.profile.actorUri);
+  if (existingLink) {
+    const session = await createFederatedSession(db, existingLink.userId, ipAddress, userAgent);
+    setSessionCookie(event, session.sessionToken, session.expiresAt);
+    return sendRedirect(event, loginState.returnTo ?? '/dashboard', 302);
+  }
+
+  // Outcome 2: a user is signed in locally and wants to add this link.
+  const auth = event.context.auth;
+  if (auth?.user) {
+    await linkFederatedAccount(
+      db,
+      auth.user.id,
+      verified.profile.actorUri,
+      loginState.host,
+      {
+        preferredUsername: verified.profile.username,
+        displayName: verified.profile.displayName,
+        avatarUrl: verified.profile.avatarUrl,
+      },
+      {
+        accessToken: verified.accessToken,
+        scopes: verified.scopes,
+        softwareKind: verified.softwareKind,
+      },
+    );
+    return sendRedirect(event, '/settings/account?federated=linked', 302);
+  }
+
+  // Outcome 3: anonymous + first-time → store as pending link, hand
+  // the opaque token to the login UI. Phase 2b's UI consumes the token.
+  const linkToken = await storePendingLink(db, {
+    actorUri: verified.profile.actorUri,
+    username: verified.profile.username,
+    instanceDomain: loginState.host,
+    displayName: verified.profile.displayName,
+    avatarUrl: verified.profile.avatarUrl,
+  });
+  return sendRedirect(event, `/auth/login?federated=true&linkToken=${linkToken}`, 302);
+});

package/server/api/auth/mastodon/start.get.ts

@@ -0,0 +1,71 @@
+/**
+ * GET /api/auth/mastodon/start?host=<domain>[&returnTo=<path>]
+ *
+ * Phase 2a — server side of "Sign in via @user@host" / "Link a
+ * Mastodon-API account". CommonPub plays the OAuth client role here:
+ * registers itself with the remote, then redirects the user to the
+ * remote's `/oauth/authorize`.
+ *
+ * Gated by `features.identity.signInWithRemote`. When the flag is off,
+ * this route 404s — no leakage of new endpoints to scrapers.
+ *
+ * The companion `callback.get.ts` handles the auth code return.
+ */
+import { z } from 'zod';
+import {
+  buildAuthorizeUrl,
+  getOrRegisterRemoteClient,
+  isValidHost,
+  storeMastodonLoginState,
+} from '@commonpub/server';
+
+const startSchema = z.object({
+  host: z.string().min(3).max(253),
+  returnTo: z.string().optional(),
+});
+
+export default defineEventHandler(async (event) => {
+  const config = useConfig();
+  if (!config.features.identity.signInWithRemote) {
+    throw createError({ statusCode: 404, statusMessage: 'Not found' });
+  }
+
+  const db = useDB();
+  const { host: rawHost, returnTo } = parseQueryParams(event, startSchema);
+  const host = rawHost.trim().toLowerCase();
+
+  if (!isValidHost(host)) {
+    throw createError({
+      statusCode: 400,
+      statusMessage: `Invalid host: ${rawHost}`,
+    });
+  }
+
+  const redirectUri = `https://${config.instance.domain}/api/auth/mastodon/callback`;
+
+  // Get or register our OAuth client at the remote. First call to a
+  // given host hits the network (megalodon's `registerApp` →
+  // POST /api/v1/apps); subsequent calls read the cache.
+  let creds: Awaited<ReturnType<typeof getOrRegisterRemoteClient>>;
+  try {
+    creds = await getOrRegisterRemoteClient(db, host, redirectUri);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : 'Unknown registration error';
+    throw createError({
+      statusCode: 502,
+      statusMessage: `Could not register CommonPub at ${host}: ${msg}`,
+    });
+  }
+
+  // Mint a CSRF state token bound to this (host, redirectUri, returnTo)
+  // tuple. Single-use, 10-min TTL.
+  const state = await storeMastodonLoginState(db, {
+    host,
+    redirectUri,
+    returnTo,
+  });
+
+  // Redirect the user to the remote's authorize endpoint.
+  const authUrl = buildAuthorizeUrl(host, creds, state);
+  return sendRedirect(event, authUrl, 302);
+});

package/server/plugins/identity-startup.ts

@@ -0,0 +1,43 @@
+/**
+ * Cross-instance identity — Nitro startup wiring.
+ *
+ * Runs at app init to:
+ *
+ *   1. Validate that any token-using `features.identity.*` flag has
+ *      `CPUB_FED_TOKEN_KEY` set. Throws if misconfigured — the boot
+ *      fails loudly rather than 500-ing partway through a real user's
+ *      OAuth callback. Only `actingAs` is exempt (UI-only, no token I/O).
+ *
+ *   2. Register the Mastodon-API-backed FediClient factory so
+ *      `run(event, ctx.active, action, input)` can dispatch to remote
+ *      handlers when `ctx.active.kind === 'linked'`. Factory closes
+ *      over the request-scoped DB handle.
+ *
+ * Plugin order: this should run early, alongside other infrastructure
+ * plugins. Nitro picks up plugins in alphabetical order — file is
+ * named `identity-startup.ts` so it sorts before app-level plugins.
+ *
+ * Phase-skip ergonomics: if no identity flag is enabled, the factory
+ * is registered anyway (cheap; the factory is lazy and only executes
+ * when `getFediClient` is called). The startup invariant only fires
+ * for flags that need the key.
+ *
+ * See docs/sessions/136-cross-instance-identity-plan.md.
+ */
+import {
+  assertIdentityConfig,
+  createMastodonFediClientFactory,
+  setFediClientFactory,
+} from '@commonpub/server';
+
+export default defineNitroPlugin(() => {
+  const config = useConfig();
+
+  // Fails loudly + early if a token-using flag is on without the
+  // encryption key. Listed errors include the env var name to set.
+  assertIdentityConfig(config);
+
+  // Register the factory exactly once. Subsequent calls would replace
+  // (which is fine in tests; in prod this fires once per process).
+  setFediClientFactory(createMastodonFediClientFactory(useDB()));
+});