feat(box): restrict box creation to the supported pinned images by law-chain-hot · Pull Request #758 · boxlite-ai/boxlite

law-chain-hot · 2026-06-13T10:31:52Z

Summary

main already accepts a free-form image string on box creation (landed in #755). This PR adds only the curated allowlist on top — the pre-launch security gate.

main (#755):   create accepts ANY image string  →  runner pulls it
this PR:       create validates image against the supported pinned set
               (base / python / node, sha256-pinned ghcr refs)
               unsupported  → 400 listing the supported refs
               undefined    → defaults to the base image

Without this gate, a request can make the runner pull an arbitrary image using its private-registry token — so the allowlist is required before launch.

Changes (server-side only)

apps/api/src/box/constants/curated-images.constant.ts — supportedImages() / assertSupportedImage(); env-overridable (BOXLITE_SYSTEM_{BASE,PYTHON,NODE}_IMAGE) with sha256-pinned fallbacks. + spec.
box.service create: validate createBoxDto.image at the request boundary.

Scope boundary (what this PR is NOT)

No client regen — the image field shape is unchanged (still a string), only its accepted values are restricted server-side.
No SDK / dashboard / identity changes. The single-id collapse and the SDK removal are separate PRs.

Verification

API jest 106/106 (curated allowlist spec 5/5).

Summary by CodeRabbit

Tests
- Added comprehensive test coverage for image allowlist validation.
New Features
- The API now validates container image requests against a curated allowlist. Unsupported images are rejected with error messages listing available options.

main already accepts a free-form image string (#755). This adds the curated allowlist on top: box creation validates the image against the deployment's supported, sha256-pinned ghcr refs (base/python/node) and rejects anything else with a 400 listing the supported set. Undefined defaults to the base image. This is the pre-launch security gate — without it a request could make the runner pull an arbitrary image with its private-registry token. - add curated-images.constant.ts (supportedImages / assertSupportedImage, env-overridable, pinned fallbacks) + spec - box.service create: validate createBoxDto.image at the request boundary Scope: server-side allowlist only. No client regen (image field shape is unchanged), no SDK/dashboard/identity changes. API jest 106/106 (curated spec 5/5).

coderabbitai · 2026-06-13T10:32:04Z

📝 Walkthrough

Walkthrough

A new image allowlist module restricts Box creation to three pinned OCI refs with environment variable overrides. The BoxService now validates and normalizes the requested image via assertSupportedImage() at the API boundary, rejecting unsupported refs with a detailed error.

Changes

Image Allowlist Validation

Layer / File(s)	Summary
Image allowlist contract and validation `apps/api/src/box/constants/curated-images.constant.ts`, `apps/api/src/box/constants/curated-images.constant.spec.ts`	Defines `SUPPORTED_IMAGE_SOURCES` mapping three environment variable override names to pinned fallback OCI refs. Exports `supportedImages()` to return the effective allowlist (env overrides take precedence) and `assertSupportedImage(image)` to normalize `undefined` to the default base image, accept allowlisted refs verbatim, and reject unsupported refs by throwing `BadRequestError` with the supported list in the error message. Comprehensive tests verify allowlist ordering, defaulting behavior, environment variable precedence, and error rejection paths.
Box service image validation `apps/api/src/box/services/box.service.ts`	Imports `assertSupportedImage` and applies it in `create()` to validate and normalize `createBoxDto.image`, enforcing image support at the request boundary.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Poem

🐰 Three pinned images hop through the gate,
With env vars that dictate their fate,
The allowlist bounds what boxes may wear,
Validation assured, no imports to spare!

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely summarizes the main change: restricting box creation to supported pinned images, which is the primary objective of the changeset.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

Create stacked PR
Commit on current branch

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch feat/box-curated-allowlist

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

coderabbitai

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@apps/api/src/box/constants/curated-images.constant.ts`:
- Around line 39-41: supportedImages currently trusts raw env overrides from
SUPPORTED_IMAGE_SOURCES and can accept unpinned or non-GHCR refs; change
supportedImages() so that for each entry (from SUPPORTED_IMAGE_SOURCES.map(({
envVar, fallbackRef })) you read process.env[envVar] but only accept it if it
matches a pinned GHCR digest pattern (e.g.
/^ghcr\.io\/[^\s@]+@sha256:[a-f0-9]{64}$/i); if the env value fails validation,
fall back to fallbackRef instead (no throw), and return the array of validated
refs. Use the function name supportedImages and the SUPPORTED_IMAGE_SOURCES
entries to locate and implement this validation logic.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

Push a commit to this branch (recommended)
Create a new PR with the fixes

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 2c2b4acb-f945-4e61-aad6-ce24865dfde1

📥 Commits

Reviewing files that changed from the base of the PR and between d035ad2 and 631b8ce.

📒 Files selected for processing (3)

apps/api/src/box/constants/curated-images.constant.spec.ts
apps/api/src/box/constants/curated-images.constant.ts
apps/api/src/box/services/box.service.ts

#758 dropped the docker.io/library/alpine entry from supportedImages, so the chore-conftest's bare 'alpine:3.23' default now gets 400 'Unsupported image' on Tokyo Api. Send the curated-images constant's default ghcr ref (which the 20260605-p0-r3 tag also points at), so the test exercises the runner toolbox fix end-to-end. Tokyo runner has GHCR_USERNAME/GHCR_TOKEN injected via systemd drop-in for the pull. Local-verified: yaml parses, conftest reads the env into DEFAULT_IMAGE, ghcr token exchange + manifest fetch returns 200.

law-chain-hot requested a review from a team as a code owner June 13, 2026 10:31

law-chain-hot requested a review from DorianZheng June 13, 2026 10:31

law-chain-hot mentioned this pull request Jun 13, 2026

feat(box): image pipeline + single box identity (drop dual boxId) #756

Closed

coderabbitai Bot reviewed Jun 13, 2026

View reviewed changes

Comment thread apps/api/src/box/constants/curated-images.constant.ts

DorianZheng enabled auto-merge June 13, 2026 10:43

DorianZheng approved these changes Jun 13, 2026

View reviewed changes

DorianZheng added this pull request to the merge queue Jun 13, 2026

Merged via the queue into main with commit 707fb80 Jun 13, 2026
30 of 31 checks passed

DorianZheng deleted the feat/box-curated-allowlist branch June 13, 2026 10:45

law-chain-hot mentioned this pull request Jun 13, 2026

Single box identity: collapse uuid/boxId into one 12-char id (after #748) #759

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(box): restrict box creation to the supported pinned images#758

feat(box): restrict box creation to the supported pinned images#758
DorianZheng merged 1 commit into
mainfrom
feat/box-curated-allowlist

law-chain-hot commented Jun 13, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

coderabbitai Bot commented Jun 13, 2026 •

edited

Loading

Walkthrough

Changes

Estimated code review effort

Poem

Uh oh!

coderabbitai Bot left a comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

law-chain-hot commented Jun 13, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes (server-side only)

Scope boundary (what this PR is NOT)

Verification

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented Jun 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Estimated code review effort

Poem

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

law-chain-hot commented Jun 13, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Jun 13, 2026 •

edited

Loading