Documentation
¶
Overview ¶
Package workspace identifies the filesystem root owned by a coding session and persists explicit user trust outside that root.
Index ¶
- Constants
- Variables
- func NormalizePath(name string, allowRoot bool) (string, error)
- type Identity
- type Mutation
- type MutationDir
- func (d *MutationDir) Close() error
- func (d *MutationDir) Link(oldName, newName string) error
- func (d *MutationDir) Lstat(name string) (fs.FileInfo, error)
- func (d *MutationDir) Mkdir(name string, perm fs.FileMode) error
- func (d *MutationDir) Open(name string) (*os.File, error)
- func (d *MutationDir) OpenFile(name string, flag int, perm fs.FileMode) (*os.File, error)
- func (d *MutationDir) Path() string
- func (d *MutationDir) Remove(name string) error
- func (d *MutationDir) Rename(oldName, newName string) error
- func (d *MutationDir) Sync() error
- type Permission
- type PermissionDecision
- type PermissionKind
- type Store
- func (s *Store) IsTrusted(identity Identity) (bool, error)
- func (s *Store) Path() string
- func (s *Store) Permission(identity Identity, kind PermissionKind, resourceID string) (Permission, bool, error)
- func (s *Store) SetPermission(identity Identity, permission Permission) error
- func (s *Store) Trust(identity Identity) error
- type Tree
- func (t *Tree) Close() error
- func (t *Tree) FileSystem() fs.FS
- func (t *Tree) InspectAddPath(name string) (string, fs.FileInfo, []string, error)
- func (t *Tree) InspectMutationPath(name string) (string, fs.FileInfo, error)
- func (t *Tree) InspectRegularPath(name string) (string, fs.FileInfo, error)
- func (t *Tree) Lstat(name string) (fs.FileInfo, error)
- func (t *Tree) Mutate(ctx context.Context, fn func(*Mutation) error) error
- func (t *Tree) NormalizeUserPath(name string, allowRoot bool) (string, error)
- func (t *Tree) Open(name string) (*os.File, error)
- func (t *Tree) Path() string
- func (t *Tree) ReadDir(name string) ([]fs.DirEntry, error)
- func (t *Tree) Readlink(name string) (string, error)
- func (t *Tree) Stat(name string) (fs.FileInfo, error)
- type Workspace
Constants ¶
const (
// StoreSchema identifies the durable workspace store format.
StoreSchema = "pips.workspaces/v1alpha1"
)
Variables ¶
var ( // ErrInsecurePermissions means a workspace store path can be accessed by // users other than its owner. ErrInsecurePermissions = errors.New("coding workspace: insecure store permissions") // ErrUnsupportedStoreSchema means the store uses an unknown schema. ErrUnsupportedStoreSchema = errors.New("coding workspace: unsupported store schema") // ErrStoreTooLarge means the store exceeds its bounded input size. ErrStoreTooLarge = errors.New("coding workspace: store too large") // ErrWorkspaceUnknown means a permission was recorded before its Workspace // was explicitly trusted. ErrWorkspaceUnknown = errors.New("coding workspace: workspace is not trusted") )
var ( // ErrInvalid means a workspace path or identity is unusable. ErrInvalid = errors.New("coding workspace: invalid workspace") // ErrInvalidPath means a workspace-relative path is malformed. ErrInvalidPath = errors.New("coding workspace: invalid path") // ErrOutsideRoot means a path attempts to leave the workspace root. ErrOutsideRoot = errors.New("coding workspace: path outside root") // ErrSymlink means a mutation path traverses a symbolic link. ErrSymlink = errors.New("coding workspace: symbolic link not allowed") // ErrUnsupportedType means a path is not a regular file or directory. ErrUnsupportedType = errors.New("coding workspace: unsupported file type") // ErrChanged means a filesystem object changed during a guarded operation. ErrChanged = errors.New("coding workspace: path changed") // ErrClosed means an operation used a closed workspace tree. ErrClosed = errors.New("coding workspace: tree closed") // ErrUnsupportedPlatform means the current platform cannot supply the // filesystem identity required for a safe trust decision. ErrUnsupportedPlatform = errors.New("coding workspace: unsupported platform") )
Functions ¶
Types ¶
type Identity ¶
type Identity struct {
// contains filtered or unexported fields
}
Identity binds trust to both a canonical path and the filesystem object currently found there.
type Mutation ¶
type Mutation struct {
// contains filtered or unexported fields
}
Mutation is active only for the duration of a Tree.Mutate callback.
type MutationDir ¶
type MutationDir struct {
// contains filtered or unexported fields
}
MutationDir is a stable directory handle used by a guarded mutation.
func (*MutationDir) Close ¶
func (d *MutationDir) Close() error
Close releases the directory handle. Repeated calls are safe.
func (*MutationDir) Link ¶
func (d *MutationDir) Link(oldName, newName string) error
Link creates a hard link between two direct children. It fails when the new name already exists, which makes it suitable for guarded backup creation.
func (*MutationDir) Lstat ¶
func (d *MutationDir) Lstat(name string) (fs.FileInfo, error)
Lstat inspects a direct child without following a final symbolic link.
func (*MutationDir) Mkdir ¶
func (d *MutationDir) Mkdir(name string, perm fs.FileMode) error
Mkdir creates one direct child directory without following symbolic links.
func (*MutationDir) Open ¶
func (d *MutationDir) Open(name string) (*os.File, error)
Open opens a direct child for guarded inspection.
func (*MutationDir) OpenFile ¶
OpenFile opens a direct child using the supplied flags and permission bits.
func (*MutationDir) Path ¶
func (d *MutationDir) Path() string
Path returns the normalized workspace-relative directory path.
func (*MutationDir) Remove ¶
func (d *MutationDir) Remove(name string) error
Remove removes one direct child.
func (*MutationDir) Rename ¶
func (d *MutationDir) Rename(oldName, newName string) error
Rename atomically renames one direct child to another in the same directory.
func (*MutationDir) Sync ¶
func (d *MutationDir) Sync() error
Sync asks the operating system to persist directory metadata.
type Permission ¶
type Permission struct {
Kind PermissionKind `json:"kind"`
ResourceID string `json:"resource_id"`
Fingerprint string `json:"fingerprint"`
Decision PermissionDecision `json:"decision"`
DecidedAt time.Time `json:"decided_at"`
}
Permission binds one local decision to a normalized resource fingerprint.
type PermissionDecision ¶
type PermissionDecision string
PermissionDecision is an explicit local allow or deny decision.
const ( PermissionAllow PermissionDecision = "allow" PermissionDeny PermissionDecision = "deny" )
Supported permission decisions.
type PermissionKind ¶
type PermissionKind string
PermissionKind identifies a typed workspace-scoped authority.
const (
PermissionMCPServer PermissionKind = "mcp_server"
)
Supported permission kinds.
type Store ¶
type Store struct {
// contains filtered or unexported fields
}
Store records workspace-scoped user decisions outside project directories. The file is read lazily and mutations are serialized per Store instance.
func (*Store) IsTrusted ¶
IsTrusted reports whether identity is present and still matches its stored canonical path and filesystem identity.
func (*Store) Permission ¶
func (s *Store) Permission( identity Identity, kind PermissionKind, resourceID string, ) (Permission, bool, error)
Permission returns one typed decision for identity and resourceID.
func (*Store) SetPermission ¶
func (s *Store) SetPermission(identity Identity, permission Permission) error
SetPermission records a typed decision for an already trusted Workspace.
type Tree ¶
type Tree struct {
// contains filtered or unexported fields
}
Tree owns confined filesystem access for a Workspace. It is safe for concurrent reads; mutations submitted through Mutate are serialized.
func OpenTree ¶
OpenTree opens confined filesystem access for workspace and verifies that its canonical directory identity has not changed since Workspace was opened.
func (*Tree) FileSystem ¶
FileSystem returns a confined read-only fs.FS view. Operations continue to honor Tree closure and path validation.
func (*Tree) InspectAddPath ¶
InspectAddPath validates an Add target without requiring its parent tree to exist. It returns the exact missing parent directories in shallow-to-deep order. Existing components may not be symbolic links and existing parents must be directories.
func (*Tree) InspectMutationPath ¶
InspectMutationPath validates a file mutation target. Existing path components may not be symbolic links; parents must be directories. A nil FileInfo means the final path does not exist.
func (*Tree) InspectRegularPath ¶
InspectRegularPath validates an existing regular file path without following symbolic links in any component.
func (*Tree) Lstat ¶
Lstat returns information about name without following its final symbolic link.
func (*Tree) Mutate ¶
Mutate serializes a guarded filesystem mutation. The callback may open stable directory handles and operate on base names through Mutation.
func (*Tree) NormalizeUserPath ¶ added in v0.1.9
NormalizeUserPath accepts a relative path or an absolute path that resolves lexically inside the tree root, returning the confined relative spelling. It cleans the model-facing path shape first: surrounding quotes and whitespace, trailing literal line escapes, a leading tilde, and a workspace absolute path that lost its leading slash. Absolute paths outside the root and parent traversals remain refused. Callers still open through the Tree, so symlink escapes keep their existing checks.
func (*Tree) Open ¶
Open opens name through the confined root. Internal symbolic links are allowed only when their targets remain inside the root.
func (*Tree) Path ¶
Path returns the canonical workspace path for display and process-level adapters. File operations must use Tree methods instead.
type Workspace ¶
type Workspace struct {
// contains filtered or unexported fields
}
Workspace is a canonical directory and its filesystem identity.
func Open ¶
Open canonicalizes path and verifies that it names a directory with a platform filesystem identity.