@learnpack/learnpack 5.0.355 → 5.0.357

package/src/services/ingest/http/zipPackageReader.ts

@@ -0,0 +1,81 @@
+import * as JSZip from "jszip"
+import { IngestError } from "../errors"
+import { PackageFiles } from "../core/validatePackage"
+
+/**
+ * Rejects an entry whose path could escape the course prefix.
+ *
+ * Every entry eventually becomes a bucket key under `courses/{slug}/`. A zip is
+ * attacker-controlled input, and an entry named `../../other-course/learn.json`
+ * would land outside the prefix the caller was authorized for — the storage
+ * layer concatenates, it does not resolve.
+ * Exported for its own test: JSZip's writer normalizes `..` away, so a zip
+ * built through that API cannot express the traversal case, while an archive
+ * from any other tool can — its reader passes entry names through untouched.
+ * @param path - Entry name as stored in the zip.
+ * @returns True when the entry is safe to keep.
+ */
+export function isSafeEntryPath(path: string): boolean {
+  if (path.startsWith("/") || /^[a-z]:/i.test(path)) {
+    return false
+  }
+
+  return !path.split("/").includes("..")
+}
+
+/**
+ * Reads a course package zip into memory.
+ *
+ * Lives beside the router rather than in `core/` on purpose: this is decoding a
+ * transport format, and the core is meant to know nothing about how a package
+ * reached it — not even that it arrived compressed.
+ * @param buffer - The uploaded zip.
+ * @returns Entry path relative to the package root → text contents.
+ * @throws IngestError `INVALID_PACKAGE` when the archive cannot be read.
+ */
+export async function readPackageZip(buffer: Buffer): Promise<PackageFiles> {
+  let archive: JSZip
+
+  try {
+    archive = await JSZip.loadAsync(buffer)
+  } catch (error) {
+    throw new IngestError(
+      "INVALID_PACKAGE",
+      `The uploaded file is not a readable zip: ${(error as Error).message}`,
+      error
+    )
+  }
+
+  const files: PackageFiles = {}
+  const unsafe: string[] = []
+
+  const entries = Object.values(archive.files).filter(entry => !entry.dir)
+
+  await Promise.all(
+    entries.map(async entry => {
+      const path = entry.name.replace(/\\/g, "/")
+
+      if (!isSafeEntryPath(path)) {
+        unsafe.push(entry.name)
+        return
+      }
+
+      files[path] = await entry.async("string")
+    })
+  )
+
+  if (unsafe.length > 0) {
+    throw new IngestError(
+      "INVALID_PACKAGE",
+      `The zip contains ${unsafe.length} entr${
+        unsafe.length === 1 ? "y" : "ies"
+      } pointing outside the package: ${unsafe.slice(0, 3).join(", ")}`
+    )
+  }
+
+  if (Object.keys(files).length === 0) {
+    throw new IngestError("INVALID_PACKAGE", "The zip holds no files")
+  }
+
+  return files
+}

package/src/services/ingest/ports/courseStorage.ts

@@ -0,0 +1,25 @@
+/**
+ * Where an ingested course's files live.
+ *
+ * Object-level operations only: the ingest core decides *what* the course
+ * layout is, and this port only knows how to put bytes somewhere and take them
+ * back. Keeping it this small is what lets the core run against an in-memory
+ * double in tests, with no credentials and no network.
+ */
+export interface CourseStorage {
+  /** Writes (or overwrites) a text object at `path`. */
+  write(path: string, content: string): Promise<void>;
+  /** Reads an object, or null when it does not exist. */
+  read(path: string): Promise<string | null>;
+  /** Lists every object path under `prefix`. */
+  list(prefix: string): Promise<string[]>;
+  /**
+   * Deletes the given paths.
+   *
+   * Re-ingesting with `--overwrite` has to remove lessons the regenerated
+   * course no longer has: the IDE derives its exercise list from whatever files
+   * it finds, so an upsert would leave the old folders behind as phantom
+   * lessons.
+   */
+  deleteMany(paths: string[]): Promise<void>;
+}

package/src/services/ingest/ports/packageRegistry.ts

@@ -0,0 +1,60 @@
+/**
+ * The subset of a Rigobot learning package the ingest service reads.
+ *
+ * Deliberately not the full payload: naming only what is used keeps the
+ * contract honest about what a replacement registry would have to provide.
+ */
+export type RigoPackage = {
+  id: number;
+  package_slug: string;
+  /**
+   * Organization **id**, or null when Rigobot could not auto-detect one.
+   *
+   * An id rather than a slug because that is what comes back: the field is a
+   * plain ForeignKey on a ModelSerializer, so it serializes to the primary key.
+   * The assignment endpoint accepts either form, but nothing ever reads a slug
+   * back, which is why ids are the only representation the two ends share.
+   */
+  organization: number | null;
+  status: string;
+};
+
+/** One of the organizations the calling user belongs to. */
+export type RigoOrganization = {
+  id: number;
+  name: string;
+};
+
+/**
+ * The registry that owns course slugs and their ownership.
+ *
+ * Slugs are globally unique across every Rigobot user, and in practice
+ * immutable — the rename endpoint does not update the package on Rigobot's
+ * side — so the ingest resolves availability *before* writing anything.
+ */
+export interface PackageRegistry {
+  /** True when no package holds this slug yet. */
+  isSlugAvailable(slug: string): Promise<boolean>;
+  /**
+   * Registers a new package.
+   * @throws IngestError `SLUG_TAKEN` when the slug is already registered.
+   */
+  createPackage(slug: string, config: unknown): Promise<RigoPackage>;
+  /** Reads a package, or null when it does not exist or is not ours. */
+  getPackageBySlug(slug: string): Promise<RigoPackage | null>;
+  /**
+   * Attaches a package to an organization.
+   *
+   * One-shot: Rigobot only accepts this while the package's organization is
+   * still null, and offers no way to detach it afterwards.
+   */
+  assignOrganization(packageId: number, organizationId: number): Promise<void>;
+  /**
+   * The organizations the calling user belongs to.
+   *
+   * Needed because configuration names an organization the way a human would,
+   * while packages report it as an id. This is the only lookup that bridges
+   * the two — and it doubles as the list to show when the name matches none.
+   */
+  listOrganizations(): Promise<RigoOrganization[]>;
+}

package/src/services/ingest/ports/requestAuthenticator.ts

@@ -0,0 +1,28 @@
+/**
+ * Who is making an ingest request.
+ *
+ * Carried as data through the core, never re-read from headers or the
+ * environment further in: the moment the core reaches for a credential itself,
+ * swapping the auth scheme stops being a one-file change.
+ */
+export type Identity = {
+  rigoToken: string;
+};
+
+/**
+ * Resolves an identity from a request's headers.
+ *
+ * Takes headers rather than a request object on purpose — the port must not
+ * know that Express exists, so the day this service moves behind a different
+ * transport only the adapter changes. Today the credential is a Rigobot user
+ * token; when the machine-to-machine token arrives, it is a second adapter
+ * here and nothing else moves.
+ */
+export interface RequestAuthenticator {
+  /**
+   * @throws IngestError `INVALID_TOKEN` when the credential is missing or rejected.
+   */
+  authenticate(
+    headers: Record<string, string | string[] | undefined>
+  ): Promise<Identity>;
+}