fix(atelet): prevent path traversal in OCI tar extraction

[Kyosuke Konishi (konippi)]

Resolves the three TODO comments in cmd/atelet/oci.go that called for a constrained filesystem to prevent path traversal, symlink escape, and hardlink escape during OCI tar extraction.

Uses os.Root (Go 1.24+) to confine all file operations to the rootfs directory. Adds validateTarName() as defence in depth.

• Tests pass
• Appropriate changes to documentation are included in the PR

[Kyosuke Konishi (konippi)]

e2e-test failure is unrelated to this change — TestDemo3 timed out waiting for ResumeGoldenActor (gVisor restore) after 90s. The atelet image built and rolled out successfully; run-tests (unit tests + verify) passed. This looks like a flaky timeout in the kind CI environment. Happy to rebase and re-run if needed.

[Benjamin Elder (BenTheElder)]

Hmm, I haven't seen this flake yet and we've tested quite a few PRs in this environment. Will rerun it.

[Benjamin Elder (BenTheElder)]

These tests are also possible to run locally.

[Benjamin Elder (BenTheElder)]

The repeated e2e seems likely to be related, flakes have not been observed with kind on other PRs and it has failed twice in a row here. You can test the counter demo locally by following the README.

[Kyosuke Konishi (konippi)]

Benjamin Elder (@BenTheElder)
Thanks for the re-run and the nudge to test locally — I was able to reproduce and found the root cause.

mutate.Extract produces entries with absolute paths (e.g. /ko-app/counter), and my validateTarName was rejecting them via filepath.IsLocal. The old code handled this implicitly through filepath.Join. Fixed by stripping the leading / before validation. Verified locally on kind.

[a4-a4s1]

Heads-up on a parallel PR that touches the same file: #96 (WIP, dims) modifies cmd/atelet/oci.go to add gpu *ateletpb.GpuSpec to prepareOCIDirectory's signature and adds a ~168-line GPU/CUDA helper block after untar. It doesn't touch untar itself, but the signature change will likely conflict with the resolve here.

Two observations for the maintainers:

• This PR's os.Root rewrite (lines ~188-215) is a hard security-bound constraint; the new oci_test.go (+362 lines) anchors it well.
• [WIP] feat: GPU passthrough for actors via gVisor nvproxy + cuda-checkpoint #96's GPU helpers extend prepareOCIDirectory's call pattern but don't redefine the tar/extraction primitives — they ride on top.

Q: any preference on merge order? Landing this PR first anchors the constrained-filesystem invariant for #96 to build on; the reverse means re-porting os.Root semantics into the GPU-aware code path. Both are dims's-queue calls, but flagging in case the overlap wasn't already on radar.

[🤖a4s1]

[Benjamin Elder (BenTheElder)]

The other PR is ... "WIP" ... this is not a concern.

[Benjamin Elder (BenTheElder)]

I checked this out locally for review, it looks like we need to handle "last entry wins" still for symlinks being replaced by real files and vice versa, wrote a follow-up commit at:

https://github.com/agent-substrate/substrate/compare/main...BenTheElder:substrate:tar-fix?expand=1

[Benjamin Elder (BenTheElder)]

That appears to be a pre-existing issue, so I think we can handle it as a follow-up.