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) 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) 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.
Source Files