feat: resolve Phase 1 contract requests and compose every feature

Contracts and core:
- Feature gains auth and stop; FeatureFactory; core composeServer builds the
  context, runs the factories, then the job queue from the union of their jobs
  (R8/R14). startServer uses it; main.ts composes learner, import, studio, AI.
- AppConfig/loadConfig own the layout and settings: courseDirs include
  <dataDir>/courses and <dataDir>/worktrees, studioReposDir, cacheDir,
  importRoots, uploadMaxMb, aiAllowedBaseUrls, transcribeUrl, python.
  resolveConfig derives the same for tests; cachePaths shares the importer's
  cache layout.
- canView: the global author role views every course (R14); the learner,
  studio and AI packages all call it.
- migrate(db, packages): core first, then packages in name order.
- Media: nosniff on every response, a sandbox CSP on svg/html/js; a Range on
  an empty file is 416.
- courseUrl/lessonUrl and the lesson route patterns live in @stc/contracts.

Packages:
- import, studio and AI read AppConfig instead of process.env; the importer
  refuses ids used by studio/repos.
- learner migrations run through core migrate; library covers fall back to
  the importer's cached candidate behind a canView-checked route.
- studio preview renders through the learner LessonView (anchors honoured,
  draft URLs); AI drafts go to the studio draft branch for studio courses (as
  the requesting user) and to <dataDir>/drafts otherwise, and the generator
  page says which.

Web: tsconfig paths for @stc/<feature>/web browser entries; features.ts
imports them by package name; nav.roles hides links by role.

Tests: compose, config, canView, media headers, migrations order, covers,
preview, nav, SPA bundle without server code, and an end-to-end flow on
SQLite and Postgres.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

packages/core/src/app.ts

@@ -6,12 +6,17 @@ import { serveMedia } from "./media";
 type Method = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
 export type Routes = Record<string, Partial<Record<Method, (req: Request) => Response | Promise<Response>>>>;
 
+/**
+ * The one visibility rule (ruling R14). Every package calls this; none keeps a local variant.
+ * public: everyone; signed-in: any signed-in user; restricted: the owner, the global `author` role, a per-course
+ * author (`isAuthor`, a course_authors row), or an ACL grant to the user or one of their groups.
+ */
 export function canView(user: AuthUser | null, course: LoadedCourse, acl: { principal_type: string; principal_id: string }[], isAuthor = false): boolean {
   const vis = course.manifest?.visibility ?? "restricted";
   if (vis === "public") return true;
   if (!user) return false;
   if (vis === "signed-in") return true;
-  if (user.roles.includes("owner") || isAuthor) return true;
+  if (user.roles.includes("owner") || user.roles.includes("author") || isAuthor) return true;
   return acl.some((a) => (a.principal_type === "user" && a.principal_id === user.id) || (a.principal_type === "group" && user.groups.includes(a.principal_id)));
 }
 

packages/core/src/compose.ts

@@ -0,0 +1,75 @@
+import type { AppConfig, AuthService, Feature, FeatureFactory, JobHandler, JobQueue, ServerContext } from "@stc/contracts";
+import { createCourseRepository } from "@stc/course-format";
+import { connect, migrate, type PackageMigrations } from "@stc/db";
+import { createApp } from "./app";
+import { createJobQueue } from "./jobs";
+
+/** Used until a feature supplies an `auth` service (the learner package does). */
+const anonymousAuth: AuthService = { userFromRequest: async () => null };
+
+export interface ComposeOptions {
+  /** Each package's migration folders, keyed by package name; run after core's, in name order. */
+  migrations?: PackageMigrations;
+  /** Start polling the job queue (default true). */
+  startJobs?: boolean;
+}
+
+export interface ComposedServer {
+  ctx: ServerContext;
+  features: Feature[];
+  app: ReturnType<typeof createApp>;
+  stop(): Promise<void>;
+}
+
+/**
+ * Builds the server context and the features (rulings R8/R14). Order:
+ * 1. connect and migrate (core, then packages);
+ * 2. load courses from `config.courseDirs`;
+ * 3. run each factory with the context. `ctx.jobs` already exists as a handle, but it forwards to the real queue,
+ *    which is built in step 4 from the union of the features' `jobs`, so factories may keep it but must not
+ *    enqueue while they run;
+ * 4. a feature carrying `auth` replaces the anonymous AuthService (at most one may).
+ */
+export async function composeServer(config: AppConfig, entries: (Feature | FeatureFactory)[], opts: ComposeOptions = {}): Promise<ComposedServer> {
+  const db = await connect(config.databaseUrl);
+  try {
+    await migrate(db, opts.migrations ?? {});
+    const courses = await createCourseRepository(config.courseDirs);
+    let queue: (JobQueue & { start(): void; stop(): Promise<void> }) | null = null;
+    const notYet = (): never => { throw new Error("the job queue is not ready while features are being built"); };
+    const jobs: JobQueue = {
+      enqueue: (kind, payload) => (queue ?? notYet()).enqueue(kind, payload),
+      get: (id) => (queue ?? notYet()).get(id),
+      list: (kind) => (queue ?? notYet()).list(kind),
+    };
+    const ctx: ServerContext = { config, db, courses, jobs, auth: anonymousAuth };
+    const features = entries.map((f) => (typeof f === "function" ? f(ctx) : f));
+    const handlers: Record<string, JobHandler> = {};
+    let authFrom: string | null = null;
+    for (const f of features) {
+      for (const [kind, h] of Object.entries(f.jobs ?? {})) {
+        if (handlers[kind]) throw new Error(`Duplicate job kind "${kind}" (feature "${f.name}")`);
+        handlers[kind] = h;
+      }
+      if (f.auth) {
+        if (authFrom) throw new Error(`Both "${authFrom}" and "${f.name}" supply an AuthService`);
+        authFrom = f.name;
+        ctx.auth = f.auth;
+      }
+    }
+    queue = createJobQueue(db, handlers);
+    const app = createApp(ctx, features);
+    if (opts.startJobs !== false) queue.start();
+    return {
+      ctx, features, app,
+      async stop() {
+        for (const f of features) { try { await f.stop?.(); } catch (e) { console.error(`[stc] stopping ${f.name}`, e); } }
+        await queue!.stop();
+        await db.close();
+      },
+    };
+  } catch (e) {
+    await db.close().catch(() => {});
+    throw e;
+  }
+}

packages/core/src/config.ts

@@ -1,7 +1,48 @@
+import { resolve } from "node:path";
 import type { AppConfig } from "@stc/contracts";
 
 const DEV_SECRET = "stc-dev-secret-change-me";
 
+/** The settings a deployment chooses; everything else in AppConfig is derived by `resolveConfig`. */
+export type ConfigInput = Pick<AppConfig, "dataDir"> & Partial<Omit<AppConfig, "dataDir">>;
+
+// Path lists are split on ":" only (paths may contain spaces); URL lists are trimmed.
+const paths = (raw: string | undefined) => (raw ?? "").split(":").filter(Boolean);
+const urls = (raw: string | undefined) => (raw ?? "").split(",").map((s) => s.trim()).filter(Boolean);
+
+/**
+ * Fills in the derived parts of the configuration. Course discovery always covers the importer's folders and the
+ * studio's published worktrees, after the configured dirs, without duplicates (compared as absolute paths).
+ * Tests and dev entries use this to build an AppConfig the same way `loadConfig` does.
+ */
+export function resolveConfig(input: ConfigInput): AppConfig {
+  const dataDir = input.dataDir;
+  const importedCoursesDir = input.importedCoursesDir ?? resolve(dataDir, "courses");
+  const studioWorktreesDir = input.studioWorktreesDir ?? resolve(dataDir, "worktrees");
+  const courseDirs: string[] = [];
+  for (const d of [...(input.courseDirs ?? []), importedCoursesDir, studioWorktreesDir]) {
+    if (!courseDirs.some((c) => resolve(c) === resolve(d))) courseDirs.push(d);
+  }
+  const port = input.port ?? 3000;
+  return {
+    port,
+    databaseUrl: input.databaseUrl ?? "sqlite://./data/stcourses.db",
+    dataDir,
+    courseDirs,
+    secret: input.secret ?? DEV_SECRET,
+    publicUrl: input.publicUrl ?? `http://localhost:${port}`,
+    importedCoursesDir,
+    studioReposDir: input.studioReposDir ?? resolve(dataDir, "studio", "repos"),
+    studioWorktreesDir,
+    cacheDir: input.cacheDir ?? resolve(dataDir, "cache"),
+    importRoots: input.importRoots ?? [resolve(dataDir, "import-inbox")],
+    uploadMaxMb: input.uploadMaxMb ?? 100,
+    aiAllowedBaseUrls: input.aiAllowedBaseUrls ?? [],
+    transcribeUrl: input.transcribeUrl ?? null,
+    python: input.python ?? "python3",
+  };
+}
+
 export function loadConfig(env: Record<string, string | undefined> = process.env): AppConfig {
   const port = env.STC_PORT !== undefined && env.STC_PORT !== "" ? Number(env.STC_PORT) : 3000;
   if (!Number.isInteger(port) || port < 0) throw new Error(`Invalid STC_PORT: ${env.STC_PORT}`);
@@ -11,12 +52,40 @@ export function loadConfig(env: Record<string, string | undefined> = process.env
     console.warn("[stc] STC_SECRET is not set; using an insecure development default");
     secret = DEV_SECRET;
   }
-  return {
+  let uploadMaxMb = 100;
+  if (env.STC_UPLOAD_MAX_MB) {
+    uploadMaxMb = Number(env.STC_UPLOAD_MAX_MB);
+    if (!Number.isFinite(uploadMaxMb) || uploadMaxMb <= 0) throw new Error(`Invalid STC_UPLOAD_MAX_MB: ${env.STC_UPLOAD_MAX_MB}`);
+  }
+  const dataDir = env.STC_DATA_DIR || "./data";
+  const roots = paths(env.STC_IMPORT_ROOTS);
+  return resolveConfig({
     port,
     databaseUrl: env.STC_DATABASE_URL || "sqlite://./data/stcourses.db",
-    dataDir: env.STC_DATA_DIR || "./data",
-    courseDirs: (env.STC_COURSE_DIRS || "./overlays:./courses").split(":").filter(Boolean),
+    dataDir,
+    courseDirs: paths(env.STC_COURSE_DIRS || "./overlays:./courses"),
     secret,
     publicUrl: env.STC_PUBLIC_URL || `http://localhost:${port}`,
+    importRoots: roots.length ? roots.map((r) => resolve(r)) : undefined,
+    uploadMaxMb,
+    aiAllowedBaseUrls: urls(env.STC_AI_ALLOWED_BASE_URLS),
+    transcribeUrl: env.STC_TRANSCRIBE_URL || null,
+    python: env.STC_PYTHON || "python3",
+  });
+}
+
+/** The importer's derived-file layout under `cacheDir` (decks, cover candidates, transcripts), shared by every package. */
+export function cachePaths(config: Pick<AppConfig, "cacheDir">) {
+  const root = config.cacheDir;
+  const seg = (s: string) => {
+    if (!s || s === "." || s === ".." || s.includes("/") || s.includes("\\") || s.includes("\0")) throw new Error(`invalid cache path segment "${s}"`);
+    return s;
+  };
+  return {
+    root,
+    deckDir: (courseId: string, deckId: string) => resolve(root, "decks", seg(courseId), seg(deckId)),
+    coversDir: (courseId: string) => resolve(root, "covers", seg(courseId)),
+    transcriptFile: (courseId: string, lessonId: string) => resolve(root, "transcripts", seg(courseId), `${seg(lessonId)}.json`),
+    transcriptsDir: (courseId: string) => resolve(root, "transcripts", seg(courseId)),
   };
 }

packages/core/src/index.ts

@@ -1,4 +1,5 @@
-export { loadConfig } from "./config";
+export { loadConfig, resolveConfig, cachePaths, type ConfigInput } from "./config";
 export { createJobQueue } from "./jobs";
-export { serveMedia, contentType, contentDisposition } from "./media";
+export { serveMedia, contentType, contentDisposition, mediaSecurityHeaders, MEDIA_SANDBOX_CSP } from "./media";
 export { createApp, canView, type Routes } from "./app";
+export { composeServer, type ComposeOptions, type ComposedServer } from "./compose";

packages/core/src/media.ts

@@ -1,9 +1,23 @@
 const TYPES: Record<string, string> = {
   mp4: "video/mp4", webm: "video/webm", pdf: "application/pdf", png: "image/png", jpg: "image/jpeg", jpeg: "image/jpeg",
   svg: "image/svg+xml", md: "text/markdown; charset=utf-8", txt: "text/plain; charset=utf-8", zip: "application/zip",
-  js: "text/javascript; charset=utf-8", ts: "text/plain; charset=utf-8",
+  js: "text/javascript; charset=utf-8", mjs: "text/javascript; charset=utf-8", ts: "text/plain; charset=utf-8",
+  html: "text/html; charset=utf-8", htm: "text/html; charset=utf-8", xhtml: "application/xhtml+xml", xml: "application/xml",
 };
 
+/** Types a browser could run script from. Course media is author content on the app origin, so these get a sandbox. */
+const ACTIVE = new Set(["svg", "html", "htm", "xhtml", "xml", "js", "mjs"]);
+/** Opaque origin, no script, no plugins: an svg still renders as an image, an html page as inert markup. */
+export const MEDIA_SANDBOX_CSP = "sandbox; default-src 'none'; img-src 'self' data:; style-src 'unsafe-inline'; media-src 'self'";
+
+/** Headers every media response carries; plus a sandbox CSP for script-capable types. */
+export function mediaSecurityHeaders(path: string): Record<string, string> {
+  const ext = path.slice(path.lastIndexOf(".") + 1).toLowerCase();
+  const h: Record<string, string> = { "X-Content-Type-Options": "nosniff" };
+  if (ACTIVE.has(ext)) h["Content-Security-Policy"] = MEDIA_SANDBOX_CSP;
+  return h;
+}
+
 export function contentType(path: string): string {
   const ext = path.slice(path.lastIndexOf(".") + 1).toLowerCase();
   return TYPES[ext] ?? "application/octet-stream";
@@ -42,11 +56,14 @@ export async function serveMedia(req: Request, absPath: string, opts: { download
   const headers: Record<string, string> = {
     "Content-Type": contentType(absPath),
     "Accept-Ranges": "bytes",
+    ...mediaSecurityHeaders(absPath),
   };
   if (opts.download) headers["Content-Disposition"] = contentDisposition(name);
   const range = req.headers.get("range");
   const parsed = range ? parseRange(range, size) : null;
-  if (parsed === "invalid") return new Response(null, { status: 416, headers: { "Content-Range": `bytes */${size}`, "Accept-Ranges": "bytes" } });
+  if (parsed === "invalid" || (parsed && size === 0)) {
+    return new Response(null, { status: 416, headers: { "Content-Range": `bytes */${size}`, "Accept-Ranges": "bytes", "X-Content-Type-Options": "nosniff" } });
+  }
   if (!parsed) {
     headers["Content-Length"] = String(size);
     return new Response(req.method === "HEAD" ? null : file, { status: 200, headers });