feat(settings): expose federatedRegistrationOpen in /settings/instance + /instance/info

Surfaces the federatedRegistrationOpen flag (Task 1 schema column) on the
admin settings GET/PATCH endpoints and the public /api/instance/info
endpoint. Closes the 3 deferred TypeScript errors from Task 2 by
populating the now-required InstanceAdminSettings/InstanceInfoResponse
field.

Adds smoke tests (routes/instance.test.ts, routes/settings.test.ts) that
lock in the JSON contract the Connections UI (Task 21) and admin
RegistrationPanel (Task 15) consume, plus boolean-validation coverage
for the PATCH path. Updates docs/systems/admin.md with the new field in
both InstanceAdminSettings and the public info response schema.

docs/systems/admin.md

@@ -53,7 +53,8 @@ Settings are split into two API surfaces:
 | Field | Type | DB Column | Validation | Notes |
 |-------|------|-----------|------------|-------|
 | instanceName | string | instanceName | 1-32 chars, trimmed | Default: `'Backspace'` |
-| registrationOpen | boolean | registrationOpen | boolean | DB null = use env `REGISTRATION_OPEN` (default true) |
+| registrationOpen | boolean | registrationOpen | boolean | Local-account registration. DB null = use env `REGISTRATION_OPEN` (default true) |
+| federatedRegistrationOpen | boolean | federatedRegistrationOpen | boolean | Federated-account creation against this instance. NOT NULL DEFAULT 1. Controls whether remote users can create `username@thisInstance` accounts via Connections (see auth.md + client-federation.md) |
 | discoveryEnabled | boolean | discoveryEnabled | boolean | Controls space Explore page |
 | gifApiKey | string? | gifApiKey | string or empty to clear | Returned masked as `****{last4}` for security |
 | gifEnabled | boolean? | (derived) | -- | Read-only; true when gifApiKey is non-null |
@@ -164,11 +165,14 @@ No authentication. Returns:
   name: string;        // instanceSettings.instanceName ?? 'Backspace'
   version: string;     // Hardcoded '1.0.0' in instance.ts
   registrationOpen: boolean;  // DB setting overrides env if non-null
+  federatedRegistrationOpen: boolean;  // NOT NULL DEFAULT 1; gates federated-account creation
 }
 ```
 
 Registration resolution order: `instance_settings.registrationOpen` (if not null) > `config.registrationOpen` (from `REGISTRATION_OPEN` env, default true).
 
+`federatedRegistrationOpen` is consumed by the Connections UI (client-federation.md) to decide whether to surface the "create federated account on this instance" affordance.
+
 ### General Instance Settings
 
 ```

packages/server/src/routes/instance.test.ts

@@ -0,0 +1,94 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import Fastify, { type FastifyInstance } from 'fastify';
+import Database from 'better-sqlite3';
+import { drizzle } from 'drizzle-orm/better-sqlite3';
+import { eq } from 'drizzle-orm';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import * as schema from '../db/schema.js';
+import { setWorkerId } from '../utils/snowflake.js';
+
+setWorkerId(3);
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+// Module-level mutable state — see invites.test.ts for the rationale on why
+// the `getDb` mock closes over a getter rather than the binding directly.
+type TestDb = ReturnType<typeof drizzle<typeof schema>>;
+let sqlite: Database.Database;
+let testDb: TestDb;
+let app: FastifyInstance;
+
+vi.mock('../db/index.js', () => ({
+  getDb: () => testDb,
+  getRawDb: () => sqlite,
+  schema,
+}));
+
+function applyMigrations(db: Database.Database): void {
+  const migrationsDir = path.resolve(__dirname, '../../drizzle');
+  const files = fs.readdirSync(migrationsDir).filter(f => f.endsWith('.sql')).sort();
+  for (const f of files) {
+    const sqlText = fs.readFileSync(path.join(migrationsDir, f), 'utf8');
+    const statements = sqlText.split(/-->\s*statement-breakpoint/);
+    for (const stmt of statements) {
+      const clean = stmt.trim();
+      if (clean) db.exec(clean);
+    }
+  }
+}
+
+async function buildApp(): Promise<FastifyInstance> {
+  const { instanceRoutes } = await import('./instance.js');
+  const f = Fastify();
+  await f.register(instanceRoutes);
+  return f;
+}
+
+beforeEach(async () => {
+  sqlite = new Database(':memory:');
+  sqlite.pragma('foreign_keys = ON');
+  applyMigrations(sqlite);
+  testDb = drizzle(sqlite, { schema });
+
+  // Seed the singleton instance_settings row mirroring ensureDefaults() —
+  // tests don't run the boot-time helper, so we insert manually with the
+  // schema-default values for the new federatedRegistrationOpen column.
+  testDb.insert(schema.instanceSettings).values({
+    id: 1,
+    updatedAt: Date.now(),
+  }).run();
+
+  app = await buildApp();
+});
+
+describe('GET /api/instance/info', () => {
+  it('includes federatedRegistrationOpen (default true)', async () => {
+    const res = await app.inject({ method: 'GET', url: '/api/instance/info' });
+    expect(res.statusCode).toBe(200);
+    const body = res.json();
+    expect(body.federatedRegistrationOpen).toBe(true);
+  });
+
+  it('reflects federatedRegistrationOpen=false when toggled off', async () => {
+    testDb.update(schema.instanceSettings)
+      .set({ federatedRegistrationOpen: 0 })
+      .where(eq(schema.instanceSettings.id, 1))
+      .run();
+
+    const res = await app.inject({ method: 'GET', url: '/api/instance/info' });
+    expect(res.statusCode).toBe(200);
+    const body = res.json();
+    expect(body.federatedRegistrationOpen).toBe(false);
+  });
+
+  it('returns the full contract: name, version, registrationOpen, federatedRegistrationOpen', async () => {
+    const res = await app.inject({ method: 'GET', url: '/api/instance/info' });
+    expect(res.statusCode).toBe(200);
+    const body = res.json();
+    expect(typeof body.name).toBe('string');
+    expect(typeof body.version).toBe('string');
+    expect(typeof body.registrationOpen).toBe('boolean');
+    expect(typeof body.federatedRegistrationOpen).toBe('boolean');
+  });
+});

packages/server/src/routes/instance.ts

@@ -22,6 +22,7 @@ export async function instanceRoutes(app: FastifyInstance): Promise<void> {
       name: instanceName,
       version: BACKSPACE_VERSION,
       registrationOpen,
+      federatedRegistrationOpen: settings?.federatedRegistrationOpen === 1,
     };
 
     return reply.code(200).send(response);

packages/server/src/routes/settings.test.ts

@@ -0,0 +1,158 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import Fastify, { type FastifyInstance } from 'fastify';
+import Database from 'better-sqlite3';
+import { drizzle } from 'drizzle-orm/better-sqlite3';
+import { eq } from 'drizzle-orm';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import * as schema from '../db/schema.js';
+import { setWorkerId } from '../utils/snowflake.js';
+
+setWorkerId(4);
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+// Module-level mutable state — see invites.test.ts for the rationale on why
+// the `getDb` mock closes over a getter rather than the binding directly.
+type TestDb = ReturnType<typeof drizzle<typeof schema>>;
+let sqlite: Database.Database;
+let testDb: TestDb;
+let app: FastifyInstance;
+const ADMIN_ID = 'admin-1';
+
+vi.mock('../db/index.js', () => ({
+  getDb: () => testDb,
+  getRawDb: () => sqlite,
+  schema,
+}));
+
+vi.mock('../utils/auth.js', () => ({
+  authenticate: async (req: { userId?: string }) => {
+    req.userId = ADMIN_ID;
+  },
+  requireAdmin: async () => {
+    // tests run as admin
+  },
+}));
+
+function applyMigrations(db: Database.Database): void {
+  const migrationsDir = path.resolve(__dirname, '../../drizzle');
+  const files = fs.readdirSync(migrationsDir).filter(f => f.endsWith('.sql')).sort();
+  for (const f of files) {
+    const sqlText = fs.readFileSync(path.join(migrationsDir, f), 'utf8');
+    const statements = sqlText.split(/-->\s*statement-breakpoint/);
+    for (const stmt of statements) {
+      const clean = stmt.trim();
+      if (clean) db.exec(clean);
+    }
+  }
+}
+
+async function buildApp(): Promise<FastifyInstance> {
+  const { settingsRoutes } = await import('./settings.js');
+  const f = Fastify();
+  await f.register(settingsRoutes);
+  return f;
+}
+
+beforeEach(async () => {
+  sqlite = new Database(':memory:');
+  sqlite.pragma('foreign_keys = ON');
+  applyMigrations(sqlite);
+  testDb = drizzle(sqlite, { schema });
+
+  // Seed the singleton instance_settings row (mirrors ensureDefaults at boot).
+  testDb.insert(schema.instanceSettings).values({
+    id: 1,
+    updatedAt: Date.now(),
+  }).run();
+
+  // Seed the admin user — settings routes require an authenticated admin.
+  testDb.insert(schema.users).values({
+    id: ADMIN_ID,
+    username: 'admin',
+    passwordHash: 'x',
+    isAdmin: 1,
+    createdAt: Date.now(),
+  }).run();
+
+  app = await buildApp();
+});
+
+describe('GET /api/settings/instance', () => {
+  it('surfaces federatedRegistrationOpen (default true)', async () => {
+    const res = await app.inject({ method: 'GET', url: '/api/settings/instance' });
+    expect(res.statusCode).toBe(200);
+    const body = res.json();
+    expect(body.federatedRegistrationOpen).toBe(true);
+  });
+
+  it('reflects federatedRegistrationOpen=false when toggled off in DB', async () => {
+    testDb.update(schema.instanceSettings)
+      .set({ federatedRegistrationOpen: 0 })
+      .where(eq(schema.instanceSettings.id, 1))
+      .run();
+
+    const res = await app.inject({ method: 'GET', url: '/api/settings/instance' });
+    expect(res.statusCode).toBe(200);
+    expect(res.json().federatedRegistrationOpen).toBe(false);
+  });
+});
+
+describe('PATCH /api/settings/instance — federatedRegistrationOpen', () => {
+  it('accepts federatedRegistrationOpen=false and persists it', async () => {
+    const res = await app.inject({
+      method: 'PATCH',
+      url: '/api/settings/instance',
+      payload: { federatedRegistrationOpen: false },
+    });
+    expect(res.statusCode).toBe(200);
+    expect(res.json().federatedRegistrationOpen).toBe(false);
+
+    // Verify persistence
+    const row = testDb.select().from(schema.instanceSettings)
+      .where(eq(schema.instanceSettings.id, 1)).get();
+    expect(row?.federatedRegistrationOpen).toBe(0);
+  });
+
+  it('accepts federatedRegistrationOpen=true (re-enable)', async () => {
+    testDb.update(schema.instanceSettings)
+      .set({ federatedRegistrationOpen: 0 })
+      .where(eq(schema.instanceSettings.id, 1))
+      .run();
+
+    const res = await app.inject({
+      method: 'PATCH',
+      url: '/api/settings/instance',
+      payload: { federatedRegistrationOpen: true },
+    });
+    expect(res.statusCode).toBe(200);
+    expect(res.json().federatedRegistrationOpen).toBe(true);
+
+    const row = testDb.select().from(schema.instanceSettings)
+      .where(eq(schema.instanceSettings.id, 1)).get();
+    expect(row?.federatedRegistrationOpen).toBe(1);
+  });
+
+  it('rejects non-boolean federatedRegistrationOpen with 400', async () => {
+    const res = await app.inject({
+      method: 'PATCH',
+      url: '/api/settings/instance',
+      payload: { federatedRegistrationOpen: 'yes' },
+    });
+    expect(res.statusCode).toBe(400);
+    expect(res.json().error).toMatch(/federatedRegistrationOpen/);
+  });
+
+  it('leaves federatedRegistrationOpen unchanged when omitted from payload', async () => {
+    const res = await app.inject({
+      method: 'PATCH',
+      url: '/api/settings/instance',
+      payload: { instanceName: 'NewName' },
+    });
+    expect(res.statusCode).toBe(200);
+    // Schema default is 1 → response should still report true
+    expect(res.json().federatedRegistrationOpen).toBe(true);
+    expect(res.json().instanceName).toBe('NewName');
+  });
+});

packages/server/src/routes/settings.ts

@@ -185,6 +185,7 @@ export async function settingsRoutes(app: FastifyInstance): Promise<void> {
     const response: InstanceAdminSettings = {
       instanceName: row.instanceName ?? 'Backspace',
       registrationOpen: row.registrationOpen !== null ? row.registrationOpen === 1 : config.registrationOpen,
+      federatedRegistrationOpen: row.federatedRegistrationOpen === 1,
       discoveryEnabled: row.discoveryEnabled === 1,
       gifApiKey: gifKey ? `****${gifKey.slice(-4)}` : undefined,
       gifEnabled: !!gifKey,
@@ -216,6 +217,13 @@ export async function settingsRoutes(app: FastifyInstance): Promise<void> {
       updateData.registrationOpen = body.registrationOpen ? 1 : 0;
     }
 
+    if (body.federatedRegistrationOpen !== undefined) {
+      if (typeof body.federatedRegistrationOpen !== 'boolean') {
+        return reply.code(400).send({ error: 'federatedRegistrationOpen must be boolean', statusCode: 400 });
+      }
+      updateData.federatedRegistrationOpen = body.federatedRegistrationOpen ? 1 : 0;
+    }
+
     if (body.discoveryEnabled !== undefined) {
       updateData.discoveryEnabled = body.discoveryEnabled ? 1 : 0;
     }
@@ -276,6 +284,7 @@ export async function settingsRoutes(app: FastifyInstance): Promise<void> {
     const response: InstanceAdminSettings = {
       instanceName: updatedRow.instanceName ?? 'Backspace',
       registrationOpen: updatedRow.registrationOpen !== null ? updatedRow.registrationOpen === 1 : config.registrationOpen,
+      federatedRegistrationOpen: updatedRow.federatedRegistrationOpen === 1,
       discoveryEnabled: updatedRow.discoveryEnabled === 1,
       gifApiKey: updatedGifKey ? `****${updatedGifKey.slice(-4)}` : undefined,
       gifEnabled: !!updatedGifKey,