1878 api cms hls media data model

.dockerignore

@@ -0,0 +1,18 @@
+# The build context is the repository root, and every Dockerfile here installs
+# its own dependencies. Shipping the working tree's node_modules would send
+# well over a gigabyte to the daemon and then be overwritten by `npm ci` anyway.
+**/node_modules
+**/dist
+**/.git
+
+# Test fixtures and desktop build output from the encoder submodule: large,
+# and nothing in an image needs them.
+luminary-media-convert/test-media
+luminary-media-convert/app-electron/bin
+luminary-media-convert/app-electron/release
+luminary-media-convert/api/work
+
+# NOT .env: the deploy workflow writes app/.env immediately before `docker build`,
+# and the PWA plugin reads its icon paths from it. Excluding it here would fail
+# the staging build with an undefined icon path.
+**/*.log

.github/workflows/app-deploy-staging.yml

@@ -33,6 +33,8 @@ jobs:
     steps:
       - name: Checkout repository
         uses: actions/checkout@v5
+        with:
+          submodules: true
 
       - name: Create .env file
         run: |

.github/workflows/app-unit-tests.yml

@@ -22,6 +22,8 @@ jobs:
     steps:
       - name: Checkout repository
         uses: actions/checkout@v5
+        with:
+          submodules: true
 
       - name: Setup Node.js
         uses: actions/setup-node@v6
@@ -31,6 +33,14 @@ jobs:
           cache: "npm"
           cache-dependency-path: app/package-lock.json
 
+      - name: Build the encoder's player libraries
+        # The submodule's packages ship only dist/, which is gitignored — a fresh
+        # checkout has sources and no entry points, and Vite fails with "Failed to
+        # resolve entry for package". ci:libs installs the five library workspaces
+        # without electron; build:libs builds them. Same as both Dockerfiles.
+        run: npm run ci:libs; npm run build:libs;
+        working-directory: luminary-media-convert
+
       - name: Build shared dependencies
         run: npm ci; npm run build;
         working-directory: shared

.github/workflows/cms-deploy-staging.yml

@@ -33,6 +33,8 @@ jobs:
     steps:
       - name: Checkout repository
         uses: actions/checkout@v5
+        with:
+          submodules: true
 
       - name: Create .env file
         run: |

.github/workflows/cms-unit-tests.yml

@@ -22,6 +22,8 @@ jobs:
     steps:
       - name: Checkout repository
         uses: actions/checkout@v5
+        with:
+          submodules: true
 
       - name: Setup Node.js
         uses: actions/setup-node@v6
@@ -31,6 +33,14 @@ jobs:
           cache: "npm"
           cache-dependency-path: cms/package-lock.json
 
+      - name: Build the encoder's player libraries
+        # The submodule's packages ship only dist/, which is gitignored — a fresh
+        # checkout has sources and no entry points, and Vite fails with "Failed to
+        # resolve entry for package". ci:libs installs the five library workspaces
+        # without electron; build:libs builds them. Same as both Dockerfiles.
+        run: npm run ci:libs; npm run build:libs;
+        working-directory: luminary-media-convert
+
       - name: Build shared dependencies
         run: npm ci; npm run build;
         working-directory: shared

.github/workflows/e2e-local-stack.yml

@@ -36,6 +36,8 @@ jobs:
     steps:
       - name: Checkout repository
         uses: actions/checkout@v5
+        with:
+          submodules: true
 
       - name: Setup Node.js
         uses: actions/setup-node@v6
@@ -49,6 +51,13 @@ jobs:
             cms/package-lock.json
             playwright-tests/package-lock.json
 
+      - name: Build the encoder's player libraries
+        # The submodule's packages ship only dist/, which is gitignored — a fresh
+        # checkout has sources and no entry points, and Vite fails with "Failed to
+        # resolve entry for package". Same as the unit-test workflows.
+        run: npm run ci:libs; npm run build:libs;
+        working-directory: luminary-media-convert
+
       - name: Start CouchDB
         run: |
           ./scripts/start-couchdb-in-ci.sh

.gitmodules

@@ -0,0 +1,4 @@
+[submodule "luminary-media-convert"]
+	path = luminary-media-convert
+	url = https://github.com/bccsa/luminary-media-convert.git
+	branch = main

CLAUDE.md

@@ -61,9 +61,24 @@ These are the seams that bite when you change one side and forget the other:
 
 ## Comment style
 
-Comments explain **why** code is added, in ~1–3 small sentences — neat and quick to read. They must not describe domain-specific / Luminary-internal concepts in depth, describe a problem or bug, narrate how logic previously worked ("previously", "used to", "the old approach", "now"), reference issue/ticket/spec/phase numbers, or run into multi-paragraph rationale (that belongs in PR descriptions, ADRs, or commit messages). Apply this to inline `//`, block `/* */`, JSDoc `/** */`, and `<!-- -->` in `.vue`. Don't rewrite pre-existing comments unless asked; only apply it to comments you're adding or already changing.
+Comments capture *why* code exists or why it's written a certain way — not *what* it does (the code already says that) and not architecture or design rationale. A comment that reads like a paragraph of prose, enumerates everywhere a concept is "excluded," or reproduces a doc is a signal it belongs in an ADR (`docs/adr/`), the package docs, or the datamodel — not inline.
 
-Comments should stay relevant to the repo they're in — don't explain how something outside this repo (a separate packaging/deploy pipeline, another service, an external tool) consumes or wraps the code. This repo has one source of truth for its own behavior; what happens to the build afterward belongs in that other project's docs, not here.
+- **No comment when the *why* is obvious or the code is self-explanatory.** Comments don't have to be everywhere.
+- **Keep a comment to a tldr — one or two short lines of *why*.** If more is needed, the explanation goes in docs and the comment shrinks to a one-line pointer.
+- **Don't trim past clarity.** Brevity is not the goal; a readable *why* is. Keep the subject/referent — a dangling fragment like `// Never replicated` is useless because *replicated to what?* Say `// Sidecars are never replicated to clients`. If dropping a word loses what the comment is about, keep the word.
+- **Never reproduce documentation in a comment.** A pointer is fine; re-explaining the contents is not.
+- **Never point a code comment at a `temp_` doc** (see Development docs below) — those are scaffolding, not a source of truth the code should depend on. If the *why* needs to live in code, write it as JSDoc, not as a link to a temp doc.
+- **JSDoc on exported APIs:** a one-line *why/what-it-is*. Reserve longer treatment for the docs.
+- Don't rewrite pre-existing comments unless asked; match the surrounding file's convention.
+
+## Development docs
+
+Working/proposal docs that exist only to develop a feature — not to document the final product — are **temporary scaffolding**. Treat them as such:
+
+- **Prefix their filenames with `temp_`** (e.g. `docs/temp_sidecar-...md`) so they're trivially findable and removable once the feature lands.
+- **Never reference a `temp_` doc from code or tests.** Code comments and JSDoc must stand on their own; a `temp_` doc will be deleted, so linking to it rots immediately.
+- When the feature ships, either delete the `temp_` docs (if the substance now lives in code/ADRs) or promote the durable parts into a permanent doc/ADR and drop the `temp_` prefix.
+- Anything that genuinely needs to be documented *in code* uses **JSDoc** (`/** */`), neatly — not `//` prose paragraphs.
 
 ## When changes span multiple packages
 

api/src/app.module.ts

@@ -15,8 +15,11 @@ import { QueryController } from "./endpoints/query.controller";
 import { FtsSearchService } from "./endpoints/ftsSearch.service";
 import { FtsSearchController } from "./endpoints/ftsSearch.controller";
 import { StorageStatusController } from "./endpoints/storageStatus.controller";
+import { EncoderConfigController } from "./endpoints/encoderConfig.controller";
+import { SidecarController } from "./endpoints/sidecar.controller";
 import { AuthIdentityService } from "./auth/authIdentity.service";
 import { QueryRateLimiterService } from "./ratelimit/queryRateLimiter.service";
+import { SidecarRateLimiterService } from "./ratelimit/sidecarRateLimiter.service";
 
 let winstonTransport: winston.transport;
 if (!process.env.NODE_ENV || process.env.NODE_ENV === "development") {
@@ -57,13 +60,16 @@ if (!process.env.NODE_ENV || process.env.NODE_ENV === "development") {
         QueryController,
         FtsSearchController,
         StorageStatusController,
+        EncoderConfigController,
+        SidecarController,
     ],
     providers: [
         DbService,
         Socketio,
         S3Service,
         QueryService,
         QueryRateLimiterService,
+        SidecarRateLimiterService,
         FtsSearchService,
         ChangeRequestService,
         AuthIdentityService,

api/src/changeRequests/aclValidation.spec.ts

@@ -146,4 +146,13 @@ describe("validateAcl", () => {
 
         expect(result).toHaveLength(0);
     });
+
+    it("should reject an ACL entry for DocType.Sidecar (never replicable, never grantable)", () => {
+        // Sidecar is absent from availablePermissionsPerDocType — the load-bearing
+        // non-replication guarantee. An entry is stripped.
+        const acl = [createEntry(DocType.Sidecar, "g1", [AclPermission.View, AclPermission.CmsView])];
+        const result = validateAcl(acl);
+
+        expect(result).toHaveLength(0);
+    });
 });

api/src/changeRequests/aclValidation.ts

@@ -72,7 +72,9 @@ const availablePermissionsPerDocType = {
     ],
 };
 
-// Valid DocTypes that can be used for ACL assignments
+// Derived from the map keys, NOT the DocType enum — so omitting Crypto/Sidecar
+// here is load-bearing: no ACL can grant view on them, so no client joins a
+// crypto-*/sidecar-* room.
 const validDocTypes = Object.keys(availablePermissionsPerDocType) as DocType[];
 
 /**

api/src/changeRequests/documentProcessing/deleteMediaCollection.spec.ts

@@ -0,0 +1,121 @@
+import { resolveCollectionPrefix } from "./deleteMediaCollection";
+
+/** A real collection URL: MinIO, where the bucket name is part of the public path. */
+const PUBLIC = "http://localhost:9000/media";
+const SESSION = "c5829f07-4ba8-42ed-a449-80d83e6c0b53";
+const HLS = `${PUBLIC}/${SESSION}/master.m3u8`;
+
+const prefixOf = (r: ReturnType<typeof resolveCollectionPrefix>) =>
+    "prefix" in r ? r.prefix : undefined;
+const refusalOf = (r: ReturnType<typeof resolveCollectionPrefix>) =>
+    "refusal" in r ? r.refusal : undefined;
+
+describe("resolveCollectionPrefix", () => {
+    describe("a URL stored relative to the bucket", () => {
+        it("needs no public URL at all — the path is already the key", () => {
+            const r = resolveCollectionPrefix(
+                "/c5829f07-4ba8-42ed-a449-80d83e6c0b53/master.m3u8",
+                undefined,
+            );
+            expect("prefix" in r && r.prefix).toBe(
+                "c5829f07-4ba8-42ed-a449-80d83e6c0b53",
+            );
+        });
+
+        it("still refuses a folder the encoder did not write", () => {
+            const r = resolveCollectionPrefix("/shared-folder/master.m3u8", undefined);
+            expect("refusal" in r && r.refusal).toContain("not a session id");
+        });
+
+        it("still refuses the bucket root", () => {
+            const r = resolveCollectionPrefix("/master.m3u8", undefined);
+            expect("refusal" in r && r.refusal).toContain("bucket root");
+        });
+    });
+
+    describe("resolves a collection this API wrote", () => {
+        it("strips the bucket's public base and the master filename", () => {
+            expect(prefixOf(resolveCollectionPrefix(HLS, PUBLIC))).toBe(SESSION);
+        });
+
+        it("tolerates a trailing slash on the configured public URL", () => {
+            expect(prefixOf(resolveCollectionPrefix(HLS, `${PUBLIC}/`))).toBe(SESSION);
+            expect(prefixOf(resolveCollectionPrefix(HLS, `${PUBLIC}///`))).toBe(SESSION);
+        });
+
+        it("keeps a nested path prefix intact", () => {
+            // pathPrefix on the session puts the collection in a subfolder.
+            const url = `${PUBLIC}/tenant-a/videos/${SESSION}/master.m3u8`;
+            expect(prefixOf(resolveCollectionPrefix(url, PUBLIC))).toBe(
+                `tenant-a/videos/${SESSION}`,
+            );
+        });
+
+        it("ignores a query string or fragment", () => {
+            expect(prefixOf(resolveCollectionPrefix(`${HLS}?v=2`, PUBLIC))).toBe(SESSION);
+            expect(prefixOf(resolveCollectionPrefix(`${HLS}#top`, PUBLIC))).toBe(SESSION);
+        });
+
+        it("handles a bucket published at a bare host", () => {
+            const base = "https://cdn.example.com";
+            expect(
+                prefixOf(resolveCollectionPrefix(`${base}/${SESSION}/master.m3u8`, base)),
+            ).toBe(SESSION);
+        });
+    });
+
+    describe("refuses anything it cannot prove it wrote", () => {
+        it("refuses a URL in a different bucket", () => {
+            const other = "https://someone-elses-cdn.example.com/media";
+            expect(refusalOf(resolveCollectionPrefix(`${other}/${SESSION}/master.m3u8`, PUBLIC)))
+                .toMatch(/not in this bucket/);
+        });
+
+        it("refuses a bucket whose name merely prefixes another", () => {
+            // The separator is part of the match, or `…/media` would claim
+            // `…/media-archive/<session>/master.m3u8`.
+            const url = `${PUBLIC}-archive/${SESSION}/master.m3u8`;
+            expect(refusalOf(resolveCollectionPrefix(url, PUBLIC))).toMatch(/not in this bucket/);
+        });
+
+        it("refuses a URL that is not a master playlist", () => {
+            expect(refusalOf(resolveCollectionPrefix(`${PUBLIC}/${SESSION}/`, PUBLIC)))
+                .toMatch(/master playlist/);
+            expect(
+                refusalOf(
+                    resolveCollectionPrefix(`${PUBLIC}/${SESSION}/stream/playlist.m3u8`, PUBLIC),
+                ),
+            ).toMatch(/master playlist/);
+        });
+
+        it("refuses the bucket root", () => {
+            expect(refusalOf(resolveCollectionPrefix(`${PUBLIC}/master.m3u8`, PUBLIC)))
+                .toMatch(/bucket root/);
+        });
+
+        it("refuses a path that tries to climb out", () => {
+            const url = `${PUBLIC}/../other-tenant/${SESSION}/master.m3u8`;
+            expect(refusalOf(resolveCollectionPrefix(url, PUBLIC))).toMatch(/suspicious path/);
+        });
+
+        it("refuses a folder that is not a session id", () => {
+            // The case the tick box makes possible: hlsUrl is editable, so someone
+            // can paste a URL naming a folder shared with other content.
+            const url = `${PUBLIC}/shared-videos/master.m3u8`;
+            expect(refusalOf(resolveCollectionPrefix(url, PUBLIC))).toMatch(/not a session id/);
+        });
+
+        it("refuses when either side is missing", () => {
+            expect(refusalOf(resolveCollectionPrefix(undefined, PUBLIC))).toMatch(/no media URL/);
+            expect(refusalOf(resolveCollectionPrefix(HLS, undefined))).toMatch(/no public URL/);
+            expect(refusalOf(resolveCollectionPrefix("", PUBLIC))).toMatch(/no media URL/);
+        });
+    });
+
+    it("never returns a prefix with a leading or trailing slash", () => {
+        // The caller appends '/' to scope the listing; a stray slash would widen it.
+        const prefix = prefixOf(resolveCollectionPrefix(HLS, PUBLIC))!;
+        expect(prefix.startsWith("/")).toBe(false);
+        expect(prefix.endsWith("/")).toBe(false);
+    });
+});