pathrs-lite: move new API to subpackage

This code should probably have been in a subpackage from the start
(since it has very little to do with securejoin) but at the time it felt
like a very minimal workaround.

Now that it looks like this is going to be a more permanent solution for
part of the Go ecosystem (and the license for most of this code has been
changed) we should separate it. The name "pathrs-lite" indicates what
the purpose of this subpackage is (i.e., it is a less complete version
of libpathrs).

Signed-off-by: Aleksa Sarai <[email protected]>

Author: cyphar

CHANGELOG.md

@@ -7,13 +7,26 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 ## [Unreleased] ##
 
 > **NOTE**: With this release, some parts of
-> `github.com/cyphar/filepath-securejoin` (notably the new APIs introduced
-> since the [0.3.0][] release) are now licensed under the Mozilla Public
-> License (version 2).
+> `github.com/cyphar/filepath-securejoin` are now licensed under the Mozilla
+> Public License (version 2). Please see [COPYING.md][] as well as the the
+> license header in each file for more details.
+
+[COPYING.md]: ./COPYING.md
+
+### Breaking ###
+- The new API introduced in the [0.3.0][] release has been moved to a new
+  subpackage called `pathrs-lite`. This was primarily done to better indicate
+  the split between the new and old APIs, as well as indicate to users the
+  purpose of this subpackage (it is a less complete version of [libpathrs][]).
+
+  We have added some wrappers to the top-level package to ease the transition,
+  but those are deprecated and will be removed in the next minor release of
+  filepath-securejoin. Users should update their import paths.
 
 ### Added ###
-- Most of the key bits the safe `procfs` API have now been exposed. At the
-  moment this primarily consists of a new `ProcfsHandle` API:
+- Most of the key bits the safe `procfs` API have now been exported and are
+  available in `github.com/cyphar/filepath-securejoin/pathrs-lite/procfs`. At
+  the moment this primarily consists of a new `procfs.Handle` API:
 
    * `OpenProcRoot` returns a new handle to `/proc`, endeavouring to make it
      safe if possible (`subset=pid` to protect against mistaken write attacks
@@ -25,8 +38,8 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
      of an operation, as filepath-securejoin will internally open a handle when
      necessary).
 
-   * The `(*ProcfsHandle).Open*` family of methods lets you get a safe `O_PATH`
-     handle to subpaths within `/proc` for certain subpaths.
+   * The `(*procfs.Handle).Open*` family of methods lets you get a safe
+     `O_PATH` handle to subpaths within `/proc` for certain subpaths.
 
      For `OpenThreadSelf`, the returned `ProcThreadSelfCloser` needs to be
      called after you completely finish using the handle (this is necessary

deprecated_linux.go

@@ -0,0 +1,48 @@
+// SPDX-License-Identifier: MPL-2.0
+
+//go:build linux
+
+// Copyright (C) 2024-2025 Aleksa Sarai <[email protected]>
+// Copyright (C) 2024-2025 SUSE LLC
+//
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+package securejoin
+
+import (
+	"github.com/cyphar/filepath-securejoin/pathrs-lite"
+)
+
+var (
+	// MkdirAll is a wrapper around [pathrs.MkdirAll].
+	//
+	// Deprecated: You should use [pathrs.MkdirAll] directly instead. This
+	// wrapper will be removed in filepath-securejoin v0.6.
+	MkdirAll = pathrs.MkdirAll
+
+	// MkdirAllHandle is a wrapper around [pathrs.MkdirAllHandle].
+	//
+	// Deprecated: You should use [pathrs.MkdirAllHandle] directly instead.
+	// This wrapper will be removed in filepath-securejoin v0.6.
+	MkdirAllHandle = pathrs.MkdirAllHandle
+
+	// OpenInRoot is a wrapper around [pathrs.OpenInRoot].
+	//
+	// Deprecated: You should use [pathrs.OpenInRoot] directly instead. This
+	// wrapper will be removed in filepath-securejoin v0.6.
+	OpenInRoot = pathrs.OpenInRoot
+
+	// OpenatInRoot is a wrapper around [pathrs.OpenatInRoot].
+	//
+	// Deprecated: You should use [pathrs.OpenatInRoot] directly instead. This
+	// wrapper will be removed in filepath-securejoin v0.6.
+	OpenatInRoot = pathrs.OpenatInRoot
+
+	// Reopen is a wrapper around [pathrs.Reopen].
+	//
+	// Deprecated: You should use [pathrs.Reopen] directly instead. This
+	// wrapper will be removed in filepath-securejoin v0.6.
+	Reopen = pathrs.Reopen
+)

pathrs-lite/README.md

@@ -0,0 +1,33 @@
+## `pathrs-lite` ##
+
+`github.com/cyphar/filepath-securejoin/pathrs-lite` provides a minimal **pure
+Go** implementation of the core bits of [libpathrs][]. This is not intended to
+be a complete replacement for libpathrs, instead it is mainly intended to be
+useful as a transition tool for existing Go projects.
+
+The long-term plan for `pathrs-lite` is to provide a build tag that will cause
+all `pathrs-lite` operations to call into libpathrs directly, thus removing
+code duplication for projects that wish to make use of libpathrs (and providing
+the ability for software packagers to opt-in to libpathrs support without
+needing to patch upstream).
+
+[libpathrs]: https://github.com/cyphar/libpathrs
+
+### License ###
+
+Most of this subpackage is licensed under the Mozilla Public License (version
+2.0). For more information, see the top-level [COPYING.md][] and
+[LICENSE.MPL-2.0][] files, as well as the individual license headers for each
+file.
+
+```
+Copyright (C) 2024-2025 Aleksa Sarai <[email protected]>
+Copyright (C) 2024-2025 SUSE LLC
+
+This Source Code Form is subject to the terms of the Mozilla Public
+License, v. 2.0. If a copy of the MPL was not distributed with this
+file, You can obtain one at https://mozilla.org/MPL/2.0/.
+```
+
+[COPYING.md]: ../COPYING.md
+[LICENSE.MPL-2.0]: ../LICENSE.MPL-2.0

pathrs-lite/doc.go

@@ -0,0 +1,14 @@
+// SPDX-License-Identifier: MPL-2.0
+
+//go:build linux
+
+// Copyright (C) 2024-2025 Aleksa Sarai <[email protected]>
+// Copyright (C) 2024-2025 SUSE LLC
+//
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+// Package pathrs (pathrs-lite) is a less complete pure Go implementation of
+// some of the APIs provided by [libpathrs].
+package pathrs

internal/assert/assert.go renamed to pathrs-lite/internal/assert/assert.go

@@ -15,7 +15,7 @@ import (
 
 	testassert "github.com/stretchr/testify/assert"
 
-	"github.com/cyphar/filepath-securejoin/internal/assert"
+	"github.com/cyphar/filepath-securejoin/pathrs-lite/internal/assert"
 )
 
 func TestAssertTrue(t *testing.T) {

internal/assert/assert_test.go renamed to pathrs-lite/internal/assert/assert_test.go

@@ -19,7 +19,7 @@ import (
 
 	"golang.org/x/sys/unix"
 
-	"github.com/cyphar/filepath-securejoin/internal/gocompat"
+	"github.com/cyphar/filepath-securejoin/pathrs-lite/internal/gocompat"
 )
 
 // prepareAtWith returns -EBADF (an invalid fd) if dir is nil, otherwise using

internal/errors.go renamed to pathrs-lite/internal/errors.go

@@ -18,7 +18,7 @@ import (
 
 	"golang.org/x/sys/unix"
 
-	"github.com/cyphar/filepath-securejoin/internal"
+	"github.com/cyphar/filepath-securejoin/pathrs-lite/internal"
 )
 
 // DupWithName creates a new file descriptor referencing the same underlying