I made an independent starting point for a file explorer. It reads names, kinds and sizes beneath a real folder configured by a host. It neither opens file contents nor executes code. Listings and direct file-metadata requests share the same scope, but this module is not a copy of the original server or its Jupyter integration.
The root comes from a trusted host
list_metadata and file_metadata accept a configured absolute root and a relative path. Parent traversal, absolute addresses, drive or share forms, backslashes, control characters, empty segments and dot segments are rejected. This is a contract that narrows path interpretation, rather than an example of concatenating names into a URL. Error messages do not echo the original absolute path.
This does not permit an arbitrary caller to choose the root. An authenticated server must obtain it from an authorized project registry. The module implements no login or project-permission store. Hidden filenames may also appear, so the absence of file contents does not eliminate the need to authorize metadata disclosure. The host retains responsibility for deciding what may be seen.
Showing a link differs from following it
A symbolic link or Windows reparse point appears in a listing by name with blocked set to true. A request through that entry is rejected, as is a linked configured root. This independent example adopts the narrower policy of rejecting even links that point back inside the root. It does not claim to match the original explorer, which can permit links whose resolved target stays inside the root.
Each path component is checked and the final resolved location must remain beneath the configured root. These checks still do not defeat every hostile filesystem change between checks. A controlled workspace and serialization of relevant writers are required. OS_sandbox_proven stays False; the example must not be presented as verified operating-system isolation.
Page size is not a bound on directory-scan cost
Listings put directories before files and then sort by name. They read only immediate entries and do not recursively enter child folders. limit and offset select the response page, with at most one hundred returned entries. The complete implementation appears below. A direct file request uses the same path checks and returns only metadata for a regular file.
The implementation reads all immediate entries before sorting, so limit set to one does not make filesystem work stop after one entry. directory_entries_scanned and total expose that distinction. File creation or deletion between pages is not frozen either. snapshot_stable is False, and page numbers must not be treated as proof of a complete listing at a single instant.
Explore the implementation
Complete independent synthetic implementation
"""Single-directory metadata for a trusted configured root. No content or execution."""
from pathlib import Path
import os
import stat
class ScopeError(ValueError):
pass
def _linked(info):
return stat.S_ISLNK(info.st_mode) or bool(
getattr(info, 'st_file_attributes', 0) & getattr(stat, 'FILE_ATTRIBUTE_REPARSE_POINT', 0x400))
def _parts(relative):
if type(relative) is not str or len(relative) > 1000:
raise ScopeError('RELATIVE_PATH_REQUIRED')
if relative == '':
return []
parts = relative.split('/')
if (any(ord(c) < 32 for c in relative) or '\\' in relative or ':' in relative
or any(p in {'', '.', '..'} for p in parts)):
raise ScopeError('RELATIVE_PATH_REQUIRED')
return parts
def _root(root):
p = Path(root)
if not p.is_absolute():
raise ScopeError('ABSOLUTE_CONFIGURED_ROOT_REQUIRED')
try:
if _linked(p.lstat()) or not p.is_dir():
raise ScopeError('NORMAL_ROOT_REQUIRED')
return p.resolve(strict=True)
except OSError:
raise ScopeError('ROOT_UNAVAILABLE') from None
def _target(root, relative):
current = root
for part in _parts(relative):
current = current / part
try:
if _linked(current.lstat()):
raise ScopeError('LINK_NOT_ALLOWED')
except OSError:
raise ScopeError('TARGET_UNAVAILABLE') from None
try:
resolved = current.resolve(strict=True)
except (OSError, RuntimeError):
raise ScopeError('TARGET_UNAVAILABLE') from None
if not resolved.is_relative_to(root):
raise ScopeError('OUTSIDE_CONFIGURED_ROOT')
return resolved
def _entry(path, relative):
result = {'name': path.name, 'path': relative, 'kind': 'unavailable',
'size': None, 'blocked': True}
try:
_parts(relative)
info = path.lstat()
if _linked(info):
result['kind'] = 'link'
elif stat.S_ISDIR(info.st_mode):
result.update(kind='directory', blocked=False)
elif stat.S_ISREG(info.st_mode):
result.update(kind='file', size=info.st_size, blocked=False)
except (OSError, ScopeError):
pass
return result
def list_metadata(root, relative='', *, offset=0, limit=50):
"""Page a sorted one-level listing; pagination is not an I/O or snapshot bound."""
if type(offset) is not int or not 0 <= offset <= 1000000:
raise ScopeError('INVALID_OFFSET')
if type(limit) is not int or not 1 <= limit <= 100:
raise ScopeError('INVALID_LIMIT')
configured = _root(root)
directory = _target(configured, relative)
if not directory.is_dir():
raise ScopeError('DIRECTORY_REQUIRED')
try:
rows = [_entry(p, '/'.join(filter(None, (relative, p.name)))) for p in directory.iterdir()]
except OSError:
raise ScopeError('DIRECTORY_UNAVAILABLE') from None
rows.sort(key=lambda x: (x['kind'] != 'directory', x['name'].casefold(), x['name']))
page = rows[offset:offset + limit]
end = offset + len(page)
return {'path': relative, 'entries': page, 'directory_entries_scanned': len(rows),
'total': len(rows), 'offset': offset, 'next_offset': end if end < len(rows) else None,
'content_read': False, 'code_executed': False, 'snapshot_stable': False,
'OS_sandbox_proven': False}
def file_metadata(root, relative):
configured = _root(root)
target = _target(configured, relative)
item = _entry(target, relative)
if item['blocked'] or item['kind'] != 'file':
raise ScopeError('REGULAR_FILE_REQUIRED')
return {**item, 'content_read': False, 'code_executed': False, 'OS_sandbox_proven': False}
File information does not create content access or execution
Results contain a name, relative path, kind, size and blocked state. They omit the configured root's absolute location and the file body. Inspecting the size of a Python file does not import or run it. content_read and code_executed remain false; this package includes no document-content reader, saver or executor.
A file may change or disappear after the listing, so a later action needs its own appropriate check. A metadata result is neither a fixed content hash nor permission to execute. Server-side opening and kernel permissions belong to other layers. Keeping a small function's return contract separate from the guarantees of an entire program makes reuse easier to assess.
Tests and records from actual synthetic folders
Twenty tests cover relative paths and input types, response pages versus total scan counts, hidden names, absence of content, unchanged bytes and link rejection. On Windows they use actual junctions created in owned fixture folders beneath this package. Each junction is removed first, and the temporary cleanup target is checked against that owned boundary. No customer folder or original program material is used.
The records show a first page, a next page containing a blocked link, a nested directory, file metadata and rejected requests. They are actual local synthetic outputs of this code. The selector reads saved JSON and never explores a visitor's filesystem. The same twenty tests run after ZIP extraction and the public file is checked for bytes and hash. These are not tests of server authentication, the Jupyter interface or a kernel.
Connecting it to another administration interface
The download contains implementation, tests, a record generator and outputs, README and reuse permission. A server should select a root registered for its authenticated context rather than forwarding a root string supplied by a user. A separate file-open API must check the same boundary again. Putting this module into a browser cannot substitute for server access control.
The existing confirmed-folder iterator is a different component for source, working copies and completed copies. I separated read-only metadata so an explorer does not unnecessarily invoke its copy-and-move behavior. This package has not been installed into the original controller. The verified scope is kept alongside the host's remaining authentication, opening, saving and execution responsibilities.